Maxio Advanced Billing
HomeSDKsAPI ReferenceContext Plugin
Subscriptions

Preview Subscription

POST
/subscriptions/preview.json

Previews a subscription by POSTing the same JSON or XML as for a subscription creation.

The "Next Billing" amount and "Next Billing" date are represented in each Subscriber's Summary.

This endpoint does not create a subscription; it is meant to serve as a prediction.

For more information, see Subscriber Interface Overview.

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)

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.

Taxable Subscriptions

This endpoint previews taxes applicable to a purchase. For taxes to be previewed, the following conditions must be met:

  • Taxes must be configured on the subscription
  • The preview must be for the purchase of a taxable product or component, or combination of the two.
  • The subscription payload must contain a full billing or shipping address to calculate tax

For more information about creating taxable previews, see Taxes.

You do not need to include a card number to generate tax information when you are previewing a subscription. However, when you actually want to create the subscription, you must include the credit card information if you want the billing address to be stored. The billing address and the credit card information are stored together within the payment profile object. Also, you cannot send a billing address without payment profile information, as the address is stored on the card.

You can pass shipping and billing addresses and still decide not to calculate taxes. To do that, pass skip_billing_manifest_taxes: true attribute.

Non-taxable Subscriptions

If you'd like to calculate subscriptions that do not include tax, you can leave off the billing information.

Authorization

BasicAuth
AuthorizationBasic <token>

The username is a Maxio Chargify API key. The password is x.

In: header

Request Body

application/json

subscription*

Response Body

application/json

curl -X POST "https://example.com/subscriptions/preview.json" \  -H "Content-Type: application/json" \  -d '{    "subscription": {      "product_handle": "gold-product"    }  }'
{  "subscription_preview": {    "current_billing_manifest": {      "line_items": [        {          "transaction_type": "charge",          "kind": "baseline",          "amount_in_cents": 5000,          "memo": "Gold Product (08/21/2018 - 09/21/2018)",          "discount_amount_in_cents": 0,          "taxable_amount_in_cents": 0,          "product_id": 1,          "product_handle": "gold-product",          "product_name": "Gold Product",          "period_range_start": "13 Oct 2023",          "period_range_end": "13 Nov 2023"        },        {          "transaction_type": "charge",          "kind": "component",          "amount_in_cents": 28000,          "memo": "Component name: 14 Unit names",          "discount_amount_in_cents": 0,          "taxable_amount_in_cents": 0,          "component_id": 462149,          "component_handle": "handle",          "component_name": "Component name"        },        {          "transaction_type": "charge",          "kind": "component",          "amount_in_cents": 2000,          "memo": "Fractional Metered Components: 20.0 Fractional Metereds",          "discount_amount_in_cents": 0,          "taxable_amount_in_cents": 0,          "component_id": 426665,          "component_handle": "handle",          "component_name": "Fractional Metered Components"        },        {          "transaction_type": "charge",          "kind": "component",          "amount_in_cents": 0,          "memo": "On/Off Component",          "discount_amount_in_cents": 0,          "taxable_amount_in_cents": 0,          "component_id": 426670,          "component_handle": "handle",          "component_name": "On/Off Component"        },        {          "transaction_type": "adjustment",          "kind": "coupon",          "amount_in_cents": 0,          "memo": "Coupon: 1DOLLAR - You only get $1.00 off",          "discount_amount_in_cents": 0,          "taxable_amount_in_cents": 0        }      ],      "total_in_cents": 35000,      "total_discount_in_cents": 0,      "total_tax_in_cents": 0,      "subtotal_in_cents": 35000,      "start_date": "2018-08-21T21:25:21Z",      "end_date": "2018-09-21T21:25:21Z",      "period_type": "recurring",      "existing_balance_in_cents": 0    },    "next_billing_manifest": {      "line_items": [        {          "transaction_type": "charge",          "kind": "baseline",          "amount_in_cents": 5000,          "memo": "Gold Product (09/21/2018 - 10/21/2018)",          "discount_amount_in_cents": 0,          "taxable_amount_in_cents": 0,          "product_id": 1,          "product_handle": "gold-product",          "product_name": "Gold Product"        },        {          "transaction_type": "charge",          "kind": "component",          "amount_in_cents": 28000,          "memo": "Component name: 14 Unit names",          "discount_amount_in_cents": 0,          "taxable_amount_in_cents": 0,          "component_id": 462149,          "component_handle": "handle",          "component_name": "Component name"        },        {          "transaction_type": "charge",          "kind": "component",          "amount_in_cents": 0,          "memo": "On/Off Component",          "discount_amount_in_cents": 0,          "taxable_amount_in_cents": 0,          "component_id": 426670,          "component_handle": "handle",          "component_name": "On/Off Component"        }      ],      "total_in_cents": 33000,      "total_discount_in_cents": 0,      "total_tax_in_cents": 0,      "subtotal_in_cents": 33000,      "start_date": "2018-09-21T21:25:21Z",      "end_date": "2018-10-21T21:25:21Z",      "period_type": "recurring",      "existing_balance_in_cents": 0    }  }}

Update Prepaid Subscription Configuration POST

Updates a subscription's prepaid configuration.

Apply Coupons to Subscription POST

Applies one or more coupon codes to an existing subscription. An existing subscription can accommodate multiple discounts/coupon codes. This is only applicable if each coupon is stackable. For more information on stackable coupons, we recommend reviewing our [coupon documentation.](https://maxio.zendesk.com/hc/en-us/articles/24261259337101-Coupons-and-Subscriptions#stackability-rules) ## Query Parameters vs Request Body Parameters Passing in a coupon code as a query parameter will add the code to the subscription, completely replacing all existing coupon codes on the subscription. For this reason, using this query parameter on this endpoint has been deprecated in favor of using the request body parameters as described below. When passing in request body parameters, the list of coupon codes will simply be added to any existing list of codes on the subscription.