# Preview a Subscription update

`POST /v2/subscriptions/{id}/preview`

Core API v2, Subscriptions.

Generates a preview of the changes that would occur if the Subscription is updated

**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 (GenerateUpdatePreviewRequestDTO).

- `price` (string): The ID of the price to apply to the subscription update. Example: `price_2R4e2xDqbww8ewmkIYWE1A6Zcfp`.
- `nextBillingDate` (string (date-time)): The date of the next recurring payment. Must be in the future and after the current period start. Example: `2026-06-01T00:00:00.000Z`.
- `applyTrial` (boolean): Bill the next cycle on the new price's trial, using the trial's amount and interval. Later cycles follow the price's regular schedule. Requires `price`, and that price must have a trial. Defaults to `false`, which skips the trial. Example: `true`.

## Responses

### `200`

OK

Type: object (UpdatePreviewDTO).

- `id` (string, required): The ID of the preview. Example: `sub_preview_2pKw553IpHphT79MHhZh8jEf2cT`.
- `subscription` (object, required): How subscription will be updated, if the preview is applied.
  - `id` (string, required): The ID of the subscription. Example: `sub_2QC7PqoUeOxQEWscJJt6B3PkvyL`.
  - `price` (string, required): The ID of the price associated with the subscription.
  - `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 period.
  - `currentPeriodEnd` (string (date-time), required): The end date of the current period.
  - `upcomingInvoice` (object, required): 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`.
- `previewValidUntil` (string (date-time), required): The date until the preview is valid.

### `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`.
- `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-generate-update-preview