Read Subscription
Retrieves subscription details.
If you have the new Catalog experience 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.
Authorization
BasicAuth The username is a Maxio Chargify API key. The password is x.
In: header
Path Parameters
The Chargify id of the subscription.
Query Parameters
Allows including additional data in the response. Use in query: include[]=coupons&include[]=self_service_page_token.
Response Body
application/json
curl -X GET "https://example.com/subscriptions/0.json"{ "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": null, "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, "net_terms": 0, "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, "stored_credential_transaction_id": 166411599220288, "on_hold_at": null, "scheduled_cancellation_at": "2016-11-14T14:48:13-05:00" }}Create Subscription POST
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](https://docs.maxio.com/hc/en-us/articles/24177001342861-Create-and-Configure-RevenueBooks). 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](https://maxio-test-wp.pages.dev/support/announcements/2026-announcements#new-catalog-experience-and-terminology) 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](https://docs.maxio.com/hc/en-us/articles/24261076617869-Edit-Products) for more information. See the [Payments Profile](https://maxio-test-wp.pages.dev/api/openapi/payment-profiles/createPaymentProfile) endpoint for details on payment parameters. See the [Subscription Signups](https://maxio-test-wp.pages.dev/getting-started/basic-concepts/subscription-signup) 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](https://docs.maxio.com/hc/en-us/articles/24261076617869-Edit-Products) for more information. See the [Payments Profile](https://maxio-test-wp.pages.dev/api/openapi/payment-profiles/createPaymentProfile) endpoint for details on payment parameters. Do not use real card information for testing. See the Sites articles that cover [testing your site setup](https://docs.maxio.com/hc/en-us/articles/24250712113165-Testing-Overview#testing-overview-0-0) for more details on testing in your sandbox. Note that collecting and sending raw card details in production requires [PCI compliance](https://docs.maxio.com/hc/en-us/articles/24183956938381-PCI-Compliance#pci-compliance-0-0) on your end. If your business is not PCI compliant, use [Maxio.js (formerly Chargify.js)](https://docs.maxio.com/hc/en-us/articles/38163190843789-Chargify-js-Overview#chargify-js-overview-0-0) 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](https://docs.maxio.com/hc/en-us/articles/44277749524365-3D-Secure-Post-Authentication-Flow) article in the product documentation to learn how to manage the redirect flow.
Update Subscription PUT
Updates one or more attributes of a subscription. ## Update Subscription Payment Method Change the card that your subscriber uses for their subscription. You can also use this method to change the expiration date of the card **if your gateway allows**. Do not use real card information for testing. See the Sites articles that cover [testing your site setup](https://docs.maxio.com/hc/en-us/articles/24250712113165-Testing-Overview#testing-overview-0-0) for more details on testing in your sandbox. Note that collecting and sending raw card details in production requires [PCI compliance](https://docs.maxio.com/hc/en-us/articles/24183956938381-PCI-Compliance#pci-compliance-0-0) on your end. If your business is not PCI compliant, use [Chargify.js](https://docs.maxio.com/hc/en-us/articles/38163190843789-Chargify-js-Overview#chargify-js-overview-0-0) to collect credit card or bank account information. > Note: Partial card updates for **Authorize.Net** are not allowed via this endpoint. The existing Payment Profile must be directly updated instead. ## Update Product You also use this method to change the subscription to a different product by setting a new value for product_handle. A product change can be done in two different ways, **product change** or **delayed product change**. ### Product Change You can change a subscription's product. The new payment amount is calculated and charged at the normal start of the next period. If you require complex product changes or prorated upgrades and downgrades instead, please see the documentation on [Migrating Subscription Products](https://docs.maxio.com/hc/en-us/articles/24252069837581-Product-Changes-and-Migrations#product-changes-and-migrations-0-0). To perform a product change, set either the `product_handle` or `product_id` attribute to that of a different product from the same site as the subscription. You can also change the price point by passing in either `product_price_point_id` or `product_price_point_handle` - otherwise the new product's default price point is used. ### Delayed Product Change This method also changes the product and/or price point, and the new payment amount is calculated and charged at the normal start of the next period. This method schedules the product change to happen automatically at the subscription’s next renewal date. To perform a delayed product change, set the `product_handle` attribute as you would in a regular product change, but also set the `product_change_delayed` attribute to `true`. No proration applies in this case. You can also perform a delayed change to the price point by passing in either `product_price_point_id` or `product_price_point_handle` > **Note:** To cancel a delayed product change, set `next_product_id` to an empty string. ## Billing Date Changes You can update dates for a subscription. ### Regular Billing Date Changes Send the `next_billing_at` to set the next billing date for the subscription. After that date passes and the subscription is processed, the following billing date will be set according to the subscription's product period. > Note: If you pass an invalid date, the correct date is automatically set to the correct date. For example, if February 30 is passed, the next billing would be set to March 2nd in a non-leap year. The server response will not return data under the key/value pair of `next_billing_at`. View the key/value pair of `current_period_ends_at` to verify that the `next_billing_at` date has been changed successfully. ### Calendar Billing and Snap Day Changes For a subscription using Calendar Billing, setting the next billing date is a bit different. Send the `snap_day` attribute to change the calendar billing date for **a subscription using a product eligible for calendar billing**. > Note: If you change the product associated with a subscription that contains a `snap_day` and immediately READ/GET the subscription data, it will still contain the original `snap_day`. The `snap_day` will be reset to `null` on the next billing cycle. This is because a product change is instantaneous and only affects the product associated with a subscription. 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`.