> ## Documentation Index
> Fetch the complete documentation index at: https://docs.y.uno/llms.txt
> Use this file to discover all available pages before exploring further.

# Update a Routing

> Replaces the routing's full configuration.

Replaces the routing's full configuration. The body has the same shape as [Create a Routing](/reference/organizations/routing/create-routing) — the new `default_route` and `condition_sets[]` entirely supersede the previous live state. **There is no field-level merge.**

`account_code` and `payment_method` are sticky to the `routing_id` — they're set at creation and cannot be changed by `PATCH`.

### Path Parameters

<ParamField path="routing_id" type="string" required>
  The id returned by [Create a Routing](/reference/organizations/routing/create-routing).
</ParamField>

### Body

<ParamField body="name" type="string" required>
  Free-form label.
</ParamField>

<ParamField body="default_route" type="object" required>
  The route used when no `condition_sets[]` matches.

  <Expandable title="properties">
    <ParamField body="steps" type="object[]" required>
      Each step is one provider attempt. `index` values are contiguous starting at 1.

      <Expandable title="item">
        <ParamField body="index" type="integer" required>
          Step ordinal.
        </ParamField>

        <ParamField body="provider_id" type="string" required>
          Must match the provider of the connection.
        </ParamField>

        <ParamField body="connection_id" type="UUID" required>
          Must be `ACTIVE` and support the `payment_method`.
        </ParamField>

        <ParamField body="output" type="object[]">
          Defines how to handle each possible outcome of this step.

          <Expandable title="item">
            <ParamField body="status" type="string" required>
              The outcome status that triggers this rule (e.g., `APPROVED`, `DECLINED`, `DECLINE_GROUP`, `TIMEOUT`, `INTERNAL_ERROR`).
            </ParamField>

            <ParamField body="decline_types" type="string[]">
              Required when `status` is `DECLINE_GROUP`. Specifies which decline subtypes trigger this rule (e.g., `INSUFFICIENT_FUNDS`, `DECLINED_BY_BANK`).
            </ParamField>

            <ParamField body="next" type="integer">
              The `index` of the next step to execute. Omit if no fallback is needed.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="condition_sets" type="object[]">
  Optional. Ordered by `sort_number` — first matching set wins.

  <Expandable title="item">
    <ParamField body="sort_number" type="integer" required>
      Priority of the condition set.
    </ParamField>

    <ParamField body="name" type="string" required>
      Label for the set.
    </ParamField>

    <ParamField body="conditions" type="object[]" required>
      List of [Conditions](/reference/organizations/routing/routing-conditions) that must match.
    </ParamField>

    <ParamField body="route" type="object" required>
      The steps to execute if this set matches.
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="id" type="string">
  Unique identifier for the routing.
</ResponseField>

<ResponseField name="account_code" type="string">
  Unique code for the account.
</ResponseField>

<ResponseField name="payment_method" type="enum">
  The payment method this routing applies to (e.g., `CARD`).
</ResponseField>

<ResponseField name="name" type="string">
  Label for the routing.
</ResponseField>

<ResponseField name="default_route" type="object">
  The default routing logic.
</ResponseField>

