# Update a Subscription

`POST /v2/subscriptions/{id}`

Core API v2, Subscriptions.

Updates a Subscription based on previously generated preview

**Authentication:** Send `Authorization: Bearer <token>`. To authenticate, generate a Secret API Key from your ODUS Dashboard and include it in the `Authorization` header as follows: `Authorization: Bearer <YOUR_SECRET_API_KEY>`

## Parameters

### Path parameters

- `id` (string, required)

## Request body

Content type `application/json`, required.

Type: object (UpdateSubscriptionPlanRequestDTO).

- `metadata` (map of string to string, nullable): Metadata used by merchants to store additional information about the entity.
- `previewId` (string): The ID of the preview obtained from the generate preview endpoint. Used to apply the plan change preview.

## Responses

### `200`

OK

Type: object (SubscriptionDTO).

- `createdAt` (string (date-time), required): The date and time when the entity was created. Example: `2024-02-18T12:00:00Z`.
- `updatedAt` (string (date-time), required, nullable): The date and time when the entity was last updated. Example: `2024-02-21T12:15:00Z`.
- `metadata` (map of string to string, nullable): Metadata used by merchants to store additional information about the entity.
- `id` (string, required): The ID of the subscription. Example: `sub_2QC7PqoUeOxQEWscJJt6B3PkvyL`.
- `status` (string, required): The status of the subscription. One of `active`, `cancelled`. Example: `active`.
- `isRecovering` (boolean, required): Whether the subscription is recovering from a failed payment. Example: `false`.
- `autoBillingEnabled` (boolean, required): Whether the subscription is going to be billed automatically. Example: `true`.
- `autoBillingDisabledAt` (string (date-time), required, nullable): The date when auto billing was disabled.
- `autoBillingDisabledReason` (string, required, nullable): The reason why auto billing was disabled. One of `recurring_payment_errored`, `subscription_cancelled`, `latest_invoice_retrying`. Example: `subscription_cancelled`.
- `startDate` (string (date-time), required): The start date of the subscription.
- `endDate` (string (date-time), required, nullable): The end date of the subscription, if it has ended.
- `cancelAtPeriodEnd` (boolean, required): Whether the subscription should be cancelled when current billing cycle ends. Example: `true`.
- `cancelAtCycle` (number, required, nullable): The cycle at whose end the subscription is scheduled to be cancelled, or absent when no cancellation is scheduled. Equals `currentCycle` once `cancelAtPeriodEnd` is true. Example: `2`.
- `currentCycle` (number, required): The current cycle of the subscription, starting from 1. Example: `1`.
- `currentPeriodStart` (string (date-time), required): The start date of the current billing period.
- `currentPeriodEnd` (string (date-time), required): The end date of the current billing period.
- `setupInvoice` (string, required): The ID of the invoice that set up the subscription.
- `setupLineItem` (string, required, nullable): The ID of the line item that set up the subscription.
- `billingSettings` (object, required): The billing settings for recurring charges.
  - `paymentMethodType` (string, required): The payment method type used for recurring billing. One of `card`, `paypal`, `applePay`.
  - `gatewayProfile` (string, required): The gateway profile used for recurring billing.
  - `captureMethod` (string, required): The capture method used for recurring billing. One of `automatic`, `automaticDelayed`, `manual`.
  - `captureDelay` (number, required, nullable): The capture delay in days, if applicable. Example: `3`.
- `upcomingInvoice` (object, required, nullable): The upcoming invoice details.
  - `amount` (number, required): Amount to be charged for the upcoming invoice. Example: `1500`.
  - `currency` (string, required): Currency of the upcoming invoice. One of `usd`, `eur`, `gbp`, `cad`, `aud`, `pln`, `czk`, `sek`, `dkk`. Example: `usd`.
  - `periodStart` (string (date-time), required): Start date of the billing period. Example: `2023-01-01T00:00:00Z`.
  - `periodEnd` (string (date-time), required): End date of the billing period. Example: `2023-01-31T23:59:59Z`.
  - `statementDescriptor` (string, required, nullable): Statement descriptor for the upcoming invoice. Example: `SUBSCRIPTION`.
  - `statementDescriptorSuffix` (string, required, nullable): Statement descriptor suffix for the upcoming invoice. Example: `PRO PLAN`.
  - `comment` (string, required, nullable): Comment for the upcoming invoice. Example: `Invoice for subscription 123, period January 2023`.
