# Update a Cascade `POST /v2/cascades/{id}` Core API v2, Cascades. Update an existing Cascade by its ID **Authentication:** Send `Authorization: Bearer `. To authenticate, generate a Secret API Key from your ODUS Dashboard and include it in the `Authorization` header as follows: `Authorization: Bearer ` ## Parameters ### Path parameters - `id` (string, required) ## Request body Content type `application/json`, required. Type: object (UpdateCascadeRequestDTO). - `name` (string): The cascade's name. Example: `My Cascade`. - `description` (string): The cascade's description. - `algorithm` (string): The algorithm to be used to route payments in the cascade. One of `roundRobin`, `weightedRoundRobin`, `priorityQueue`. Example: `weightedRoundRobin`. - `gateways` (array of object (CreateCascadeGatewayCascadeDTO)): Gateway profiles that are utilised by the cascade and their configuration. Minimum items 1. - `profile` (string, required): The gateway profile ID. Example: `gwp_2QUGPTQo8As1cNIvgKlSFDxjJDd`. - `position` (number): The position in which the gateway is used in the cascade, from lowest to highest. Minimum 1. Maximum 10. Example: `1`. - `weight` (number): The weight of the gateway in the cascade, which represents the percentage of payments that are processed with the gateway. Is required for cascades using the weighted algorithm. Minimum 0. Maximum 100. Example: `80`. - `transactionLimit` (number): The maximum number of transactions allowed in the limit period. Minimum 1. Example: `100`. - `transactionLimitPeriod` (string): The period in which the transaction limit applies. Required if `transactionLimit` is set. One of `day`, `week`, `month`. Example: `day`. - `transactionCap` (number): The maximum total amount (in minor units) charged in the cap period. Minimum 1. Example: `10000`. - `transactionCapPeriod` (string): The period in which the cap value applies. Required if `transactionCap` is set. One of `day`, `week`, `month`. Example: `day`. - `active` (boolean): Whether the cascade is active and available for routing. ## Responses ### `200` OK Type: object (CascadeDTO). - `createdAt` (string (date-time), required): The date and time when the entity was created. Example: `2024-02-18T12:00:00Z`. - `updatedAt` (string (date-time), required, nullable): The date and time when the entity was last updated. Example: `2024-02-21T12:15:00Z`. - `metadata` (map of string to string, nullable): Metadata used by merchants to store additional information about the entity. - `id` (string, required): The unique identifier of the cascade. - `name` (string, required): Example: `My Cascade`. - `description` (string, required, nullable): Example: `Simple cascade`. - `active` (boolean, required): Whether the cascade is active and available for routing. Example: `true`. - `algorithm` (string, required): The algorithm used for gateway selection. Available options: roundRobin, weightedRoundRobin, priorityQueue. One of `roundRobin`, `weightedRoundRobin`, `priorityQueue`. Example: `weightedRoundRobin`. - `gateways` (array of object, required): The list of gateway profiles configured for this cascade. - `createdAt` (string (date-time), required): The date and time when the entity was created. Example: `2024-02-18T12:00:00Z`. - `updatedAt` (string (date-time), required, nullable): The date and time when the entity was last updated. Example: `2024-02-21T12:15:00Z`. - `metadata` (map of string to string, nullable): Metadata used by merchants to store additional information about the entity. - `id` (string, required): The unique identifier of the cascade gateway entry. - `profile` (object, required): The gateway profile associated with this cascade entry. - `createdAt` (string (date-time), required): The date and time when the entity was created. Example: `2024-02-18T12:00:00Z`. - `updatedAt` (string (date-time), required, nullable): The date and time when the entity was last updated. Example: `2024-02-21T12:15:00Z`. - `metadata` (map of string to string, nullable): Metadata used by merchants to store additional information about the entity. - `id` (string, required): ID of the Gateway Profile. Example: `gwp_2QC7PqoUeOxQEWscJJt6B3PkvyL`. - `active` (boolean, required): Whether the gateway profile is active and available for processing. Example: `true`. - `title` (string, required): Title of the Gateway Profile. Example: `Profile #1`. - `integration` (string, required): Associated Gateway Integration. One of `stripe`, `adyen`, `checkout`, `paypal`. Example: `stripe`. - `environment` (string, required, nullable): The environment the gateway profile operates in. One of `live`, `test`. Example: `test`. - `supportedPaymentMethods` (array of string, required): Supported payment methods for the Gateway Profile. Each item: One of `card`, `paypal`, `applePay`. - `position` (number, required): Order in which this gateway is tried in the cascade. Example: `1`. - `weight` (number, required, nullable): Relative weight for weighted routing algorithms. Example: `80`. - `transactionLimit` (number, required, nullable): Maximum transaction amount this gateway can process. Example: `100`. - `transactionLimitCounter` (number, required): Current counter value for the transaction limit. Example: `0`. - `transactionLimitPeriod` (string, required, nullable): Time period for the transaction limit. One of `day`, `week`, `month`. Example: `day`. - `isTransactionLimitExhausted` (boolean, required): Whether the transaction limit has been reached for the current period. Example: `false`. - `transactionCap` (number, required, nullable): Maximum number of transactions in a period. Example: `10000`. - `transactionCapCounter` (number, required): Current counter value for the transaction cap. Example: `0`. - `transactionCapPeriod` (string, required, nullable): Time period for the transaction cap. One of `day`, `week`, `month`. Example: `month`. - `isTransactionCapExhausted` (boolean, required): Whether the transaction cap has been reached for the current period. Example: `false`. - `lastAttempted` (object, required, nullable): The cascade gateway entry that was last attempted for routing. - `createdAt` (string (date-time), required): The date and time when the entity was created. Example: `2024-02-18T12:00:00Z`. - `updatedAt` (string (date-time), required, nullable): The date and time when the entity was last updated. Example: `2024-02-21T12:15:00Z`. - `metadata` (map of string to string, nullable): Metadata used by merchants to store additional information about the entity. - `id` (string, required): The unique identifier of the last-used cascade gateway entry. - `lastBilled` (object, required, nullable): The cascade gateway entry that last successfully processed a payment. - `createdAt` (string (date-time), required): The date and time when the entity was created. Example: `2024-02-18T12:00:00Z`. - `updatedAt` (string (date-time), required, nullable): The date and time when the entity was last updated. Example: `2024-02-21T12:15:00Z`. - `metadata` (map of string to string, nullable): Metadata used by merchants to store additional information about the entity. - `id` (string, required): The unique identifier of the last-used cascade gateway entry. ### `202` The merchant is entitled but its environment is not provisioned yet. Provisioning has been kicked off (exactly once) and is in progress; retry the request — it succeeds once the environment is ready. Returned only for identity-token (dashboard) requests bound to a merchant, not for secret-key API calls; any such endpoint can return it while provisioning is underway. Type: object (ProvisioningInProgress). - `status` (string, required): Signals the merchant environment is still being provisioned. One of `provisioning`. - `merchantAccountId` (string, required): The merchant account whose environment is being provisioned. Example: `dAI3aa87ROOeupeBCjNSKCOBOisBCYjB`. ### Errors - `400`: The request was rejected. `type` is `invalid_request_error` when the request itself is at fault — `errors` then lists every problem found, with field-attributable entries prefixed by the field’s path; or `invalid_state_error` when the request was well-formed but the resource is not in a state that allows it. - `401`: No API key was supplied, or the key is not valid. `type` is `authentication_error`. - `403`: The API key is valid but lacks the permission this operation requires. `type` is `permission_error`. - `404`: No resource exists with the requested identifier. `type` is `not_found_error`. - `409`: `type` is `conflict_error`. The supplied `X-Idempotency-Key` was already used with a different request body (`code` is `idempotency_conflict`, and retrying will not help), or the resource is being modified by another in-flight request (`code` is `resource_locked`, and retrying with backoff will). - `429`: Too many requests. A limit applies per operation; requests to other operations are unaffected. `type` is `rate_limit_error`. Use the `Retry-After-global` header to know when to retry. - `500`: The request could not be completed because of an unexpected error. `type` is `api_error`. - `503`: The request could not be served right now: the API is temporarily at capacity, or a dependency needed to authorize the request is unavailable — the auth service that verifies credentials, or the entitlement lookup behind it. `type` is `api_error`. It is raised before the operation runs, so the request had no effect, and unlike a plain 500 the condition is transient: retry with backoff. - `504`: The request exceeded the processing time limit and was abandoned. `type` is `api_error` and `code` is `timeout` — unlike a plain 500 the request may still have taken effect, so retry with the same idempotency key rather than blindly. Every error response has the same body: see [Errors](https://docs.odus.com/docs/guides/api-features/errors.md). --- Generated from the Core API v2 OpenAPI document, https://api.odus.com/openapi.v2.json. Interactive page: https://docs.odus.com/docs/api/core/v2/cascade-controller-update