> ## 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 Connection
> Partially updates a connection. Only the fields you send are applied; secrets stay masked.
Partially updates a connection you previously created. Only the fields present in the body are applied — anything you omit keeps its current value.
**What you can't change here:** `provider_id`, `flow_type`, `payment_methods` and the `INTEGRATION_TYPE` param are immutable. To change any of them, create a new connection and repoint your routing rules at it.
### Path Parameters
The id returned by [Create a Connection](/reference/organizations/connections/create-connection). Must belong to the account your API key is scoped to.
### Body
UUID of the account the connection belongs to.
New label for this connection. Max 255 characters, and must still be unique within the account. Omit it to keep the current label.
Params to change, as a **flat array** of `{param_id, value}` pairs — the same shape as [Create a Connection](/reference/organizations/connections/create-connection).
Params are **merged by `param_id`** over the connection's current params: a `param_id` you don't send keeps its current value. You only need to send what you're actually changing. Every `param_id` you do send is validated against the provider catalog.
The exact `param_id` from the catalog. Casing matters.
Match the `field_type` from the catalog.
Cost configuration. Unlike `params`, `costs` is **not merged** — when present it *replaces* the connection's entire cost table. Omit it to leave the existing costs untouched.
Order of priority for the cost entry.
Label for the cost entry.
ISO 4217 currency code. Must be one supported by the provider.
Fixed fee amount.
Percentage fee.
### Response
Returns the refreshed connection, in the same shape as [Retrieve a Connection](/reference/organizations/connections/retrieve-connection).
Unique identifier for the connection. Unchanged by an update.
Your internal label for this connection.
The provider this connection belongs to.
Current status.
Always `PAYIN`.
List of supported payment methods.
The connection's full param set after the merge — not just the ones you sent. Sensitive values are masked as `***`.
Cost configuration for the connection.
ISO 8601 timestamp.
ISO 8601 timestamp. Bumped by a successful update.
```bash cURL — rotate a secret theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
curl -X PATCH 'https://api.y.uno/v1/connections/f1a3c4d5-7b8e-4a2c-9d1e-3f4a5b6c7d8e' \
-H 'public-api-key: ' \
-H 'private-secret-key: ' \
-H 'Content-Type: application/json' \
-d '{
"account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"params": [
{ "param_id": "API_KEY", "value": "sk_live_new..." }
]
}'
```
```bash cURL — rename theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
curl -X PATCH 'https://api.y.uno/v1/connections/f1a3c4d5-7b8e-4a2c-9d1e-3f4a5b6c7d8e' \
-H 'public-api-key: ' \
-H 'private-secret-key: ' \
-H 'Content-Type: application/json' \
-d '{
"account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"merchant_connection_id": "stripe-us-prod-002"
}'
```
```json 200 OK theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
"connection_id": "f1a3c4d5-7b8e-4a2c-9d1e-3f4a5b6c7d8e",
"merchant_connection_id": "stripe-us-prod-002",
"provider_id": "STRIPE",
"status": "ACTIVE",
"flow_type": "PAYIN",
"payment_methods": ["CARD", "GOOGLE_PAY", "APPLE_PAY"],
"params": [
{ "param_id": "API_KEY", "value": "***" },
{ "param_id": "PUBLISHABLE_KEY", "value": "pk_live_..." },
{ "param_id": "INTEGRATION_TYPE", "value": "PAYMENT_INTENTS" },
{ "param_id": "3DS_ENABLED", "value": true },
{ "param_id": "ORIGIN_URL", "value": "https://checkout.acme.com" }
],
"costs": [
{
"sort_number": 1,
"cost_name": "Transaction Fee",
"currency": "USD",
"cost_values": {
"successful": { "fixed_fee": 0.30, "percentage": 2.9 },
"unsuccessful": { "fixed_fee": 0.0, "percentage": 0.0 }
}
}
],
"created_at": "2026-05-12T10:24:00Z",
"updated_at": "2026-05-12T11:02:17Z"
}
```
```json 400 — Unknown Param theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
"type": "validation_error",
"code": "UNKNOWN_PARAM",
"message": "Param 'FOO' is not part of the catalog for provider 'STRIPE'",
"details": { "provider_id": "STRIPE", "param_id": "FOO" }
}
```
```json 409 — Conflict theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
"type": "conflict",
"code": "CONNECTION_MERCHANT_ID_CONFLICT",
"message": "A connection with merchant_connection_id 'stripe-us-prod-002' already exists in this account",
"details": { "merchant_connection_id": "stripe-us-prod-002" }
}
```
**Secret handling:** params marked `secret: true` in the catalog are always returned as `"value": "***"`. Sending `"***"` back is not how you keep a secret — just omit the `param_id` entirely and its stored value is preserved.
### Errors
| HTTP | `code` |
| ----- | --------------------------------------------------------------------------------------------------------------- |
| `400` | `UNKNOWN_PARAM`
A `param_id` isn't part of the provider's catalog. |
| `400` | `INVALID_PARAM_VALUE`
A value doesn't match the catalog's `field_type` or allowed options. |
| `400` | `UNSUPPORTED_CURRENCY`
A `costs[].currency` isn't in the provider's supported list. |
| `400` | `VALIDATION_ERROR`
`connection_id` isn't a valid UUID, or `merchant_connection_id` exceeds 255 characters. |
| `400` | `MALFORMED_BODY`
The body isn't valid JSON. |
| `401` | `NOT_AUTHENTICATED`
Missing or invalid API key. |
| `404` | `CONNECTION_NOT_FOUND`
Unknown `connection_id`, or the id belongs to a different account. |
| `409` | `CONNECTION_MERCHANT_ID_CONFLICT`
`merchant_connection_id` already exists in this account. |
## OpenAPI
````yaml openapi/organizations/connections/update-connection.json PATCH /connections/{connection_id}
openapi: 3.1.0
info:
title: Connections API - Update
version: 1.0.0
servers:
- url: https://api-sandbox.y.uno/v1
- url: https://api.eu.y.uno/v1
security:
- sec0: []
sec1: []
paths:
/connections/{connection_id}:
patch:
summary: Update a Connection
description: >-
Partially updates a connection. Only the fields present in the body are
applied.
operationId: update-connection
parameters:
- name: connection_id
in: path
required: true
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- account_id
properties:
account_id:
type: string
format: uuid
example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
merchant_connection_id:
type: string
maxLength: 255
example: stripe-us-prod-002
params:
type: array
items:
type: object
properties:
param_id:
type: string
example: API_KEY
value:
type: string
example: sk_live_...
costs:
type: array
items:
type: object
properties:
sort_number:
type: integer
example: 1
cost_name:
type: string
example: Transaction Fee
currency:
type: string
example: USD
cost_values:
type: object
properties:
successful:
type: object
properties:
fixed_fee:
type: number
example: 0.25
percentage:
type: number
example: 2.7
unsuccessful:
type: object
properties:
fixed_fee:
type: number
example: 0
percentage:
type: number
example: 0
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
connection_id:
type: string
example: f1a3c4d5-7b8e-4a2c-9d1e-3f4a5b6c7d8e
merchant_connection_id:
type: string
example: stripe-us-prod-002
provider_id:
type: string
example: STRIPE
status:
type: string
example: ACTIVE
flow_type:
type: string
example: PAYIN
payment_methods:
type: array
items:
type: string
example:
- CARD
- GOOGLE_PAY
- APPLE_PAY
params:
type: array
items:
type: object
properties:
param_id:
type: string
example: API_KEY
value:
type: string
example: '***'
costs:
type: array
items:
type: object
properties:
sort_number:
type: integer
example: 1
cost_name:
type: string
example: Transaction Fee
currency:
type: string
example: USD
created_at:
type: string
format: date-time
example: '2026-05-12T10:24:00Z'
updated_at:
type: string
format: date-time
example: '2026-05-12T11:02:17Z'
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
type:
type: string
example: validation_error
code:
type: string
example: UNKNOWN_PARAM
message:
type: string
example: >-
Param 'FOO' is not part of the catalog for provider
'STRIPE'
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
type:
type: string
example: auth_error
code:
type: string
example: NOT_AUTHENTICATED
message:
type: string
example: Not authenticated
'404':
description: Not Found
content:
application/json:
schema:
type: object
properties:
type:
type: string
example: not_found
code:
type: string
example: CONNECTION_NOT_FOUND
message:
type: string
example: Connection '...' was not found
'409':
description: Conflict
content:
application/json:
schema:
type: object
properties:
type:
type: string
example: conflict
code:
type: string
example: CONNECTION_MERCHANT_ID_CONFLICT
message:
type: string
example: >-
A connection with merchant_connection_id
'stripe-us-prod-002' already exists in this account
components:
securitySchemes:
sec0:
type: apiKey
in: header
name: PUBLIC-API-KEY
x-default:
sec1:
type: apiKey
in: header
name: PRIVATE-SECRET-KEY
x-default:
````