---
title: "Update a subscription (upgrades now with proration, downgrades and interval switches at the period end)"
method: PATCH
path: "/api/v1/subscriptions/{id}"
tags: ["Subscriptions"]
---

# Update a subscription (upgrades now with proration, downgrades and interval switches at the period end)

`PATCH /api/v1/subscriptions/{id}`

## Request

- Base URL: `https://merchant.zahlo.eu`
- URL: `https://merchant.zahlo.eu/api/v1/subscriptions/{id}`
- Auth: API key in header `x-api-key`

Update a subscription (upgrades now with proration, downgrades and interval switches at the period end). Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.

## Path parameters

- `id` string, required

## Headers

- `Idempotency-Key` string

## Request body

- SubscriptionUpdateRequest
  - `priceId` string: Same currency. An upgrade or seat increase applies now and prorates; a downgrade or interval switch applies at the period end.
  - `quantity` integer
  - `addOns` object[]: Replaces the add-ons. A new add-on or a higher quantity applies now and prorates on the next charge; a lower quantity or a removal applies at the period end. Card only.
    - `priceId` string, required
    - `quantity` integer, required
  - `paymentMethodId` string
  - `metadata` object: Up to 50 key-value pairs; keys up to 40 characters, values strings up to 500 characters.

## Response `200`

The updated subscription

- Subscription
  - `id` string, required
  - `object` 'subscription', required
  - `livemode` boolean
  - `createdAt` string, date-time
  - `customerId` string, required
  - `priceId` string, required
  - `quantity` integer
  - `status` 'incomplete' | 'trialing' | 'active' | 'past_due' | 'paused' | 'cancelled', required
  - `currency` string, required
  - `amountMinor` integer, required: The current or next period's charge, after discount.
  - `couponId` string, nullable
  - `discountEndsAt` string, date-time, nullable
  - `paymentMethodId` string, nullable
  - `rail` 'card' | 'sepa_debit'
  - `trialEnd` string, date-time, nullable
  - `currentPeriodStart` string, date-time, nullable
  - `currentPeriodEnd` string, date-time, nullable
  - `cancelAtPeriodEnd` boolean, required
  - `cancelledAt` string, date-time, nullable
  - `cancellationReason` 'requested' | 'payment_failed', nullable
  - `pastDueSince` string, date-time, nullable
  - `latestPaymentId` string, nullable
  - `pendingUpdate` object, nullable
    - `priceId` string
    - `quantity` integer
    - `effectiveAt` string, date-time
  - `prorationMinor` integer: Proration for an upgrade or seat increase, added to the next period's charge.
  - `addOns` object[]: More recurring prices billed with the main price every period, discounted with it. `pendingQuantity` takes effect at the period end (0 removes the add-on).
    - `priceId` string, required
    - `quantity` integer, required
    - `pendingQuantity` integer, nullable, required
  - `metadata` object: Up to 50 key-value pairs; keys up to 40 characters, values strings up to 500 characters.

## Other responses

- `400`: Invalid request
- `401`: Authentication failed
- `404`: Resource not found
- `409`: Request conflicts with existing state

---

[API](https://skmtc.dev/zahlo/apis/zahlo-merchant-api.md) - [All operations](https://skmtc.dev/zahlo/apis/zahlo-merchant-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zahlo/apis/zahlo-merchant-api/revisions/8fcbef981e0d?raw)