- `customer` (object, required): The customer associated with the subscription.
  - `createdAt` (string (date-time), required): The date and time when the entity was created. Example: `2024-02-18T12:00:00Z`.
  - `updatedAt` (string (date-time), required, nullable): The date and time when the entity was last updated. Example: `2024-02-21T12:15:00Z`.
  - `metadata` (map of string to string, nullable): Metadata used by merchants to store additional information about the entity.
  - `id` (string, required): The ID of the customer. Example: `cus_2QC7PqoUeOxQEWscJJt6B3PkvyL`.
  - `email` (string, required): The email of the customer. Example: `user@gmail.com`.
  - `name` (string, required, nullable): The name of the customer. Example: `John Doe`.
  - `phoneNumber` (string, required, nullable): The phone number of the customer. Numbers submitted since normalisation began are stored in E.164 format (`+` followed by digits) when they could be validated; any other number is returned as it was sent. Example: `+12015550123`.
  - `dateOfBirth` (string (date), required, nullable): The date of birth of the customer. Pattern `^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$`. Example: `2020-01-01`.
  - `gender` (string, required, nullable): The gender of the customer. One of `male`, `female`, `other`. Example: `male`.
  - `restrictMit` (boolean): Whether the customer is restricted from making merchant-initiated payments. Only available from the dashboard or the API using a secret key. Example: `false`.
  - `restrictCit` (boolean): Whether the customer is restricted from making customer-initiated payments. Only available from the dashboard or the API using a secret key. Example: `false`.
  - `restrictReason` (string, nullable): Reason for restricting the customer. Only available from the dashboard or the API using a secret key. Example: `Customer restricted due to suspicious activity`.
  - `isRestricted` (boolean): Whether the customer has at least one restriction applied (either `restrictMit` or `restrictCit`). Only available from the dashboard or the API using a secret key. Example: `true`.
  - `billingAddress` (object, required): The billing address of the customer.
    - `firstName` (string, required, nullable)
    - `lastName` (string, required, nullable)
    - `companyName` (string, required, nullable)
    - `line1` (string, required, nullable)
    - `line2` (string, required, nullable)
    - `city` (string, required, nullable)
    - `state` (string, required, nullable)
    - `postalCode` (string, required, nullable)
    - `country` (string, required, nullable)
  - `shippingAddress` (object, required): The shipping address of the customer.
    - `firstName` (string, required, nullable)
    - `lastName` (string, required, nullable)
    - `companyName` (string, required, nullable)
    - `line1` (string, required, nullable)
    - `line2` (string, required, nullable)
    - `city` (string, required, nullable)
    - `state` (string, required, nullable)
    - `postalCode` (string, required, nullable)
    - `country` (string, required, nullable)
