---
title: "Update a Cascade"
method: POST
path: "/cascades/{id}"
tags: ["Cascades"]
---

# Update a Cascade

`POST /cascades/{id}`

Update an existing Cascade by its ID

## Path parameters

- `id` string, required

## Request body

- UpdateCascadeRequestDTO
  - `name` string — The cascade's name
  - `description` string — The cascade's description
  - `algorithm` 'roundRobin' | 'weightedRoundRobin' | 'priorityQueue' — The algorithm to be used to route payments in the cascade
  - `gateways` CreateCascadeGatewayCascadeDTO[] — Gateway profiles that are utilised by the cascade and their configuration
    - `profile` string, required — The gateway profile ID
    - `position` number — The position in which the gateway is used in the cascade, from lowest to highest.
    - `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.
    - `transactionLimit` number — The maximum number of transactions allowed in the limit period.
    - `transactionLimitPeriod` 'day' | 'week' | 'month' — The period in which the transaction limit applies. Required if `transactionLimit` is set.
    - `transactionCap` number — The maximum total amount (in minor units) charged in the cap period.
    - `transactionCapPeriod` 'day' | 'week' | 'month' — The period in which the cap value applies. Required if `transactionCap` is set.
  - `active` boolean — Whether the cascade is active and available for routing

## Response `200`

OK

- CascadeDTO
  - `createdAt` string, date-time, required — The date and time when the entity was created.
  - `updatedAt` string, date-time, nullable, required — The date and time when the entity was last updated.
  - `metadata` object, nullable — Metadata used by merchants to store additional information about the entity.
  - `id` string, required — The unique identifier of the cascade
  - `name` string, required
  - `description` string, nullable, required
  - `active` boolean, required — Whether the cascade is active and available for routing
  - `algorithm` 'roundRobin' | 'weightedRoundRobin' | 'priorityQueue', required — The algorithm used for gateway selection. Available options: roundRobin, weightedRoundRobin, priorityQueue
  - `gateways` 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.
    - `updatedAt` string, date-time, nullable, required — The date and time when the entity was last updated.
    - `metadata` object, 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.
      - `updatedAt` string, date-time, nullable, required — The date and time when the entity was last updated.
      - `metadata` object, nullable — Metadata used by merchants to store additional information about the entity.
      - `id` string, required — ID of the Gateway Profile
      - `active` boolean, required — Whether the gateway profile is active and available for processing
      - `title` string, required — Title of the Gateway Profile
      - `integration` 'stripe' | 'adyen' | 'checkout' | 'paypal', required — Associated Gateway Integration
      - `environment` 'live' | 'test' | 'null', nullable, required — The environment the gateway profile operates in
      - `supportedPaymentMethods` string[], required — Supported payment methods for the Gateway Profile
    - `position` number, required — Order in which this gateway is tried in the cascade
    - `weight` number, nullable, required — Relative weight for weighted routing algorithms
    - `transactionLimit` number, nullable, required — Maximum transaction amount this gateway can process
    - `transactionLimitCounter` number, required — Current counter value for the transaction limit
    - `transactionLimitPeriod` 'day' | 'week' | 'month' | 'null', nullable, required — Time period for the transaction limit
    - `isTransactionLimitExhausted` boolean, required — Whether the transaction limit has been reached for the current period
    - `transactionCap` number, nullable, required — Maximum number of transactions in a period
    - `transactionCapCounter` number, required — Current counter value for the transaction cap
    - `transactionCapPeriod` 'day' | 'week' | 'month' | 'null', nullable, required — Time period for the transaction cap
    - `isTransactionCapExhausted` boolean, required — Whether the transaction cap has been reached for the current period
  - `lastAttempted` object, 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.
    - `updatedAt` string, date-time, nullable, required — The date and time when the entity was last updated.
    - `metadata` object, 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, 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.
    - `updatedAt` string, date-time, nullable, required — The date and time when the entity was last updated.
    - `metadata` object, 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

## Other responses

- `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.
- `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; `invalid_state_error` when the request was well-formed but the resource is not in a state that allows it; or `payment_error` when the payment was refused by the issuer or processor.
- `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. The rate limit is applied per client across all operations. `type` is `rate_limit_error`.
- `500` — The request could not be completed because of an unexpected error. `type` is `api_error`.
- `503` — A dependency needed to authorize the request is temporarily 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.

## Changes

- **2026-09-02** `de9880e65aea` — 1 info
  - added the non-success response with the status `503`

[Change history](https://skmtc.dev/odus/apis/odus-orchestration-api/changes/cascades/:id/post.md)

---

[API](https://skmtc.dev/odus/apis/odus-orchestration-api.md) · [All operations](https://skmtc.dev/odus/apis/odus-orchestration-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/odus/odus-orchestration-api/revisions/de9880e65aea/schema)