Create Subscription

Creates a subscription that requires separate confirmation. Use this endpoint when you need to collect payment details from the customer after creating the subscription (e.g. via the SDK). To create and confirm in one step, use Create and Confirm Subscription.

POST /subscriptions/create

Headers

Header	Type	Required	Description
`api-key`	string	Yes	Your secret API key.
`X-Profile-Id`	string	Yes	Profile ID for authentication.

Body Parameters

Parameter	Type	Required	Description
`customer_id`	string	Yes	The unique identifier for the customer.
`item_price_id`	string	Yes	Identifier for the item price to subscribe to (e.g. `standard-plan-USD-Monthly`).
`payment_details`	object	Yes	Payment configuration for the subscription. See Payment Details.
`merchant_reference_id`	string	No	Your own unique identifier for this subscription.
`plan_id`	string	No	Identifier for the subscription plan.
`coupon_code`	string	No	Coupon code to apply to the subscription.
`billing`	object	No	Billing address. See Address.
`shipping`	object	No	Shipping address. See Address.

Payment Details

Parameter	Type	Required	Description
`return_url`	string	Yes	URL to redirect the user to after payment completion.
`authentication_type`	string	No	`three_ds` or `no_three_ds`. Defaults to connector behaviour if omitted.
`capture_method`	string	No	`automatic`, `manual`, `manual_multiple`, `scheduled`, or `sequential_automatic`. Defaults to `automatic`.
`setup_future_usage`	string	No	`off_session` (charge later without customer present) or `on_session`. Defaults to `on_session`.
`payment_type`	string	No	`normal`, `new_mandate`, `setup_mandate`, or `recurring_mandate`. Use `setup_mandate` for zero-auth flows.

Address

Parameter	Type	Required	Description
`address.line1`	string	No	First line of the street address.
`address.line2`	string	No	Second line (apartment, suite, unit, etc.).
`address.line3`	string	No	Third line, if applicable.
`address.city`	string	No	City, district, suburb, town, or village.
`address.state`	string	No	State or region.
`address.zip`	string	No	Postal or ZIP code.
`address.country`	string	No	Two-letter ISO 3166-1 country code (e.g. `US`, `GB`).
`address.first_name`	string	No	First name on the address.
`address.last_name`	string	No	Last name on the address.
`phone.number`	string	No	Contact phone number.
`phone.country_code`	string	No	Phone country code (e.g. `+1`).
`email`	string	No	Email address.

Request Example

curl -X POST 'https://api.sandbox.paychtec.com/subscriptions/create' \
  -H "Content-Type: application/json" \
  -H "api-key: snd_YOUR_API_KEY" \
  -H "X-Profile-Id: prof_12345" \
  -d '{
  "customer_id": "cust_123456789",
  "item_price_id": "standard-plan-USD-Monthly",
  "payment_details": {
    "authentication_type": "no_three_ds",
    "capture_method": "automatic",
    "return_url": "https://yourapp.com/return",
    "setup_future_usage": "off_session"
  }
}'

curl -X POST 'https://api.sandbox.paychtec.com/subscriptions/create' \  -H "Content-Type: application/json" \  -H "api-key: snd_YOUR_API_KEY" \  -H "X-Profile-Id: prof_12345" \  -d '{  "customer_id": "cust_123456789",  "item_price_id": "standard-plan-USD-Monthly",  "payment_details": {    "authentication_type": "no_three_ds",    "capture_method": "automatic",    "return_url": "https://yourapp.com/return",    "setup_future_usage": "off_session"  }}'

Response

{
  "id": "sub_abc123",
  "status": "created",
  "profile_id": "prof_12345",
  "merchant_id": "mer_abc123",
  "customer_id": "cust_123456789",
  "item_price_id": "standard-plan-USD-Monthly",
  "client_secret": "cs_live_...",
  "payment": {
    "payment_id": "pay_xyz789",
    "status": "requires_confirmation",
    "amount": 2900,
    "currency": "USD"
  },
  "invoice": {
    "id": "inv_abc123",
    "subscription_id": "sub_abc123",
    "amount": 2900,
    "currency": "USD",
    "status": "payment_pending"
  }
}

The response includes a client_secret which expires after 15 minutes. Pass this to the SDK or use it to authenticate the subsequent Confirm Subscription call.

Subscription Statuses

Status	Description
`created`	Subscription created but not yet confirmed.
`active`	Subscription is live and billing normally.
`pending`	Awaiting activation.
`trial`	In a free trial period.
`paused`	Temporarily paused.
`unpaid`	Payment failed and subscription is unpaid.
`cancelled`	Subscription has been cancelled.
`failed`	Subscription setup failed.
`in_active`	Subscription is inactive.
`onetime`	One-time payment subscription.

Error Responses

Status Code	Description
`400`	Invalid subscription data — check required fields and payment details.
`404`	Customer or plan not found — verify `customer_id` and `item_price_id`.

On this page