# Update subscription

Applies targeted updates to an active subscription, including updating the payment instrument, discount, description, and metadata, ending a trial period, and managing line items. For example, trial end uses an explicit mode, and line items are managed by adding, updating, and removing entries instead of full replacement. Each update is applied only when its corresponding field is present in the request.

Endpoint: POST /subscriptions/update
Version: 2.0.0
Security: bearerAuth

## Request fields (application/json):

  - `channel_id` (string)
    Unique channel identifier. Required when using multi-channel API keys.
    Example: "chn_01JYWX6Z5A8P32B6NVH1G9876A"

  - `id` (string, required)
    Unique subscription identifier.
    Example: "subs_01HYDYBRKN16B8X3BR9WP78ZR7"

  - `application` (object)
    Controls when the subscription updates take effect. Defaults to PERIOD_END when omitted.
    Example: {"mode":"IMMEDIATE"}

  - `application.mode` (string, required)
    Determines when the updates apply. PERIOD_END keeps the current period unchanged. IMMEDIATE stops the current period and resets the next charge date and anchor date to now.
    Enum: "IMMEDIATE", "PERIOD_END"

  - `payment_instrument_id` (string)
    Identifier of the payment instrument used for billing.
    Example: "pi_01J1Z2X3Y4W5V6U7T8S9R0"

  - `description` (string,null)
    Additional description for the subscription.
    Example: "Premium plan subscription"

  - `metadata` (object,null)
    Set of key-value pairs attached to the subscription.
    Example: {"order_id":"12345"}

  - `discounts` (array,null) — one of:
    Discounts applied to the subscription using coupons.
    Example: [{"coupon_code":"WINTER25"}]
    - Coupon ID:
      - `coupon_id` (string, required)
        Unique coupon identifier.
        Example: "0291b87b-deac-4eb4-8732-2a70d247a171"
    - Coupon code:
      - `coupon_code` (string, required)
        Code of the associated coupon.
        Example: "WINTER25"

  - `trial_end_update` (object) — one of:
    Changes to apply to the trial end date.
    Example: {"mode":"SPECIFIC_DATE","ends_at":"2026-01-24T11:45:00.000000Z"}
    - Now:
      - `mode` (string, required)
        Ends the trial immediately.
        Example: "SPECIFIC_DATE"
    - Specific date:
      - `mode` (string, required)
        Ends the trial on a specific date.
        Example: "SPECIFIC_DATE"
      - `ends_at` (string, required)
        Date and time when the trial ends. Must be in the future.
        Example: "2026-01-24T11:45:00.000000Z"

  - `line_items_updates` (object)
    Changes to apply to the subscription line items.
    Example: {"to_add":[{"product_price_id":"f47ac10b-58cc-4372-a567-0e02b2c3d479","quantity":1}],"to_update":[{"id":"slit_01KPWT0K1PQWEYYRT7J1H3NC85","quantity":2}],"to_delete":["slit_01KPWT0K1PQWEYYRT7J1H3NC86"]}

  - `line_items_updates.to_add` (array)
    Line items to add to the subscription.
    Example: [{"product_price_id":"f47ac10b-58cc-4372-a567-0e02b2c3d479","quantity":1}]

  - `line_items_updates.to_add.product_price_id` (string, required)
    Identifier of the price to add.
    Example: "f47ac10b-58cc-4372-a567-0e02b2c3d479"

  - `line_items_updates.to_add.quantity` (integer, required)
    Number of product units.
    Example: 1

  - `line_items_updates.to_update` (array)
    Existing line items to update.
    Example: [{"id":"slit_01KPWT0K1PQWEYYRT7J1H3NC85","quantity":2}]

  - `line_items_updates.to_update.id` (string, required)
    Unique line item identifier.
    Example: "slit_01KPWT0K1PQWEYYRT7J1H3NC85"

  - `line_items_updates.to_update.quantity` (integer, required)
    Number of product units.
    Example: 2

  - `line_items_updates.to_delete` (array)
    Identifiers of line items to remove.
    Example: ["slit_01KPWT0K1PQWEYYRT7J1H3NC86"]

