# Update subscription

By using this method, merchants can update an active subscription by modifying the trial period, applying a discount, or changing the product. It allows multiple changes in a single request for efficient subscription management and customer retention.

Endpoint: POST /subscription/update
Version: 1.0.0
Security: MerchantID

## Header parameters:

  - `merchant` (string, required)
    Unique public key provided upon registration and must be shared for identification purposes.
    Example: "api_pk_7b197...ba108f842"

  - `signature` (string, required)
    Request signature that allows verification of merchant authenticity on the payment gateway server.
    Example: "M2E3OTkyNzcz...xMmExODI4"

## Request fields (application/json):

  - `id` (string, required)
    Unique subscription identifier.
    Example: "83b19018-cbc4-45f0-899a-dda84fd2705e"

  - `product_id` (string)
    Unique product identifier to apply to the specified subscription.
    Example: "ac43b415-5522-4373-b026-a365462f9657"

  - `trial_ended_at` (object)
    Datetime to end the subscription trial.

  - `trial_ended_at.type` (string, required)
    Indicates how the trial should end.        
- immediate - end trial immediately
- specific_date - end trial at specific date
    Enum: "specific_date", "immediate"

  - `trial_ended_at.date` (string)
    Indicates the specific date when the trial should end.


  Required if the type is specific_date.


  Trial end date must be within 1 year from the current date.
    Example: "2026-07-20 13:20:00"

  - `discount` (object) — one of:
    Discount details to manage subscription pricing.


  To remove an existing discount, send null for discount.
    - coupon_id:
      - `coupon_id` (string, required)
        Unique coupon identifier.
        Example: "379bd8d9-7f2a-44eb-be35-b741985e1b08"
    - coupon_code:
      - `coupon_code` (string, required)
        Coupon code for customers to redeem.
        Example: "PRIME50"

  - `coupon_id` (string)
    Unique coupon identifier.


  Pass either coupon_id or coupon_code, not both.
    Example: "379bd8d9-7f2a-44eb-be35-b741985e1b08"

  - `coupon_code` (string)
    Coupon code.


  Pass either coupon_id or coupon_code, not both.
    Example: "PRIME50"