- `price` (object, required): The price details of the subscription.
  - `createdAt` (string (date-time), required): The date and time when the entity was created. Example: `2024-02-18T12:00:00Z`.
  - `updatedAt` (string (date-time), required, nullable): The date and time when the entity was last updated. Example: `2024-02-21T12:15:00Z`.
  - `metadata` (map of string to string, nullable): Metadata used by merchants to store additional information about the entity.
  - `id` (string, required): ID of the price. Example: `price_2R4e2xDqbww8ewmkIYWE1A6Zcfp`.
  - `type` (string, required): Type of the price. One of `one_time`, `recurring`. Example: `recurring`.
  - `active` (boolean, required): Indicates if the price is currently active. Inactive prices will be hidden from the dashboard, but can still be used in the API. Example: `true`.
  - `name` (string): Name of the price. Only available from the dashboard or the API using a secret key. Example: `My Digital Subscription`.
  - `amount` (number, required): Amount of the price in minor units (e.g., cents) Example: `1500`.
  - `quantity` (number, required): Number of units this price represents. The `amount` covers all of them, so a line item referencing this price gets this quantity at a per-unit amount of `amount / quantity`. Example: `1`.
  - `currency` (string, required): Currency of the price. One of `usd`, `eur`, `gbp`, `cad`, `aud`, `pln`, `czk`, `sek`, `dkk`. Example: `usd`.
  - `product` (object): The product that this price represents. Only available from the dashboard or the API using a secret key.
    - `createdAt` (string (date-time), required): The date and time when the entity was created. Example: `2024-02-18T12:00:00Z`.
    - `updatedAt` (string (date-time), required, nullable): The date and time when the entity was last updated. Example: `2024-02-21T12:15:00Z`.
    - `metadata` (map of string to string, required, nullable): Metadata used by merchants to store additional information about the entity.
    - `id` (string, required): ID of the product. Example: `prod_2QC7PqoUeOxQEWscJJt6B3PkvyL`.
    - `active` (boolean, required): Indicates if the product is currently active. Inactive products will be hidden from the dashboard, but can still be used in the API. Example: `true`.
    - `name` (string, required): Name of the product. Only available from the dashboard or the API using a secret key. Example: `My product`.
    - `description` (string, required, nullable): Description of the product. Only available from the dashboard or the API using a secret key. Example: `Best selling product`.
    - `statementDescriptor` (string, required, nullable): Statement descriptor for the product that will be used in the bank statement. Example: `Face Yoga subscription`.
    - `statementDescriptorSuffix` (string, required, nullable): Statement descriptor suffix for the product, appended to your account's descriptor by gateways that support a per-payment suffix. Only available from the dashboard or the API using a secret key. Example: `PRO PLAN`.
    - `category` (string, required, nullable): Category of the product, sent to the payment provider so the VAT split between digital services and physical goods can be reconstructed from the provider reports. Plays no part in fulfillment. Only available from the dashboard or the API using a secret key. One of `digital`, `physical`. Example: `digital`.
    - `shippable` (boolean, required): Whether the product takes part in Order Management: a payment for one of its prices becomes an order item. Only available from the dashboard or the API using a secret key. Example: `false`.
    - `sku` (string, required, nullable): Stock Keeping Unit the warehouse ships this product under, used on the 3PL manifest. For a shippable product it decides whether the resulting order item physically ships: an item without one is kept on the order but never fulfilled. Null when the product has none. Only available from the dashboard or the API using a secret key. Example: `FY-YOGA-MAT-01`.
  - `billingSchedule` (object, nullable): Deprecated: Use recurringSchedule instead. Billing schedule for `recurring` prices. Only available from the dashboard or the API using a secret key. Deprecated.
    - `createdAt` (string (date-time), required): The date and time when the entity was created. Example: `2024-02-18T12:00:00Z`.
    - `updatedAt` (string (date-time), required, nullable): The date and time when the entity was last updated. Example: `2024-02-21T12:15:00Z`.
    - `metadata` (map of string to string, required, nullable): Metadata used by merchants to store additional information about the entity.
    - `id` (string, required): ID of the billing schedule. Example: `bsch_2QC7PqoUeOxQEWscJJt6B3PkvyL`.
    - `currency` (string, required): Currency of the billing schedule. One of `usd`, `eur`, `gbp`, `cad`, `aud`, `pln`, `czk`, `sek`, `dkk`. Example: `usd`.
    - `cycleDefinitions` (array of object, required)
      - `createdAt` (string (date-time), required): The date and time when the entity was created. Example: `2024-02-18T12:00:00Z`.
      - `updatedAt` (string (date-time), required, nullable): The date and time when the entity was last updated. Example: `2024-02-21T12:15:00Z`.
      - `metadata` (map of string to string, required, nullable): Metadata used by merchants to store additional information about the entity.
      - `position` (number, required): Position of the billing cycle in the schedule. Used for ordering. Example: `1`.
      - `amount` (number, required): Amount to be charged for this billing cycle in minor units (e.g., cents) Example: `1500`.
      - `currency` (string, required): Currency of the billing cycle. One of `usd`, `eur`, `gbp`, `cad`, `aud`, `pln`, `czk`, `sek`, `dkk`. Example: `usd`.
      - `intervalUnit` (string, required): Unit of time for the billing cycle interval. One of `minute`, `hour`, `day`, `week`, `month`, `year`.
      - `intervalValue` (number, required): Value of the billing cycle interval.
  - `recurringSchedule` (object, nullable): Recurring schedule for recurring prices. Only available from the dashboard or the API using a secret key.
    - `intervalUnit` (string, required): Recurring interval unit. One of `minute`, `hour`, `day`, `week`, `month`, `year`. Example: `month`.
    - `intervalCount` (number, required): Recurring interval count. Example: `1`.
    - `trial` (object, required, nullable): Trial schedule details when present.
      - `intervalUnit` (string, required): Trial interval unit. One of `minute`, `hour`, `day`, `week`, `month`, `year`. Example: `day`.
      - `intervalCount` (number, required): Trial interval count. Example: `7`.
      - `amount` (number, required): Initial setup/trial payment amount in minor units. This is the amount charged during the first billing cycle before the regular recurring amount takes effect. Example: `199`.
- `cancellationReason` (string, required, nullable): Why the subscription was cancelled. `requested`: you cancelled it. `payment_failed`: a renewal payment failed and could not be recovered. `chargeback`: one of its payments was charged back. `customer_blacklisted`: you blacklisted the customer's email. `null` while the subscription is active, and for subscriptions cancelled before this field was introduced. One of `requested`, `payment_failed`, `chargeback`, `customer_blacklisted`. Example: `customer_blacklisted`.

### `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.

Type: object (ProvisioningInProgress).

- `status` (string, required): Signals the merchant environment is still being provisioned. One of `provisioning`.
- `merchantAccountId` (string, required): The merchant account whose environment is being provisioned. Example: `dAI3aa87ROOeupeBCjNSKCOBOisBCYjB`.

### Errors

- `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; or `invalid_state_error` when the request was well-formed but the resource is not in a state that allows it.
- `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. A limit applies per operation; requests to other operations are unaffected. `type` is `rate_limit_error`. Use the `Retry-After-global` header to know when to retry.
- `500`: The request could not be completed because of an unexpected error. `type` is `api_error`.
- `503`: The request could not be served right now: the API is temporarily at capacity, or a dependency needed to authorize the request is 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.

Every error response has the same body: see [Errors](https://docs.odus.com/docs/guides/api-features/errors.md).

---

Generated from the Core API v2 OpenAPI document, https://api.odus.com/openapi.v2.json. Interactive page: https://docs.odus.com/docs/api/core/v2/subscription-controller-update