## Response 200 fields (application/json):

  - `id` (string, required)
    Unique subscription identifier.
    Example: "subs_01HYDYBRKN16B8X3BR9WP78ZR7"

  - `status` (string, required)
    Current subscription status.
    Enum: "CREATED", "PENDING", "TRIALING", "ACTIVE", "REDEMPTION", "UNPAID", "CANCELLED", "EXPIRED"

  - `currency` (string, required)
    Three-letter ISO-4217 currency code.
    Example: "USD"

  - `line_items` (array, required)
    Line items applied to the subscription.
    Example: [{"id":"slit_01KPWT0K1PQWEYYRT7J1H3NC85","billing_type":"RECURRING","currency":"USD","amount":1000,"quantity":1,"started_at":"2025-12-24T11:45:00.000000Z","period":{"start_at":"2025-12-24T11:45:00.000000Z","end_at":"2026-01-24T11:45:00.000000Z"},"billing_period_config":{"value":1,"unit":"MONTH"},"product_info":{"name":"Great product","description":"Annual subscription for a great product"},"created_at":"2025-12-24T11:45:00.000000Z","updated_at":"2025-12-24T11:47:00.000000Z","product_id":"7c9e6679-7425-40de-944b-e07fc1f90ae7","product_price_id":"f47ac10b-58cc-4372-a567-0e02b2c3d479"}]

  - `line_items.id` (string, required)
    Unique line item identifier.
    Example: "slit_01KPWT0K1PQWEYYRT7J1H3NC85"

  - `line_items.billing_type` (string, required)
    Billing type of the line item.
    Enum: "RECURRING", "ONE_TIME"

  - `line_items.currency` (string, required)
    Three-letter ISO-4217 currency code.
    Example: "USD"

  - `line_items.amount` (integer, required)
    Line item amount in minor units.
    Example: 1000

  - `line_items.quantity` (integer, required)
    Number of product units.
    Example: 1

  - `line_items.started_at` (string)
    Date and time when the line item started.
    Example: "2025-12-24T11:45:00.000000Z"

  - `line_items.period` (object)
    Billing period interval for the line item.
    Example: {"start_at":"2025-12-24T11:45:00.000000Z","end_at":"2026-01-24T11:45:00.000000Z"}

  - `line_items.period.start_at` (string, required)
    Date and time when the interval starts.
    Example: "2025-12-24T11:45:00.000000Z"

  - `line_items.period.end_at` (string, required)
    Date and time when the interval ends. Not present when the interval is open-ended and continues indefinitely.
    Example: "2026-01-24T11:45:00.000000Z"

  - `line_items.billing_period_config` (object)
    Recurring calendar interval at which the line item is billed.
    Example: {"value":1,"unit":"MONTH"}

  - `line_items.billing_period_config.value` (integer, required)
    Number of units in the period.
    Example: 1

  - `line_items.billing_period_config.unit` (string, required)
    Time unit for the period.
    Enum: "MINUTE", "HOUR", "DAY", "WEEK", "MONTH", "QUARTER", "YEAR"

  - `line_items.product_info` (object, required)
    Snapshot of product details for the line item.
    Example: {"name":"Great product","description":"Annual subscription for a great product"}

  - `line_items.product_info.name` (string, required)
    Product name.
    Example: "Great product"

  - `line_items.product_info.description` (string)
    Product description.
    Example: "Annual subscription for a great product"

  - `line_items.created_at` (string, required)
    Date and time when the line item was created.
    Example: "2025-12-24T11:45:00.000000Z"

  - `line_items.updated_at` (string, required)
    Date and time when the line item was updated.
    Example: "2025-12-24T11:47:00.000000Z"

  - `line_items.product_id` (string, required)
    Identifier of the associated product.
    Example: "7c9e6679-7425-40de-944b-e07fc1f90ae7"

  - `line_items.product_price_id` (string, required)
    Identifier of the associated price.
    Example: "f47ac10b-58cc-4372-a567-0e02b2c3d479"

  - `created_at` (string, required)
    Date and time when the subscription was created.
    Example: "2025-12-24T11:45:00.000000Z"

  - `updated_at` (string, required)
    Date and time when the subscription was updated.
    Example: "2025-12-24T11:47:00.000000Z"

  - `started_at` (string)
    Date and time when the subscription started.
    Example: "2025-12-24T11:45:00.000000Z"

  - `next_billing_at` (string)
    Date and time when the next billing occurs.
    Example: "2026-01-24T11:45:00.000000Z"

  - `anchor_at` (string)
    Date and time used to anchor billing cycles.
    Example: "2025-12-24T11:45:00.000000Z"

  - `trial_info` (object)
    Trial details for the subscription.
    Example: {"type":"FREE","period":{"start_at":"2025-12-24T11:45:00.000000Z","end_at":"2025-12-31T11:45:00.000000Z"},"amount":0,"period_config":{"value":7,"unit":"DAY"}}

  - `trial_info.type` (string, required)
    Trial type.
    Enum: "FREE", "PAID"

  - `trial_info.period` (object)
    Trial period interval.
    Example: {"start_at":"2025-12-24T11:45:00.000000Z","end_at":"2026-01-24T11:45:00.000000Z"}

  - `trial_info.period.start_at` (string, required)
    Date and time when the interval starts.
    Example: "2025-12-24T11:45:00.000000Z"

  - `trial_info.period.end_at` (string, required)
    Date and time when the interval ends. Not present when the interval is open-ended and continues indefinitely.
    Example: "2026-01-24T11:45:00.000000Z"

  - `trial_info.amount` (integer, required)
    Trial amount in minor units.

  - `trial_info.period_config` (object)
    Period expressed as a numeric value and a time unit.
    Example: {"value":7,"unit":"DAY"}

  - `trial_info.period_config.value` (integer, required)
    Number of units in the period.
    Example: 7

  - `trial_info.period_config.unit` (string, required)
    Time unit for the period.
    Enum: same as `line_items.billing_period_config.unit` (7 values)

  - `cancellation_info` (object)
    Cancellation details for the subscription. Present when the subscription is scheduled for cancellation or already cancelled.
    Example: {"cancel_at":"2026-03-24T11:45:00.000000Z","requested_at":"2026-02-24T11:45:00.000000Z","reason":"CANCELLATION_REQUESTED","comment":"Customer requested cancellation"}

  - `cancellation_info.cancel_at` (string, required)
    Date and time when the subscription is scheduled to be cancelled or was cancelled.
    Example: "2026-03-24T11:45:00.000000Z"

  - `cancellation_info.requested_at` (string, required)
    Date and time when cancellation was requested.
    Example: "2026-02-24T11:45:00.000000Z"

  - `cancellation_info.reason` (string, required)
    Reason for the cancellation.
    Enum: "DUNNING_EXHAUSTED", "CANCELLATION_REQUESTED"

  - `cancellation_info.comment` (string)
    Additional cancellation comment.
    Example: "Customer requested cancellation"

  - `discounts` (array)
    Discounts applied to the subscription.
    Example: [{"coupon_id":"0291b87b-deac-4eb4-8732-2a70d247a171","coupon_code":"WINTER25"}]

  - `discounts.coupon_id` (string, required)
    Unique identifier of the associated coupon.
    Example: "0291b87b-deac-4eb4-8732-2a70d247a171"

  - `discounts.coupon_code` (string)
    Code of the associated coupon.
    Example: "WINTER25"

  - `metadata` (object)
    Set of key-value pairs attached to the subscription.
    Example: {"order_id":"12345"}

  - `description` (string)
    Additional description for the subscription.
    Example: "Premium plan subscription"

  - `customer_id` (string, required)
    Unique customer identifier.
    Example: "cust_01KMG2ABYPF6XS5DMJQ817C429"

  - `payment_instrument_id` (string)
    Identifier of the payment instrument used for billing.
    Example: "pi_01J1Z2X3Y4W5V6U7T8S9R0"

  - `latest_invoice_id` (string)
    Identifier of the most recent invoice.
    Example: "inv_01KPWT0K1PQWEYYRT7J1H3NC85"