## Response 200 fields (application/json):

  - `body` (object) — one of (discriminator: status):
    - pending:
      - `id` (string, required)
        Unique subscription identifier.
        Example: "9e252e9f-c5a3-4dca-93df-4c9fcf54267e"
      - `status` (string, required)
        Subscription status.
        Example: "pending"
      - `started_at` (string)
        Datetime of the subscription start.
        Example: "2025-12-08 12:37:24"
      - `updated_at` (string, required)
        Datetime of the subscription update.
        Example: "2025-12-08 12:37:25"
      - `expired_at` (string)
        Datetime of the subscription expiration.
        Example: "2025-12-12 12:37:24"
      - `payment_type` (string)
        Customer payment method used to pay for a subscription.
        Enum: "card", "paypal-vault", "mercadopago", "upi", "pix", "gcash", "alipay", "mbway", "wechatpay"
      - `discount` (object)
        Contains information about the discount applied.
      - `discount.created_at` (string, required)
        Datetime of the discount creation.
        Example: "2025-05-31 12:53:12"
      - `discount.coupon_code` (string)
        Coupon code.
        Example: "SUMMER25OFF"
      - `discount.coupon` (object, required)
        Coupon details.
      - `discount.coupon.name` (string, required)
        Coupon name.
        Example: "Summer 25% OFF"
      - `discount.coupon.description` (string)
        Coupon description.
        Example: "25% off for 3 months"
      - `discount.coupon.type` (string, required)
        Discount type indicating percentage or fixed amount off the price.
        Enum: "percentage", "amount"
      - `discount.coupon.value` (integer, required)
        Discount value.


  Depending on the coupon type, the value represents either a percentage or a fixed amount.
        Example: 25
      - `trial` (boolean, required)
        Indicates whether the subscription has a trial.
      - `trial_started_at` (string)
        Datetime of the subscription trial start.
        Example: "2025-12-08 12:37:24"
      - `trial_ended_at` (string)
        Datetime of the subscription trial expiration.
        Example: "2025-12-08 12:37:25"
      - `cancelled_at` (string)
        Datetime of subscription cancellation.
        Example: "2025-12-12 19:37:24"
      - `cancellation_requested_at` (string)
        Datetime of subscription cancellation request.
        Example: "2025-12-11 19:37:24"
      - `cancel_code` (string)
        Reason code that is used to cancel the subscription.
        Enum: "8.01", "8.02", "8.03", "8.04", "8.05", "8.06", "8.07", "8.08", "8.09", "8.10", "8.11", "8.12", "8.13", "8.14", "8.15"
      - `cancel_message` (string)
        Cancellation reason brief description.
        Example: "Cancellation after redemption period"
      - `pause` (object)
        Pause schedule parameters.
      - `pause.from_date` (string, required)
        Datetime of the pause start.


   If the subscription pause type value is immediate, the datetime is the date and time of the pause start request.
        Example: "2025-12-27 11:26:08"
      - `pause.to_date` (string)
        Datetime of the pause end.


  It is absent when the subscription is planned to pause infinitely.
        Example: "2025-12-27 11:26:08"
    - active:
      - `id` (string, required)
        Unique subscription identifier.
        Example: "9e252e9f-c5a3-4dca-93df-4c9fcf54267e"
      - `status` (string, required)
        Subscription status.
        Example: "active"
      - `started_at` (string, required)
        Datetime of the subscription start.
        Example: "2025-12-08 12:37:24"
      - `updated_at` (string, required)
        Datetime of the subscription update.
        Example: "2025-12-08 12:37:25"
      - `expired_at` (string)
        Datetime of the subscription expiration.
        Example: "2025-12-12 12:37:24"
      - `next_charge_at` (string)
        Datetime of the subsequent charge.


  It is absent when the subscription is planned to pause infinitely.
        Example: "2025-12-12 14:37:24"
      - `payment_type` (string, required)
        Customer payment method used to pay for a subscription.
        Enum: same as `payment_type` in "pending" (9 values)
      - `discount` (object)
        Contains information about the discount applied.
      - `discount.created_at` (string, required)
        Datetime of the discount creation.
        Example: "2025-05-31 12:53:12"
      - `discount.coupon_code` (string)
        Coupon code.
        Example: "SUMMER25OFF"
      - `discount.coupon` (object, required)
        Coupon details.
      - `discount.coupon.name` (string, required)
        Coupon name.
        Example: "Summer 25% OFF"
      - `discount.coupon.description` (string)
        Coupon description.
        Example: "25% off for 3 months"
      - `discount.coupon.type` (string, required)
        Discount type indicating percentage or fixed amount off the price.
        Enum: same as `discount.coupon.type` in "pending" (2 values)
      - `discount.coupon.value` (integer, required)
        Discount value.


  Depending on the coupon type, the value represents either a percentage or a fixed amount.
        Example: 25
      - `trial` (boolean, required)
        Indicates whether the subscription has a trial.
      - `trial_started_at` (string)
        Datetime of the subscription trial start.
        Example: "2025-12-08 12:37:24"
      - `trial_ended_at` (string)
        Datetime of the subscription trial expiration.
        Example: "2025-12-08 12:37:25"
      - `cancelled_at` (string)
        Datetime of subscription cancellation.
        Example: "2025-12-12 19:37:24"
      - `cancellation_requested_at` (string)
        Datetime of subscription cancellation request.
        Example: "2025-12-11 19:37:24"
      - `cancel_code` (string)
        Reason code that is used to cancel the subscription.
        Enum: same as `cancel_code` in "pending" (15 values)
      - `cancel_message` (string)
        Cancellation reason brief description.
        Example: "Cancellation after redemption period"
      - `pause` (object)
        Pause schedule parameters.
      - `pause.from_date` (string, required)
        Datetime of the pause start.


   If the subscription pause type value is immediate, the datetime is the date and time of the pause start request.
        Example: "2025-03-27 11:26:08"
      - `pause.to_date` (string)
        Datetime of the pause end.


  It is absent when the subscription is planned to pause infinitely.
        Example: "2025-03-27 11:26:08"
    - cancelled:
      - `id` (string, required)
        Unique subscription identifier.
        Example: "9e252e9f-c5a3-4dca-93df-4c9fcf54267e"
      - `status` (string, required)
        Subscription status.
        Example: "cancelled"
      - `started_at` (string, required)
        Datetime of the subscription start.
        Example: "2025-12-08 12:37:24"
      - `updated_at` (string, required)
        Datetime of the subscription update.
        Example: "2025-12-08 12:37:25"
      - `expired_at` (string)
        Datetime of the subscription expiration.
        Example: "2025-12-12 12:37:24"
      - `payment_type` (string, required)
        Customer payment method used to pay for a subscription.
        Enum: same as `payment_type` in "pending" (9 values)
      - `discount` (object)
        Contains information about the discount applied.
      - `discount.created_at` (string, required)
        Datetime of the discount creation.
        Example: "2025-05-31 12:53:12"
      - `discount.coupon_code` (string)
        Coupon code.
        Example: "SUMMER25OFF"
      - `discount.coupon` (object, required)
        Coupon details.
      - `discount.coupon.name` (string, required)
        Coupon name.
        Example: "Summer 25% OFF"
      - `discount.coupon.description` (string)
        Coupon description.
        Example: "25% off for 3 months"
      - `discount.coupon.type` (string, required)
        Discount type indicating percentage or fixed amount off the price.
        Enum: same as `discount.coupon.type` in "pending" (2 values)
      - `discount.coupon.value` (integer, required)
        Discount value.


  Depending on the coupon type, the value represents either a percentage or a fixed amount.
        Example: 25
      - `trial` (boolean, required)
        Indicates whether the subscription has a trial.
      - `trial_started_at` (string)
        Datetime of the subscription trial start.
        Example: "2025-12-08 12:37:24"
      - `trial_ended_at` (string)
        Datetime of the subscription trial expiration.
        Example: "2025-12-08 12:37:25"
      - `cancelled_at` (string)
        Datetime of subscription cancellation.
        Example: "2025-12-12 19:37:24"
      - `cancellation_requested_at` (string)
        Datetime of subscription cancellation request.
        Example: "2025-12-11 19:37:24"
      - `cancel_code` (string)
        Reason code that is used to cancel the subscription.
        Enum: same as `cancel_code` in "pending" (15 values)
      - `cancel_message` (string)
        Cancellation reason brief description.
        Example: "Cancellation after redemption period"
      - `pause` (object)
        Pause schedule parameters.
      - `pause.from_date` (string, required)
        Datetime of the pause start.


   If the subscription pause type value is immediate, the datetime is the date and time of the pause start request.
        Example: "2025-03-27 11:26:08"
      - `pause.to_date` (string)
        Datetime of the pause end.


  It is absent when the subscription is planned to pause infinitely.
        Example: "2025-03-27 11:26:08"
    - redemption:
      - `id` (string, required)
        Unique subscription identifier.
        Example: "9e252e9f-c5a3-4dca-93df-4c9fcf54267e"
      - `status` (string, required)
        Subscription status.
        Example: "redemption"
      - `started_at` (string, required)
        Datetime of the subscription start.
        Example: "2025-12-08 12:37:24"
      - `updated_at` (string, required)
        Datetime of the subscription update.
        Example: "2025-12-08 12:37:25"
      - `expired_at` (string)
        Datetime of the subscription expiration.
        Example: "2025-12-12 12:37:24"
      - `next_charge_at` (string)
        Datetime of the subsequent charge.


  It is absent when the subscription is planned to pause infinitely.
        Example: "2025-12-12 14:37:24"
      - `payment_type` (string, required)
        Customer payment method used to pay for a subscription.
        Enum: same as `payment_type` in "pending" (9 values)
      - `discount` (object)
        Contains information about the discount applied.
      - `discount.created_at` (string, required)
        Datetime of the discount creation.
        Example: "2025-05-31 12:53:12"
      - `discount.coupon_code` (string)
        Coupon code.
        Example: "SUMMER25OFF"
      - `discount.coupon` (object, required)
        Coupon details.
      - `discount.coupon.name` (string, required)
        Coupon name.
        Example: "Summer 25% OFF"
      - `discount.coupon.description` (string)
        Coupon description.
        Example: "25% off for 3 months"
      - `discount.coupon.type` (string, required)
        Discount type indicating percentage or fixed amount off the price.
        Enum: same as `discount.coupon.type` in "pending" (2 values)
      - `discount.coupon.value` (integer, required)
        Discount value.


  Depending on the coupon type, the value represents either a percentage or a fixed amount.
        Example: 25
      - `trial` (boolean, required)
        Indicates whether the subscription has a trial.
      - `trial_started_at` (string)
        Datetime of the subscription trial start.
        Example: "2025-12-08 12:37:24"
      - `trial_ended_at` (string)
        Datetime of the subscription trial expiration.
        Example: "2025-12-08 12:37:25"
      - `cancel_code` (string)
        Reason code that is used to cancel the subscription.
        Enum: same as `cancel_code` in "pending" (15 values)
      - `cancel_message` (string)
        Cancellation reason brief description.
        Example: "Cancellation after redemption period"
      - `pause` (object)
        Pause schedule parameters.
      - `pause.from_date` (string, required)
        Datetime of the pause start.


   If the subscription pause type value is immediate, the datetime is the date and time of the pause start request.
        Example: "2025-03-27 11:26:08"
      - `pause.to_date` (string)
        Datetime of the pause end.


  It is absent when the subscription is planned to pause infinitely.
        Example: "2025-03-27 11:26:08"
    - paused:
      - `id` (string, required)
        Unique subscription identifier.
        Example: "9e252e9f-c5a3-4dca-93df-4c9fcf54267e"
      - `status` (string, required)
        Subscription status.
        Example: "paused"
      - `started_at` (string, required)
        Datetime of the subscription start.
        Example: "2025-12-08 12:37:24"
      - `updated_at` (string, required)
        Datetime of the subscription update.
        Example: "2025-12-08 12:37:25"
      - `expired_at` (string)
        Datetime of the subscription expiration.
        Example: "2025-12-12 12:37:24"
      - `next_charge_at` (string)
        Datetime of the subsequent charge.


  It is absent when the subscription is planned to pause infinitely.
        Example: "2025-12-12 14:37:24"
      - `payment_type` (string, required)
        Customer payment method used to pay for a subscription.
        Enum: same as `payment_type` in "pending" (9 values)
      - `discount` (object)
        Contains information about the discount applied.
      - `discount.created_at` (string, required)
        Datetime of the discount creation.
        Example: "2025-05-31 12:53:12"
      - `discount.coupon_code` (string)
        Coupon code.
        Example: "SUMMER25OFF"
      - `discount.coupon` (object, required)
        Coupon details.
      - `discount.coupon.name` (string, required)
        Coupon name.
        Example: "Summer 25% OFF"
      - `discount.coupon.description` (string)
        Coupon description.
        Example: "25% off for 3 months"
      - `discount.coupon.type` (string, required)
        Discount type indicating percentage or fixed amount off the price.
        Enum: same as `discount.coupon.type` in "pending" (2 values)
      - `discount.coupon.value` (integer, required)
        Discount value.


  Depending on the coupon type, the value represents either a percentage or a fixed amount.
        Example: 25
      - `trial` (boolean, required)
        Indicates whether the subscription has a trial.
      - `trial_started_at` (string)
        Datetime of the subscription trial start.
        Example: "2025-12-08 12:37:24"
      - `trial_ended_at` (string)
        Datetime of the subscription trial expiration.
        Example: "2025-12-08 12:37:25"
      - `cancel_code` (string)
        Reason code that is used to cancel the subscription.
        Enum: same as `cancel_code` in "pending" (15 values)
      - `cancel_message` (string)
        Cancellation reason brief description.
        Example: "Cancellation after redemption period"
      - `pause` (object)
        Pause schedule parameters.
      - `pause.from_date` (string, required)
        Datetime of the pause start.


   If the subscription pause type value is immediate, the datetime is the date and time of the pause start request.
        Example: "2025-03-27 11:26:08"
      - `pause.to_date` (string)
        Datetime of the pause end.


  It is absent when the subscription is planned to pause infinitely.
        Example: "2025-03-27 11:26:08"
    - expired:
      - `id` (string, required)
        Unique subscription identifier.
        Example: "9e252e9f-c5a3-4dca-93df-4c9fcf54267e"
      - `status` (string, required)
        Subscription status.
        Example: "expired"
      - `started_at` (string)
        Datetime of the subscription start.
        Example: "2025-12-08 12:37:24"
      - `updated_at` (string, required)
        Datetime of the subscription update.
        Example: "2025-12-08 12:37:25"
      - `expired_at` (string)
        Datetime of the subscription expiration.
        Example: "2025-12-12 12:37:24"
      - `payment_type` (string)
        Customer payment method used to pay for a subscription.
        Enum: same as `payment_type` in "pending" (9 values)
      - `discount` (object)
        Contains information about the discount applied.
      - `discount.created_at` (string, required)
        Datetime of the discount creation.
        Example: "2025-05-31 12:53:12"
      - `discount.coupon_code` (string)
        Coupon code.
        Example: "SUMMER25OFF"
      - `discount.coupon` (object, required)
        Coupon details.
      - `discount.coupon.name` (string, required)
        Coupon name.
        Example: "Summer 25% OFF"
      - `discount.coupon.description` (string)
        Coupon description.
        Example: "25% off for 3 months"
      - `discount.coupon.type` (string, required)
        Discount type indicating percentage or fixed amount off the price.
        Enum: same as `discount.coupon.type` in "pending" (2 values)
      - `discount.coupon.value` (integer, required)
        Discount value.


  Depending on the coupon type, the value represents either a percentage or a fixed amount.
        Example: 25
      - `trial` (boolean, required)
        Indicates whether the subscription has a trial.
      - `trial_started_at` (string)
        Datetime of the subscription trial start.
        Example: "2025-12-08 12:37:24"
      - `trial_ended_at` (string)
        Datetime of the subscription trial expiration.
        Example: "2025-12-08 12:37:25"
      - `cancelled_at` (string)
        Datetime of subscription cancellation.
        Example: "2025-12-12 19:37:24"
      - `cancellation_requested_at` (string)
        Datetime of subscription cancellation request.
        Example: "2025-12-11 19:37:24"
      - `cancel_code` (string)
        Reason code that is used to cancel the subscription.
        Enum: same as `cancel_code` in "pending" (15 values)
      - `cancel_message` (string)
        Cancellation reason brief description.
        Example: "Cancellation after redemption period"
      - `pause` (object)
        Pause schedule parameters.
      - `pause.from_date` (string, required)
        Datetime of the pause start.


   If the subscription pause type value is immediate, the datetime is the date and time of the pause start request.
        Example: "2025-12-27 11:26:08"
      - `pause.to_date` (string)
        Datetime of the pause end.


  It is absent when the subscription is planned to pause infinitely.
        Example: "2025-12-27 11:26:08"

## Response 400 fields (application/json):

  - `error` (object, required)
    Error object.

  - `error.code` (string, required)
    Error code.
    Example: "2.01"

  - `error.message` (string, required)
    Error message.
    Example: "Validation error"

  - `error.constraints` (object)
    Map of constraints.

## Response 401 fields (application/json):

  - `error` (object, required)
    Error object.

  - `error.code` (string, required)
    Error code indicating the specific authorization failure.
    Example: "1.01"

  - `error.message` (string, required)
    Descriptive message providing more details about the authorization failure.
    Example: "Authorization failed"

## Response 403 fields (application/json):

  - `error` (object, required)
    Error object.

  - `error.code` (string, required)
    Error code indicating that access to the service is denied.
    Example: "1.02"

  - `error.message` (string, required)
    Message informing that the service is not allowed for the account.
    Example: "Access denied"

## Response 422 fields (application/json):

  - `error` (object, required)
    Error object.

  - `error.code` (string, required)
    Error code indicating that while the request is well-formed, it cannot be processed due to conflicting or incorrect data.
    Example: "2.01"

  - `error.message` (string, required)
    Descriptive message providing more details about the processing failure.
    Example: "Unprocessable entity"