Skip to main content
POST
/
subscriptions
/
create
Subscription - Create
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"
  }
}'
{
  "id": "<string>",
  "merchant_reference_id": "<string>",
  "status": "active",
  "plan_id": "<string>",
  "item_price_id": "<string>",
  "profile_id": "<string>",
  "client_secret": "<string>",
  "merchant_id": "<string>",
  "coupon_code": "<string>",
  "customer_id": "<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"
  },
  "invoice": {
    "id": "<string>",
    "subscription_id": "<string>",
    "merchant_id": "<string>",
    "profile_id": "<string>",
    "merchant_connector_id": "<string>",
    "payment_intent_id": "<string>",
    "payment_method_id": "pm_01926c58bc6e77c09e809964e72af8c8",
    "customer_id": "<string>",
    "amount": 123,
    "currency": "AED",
    "status": "invoice_created"
  }
}

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
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.

​
item_price_id
string
required

Identifier for the associated item_price_id for the subscription.

​
customer_id
string
required

A type for customer_id that can be used for customer ids

​
payment_details
object
required
​
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
​
shipping
object

Response

Subscription created successfully

Response payload returned after successfully creating a subscription.

Includes details such as subscription ID, status, plan, merchant, and customer info.

​
id
string
required

A type for subscription_id that can be used for subscription ids

​
status
enum<string>
required

Possible states of a subscription lifecycle.

  • Created: Subscription was created but not yet activated.
  • Active: Subscription is currently active.
  • InActive: Subscription is inactive.
  • Pending: Subscription is pending activation.
  • Trial: Subscription is in a trial period.
  • Paused: Subscription is paused.
  • Unpaid: Subscription is unpaid.
  • Onetime: Subscription is a one-time payment.
  • Cancelled: Subscription has been cancelled.
  • Failed: Subscription has failed.
Available options:
active,
created,
in_active,
pending,
trial,
paused,
unpaid,
onetime,
cancelled,
failed
​
profile_id
string
required

A type for profile_id that can be used for business profile ids

​
merchant_id
string
required

A type for merchant_id that can be used for merchant ids

​
customer_id
string
required

A type for customer_id that can be used for customer ids

​
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

This is a 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
​
invoice
object
⌘I