# subscriptions.merges.create

Merge two or more plans in the same currency by hand, combining their history and yearly estimate into one plan. Requires an idempotencyKey. Changes no accounting entries and can be undone.

`POST /api/v1/accounting/subscriptions.merges.create`

Permissions: `accounting:read`, `accounting:write` · Roles: admin, finance · Idempotency key required

MCP tool: `accounting_subscriptions_merges_create`

## Fields

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `currency` | string | Yes | Three-letter currency code, such as CAD or USD. |
| `vendorKeys` | array of strings | Yes | 2–10 items; each 1–120 characters; each Matches ^[a-z0-9 ]+$. |
| `idempotencyKey` | string | Yes | Any unique text you generate once per intended change, so a retried request only happens once. Send it as the Idempotency-Key header instead if you prefer; if you send both they must match. 8–200 characters. |

## Example request

```bash
curl https://app.getoatmilk.com/api/v1/accounting/subscriptions.merges.create \
  -H "Authorization: Bearer $OATMILK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "currency": "CAD",
  "vendorKeys": [
    "example",
    "example"
  ]
}'
```

Reference page: https://app.getoatmilk.com/docs/api/subscriptions.merges.create