Subscription - Update

PUT /subscriptions/{subscription_id}/update

Updates an existing subscription's plan or item price.

cURL

curl --request PUT \
  --url https://sandbox.hyperswitch.io/subscriptions/{subscription_id}/update \
  --header 'Content-Type: application/json' \
  --header 'X-Profile-Id: <x-profile-id>' \
  --header 'api-key: <api-key>' \
  --data '
{
  "item_price_id": "cbdemo_enterprise-suite-monthly",
  "plan_id": "cbdemo_enterprise-suite"
}
'

Response: 200 — application/json

Example response (200)

{
  "id": "<string>",
  "status": "active",
  "profile_id": "<string>",
  "merchant_id": "<string>",
  "customer_id": "<string>",
  "merchant_reference_id": "<string>",
  "plan_id": "<string>",
  "item_price_id": "<string>",
  "client_secret": "<string>",
  "coupon_code": "<string>",
  "payment": {
    "payment_id": "<string>",
    "status": "succeeded",
    "amount": 123,
    "currency": "AED",
    "profile_id": "<string>",
    "connector": "<string>",
    "payment_method_id": "pm_01926c58bc6e77c09e809964e72af8c8",
    "return_url": "<string>",
    "next_action": {
      "redirect_to_url": "<string>",
      "type": "redirect_to_url"
    },
    "payment_experience": "redirect_to_url",
    "error_code": "<string>",
    "error_message": "<string>",
    "payment_method_type": "ach",
    "client_secret": "<string>",
    "billing": {
      "address": {
        "city": "New York",
        "country": "AF",
        "line1": "123, King Street",
        "line2": "Powelson Avenue",
        "line3": "Bridgewater",
        "zip": "08807",
        "state": "New York",
        "first_name": "John",
        "last_name": "Doe",
        "origin_zip": "08807"
      },
      "phone": {
        "number": "9123456789",
        "country_code": "+1"
      },
      "email": "<string>"
    },
    "shipping": {
      "address": {
        "city": "New York",
        "country": "AF",
        "line1": "123, King Street",
        "line2": "Powelson Avenue",
        "line3": "Bridgewater",
        "zip": "08807",
        "state": "New York",
        "first_name": "John",
        "last_name": "Doe",
        "origin_zip": "08807"
      },
      "phone": {
        "number": "9123456789",
        "country_code": "+1"
      },
      "email": "<string>"
    },
    "payment_type": "normal",
    "payment_token": "token_sxJdmpUnpNsJk5VWzcjl"
  },
  "invoice": {
    "id": "<string>",
    "subscription_id": "<string>",
    "merchant_id": "<string>",
    "profile_id": "<string>",
    "merchant_connector_id": "<string>",
    "customer_id": "<string>",
    "amount": 123,
    "currency": "AED",
    "status": "invoice_created",
    "payment_intent_id": "<string>",
    "payment_method_id": "pm_01926c58bc6e77c09e809964e72af8c8",
    "billing_processor_invoice_id": "<string>"
  }
}

Authorizations

• api-key (string, header) — required Use the API key created under your merchant account from the HyperSwitch dashboard. API key is used to authenticate API requests from your merchant server only. Don't expose this key on a website or embed it in a mobile application.

Headers

• X-Profile-Id (string, header) — required Profile ID for authentication

• Content-Type: application/json

Path parameters

• subscription_id (string) — required The unique identifier for the subscription

Body (application/json)

• plan_id (string) — required Identifier for the associated plan_id.

• item_price_id (string) — required Identifier for the associated item_price_id for the subscription.

Example request body:

Request body

{
  "item_price_id": "cbdemo_enterprise-suite-monthly",
  "plan_id": "cbdemo_enterprise-suite"
}

Response schema (200)

• id (string) — required Subscription identifier.

• status (enum) — required Possible states of a subscription lifecycle. Available options:

  • active

  • created

  • in_active

  • pending

  • trial

  • paused

  • unpaid

  • onetime

  • cancelled

  • failed

• profile_id (string) — required

• merchant_id (string) — required

• customer_id (string) — required

• merchant_reference_id (string | null) — Merchant specific unique identifier.

• plan_id (string | null) — Identifier for the associated subscription plan.

• item_price_id (string | null) — Identifier for the associated item_price_id for the subscription.

• client_secret (string | null) — Token which expires after 15 minutes, used from the client to authenticate and create sessions from the SDK.

• coupon_code (string | null) — Optional coupon code applied to this subscription.

• payment (object) — Payment details (see example response for fields such as payment_id, status, amount, currency, billing, shipping, next_action, etc.).

• invoice (object) — Invoice details (see example response for fields such as id, amount, currency, status, payment_intent_id, etc.).

---

Suggest edits or raise an issue:

• Edit on GitHub: https://github.com/juspay/hyperswitch/edit/main/api-reference/v1/subscriptions/update.mdx

• Raise issue: https://github.com/juspay/hyperswitch/issues/new?title=Issue%20on%20docs&body=Path:%20/v1/subscriptions/update

Related:

• Subscription — Create and Confirm: https://api-reference.hyperswitch.io/v1/subscriptions/create-and-confirm

• Subscription — Retrieve: https://api-reference.hyperswitch.io/v1/subscriptions/get