Create Subscription

Creates a Subscription for a customer and product.

Specify the product with product_id or product_handle. To set a specific product price point, use product_price_point_handle or product_price_point_id.

Identify an existing customer with customer_id or customer_reference. Optionally, include an existing payment profile using payment_profile_id. To create a new customer, pass customer_attributes.

Select an option from the Request Examples drop-down on the right side of the portal to see examples of common scenarios for creating subscriptions.

List vs Sales Pricing

When a subscription uses custom pricing as the sales price, you can optionally provide a list price for any item. If omitted, the list price defaults to the sales price. The difference between the list price and sales price is used to calculate implicit discounts, which appear on Invoices and in reporting. List price can also support revenue allocations in Advanced Revenue.

If your site has list pricing enabled, the API accepts custom_price.list_price_point_id for custom pricing, validates and persists it, and returns list price metadata in subscription responses. If list pricing is disabled, this input is ignored and related response fields are omitted.

When list pricing is enabled:

• Subscription → Product product_price_point_list_price_point_id (integer)
• product_price_point_list_price_point_handle (string)
• Subscription Components (when components are included in the response, such as with subscriptions built from components or component serialization paths) component_id (integer)
• price_point_id (integer)
• list_price_point_id (integer)

When list pricing is disabled:

• Subscription → Product product_price_point_list_price_point_id: omitted
• product_price_point_list_price_point_handle: omitted
• Subscription Components list_price_point_id: omitted

This functionality is supported in the API, but is not currently supported in SDKs.

Subscriptions can now work independently from the catalog

If you have the new Catalog experience enabled, you can create subscriptions without a product_id or product_handle using POST /subscriptions, building them entirely from components.

A valid subscription must include at least one active component with:

• a positive allocated_quantity,
• a positive unit_balance, or
• 'enabled: true' (for on/off components)
• a configured metered component

component_id can be provided as a numeric ID or in handle: format. If trial_interval and trial_interval_unit are included, they are applied at creation.

In the response, product and product price point fields are null, and component details are returned instead.

This functionality is supported in the API, but is not currently supported in SDKs.

Payment information

Payment information may be required to create a subscription, depending on the options for the Product being subscribed. See product options for more information. See the Payments Profile endpoint for details on payment parameters. See the Subscription Signups article for more information on working with subscriptions in Advanced Billing.

Payment information

Payment information may be required to create a subscription, depending on the options for the Product being subscribed. See product options for more information. See the Payments Profile endpoint for details on payment parameters.

Do not use real card information for testing. See the Sites articles that cover testing your site setup for more details on testing in your sandbox.

Note that collecting and sending raw card details in production requires PCI compliance on your end. If your business is not PCI compliant, use Maxio.js (formerly Chargify.js) to collect credit card or bank account information.

3D Secure (3DS) Authentication post-authentication flow

When a payment requires 3DS Authentication to adhere to Strong Customer Authentication (SCA), the request enters a post-authentication flow where a 422 Unprocessable Entity status is returned with an action_link that will direct the customer through 3DS Authentication.

See the 3D Secure Post-Authentication Flow article in the product documentation to learn how to manage the redirect flow.