Subscription - Create and Confirm

POST /subscriptions

Create and confirm a subscription. Returns subscription details including payment and invoice information.

cURL

Create and confirm subscription (cURL)
curl --request POST \
  --url https://sandbox.hyperswitch.io/subscriptions \
  --header 'Content-Type: application/json' \
  --header 'X-Profile-Id: <x-profile-id>' \
  --header 'api-key: <api-key>' \
  --data '
{
  "billing": {
    "address": {
      "city": "San Fransico",
      "country": "US",
      "first_name": "joseph",
      "last_name": "Doe",
      "line1": "1467",
      "line2": "Harrison Street",
      "line3": "Harrison Street",
      "state": "California",
      "zip": "94122"
    },
    "phone": {
      "country_code": "+1",
      "number": "123456789"
    }
  },
  "customer_id": "cust_123456789",
  "description": "Hello this is description",
  "item_price_id": "standard-plan-USD-Monthly",
  "merchant_reference_id": "mer_ref_123456789",
  "payment_details": {
    "authentication_type": "no_three_ds",
    "capture_method": "automatic",
    "customer_acceptance": {
      "acceptance_type": "online",
      "accepted_at": "1963-05-03T04:07:52.723Z",
      "online": {
        "ip_address": "127.0.0.1",
        "user_agent": "amet irure esse"
      }
    },
    "payment_method": "card",
    "payment_method_data": {
      "card": {
        "card_cvc": "737",
        "card_exp_month": "03",
        "card_exp_year": "2030",
        "card_holder_name": "CLBRW dffdg",
        "card_number": "4000000000000002"
      }
    },
    "payment_method_type": "credit",
    "payment_type": "setup_mandate",
    "return_url": "https://google.com",
    "setup_future_usage": "off_session"
  },
  "shipping": {
    "address": {
      "city": "Banglore",
      "country": "US",
      "first_name": "joseph",
      "last_name": "doe",
      "line1": "sdsdfsdf",
      "line2": "hsgdbhd",
      "line3": "alsksoe",
      "state": "zsaasdas",
      "zip": "571201"
    },
    "phone": {
      "country_code": "+1",
      "number": "123456789"
    }
  }
}
'

Authorization

api-key (header) — Use the API key created under your merchant account from the HyperSwitch dashboard. API key authenticates API requests from your merchant server only. Do not expose this key on a website or embed it in a mobile application.

Required headers:

  • Content-Type: application/json

  • api-key: string (required)

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

Request body (application/json)

Top-level required fields:

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

  • customer_id (string) — Customer identifier. (required)

  • payment_details (object) — Payment-related information. (required)

Other optional / related fields:

  • plan_id (string | null)

  • coupon_code (string | null)

  • billing (object)

  • shipping (object)

  • merchant_reference_id (string | null)

  • description (string)

The example request body is shown in the cURL section above.

Response

200 application/json — Subscription created and confirmed successfully.

Response fields (summary)

Subscription fields

  • id (string) — Subscription identifier.

  • status (enum) — Subscription lifecycle state. Possible values:

    • active, created, in_active, pending, trial, paused, unpaid, onetime, cancelled, failed

  • profile_id (string) — Business profile id.

  • merchant_id (string) — Merchant id.

  • customer_id (string) — Customer id.

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

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

  • item_price_id (string | null) — Associated item_price id.

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

  • coupon_code (string | null) — Optional coupon code.

Payment object

Includes:

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

  • next_action (object) — e.g. redirect_to_url and URL.

  • payment_experience, error_code, error_message, payment_method_type, client_secret

  • billing (object) and shipping (object) — address, phone, email details.

  • payment_type, payment_token

Invoice object

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

Related

  • Subscription - Confirm: https://api-reference.hyperswitch.io/v1/subscriptions/confirm

  • Subscription - Update: https://api-reference.hyperswitch.io/v1/subscriptions/update

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

PrevioussubscriptionsNextrelay