## Response 400 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "VALIDATION"

  - `message` (string, required)
    Message describing the error.
    Example: "One or more fields failed validation due to constraints"

  - `context` (object, required)
    Additional context about the validation error, including specific constraints.
    Example: {"constraints":{"email":{"type":"TYPE","message":"The 'email' field must be a valid email address"},"age":{"type":"MIN","message":"The 'age' field must be a number greater than or equal to 18"}}}

  - `context.constraints` (object, required)
    Failed constraints keyed by the field name.
    Example: {"email":{"type":"TYPE","message":"The 'email' field must be a valid email address"},"age":{"type":"MIN","message":"The 'age' field must be a number greater than or equal to 18"}}

## Response 401 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "UNAUTHENTICATED"

  - `message` (string, required)
    Message describing the error.
    Example: "Credentials are invalid or missing"

## Response 403 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "PERMISSION_DENIED"

  - `message` (string, required)
    Message describing the error.
    Example: "Permission denied"

## Response 404 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "NOT_FOUND"

  - `message` (string, required)
    Message describing the error. The entity varies by endpoint.
    Example: "The requested resource could not be found"

## Response 422 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "INCOMPATIBLE_STATUS", "SUBSCRIPTION_IN_PROCESSING", "PAYMENT_INSTRUMENT_NOT_FOUND", "PAYMENT_INSTRUMENT_NOT_ACTIVE", "LONG_TRIAL_PERIOD", "SAME_COUPON", "SAME_COUPON_CODE", "COUPON_NOT_FOUND", "COUPON_NOT_ACTIVE", "COUPON_CODE_NOT_FOUND", "COUPON_CODE_NOT_ACTIVE", "INCOMPATIBLE_CURRENCY", "LINE_ITEM_NOT_FOUND", "DUPLICATE_PRICE", "DUPLICATE_PRODUCT", "ITEMS_LIMIT_EXCEEDED", "NO_RECURRING_ITEMS", "MULTIPLE_RECURRING_ITEMS", "PRICE_NOT_FOUND", "PRICE_NOT_ACTIVE", "PRODUCT_NOT_FOUND", "PRODUCT_NOT_ACTIVE"

  - `message` (string, required)
    Message describing the error.
    Example: "The request conflicts with the current state"

  - `context` (object)
    Additional error context.

## Response 429 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "RATE_LIMIT"

  - `message` (string, required)
    Message describing the error.
    Example: "Rate limit exhausted"

  - `context` (object)
    Additional context about the error.

  - `context.next_try_at` (string)
    Timestamp indicating when to retry the request.
    Example: "2024-12-31T23:59:59.000000Z"