Subscription - Retrieve

Retrieve a subscription by its unique identifier.

Endpoint GET /subscriptions/{subscription_id}

Example cURL

curl --request GET \
  --url https://sandbox.hyperswitch.io/subscriptions/{subscription_id} \
  --header 'X-Profile-Id: <x-profile-id>' \
  --header 'api-key: <api-key>'

Response (200 — application/json)

{
  "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>"
  }
}

Hint: Authentication

Use the API key created under your merchant account from the HyperSwitch dashboard. The API key authenticates requests from your merchant server only — do not expose it on a website or embed it in a mobile application.

Headers

• api-key (string, header, required) — API key for merchant server authentication.

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

Path parameters

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

Response: Fields

• id (string, required) — Subscription identifier.

• status (string enum, required) — Subscription lifecycle state. Available options:

  • active

  • created

  • in_active

  • pending

  • trial

  • paused

  • unpaid

  • onetime

  • cancelled

  • failed

• profile_id (string, required) — Business profile id.

• merchant_id (string, required) — Merchant id.

• customer_id (string, required) — Customer id.

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

• plan_id (string | null) — Associated subscription plan id.

• item_price_id (string | null) — Associated item price id.

• client_secret (string | null) — Client token that expires after 15 minutes; used by the client to authenticate and create SDK sessions.

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

• payment (object) — Payment details for the subscription. Includes:

  • payment_id, status, amount, currency, profile_id, connector

  • payment_method_id, return_url, next_action (e.g., redirect_to_url), payment_experience

  • error_code, error_message, payment_method_type, client_secret

  • billing (address, phone, email) — address fields: city, country, line1, line2, line3, zip, state, first_name, last_name, origin_zip

  • shipping (same structure as billing)

  • payment_type, payment_token

• invoice (object) — Invoice details. Includes:

  • id, subscription_id, merchant_id, profile_id, merchant_connector_id, customer_id

  • amount, currency, status (e.g., invoice_created)

  • payment_intent_id, payment_method_id, billing_processor_invoice_id

Notes

• The response payload contains the subscription and nested objects (payment, invoice) returned after successfully retrieving a subscription.

• client_secret fields are short-lived and intended for client-side SDK session creation.