Subscription - Create

Create a subscription.

Example request (cURL)

curl --request POST \
  --url https://sandbox.hyperswitch.io/subscriptions/create \
  --header 'Content-Type: application/json' \
  --header 'X-Profile-Id: <x-profile-id>' \
  --header 'api-key: <api-key>' \
  --data '
{
  "customer_id": "cust_123456789",
  "item_price_id": "standard-plan-USD-Monthly",
  "payment_details": {
    "authentication_type": "no_three_ds",
    "capture_method": "automatic",
    "return_url": "https://google.com",
    "setup_future_usage": "off_session"
  }
}
'

POST /subscriptions/create

Try it

Example response (200)

Authorizations

  • Header: api-key (string, 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, required) — Profile ID for authentication

Body (application/json)

Request payload for creating a subscription. This struct captures details required to create a subscription, including plan, profile, merchant connector, and optional customer info.

Required fields:

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

  • customer_id (string) — A type for customer_id that can be used for customer ids.

  • payment_details (object) — Required. See child attributes in the API reference.

Optional fields:

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

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

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

  • billing (object) — Billing details (child attributes available).

  • shipping (object) — Shipping details (child attributes available).

Response (200 application/json)

Subscription created successfully. Response payload returned after successfully creating a subscription. Includes details such as subscription ID, status, plan, merchant, and customer info.

Top-level response fields:

  • id (string, required) — subscription id

  • 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) — 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) — 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 (child attributes).

  • invoice (object) — Invoice details (child attributes).

For full field definitions and child attributes (payment.billing, payment.shipping, invoice, etc.), refer to the API reference links in the original documentation.

Suggest edits: https://github.com/juspay/hyperswitch/edit/main/api-reference/v1/subscriptions/create.mdx Raise issue: https://github.com/juspay/hyperswitch/issues/new?title=Issue%20on%20docs&body=Path:%20/v1/subscriptions/create

Outgoing webhook schema: https://api-reference.hyperswitch.io/v1/schemas/outgoing--webhook Subscription - Confirm: https://api-reference.hyperswitch.io/v1/subscriptions/confirm

(Responses are generated using AI and may contain mistakes.)

PreviousRouting - Update Default For ProfileNextPayments - Confirm