<ResponseField name="condition_sets" type="object[]">
  Optional conditional logic.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp.
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 timestamp.
</ResponseField>

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
  curl -X PATCH 'https://api.y.uno/v1/routing/r_8f2c1d3e-4b5a-6c7d-8e9f-0a1b2c3d4e5f' \
    -H 'public-api-key: <YOUR_PUBLIC_KEY>' \
    -H 'private-secret-key: <YOUR_SECRET_KEY>' \
    -H 'Content-Type: application/json' \
    -H 'X-Idempotency-Key: <UUID>' \
    -d '{
      "payment_method": "CARD",
      "name": "Card routing v2 — adds BR installments rule",
      "default_route": {
        "steps": [
          {
            "index": 1,
            "provider_id": "STRIPE",
            "connection_id": "f1a3c4d5-7b8e-4a2c-9d1e-3f4a5b6c7d8e",
            "output": [
              { "status": "DECLINED", "next": 2 }
            ]
          },
          {
            "index": 2,
            "provider_id": "ADYEN",
            "connection_id": "b2c4d5e6-1a2b-3c4d-5e6f-7a8b9c0d1e2f"
          }
        ]
      },
      "condition_sets": [
        {
          "sort_number": 1,
          "name": "Brazil — 3 to 6 installments via Adyen",
          "description": "BR card transactions with 3–6 installments go to Adyen directly",
          "conditions": [
            { "condition_type": "COUNTRY",      "conditional": "EQUAL",   "values": ["BR"] },
            { "condition_type": "INSTALLMENTS", "conditional": "BETWEEN", "values": ["3", "6"] }
          ],
          "route": {
            "steps": [
              { "index": 1, "provider_id": "ADYEN", "connection_id": "b2c4d5e6-..." }
            ]
          }
        }
      ]
    }'
  ```

  ```json 200 OK — Updated theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
  {
    "id": "r_8f2c1d3e-4b5a-6c7d-8e9f-0a1b2c3d4e5f",
    "account_code": "acc-uuid",
    "payment_method": "CARD",
    "name": "Card routing v2 — adds BR installments rule",
    "default_route": {
      "steps": [
        {
          "index": 1,
          "provider_id": "STRIPE",
          "connection_id": "f1a3c4d5-7b8e-4a2c-9d1e-3f4a5b6c7d8e",
          "output": [ { "status": "DECLINED", "next": 2 } ]
        },
        { "index": 2, "provider_id": "ADYEN", "connection_id": "b2c4d5e6-..." }
      ]
    },
    "condition_sets": [
      {
        "sort_number": 1,
        "name": "Brazil — 3 to 6 installments via Adyen",
        "conditions": [
          { "condition_type": "COUNTRY", "conditional": "EQUAL", "values": ["BR"] }
        ],
        "route": { "steps": ["..."] }
      }
    ],
    "created_at": "2026-05-12T14:30:00Z",
    "updated_at": "2026-05-13T09:18:42Z"
  }
  ```

  ```json 400 — Immutable Payment Method theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
  {
    "type": "validation_error",
    "code": "ROUTING_PAYMENT_METHOD_IMMUTABLE",
    "message": "payment_method cannot be changed on an existing routing",
    "details": {
      "routing_id": "r_...",
      "current_payment_method": "CARD",
      "received_payment_method": "PIX"
    }
  }
  ```
</CodeGroup>

### Errors

| HTTP  | `code`                             | When                                                                  |
| ----- | ---------------------------------- | --------------------------------------------------------------------- |
| `404` | `ROUTING_NOT_FOUND`                | Unknown `routing_id`, or id belongs to a different account.           |
| `400` | `ROUTING_VALIDATION_FAILED`        | Schema or rule violation.                                             |
| `400` | `ROUTING_PROVIDER_NOT_AVAILABLE`   | A step references an inactive/unknown connection.                     |
| `400` | `ROUTING_PAYMENT_METHOD_IMMUTABLE` | Body's `payment_method` doesn't match the routing's `payment_method`. |
| `409` | `ROUTING_VERSION_CONFLICT`         | Another concurrent `PATCH` won the publish race.                      |
| `403` | `INSUFFICIENT_SCOPE`               | API key missing `routing:write`.                                      |


## OpenAPI

````yaml openapi/organizations/routing/update-routing.json PATCH /routing/{routing_id}
openapi: 3.1.0
info:
  title: Routing API - Update
  version: 1.0.0
servers:
  - url: https://api-sandbox.y.uno/v1
security:
  - sec0: []
    sec1: []
paths:
  /routing/{routing_id}:
    patch:
      summary: Update a Routing
      description: Replaces the routing's full configuration.
      operationId: update-routing
      parameters:
        - name: routing_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: X-Idempotency-Key
          in: header
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: r_8f2c1d3e-4b5a-6c7d-8e9f-0a1b2c3d4e5f
                  account_code:
                    type: string
                    example: acc-uuid
                  payment_method:
                    type: string
                    example: CARD
                  name:
                    type: string
                    example: Updated Card routing v2
                  default_route:
                    type: object
                    properties:
                      steps:
                        type: array
                        items:
                          type: object
                          properties:
                            index:
                              type: integer
                              example: 1
                            provider_id:
                              type: string
                              example: STRIPE
                            connection_id:
                              type: string
                              example: f1a3c4d5-...
                  condition_sets:
                    type: array
                    items:
                      type: object
                      properties:
                        sort_number:
                          type: integer
                          example: 1
                        name:
                          type: string
                          example: Updated Card routing
                        conditions:
                          type: array
                          items:
                            type: object
                        route:
                          type: object
                  created_at:
                    type: string
                    format: date-time
                    example: '2026-05-12T14:30:00Z'
                  updated_at:
                    type: string
                    format: date-time
                    example: '2026-05-12T14:30:00Z'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    example: validation_error
                  code:
                    type: string
                    example: ROUTING_VALIDATION_FAILED
                  message:
                    type: string
                    example: Validation failed for update
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    example: not_found
                  code:
                    type: string
                    example: ROUTING_NOT_FOUND
                  message:
                    type: string
                    example: Routing '...' was not found
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    example: conflict
                  code:
                    type: string
                    example: ROUTING_VERSION_CONFLICT
                  message:
                    type: string
                    example: Another concurrent PATCH won the publish race
components:
  securitySchemes:
    sec0:
      type: apiKey
      in: header
      name: PUBLIC-API-KEY
      x-default: <Your PUBLIC-API-KEY>
    sec1:
      type: apiKey
      in: header
      name: PRIVATE-SECRET-KEY
      x-default: <Your PRIVATE-SECRET-KEY>

````