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.
Authorization
BasicAuth The username is a Maxio Chargify API key. The password is x.
In: header
Request Body
application/json
Response Body
application/json
application/json
curl -X POST "https://example.com/subscriptions.json" \ -H "Content-Type: application/json" \ -d '{ "subscription": { "product_handle": "basic", "customer_attributes": { "first_name": "Joe", "last_name": "Smith", "email": "joe@example.com", "zip": "02120", "state": "MA", "reference": "XYZ", "phone": "(617) 111 - 0000", "organization": "Acme", "country": "US", "city": "Boston", "address_2": null, "address": "123 Mass Ave." }, "payment_collection_method": "remittance" } }'{ "subscription": { "id": 15236915, "state": "active", "balance_in_cents": 0, "total_revenue_in_cents": 14000, "product_price_in_cents": 1000, "product_version_number": 7, "current_period_ends_at": "2016-11-15T14:48:10-05:00", "next_assessment_at": "2016-11-15T14:48:10-05:00", "trial_started_at": null, "trial_ended_at": null, "activated_at": "2016-11-14T14:48:12-05:00", "expires_at": null, "created_at": "2016-11-14T14:48:10-05:00", "updated_at": "2016-11-14T15:24:41-05:00", "cancellation_message": null, "cancellation_method": "merchant_api", "cancel_at_end_of_period": null, "canceled_at": null, "current_period_started_at": "2016-11-14T14:48:10-05:00", "previous_state": "active", "signup_payment_id": 162269766, "signup_revenue": "260.00", "delayed_cancel_at": null, "coupon_code": "5SNN6HFK3GBH", "payment_collection_method": "automatic", "snap_day": null, "reason_code": null, "receives_invoice_emails": false, "customer": { "first_name": "Curtis", "last_name": "Test", "email": "curtis@example.com", "cc_emails": "jeff@example.com", "organization": "", "reference": null, "id": 14714298, "created_at": "2016-11-14T14:48:10-05:00", "updated_at": "2016-11-14T14:48:13-05:00", "address": "123 Anywhere Street", "address_2": "", "city": "Boulder", "state": "CO", "zip": "80302", "country": "US", "phone": "", "verified": false, "portal_customer_created_at": "2016-11-14T14:48:13-05:00", "portal_invite_last_sent_at": "2016-11-14T14:48:13-05:00", "portal_invite_last_accepted_at": null, "tax_exempt": false, "vat_number": "012345678" }, "product": { "id": 3792003, "name": "$10 Basic Plan", "handle": "basic", "description": "lorem ipsum", "accounting_code": "basic", "price_in_cents": 1000, "interval": 1, "interval_unit": "day", "initial_charge_in_cents": null, "expiration_interval": null, "expiration_interval_unit": "never", "trial_price_in_cents": null, "trial_interval": null, "trial_interval_unit": "month", "initial_charge_after_trial": false, "return_params": "", "request_credit_card": false, "require_credit_card": false, "created_at": "2016-03-24T13:38:39-04:00", "updated_at": "2016-11-03T13:03:05-04:00", "archived_at": null, "update_return_url": "", "update_return_params": "", "product_family": { "id": 527890, "name": "Acme Projects", "handle": "billing-plans", "accounting_code": null, "description": "" }, "public_signup_pages": [ { "id": 281054, "url": "https://general-goods.chargify.com/subscribe/kqvmfrbgd89q/basic" }, { "id": 281240, "url": "https://general-goods.chargify.com/subscribe/dkffht5dxfd8/basic" }, { "id": 282694, "url": "https://general-goods.chargify.com/subscribe/jwffwgdd95s8/basic" } ], "taxable": false, "version_number": 7, "product_price_point_name": "Default" }, "credit_card": { "id": 10191713, "payment_type": "credit_card", "first_name": "Curtis", "last_name": "Test", "masked_card_number": "XXXX-XXXX-XXXX-1", "card_type": "bogus", "expiration_month": 1, "expiration_year": 2026, "billing_address": "123 Anywhere Street", "billing_address_2": "", "billing_city": "Boulder", "billing_state": null, "billing_country": "", "billing_zip": "80302", "current_vault": "bogus", "vault_token": "1", "customer_vault_token": null, "customer_id": 14714298 }, "payment_type": "credit_card", "referral_code": "w7kjc9", "next_product_id": null, "coupon_use_count": 1, "coupon_uses_allowed": 1, "next_product_handle": null, "stored_credential_transaction_id": 125566112256688, "dunning_communication_delay_enabled": true, "dunning_communication_delay_time_zone": "Eastern Time (US & Canada)" }}List Subscriptions GET
Lists subscriptions for a site. Use the query string filters and pagination to control responses from the server. If you have the new [Catalog experience](https://maxio-test-wp.pages.dev/support/announcements/2026-announcements#new-catalog-experience-and-terminology) enabled, some subscriptions may not have an associated product. For subscriptions without an associated product, 'product', 'product_price_point_id', and 'product_price_point_type' are returned as 'null'. ## Search for a subscription Use the query strings below to search for a subscription using the criteria available. The return value will be an array. ## Self-Service Page token Self-Service Page token for the subscriptions is not returned by default. If this information is desired, the include[]=self_service_page_token parameter must be provided with the request.
Read Subscription GET
Retrieves subscription details. If you have the new [Catalog experience](https://maxio-test-wp.pages.dev/support/announcements/2026-announcements#new-catalog-experience-and-terminology) enabled, some subscriptions may not have an associated product. For subscriptions without an associated product, 'product', 'product_price_point_id', and 'product_price_point_type' are returned as 'null'. ## Self-Service Page token Self-Service Page token for the subscription is not returned by default. If this information is desired, the include[]=self_service_page_token parameter must be provided with the request.