B2B Billing, Redefined: Developer Resources at Your
FingertipsWelcome to the Maxio Developer Portal – an easy access to our API
endpoints, documentation, and more! Find all the tools you need to
build, test, and launch a world-class billing experience.
Maxio will use commercially reasonable efforts to ensure that the
Services will be available 99.6% of the time each month other than
during scheduled maintenance.
Which methodologies are used to monitor API usage and limits?
Our API limits are described
here.
We log all incoming traffic, and have alerts when the limits are
triggered too often. We use one of the best-in-class APM tools to
monitor app performance.
How many API calls do your largest customers make per day?
1st largest customer: 2.5M
2nd largest customer: 1.2M
3rd largest customer: 1M
4th largest customer: 1M
5th largest customer: 900K
### How to Get Started
Source: https://developers.maxio.com/http/getting-started/how-to-get-started
# Introduction
Maxio Advanced Billing (formerly Chargify) provides an HTTP-based API that conforms to the principles of REST.
One of the many reasons to use Advanced Billing is the immense feature set and [client libraries](https://developers.maxio.com/http/development-tools/using-the-developer-portal).
The Maxio API returns JSON responses as the primary and recommended format, but XML is also provided as a backwards compatible option for merchants who require it.
## Steps to make your first Maxio Advanced Billing API call
1. [Sign-up](https://app.chargify.com/signup/maxio-billing-sandbox) or [log-in](https://app.chargify.com/login.html) to your [test site](https://maxio.zendesk.com/hc/en-us/articles/24250712113165-Testing-Overview) account.
2. [Setup authentication](https://maxio.zendesk.com/hc/en-us/articles/24294819360525-API-Keys) credentials.
3. [Submit an API request and verify the response](https://developers.maxio.com/http/development-tools/using-the-developer-portal#make-your-first-maxio-advanced-billing-api-request).
4. Test the Advanced Billing [integrations](https://www.maxio.com/integrations).
Next, you can explore [authentication methods](https://developers.maxio.com/http/getting-started/authentication), [basic concepts](https://developers.maxio.com/http/getting-started/advanced-billing-concepts/sites) for interacting with Advanced Billing via the API, and the entire set of [application-based documentation](https://docs.maxio.com/hc/en-us) to aid in your discovery of the product.
### Request Example
The following example uses the curl command-line tool to make an API request.
**Request**
curl -u :x -H Accept:application/json -H Content-Type:application/json https://acme.chargify.com/subscriptions.json
# Environments
This API has support for the following environment(s). Each environment has one or more base URIs defined.
## US
Default Advanced Billing environment hosted in US. Valid for the majority of our customers.
| Server | Base URI |
| --- | --- |
| production | `https://{site}.chargify.com` |
| ebb | `https://events.chargify.com/{site}` |
## EU
Advanced Billing environment hosted in EU. Use only when you requested EU hosting for your AB account.
| Server | Base URI |
| --- | --- |
| production | `https://{site}.ebilling.maxio.com` |
| ebb | `https://events.chargify.com/{site}` |
The default environment is **US** and the default server is **production**.
## Template Parameters in Base URI
Some of the base URI have template parameters.
| Name | Type | Description |
| --- | --- | --- |
| site | `String` | The subdomain for your Advanced Billing site. *Default: subdomain* |
# Authorization
This API uses the following authentication schemes.
* [`BasicAuth (Basic Authentication)`](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
## BasicAuth (Basic Authentication)
HTTP Basic Authentication will need client credentials.
The client credentials are concatenated with a colon (:) and base64-encoded before being sent in the *Authorization* header.
```bash
curl {BASEURI} -u '{BASIC_AUTH_USER_NAME}:{BASIC_AUTH_PASSWORD}'
```
```http
GET / HTTP/1.1
Host: {HOST}
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
```
### Authentication
Source: https://developers.maxio.com/http/getting-started/authentication
# Authentication
Learn how to use API authentication to communicate directly with Advanced Billing from any programming language that you wish.
---
There are two methods of authentication, depending on what you are accessing:
- [Maxio API](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscriptions/create-subscription)
- [Maxio.js (formerly Chargify.js)](https://docs.maxio.com/hc/en-us/articles/38163190843789-Chargify-js-Overview)
Both methods of authentication assume you have previously generated API keys and securely stored them for later use. For more information, see this help article on [Advanced Billing API Keys](https://maxio.zendesk.com/hc/en-us/articles/24294819360525-API-Keys).
## API
The first method of interaction is through the API. API Authentication is implemented as HTTP Basic Authentication over TLS (HTTPS).
Your API login credentials are not the same as the credentials you use to log in to the web interface. You must obtain your API credentials separately, and you must connect to the API via TLS 1.2 (or better).
> Advanced Billing no longer supports TLS 1.0 or TLS 1.1 over HTTPS on the chargify.com domain. Any older browsers or API clients that do not support TLS 1.2 will no longer work. This change is mandated by the PCI Security Council and affects all merchants and service providers processing or transmitting credit card data. For more information, see our help article on [Security](https://maxio.zendesk.com/hc/en-us/articles/24183963101069-Security).
One of the most common calls you will make via the API is to retrieve a list of subscriptions to retrieve additional information, such as the status of a specific subscription. A simple way to authenticate is to use the API Key as the _username_ and "X" as the _password_, like the following:
```
curl https://{subdomain}.chargify.com/subscriptions.{format} \
-u '{API_key}:X' \
-H 'content-type: application/json' \
-X GET
```
If passing the Basic Authentication header, the API key and password require base64 encoding:
```
curl --request GET \
--url 'https:///{subdomain}.chargify.com/subscriptions.{format}' \
--header 'authorization: Basic PDxhcGlfa2V5Pj46...' \
--header 'content-type: application/json'
```
> ❗️ The API is case-sensitive.
---
# What's next?
After completing authentication setup, review the following articles:
- Managing [sites](https://developers.maxio.com/http/getting-started/advanced-billing-concepts/sites)
- Creating [products](https://developers.maxio.com/http/getting-started/advanced-billing-concepts/product-catalog#product) and how they control what you bill customers
- Creating [subscriptions](https://developers.maxio.com/http/getting-started/advanced-billing-concepts/subscription-signup) (i.e., signing up customers)
### Advanced Billing Concepts
#### Sites
Source: https://developers.maxio.com/http/getting-started/advanced-billing-concepts/sites
# Site Subdomains
Learn how to use sites to organize your business and configure access for API calls.
---
Your first site is created automatically after you choose a currency. Sites are simply "containers" for your products, customers, and subscriptions. A single site is sufficient for some use cases, though most merchants use at least two — one for **testing** and one for **production.**
## Site Access
[Log in to manage your sites](https://app.chargify.com/login). You have the following options for managing sites:
- Creating a new site
- Viewing a site dashboard
- Cloning a site (i.e., making a copy of the site structure, including products, components, families, etc.)
- Editing a site (currency, name, date/time format, timezone, etc)
- Deleting a site
To begin, create a site (make sure to put it in test mode) and pick a subdomain that you will remember for use in your API calls.
For more information about sites, including: switching sites, clearing site data, cloning - see the [Sites](https://maxio.zendesk.com/hc/en-us/articles/24250614702221-Sites-Overview) help article.
## Site API Subdomain
Every site has the ability to have one or more API keys associated with it to allow API access. The subdomain name is used in API calls to direct what site should be used in the context of the API call.
For example, if you have a site called "Acme, Inc." with the subdomain "acme," you would use a call similar to:
```perl
curl -u :X -H Accept:application/json -X GET https://acme.chargify.com/subscriptions.json
```
The host is always in the form `https://.chargify.com` followed by the URI for the API resource you are trying to access. In this last example, that would be `/subscriptions.json` as that is the URI of the resource to get a list of subscriptions in JSON.
## Clearing Site Data
Clearing your site data is very useful in specific circumstances:
- When in **development/test**, clearing your site data allows you to remove records that you added in for testing.
- When moving to **production/live mode**, clearing your site data is necessary for allowing your gateway to actually process real money.
Clearing your site data can be done in the following methods:
1. Clearing site data via the website.
2. Clearing site data via the API.
### Clearing via Website
To clear your site data via the website, see the [Clearing Site Data](https://maxio.zendesk.com/hc/en-us/articles/24250617028365-Clearing-Site-Data) help article.
### Clearing via API
There are a few options for clearing your site data, which match the settings available if you perform this action through the website. The most basic is clearing _all your data_:
```perl
curl -u :X -H Accept:application/json -X POST https://acme.chargify.com/sites/clear_data.json
```
For more information about the parameters for clearing your site data using the API, see [Clear Site](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/sites/clear-site).
---
# What's next?
After you've created a new site, you should check out the following articles:
- [Products](https://developers.maxio.com/http/getting-started/advanced-billing-concepts/product-catalog#product)
- [Subscriptions](https://developers.maxio.com/http/getting-started/advanced-billing-concepts/subscription-signup)
#### Product Catalog
Source: https://developers.maxio.com/http/getting-started/advanced-billing-concepts/product-catalog
Learn how to setup products and components for use when creating subscriptions.
Products control what is charged and how often charges are assessed/billed to a subscription. If you need help after reading this, [let us know](https://developers.maxio.com/http/help/getting-support) so we can help and also improve this documentation.
---
With regards to products, there are three important aspects that are required for using products when interacting with the API:
- Creating the [product family](https://developers.maxio.com/http/getting-started/advanced-billing-concepts/product-catalog#product-family)
- Creating the [product](https://developers.maxio.com/http/getting-started/advanced-billing-concepts/product-catalog#product)
Before delving into this section, we recommend reviewing our [Products Introduction](https://maxio.zendesk.com/hc/en-us/articles/24261090117645-Products-Overview) help article.
# Product Family
Products have to belong to a product family. Think of them as a logical grouping of products. In our Acme, Inc. example - one possible product family would be "Acme Projects".
To create a product family using the API you need to do the following:
Input attributes:
- `name` (required) - The product family name. For example, if your app had two levels of service, "Basic" and "Premium" then these might be the product names.
- `handle` (optional) - The handle of the product family. This is generated automatically if not specified.
- `description` (optional) - A quick description of what the product family is.
An example of our input attributes might look like the following:
```json
// product_family.json
{
"product_family": {
"name": "Acme Projects",
"description": "Amazing project management tool"
}
}
```
That data should be posted to the [Create Product Family](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/product-families/create-product-family) endpoint.
A simple curl example would be the following:
```perl
curl -u :X -H Accept:application/json -d @product_family.json -X POST https://.chargify.com/product_families.json
```
To create a product family using the application, refer to the [Creating Product Families](https://maxio.zendesk.com/hc/en-us/articles/24261098936205-Product-Families) help article for more information.
See [Create Product Family](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/product-families/create-product-family) for a complete listing of input/output schema, along with code examples in multiple programming languages.
# Product
In Advanced Billing, you sell Subscriptions to your Products. You must first create and configure a Product before you can sell anything to a Customer.
In your app or business, you might call these products your “Plans” or “Feature Levels”. For example, if you have “Basic”, “Pro”, and “Max” plans, each of these would be a separate Product within Advanced Billing.
You can create a product using the Create Product endpoint:
```json
{
"product": {
"name": "Basic Plan",
"handle": "basic",
"description": "This is our basic plan.",
"accounting_code": "123",
"request_credit_card": true,
"price_in_cents": 1000,
"interval": 1,
"interval_unit": "month",
"auto_create_signup_page": true
}
}
```
That data is posted to the [Create Product](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/products/create-product) endpoint.
# Product Price Points
Product price points allow you to charge customers different amounts and at different frequencies for the same product.
See the [Product Price Points](https://maxio.zendesk.com/hc/en-us/articles/24261111947789-Product-Price-Points) help article.
# Components
Components are a great way to customize how your customers can use your products or services, and provide an excellent mechanism for increasing the [MRR](https://www.maxio.com/saaspedia#saaspedia_mrr-articles) per subscription through new features you might develop.
---
Components allow you to introduce additional line items to your products that are often expressed as add-ons, premium features, or pay-per-use items. There are two basic concepts needed to use components that we will discuss:
1. [Creating](https://developers.maxio.com/http/getting-started/advanced-billing-concepts/product-catalog#creating-components) components
2. The [usage/allocation](https://developers.maxio.com/http/getting-started/advanced-billing-concepts/product-catalog#usage-allocation) of components
For more information about components, see our [Component](https://maxio.zendesk.com/hc/en-us/articles/24261141522189-Components-Overview) help article.
## Creating Components
To use components, you must first create them. You can do this in a number of ways: by creating them via the Advanced Billing user interface, or by creating them via the API. In the following example, let's create a component called "Text Messages" that costs $0.0075 per message:
```json
{
"metered_component": {
"name": "Text messages",
"unit_name": "text message",
"taxable": true,
"pricing_scheme": "per_unit",
"unit_price": 0.0075
}
}
```
The response for the creation of this component would provide you the ID necessary to use the component in all further subsequent API usage requests.
If you need to display component pricing to your customers, we recommend caching this information in your application rather than making repeated API calls for it, since the pricing structure of a component does not usually change very often.
For more information on components, see the following:
- About [Components](https://maxio.zendesk.com/hc/en-us/articles/24261141522189-Components-Overview) help article
- Creating components [via the API](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/components/create-metered-component)
## Usage/Allocation
Associating components with a subscription is done by allocating (or adding usage, depending on the type of component).
- For metered components which reset to zero at each billing period, you would be adding "usage". For example, if your customer sent 10 text messages today, you would add usage for 10 units of the "text message" component (see above).
- For quantity components, you would be "allocating" use. For example, if you had a component that represented the number of seats covered under their license, you would allocate that amount: i.e., the customer is allocated 10 seats covered by their license to use your software.
- For "on/off" components, you would be turning them on or off. For example, let's say your customer could have "premium support" for an extra $25/month. That component, "premium support" could be turned on or off at will during the life time of the subscription - including prorating it during changes to the subscription plan.
The following is an example that adds 5 text messages as "usage":
```json
{
"usage": {
"quantity": 5,
"memo": "Extra text messages"
}
}
```
Components can be used in a huge number of varying ways to cover your business model - it's just up to you on how you want it to work.
## Coupons
Are you looking to offer current or potential customers a discount? Advanced Billing handles all of your promotional codes, discounts, and coupons with ease. Simply name the promotion, set your desired promo code, and enter the discount. You even have the power to control the expiration date and how long the promotion runs for in conjunction with your products.
Let's create a coupon that we can then use when creating our next subscription.
```json
// POST /coupons.json
{
"coupon": {
"name": "15% off",
"code": "15OFF",
"description": "15% off for life",
"percentage": "15",
"allow_negative_balance": "false",
"recurring": "false",
"end_date": "2012-08-29T12:00:00-04:00",
"product_family_id": "2"
}
}
```
For more information on coupons, see the following:
- Create a coupon [via the API](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/coupons/create-coupon).
- Use a coupon when creating a new subscription [via the API](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscriptions/create-subscription).
#### Hybrid Pricing
Source: https://developers.maxio.com/http/getting-started/advanced-billing-concepts/hybrid-pricing
Hybrid Pricing lets a single Component bill a primary tiered, volume, or stairstep pricing model together with a secondary pricing model for usage above an included threshold, as a single invoice line item.
---
# How it works
Hybrid Pricing combines a Component's primary pricing model with a secondary pricing model, and bills both together as one invoice line item instead of multiple. The primary model covers usage up to an included threshold, and the secondary model takes over for usage beyond that threshold.
# Requirements
Hybrid Pricing only applies when all of the following are true for a given Price Point:
| Requirement | Details |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Site feature | Hybrid Pricing must be enabled for the Site, and requires Invoice-Centric Billing to also be enabled. This is not a self-service toggle. Contact your Maxio account team to enable it. |
| Component type | Only Quantity-Based and Metered Components support Hybrid Pricing. Metered Components configured for event-based billing (metric, meter, or formula) are not eligible. |
| Primary pricing model | Must be `volume`, `tiered`, or `stairstep`. `per_unit` cannot be the primary model. |
| Primary pricing brackets | The primary model's highest bracket must have a finite `ending_quantity` (the included threshold). An open-ended top bracket disqualifies the Price Point from Hybrid Pricing. |
| Secondary pricing model | A secondary pricing model must be configured on the Price Point (the `overage_pricing_scheme` and `overage_pricing` parameters). |
There is no explicit `hybrid` flag anywhere in the API. A Price Point becomes a hybrid Price Point automatically once the requirements above are satisfied. Configure it the same way you would configure any Component with a secondary pricing model.
# Configuring Hybrid Pricing via the API
Hybrid Pricing is configured through the existing Components and Price Points endpoints. There is no dedicated Hybrid Pricing endpoint or parameter.
## Creating the Component
Create a Quantity-Based or Metered Component with a bracketed primary `pricing_scheme` and a secondary pricing block (the `overage_pricing` parameter):
```json
// POST /product_families/{product_family_id}/quantity_based_components.json
{
"quantity_based_component": {
"name": "Seats",
"unit_name": "seat",
"pricing_scheme": "stairstep",
"prices": [
{ "starting_quantity": 1, "ending_quantity": 10, "unit_price": 500 }
],
"overage_pricing": {
"pricing_scheme": "per_unit",
"prices": [{ "starting_quantity": 1, "unit_price": 8 }]
}
}
}
```
This creates a Component whose default Price Point charges a flat $500 for up to 10 seats, then $8 per seat beyond that. Post this to the [Create Quantity Based Component](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/components/create-quantity-based-component) endpoint. Since the site has Hybrid Pricing enabled and the primary model (`stairstep`) has a finite included threshold, this Price Point is a hybrid Price Point.
`overage_pricing.prices` is its own self-contained bracket set: `starting_quantity` always starts at `1`, not at the primary model's `ending_quantity`. The secondary model still only takes effect once usage crosses the primary model's included threshold.
## Adding or updating a Price Point
The same secondary pricing structure (the `overage_pricing` parameter) applies when creating or updating additional Price Points on an existing Component:
```json
// POST /components/{component_id}/price_points.json
{
"price_point": {
"name": "Enterprise",
"pricing_scheme": "tiered",
"prices": [
{ "starting_quantity": 1, "ending_quantity": 50, "unit_price": 4 }
],
"overage_pricing_scheme": "per_unit",
"overage_pricing": {
"prices": [{ "starting_quantity": 1, "unit_price": 2 }]
}
}
}
```
See [Create Component Price Point](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/component-price-points/create-component-price-point) and [Update Component Price Point](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/component-price-points/update-component-price-point) for the complete input/output schema.
## Common validation errors
| Error | Cause |
| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Pricing scheme cannot be per_unit for hybrid pricing` | The primary `pricing_scheme` was set to `per_unit` while a secondary pricing model was also configured on a hybrid-eligible Component. Use `volume`, `tiered`, or `stairstep` for the primary model instead. |
| `Prices primary pricing must have a finite included threshold for hybrid pricing` | The primary model's highest bracket did not specify an `ending_quantity`. Add one to define where the secondary model takes over. |
`overage_pricing_scheme` is required for Hybrid Pricing to take effect, but omitting it does not raise a validation error: the entire `overage_pricing` block is silently ignored and the Price Point is created as a normal, non-hybrid Price Point using only the primary pricing. Always confirm `overage_pricing_scheme` is present in your request when you expect a Price Point to be hybrid.
# Invoicing
Hybrid Price Points bill through the same Invoices you already use. No separate resource is introduced. The customer sees one line item per billing period for the Component, combining the primary and secondary charges instead of billing them as separate line items.
# Best Practices
- **Confirm Invoice-Centric Billing and the Hybrid Pricing feature are both enabled for the Site** before configuring a hybrid Price Point. Otherwise the Price Point falls back to billing the primary and secondary pricing as separate invoice line items, even with an identical `overage_pricing` configuration.
- **Always set a finite `ending_quantity`** on the primary model's top bracket to indicate where the primary model ends and the secondary model begins.
- **Cache pricing structure in your application** rather than re-fetching it on every request, consistent with our general guidance for [Components](https://developers.maxio.com/http/getting-started/advanced-billing-concepts/product-catalog#components).
#### Subscription Signup
Source: https://developers.maxio.com/http/getting-started/advanced-billing-concepts/subscription-signup
You can create signups (also called subscriptions) by signing up customers to products on your site.
This guide focuses on the basics of creating subscriptions, though Advanced Billing can almost handle any scenario using API integration.
- Advanced Billing [signup methods](https://developers.maxio.com/http/getting-started/advanced-billing-concepts/subscription-signup#signup-methods)
- The [payment methods](https://developers.maxio.com/http/getting-started/advanced-billing-concepts/subscription-signup#payment-methods) available for subscriptions
- How to handle customers with [multiple subscriptions](https://developers.maxio.com/http/getting-started/advanced-billing-concepts/subscription-signup#multiple-subscriptions)
- Component [quantities](https://developers.maxio.com/http/getting-started/advanced-billing-concepts/subscription-signup#components) and how they can be used to customize billing
---
You can review our product documentation for more details:
- [Subscriptions Reference](https://maxio.zendesk.com/hc/en-us/articles/24251526991757-Subscription-Overview)
- [Subscriptions Actions](https://maxio.zendesk.com/hc/en-us/articles/24251983024653-Subscription-Actions-Overview)
- [Subscription Cancellation](https://maxio.zendesk.com/hc/en-us/articles/24251957778829-Cancel-Subscriptions)
- [Subscription Reactivation](https://maxio.zendesk.com/hc/en-us/articles/24252109503629-Reactivating-and-Resuming)
- [Subscription Import](https://maxio.zendesk.com/hc/en-us/articles/24251489107213-Imports)
- [Product Options](https://maxio.zendesk.com/hc/en-us/articles/24261076617869-Product-Editing).
# Signup Methods
There are a number of methods of actually signing up customers to your business. Explore the following help articles and see how they might be used in your business:
- [Manually (within Advanced Billing)](https://maxio.zendesk.com/hc/en-us/articles/24181202779149-Create-Subscriptions-Inside-Advanced-Billing)
- [With Public Signup Pages (PSP)](https://maxio.zendesk.com/hc/en-us/articles/24181172242957-Accept-Signups-with-Public-Signup-Pages?method=themes)
- [Via the API](https://developers.maxio.com/http/getting-started/advanced-billing-concepts/subscription-signup#api)
## Manually (within Advanced Billing)
The easiest way to create simple subscriptions is directly within your Advanced Billing account. Before you begin, ensure that you have at least one Product available for use in the example below. For step-by-step instructions, see the [Create Subscriptions Inside Advanced Billing quick start guide](https://maxio.zendesk.com/hc/en-us/articles/24181202779149-Create-Subscriptions-Inside-Advanced-Billing).
This sign-up method is ideal for businesses with a low volume of subscriptions. It is the fastest way to get started, as it requires no integration.
While this method is simple and effective for initial setup, manually signing up customers is not scalable. Fortunately, there are more robust solutions available to automate and streamline the process.
## Public Signup Pages (PSP)
Public Signup Pages are fully customizable, white-labeled pages that serve as the public-facing side of your subscription business. They provide a fast, code-free way to integrate with Advanced Billing without handling payment information or building a custom integration.
All Advanced Billing plans include access to two types of Public Signup Pages:
1. A Public Signup Page is automatically created for each new product and allows people to sign up for any of your current active products.
2. A [Self-Service Page](https://maxio.zendesk.com/hc/en-us/articles/24261425318541-Self-Service-Pages#example-self-service-page) is automatically created for each active subscription and allows the customer to manage payment methods.
For details on configuring the appearance and behavior of your Public Page, see [Public Page Default Settings](https://maxio.zendesk.com/hc/en-us/articles/24261337051789-Default-Page-Settings) and [Individual Page Settings](https://maxio.zendesk.com/hc/en-us/articles/24261368332557-Individual-Page-Settings).
When using Public Signup Pages, you have a specific URL to which customers can be sent that will allow them to sign themselves up - creating the subscription that is then added to your site.
We recommend reviewing how [Public Signup Pages work](https://maxio.zendesk.com/hc/en-us/articles/24181202779149-Create-Subscriptions-Inside-Advanced-Billing) to better understand the many ways Advanced Billing can be integrated with your systems. Public Signup Pages can also be a useful tool during development to test a simple signup with our pre-made forms versus your form in order to troubleshoot.
In some cases, the Public Signup Pages can't quite handle the specific scenario that you might need in your integration with Advanced Billing - that's why we expose a public API for you to consume by your application.
## API
You can create a basic subscription through the Advanced Billing API by providing just a few key details:
1. The **product** - A subscription links a customer to a product available on your site, so it needs to be specified when creating a subscription.
2. The **customer** - A customer is the person who is consuming your product/service. This can either be a reference to an existing customer in your site, or a completely new customer.
3. The **payment method** - Required for paid Products or any product with a billable component. This specifies how payment is collected.
> **Note:**
> 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.
- For [automatic](https://developers.maxio.com/http/getting-started/advanced-billing-concepts/subscription-signup#payment-methods) billing, payments are collected through a credit card or Automated Clearing House (ACH) details.
> **Note:**
> Use [Maxio.js (formerly Chargify.js)](https://developers.maxio.com/#/http/x-redirect/JTI0ZSUyRmRldmVsb3BtZW50LXRvb2xzJTJGY2hhcmdpZnktanMtb3ZlcnZpZXc) to easily construct signup and payment profile update forms directly on your existing sites. This approach ensures that you meet the latest [PCI compliance requirements](https://docs.maxio.com/hc/en-us/articles/24183956938381-PCI-Compliance).
- For [invoice](https://maxio.zendesk.com/hc/en-us/articles/24302160124173-Invoices-Overview-Statements) billing, the payment does not happen automatically but can still be done manually either through: non-electronic means and marked manually, or by using a credit card.
For example, the following `POST` to the Create Subscription API endpoint creates a subscription:
```json
{
"subscription": {
"product_handle": "pro-plan",
"customer_attributes": {
"first_name": "Joe",
"last_name": "Smith",
"email": "j.smith@example.com"
},
"credit_card_attributes": {
"chargify_token": "tok_cwhvpfcnbtgkd8nfkzf9dnjn",
"payment_type": "credit_card"
}
}
}
```
For more information, see the [Create Subscription endpoint documentation](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscriptions/create-subscription).
For advanced subscription creation scenarios, see [Advanced Subscription Creation Examples](https://developers.maxio.com/http/getting-started/about-the-api/expert-usage#advanced-signup-examples).
# Payment Methods
The payment method for a customer can be either Automatic or Remittance. With Automatic billing, the customer is automatically charged when a subscription renews. With Remittance, the customer is not automatically charged. Instead, an invoice is generated at renewal and can be sent to the customer. You can then record the payment manually once it is received.
For more information, see the [Payment Methods](https://maxio.zendesk.com/hc/en-us/articles/24181238764685-Overview-Subscription-Management?method=paymenttype) help article.
# Taxes
If you intend to charge your subscribers tax via [Avalara taxes](https://maxio.zendesk.com/hc/en-us/articles/24287008131853-Advanced-Billing-Managed-Sales-Tax) or [custom taxes](https://maxio.zendesk.com/hc/en-us/articles/24287044212749-Custom-Taxes), there are a few considerations regarding collecting subscription data. For subscribers to be eligible to be taxed, the following information for the `customer` object or `payment_profile` object must be supplied:
- A subscription to a [taxable product](https://maxio.zendesk.com/hc/en-us/articles/24261076617869-Product-Editing#tax-settings)
- [Full valid billing or shipping address](https://maxio.zendesk.com/hc/en-us/articles/24287008131853-Advanced-Billing-Managed-Sales-Tax#full-address-required-for-taxable-subscriptions) to identify the tax locale
- The portion of the address that houses the [state information](https://maxio.zendesk.com/hc/en-us/articles/24287008131853-Advanced-Billing-Managed-Sales-Tax#required-state-format-for-taxable-subscriptions) of either address must adhere to the ISO standard of a 2-3 character limit/format.
The portion of the address that houses the [country information](https://maxio.zendesk.com/hc/en-us/articles/24287008131853-Advanced-Billing-Managed-Sales-Tax#required-country-format-for-taxable-subscriptions) must adhere to the ISO standard of a 2 character limit/format.
# Multiple Subscriptions
Advanced Billing doesn't limit you to only allowing one single subscription per customer, you can have multiple subscriptions for a single customer using separate or linked payment methods.
In the following example, the existing customer with `reference` (shown as `customer_reference` below) value `1234-AB` will be subscribed to the product specified. You may also specify the customer_id, but it's far more useful to map a user on your system to a customer on Advanced Billing using this reference value. It's commonly filled with the user's unique identifier (i.e., the userID), which makes referencing the customer in Advanced Billing very simple as there are customer reference value filters in many methods.
```json
{
"subscription": {
"product_handle": "basic",
"customer_reference": "1234-AB",
"credit_card_attributes": {
"chargify_token": "tok_cwhvpfcnbtgkd8nfkzf9dnjn",
"payment_type": "credit_card"
}
}
}
```
For more information about the `customer_reference` and `customer_id` values, see [Create Subscription](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscriptions/create-subscription).
# Subscription in a Customer Hierarchy
For sites using the [Relationship Billing](https://maxio.zendesk.com/hc/en-us/articles/24252287829645-Advanced-Billing-Invoices-Overview) and [Customer Hierarchy](https://maxio.zendesk.com/hc/en-us/articles/24252185211533-Customer-Hierarchies-WhoPays) features, it is possible to create subscriptions within a customer hierarchy. This functionality is available through the API by including `group` parameters in the create subscription request.
The `group` parameters are optional and consist of the required `target` parameter and the optional `billing` parameter.
When the `target` parameter specifies a customer that is already part of a hierarchy, the new subscription becomes a member of the customer hierarchy. If the target customer is not part of a hierarchy, Maxio creates a new customer hierarchy, and both the target customer and the new subscription become part of the hierarchy with the specified target customer designated as the responsible payer for all subscriptions in that hierarchy.
Rather than specifying a customer, the `target` parameter can a value of `self`, which indicates the subscription is paid for by the subscribing customer. This is true whether the customer is being created new, already part of a hierarchy, or already exists outside a hierarchy. A valid payment method must also be specified in the subscription parameters.
When creating subscriptions in a customer hierarchy, if the hierarchy does not already have a payment method, passing a payment method makes that payment method the default for the customer hierarchy, regardless of the responsible payer.
# Subscription in a Subscription Group
For sites making use of [relationship billing](https://maxio.zendesk.com/hc/en-us/articles/24252287829645-Advanced-Billing-Invoices-Overview) you can create a subscription as part of a [subscription group](https://maxio.zendesk.com/hc/en-us/articles/24252172565005-Subscription-Groups-Overview) to use [invoice consolidation](https://maxio.zendesk.com/hc/en-us/articles/24252269909389-Invoice-Consolidation). You can achieve this through the API by passing group parameters in the create subscription request. The `group` parameters are optional and consist of the required `target` and optional `billing` parameters.
The `target` parameters specify an existing subscription with which the newly created subscription should be grouped. If the target subscription is already part of a group, the new subscription becomes a member of the group as well. If the target subscription is not part of a group, a new group is created and both the target and the new subscription become part of the group with the target as the group's primary subscription.
## Billing Parameters for Group and Customer Hierarchy Subscriptions
The optional `billing` parameters control how billing is handled for new subscription in a customer hierarchy or group:
- Use the `accrue` parameter to defer payment capture and accrue charges until the next assessment date.
- Use the `align_date` parameter to align the billing date of the new Subscription with the target Subscription.
- When aligning dates, you can also specify the `prorate` parameter so that charges for the new Subscription are prorated according to the target Subscription’s billing period.
# Components
A common first step during signup is to allocate one or more components that match the initial state of the customer’s subscription. Consider a subscription service that ships a set number of widgets each month. If the Customer signs up for the “5 widgets per month” Product, you would allocate five units of the widget component, as shown below:
```json
{
"subscription": {
"product_handle": "basic",
"customer_attributes": {
"first_name": "Alysa",
"last_name": "Test",
"email": "alysa@example.com",
"reference": "1234-AB"
},
"credit_card_attributes": {
"chargify_token": "tok_cwhvpfcnbtgkd8nfkzf9dnjn",
"payment_type": "credit_card"
},
"components": [
{
"component_id": 1,
"allocated_quantity": 5
}
]
}
}
```
For more information about components and how to use this great feature to customize your signup process - see [components](https://developers.maxio.com/#/http/x-redirect/cGFnZSUzQWNvcmUtY29uY2VwdHMlMkZwcm9kdWN0LWNhdGFsb2clMjNjb21wb25lbnRz).
See the following articles for a deep dive into how components function within Advanced Billing:
- [Setting component allocations](https://maxio.zendesk.com/hc/en-us/articles/24251883961485-Component-Allocations-Overview)
- [Building components in Advanced Billing](https://maxio.zendesk.com/hc/en-us/articles/24261141522189-Components-Overview)
# Managing Subscriptions
After a Subscription is created, you or your customer will likely need to manage it in various ways. The following sections outline common subscription management tasks.
---
## One-Time Charges
Advanced Billing allows you to add charges to a subscription outside of the regular recurring billing cycle. This is called a ["one-time" charge](https://maxio.zendesk.com/hc/en-us/articles/24302079003533-One-time-Charges) A one-time charge is a charge that happens once either by submitting the charge via the API or by creating the charge manually in the app.
This example posts a $1 charge to a subscription:
```json
// POST /subscriptions/{subscription_id}/charges.json
{
"charge": {
"amount_in_cents": 100,
"memo": "This is the description of the reason for the $1 charge."
}
}
```
For more information, see [the API details for creating charges](https://developers.maxio.com/legacy/http/api-endpoints/legacy-subscription-balance/create-subscription-charge).
## Billing Dates
It is common for a subscription’s billing date to change. The billing date is the next date the subscription is processed or assessed, and when charges may be captured from its payment method. Changes to the billing date are typically made to extend or shorten trials, process a Subscription immediately, or adjust the date for [calendar billing](https://maxio.zendesk.com/hc/en-us/articles/24286596359949-Calendar-Billing) scenarios.
This example updates the billing date for a subscription:
```json
/// POST /subscriptions/{subscription_id}.json
{
"subscription": {
"next_billing_at": "2016-08-29T12:00:00-04:00"
}
}
```
See the full API documentation for [updating subscription assessment date](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscriptions/update-subscription) for more information.
## Updating Payment Details
Updating the payment details allows you to change the card used for a subscription or update the card’s expiration date.
> If your customer pays taxes on their purchased product, and you are attempting to update the `payment_profile`, complete address information is required. For information on required address formatting to allow your subscriber to be taxed, see the section on [sign-up taxes](https://developers.maxio.com/#/http/x-redirect/cGFnZSUzQWludHJvZHVjdGlvbiUyRmJhc2ljLWNvbmNlcHRzJTJGU2lnbnVwcyUyM3RheGVz).
You can update the payment details via:
- [Self-Service Pages](https://developers.maxio.com/http/getting-started/advanced-billing-concepts/subscription-signup#updating-via-self-service-pages)
- [API](https://developers.maxio.com/http/getting-started/advanced-billing-concepts/subscription-signup#updating-via-api)
- [Maxio.js (formerly Chargify.js)](https://docs.maxio.com/hc/en-us/articles/38163190843789-Chargify-js-Overview)
### Updating via Self-Service Pages
You can allow your users to update their information themselves, using the self-service public hosted pages or even the new billing portal.
For the public service page card update, you merely direct them to a specific URL:
`https://{subdomain}.chargify.com/update_payment/{subscription_id}/{token}`
- The `subdomain` is just your subdomain. Our imaginary company "Acme"'s URL would start like the following: `https://acme.chargify.com`
- The `subscription_id` would be the integer ID of the subscription as it is in the Advanced Billing site/subdomain.
- The `token` is calculated using the first 10 characters of the SHA-1 hex digest of this message:
```
message = "update_payment--{subscription_id}--{shared_key}"
token = SHA1(message)[0..9]
```
For more information about the self-service card update public page, see the [Obtaining the Self-Service Page URL](https://maxio.zendesk.com/hc/en-us/articles/24261425318541-Self-Service-Pages#obtaining-the-self-service-page-url) article.
Your users can also self-service update their payment method if using the Advanced Billing Portal feature, see [Updating Payment Information via the Billing Portal](https://maxio.zendesk.com/hc/en-us/articles/24261425318541-Self-Service-Pages#updating-payment-information-via-the-billing-portal) for more information.
### Updating via API
Updating payment profiles via the API is useful in situations where you are more directly integrating with Advanced Billing.
There are many methods of performing this action via the API, you can:
1. Update the payment profile indirectly through a subscription update
2. Update the payment profile directly
See [Update Payment Profile](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/payment-profiles/update-payment-profile) and [Update Subscription](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscriptions/update-subscription) for more complete documentation about updating payment profiles via the API.
## Cancelling
Cancelling subscriptions is another common task that customers can perform, or that is performed on their behalf when payment cannot be captured.
This example cancels a subscription:
```json
// DELETE /subscriptions/{subscription_id}.json
{
"subscription": {
"cancellation_message": "Canceling the subscription via the API"
}
}
```
You can also cancel a subscription at the end of the current billing period, which is called a delayed cancellation.
This is an example of a delayed cancellation request:
```json
// DELETE /subscriptions/{subscription_id}.json
{
"subscription": {
"cancel_at_end_of_period": 1,
"cancellation_message": "Canceling the subscription via the API"
}
}
```
For information about cancelling using the API, see [Cancelling via API](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-status/cancel-subscription).
For information about cancelling subscriptions in general, see the [Cancellations](https://maxio.zendesk.com/hc/en-us/articles/24252133729165-Cancellations) help article.
## Refunds
With Advanced Billing you have the ability to apply a refund to payments that have been processed at the gateway. Refunds are only supported for the gateways listed in the [Issuing Refunds in Statement-Based Sites](https://maxio.zendesk.com/hc/en-us/articles/24302120115213-Refunds) help article.
For gateways like Bambora, you need to perform a "manual refund" in that you record the refund as a transaction directly after you perform the actual refund in your gateway account.
You can perform a non-manual refund using the API, as shown in the following example:
```json
{
"refund": {
"payment_id": "{payment_id}",
"amount": "4.00",
"memo": "Your memo here."
}
}
```
You will substitute values for `payment_id`, `amount` and `memo` in this example. The `payment_id` is the ID of the payment transaction that the credit will be applied to.
For more information, see [API refunds](https://developers.maxio.com/legacy/http/api-endpoints/legacy-subscription-balance/create-refund).
For a manual or external refund, you also supply a value for `external`:
```json
{
"refund": {
"payment_id": "{payment_id}",
"amount": "4.00",
"memo": "Your memo here."
},
"external": 1
}
```
For a manual or external refund, there is nothing passed through to your gateway - it is simply added to the subscription, modifying the balance and adding a transaction record.
For more information, see [API Refunds (External)](https://developers.maxio.com/legacy/http/api-endpoints/legacy-subscription-balance/create-refund).
## Subscription Updates via Billing Portal
Subscriptions can also be updated by the subscriber via the Billing Portal. The Billing Portal allows your subscribers to perform certain managerial actions on their current subscription. As a merchant, you have the ability to also restrict what actions can be performed by a subscriber.
Here are a few examples of actions that can be performed via the Billing Portal:
- Plan changes
- Subscription cancellation
- Credit card updates
- Component purchase / allocation updates
For more information on the Advanced Billing Portal, see the [Billing Portal](https://maxio.zendesk.com/hc/en-us/articles/24252412965133-Billing-Portal-Overview) help articles.
#### Entitlements
Source: https://developers.maxio.com/http/getting-started/advanced-billing-concepts/entitlements
Entitlements let you define features once — like Single Sign-On, a monthly API call limit, or a support tier — and grant them to subscribers through the products and components they already have.
At runtime, Entitlements answers a simple question: **what is this subscription actually allowed to do, and how much of it?**
---
There are three steps to using Entitlements:
- Defining a [feature template](https://developers.maxio.com/http/getting-started/advanced-billing-concepts/entitlements#feature-templates)
- Attaching that feature template to a [product or component](https://developers.maxio.com/http/getting-started/advanced-billing-concepts/entitlements#attaching-features-to-products-and-components)
- Reading a subscriber's [aggregated entitlements](https://developers.maxio.com/http/getting-started/advanced-billing-concepts/entitlements#reading-a-subscribers-entitlements)
# Feature Templates
A feature template is defined once, at the site level, and describes a feature you might want to grant to subscribers. Every feature template has a `kind`, which determines how its value behaves:
- **`access_right`** — a boolean entitlement. A subscriber either has access or does not (for example, Single Sign-On).
- **`usage_limit`** — a quantified allowance measured over a recurring period (for example, "10,000 API calls per month").
- **`service_right`** — a free-form value (text, boolean, or number) that isn't a simple access flag or a metered limit (for example, a support tier of `"gold"`).
```json
// POST /features.json
{
"feature": {
"key": "sso",
"name": "Single Sign-On",
"kind": "access_right"
}
}
```
That data is posted to the [Create Feature Template](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/feature-templates/create-feature-template) endpoint. `key` is immutable once set, and `kind` can't be changed once the feature template has been attached to any product or component.
# Attaching Features to Products and Components
A feature template isn't granted to anyone on its own — it has to be attached to a product or component (or to one of their price points) as a **feature catalog item**, with a concrete value:
```json
// POST /products/{product_id}/features.json
{
"feature": {
"feature_template_id": 1001,
"value": "true"
}
}
```
That data is posted to the [Create Product Feature Catalog Item](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/product-features/create-product-feature) endpoint (or [Create Component Feature Catalog Item](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/component-features/create-component-feature) for a component). Once attached, subscribers on that product/component are provisioned an entitlement automatically the next time their subscription changes — for example, on signup, a plan change, or a component allocation.
You can scope a feature catalog item to a single price point instead of the whole product/component by passing `price_point_type` and `price_point_id` — see [Create Product Feature Catalog Item](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/product-features/create-product-feature) for details.
Removing a feature catalog item defaults to a soft removal: the feature is taken out of the catalog, but subscribers who already have it keep their existing entitlement (they're "grandfathered in"). Pass `destroy_entitlements=true` to instead revoke access immediately. Archiving a feature template with [Archive Feature Template](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/feature-templates/archive-feature-template) has the same default/override shape, using its own query parameter, `remove_from_catalog=true` — restoring an archived feature template never restores entitlements removed this way.
# Reading a Subscriber's Entitlements
To find out what a specific subscription is entitled to, call [Read Subscription Entitlements](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/entitlements/read-subscription-entitlements). It collapses every product and component on the subscription into one entry per feature key and periodicity window — so a `usage_limit` feature granted monthly by one product and daily by another comes back as two entries, each identified by its own `periodicity_key`:
```json
// GET /subscriptions/{subscription_id}/entitlements.json
{
"subscription_id": 12345,
"customer_id": 678,
"status": "active",
"entitlements": [
{
"feature_key": "feature.sso",
"periodicity_key": "feature.sso",
"name": "SSO",
"type": "access_right",
"value": true,
"enabled": true,
"periodicity": null,
"source_products": ["Gold Plan"]
},
{
"feature_key": "usage.api_calls",
"periodicity_key": "usage.api_calls:1:month",
"name": "API Calls",
"type": "usage_limit",
"value": 50000,
"enabled": true,
"periodicity": { "interval": 1, "unit": "month" },
"source_products": ["Gold Plan"]
}
]
}
```
`enabled` reflects both the aggregated value and the subscription's state — it's `false` whenever the subscription isn't in a live state (`active`, `trialing`, `assessing`, `past_due`, or `soft_failure`), regardless of the value. Note that entitlements stay enabled while a subscription is in dunning. This is the field most integrations should check before granting access in their own application.
If you're already fetching products or components and want their features embedded directly in that response instead of making a separate call, pass `include_features=true` to [List Products](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/products/list-products), [Read Product](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/products/read-product), or [Read Component](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/components/read-component). List Components does not support it.
### About the API
#### Tips and Best Practices
Source: https://developers.maxio.com/http/getting-started/about-the-api/tips-and-best-practices
> Maxio Advanced Billing provides an HTTP-based API that conforms to the principles of REST.
> Advanced Billing also offers a broad feature set and official [client libraries](https://developers.maxio.com/http/development-tools/using-the-developer-portal#code-language-selection-and-sdk-access) for common languages.
> The API returns JSON responses as the primary and recommended format, but XML is also provided as a backwards compatible option for merchants who require it.
API access is included on all plans at no charge, so you always have direct access to your own data. You can use the API for a wide range of purposes.
As you build your integration, keep request volume in mind. Because API traffic involves little or no user interaction, a program or routine can send far more requests than it needs. Runaway usage places unnecessary load on the platform, slows your own integration, and can trigger throttling or blocked requests.
The following tips and best practices help you keep your integration efficient and reliable.
# Client Libraries and SDKs
Maxio maintains official Advanced Billing SDKs for Python, Ruby, PHP, C#/.NET, TypeScript, Java, and Go.
Before writing your own client, check whether an SDK covers your stack. Select your language in the developer portal, and then click **Get SDK** to install it from your package manager. For more information, see [Code language selection and SDK access](https://developers.maxio.com/http/development-tools/using-the-developer-portal#code-language-selection-and-sdk-access).
# Development
If you have difficulty sending a request, try the simplest approach first and send the request with the curl command-line tool. Add the `--verbose` flag to receive additional debugging information.
[Webhook.site](https://webhook.site/) is another useful tool. If you are unsure what your integration is sending, post the request to a temporary Webhook.site URL instead of to the API so you can inspect the payload.
# Getting Subscription States
Most integrations need to know whether a customer has an active subscription, has canceled, or is behind on payments. The best approach is to keep a locally cached copy of the subscription state in your own database, then use [webhooks](https://developers.maxio.com/http/getting-started/webhooks/webhooks) to stay up to date in near real time as changes occur. Caching keeps your site available, reduces coupling to the API, and keeps both applications fast.
Avoid querying the API inline as part of a customer's request to your site. Inline queries can result in:
- Slowing down your own site while the customer waits for a check to the API on every request.
- Breaking your site during a network connectivity issue or in the unlikely event that the API is unavailable.
- Consuming large numbers of API requests as your customer base grows and becomes more active, which can lead to blocked requests from automatic abuse prevention.
There are three basic ways to track the state of a customer's subscription:
- Retrieve [subscription state](https://developers.maxio.com/http/getting-started/about-the-api/tips-and-best-practices#subscription-state) through the API
- Receive [webhooks](https://developers.maxio.com/http/getting-started/webhooks/webhooks#responding-to-a-webhook)
- Download a manual [export](https://maxio.zendesk.com/hc/en-us/articles/24285931839757-Exporting-Data#locating-exports)
One of the easiest methods is to have your application request the current state (or history) of a subscription through the API, which returns the state of the subscription at the time of the request.
## Subscription State
To get the current state of a subscription, send the following request:
```
HTTP GET https://{subdomain}.chargify.com/subscriptions/{subscription_id}.{format}
```
The response contains the current information about the subscription, including (but not limited to):
- Subscription details, such as subscription state, creation date, balance, next assessment date, and cancellation information
- Customer details
- Payment details
For more information, see [Read Subscription](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscriptions/read-subscription).
## Best Practices
Keep the following practices in mind as you synchronize your application with your Advanced Billing data:
- Do not let your application depend on another service to control access directly. If an API call fails for any reason, your customer may not receive the best user experience, depending on how you have implemented the check.
- Limit direct calls where possible. The API limits how quickly and how often it responds to rapid, numerous calls. For more information, see [Error Handling & Rate Limiting](https://developers.maxio.com/http/getting-started/about-the-api/error-handling-rate-limiting).
# Synchronizing Your Database
Normally, [webhooks](https://developers.maxio.com/http/getting-started/webhooks/webhooks) keep your local customer database in sync. If your database does fall out of sync with Advanced Billing, checking the state of all subscriptions through the API may be the only way to restore consistency.
A full reconciliation is fine when you need it. Reserve the practice for exceptional circumstances or for periodic reconciliation, usually no more than once a month.
Avoid pulling your entire subscriber base on every reconciliation run. The subscriptions list endpoint supports filtering, so you can request only what has changed since your last sync:
- `date_field=updated_at` combined with `start_date` and `end_date` returns only subscriptions modified in that window.
- `state` filters to specific subscription states (for example, `active`, `canceled`, or `past_due`), and accepts a comma-separated list of values.
- `page` and `per_page` paginate the results. See [List Subscriptions](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscriptions/list-subscriptions) for the current per-page limit for your account.
Filtering a routine reconciliation job this way, instead of pulling every subscription each time, can reduce a full-account sync to a fraction of the API calls and keeps you well clear of rate limits. The same date-field filtering is available when listing invoices.
This filtering is not currently available on the customers list endpoint, so a customer-record reconciliation still requires pulling the full list.
# Reporting Usage
When reporting component usage, avoid sending many tiny usage amounts. For example, if you charge by the minute for phone calls:
- **Don't** send a usage report for every minute or every phone call individually.
- **Don't** send all usage for all customers at once. Spread the reports out, or wait a short period of time between each request.
Instead:
- **Do** send one usage report per day with how much each customer used for the whole day.
For more information on reporting component usage or allocations, see the endpoint descriptions for the type of component used:
- [Create Usage](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-components/create-usage) for metered components
- [Allocate Component](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-components/allocate-component) for quantity-based components
## Handling Retries Safely
Advanced Billing supports a `uniqueness_token` parameter on any POST or PUT request to protect against duplicate submissions, such as when a request times out and you cannot tell whether it was received. Supply a long, random value such as a UUID. If a second request with the same token arrives within 60 minutes, it is rejected with a `409 Conflict` and a duplicate submission error instead of being processed again.
This applies to usage reports, component allocations, and subscription creation alike. Use a `uniqueness_token` any time your integration might retry a request after a timeout or an ambiguous failure, so that a retried usage report does not double-count a customer's usage for that period.
For full details, including how to recover when the outcome of the original request is unknown, see [Duplicate Prevention](https://developers.maxio.com/http/getting-started/about-the-api/duplicate-prevention).
# Downloading Bulk Data
Periodically exporting transaction, subscription, or customer data is a common use case. Where possible, use the built-in [export](https://maxio.zendesk.com/hc/en-us/articles/24285931839757-Exporting-Data) functions inside Advanced Billing to generate reports and download the data. Exports are often much faster and significantly lower your API usage.
For subscription, invoice, or proforma invoice data specifically, you can automate exports instead of using the UI. Use [Create Subscriptions Export](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/api-exports/export-subscriptions) (or the Invoices and Proforma Invoices equivalents) to start an export job, and then poll its status and retrieve the result with the corresponding Read and List endpoints. This lets you schedule exports without manual steps.
# Secure Applications
API requests cannot be made directly from the customer's browser or device. A client-side request would expose your API key, and anyone who has that key has full access to all of your Advanced Billing data.
Instead, tokenize sensitive information with [Maxio.js (formerly Chargify.js)](https://docs.maxio.com/hc/en-us/articles/38163190843789-Chargify-js-Overview) or a similar JavaScript library provided by your gateway. Post the token and any other information to your own server, and then make the API call from there.
## CORS and Browser Requests
If you attempt to make an API request directly from the customer's browser, you may see an error such as:
```
Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource.
```
or
```
Origin 'https://example.com' is therefore not allowed access.` `The response had HTTP status code 404.
```
These errors mean you need to move the API call server-side, as described above. The API does not support Cross-Origin Resource Sharing (CORS) for requests made directly from a browser. This is by design, and CORS cannot be enabled for your site or domain.
# Large Imports
If you plan to import a large amount of data through the API, send a heads-up to [support@maxio.com](mailto:support@maxio.com) ahead of time. The Maxio team can then coordinate with you to make sure your import process goes smoothly.
#### Data Types
Source: https://developers.maxio.com/http/getting-started/about-the-api/data-types
# Dates and Time Zones
API responses from Advanced Billing are sent with the timezone of the current Advanced Billing site.
Alternately, webhooks sent from Advanced Billing globally use EST (Eastern Standard Time) as the timezone for all content in the body of the payload.
For requests,
If only a date is provided: Advanced Billing uses noon in the site’s time zone
If date and time are provided, Advanced Billing uses the time of day in the site’s time zone.
If date/time/timezone is provided, Advanced Billing uses that absolute date and displays it in the site’s time zone.
# Decimal Numbers
In order to prevent losing precision, we serialize decimal numbers as strings instead of as JSON numbers.
We recommend parsing these strings into their decimal equivalent using a decimal number library in your programming language (for example, `BigDecimal` in Ruby) instead of relying on floating point values or arithmetic.
# Amount Fields and Currency
Fields holding amount values are given as a string representing a decimal whole currency amount.
For example, `"1.23"` in currency `"USD"` would equate to `$1.23`.
Not all fields will be rounded to the smallest currency denomination. Intermediate results, such as those that derive from line-level tax calculations, may hold precision up to 8 decimal places. However, the top-level totals we provide (e.g., `total_amount`) will be rounded to the smallest currency denomination.
It is up to API consumers to parse the string into a decimal number representation and do any rounding necessary for your application.
#### Request and Response Data
Source: https://developers.maxio.com/http/getting-started/about-the-api/request-and-response-data
# URL
The URL for API requests includes the subdomain of the Site you are working with:
`https://.chargify.com/`
# Response Data
Response data is sent as either XML or JSON, depending on the type of data requested (`HTTP Content-Type` header) or the type specified as being accepted (HTTP `Accept` header).
GETs for individual statements and invoices may also be requested as PDF using `application/pdf` or appending `.pdf` to the resource URI.
Response codes are sent via the normal HTTP Response Code, and are documented separately for each resource.
For boolean fields, note that a value of `null` may be considered as false. However, this is not true across all cases. Exercise good judgement here, or contact support with any questions.
For example:
- `null` can define that there's no data available for that attribute
# Request Data
POST and PUT request data may be formatted as either XML (`application/xml`) or JSON (`application/json`). For best results, you should set your HTTP `Content-Type` request header accordingly, although you may also specify your format by appending `.xml` or `.json` extensions on to the resource URI.
Note: Advanced Billing does not accept PUT or POST data sent as query parameters or form-encoded data – data must be sent as either XML or JSON. If you fail to set your `Content-Type` to either `application/xml` or `application/json`, your request may fail due to triggering of forgery protection mechanisms.
#### Error Handling & Rate Limiting
Source: https://developers.maxio.com/http/getting-started/about-the-api/error-handling-rate-limiting
# Rate Limits and Blocks
There are two different types of limits/blocks you may encounter: rate-based and account-based. Be sure to familiarize yourself with both types of limits, as they are vastly different.
Our rate limiting rules are primarily intended to prevent runaway scripts, infinite loops, or crushing amounts of concurrency. Working, good-hygiene code should not experience any blocks. The single most important guidelines are to write code that will properly handle 429 responses by slowing or pausing requests without crashing, and to not parallelize into simultaneous requests that will compete for resources and flood our systems.
Advanced Billing uses a custom algorithmic slot-based limiting that isn't based on typical rate limits per second. Rather, we handle call limiting based on concurrency, and a maximum of 4 concurrent API calls can be made. This does not mean that only 4 requests are allowed per second; rather, 4 server threads or workers can be running concurrently per subdomain at a time. Any concurrency that goes above 4 is at risk for being queued for processing after the concurrency once again drops to acceptable ranges. As such, we recommend when building out your API processes to focus on the number of concurrent calls rather than the actual rate of calls per hour.
To help illustrate this, we've provided a diagram below. Presume that each API call takes a full minute. While this will likely not be the case for your own processes, it does illustrate the limitations for calls.
|  |
| --------------------------------------------------------------------------------------- |
| **Diagram of concurrency-based rate limiting presuming a limit of 2 threads at a time** |
## Rate-based Blocks
When performing a large synchronization or retrieving a large amount of data, you may trigger a security failsafe used to prevent abuse and protect our site from attacks. We don’t want to block small bursts in usage; so instead of immediately rejecting your requests, Advanced Billing will slow and throttle requests.
> ❗️ If you see your responses coming in slower, do not parallelize your requests or try to make more concurrent requests to speed things up. You’ll only have to wait longer for your requests to get through.
If you have too many slowed requests, or your individual account queue gets too full with too many concurrent requests, you’ll likely receive an HTTP `429 Too Many Requests` response code with a message and a reference code:
`Your request was denied due to a usage violation. You can track this request with support by referencing …`
If you receive a `429 Too Many Requests` response, your code should be prepared to handle it by pausing its queries, waiting a few minutes, and then proceeding slower (or with less concurrency). Feel free to [open a support ticket](https://maxio.zendesk.com/hc/en-us/requests/new) so we can investigate what happened and why the request was blocked.
## Account-based Blocks
There are a few scenarios that could cause a request to be blocked even with correct credentials. You can read about them [here](https://developers.maxio.com/http/getting-started/about-the-api/error-handling-rate-limiting#api-access-limitations). If you have a request blocked with a `422` status code and an error message, it may be due to this account-based blocking.
## Prioritization of Endpoints
We consider certain endpoints as "critical", such as new customer signups and component allocations. We first and foremost want to ensure that we don't prevent a new signup except under the most extreme situations. Many merchants have a mix of all different types of calls. By dynamically balancing, we can slow down "low priority" requests (reports and exports), while still handling large unexpected surges in signups.
## Endpoint Variances
Each endpoint is different within Advanced Billing. Expensive endpoints have lower limits than fast endpoints. But in general, your requests will slow down because of sending too many simultaneous requests to the same endpoint(s). When you do that, your requests will be "queued" behind yourself. One request must wait for the one in front of it to finish. In that way, we 'level out' spikes of requests over a longer period of time so that it doesn't cause a negative impact for other merchants. This is why you'd see requests be processed at a slower rate.
## Timeout Limitation
Advanced Billing imposes a cut-off time of 120 seconds for all requests to all endpoints. It's important to note that when you make requests for specific actions, Advanced Billing is also sending these requests off to your associated gateway. If a request is not processed by the combination of Advanced Billing and your gateway within the 120 second guideline, the request will time out.
Keep in mind that if you encounter a timeout issue, it is worth inspecting your gateway's [current status](https://maxio.zendesk.com/hc/en-us/articles/24286964853261-Gateway-Errors). This is also important to do if you feel there is a processing issue, outside of Advanced Billing's control, that is affecting your requests.
# API Access Limitations
There are a few scenarios that may end up causing an API request to be blocked even with correct credentials.
> ❗️ All relevant API requests will be blocked if any of the below conditions are true.
Those scenarios are as follows:
- Your Advanced Billing subscription is canceled.
- Your Advanced Billing trial has reached an end.
- The site you're making a request for is in the process of ["clearing site data"](https://maxio.zendesk.com/hc/en-us/articles/24250617028365-Clearing-Site-Data)
- _Note: any API request for another site that is in a good state will NOT be blocked_
- The site you're making a request for has been deleted.
- _Note: any API request for another site that is in a good state will NOT be blocked_
Read more about your Advanced Billing subscription [here](https://maxio.zendesk.com/hc/en-us/articles/24183861526541-Advanced-Billing-Subscription)
### What happens when an API request is blocked
The request will fail with a `422` http status code. The response will also include a message explaining the reason for the request being blocked. For example:
- If your Advanced Billing subscription is canceled:
```json
{
"errors" => [
[0] "Your Advanced Billing account has been canceled. Please contact support@maxio.com to reactivate."
]
}
```
- If your Advanced Billing trial has reached an end and you attempted to make an API request, the response body will look like:
```json
{
"errors" => [
[0] "Your trial has ended, please contact sales."
]
}
```
- If the site you're making a request for is in the process of ["clearing site data"](https://maxio.zendesk.com/hc/en-us/articles/24250617028365-Clearing-Site-Data):
```json
{
"errors" => [
[0] "Site data clearing is in progress. Please try later."
]
}
```
- If the site you're making a request for has been deleted:
```json
{
"errors" => [
[0] "This site has been deleted."
]
}
```
#### List Operations
Source: https://developers.maxio.com/http/getting-started/about-the-api/list-operations
# Pagination
When an endpoint returns a list of items, it will be paginated. Usually, 20 items will be returned by default, and you may request up to a maximum of 200 at a time. Pagination is done with query string parameters, for example: `?page=5&per_page=200`
#### Versioning
Source: https://developers.maxio.com/http/getting-started/about-the-api/versioning
# Backwards Compatibility
We consider the following changes to be backwards compatible and may make them without advance notice:
- Adding new API endpoints, or adding new attributes in the responses of existing endpoints
- Adding new optional parameters to be sent to existing API endpoints
- Adding new fields to exported data
- Changing the type or length of any of the ID attributes
- For example, most IDs are currently integers, but you should not assume that this will always be the case.
In addition, you should not depend on the order of attributes within the API response as this may change.
Advanced Billing does not provide notifications for additions that are clearly defined as backwards compatible.
#### Duplicate Prevention
Source: https://developers.maxio.com/http/getting-started/about-the-api/duplicate-prevention
When making API requests, it is possible to receive an error even though your request actually completed successfully.
For example, if you submit an API request and it times out, you can’t be sure whether your request was received by Advanced Billing, or not.
If you simply retry the request, you _might_ end up with a duplicate transaction.
# Uniqueness Token
In order to prevent these duplicates, Advanced Billing allows you to supply a `uniqueness_token` parameter in any `POST` or `PUT` request.
The value you supply for the `uniqueness_token` should be long and random, like a UUID. The exact format of the value is up to you.
If a subsequent request with the same uniqueness_token is received within 60 minutes, it will be rejected with a `409 Conflict` response code and a duplicate error message.
# Example
For example, suppose you are making an adjustment on a subscription. Using curl, you send the following POST request, including a `uniqueness_token`.
```json
curl --verbose -u $CHARGIFY_API_KEY:x -H Accept:application/json -H Content-Type:application/json -X POST \
-d @adjustment.json https://$CHARGIFY_SUBDOMAIN.chargify.com/subscriptions/$SUBSCRIPTION_ID/adjustments.json
adjustment.json:
{"adjustment":
{
"amount": "-12.43",
"memo": "Credit for outage on 1/31"
},
"uniqueness_token": "2731FB23-98AD-4489-BAF6-7D5CE916F766"
}
```
After you send your request, there is some problem, and the request times out without a valid response instead of the `201 Created` you were hoping for.
Since you have supplied a `uniqueness_token`, you can safely retry the request.
If you receive the expected `201 Created` (or `422 Unprocessable Entity`) response, you can continue as usual knowing that Advanced Billing never received your first request.
If you receive a `409 Conflict` and a duplicate error message for the retry, then you know that the first request was received and responded to.
Example 409 Conflict response:
```
< Status: 409 Conflict
{"errors":["DuplicatePrevention::DuplicateSubmissionError"]}
```
Unfortunately, it is not possible to know what the outcome of the first request was, so you cannot automatically assume it was successful.
Depending on what type of request you were making, it might be possible to gracefully recover by recording some information about the original request, listening for webhooks, and matching up the webhook payload to find out whether the request succeeded or not.
In other cases, human intervention will be necessary.
# Summary
We hope this feature will help you prevent duplicate transactions during error handling.
That said, if you are experiencing repeated timeouts, [email Maxio support](mailto:support@maxio.com) so we can investigate.
#### Expert Usage
Source: https://developers.maxio.com/http/getting-started/about-the-api/expert-usage
The following are some additional useful topics that you might need to handle or read up on, and are here as reference. These generally are topics which may be useful for expert usage of Advanced Billing.
# Advanced Signup Examples
The following are a few advanced/expert examples of new signups/subscriptions that you might encounter. These may be common, but it entirely depends on what features of Advanced Billing you use and how you integrate your use of Advanced Billing.
See [Create Subscription](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscriptions/create-subscription) for details.
1. Import as new signup/subscription
**Example**
```json
// POST /subscriptions.json
{
"subscription": {
"product_handle": "basic",
"next_billing_at": "2010-08-29T12:00:00-04:00",
"customer_attributes": {
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"reference": "123",
"organization": "Acme Widgets"
},
"payment_profile_attributes": {
"vault_token": "12345",
"customer_vault_token": "67890",
"current_vault": "authorizenet",
"expiration_year": "2020",
"expiration_month": "12",
"card_type": "visa",
"last_four": "1111"
}
}
}
```
2. New Subscription with Coupon/Trial/Component
Signups can implement coupons, custom trial periods and components right from the initial creation of the subscription, like in the following:
**Example**
```json
{
"subscription": {
"product_handle": "basic",
"customer_attributes": {
"first_name": "John",
"last_name": "Smith",
"email": "john@example.com"
},
"credit_card_attributes": {
"masked_card_number": "XXXX-XXXX-XXXX-1111",
"expiration_month": "10",
"expiration_year": "2020"
},
"coupon_code": "SUB111",
"next_billing_at": "2020-06-01",
"components": [
{
"component_id": 123456,
"unit_balance": 20
}
]
}
}
```
3. New Subscription with Existing Payment Profile
# Metafields and Metadata
Metafields allow you to create custom fields that store information in a customer or subscription resource in Advanced Billing. Metafields and metadata are called [Custom Fields](https://docs.maxio.com/hc/en-us/articles/24178993762317-Custom-Fields) in the application and product documentation.
The following example creates a metafield, and then sets the metadata value for it.
**Example**
First, create a metafield. In this example, a color field is applied to the Customers resource:
```json
// POST /customers/metafields.json
{
"metafields": {
"name": "Color",
"scope": {
"csv": "1",
"invoices": "1",
"portal": "1"
}
}
}
```
The options for `scope` set here would show this metafield on Public Signup Pages, show the metadata on invoices, and allow the metadata to be exported via CSV.
Next, set the color for a particular customer:
```json
// POST /customers/{customer_id}/metadata.json
{
"metadata": {
"name": "Color",
"value": "Blue"
}
}
```
The particular customer would have the metadata for the metafield "Color" set to "Blue".
For more API information about metafields (the containers of your metadata), see [Create Metafields](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/custom-fields/create-metafields).
# Communication
Advanced Billing enables you to communicate with your subscribers through a variety of methods. For more information on these methods, read the given help article:
- [Email templating](https://maxio.zendesk.com/hc/en-us/articles/24266086168461-Email-Templates)
- The use of [Liquid Syntax](https://maxio.zendesk.com/hc/en-us/articles/24266086916877-Liquid-Examples) in your emails and communications
- [HTML/text emails](https://maxio.zendesk.com/hc/en-us/articles/24266101040781-HTML-Emails)
- [Mass emailing subscribers](https://maxio.zendesk.com/hc/en-us/articles/24266110860045-Bulk-Email-Mass-Emailing-Subscribers)
- [Email archives](https://maxio.zendesk.com/hc/en-us/articles/24266109347853-Email-Archives)
# Dunning
Dunning is the process of how you communicate with your customers in regards to failed credit card transactions and expiring credit cards.
Advanced Billing helps manage the dunning process, or what we like to call the “unhappy path.” Or what happens when a credit card transaction fails. If you’re using Authorize.net, PayPal, or Google Checkout, you have to manually address each credit card issue as it arises. This is both tedious and time consuming and is certainly not the most efficient way to handle problems when executing a large number of transactions.
For more information about dunning - including how to setup your dunning plans, see the [Dunning](https://maxio.zendesk.com/hc/en-us/articles/24287076583565-Dunning-Overview) help article.
# Referrals
Referrals are a great way to reward your customers for sharing information about your application with new potential users. Advanced Billing generates a referral code for each of your subscriptions and rewards the new customer, as well as the referrer, when a new signup is created with the code.
If referrals are enabled, then every subscription will have a `ref` (short for "referral code") as part of the available data in the subscription API response.
**Example**
```json
// GET /subscriptions/{subscription_id}.{format}
{
"subscription": {
"id": "123456789",
"state": "active",
// ...
"ref": "trdgzp"
}
}
```
To validate the code, you can do the following:
HTTP GET: `https://{subdomain}.chargify.com/referral_codes/validate.{format}?code={ref/referral_code}`
If the referral code is valid, the response will be `200 OK`. Otherwise, the response will be `404 NOT FOUND`.
For more information about referrals, see the [Referrals](https://maxio.zendesk.com/hc/en-us/articles/24287008467725-Referrals-Overview) help article.
# Notes
You can also enter and manage notes on a subscription. Notes allow you to keep non-structured data associated with individual subscriptions. If you need structured data, consider using [Metafields/Metadata](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/custom-fields/create-metafields).
To create a simple note on a subscription, see the following:
```json
// POST /subscriptions/{subscription_id}/notes.{format}
{
"note": {
"body": "This is the note that never ends, it just goes on and on ..",
"sticky": true
}
}
```
Setting the value for `sticky` to `true` will show the note prominently when viewing the subscription.
For more information about notes, see [Create Subscription Note](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-notes/create-subscription-note).
### Webhooks
#### Webhooks
Source: https://developers.maxio.com/http/getting-started/webhooks/webhooks
Use webhooks to receive notifications or initiate workflows when important events occur, like a payment succeeding, a Subscription status updating, or other relevant changes. You can subscribe to events of interest, and the system will post data to the URL you specify when one of those events occurs.
# Using Webhooks
To begin using webhooks, you must first create a publicly accessible endpoint that meets the following requirements:
1. Only HTTP endpoints are allowed in test mode. You must switch to HTTPS before moving to live mode.
2. The endpoint must be hosted on port 80 or 443. These are the only supported ports.
3. The endpoint must accept HTTP POST requests with a form-encoded body.
Once you have a public URL that Advanced Billing can access, you can begin receiving requests and responding with a `200 OK` status code.
In general, the process for using webhooks is:
1. An event to which your webhook URL is subscribed occurs in Advanced Billing. For example, a new Customer signs up, creating a Subscription.
2. Advanced Billing sends a request to your webhook URL containing the event data.
3. Your system receives the event data.
4. You [verify the event](https://developers.maxio.com/http/getting-started/webhooks/webhooks#verifying-events) data using signature validation.
5. You take action based on the event data, such as sending a welcome email or provisioning services.
6. You respond with `200 OK`, completing the webhook transaction.
Webhooks are sent as HTTP POST requests with a `Content-Type` of `application/x-www-form-urlencoded`, making them easy to parse in most programming languages.
Webhooks contain the following keys:
| Key | Description |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | A unique numeric identifier for the webhook. Use this value to track which webhooks you've already processed. |
| `event` | An identifier for the type of event that occurred. See the list of [events](https://developers.maxio.com/http/getting-started/webhooks/webhooks-reference#events)|
| `payload` | A “hash” of pertinent data about the event. Keys and sub-keys in the hash are denoted using square bracket notation in the key. For example, the product name would be included as the following form-encoded key-value pair in the content body of a `signup_success` webhook: `payload[subscription][product][name]=Basic` |
# Timestamps
Timestamps in webhook payloads use the site's configured timezone. Some newer event types (e.g., `component_allocation_change`, `metered_usage`) use ISO 8601 format in UTC for consistency across systems.
# Limitations
Advanced Billing imposes two limitations on webhooks:
- **Data retention**: Controls how long webhook data is stored.
- **Endpoint limits**: Restricts the number of webhook endpoints per site.
For more information, see [Merchant Limits](https://docs.maxio.com/hc/en-us/articles/24183916903309-Merchant-Limits#merchant-limits-0-0).
# Configuring Webhooks
You can configure webhooks and test connectivity between your URL and Advanced Billing [in the UI](https://docs.maxio.com/hc/en-us/articles/24286723085197-Webhooks#webhooks-0-0) or through the [API](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/webhooks/create-endpoint). You can enable or disable webhooks as needed.
Each webhook includes:
- A URL
- A set of [events](https://developers.maxio.com/http/getting-started/webhooks/webhooks-reference#events) you subscribe to
# Verifying Events
Webhooks include a signature generated using HMAC-SHA-256 with your site’s shared key and the raw body of the POST request.
Ruby example:
```ruby
OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), site.shared_key, webhook.body)
```
To verify events, validate that the signature included with the request matches exactly what is expected given the content being delivered.
You may either retrieve the signature value from the header `X-Chargify-Webhook-Signature-Hmac-Sha-256` or by specifying that the signature should be included in the query string by using the `{signature_hmac_sha_256} `replacement variable:
```http
http://example.com/?signature={signature_hmac_sha_256}
```
> **Note**:
> When in doubt, verify webhook data by checking the current resource state using the API.
## Finding Your Site Shared Key
Your Site’s shared key is created automatically. You can view or update it by selecting **Edit Current Site** from the **Site** drop-down menu in the utility bar. Protect your site’s shared key as you would your password. A compromised shared key could allow malicious actors to generate falsified webhooks that pass signature verification.
# Testing Webhooks
For initial testing, there are a number of options that you can use.
Before you have a publicly accessible endpoint available for troubleshooting, you could use a tool like [Webhook.site](https://webhook.site), which provides a temporary URL that Advanced Billing can send messages to, allowing you to view them within the Webhook.site application. The "bins" are temporary. This can provide insight into the content or headers Advanced Billing will be sending.
You can use the [Webhooks Control Panel](https://docs.maxio.com/hc/en-us/articles/24266161680781-Monitor-and-Resend-Webhooks) in the UI to send test webhook data to any configured endpoint. This feature lets you verify the operational status of your endpoint, though the payload may not match production webhooks. Test webhooks include the following payload:
`id=123456&event=test&payload[chargify]=testing`
For comprehensive testing, use [a sandbox account](https://app.chargify.com/signup/maxio-billing-sandbox) to create test subscriptions and perform actions that trigger webhooks.
The following steps represent a typical flow for testing the receipt of webhooks:
1. Setup publicly accessible webhook handler.
2. Enable webhooks at that endpoint, enable events you need to interact with (at the very least `subscription_state_change`, triggered when subscriptions move from active to cancelled).
3. Send a test event.
4. Check your signature verification code, check that you are responding `200 OK`.
5. Add the specific event processing code you need.
# Responding to a Webhook
Upon receipt of a webhook, accept it by returning an HTTP `200 OK` response as quickly as possible. Sending any other response (i.e. `500 Internal Server Error`, `404 Not Found`, etc.) OR failing to return a response within approximately 15 seconds results in automatic retries of the webhooks.
Advanced Billing attempts to send each webhook event up to five times before giving up. The retries follow an approximate backoff schedule:
| Attempt | Approximate Timing |
| ------- | -------------------------------------------- |
| 1 | As soon as possible after the original event |
| 2 | \~10 seconds after the most recent failure |
| 3 | \~15 seconds after the most recent failure |
| 4 | \~90 seconds after the most recent failure |
| 5 | \~180 seconds after the most recent failure |
If you use the webhook replay feature via the [webhook API](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/webhooks/replay-webhooks) or the webhook panel, avoid duplicate actions by following these suggestions:
- Use the unique webhook ID to track which webhooks you’ve already processed.
- Do not replay webhooks until the last_sent_at timestamp is well outside the automatic retry intervals.
## Inoperative Endpoints
Temporary or abandoned webhook endpoints can strain the system. If repeated failures occur, Advanced Billing may pause or disable the endpoint. Below are examples of failure counts and their associated states:
| Failure Count | State | System Behavior |
| ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 to 25 | Enabled | Retries proceed automatically |
| 26 to 50 | Paused | Webhooks are generated in a paused state and must be manually sent using the webhooks panel. The endpoint is checked every two hours for responsiveness and re-enabled if functional. |
| 51 and over | Disabled | Webhooks are no longer generated for this endpoint. |
> ❗️If you delete an endpoint from Advanced Billing, any paused webhooks referencing that endpoint cannot be resent and are effectively discarded.
# Best Practices
Keep in mind the following best practices when using webhooks:
- Webhooks are **asynchronous**. Do not rely on them for time-sensitive actions.
- Do not block users from signing up or provisioning based on webhook responses. Instead, verify Subscriptions through the API.
#### Webhooks Reference
Source: https://developers.maxio.com/http/getting-started/webhooks/webhooks-reference
Webhook events are triggered by key actions and changes within Advanced Billing, providing notifications about billing, subscription, payment, and account activities. Each event includes a structured payload with relevant data, allowing you to automate workflows, synchronize systems, or log activity for auditing and analysis.
If you’re using the [enhanced Catalog experience](https://developers.maxio.com/http/help/announcements/2026-announcements#new-catalog-experience-and-terminology), you’ll see updated naming in webhook events and messages.
Event name changes:
- subscription_product_change → subscription_plan_change
- component_allocation_change → allocation_change
- component_billing_date_change → product_billing_date_change
Message updates:
- “Successful payment for allocation changes to Product on Subscription”
- “Failed payment for allocation changes to Product on Subscription”
- “Plan changed on Subscription from previous plan to new plan”
# Payloads
The resource objects sent as payloads typically contain the same information as the corresponding API resource. For example, Site payload objects include the site’s id and subdomain. However, not all values may be populated in the payload. Use discretion to determine whether the data is available and how to handle missing information. For example, the reason_code data is not delivered in a signup_success webhook.
Webhooks retain their event and payload data. Refer to the [webhook API](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/webhooks/list-webhooks) for detailed attribute documentation.
## Webhook metadata
Webhook records include metadata about their acceptance or rejection by your application, as well as details about errors encountered during delivery attempts. Metadata attributes include:
- **id**: Unique identifier for the webhook, consistent across retries/replays.
- **successful**: Boolean indicating whether the webhook was accepted on its last attempt.
- **created_at**: Timestamp for when the webhook was created.
- **accepted_at**: Timestamp for when the webhook was successfully accepted Once a webhook is accepted, the accepted_at timestamp will be filled. This timestamp can be viewed via the Webhooks API or in the Webhooks panel, if available for your plan.
- **last_sent_at**: Timestamp for the most recent delivery attempt.
- **last_error_at**: Timestamp for the last failed delivery attempt.
- **last_error**: Description of the error from the last failed attempt.
# Events
## billing_date_change
**Trigger:** Any change to the billing date that is initiated explicitly by altering the billing date through the application or the API. This will not be triggered by a normal renewal and period advancement, or a migration.
**Payload Fields:** event_id, site, subscription (with previous_billing_date)
The subscription object also contains information on the Customer and Product.
> Note
> Multiple webhook events may be triggered by a single system event. For example, the creation of a new Subscription will typically fire both a signup_success and payment_success event (if a payment was necessary to start the Subscription).
## Full payload example
```json
{"site"=>{"id"=>31615, "subdomain"=>"general-goods"},
"subscription"=>
{"id"=>16372192,
"state"=>"active",
"trial_started_at"=>nil,
"trial_ended_at"=>nil,
"activated_at"=>Mon, 13 Feb 2025 11:50:57 EST -05:00,
"created_at"=>Mon, 13 Feb 2025 11:50:55 EST -05:00,
"updated_at"=>Mon, 13 Feb 2025 13:39:20 EST -05:00,
"expires_at"=>nil,
"balance_in_cents"=>0,
"current_period_ends_at"=>Thu, 13 Apr 2025 14:28:00 EDT -04:00,
"next_assessment_at"=>Thu, 13 Apr 2025 14:28:00 EDT -04:00,
"canceled_at"=>nil,
"cancellation_message"=>nil,
"next_product_id"=>nil,
"cancel_at_end_of_period"=>false,
"payment_collection_method"=>"automatic",
"snap_day"=>nil,
"cancellation_method"=>nil,
"current_period_started_at"=>Mon, 13 Feb 2025 13:28:05 EST -05:00,
"previous_state"=>"active",
"signup_payment_id"=>173961106,
"signup_revenue"=>"60.00",
"delayed_cancel_at"=>nil,
"coupon_code"=>nil,
"total_revenue_in_cents"=>22000,
"product_price_in_cents"=>5000,
"product_version_number"=>1,
"payment_type"=>"credit_card",
"referral_code"=>"cz8wdq",
"coupon_use_count"=>nil,
"coupon_uses_allowed"=>nil,
"product_price_point_id"=>1,
"next_product_price_point_id"=>nil,
"customer"=>
{"id"=>15826583,
"first_name"=>"Doris",
"last_name"=>"Tester",
"organization"=>"Acme",
"email"=>"doris@example.com",
"created_at"=>Mon, 13 Feb 2025 11:50:55 EST -05:00,
"updated_at"=>Mon, 13 Feb 2025 11:50:58 EST -05:00,
"reference"=>"123456789",
"address"=>"123 Anywhere Street",
"address_2"=>"",
"city"=>"Boston",
"state"=>"MA",
"zip"=>"02120",
"country"=>"US",
"phone"=>"555-555-1212",
"portal_invite_last_sent_at"=>Mon, 13 Feb 2025 11:50:58 EST -05:00,
"portal_invite_last_accepted_at"=>nil,
"verified"=>nil,
"portal_customer_created_at"=>Mon, 13 Feb 2025 11:50:58 EST -05:00,
"vat_number"=>"123456789"
"cc_emails"=>nil,
"tax_exempt"=>false,
"parent_id"=>nil},
"product"=>
{"id"=>4442358,
"name"=>"Gold Product",
"handle"=>"gold-product",
"description"=>"",
"accounting_code"=>"",
"request_credit_card"=>true,
"expiration_interval"=>nil,
"expiration_interval_unit"=>"never",
"created_at"=>Thu, 15 Dec 2024 09:32:36 EST -05:00,
"updated_at"=>Thu, 15 Dec 2024 09:32:36 EST -05:00,
"price_in_cents"=>5000,
"interval"=>1,
"interval_unit"=>"month",
"initial_charge_in_cents"=>nil,
"trial_price_in_cents"=>nil,
"trial_interval"=>nil,
"trial_interval_unit"=>"month",
"archived_at"=>nil,
"require_credit_card"=>true,
"return_params"=>"",
"taxable"=>false,
"update_return_url"=>"http://www.example.com",
"initial_charge_after_trial"=>false,
"version_number"=>1,
"update_return_params"=>"id={subscription_id}&ref={customer_reference}",
"default_product_price_point_id"=>1,
"product_price_point_id"=>1,
"product_price_point_handle"=>nil,
"product_family"=>
{"id"=>986840,
"name"=>"Acme Products",
"description"=>"",
"handle"=>"acme-products",
"accounting_code"=>nil},
"public_signup_pages"=>
[{"id"=>306012,
"return_url"=>"",
"return_params"=>"",
"url"=>
"https://general-goods.chargifypay.com/subscribe/7dbsnjd8t8cx/gold-product"},
{"id"=>310598,
"return_url"=>"",
"return_params"=>"",
"url"=>
"https://general-goods.chargifypay.com/subscribe/ksjh9py5fn5h/gold-product"},
{"id"=>311132,
"return_url"=>"",
"return_params"=>"",
"url"=>
"https://general-goods.chargifypay.com/subscribe/kjmks49g8d3d/gold-product"}]},
"credit_card"=>
{"id"=>10914352,
"first_name"=>"Doris",
"last_name"=>"Tester",
"masked_card_number"=>"XXXX-XXXX-XXXX-1111",
"card_type"=>"visa",
"expiration_month"=>2,
"expiration_year"=>2018,
"customer_id"=>15826583,
"current_vault"=>"bogus",
"vault_token"=>"1",
"billing_address"=>"",
"billing_city"=>"",
"billing_state"=>"",
"billing_zip"=>"",
"billing_country"=>"",
"customer_vault_token"=>nil,
"billing_address_2"=>"",
"payment_type"=>"credit_card"},
"previous_billing_date"=>Mon, 13 Mar 2025 14:28:05 EDT -04:00},
"event_id"=>377604301}
```
## component_allocation_change
**Trigger:** Any change to the Subscription quantity-based component allocation, enabled status of an on/off component, or a purchase of a prepaid component allocation that is made _after_ signup. This webhook does not fire if allocations are configured during the initial Subscription creation (signup). `previous_allocation` and `new_allocation` give the allocation values before and after the change. These will be either `0` or `1` for On/Off Components to represent `off` and `on`, respectively. `timestamp` provides the date and time the allocation was recorded and is listed in ISO8601 format in the UTC timezone.
**Payload Fields:** event_id, site, component, subscription, product, previous_allocation, new_allocation, memo, timestamp
## Full payload example for On/Off Component Change
```json
"component"=>
{"id"=>375117,
"kind"=>"on_off_component",
"name"=>"Cancellation fee",
"unit_name"=>"on/off"},
"subscription"=>{"id"=>16372192, "name"=>"Doris Tester"},
"product"=>{"id"=>4443536, "name"=>"Business Monthly"},
"memo"=>"Adding cancellation fee for Doris",
"timestamp"=>"2025-02-13T18:46:49Z",
"previous_allocation"=>0,
"new_allocation"=>1,
"payment"=>nil,
"event_id"=>377608723}
```
## Full payload example for Quantity-based Component Change
```json
"component"=>
{"id"=>375250,
"kind"=>"quantity_based_component",
"name"=>"Quantity Component",
"unit_name"=>"Quantity Component"},
"subscription"=>{"id"=>16372192, "name"=>"Doris Tester"},
"product"=>{"id"=>4443536, "name"=>"Business Monthly"},
"memo"=>"Adding 90 components for Doris",
"timestamp"=>"2025-02-13T18:49:58Z",
"previous_allocation"=>10,
"new_allocation"=>90,
"payment"=>
{"id"=>1078634,
"success"=>true,
"amount_in_cents"=>800,
"memo"=>"Payment for: Full-price component allocation changes."},
"event_id"=>377609562}
```
## Full payload example for Prepaid Component Change
```json
"component"=>
{"id"=>957864,
"kind"=>"prepaid_usage_component",
"name"=>"Minutes",
"unit_name"=>"minutes",
"handle"=>nil},
"subscription"=>
{"id"=>32304660,
"name"=>"Mario Smith",
"organization"=>"",
"state"=>"active",
"product"=>
{"id"=>4607690,
"product_price_point_id"=>322106,
"product_price_point_handle"=>"uuid:8e1f3840-c44a-0136-fd09-02d0e580fd36",
"name"=>"v-1",
"interval"=>1,
"interval_unit"=>"month"}},
"product"=>
{"id"=>4607690,
"name"=>"Silver Plan",
"interval"=>1,
"interval_unit"=>"month"},
"allocation"=>
{"id"=>571895482,
"proration_upgrade_scheme"=>"full-price-attempt-capture",
"proration_downgrade_scheme"=>"no-prorate"},
"previous_allocation"=>0,
"new_allocation"=>10,
"memo"=>"",
"timestamp"=>"2025-04-28T18:34:28Z",
"price_point_id"=>821647,
"payment"=>
{"id"=>381732923,
"success"=>true,
"amount_in_cents"=>2000,
"memo"=>"Payment for: Full-price component allocation changes."},
"allocated_quantity"=>10,
"expires_at"=>nil,
"renews"=>true,
"total_used"=>0,
"total_overage"=>0,
"event_id"=>1064815277}
```
## chjs_tokenization_failure
**Trigger:** Maxio.js (formerly Chargify.js) failed to tokenize a payment profile at the payment gateway (for example, a declined test card or a gateway error). The event is recorded when tokenization is attempted through `POST /js/tokens` and the gateway returns an error. Failures that occur before tokenization (such as reCAPTCHA, fraud blocking, or an invalid security token) do not trigger this event.
**Payload Fields:** event_id, site, errors, payment_profile_params
## Full payload example
```json
{
"site": {
"id": 1,
"subdomain": "acme"
},
"errors": "Card was declined",
"payment_profile_params": {
"first_name": "John",
"last_name": "Doe",
"card_type": "visa"
},
"event_id": 12346
}
```
## chjs_tokenization_success
**Trigger:** Maxio.js successfully tokenized a payment profile at the payment gateway. The event is recorded when tokenization completes through `POST /js/tokens` during public signup pages, self-service flows, or other Maxio.js integrations.
**Payload Fields:** event_id, site, payment_profile, gateway_customer_id
## Full payload example
```json
{
"site": {
"id": 1,
"subdomain": "acme"
},
"payment_profile": {
"id": 987,
"vault_token": "1",
"gateway_handle": "default",
"customer_vault_token": "cus_example"
},
"gateway_customer_id": 456,
"event_id": 12345
}
```
## custom_field_value_change
**Trigger:** A change to any custom field value, whether adding a custom field at signup, or updating a custom field on an existing Subscription or Customer record.
**Payload Fields:** See full payload example.
## Full payload example
```json
{"site"=>{"id"=>60050, "subdomain"=>"chargify-sandbox-141"},
"metafield"=>
{"event_type"=>"created",
"metafield_name"=>"Device ID",
"metafield_id"=>31483,
"old_value"=>nil,
"new_value"=>"dev_7hbd)jh27gyJ",
"resource_type"=>"Subscription",
"resource_id"=>63081463},
"event_id"=>2946240555}
```
## customer_create
**Trigger:** A new customer is created.
**Payload Fields:** event_id, site, customer
## Full payload example
```json
{"address"=>"123 Main St",
"address_2"=>"Apt 123",
"city"=>"Pleasantville",
"country"=>"US",
"created_at"=>"2025-09-09 11:38:32 -0400",
"email"=>"john@example.com",
"first_name"=>"John",
"id"=>"0",
"last_name"=>"Doe",
"organization"=>"Acme, Inc.",
"phone"=>"555-555-1234",
"reference"=>"johndoe",
"state"=>"NC",
"updated_at"=>"2025-09-09 11:38:32 -0400",
"zip"=>"12345",
"parent_id"=>nil},
"site"=>{"id"=>2, "subdomain"=>"acme"},
"event_id"=>855147013}
```
## customer_delete
**Trigger:** When a customer is deleted. _Note_: This webhook is **not** triggered by the deletion of a Subscription and Customer simultaneously; it is only triggered by explicitly deleting the customer as a single action.
**Payload Fields:** See full payload example.
## Full payload example
```json
{"customer"=>
{"id"=>59200671,
"first_name"=>"Harrison",
"last_name"=>"Ankunding",
"organization"=>"Jacobs and Sons",
"email"=>"Mellie.Lindgren80@example.org",
"created_at"=>Fri, 07 Oct 2025 12:53:42 PDT -07:00,
"updated_at"=>Fri, 07 Oct 2025 12:53:58 PDT -07:00,
"reference"=>nil,
"address"=>"303 Mozell Summit",
"address_2"=>"Suite 602",
"city"=>"East Emie",
"state"=>"CO",
"zip"=>"25924",
"country"=>"US",
"phone"=>"484-328-6314",
"portal_invite_last_sent_at"=>nil,
"portal_invite_last_accepted_at"=>nil,
"verified"=>false,
"portal_customer_created_at"=>Fri, 07 Oct 2025 12:53:58 PDT -07:00,
"vat_number"=>nil,
"cc_emails"=>nil,
"tax_exempt"=>false,
"parent_id"=>nil,
"locale"=>nil},
"site"=>{"id"=>60050, "subdomain"=>"chargify-sandbox-141"},
"event_id"=>2946257113}
```
## customer_update
**Trigger:** Any change to the following Customer fields: first_name, last_name, organization, email, reference, address, address 2, city, state, zip, country, phone, vat_number, parent_id, cc_email.
**Payload Fields:** event_id, site, customer
## Full payload example
```json
{"id"=>15826583,
"first_name"=>"Doris",
"last_name"=>"Tester",
"organization"=>"Acme",
"email"=>"doristester@example.com",
"created_at"=>Mon, 13 Feb 2025 11:50:55 EST -05:00,
"updated_at"=>Mon, 13 Feb 2025 13:42:07 EST -05:00,
"reference"=>"123456789",
"address"=>"123 Anywhere Street",
"address_2"=>"",
"city"=>"Boston",
"state"=>"MA",
"zip"=>"02120",
"country"=>"US",
"phone"=>"555-555-1212",
"portal_invite_last_sent_at"=>Mon, 13 Feb 2025 11:50:55 EST -05:00,
"portal_invite_last_accepted_at"=>Mon, 13 Feb 2025 12:50:55 EST -05:00,
"verified"=>false,
"portal_customer_created_at"=>Mon, 13 Feb 2025 11:50:55 EST -05:00,
"vat_number"=>737291901,
"cc_emails"=>nil,
"tax_exempt"=>false,
"parent_id"=>7
},
"site"=>{"id"=>31615, "subdomain"=>"general-goods"},
"event_id"=>377607274}
```
## delayed_subscription_creation_failure
**Trigger:** A failure to create a delayed Subscription.
**Payload Fields:** event_id, site, subscription
## Full payload example
```json
{"subscription"=>
{"id"=>63126445,
"state"=>"pending",
"trial_started_at"=>nil,
"trial_ended_at"=>nil,
"activated_at"=>nil,
"created_at"=>Fri, 10 Mar 2025 09:19:03 PST -08:00,
"updated_at"=>Fri, 10 Mar 2025 09:19:03 PST -08:00,
"expires_at"=>nil,
"balance_in_cents"=>0,
"current_period_ends_at"=>nil,
"next_assessment_at"=>nil,
"canceled_at"=>nil,
"cancellation_message"=>nil,
"next_product_id"=>nil,
"next_product_handle"=>nil,
"cancel_at_end_of_period"=>nil,
"payment_collection_method"=>"automatic",
"snap_day"=>nil,
"cancellation_method"=>nil,
"current_period_started_at"=>Fri, 10 Mar 2025 09:19:03 PST -08:00,
"previous_state"=>"pending",
"signup_payment_id"=>0,
"signup_revenue"=>"0.00",
"delayed_cancel_at"=>nil,
"coupon_code"=>nil,
"total_revenue_in_cents"=>0,
"product_price_in_cents"=>10000,
"product_version_number"=>1,
"payment_type"=>"credit_card",
"referral_code"=>"4t9cnw",
"coupon_use_count"=>nil,
"coupon_uses_allowed"=>nil,
"reason_code"=>nil,
"automatically_resume_at"=>nil,
"coupon_codes"=>[],
"offer_id"=>nil,
"payer_id"=>64300587,
"receives_invoice_emails"=>nil,
"product_price_point_id"=>898846,
"next_product_price_point_id"=>nil,
"credit_balance_in_cents"=>0,
"prepayment_balance_in_cents"=>0,
"net_terms"=>nil,
"stored_credential_transaction_id"=>nil,
"locale"=>nil,
"reference"=>nil,
"currency"=>"USD",
"on_hold_at"=>nil,
"scheduled_cancellation_at"=>nil,
"prepaid_dunning"=>false,
"product_price_point_type"=>"default",
"dunning_communication_delay_enabled"=>false,
"dunning_communication_delay_time_zone"=>nil,
"customer"=>
{"id"=>64300587,
"first_name"=>"Summer",
"last_name"=>"Bayer",
"organization"=>"Fay - Rowe",
"email"=>"Carolyn.Gutmann@example.net",
"created_at"=>Fri, 10 Mar 2025 09:18:29 PST -08:00,
"updated_at"=>Fri, 10 Mar 2025 09:18:29 PST -08:00,
"reference"=>nil,
"address"=>"407 Bogisich Roads",
"address_2"=>"Suite 406",
"city"=>"New Daniella",
"state"=>"IA",
"state_name"=>"Iowa",
"zip"=>"17933",
"country"=>"US",
"country_name"=>"United States",
"phone"=>"964-327-5176",
"portal_invite_last_sent_at"=>nil,
"portal_invite_last_accepted_at"=>nil,
"verified"=>false,
"portal_customer_created_at"=>nil,
"vat_number"=>nil,
"cc_emails"=>nil,
"tax_exempt"=>false,
"parent_id"=>nil,
"locale"=>nil},
"product"=>
{"id"=>5209515,
"name"=>"Bronze Plan",
"handle"=>"bronze_plan",
"description"=>"my description",
"accounting_code"=>nil,
"request_credit_card"=>true,
"expiration_interval"=>nil,
"expiration_interval_unit"=>nil,
"created_at"=>Fri, 13 Mar 2025 14:32:26 PDT -07:00,
"updated_at"=>Fri, 13 Mar 2025 14:32:26 PDT -07:00,
"price_in_cents"=>10000,
"interval"=>1,
"interval_unit"=>"month",
"initial_charge_in_cents"=>nil,
"trial_price_in_cents"=>nil,
"trial_interval"=>nil,
"trial_interval_unit"=>nil,
"archived_at"=>nil,
"require_credit_card"=>true,
"return_params"=>nil,
"taxable"=>false,
"update_return_url"=>nil,
"tax_code"=>nil,
"initial_charge_after_trial"=>false,
"version_number"=>1,
"update_return_params"=>nil,
"default_product_price_point_id"=>898846,
"request_billing_address"=>false,
"require_billing_address"=>false,
"require_shipping_address"=>false,
"use_site_exchange_rate"=>true,
"item_category"=>nil,
"product_price_point_id"=>898846,
"product_price_point_name"=>"Original",
"product_price_point_handle"=>"uuid:0edd1580-47a0-0138-6907-060451d6a6ae",
"product_family"=>
{"id"=>1513518,
"name"=>"import test",
"description"=>"",
"handle"=>"import-test",
"accounting_code"=>nil,
"created_at"=>Wed, 11 Mar 2025 09:45:14 PDT -07:00,
"updated_at"=>Wed, 11 Mar 2025 09:45:14 PDT -07:00},
"public_signup_pages"=>[]},
"credit_card"=>
{"id"=>50327544,
"first_name"=>"Gus",
"last_name"=>"Terry",
"masked_card_number"=>"XXXX-XXXX-XXXX-3",
"card_type"=>"bogus",
"expiration_month"=>3,
"expiration_year"=>2024,
"customer_id"=>64300587,
"current_vault"=>nil,
"vault_token"=>nil,
"billing_address"=>"172 Abernathy Mountain",
"billing_city"=>"North Lornachester",
"billing_state"=>"CA",
"billing_zip"=>"63011-5354",
"billing_country"=>"US",
"customer_vault_token"=>nil,
"billing_address_2"=>"Suite 227",
"payment_type"=>"credit_card",
"disabled"=>false,
"site_gateway_setting_id"=>nil,
"gateway_handle"=>nil},
"prepaid_configuration"=>nil,
"group"=>nil,
"initial_billing_at"=>Sat, 01 Apr 2025 05:00:00 PDT -07:00},
"site"=>{"id"=>60050, "subdomain"=>"chargify-sandbox-141"},
"event_id"=>2950983304}
```
## delayed_subscription_creation_success
**Trigger:** Successful creation of a delayed Subscription in an awaiting signup state.
**Payload Fields:** event_id, site, subscription
## Full payload example
```json
{"subscription"=>
{"id"=>63126383,
"state"=>"awaiting_signup",
"trial_started_at"=>nil,
"trial_ended_at"=>nil,
"activated_at"=>nil,
"created_at"=>Fri, 10 Mar 2025 09:16:28 PST -08:00,
"updated_at"=>Fri, 10 Mar 2025 09:16:28 PST -08:00,
"expires_at"=>nil,
"balance_in_cents"=>0,
"current_period_ends_at"=>Sat, 01 Apr 2025 05:00:00 PDT -07:00,
"next_assessment_at"=>Sat, 01 Apr 2025 05:00:00 PDT -07:00,
"canceled_at"=>nil,
"cancellation_message"=>nil,
"next_product_id"=>nil,
"next_product_handle"=>nil,
"cancel_at_end_of_period"=>nil,
"payment_collection_method"=>"automatic",
"snap_day"=>nil,
"cancellation_method"=>nil,
"current_period_started_at"=>Fri, 10 Mar 2025 09:16:28 PST -08:00,
"previous_state"=>"awaiting_signup",
"signup_payment_id"=>0,
"signup_revenue"=>"0.00",
"delayed_cancel_at"=>nil,
"coupon_code"=>nil,
"total_revenue_in_cents"=>0,
"product_price_in_cents"=>10000,
"product_version_number"=>1,
"payment_type"=>"credit_card",
"referral_code"=>"w376jg",
"coupon_use_count"=>nil,
"coupon_uses_allowed"=>nil,
"reason_code"=>nil,
"automatically_resume_at"=>nil,
"coupon_codes"=>[],
"offer_id"=>nil,
"payer_id"=>64300481,
"receives_invoice_emails"=>nil,
"product_price_point_id"=>898846,
"next_product_price_point_id"=>nil,
"credit_balance_in_cents"=>0,
"prepayment_balance_in_cents"=>0,
"net_terms"=>nil,
"stored_credential_transaction_id"=>nil,
"locale"=>nil,
"reference"=>nil,
"currency"=>"USD",
"on_hold_at"=>nil,
"scheduled_cancellation_at"=>nil,
"prepaid_dunning"=>false,
"product_price_point_type"=>"default",
"dunning_communication_delay_enabled"=>false,
"dunning_communication_delay_time_zone"=>nil,
"customer"=>
{"id"=>64300481,
"first_name"=>"Leonie",
"last_name"=>"Hickle",
"organization"=>"McCullough, Bogisich and Bayer",
"email"=>"Cortney.Gulgowski59@example.com",
"created_at"=>Fri, 10 Mar 2025 09:15:24 PST -08:00,
"updated_at"=>Fri, 10 Mar 2025 09:15:24 PST -08:00,
"reference"=>nil,
"address"=>"064 Gislason Hollow",
"address_2"=>"Suite 099",
"city"=>"Lindberg",
"state"=>"NC",
"state_name"=>"North Carolina",
"zip"=>"39203-7738",
"country"=>"US",
"country_name"=>"United States",
"phone"=>"308-857-8585",
"portal_invite_last_sent_at"=>nil,
"portal_invite_last_accepted_at"=>nil,
"verified"=>false,
"portal_customer_created_at"=>nil,
"vat_number"=>nil,
"cc_emails"=>nil,
"tax_exempt"=>false,
"parent_id"=>nil,
"locale"=>nil},
"product"=>
{"id"=>5209515,
"name"=>"Bronze Plan",
"handle"=>"bronze_plan",
"description"=>"my description",
"accounting_code"=>nil,
"request_credit_card"=>true,
"expiration_interval"=>nil,
"expiration_interval_unit"=>nil,
"created_at"=>Fri, 13 Mar 2025 14:32:26 PDT -07:00,
"updated_at"=>Fri, 13 Mar 2025 14:32:26 PDT -07:00,
"price_in_cents"=>10000,
"interval"=>1,
"interval_unit"=>"month",
"initial_charge_in_cents"=>nil,
"trial_price_in_cents"=>nil,
"trial_interval"=>nil,
"trial_interval_unit"=>nil,
"archived_at"=>nil,
"require_credit_card"=>true,
"return_params"=>nil,
"taxable"=>false,
"update_return_url"=>nil,
"tax_code"=>nil,
"initial_charge_after_trial"=>false,
"version_number"=>1,
"update_return_params"=>nil,
"default_product_price_point_id"=>898846,
"request_billing_address"=>false,
"require_billing_address"=>false,
"require_shipping_address"=>false,
"use_site_exchange_rate"=>true,
"item_category"=>nil,
"product_price_point_id"=>898846,
"product_price_point_name"=>"Original",
"product_price_point_handle"=>"uuid:0edd1580-47a0-0138-6907-060451d6a6ae",
"product_family"=>
{"id"=>1513518,
"name"=>"import test",
"description"=>"",
"handle"=>"import-test",
"accounting_code"=>nil,
"created_at"=>Wed, 11 Mar 2025 09:45:14 PDT -07:00,
"updated_at"=>Wed, 11 Mar 2025 09:45:14 PDT -07:00},
"public_signup_pages"=>[]},
"credit_card"=>
{"id"=>50327479,
"first_name"=>"Romaine",
"last_name"=>"Grimes",
"masked_card_number"=>"XXXX-XXXX-XXXX-1111",
"card_type"=>"visa",
"expiration_month"=>3,
"expiration_year"=>2024,
"customer_id"=>64300481,
"current_vault"=>"bogus",
"vault_token"=>"1",
"billing_address"=>"8193 Abner Greens",
"billing_city"=>"Westland",
"billing_state"=>"NM",
"billing_zip"=>"48592",
"billing_country"=>"US",
"customer_vault_token"=>nil,
"billing_address_2"=>"Suite 544",
"payment_type"=>"credit_card",
"disabled"=>false,
"site_gateway_setting_id"=>nil,
"gateway_handle"=>nil},
"prepaid_configuration"=>nil,
"group"=>nil,
"initial_billing_at"=>Sat, 01 Apr 2025 05:00:00 PDT -07:00,
"referred_by"=>nil},
"site"=>{"id"=>60050, "subdomain"=>"chargify-sandbox-141"},
"event_id"=>2950981186}
```
## direct_debit_payment_paid_out
**Trigger:** When Direct Debit Payment was successfully processed in the gateway (currently, only Stripe and GoCardless are supported).
**Payload Fields:** event_id, site, subscription, transaction
## Full payload example
```json
"subscription"=>
{"id"=>102485,
"state"=>"active",
"trial_started_at"=>nil,
"trial_ended_at"=>nil,
"activated_at"=>Thu, 25 Feb 2021 03:33:01 EST -05:00,
"created_at"=>Thu, 25 Feb 2021 03:32:54 EST -05:00,
"updated_at"=>Thu, 25 Feb 2021 03:33:10 EST -05:00,
"expires_at"=>nil,
"balance_in_cents"=>0,
"current_period_ends_at"=>Thu, 25 Mar 2021 04:32:54 EDT -04:00,
"next_assessment_at"=>Thu, 25 Mar 2021 04:32:54 EDT -04:00,
"canceled_at"=>nil,
"cancellation_message"=>nil,
"next_product_id"=>nil,
"next_product_handle"=>nil,
"cancel_at_end_of_period"=>nil,
"payment_collection_method"=>"automatic",
"snap_day"=>nil,
"cancellation_method"=>nil,
"current_period_started_at"=>Thu, 25 Feb 2021 03:32:54 EST -05:00,
"previous_state"=>"active",
"signup_payment_id"=>34793,
"signup_revenue"=>"30,00",
"delayed_cancel_at"=>nil,
"coupon_code"=>nil,
"total_revenue_in_cents"=>3000,
"product_price_in_cents"=>3000,
"product_version_number"=>1,
"payment_type"=>"bank_account",
"referral_code"=>nil,
"coupon_use_count"=>nil,
"coupon_uses_allowed"=>nil,
"reason_code"=>nil,
"automatically_resume_at"=>nil,
"coupon_codes"=>[],
"offer_id"=>nil,
"payer_id"=>nil,
"receives_invoice_emails"=>nil,
"product_price_point_id"=>466,
"next_product_price_point_id"=>nil,
"credit_balance_in_cents"=>0,
"prepayment_balance_in_cents"=>0,
"net_terms"=>nil,
"stored_credential_transaction_id"=>nil,
"locale"=>nil,
"reference"=>nil,
"currency"=>"EUR",
"on_hold_at"=>nil,
"scheduled_cancellation_at"=>nil,
"customer"=>
{"id"=>4260,
"first_name"=>"Test",
"last_name"=>"Test",
"organization"=>"",
"email"=>"test@example.com",
"created_at"=>Thu, 25 Feb 2021 03:32:53 EST -05:00,
"updated_at"=>Thu, 25 Feb 2021 03:32:53 EST -05:00,
"reference"=>nil,
"address"=>nil,
"address_2"=>nil,
"city"=>nil,
"state"=>nil,
"state_name"=>nil,
"zip"=>nil,
"country"=>nil,
"country_name"=>nil,
"phone"=>"",
"portal_invite_last_sent_at"=>nil,
"portal_invite_last_accepted_at"=>nil,
"verified"=>false,
"portal_customer_created_at"=>nil,
"vat_number"=>nil,
"cc_emails"=>nil,
"tax_exempt"=>false,
"parent_id"=>nil,
"locale"=>nil},
"product"=>
{"id"=>372,
"name"=>"test",
"handle"=>"test",
"description"=>"",
"accounting_code"=>"",
"request_credit_card"=>true,
"expiration_interval"=>nil,
"expiration_interval_unit"=>"never",
"created_at"=>Wed, 09 Dec 2020 05:06:07 EST -05:00,
"updated_at"=>Thu, 21 Jan 2021 09:28:12 EST -05:00,
"price_in_cents"=>3000,
"interval"=>1,
"interval_unit"=>"month",
"initial_charge_in_cents"=>nil,
"trial_price_in_cents"=>nil,
"trial_interval"=>nil,
"trial_interval_unit"=>"month",
"archived_at"=>nil,
"require_credit_card"=>true,
"return_params"=>"",
"taxable"=>false,
"update_return_url"=>"",
"tax_code"=>"",
"initial_charge_after_trial"=>false,
"version_number"=>1,
"update_return_params"=>"",
"default_product_price_point_id"=>466,
"request_billing_address"=>false,
"require_billing_address"=>false,
"require_shipping_address"=>false,
"product_price_point_id"=>466,
"product_price_point_name"=>"Original",
"product_price_point_handle"=>"uuid:14078c50-1c34-0139-f2b7-08e9fe639598",
"product_family"=>
{"id"=>131,
"name"=>"Billing Plans",
"description"=>nil,
"handle"=>"test-billing-plans",
"accounting_code"=>nil,
"created_at"=>Wed, 09 Dec 2020 04:37:03 EST -05:00,
"updated_at"=>Wed, 09 Dec 2020 04:37:03 EST -05:00},
"public_signup_pages"=>
[{"id"=>199,
"return_url"=>"",
"return_params"=>"",
"url"=>
"https://test-71.chargifypay.test/subscribe/3gx9xh5z8gj2/test"}]},
"bank_account"=>
{"id"=>5847,
"first_name"=>"Test",
"last_name"=>"Test",
"customer_id"=>4260,
"current_vault"=>"stripe_connect",
"vault_token"=>"cus_J0gewnaw35SKLd",
"billing_address"=>nil,
"billing_city"=>nil,
"billing_state"=>nil,
"billing_zip"=>nil,
"billing_country"=>nil,
"customer_vault_token"=>nil,
"billing_address_2"=>nil,
"bank_name"=>nil,
"masked_bank_routing_number"=>nil,
"masked_bank_account_number"=>"XXXX3000",
"bank_account_type"=>"checking",
"bank_account_holder_type"=>"personal",
"payment_type"=>"bank_account",
"verified"=>true,
"site_gateway_setting_id"=>402},
"group"=>nil},
"transaction"=>
{"id"=>34793,
"subscription_id"=>102485,
"type"=>"Payment",
"kind"=>nil,
"transaction_type"=>"payment",
"success"=>true,
"amount_in_cents"=>3000,
"memo"=>"Test Test - test: Signup payment",
"created_at"=>Thu, 25 Feb 2021 03:33:00 EST -05:00,
"starting_balance_in_cents"=>3000,
"ending_balance_in_cents"=>0,
"gateway_used"=>"stripe_connect",
"gateway_transaction_id"=>"pi_1IOfHLKajOcZzbwkfsXCKj1P",
"gateway_order_id"=>nil,
"payment_id"=>nil,
"product_id"=>372,
"tax_id"=>nil,
"component_id"=>nil,
"statement_id"=>24750,
"customer_id"=>4260,
"item_name"=>nil,
"period_range_start"=>nil,
"period_range_end"=>nil,
"currency"=>"EUR",
"exchange_rate"=>1,
"component_handle"=>nil,
"component_price_point_id"=>nil,
"component_price_point_handle"=>nil,
"parent_id"=>nil,
"role"=>nil,
"card_number"=>nil,
"card_expiration"=>nil,
"card_type"=>nil,
"refunded_amount_in_cents"=>0,
"invoice_id"=>nil},
"event_id"=>51601}
```
## direct_debit_payment_pending
**Trigger:** When Direct Debit Payment was created in the gateway and is pending processing (currently, only Stripe and GoCardless are supported).
**Payload Fields:** event_id, site, subscription, transaction
## Full payload example
```json
"subscription"=>
{"id"=>102485,
"state"=>"pending",
"trial_started_at"=>nil,
"trial_ended_at"=>nil,
"activated_at"=>nil,
"created_at"=>Thu, 25 Feb 2021 03:32:54 EST -05:00,
"updated_at"=>Thu, 25 Feb 2021 03:33:00 EST -05:00,
"expires_at"=>nil,
"balance_in_cents"=>0,
"current_period_ends_at"=>nil,
"next_assessment_at"=>nil,
"canceled_at"=>nil,
"cancellation_message"=>nil,
"next_product_id"=>nil,
"next_product_handle"=>nil,
"cancel_at_end_of_period"=>nil,
"payment_collection_method"=>"automatic",
"snap_day"=>nil,
"cancellation_method"=>nil,
"current_period_started_at"=>Thu, 25 Feb 2021 03:32:54 EST -05:00,
"previous_state"=>"pending",
"signup_payment_id"=>34793,
"signup_revenue"=>"30,00",
"delayed_cancel_at"=>nil,
"coupon_code"=>nil,
"total_revenue_in_cents"=>3000,
"product_price_in_cents"=>3000,
"product_version_number"=>1,
"payment_type"=>"bank_account",
"referral_code"=>nil,
"coupon_use_count"=>nil,
"coupon_uses_allowed"=>nil,
"reason_code"=>nil,
"automatically_resume_at"=>nil,
"coupon_codes"=>[],
"offer_id"=>nil,
"payer_id"=>nil,
"receives_invoice_emails"=>nil,
"product_price_point_id"=>466,
"next_product_price_point_id"=>nil,
"credit_balance_in_cents"=>0,
"prepayment_balance_in_cents"=>0,
"net_terms"=>nil,
"stored_credential_transaction_id"=>nil,
"locale"=>nil,
"reference"=>nil,
"currency"=>"EUR",
"on_hold_at"=>nil,
"scheduled_cancellation_at"=>nil,
"customer"=>
{"id"=>4260,
"first_name"=>"Test",
"last_name"=>"Test",
"organization"=>"",
"email"=>"test@example.com",
"created_at"=>Thu, 25 Feb 2021 03:32:53 EST -05:00,
"updated_at"=>Thu, 25 Feb 2021 03:32:53 EST -05:00,
"reference"=>nil,
"address"=>nil,
"address_2"=>nil,
"city"=>nil,
"state"=>nil,
"state_name"=>nil,
"zip"=>nil,
"country"=>nil,
"country_name"=>nil,
"phone"=>"",
"portal_invite_last_sent_at"=>nil,
"portal_invite_last_accepted_at"=>nil,
"verified"=>false,
"portal_customer_created_at"=>nil,
"vat_number"=>nil,
"cc_emails"=>nil,
"tax_exempt"=>false,
"parent_id"=>nil,
"locale"=>nil},
"product"=>
{"id"=>372,
"name"=>"test",
"handle"=>"test",
"description"=>"",
"accounting_code"=>"",
"request_credit_card"=>true,
"expiration_interval"=>nil,
"expiration_interval_unit"=>"never",
"created_at"=>Wed, 09 Dec 2020 05:06:07 EST -05:00,
"updated_at"=>Thu, 21 Jan 2021 09:28:12 EST -05:00,
"price_in_cents"=>3000,
"interval"=>1,
"interval_unit"=>"month",
"initial_charge_in_cents"=>nil,
"trial_price_in_cents"=>nil,
"trial_interval"=>nil,
"trial_interval_unit"=>"month",
"archived_at"=>nil,
"require_credit_card"=>true,
"return_params"=>"",
"taxable"=>false,
"update_return_url"=>"",
"tax_code"=>"",
"initial_charge_after_trial"=>false,
"version_number"=>1,
"update_return_params"=>"",
"default_product_price_point_id"=>466,
"request_billing_address"=>false,
"require_billing_address"=>false,
"require_shipping_address"=>false,
"product_price_point_id"=>466,
"product_price_point_name"=>"Original",
"product_price_point_handle"=>"uuid:14078c50-1c34-0139-f2b7-08e9fe639598",
"product_family"=>
{"id"=>131,
"name"=>"Billing Plans",
"description"=>nil,
"handle"=>"test-billing-plans",
"accounting_code"=>nil,
"created_at"=>Wed, 09 Dec 2020 04:37:03 EST -05:00,
"updated_at"=>Wed, 09 Dec 2020 04:37:03 EST -05:00},
"public_signup_pages"=>
[{"id"=>199,
"return_url"=>"",
"return_params"=>"",
"url"=>
"https://test-71.chargifypay.test/subscribe/3gx9xh5z8gj2/test"}]},
"bank_account"=>
{"id"=>5847,
"first_name"=>"Test",
"last_name"=>"Test",
"customer_id"=>4260,
"current_vault"=>"stripe_connect",
"vault_token"=>"cus_J0gewnaw35SKLd",
"billing_address"=>nil,
"billing_city"=>nil,
"billing_state"=>nil,
"billing_zip"=>nil,
"billing_country"=>nil,
"customer_vault_token"=>nil,
"billing_address_2"=>nil,
"bank_name"=>nil,
"masked_bank_routing_number"=>nil,
"masked_bank_account_number"=>"XXXX3000",
"bank_account_type"=>"checking",
"bank_account_holder_type"=>"personal",
"payment_type"=>"bank_account",
"verified"=>true,
"site_gateway_setting_id"=>402},
"group"=>nil},
"transaction"=>
{"id"=>34793,
"subscription_id"=>102485,
"type"=>"Payment",
"kind"=>nil,
"transaction_type"=>"payment",
"success"=>true,
"amount_in_cents"=>3000,
"memo"=>"Test Test - test: Signup payment",
"created_at"=>Thu, 25 Feb 2021 03:33:00 EST -05:00,
"starting_balance_in_cents"=>3000,
"ending_balance_in_cents"=>0,
"gateway_used"=>"stripe_connect",
"gateway_transaction_id"=>"pi_1IOfHLKajOcZzbwkfsXCKj1P",
"gateway_order_id"=>nil,
"payment_id"=>nil,
"product_id"=>372,
"tax_id"=>nil,
"component_id"=>nil,
"statement_id"=>24750,
"customer_id"=>4260,
"item_name"=>nil,
"period_range_start"=>nil,
"period_range_end"=>nil,
"currency"=>"EUR",
"exchange_rate"=>1,
"component_handle"=>nil,
"component_price_point_id"=>nil,
"component_price_point_handle"=>nil,
"parent_id"=>nil,
"role"=>nil,
"card_number"=>nil,
"card_expiration"=>nil,
"card_type"=>nil,
"refunded_amount_in_cents"=>0,
"invoice_id"=>nil},
"event_id"=>51595}
```
## direct_debit_payment_rejected
**Trigger:** When Direct Debit Payment was rejected in the gateway—for example, due to insufficient funds (currently, only Stripe and GoCardless are supported).
**Payload Fields:** event_id, site, subscription, transaction
## Full payload example
```json
"subscription"=>
{"id"=>102493,
"state"=>"past_due",
"trial_started_at"=>nil,
"trial_ended_at"=>nil,
"activated_at"=>Thu, 25 Feb 2021 05:27:47 EST -05:00,
"created_at"=>Thu, 25 Feb 2021 05:27:38 EST -05:00,
"updated_at"=>Thu, 25 Feb 2021 05:28:06 EST -05:00,
"expires_at"=>nil,
"balance_in_cents"=>3000,
"current_period_ends_at"=>Thu, 25 Mar 2021 06:27:38 EDT -04:00,
"next_assessment_at"=>Fri, 26 Feb 2021 05:28:06 EST -05:00,
"canceled_at"=>nil,
"cancellation_message"=>nil,
"next_product_id"=>nil,
"next_product_handle"=>nil,
"cancel_at_end_of_period"=>nil,
"payment_collection_method"=>"automatic",
"snap_day"=>nil,
"cancellation_method"=>nil,
"current_period_started_at"=>Thu, 25 Feb 2021 05:27:38 EST -05:00,
"previous_state"=>"past_due",
"signup_payment_id"=>34807,
"signup_revenue"=>"30,00",
"delayed_cancel_at"=>nil,
"coupon_code"=>nil,
"total_revenue_in_cents"=>0,
"product_price_in_cents"=>3000,
"product_version_number"=>1,
"payment_type"=>"bank_account",
"referral_code"=>nil,
"coupon_use_count"=>nil,
"coupon_uses_allowed"=>nil,
"reason_code"=>nil,
"automatically_resume_at"=>nil,
"coupon_codes"=>[],
"offer_id"=>nil,
"payer_id"=>nil,
"receives_invoice_emails"=>nil,
"product_price_point_id"=>466,
"next_product_price_point_id"=>nil,
"credit_balance_in_cents"=>0,
"prepayment_balance_in_cents"=>0,
"net_terms"=>nil,
"stored_credential_transaction_id"=>nil,
"locale"=>nil,
"reference"=>nil,
"currency"=>"EUR",
"on_hold_at"=>nil,
"scheduled_cancellation_at"=>nil,
"customer"=>
{"id"=>4268,
"first_name"=>"Test",
"last_name"=>"Test",
"organization"=>"",
"email"=>"test@example.com",
"created_at"=>Thu, 25 Feb 2021 05:27:38 EST -05:00,
"updated_at"=>Thu, 25 Feb 2021 05:27:38 EST -05:00,
"reference"=>nil,
"address"=>nil,
"address_2"=>nil,
"city"=>nil,
"state"=>nil,
"state_name"=>nil,
"zip"=>nil,
"country"=>nil,
"country_name"=>nil,
"phone"=>"",
"portal_invite_last_sent_at"=>nil,
"portal_invite_last_accepted_at"=>nil,
"verified"=>false,
"portal_customer_created_at"=>nil,
"vat_number"=>nil,
"cc_emails"=>nil,
"tax_exempt"=>false,
"parent_id"=>nil,
"locale"=>nil},
"product"=>
{"id"=>372,
"name"=>"test",
"handle"=>"test",
"description"=>"",
"accounting_code"=>"",
"request_credit_card"=>true,
"expiration_interval"=>nil,
"expiration_interval_unit"=>"never",
"created_at"=>Wed, 09 Dec 2020 05:06:07 EST -05:00,
"updated_at"=>Thu, 21 Jan 2021 09:28:12 EST -05:00,
"price_in_cents"=>3000,
"interval"=>1,
"interval_unit"=>"month",
"initial_charge_in_cents"=>nil,
"trial_price_in_cents"=>nil,
"trial_interval"=>nil,
"trial_interval_unit"=>"month",
"archived_at"=>nil,
"require_credit_card"=>true,
"return_params"=>"",
"taxable"=>false,
"update_return_url"=>"",
"tax_code"=>"",
"initial_charge_after_trial"=>false,
"version_number"=>1,
"update_return_params"=>"",
"default_product_price_point_id"=>466,
"request_billing_address"=>false,
"require_billing_address"=>false,
"require_shipping_address"=>false,
"product_price_point_id"=>466,
"product_price_point_name"=>"Original",
"product_price_point_handle"=>"uuid:14078c50-1c34-0139-f2b7-08e9fe639598",
"product_family"=>
{"id"=>131,
"name"=>"Billing Plans",
"description"=>nil,
"handle"=>"test-billing-plans",
"accounting_code"=>nil,
"created_at"=>Wed, 09 Dec 2020 04:37:03 EST -05:00,
"updated_at"=>Wed, 09 Dec 2020 04:37:03 EST -05:00},
"public_signup_pages"=>
[{"id"=>199,
"return_url"=>"",
"return_params"=>"",
"url"=>
"https://test-71.chargifypay.test/subscribe/3gx9xh5z8gj2/test"}]},
"bank_account"=>
{"id"=>5855,
"first_name"=>"Test",
"last_name"=>"Test",
"customer_id"=>4268,
"current_vault"=>"stripe_connect",
"vault_token"=>"cus_J0iV6HHEeYiAX4",
"billing_address"=>nil,
"billing_city"=>nil,
"billing_state"=>nil,
"billing_zip"=>nil,
"billing_country"=>nil,
"customer_vault_token"=>nil,
"billing_address_2"=>nil,
"bank_name"=>nil,
"masked_bank_routing_number"=>nil,
"masked_bank_account_number"=>"XXXX3001",
"bank_account_type"=>"checking",
"bank_account_holder_type"=>"personal",
"payment_type"=>"bank_account",
"verified"=>true,
"site_gateway_setting_id"=>402},
"group"=>nil},
"transaction"=>
{"id"=>34807,
"subscription_id"=>102493,
"type"=>"Payment",
"kind"=>nil,
"transaction_type"=>"payment",
"success"=>false,
"amount_in_cents"=>3000,
"memo"=>"Test Test - test: Signup payment",
"created_at"=>Thu, 25 Feb 2021 05:27:45 EST -05:00,
"starting_balance_in_cents"=>3000,
"ending_balance_in_cents"=>0,
"gateway_used"=>"stripe_connect",
"gateway_transaction_id"=>"pi_1IOh4NKajOcZzbwkC2xrThzC",
"gateway_order_id"=>nil,
"payment_id"=>nil,
"product_id"=>372,
"tax_id"=>nil,
"component_id"=>nil,
"statement_id"=>24757,
"customer_id"=>4268,
"item_name"=>nil,
"period_range_start"=>nil,
"period_range_end"=>nil,
"currency"=>"EUR",
"exchange_rate"=>1,
"component_handle"=>nil,
"component_price_point_id"=>nil,
"component_price_point_handle"=>nil,
"parent_id"=>nil,
"role"=>nil,
"card_number"=>nil,
"card_expiration"=>nil,
"card_type"=>nil,
"refunded_amount_in_cents"=>0,
"invoice_id"=>nil},
"event_id"=>51655}
```
## dunning_step_reached
**Trigger:** When a subscription reaches any step of the dunning process.
**Payload Fields:** event_id, site, subscription, product, dunner, current_step, next_step
## Full payload example
```json
"subscription" => {
"id" => 37,
"state" => "past_due",
"trial_started_at" => Wed, 25 Jan 2025 15:48:56 EST -05:00,
"trial_ended_at" => Wed, 25 Jan 2025 15:49:35 EST -05:00,
"activated_at" => nil,
"created_at" => Wed, 25 Jan 2025 15:48:56 EST -05:00,
"updated_at" => Wed, 25 Jan 2025 15:49:40 EST -05:00,
"expires_at" => nil,
"balance_in_cents" => 2400,
"current_period_ends_at" => Sat, 25 Feb 2025 15:49:35 EST -05:00,
"next_assessment_at" => Wed, 25 Jan 2025 15:49:35 EST -05:00,
"canceled_at" => nil,
"cancellation_message" => nil,
"next_product_id" => nil,
"cancel_at_end_of_period" => false,
"payment_collection_method" => "automatic",
"snap_day" => nil,
"cancellation_method" => nil,
"current_period_started_at" => Wed, 25 Jan 2025 15:49:35 EST -05:00,
"previous_state" => "past_due",
"signup_payment_id" => 101,
"signup_revenue" => "0.00",
"delayed_cancel_at" => nil,
"coupon_code" => nil,
"total_revenue_in_cents" => 0,
"product_price_in_cents" => 2400,
"product_version_number" => 1,
"payment_type" => nil,
"referral_code" => nil,
"coupon_use_count" => nil,
"coupon_uses_allowed" => nil,
"product_price_point_id"=>1,
"next_product_price_point_id"=>nil,
"customer" => {
"id" => 37,
"first_name" => "Ella",
"last_name" => "Gertrude",
"organization" => "",
"email" => "ella@example.com",
"created_at" => Wed, 25 Jan 2025 15:48:56 EST -05:00,
"updated_at" => Wed, 25 Jan 2025 15:48:56 EST -05:00,
"reference" => nil,
"address" => "",
"address_2" => "",
"city" => "",
"state" => "",
"zip" => "",
"country" => "",
"phone" => "",
"portal_invite_last_sent_at" => nil,
"portal_invite_last_accepted_at" => nil,
"verified" => false,
"portal_customer_created_at" => nil,
"vat_number"=>"123456789"
"cc_emails" => nil,
"tax_exempt" => false,
"parent_id" => nil},
"product" => {
"id" => 24,
"name" => "Basic",
"handle" => "basic",
"description" => "Magni porro sint iste illum. Qui aut reiciendis voluptatum. Est et aut.",
"accounting_code" => nil,
"request_credit_card" => true,
"expiration_interval" => nil,
"expiration_interval_unit" => nil,
"created_at" => Mon, 23 Jan 2025 15:33:40 EST -05:00,
"updated_at" => Mon, 23 Jan 2025 15:33:40 EST -05:00,
"price_in_cents" => 2400,
"interval" => 1,
"interval_unit" => "month",
"initial_charge_in_cents" => nil,
"trial_price_in_cents" => 0,
"trial_interval" => 1,
"trial_interval_unit" => "month",
"archived_at" => nil,
"require_credit_card" => true,
"return_params" => nil,
"taxable" => false,
"update_return_url"=>"http://www.example.com",
"initial_charge_after_trial" => false,
"version_number" => 1,
"update_return_params"=>"id={subscription_id}&ref={customer_reference}",
"default_product_price_point_id"=>1,
"product_price_point_id"=>1,
"product_price_point_handle"=>nil,
"product_family" => {
"id" => 4,
"name" => "Acme Online",
"description" => nil,
"handle" => "acme-online",
"accounting_code" => nil},
"public_signup_pages" => [ {
"id" => 5,
"return_url" => nil,
"return_params" => nil,
"url" => "http://acme-test.chargify.dev/subscribe/y884dzrgd9r9/basic"}]}},
"dunner" => {
"subscription_id" => 37,
"state" => "active",
"attempts" => 1,
"last_attempted_at" => Wed, 25 Jan 2025 15:49:42 EST -05:00,
"created_at" => Wed, 25 Jan 2025 15:49:42 EST -05:00,
"revenue_at_risk_in_cents" => nil},
"current_step" => {
"day_threshold" => 1,
"action" => "retry",
"email_body" => "Hello ,\n\nWe just tried to process your current amount due of \nfor , but there is no credit card on file for this subscription. \n\nPlease use the following link to quickly and easily update your billing information:\n\n\nWe will attempt to retry the card on file prior to cancellation. If we are unable to successfully charge the outstanding balance of , your account will be canceled in 27 days.\n\nThank you for choosing us!\n\nSincerely,\n\n\n",
"email_subject" => "NOTICE: ",
"send_email" => true,
"send_bcc_email" => false,
"send_sms" => false,
"sms_body" => nil},
"next_step" => {
"day_threshold" => 28,
"action" => "cancel",
"email_body" => "Hello ,\n\n\nWe've made several attempts to bill you for your account but you have not yet provided us with a valid credit card profile.\n\nAs a result, your account has been canceled.\n\nIf you did not intend to cancel your account, please contact us to reactivate your account and avoid further interruption of your service.\n\nThank you for choosing us!\n\nSincerely,\n\n\n",
"email_subject" => "NOTICE: Account Canceled",
"send_email" => true,
"send_bcc_email" => false,
"send_sms" => false,
"sms_body" => nil},
"event_id" => 165}
```
## expiration_date_change
**Trigger:** Any change to an existing `expiration_date` for a subscription.
**Payload Fields:** event_id, site, subscription
## Full payload example
```json
"subscription"=>
{"id"=>16945349,
"state"=>"active",
"trial_started_at"=>nil,
"trial_ended_at"=>nil,
"activated_at"=>Fri, 03 Mar 2025 13:00:08 EST -05:00,
"created_at"=>Fri, 03 Mar 2025 13:00:02 EST -05:00,
"updated_at"=>Fri, 03 Mar 2025 13:03:55 EST -05:00,
"expires_at"=>Sun, 15 Oct 2025 00:00:00 EDT -04:00,
"balance_in_cents"=>0,
"current_period_ends_at"=>Sun, 05 Mar 2025 13:00:02 EST -05:00,
"next_assessment_at"=>Sat, 04 Mar 2025 13:00:02 EST -05:00,
"canceled_at"=>nil,
"cancellation_message"=>nil,
"next_product_id"=>nil,
"cancel_at_end_of_period"=>false,
"payment_collection_method"=>"automatic",
"snap_day"=>nil,
"cancellation_method"=>nil,
"current_period_started_at"=>Fri, 03 Mar 2025 13:00:02 EST -05:00,
"previous_state"=>"active",
"signup_payment_id"=>176501894,
"signup_revenue"=>"1.00",
"delayed_cancel_at"=>nil,
"coupon_code"=>nil,
"total_revenue_in_cents"=>100,
"product_price_in_cents"=>100,
"product_version_number"=>1,
"payment_type"=>"credit_card",
"referral_code"=>"968js9",
"coupon_use_count"=>nil,
"coupon_uses_allowed"=>nil,
"product_price_point_id"=>1,
"next_product_price_point_id"=>nil,
"reason_code"=>nil,
"customer"=>
{"id"=>16428076,
"first_name"=>"Expiring ",
"last_name"=>"Subscription",
"organization"=>"",
"email"=>"expiring@example.com",
"created_at"=>Fri, 03 Mar 2025 13:00:02 EST -05:00,
"updated_at"=>Fri, 03 Mar 2025 13:00:02 EST -05:00,
"reference"=>nil,
"address"=>"",
"address_2"=>"",
"city"=>"",
"state"=>"",
"zip"=>"",
"country"=>"",
"phone"=>"",
"portal_invite_last_sent_at"=>nil,
"portal_invite_last_accepted_at"=>nil,
"verified"=>nil,
"portal_customer_created_at"=>nil,
"vat_number"=>"123456789"
"cc_emails"=>nil,
"tax_exempt"=>false,
"parent_id"=>nil},
"product"=>
{"id"=>4464208,
"name"=>"Product that expires",
"handle"=>"product-that-expires",
"description"=>"",
"accounting_code"=>"",
"request_credit_card"=>true,
"expiration_interval"=>1,
"expiration_interval_unit"=>"day",
"created_at"=>Fri, 03 Mar 2025 12:02:38 EST -05:00,
"updated_at"=>Fri, 03 Mar 2025 12:02:38 EST -05:00,
"price_in_cents"=>100,
"interval"=>2,
"interval_unit"=>"day",
"initial_charge_in_cents"=>nil,
"trial_price_in_cents"=>nil,
"trial_interval"=>nil,
"trial_interval_unit"=>"month",
"archived_at"=>nil,
"require_credit_card"=>true,
"return_params"=>"",
"taxable"=>false,
"update_return_url"=>"http://www.example.com",
"initial_charge_after_trial"=>false,
"version_number"=>1,
"update_return_params"=>"id={subscription_id}&ref={customer_reference}",
"default_product_price_point_id"=>1,
"product_price_point_id"=>1,
"product_price_point_handle"=>nil,
"product_family"=>
{"id"=>986840,
"name"=>"Acme Products",
"description"=>"",
"handle"=>"acme-products",
"accounting_code"=>nil},
"public_signup_pages"=>
[{"id"=>314126,
"return_url"=>nil,
"return_params"=>"",
"url"=>
"https://general-goods.chargifypay.com/subscribe/zs8352q9qtyz/product-that-expires"}]},
"credit_card"=>
{"id"=>11380641,
"first_name"=>"Expiring ",
"last_name"=>"Subscription",
"masked_card_number"=>"XXXX-XXXX-XXXX-1",
"card_type"=>"bogus",
"expiration_month"=>1,
"expiration_year"=>2027,
"customer_id"=>16428076,
"current_vault"=>"bogus",
"vault_token"=>"1",
"billing_address"=>"",
"billing_city"=>"",
"billing_state"=>"",
"billing_zip"=>"",
"billing_country"=>"",
"customer_vault_token"=>nil,
"billing_address_2"=>"",
"payment_type"=>"credit_card"},
"previous_expires_at"=>Wed, 15 Jul 2015 00:00:00 EDT -04:00},
"event_id"=>384446169}
```
## expiring_card
**Trigger:** A periodic event sent by Advanced Billing on the 1st, 15th, and 7 days before the end of the month. These webhooks identify cards expiring in the current month.
**Payload Fields:** event_id, site, subscription
The subscription object also contains information on the Customer and Product. The expiring_card webhook is sent on the 1st, 15th and 7 days before the end of the month. This will identify all cards expiring in the current month.
## Full payload example
```json
{"id"=>16474328,
"state"=>"active",
"trial_started_at"=>nil,
"trial_ended_at"=>nil,
"activated_at"=>Mon, 20 Feb 2025 18:28:48 EST -05:00,
"created_at"=>Mon, 20 Feb 2025 18:28:47 EST -05:00,
"updated_at"=>Mon, 20 Feb 2025 18:32:14 EST -05:00,
"expires_at"=>nil,
"balance_in_cents"=>0,
"current_period_ends_at"=>Mon, 20 Mar 2025 19:28:47 EDT -04:00,
"next_assessment_at"=>Mon, 20 Mar 2025 19:28:47 EDT -04:00,
"canceled_at"=>nil,
"cancellation_message"=>nil,
"next_product_id"=>nil,
"cancel_at_end_of_period"=>false,
"payment_collection_method"=>"automatic",
"snap_day"=>nil,
"cancellation_method"=>nil,
"current_period_started_at"=>Mon, 20 Feb 2025 18:28:47 EST -05:00,
"previous_state"=>"active",
"signup_payment_id"=>174876340,
"signup_revenue"=>"0.00",
"delayed_cancel_at"=>nil,
"coupon_code"=>nil,
"total_revenue_in_cents"=>0,
"product_price_in_cents"=>0,
"product_version_number"=>1,
"payment_type"=>"credit_card",
"referral_code"=>"ww6mq5",
"coupon_use_count"=>nil,
"coupon_uses_allowed"=>nil,
"product_price_point_id"=>1,
"next_product_price_point_id"=>nil,
"customer"=>
{"id"=>15102905,
"first_name"=>"Amelia",
"last_name"=>"Example",
"organization"=>"",
"email"=>"amelia@example.com",
"created_at"=>Thu, 15 Dec 2024 09:33:15 EST -05:00,
"updated_at"=>Thu, 15 Dec 2024 09:34:09 EST -05:00,
"reference"=>nil,
"address"=>"",
"address_2"=>"",
"city"=>"",
"state"=>"",
"zip"=>"",
"country"=>"",
"phone"=>"",
"portal_invite_last_sent_at"=>nil,
"portal_invite_last_accepted_at"=>nil,
"verified"=>nil,
"portal_customer_created_at"=>Thu, 15 Dec 2024 09:33:21 EST -05:00,
"vat_number"=>"123456789"
"cc_emails"=>nil,
"tax_exempt"=>false},
"product"=>
{"id"=>4461042,
"name"=>"Gold Product",
"handle"=>"gold-product",
"description"=>"",
"accounting_code"=>"",
"request_credit_card"=>true,
"expiration_interval"=>nil,
"expiration_interval_unit"=>"never",
"created_at"=>Mon, 20 Feb 2025 18:28:18 EST -05:00,
"updated_at"=>Mon, 20 Feb 2025 18:28:18 EST -05:00,
"price_in_cents"=>0,
"interval"=>1,
"interval_unit"=>"month",
"initial_charge_in_cents"=>nil,
"trial_price_in_cents"=>nil,
"trial_interval"=>nil,
"trial_interval_unit"=>"month",
"archived_at"=>nil,
"require_credit_card"=>true,
"return_params"=>"",
"taxable"=>false,
"update_return_url"=>"http://www.example.com",
"initial_charge_after_trial"=>false,
"version_number"=>1,
"update_return_params"=>"id={subscription_id}&ref={customer_reference}",
"default_product_price_point_id"=>1,
"product_price_point_id"=>1,
"product_price_point_handle"=>nil,
"product_family"=>
{"id"=>986840,
"name"=>"Acme Products",
"description"=>"",
"handle"=>"acme-products",
"accounting_code"=>nil},
"public_signup_pages"=>
[{"id"=>312984,
"return_url"=>nil,
"return_params"=>"",
"url"=>
"https://general-goods.chargifypay.com/subscribe/yt4ybcgk7998/zero-dollar-product"}]},
"credit_card"=>
{"id"=>10548239,
"first_name"=>"Amelia",
"last_name"=>"Example",
"masked_card_number"=>"XXXX-XXXX-XXXX-2",
"card_type"=>"bogus",
"expiration_month"=>2,
"expiration_year"=>2025,
"customer_id"=>15102905,
"current_vault"=>"bogus",
"vault_token"=>"2",
"billing_address"=>"",
"billing_city"=>"",
"billing_state"=>"",
"billing_zip"=>"",
"billing_country"=>"",
"customer_vault_token"=>nil,
"billing_address_2"=>"",
"payment_type"=>"credit_card"}},
"site"=>{"id"=>31615, "subdomain"=>"general-goods"},
"event_id"=>380080310}
```
## invoice_issued
**Trigger:** Invoices issued towards a subscription on Relationship Invoicing site.
**Payload Fields:** event_id, site, subscription, invoice
The subscription object also contains information on the Customer and Product.
## Full payload example
```json
"site"=>{"id"=>31615, "subdomain"=>"general-goods"},
"subscription"=>
{"id"=>28224225,
"current_period_ends_at"=>Wed, 31 Jul 2025 15:25:54 CDT -05:00},
"invoice"=>
{"uid"=>"inv_4ffwqn13mppt7"
"role"=>"renewal",
"due_date"=>"2025-07-31",
"issue_date"=>"2025-07-31",
"paid_date"=>"",
"due_amount"=>"$3,000.00",
"paid_amount"=>"$0.00",
"refund_amount"=>"$0.00",
"tax_amount"=>"$0.00",
"total_amount"=>"$3,000.00",
"status_amount"=>"$3,000.00",
"product_name"=>"2000",
"line_items"=>
{"0"=>
{"uid"=>"li_8tjw5rjzyt287",
"title"=>"2000",
"description"=>"31 Jul 2025 - 31 Aug 2025",
"quantity"=>1,
"unit_price"=>"$3,000.00",
"period_range_start"=>"2025-07-31",
"period_range_end"=>"2025-08-31",
"amount"=>"$3,000.00",
"line_references"=>"",
"pricing_details_index"=>nil,
"pricing_details"=>{},
"tax_code"=>nil,
"tax_amount"=>"0.0"}}},
"event_id"=>854499834}
```
## invoice_pending
**Trigger:** Any time an invoice transitions into the `pending` state.
**Payload Fields:** event_id, site, invoice, customer, subscription (if applicable), previous_state, new_state, timestamp
This event follows the standard webhook behavior for event subscriptions, signed payload delivery, retries, and replay.
## Full payload example with subscription
```json
"site"=>{"id"=>31111, "subdomain"=>"general-goods"},
"invoice"=>
{"id"=>76439765,
"uid"=>"inv_4fffff13mppt5",
"status"=>"pending"},
"customer"=>
{"id"=>15822222,
"reference"=>"cust-000123"},
"subscription"=>
{"id"=>22224225},
"previous_state"=>"draft",
"new_state"=>"pending",
"timestamp"=>"2025-07-31T20:45:00Z",
"event_id"=>854500001}
```
## Full payload example without subscription
```json
"site"=>{"id"=>31111, "subdomain"=>"general-goods"},
"invoice"=>
{"id"=>76222,
"uid"=>"inv_4fffff16mppt6",
"status"=>"pending"},
"customer"=>
{"id"=>15822222,
"reference"=>"cust-000123"},
"subscription"=>nil,
"previous_state"=>"open",
"new_state"=>"pending",
"timestamp"=>"2025-07-31T21:10:00Z",
"event_id"=>854500000}
```
## metered_usage
**Trigger:** Any reported usage for a Subscription’s metered components. This webhook will not fire when the unit balance is reset to `0` at renewal. `timestamp` is in ISO8601 format in UTC.
**Payload Fields:** event_id, site, component, subscription, product, previous_unit_balance, new_unit_balance, usage_quantity, memo, timestamp
## Full payload example
```json
"component"=>
{"id"=>375042,
"kind"=>"metered_component",
"name"=>"Test Metered",
"unit_name"=>"Test Metered"},
"subscription"=>{"id"=>16372192, "name"=>"Doris Tester"},
"product"=>{"id"=>4443536, "name"=>"Business Monthly"},
"memo"=>"Recording Metered Component Usage",
"timestamp"=>"2025-02-13T18:50:23Z",
"previous_unit_balance"=>#,
"new_unit_balance"=>1000,
"usage_quantity"=>1000,
"event_id"=>377609676}
```
## payment_failure
**Trigger:** Any failed payment attempt.payment_success or payment_failure are triggered for every payment attempted, whether it is for a normal renewal, a One-time Charge, a retry after failure, or a payment applied to an Invoice. Note that in some cases the payment may fail later, most commonly with ACH/eCheck and Direct Debit.
**Payload Fields:** event_id, site, subscription, transaction
## Full payload example
```json
"subscription"=>
{"id"=>16090357,
"state"=>"past_due",
"trial_started_at"=>Mon, 23 Jan 2025 09:59:26 EST -05:00,
"trial_ended_at"=>Mon, 23 Jan 2025 09:59:49 EST -05:00,
"activated_at"=>nil,
"created_at"=>Mon, 23 Jan 2025 09:59:26 EST -05:00,
"updated_at"=>Mon, 30 Jan 2025 12:07:40 EST -05:00,
"expires_at"=>nil,
"balance_in_cents"=>1000,
"current_period_ends_at"=>Thu, 23 Feb 2025 09:59:49 EST -05:00,
"next_assessment_at"=>Tue, 31 Jan 2025 12:07:40 EST -05:00,
"canceled_at"=>nil,
"cancellation_message"=>nil,
"next_product_id"=>nil,
"cancel_at_end_of_period"=>false,
"payment_collection_method"=>"automatic",
"snap_day"=>nil,
"cancellation_method"=>nil,
"current_period_started_at"=>Mon, 23 Jan 2025 09:59:49 EST -05:00,
"previous_state"=>"past_due",
"signup_payment_id"=>171203419,
"signup_revenue"=>"0.00",
"delayed_cancel_at"=>nil,
"coupon_code"=>nil,
"total_revenue_in_cents"=>0,
"product_price_in_cents"=>1000,
"product_version_number"=>1,
"payment_type"=>"credit_card",
"referral_code"=>"4nvrr2",
"coupon_use_count"=>nil,
"coupon_uses_allowed"=>nil,
"product_price_point_id"=>1,
"next_product_price_point_id"=>nil,
"currency"=>"USD",
"customer"=>
{"id"=>15547334,
"first_name"=>"No obligation",
"last_name"=>"Bad Card",
"organization"=>"",
"email"=>"nobbad@example.com",
"created_at"=>Mon, 23 Jan 2025 09:59:26 EST -05:00,
"updated_at"=>Mon, 23 Jan 2025 09:59:28 EST -05:00,
"reference"=>nil,
"address"=>"",
"address_2"=>"",
"city"=>"",
"state"=>"",
"zip"=>"",
"country"=>"",
"phone"=>"",
"portal_invite_last_sent_at"=>Mon, 23 Jan 2025 09:59:28 EST -05:00,
"portal_invite_last_accepted_at"=>nil,
"verified"=>nil,
"portal_customer_created_at"=>Mon, 23 Jan 2025 09:59:28 EST -05:00,
"vat_number"=>"123456789"
"cc_emails"=>nil,
"tax_exempt"=>false,
"parent_id"=>nil},
"product"=>
{"id"=>4453830,
"name"=>"Trial No obligation",
"handle"=>"trial-no-obligation",
"description"=>"",
"accounting_code"=>"",
"request_credit_card"=>true,
"expiration_interval"=>nil,
"expiration_interval_unit"=>"never",
"created_at"=>Mon, 23 Jan 2025 09:53:23 EST -05:00,
"updated_at"=>Thu, 26 Jan 2025 13:35:29 EST -05:00,
"price_in_cents"=>1000,
"interval"=>1,
"interval_unit"=>"month",
"initial_charge_in_cents"=>nil,
"trial_price_in_cents"=>0,
"trial_interval"=>1,
"trial_interval_unit"=>"day",
"archived_at"=>nil,
"require_credit_card"=>false,
"return_params"=>"",
"taxable"=>false,
"update_return_url"=>"http://www.example.com",
"initial_charge_after_trial"=>false,
"version_number"=>1,
"update_return_params"=>"id={subscription_id}&ref={customer_reference}",
"default_product_price_point_id"=>1,
"product_price_point_id"=>1,
"product_price_point_handle"=>nil,
"product_family"=>
{"id"=>986840,
"name"=>"Acme Products",
"description"=>"",
"handle"=>"acme-products",
"accounting_code"=>nil},
"public_signup_pages"=>
[{"id"=>310559,
"return_url"=>nil,
"return_params"=>"",
"url"=>
"https://general-goods.chargifypay.com/subscribe/ngbsvxv4hq7q/trial-no-obligation"}]},
"credit_card"=>
{"id"=>10734525,
"first_name"=>"Chester",
"last_name"=>"Tester",
"masked_card_number"=>"XXXX-XXXX-XXXX-2",
"card_type"=>"bogus",
"expiration_month"=>1,
"expiration_year"=>2027,
"customer_id"=>15547334,
"current_vault"=>"bogus",
"vault_token"=>"2",
"billing_address"=>"",
"billing_city"=>"",
"billing_state"=>"",
"billing_zip"=>"",
"billing_country"=>"",
"customer_vault_token"=>nil,
"billing_address_2"=>"",
"payment_type"=>"credit_card"}},
"transaction"=>
{"id"=>172084191,
"subscription_id"=>16090357,
"type"=>"Payment",
"kind"=>nil,
"transaction_type"=>"payment",
"success"=>false,
"amount_in_cents"=>1000,
"memo"=>"Bogus Gateway: Forced failure",
"created_at"=>Mon, 30 Jan 2025 12:07:39 EST -05:00,
"starting_balance_in_cents"=>1000,
"ending_balance_in_cents"=>1000,
"gateway_used"=>"bogus",
"gateway_transaction_id"=>nil,
"gateway_order_id"=>nil,
"payment_id"=>nil,
"product_id"=>4453830,
"tax_id"=>nil,
"component_id"=>nil,
"statement_id"=>84491989,
"customer_id"=>15547334,
"card_number"=>"XXXX-XXXX-XXXX-2",
"card_expiration"=>"01/2027",
"card_type"=>"bogus",
"refunded_amount_in_cents"=>0,
"invoice_uids"=>["inv_9hchn3xc84mgm"],
"invoice_id"=>nil,
"currency"=>"USD"},
"event_id"=>372846073}
```
## payment_success
**Trigger:** Any payment attempt that does not result in an immediate failure.payment_success or payment_failure are triggered for every payment attempted, whether it is for a normal renewal, a One-time Charge, a retry after failure, or a payment applied to an Invoice. Note that in some cases the payment may fail later, most commonly with ACH/eCheck and Direct Debit.
**Payload Fields:** event_id, site, subscription, transaction
## Full payload example
```json
"subscription"=>
{"id"=>16327080,
"state"=>"active",
"trial_started_at"=>nil,
"trial_ended_at"=>nil,
"activated_at"=>Thu, 09 Feb 2025 11:42:28 EST -05:00,
"created_at"=>Thu, 09 Feb 2025 11:42:26 EST -05:00,
"updated_at"=>Mon, 13 Feb 2025 12:03:41 EST -05:00,
"expires_at"=>nil,
"balance_in_cents"=>0,
"current_period_ends_at"=>Wed, 08 Mar 2025 12:00:00 EST -05:00,
"next_assessment_at"=>Wed, 08 Mar 2025 12:00:00 EST -05:00,
"canceled_at"=>nil,
"cancellation_message"=>nil,
"next_product_id"=>nil,
"cancel_at_end_of_period"=>false,
"payment_collection_method"=>"automatic",
"snap_day"=>"8",
"cancellation_method"=>nil,
"current_period_started_at"=>Mon, 13 Feb 2025 12:00:00 EST -05:00,
"previous_state"=>"active",
"signup_payment_id"=>0,
"signup_revenue"=>"0.00",
"delayed_cancel_at"=>nil,
"coupon_code"=>nil,
"total_revenue_in_cents"=>5667,
"product_price_in_cents"=>6900,
"product_version_number"=>1,
"payment_type"=>"credit_card",
"referral_code"=>"6zcsxw",
"coupon_use_count"=>nil,
"coupon_uses_allowed"=>nil,
"product_price_point_id"=>1,
"next_product_price_point_id"=>nil,
"payer_id"=>15780191,
"currency"=>"USD",
"customer"=>
{"id"=>15780191,
"first_name"=>"Test "
"last_name"=>"Test",
"organization"=>"",
"email"=>"test@example.com",
"created_at"=>Thu, 09 Feb 2025 11:42:26 EST -05:00,
"updated_at"=>Thu, 09 Feb 2025 11:42:29 EST -05:00,
"reference"=>nil,
"address"=>nil,
"address_2"=>nil,
"city"=>nil,
"state"=>nil,
"zip"=>nil,
"country"=>nil,
"phone"=>"",
"portal_invite_last_sent_at"=>Thu, 09 Feb 2025 11:42:29 EST -05:00,
"portal_invite_last_accepted_at"=>nil,
"verified"=>false,
"portal_customer_created_at"=>Thu, 09 Feb 2025 11:42:29 EST -05:00,
"vat_number"=>"123456789"
"cc_emails"=>nil,
"tax_exempt"=>false,
"parent_id"=>nil},
"product"=>
{"id"=>4458204,
"name"=>"Monthly product ",
"handle"=>"monthly-product",
"description"=>"",
"accounting_code"=>"",
"request_credit_card"=>true,
"expiration_interval"=>nil,
"expiration_interval_unit"=>"never",
"created_at"=>Wed, 08 Feb 2025 16:48:54 EST -05:00,
"updated_at"=>Wed, 08 Feb 2025 16:48:54 EST -05:00,
"price_in_cents"=>6900,
"interval"=>1,
"interval_unit"=>"month",
"initial_charge_in_cents"=>nil,
"trial_price_in_cents"=>nil,
"trial_interval"=>nil,
"trial_interval_unit"=>"month",
"archived_at"=>nil,
"require_credit_card"=>true,
"return_params"=>"",
"taxable"=>false,
"update_return_url"=>"http://www.example.com",
"initial_charge_after_trial"=>false,
"version_number"=>1,
"update_return_params"=>"id={subscription_id}&ref={customer_reference}",
"default_product_price_point_id"=>1,
"product_price_point_id"=>1,
"product_price_point_handle"=>nil,
"product_family"=>
{"id"=>986840,
"name"=>"Acme Products",
"description"=>"",
"handle"=>"acme-products",
"accounting_code"=>nil},
"public_signup_pages"=>
[{"id"=>312067,
"return_url"=>nil,
"return_params"=>"",
"url"=>
"https://general-goods.chargifypay.com/subscribe/5x8sbq29vgkn/monthly-product"},
{"id"=>312068,
"return_url"=>"",
"return_params"=>"",
"url"=>
"https://general-goods.chargifypay.com/subscribe/vsmzkwvmfqqx/monthly-product"}]},
"credit_card"=>
{"id"=>10881632,
"first_name"=>"Test",
"last_name"=>"Page",
"masked_card_number"=>"XXXX-XXXX-XXXX-1",
"card_type"=>"bogus",
"expiration_month"=>1,
"expiration_year"=>2027,
"customer_id"=>15780191,
"current_vault"=>"bogus",
"vault_token"=>"1",
"billing_address"=>nil,
"billing_city"=>nil,
"billing_state"=>nil,
"billing_zip"=>"",
"billing_country"=>nil,
"customer_vault_token"=>nil,
"billing_address_2"=>nil,
"payment_type"=>"credit_card"}},
"transaction"=>
{"id"=>173963435,
"subscription_id"=>16327080,
"type"=>"Payment",
"kind"=>nil,
"transaction_type"=>"payment",
"success"=>true,
"amount_in_cents"=>5667,
"memo"=>"Test Monthly - Monthly product : Renewal payment",
"created_at"=>Mon, 13 Feb 2025 12:03:40 EST -05:00,
"starting_balance_in_cents"=>5667,
"ending_balance_in_cents"=>0,
"gateway_used"=>"bogus",
"gateway_transaction_id"=>"53433",
"gateway_order_id"=>nil,
"payment_id"=>nil,
"product_id"=>4458204,
"tax_id"=>nil,
"component_id"=>nil,
"statement_id"=>85701746,
"customer_id"=>15780191,
"card_number"=>"XXXX-XXXX-XXXX-1",
"card_expiration"=>"01/2027",
"card_type"=>"bogus",
"refunded_amount_in_cents"=>0,
"invoice_uids"=>["inv_9hchn3xc84mgm"],
"invoice_id"=>nil,
"currency"=>"USD"},
"event_id"=>377575306}
```
Note that if you are using Authorize.Net for your payment gateway, you will receive extra payload information in the form of gateway_response and approval_code:
```json
{
"site": { ... },
"subscription": { ... },
"transaction": { ... },
"gateway_response": {
"approval_code": "AB1CDO"
},
"event_id": 1
}
```
## pending_cancellation_change
**Trigger:** When a subscription is canceled with delay (cancel at end of period) or when pending cancellation is cleared.
**Payload Fields:** event_id, site, subscription, cancellation_state, cancels_at
The subscription object also contains information on the Customer and Product.
## Full payload example
```json
"subscription"=>
{"id"=>13,
"state"=>"active",
"trial_started_at"=>nil,
"trial_ended_at"=>nil,
"activated_at"=>Sat, 01 Feb 2020 10:38:50 EST -05:00,
"created_at"=>Sat, 01 Feb 2020 10:38:49 EST -05:00,
"updated_at"=>Fri, 10 Apr 2020 04:22:55 EDT -04:00,
"expires_at"=>nil,
"balance_in_cents"=>0,
"current_period_ends_at"=>Thu, 07 May 2020 04:33:39 EDT -04:00,
"next_assessment_at"=>Thu, 07 May 2020 04:33:39 EDT -04:00,
"canceled_at"=>nil,
"cancellation_message"=>nil,
"next_product_id"=>nil,
"next_product_handle"=>nil,
"cancel_at_end_of_period"=>false,
"payment_collection_method"=>"automatic",
"snap_day"=>nil,
"cancellation_method"=>nil,
"current_period_started_at"=>Tue, 07 Apr 2020 04:33:39 EDT -04:00,
"previous_state"=>"canceled",
"signup_payment_id"=>0,
"signup_revenue"=>"0.00",
"delayed_cancel_at"=>nil,
"coupon_code"=>nil,
"total_revenue_in_cents"=>31918,
"product_price_in_cents"=>29900,
"product_version_number"=>1,
"payment_type"=>"credit_card",
"referral_code"=>nil,
"coupon_use_count"=>nil,
"coupon_uses_allowed"=>nil,
"reason_code"=>nil,
"automatically_resume_at"=>nil,
"coupon_codes"=>[],
"offer_id"=>nil,
"payer_id"=>8,
"receives_invoice_emails"=>nil,
"product_price_point_id"=>114,
"next_product_price_point_id"=>nil,
"credit_balance_in_cents"=>0,
"prepayment_balance_in_cents"=>0,
"net_terms"=>2,
"stored_credential_transaction_id"=>nil,
"locale"=>nil,
"reference"=>nil,
"currency"=>"USD",
"customer"=>
{"id"=>8,
"first_name"=>"Marty",
"last_name"=>"McFly",
"organization"=>nil,
"email"=>"timetraveller1985@example.com",
"created_at"=>Sat, 01 Feb 2020 10:40:43 EST -05:00,
"updated_at"=>Fri, 03 Apr 2020 05:58:47 EDT -04:00,
"reference"=>nil,
"address"=>"100 Shipping St.",
"address_2"=>"Apt 200",
"city"=>"Pleasantville",
"state"=>"NC",
"zip"=>"12345",
"country"=>"US",
"phone"=>nil,
"portal_invite_last_sent_at"=>nil,
"portal_invite_last_accepted_at"=>nil,
"verified"=>false,
"portal_customer_created_at"=>nil,
"vat_number"=>nil,
"cc_emails"=>"john@example.com, sue@example.com",
"tax_exempt"=>false,
"parent_id"=>nil,
"locale"=>nil},
"product"=>
{"id"=>114,
"name"=>"Professional Plan",
"handle"=>"server-professional",
"description"=>
"Voluptatem et quod delectus ut. Reiciendis repudiandae nemo et doloribus. Maxime velit ut.",
"accounting_code"=>nil,
"request_credit_card"=>true,
"expiration_interval"=>nil,
"expiration_interval_unit"=>nil,
"created_at"=>Sat, 01 Feb 2020 10:40:43 EST -05:00,
"updated_at"=>Sat, 01 Feb 2020 10:40:43 EST -05:00,
"price_in_cents"=>29900,
"interval"=>1,
"interval_unit"=>"month",
"initial_charge_in_cents"=>nil,
"trial_price_in_cents"=>nil,
"trial_interval"=>nil,
"trial_interval_unit"=>nil,
"archived_at"=>nil,
"require_credit_card"=>true,
"return_params"=>nil,
"taxable"=>true,
"update_return_url"=>nil,
"tax_code"=>nil,
"initial_charge_after_trial"=>false,
"version_number"=>1,
"update_return_params"=>nil,
"default_product_price_point_id"=>114,
"product_price_point_id"=>114,
"product_price_point_name"=>"Default",
"product_price_point_handle"=>"uuid:213b0f81-2737-0138-4a11-2cde48001122",
"product_family"=>
{"id"=>29,
"name"=>"Cloud Compute Servers",
"description"=>nil,
"handle"=>"cloud-compute-servers",
"accounting_code"=>nil},
"public_signup_pages"=>[]},
"credit_card"=>
{"id"=>8,
"first_name"=>"Marty",
"last_name"=>"McFly",
"masked_card_number"=>"XXXX-XXXX-XXXX-1111",
"card_type"=>"visa",
"expiration_month"=>12,
"expiration_year"=>2022,
"customer_id"=>8,
"current_vault"=>"",
"vault_token"=>"1",
"billing_address"=>"200 Billing Rd.",
"billing_city"=>"Needham",
"billing_state"=>"MA",
"billing_zip"=>"02494",
"billing_country"=>"US",
"customer_vault_token"=>nil,
"billing_address_2"=>"Suite 100",
"payment_type"=>"credit_card",
"disabled"=>false}},
"cancellation_state"=>"cleared",
"cancels_at"=>nil,
"event_id"=>315}
```
## pending_payment_created
**Trigger:** When a Pending Payment was created in the gateway and is pending processing.
**Payload Fields:** event_id, site, subscription, transaction
## Full payload example
```json
"subscription"=>
{"id"=>784,
"state"=>"pending",
"trial_started_at"=>nil,
"trial_ended_at"=>nil,
"activated_at"=>nil,
"created_at"=>Wed, 18 Aug 2021 05:58:29 EDT -04:00,
"updated_at"=>Wed, 18 Aug 2021 05:58:43 EDT -04:00,
"expires_at"=>nil,
"balance_in_cents"=>0,
"current_period_ends_at"=>nil,
"next_assessment_at"=>nil,
"canceled_at"=>nil,
"cancellation_message"=>nil,
"next_product_id"=>nil,
"next_product_handle"=>nil,
"cancel_at_end_of_period"=>nil,
"payment_collection_method"=>"automatic",
"snap_day"=>nil,
"cancellation_method"=>nil,
"current_period_started_at"=>Wed, 18 Aug 2021 05:58:29 EDT -04:00,
"previous_state"=>"pending",
"signup_payment_id"=>3556,
"signup_revenue"=>"500.00",
"delayed_cancel_at"=>nil,
"coupon_code"=>nil,
"total_revenue_in_cents"=>50000,
"product_price_in_cents"=>50000,
"product_version_number"=>1,
"payment_type"=>"credit_card",
"referral_code"=>nil,
"coupon_use_count"=>nil,
"coupon_uses_allowed"=>nil,
"reason_code"=>nil,
"automatically_resume_at"=>nil,
"coupon_codes"=>[],
"offer_id"=>nil,
"payer_id"=>nil,
"receives_invoice_emails"=>nil,
"product_price_point_id"=>168,
"next_product_price_point_id"=>nil,
"credit_balance_in_cents"=>0,
"prepayment_balance_in_cents"=>0,
"net_terms"=>nil,
"stored_credential_transaction_id"=>nil,
"locale"=>nil,
"reference"=>nil,
"currency"=>"USD",
"on_hold_at"=>nil,
"scheduled_cancellation_at"=>nil,
"customer"=>
{"id"=>708,
"first_name"=>"John",
"last_name"=>"Doe",
"organization"=>"",
"email"=>"test@example.com",
"created_at"=>Wed, 18 Aug 2021 05:58:29 EDT -04:00,
"updated_at"=>Wed, 18 Aug 2021 05:58:29 EDT -04:00,
"reference"=>nil,
"address"=>"Street",
"address_2"=>"",
"city"=>"San Francisco",
"state"=>"CA",
"state_name"=>"California",
"zip"=>"66785",
"country"=>"US",
"country_name"=>"United States",
"phone"=>"123456789",
"portal_invite_last_sent_at"=>nil,
"portal_invite_last_accepted_at"=>nil,
"verified"=>false,
"portal_customer_created_at"=>nil,
"vat_number"=>nil,
"cc_emails"=>nil,
"tax_exempt"=>false,
"parent_id"=>nil,
"locale"=>nil},
"product"=>
{"id"=>154,
"name"=>"golder",
"handle"=>"golderrr",
"description"=>"",
"accounting_code"=>"",
"request_credit_card"=>true,
"expiration_interval"=>nil,
"expiration_interval_unit"=>"never",
"created_at"=>Mon, 05 Jul 2021 08:32:52 EDT -04:00,
"updated_at"=>Tue, 20 Jul 2021 08:08:49 EDT -04:00,
"price_in_cents"=>50000,
"interval"=>1,
"interval_unit"=>"month",
"initial_charge_in_cents"=>nil,
"trial_price_in_cents"=>nil,
"trial_interval"=>nil,
"trial_interval_unit"=>"month",
"archived_at"=>nil,
"require_credit_card"=>true,
"return_params"=>"",
"taxable"=>true,
"update_return_url"=>"",
"tax_code"=>"4512.100",
"initial_charge_after_trial"=>false,
"version_number"=>1,
"update_return_params"=>"",
"default_product_price_point_id"=>168,
"request_billing_address"=>true,
"require_billing_address"=>true,
"require_shipping_address"=>true,
"product_price_point_id"=>168,
"product_price_point_name"=>"Original",
"product_price_point_handle"=>"uuid:0a6d2640-bfbb-0139-c94b-2cde48001122",
"product_family"=>
{"id"=>65,
"name"=>"Billing Plans",
"description"=>nil,
"handle"=>"chargify-billing-plans",
"accounting_code"=>nil,
"created_at"=>Mon, 21 Jun 2021 08:22:16 EDT -04:00,
"updated_at"=>Mon, 21 Jun 2021 08:22:16 EDT -04:00},
"public_signup_pages"=>
[{"id"=>101,
"return_url"=>nil,
"return_params"=>"",
"url"=>
"https://some-subdomain.chargifypay.test/subscribe/nmxwp8gsjh3t/golderrr"}]},
"credit_card"=>
{"id"=>885,
"first_name"=>"John",
"last_name"=>"Doe",
"masked_card_number"=>"XXXX-XXXX-XXXX-1111",
"card_type"=>"visa",
"expiration_month"=>1,
"expiration_year"=>2029,
"customer_id"=>708,
"current_vault"=>"digital_river",
"vault_token"=>"b0aeda54-7576-4457-a36b-e775d2730df8",
"billing_address"=>"Street",
"billing_city"=>"San Francisco",
"billing_state"=>"CA",
"billing_zip"=>"66785",
"billing_country"=>"US",
"customer_vault_token"=>"541159940336",
"billing_address_2"=>"",
"payment_type"=>"credit_card",
"disabled"=>false,
"site_gateway_setting_id"=>71},
"group"=>nil},
"transaction"=>
{"id"=>3556,
"subscription_id"=>784,
"type"=>"Payment",
"kind"=>nil,
"transaction_type"=>"payment",
"success"=>true,
"amount_in_cents"=>50000,
"memo"=>"John Doe - golder: Signup payment",
"created_at"=>Wed, 18 Aug 2021 05:58:43 EDT -04:00,
"starting_balance_in_cents"=>50000,
"ending_balance_in_cents"=>0,
"gateway_used"=>"digital_river",
"gateway_transaction_id"=>"3daa894a-77e5-4bd9-88b9-8e6dd1e84185",
"gateway_order_id"=>nil,
"payment_id"=>nil,
"product_id"=>154,
"tax_id"=>nil,
"component_id"=>nil,
"statement_id"=>1553,
"customer_id"=>708,
"item_name"=>nil,
"period_range_start"=>nil,
"period_range_end"=>nil,
"currency"=>"USD",
"exchange_rate"=>1,
"component_handle"=>nil,
"component_price_point_id"=>nil,
"component_price_point_handle"=>nil,
"parent_id"=>nil,
"role"=>nil,
"card_number"=>"XXXX-XXXX-XXXX-1111",
"card_expiration"=>"01/2029",
"card_type"=>"visa",
"refunded_amount_in_cents"=>0,
"invoice_id"=>nil},
"event_id"=>5432}
```
## pending_payment_completed
**Trigger:** When a Pending Payment was successfully processed in the gateway.
**Payload Fields:** event_id, site, subscription, transaction
## Full payload example
```json
"subscription"=>
{"id"=>784,
"state"=>"pending",
"trial_started_at"=>nil,
"trial_ended_at"=>nil,
"activated_at"=>nil,
"created_at"=>Wed, 18 Aug 2021 05:58:29 EDT -04:00,
"updated_at"=>Wed, 18 Aug 2021 05:58:43 EDT -04:00,
"expires_at"=>nil,
"balance_in_cents"=>0,
"current_period_ends_at"=>nil,
"next_assessment_at"=>nil,
"canceled_at"=>nil,
"cancellation_message"=>nil,
"next_product_id"=>nil,
"next_product_handle"=>nil,
"cancel_at_end_of_period"=>nil,
"payment_collection_method"=>"automatic",
"snap_day"=>nil,
"cancellation_method"=>nil,
"current_period_started_at"=>Wed, 18 Aug 2021 05:58:29 EDT -04:00,
"previous_state"=>"pending",
"signup_payment_id"=>3556,
"signup_revenue"=>"500.00",
"delayed_cancel_at"=>nil,
"coupon_code"=>nil,
"total_revenue_in_cents"=>50000,
"product_price_in_cents"=>50000,
"product_version_number"=>1,
"payment_type"=>"credit_card",
"referral_code"=>nil,
"coupon_use_count"=>nil,
"coupon_uses_allowed"=>nil,
"reason_code"=>nil,
"automatically_resume_at"=>nil,
"coupon_codes"=>[],
"offer_id"=>nil,
"payer_id"=>nil,
"receives_invoice_emails"=>nil,
"product_price_point_id"=>168,
"next_product_price_point_id"=>nil,
"credit_balance_in_cents"=>0,
"prepayment_balance_in_cents"=>0,
"net_terms"=>nil,
"stored_credential_transaction_id"=>nil,
"locale"=>nil,
"reference"=>nil,
"currency"=>"USD",
"on_hold_at"=>nil,
"scheduled_cancellation_at"=>nil,
"customer"=>
{"id"=>708,
"first_name"=>"John",
"last_name"=>"Doe",
"organization"=>"",
"email"=>"test@example.com",
"created_at"=>Wed, 18 Aug 2021 05:58:29 EDT -04:00,
"updated_at"=>Wed, 18 Aug 2021 05:58:29 EDT -04:00,
"reference"=>nil,
"address"=>"Street",
"address_2"=>"",
"city"=>"San Francisco",
"state"=>"CA",
"state_name"=>"California",
"zip"=>"66785",
"country"=>"US",
"country_name"=>"United States",
"phone"=>"123456789",
"portal_invite_last_sent_at"=>nil,
"portal_invite_last_accepted_at"=>nil,
"verified"=>false,
"portal_customer_created_at"=>nil,
"vat_number"=>nil,
"cc_emails"=>nil,
"tax_exempt"=>false,
"parent_id"=>nil,
"locale"=>nil},
"product"=>
{"id"=>154,
"name"=>"golder",
"handle"=>"golderrr",
"description"=>"",
"accounting_code"=>"",
"request_credit_card"=>true,
"expiration_interval"=>nil,
"expiration_interval_unit"=>"never",
"created_at"=>Mon, 05 Jul 2021 08:32:52 EDT -04:00,
"updated_at"=>Tue, 20 Jul 2021 08:08:49 EDT -04:00,
"price_in_cents"=>50000,
"interval"=>1,
"interval_unit"=>"month",
"initial_charge_in_cents"=>nil,
"trial_price_in_cents"=>nil,
"trial_interval"=>nil,
"trial_interval_unit"=>"month",
"archived_at"=>nil,
"require_credit_card"=>true,
"return_params"=>"",
"taxable"=>true,
"update_return_url"=>"",
"tax_code"=>"4512.100",
"initial_charge_after_trial"=>false,
"version_number"=>1,
"update_return_params"=>"",
"default_product_price_point_id"=>168,
"request_billing_address"=>true,
"require_billing_address"=>true,
"require_shipping_address"=>true,
"product_price_point_id"=>168,
"product_price_point_name"=>"Original",
"product_price_point_handle"=>"uuid:0a6d2640-bfbb-0139-c94b-2cde48001122",
"product_family"=>
{"id"=>65,
"name"=>"Billing Plans",
"description"=>nil,
"handle"=>"chargify-billing-plans",
"accounting_code"=>nil,
"created_at"=>Mon, 21 Jun 2021 08:22:16 EDT -04:00,
"updated_at"=>Mon, 21 Jun 2021 08:22:16 EDT -04:00},
"public_signup_pages"=>
[{"id"=>101,
"return_url"=>nil,
"return_params"=>"",
"url"=>
"https://some-subdomain.chargifypay.test/subscribe/nmxwp8gsjh3t/golderrr"}]},
"credit_card"=>
{"id"=>885,
"first_name"=>"John",
"last_name"=>"Doe",
"masked_card_number"=>"XXXX-XXXX-XXXX-1111",
"card_type"=>"visa",
"expiration_month"=>1,
"expiration_year"=>2029,
"customer_id"=>708,
"current_vault"=>"digital_river",
"vault_token"=>"b0aeda54-7576-4457-a36b-e775d2730df8",
"billing_address"=>"Street",
"billing_city"=>"San Francisco",
"billing_state"=>"CA",
"billing_zip"=>"66785",
"billing_country"=>"US",
"customer_vault_token"=>"541159940336",
"billing_address_2"=>"",
"payment_type"=>"credit_card",
"disabled"=>false,
"site_gateway_setting_id"=>71},
"group"=>nil},
"transaction"=>
{"id"=>3556,
"subscription_id"=>784,
"type"=>"Payment",
"kind"=>nil,
"transaction_type"=>"payment",
"success"=>true,
"amount_in_cents"=>50000,
"memo"=>"John Doe - golder: Signup payment",
"created_at"=>Wed, 18 Aug 2021 05:58:43 EDT -04:00,
"starting_balance_in_cents"=>50000,
"ending_balance_in_cents"=>0,
"gateway_used"=>"digital_river",
"gateway_transaction_id"=>"3daa894a-77e5-4bd9-88b9-8e6dd1e84185",
"gateway_order_id"=>nil,
"payment_id"=>nil,
"product_id"=>154,
"tax_id"=>nil,
"component_id"=>nil,
"statement_id"=>1553,
"customer_id"=>708,
"item_name"=>nil,
"period_range_start"=>nil,
"period_range_end"=>nil,
"currency"=>"USD",
"exchange_rate"=>1,
"component_handle"=>nil,
"component_price_point_id"=>nil,
"component_price_point_handle"=>nil,
"parent_id"=>nil,
"role"=>nil,
"card_number"=>"XXXX-XXXX-XXXX-1111",
"card_expiration"=>"01/2029",
"card_type"=>"visa",
"refunded_amount_in_cents"=>0,
"invoice_id"=>nil},
"event_id"=>5432}
```
## pending_payment_failed
**Trigger:** When a Pending Payment was rejected in the gateway.
**Payload Fields:** event_id, site, subscription, transaction
## Full payload example
```json
"subscription"=>
{"id"=>784,
"state"=>"pending",
"trial_started_at"=>nil,
"trial_ended_at"=>nil,
"activated_at"=>nil,
"created_at"=>Wed, 18 Aug 2021 05:58:29 EDT -04:00,
"updated_at"=>Wed, 18 Aug 2021 05:58:43 EDT -04:00,
"expires_at"=>nil,
"balance_in_cents"=>0,
"current_period_ends_at"=>nil,
"next_assessment_at"=>nil,
"canceled_at"=>nil,
"cancellation_message"=>nil,
"next_product_id"=>nil,
"next_product_handle"=>nil,
"cancel_at_end_of_period"=>nil,
"payment_collection_method"=>"automatic",
"snap_day"=>nil,
"cancellation_method"=>nil,
"current_period_started_at"=>Wed, 18 Aug 2021 05:58:29 EDT -04:00,
"previous_state"=>"pending",
"signup_payment_id"=>3556,
"signup_revenue"=>"500.00",
"delayed_cancel_at"=>nil,
"coupon_code"=>nil,
"total_revenue_in_cents"=>50000,
"product_price_in_cents"=>50000,
"product_version_number"=>1,
"payment_type"=>"credit_card",
"referral_code"=>nil,
"coupon_use_count"=>nil,
"coupon_uses_allowed"=>nil,
"reason_code"=>nil,
"automatically_resume_at"=>nil,
"coupon_codes"=>[],
"offer_id"=>nil,
"payer_id"=>nil,
"receives_invoice_emails"=>nil,
"product_price_point_id"=>168,
"next_product_price_point_id"=>nil,
"credit_balance_in_cents"=>0,
"prepayment_balance_in_cents"=>0,
"net_terms"=>nil,
"stored_credential_transaction_id"=>nil,
"locale"=>nil,
"reference"=>nil,
"currency"=>"USD",
"on_hold_at"=>nil,
"scheduled_cancellation_at"=>nil,
"customer"=>
{"id"=>708,
"first_name"=>"John",
"last_name"=>"Doe",
"organization"=>"",
"email"=>"test@example.com",
"created_at"=>Wed, 18 Aug 2021 05:58:29 EDT -04:00,
"updated_at"=>Wed, 18 Aug 2021 05:58:29 EDT -04:00,
"reference"=>nil,
"address"=>"Street",
"address_2"=>"",
"city"=>"San Francisco",
"state"=>"CA",
"state_name"=>"California",
"zip"=>"66785",
"country"=>"US",
"country_name"=>"United States",
"phone"=>"123456789",
"portal_invite_last_sent_at"=>nil,
"portal_invite_last_accepted_at"=>nil,
"verified"=>false,
"portal_customer_created_at"=>nil,
"vat_number"=>nil,
"cc_emails"=>nil,
"tax_exempt"=>false,
"parent_id"=>nil,
"locale"=>nil},
"product"=>
{"id"=>154,
"name"=>"golder",
"handle"=>"golderrr",
"description"=>"",
"accounting_code"=>"",
"request_credit_card"=>true,
"expiration_interval"=>nil,
"expiration_interval_unit"=>"never",
"created_at"=>Mon, 05 Jul 2021 08:32:52 EDT -04:00,
"updated_at"=>Tue, 20 Jul 2021 08:08:49 EDT -04:00,
"price_in_cents"=>50000,
"interval"=>1,
"interval_unit"=>"month",
"initial_charge_in_cents"=>nil,
"trial_price_in_cents"=>nil,
"trial_interval"=>nil,
"trial_interval_unit"=>"month",
"archived_at"=>nil,
"require_credit_card"=>true,
"return_params"=>"",
"taxable"=>true,
"update_return_url"=>"",
"tax_code"=>"4512.100",
"initial_charge_after_trial"=>false,
"version_number"=>1,
"update_return_params"=>"",
"default_product_price_point_id"=>168,
"request_billing_address"=>true,
"require_billing_address"=>true,
"require_shipping_address"=>true,
"product_price_point_id"=>168,
"product_price_point_name"=>"Original",
"product_price_point_handle"=>"uuid:0a6d2640-bfbb-0139-c94b-2cde48001122",
"product_family"=>
{"id"=>65,
"name"=>"Billing Plans",
"description"=>nil,
"handle"=>"chargify-billing-plans",
"accounting_code"=>nil,
"created_at"=>Mon, 21 Jun 2021 08:22:16 EDT -04:00,
"updated_at"=>Mon, 21 Jun 2021 08:22:16 EDT -04:00},
"public_signup_pages"=>
[{"id"=>101,
"return_url"=>nil,
"return_params"=>"",
"url"=>
"https://some-subdomain.chargifypay.test/subscribe/nmxwp8gsjh3t/golderrr"}]},
"credit_card"=>
{"id"=>885,
"first_name"=>"John",
"last_name"=>"Doe",
"masked_card_number"=>"XXXX-XXXX-XXXX-1111",
"card_type"=>"visa",
"expiration_month"=>1,
"expiration_year"=>2029,
"customer_id"=>708,
"current_vault"=>"digital_river",
"vault_token"=>"b0aeda54-7576-4457-a36b-e775d2730df8",
"billing_address"=>"Street",
"billing_city"=>"San Francisco",
"billing_state"=>"CA",
"billing_zip"=>"66785",
"billing_country"=>"US",
"customer_vault_token"=>"541159940336",
"billing_address_2"=>"",
"payment_type"=>"credit_card",
"disabled"=>false,
"site_gateway_setting_id"=>71},
"group"=>nil},
"transaction"=>
{"id"=>3556,
"subscription_id"=>784,
"type"=>"Payment",
"kind"=>nil,
"transaction_type"=>"payment",
"success"=>true,
"amount_in_cents"=>50000,
"memo"=>"John Doe - golder: Signup payment",
"created_at"=>Wed, 18 Aug 2021 05:58:43 EDT -04:00,
"starting_balance_in_cents"=>50000,
"ending_balance_in_cents"=>0,
"gateway_used"=>"digital_river",
"gateway_transaction_id"=>"3daa894a-77e5-4bd9-88b9-8e6dd1e84185",
"gateway_order_id"=>nil,
"payment_id"=>nil,
"product_id"=>154,
"tax_id"=>nil,
"component_id"=>nil,
"statement_id"=>1553,
"customer_id"=>708,
"item_name"=>nil,
"period_range_start"=>nil,
"period_range_end"=>nil,
"currency"=>"USD",
"exchange_rate"=>1,
"component_handle"=>nil,
"component_price_point_id"=>nil,
"component_price_point_handle"=>nil,
"parent_id"=>nil,
"role"=>nil,
"card_number"=>"XXXX-XXXX-XXXX-1111",
"card_expiration"=>"01/2029",
"card_type"=>"visa",
"refunded_amount_in_cents"=>0,
"invoice_id"=>nil},
"event_id"=>5432}
```
## prepaid_subscription_balance_change
**Trigger:** Any change to a prepaid Subscription’s usage or prepayment balance.
**Payload Fields:** event_id, site, subscription, prepaid_configuration, customer, product, product_family, credit_card, group
## Full payload example
```json
"subscription"=>
{"id"=>129431,
"state"=>"expired",
"trial_started_at"=>nil,
"trial_ended_at"=>nil,
"activated_at"=>Mon, 09 Nov 2020 11:33:10 MST -07:00,
"created_at"=>Mon, 09 Nov 2020 11:33:09 MST -07:00,
"updated_at"=>Mon, 09 Nov 2020 11:57:26 MST -07:00,
"expires_at"=>Mon, 09 Nov 2020 11:37:00 MST -07:00,
"balance_in_cents"=>0,
"current_period_ends_at"=>nil,
"next_assessment_at"=>nil,
"canceled_at"=>nil,
"cancellation_message"=>nil,
"next_product_id"=>nil,
"next_product_handle"=>nil,
"cancel_at_end_of_period"=>nil,
"payment_collection_method"=>"prepaid",
"snap_day"=>nil,
"cancellation_method"=>nil,
"current_period_started_at"=>nil,
"previous_state"=>"active",
"signup_payment_id"=>3129166,
"signup_revenue"=>"30.00",
"delayed_cancel_at"=>nil,
"coupon_code"=>nil,
"total_revenue_in_cents"=>22000,
"product_price_in_cents"=>0,
"product_version_number"=>1,
"payment_type"=>"credit_card",
"referral_code"=>nil,
"coupon_use_count"=>nil,
"coupon_uses_allowed"=>nil,
"reason_code"=>nil,
"automatically_resume_at"=>nil,
"coupon_codes"=>[],
"offer_id"=>nil,
"payer_id"=>nil,
"receives_invoice_emails"=>nil,
"product_price_point_id"=>16695,
"next_product_price_point_id"=>nil,
"credit_balance_in_cents"=>0,
"prepayment_balance_in_cents"=>22000,
"net_terms"=>nil,
"stored_credential_transaction_id"=>nil,
"locale"=>nil,
"reference"=>nil,
"currency"=>"USD",
"on_hold_at"=>nil,
"scheduled_cancellation_at"=>nil,
"customer"=>
{"id"=>214718,
"first_name"=>"Baylee",
"last_name"=>"Brekke",
"organization"=>"Hickle, Strosin and Rice",
"email"=>"Caden20@example.com",
"created_at"=>Mon, 09 Nov 2020 11:32:39 MST -07:00,
"updated_at"=>Mon, 09 Nov 2020 11:33:11 MST -07:00,
"reference"=>nil,
"address"=>"7563 Gutkowski Crescent",
"address_2"=>"Apt. 499",
"city"=>"West Michael",
"state"=>"AZ",
"zip"=>"44635-5049",
"country"=>"US",
"phone"=>"270-305-7838",
"portal_invite_last_sent_at"=>Mon, 09 Nov 2020 11:33:11 MST -07:00,
"portal_invite_last_accepted_at"=>nil,
"verified"=>false,
"portal_customer_created_at"=>Mon, 09 Nov 2020 11:33:11 MST -07:00,
"vat_number"=>nil,
"cc_emails"=>nil,
"tax_exempt"=>false,
"parent_id"=>nil,
"locale"=>nil},
"product"=>
{"id"=>17900,
"name"=>"expires",
"handle"=>nil,
"description"=>"",
"accounting_code"=>"",
"request_credit_card"=>true,
"expiration_interval"=>1,
"expiration_interval_unit"=>"month",
"created_at"=>Mon, 09 Nov 2020 11:29:50 MST -07:00,
"updated_at"=>Mon, 09 Nov 2020 11:29:50 MST -07:00,
"price_in_cents"=>0,
"interval"=>1,
"interval_unit"=>"month",
"initial_charge_in_cents"=>nil,
"trial_price_in_cents"=>nil,
"trial_interval"=>nil,
"trial_interval_unit"=>"month",
"archived_at"=>nil,
"require_credit_card"=>false,
"return_params"=>"",
"taxable"=>false,
"update_return_url"=>"",
"tax_code"=>"",
"initial_charge_after_trial"=>false,
"version_number"=>1,
"update_return_params"=>"",
"default_product_price_point_id"=>16695,
"request_billing_address"=>false,
"require_billing_address"=>false,
"require_shipping_address"=>false,
"product_price_point_id"=>16695,
"product_price_point_name"=>"Original",
"product_price_point_handle"=>"uuid:79d63630-04e7-0139-d7d7-029b6d08343c",
"product_family"=>
{"id"=>10712,
"name"=>"Billing Plans",
"description"=>nil,
"handle"=>"acme-inc-billing-plans",
"accounting_code"=>nil,
"created_at"=>Mon, 27 Apr 2020 07:36:52 MDT -06:00,
"updated_at"=>Mon, 27 Apr 2020 07:36:52 MDT -06:00},
"public_signup_pages"=>[]},
"credit_card"=>
{"id"=>124033,
"first_name"=>"Ciara",
"last_name"=>"Heathcote",
"masked_card_number"=>"XXXX-XXXX-XXXX-1",
"card_type"=>"bogus",
"expiration_month"=>11,
"expiration_year"=>2021,
"customer_id"=>214718,
"current_vault"=>"bogus",
"vault_token"=>"1",
"billing_address"=>"1816 Brekke Wall",
"billing_city"=>"East Milo",
"billing_state"=>"IN",
"billing_zip"=>"00451-1348",
"billing_country"=>"US",
"customer_vault_token"=>nil,
"billing_address_2"=>"Apt. 650",
"payment_type"=>"credit_card",
"disabled"=>false,
"site_gateway_setting_id"=>nil},
"prepaid_configuration"=>
{"id"=>624,
"initial_funding_amount_in_cents"=>3000,
"auto_replenish"=>true,
"replenish_to_amount_in_cents"=>8000,
"replenish_threshold_amount_in_cents"=>3000},
"group"=>nil},
"reason"=>"usage changed",
"current_account_balance_in_cents"=>22000,
"event_id"=>4917496}
```
## prepaid_usage
**Trigger:** Any recorded usage for a Subscription’s prepaid component. Changes in allocation are reflected in `component_allocation_change`.
**Payload Fields:** event_id, site, component, subscription, product, previous_unit_balance, usage_quantity, previous_overage_unit_balance, new_overage_unit_balance, overage_usage_quantity, price_point_id
## Full payload example
```json
"component"=>
{"id"=>957864,
"kind"=>"prepaid_usage_component",
"name"=>"Minutes",
"unit_name"=>"minutes",
"handle"=>nil},
"subscription"=>{"id"=>32304660, "name"=>"Mario Smith"},
"product"=>{"id"=>4607690, "name"=>"Silver Plan"},
"memo"=>"",
"timestamp"=>"2020-04-28T18:34:36Z",
"price_point_id"=>821647,
"previous_unit_balance"=>"0.0",
"new_unit_balance"=>15,
"usage_quantity"=>15,
"previous_overage_unit_balance"=>"0.0",
"new_overage_unit_balance"=>5,
"overage_usage_quantity"=>5,
"event_id"=>1064815585}
```
## renewal_failure
**Trigger:** A failed periodic renewal, such as when the credit card is declined. At the end of every recurring interval, either a renewal_success or a renewal_failure event is triggered once. If a card is declined and a renewal_failure is triggered, a subsequent payment that brings the account current will not generate a renewal_success (although it will generate a payment_success and a subscription_state_change)
**Payload Fields:** event_id, site, subscription, transaction
The subscription object also contains information on the Customer and Product.
## Full payload example
```json
{"id"=>16372192,
"state"=>"past_due",
"trial_started_at"=>nil,
"trial_ended_at"=>nil,
"activated_at"=>Mon, 13 Feb 2025 11:50:57 EST -05:00,
"created_at"=>Mon, 13 Feb 2025 11:50:55 EST -05:00,
"updated_at"=>Mon, 13 Feb 2025 13:28:06 EST -05:00,
"expires_at"=>nil,
"balance_in_cents"=>16000,
"current_period_ends_at"=>Mon, 13 Mar 2025 14:28:05 EDT -04:00,
"next_assessment_at"=>Tue, 14 Feb 2025 13:28:06 EST -05:00,
"canceled_at"=>nil,
"cancellation_message"=>nil,
"next_product_id"=>nil,
"cancel_at_end_of_period"=>false,
"payment_collection_method"=>"automatic",
"snap_day"=>nil,
"cancellation_method"=>nil,
"current_period_started_at"=>Mon, 13 Feb 2025 13:28:05 EST -05:00,
"previous_state"=>"active",
"signup_payment_id"=>173961106,
"signup_revenue"=>"60.00",
"delayed_cancel_at"=>nil,
"coupon_code"=>nil,
"total_revenue_in_cents"=>6000,
"product_price_in_cents"=>5000,
"product_version_number"=>1,
"payment_type"=>nil,
"referral_code"=>"cz8wdq",
"coupon_use_count"=>nil,
"coupon_uses_allowed"=>nil,
"product_price_point_id"=>1,
"next_product_price_point_id"=>nil,
"currency"=>"USD",
"customer"=>
{"id"=>15826583,
"first_name"=>"Doris",
"last_name"=>"Tester",
"organization"=>"Acme",
"email"=>"doris@example.com",
"created_at"=>Mon, 13 Feb 2025 11:50:55 EST -05:00,
"updated_at"=>Mon, 13 Feb 2025 11:50:58 EST -05:00,
"reference"=>"123456789",
"address"=>"123 Anywhere Street",
"address_2"=>"",
"city"=>"Boston",
"state"=>"MA",
"zip"=>"02120",
"country"=>"US",
"phone"=>"555-555-1212",
"portal_invite_last_sent_at"=>Mon, 13 Feb 2025 11:50:58 EST -05:00,
"portal_invite_last_accepted_at"=>nil,
"verified"=>nil,
"portal_customer_created_at"=>Mon, 13 Feb 2025 11:50:58 EST -05:00,
"vat_number"=>"123456789"
"cc_emails"=>nil,
"tax_exempt"=>false,
"parent_id"=>nil},
"product"=>
{"id"=>4442358,
"name"=>"Gold Product",
"handle"=>"gold-product",
"description"=>"",
"accounting_code"=>"",
"request_credit_card"=>true,
"expiration_interval"=>nil,
"expiration_interval_unit"=>"never",
"created_at"=>Thu, 15 Dec 2024 09:32:36 EST -05:00,
"updated_at"=>Thu, 15 Dec 2024 09:32:36 EST -05:00,
"price_in_cents"=>5000,
"interval"=>1,
"interval_unit"=>"month",
"initial_charge_in_cents"=>nil,
"trial_price_in_cents"=>nil,
"trial_interval"=>nil,
"trial_interval_unit"=>"month",
"archived_at"=>nil,
"require_credit_card"=>true,
"return_params"=>"",
"taxable"=>false,
"update_return_url"=>"http://www.example.com",
"initial_charge_after_trial"=>false,
"version_number"=>1,
"update_return_params"=>"id={subscription_id}&ref={customer_reference}",
"default_product_price_point_id"=>1,
"product_price_point_id"=>1,
"product_price_point_handle"=>nil,
"product_family"=>
{"id"=>986840,
"name"=>"Acme Products",
"description"=>"",
"handle"=>"acme-products",
"accounting_code"=>nil},
"public_signup_pages"=>
[{"id"=>306012,
"return_url"=>"",
"return_params"=>"",
"url"=>
"https://general-goods.chargifypay.com/subscribe/7dbsnjd8t8cx/gold-product"},
{"id"=>310598,
"return_url"=>"",
"return_params"=>"",
"url"=>
"https://general-goods.chargifypay.com/subscribe/ksjh9py5fn5h/gold-product"},
{"id"=>311132,
"return_url"=>"",
"return_params"=>"",
"url"=>
"https://general-goods.chargifypay.com/subscribe/kjmks49g8d3d/gold-product"}]}},
"site"=>{"id"=>31615, "subdomain"=>"general-goods"},
"event_id"=>377601653}
```
## renewal_success
**Trigger:** A successful periodic renewal. At the end of every recurring interval, either a renewal_success or a renewal_failure event is triggered once. If a card is declined and a renewal_failure is triggered, a subsequent payment that brings the account current will not generate a renewal_success (although it will generate a payment_success and a subscription_state_change)
**Payload Fields:** event_id, site, subscription, transaction
## Full payload example
```json
{"id"=>16327080,
"state"=>"active",
"trial_started_at"=>nil,
"trial_ended_at"=>nil,
"activated_at"=>Thu, 09 Feb 2025 11:42:28 EST -05:00,
"created_at"=>Thu, 09 Feb 2025 11:42:26 EST -05:00,
"updated_at"=>Mon, 13 Feb 2025 12:03:41 EST -05:00,
"expires_at"=>nil,
"balance_in_cents"=>5667,
"current_period_ends_at"=>Wed, 08 Mar 2025 12:00:00 EST -05:00,
"next_assessment_at"=>Wed, 08 Mar 2025 12:00:00 EST -05:00,
"canceled_at"=>nil,
"cancellation_message"=>nil,
"next_product_id"=>nil,
"cancel_at_end_of_period"=>false,
"payment_collection_method"=>"automatic",
"snap_day"=>"8",
"cancellation_method"=>nil,
"current_period_started_at"=>Mon, 13 Feb 2025 12:00:00 EST -05:00,
"previous_state"=>"active",
"signup_payment_id"=>0,
"signup_revenue"=>"0.00",
"delayed_cancel_at"=>nil,
"coupon_code"=>nil,
"total_revenue_in_cents"=>0,
"product_price_in_cents"=>6900,
"product_version_number"=>1,
"payment_type"=>"credit_card",
"referral_code"=>"6zcsxw",
"coupon_use_count"=>nil,
"coupon_uses_allowed"=>nil,
"product_price_point_id"=>1,
"next_product_price_point_id"=>nil,
"currency"=>"USD",
"customer"=>
{"id"=>15780191,
"first_name"=>"Test ",
"last_name"=>"Monthly",
"organization"=>"",
"email"=>"test@example.com",
"created_at"=>Thu, 09 Feb 2025 11:42:26 EST -05:00,
"updated_at"=>Thu, 09 Feb 2025 11:42:29 EST -05:00,
"reference"=>nil,
"address"=>nil,
"address_2"=>nil,
"city"=>nil,
"state"=>nil,
"zip"=>nil,
"country"=>nil,
"phone"=>"",
"portal_invite_last_sent_at"=>Thu, 09 Feb 2025 11:42:29 EST -05:00,
"portal_invite_last_accepted_at"=>nil,
"verified"=>false,
"portal_customer_created_at"=>Thu, 09 Feb 2025 11:42:29 EST -05:00,
"vat_number"=>"123456789"
"cc_emails"=>nil,
"tax_exempt"=>false,
"parent_id"=>nil},
"product"=>
{"id"=>4458204,
"name"=>"Monthly product ",
"handle"=>"monthly-product",
"description"=>"",
"accounting_code"=>"",
"request_credit_card"=>true,
"expiration_interval"=>nil,
"expiration_interval_unit"=>"never",
"created_at"=>Wed, 08 Feb 2025 16:48:54 EST -05:00,
"updated_at"=>Wed, 08 Feb 2025 16:48:54 EST -05:00,
"price_in_cents"=>6900,
"interval"=>1,
"interval_unit"=>"month",
"initial_charge_in_cents"=>nil,
"trial_price_in_cents"=>nil,
"trial_interval"=>nil,
"trial_interval_unit"=>"month",
"archived_at"=>nil,
"require_credit_card"=>true,
"return_params"=>"",
"taxable"=>false,
"update_return_url"=>"http://www.example.com",
"initial_charge_after_trial"=>false,
"version_number"=>1,
"update_return_params"=>"id={subscription_id}&ref={customer_reference}",
"default_product_price_point_id"=>1,
"product_price_point_id"=>1,
"product_price_point_handle"=>nil,
"product_family"=>
{"id"=>986840,
"name"=>"Acme Products",
"description"=>"",
"handle"=>"acme-products",
"accounting_code"=>nil},
"public_signup_pages"=>
[{"id"=>312067,
"return_url"=>nil,
"return_params"=>"",
"url"=>
"https://general-goods.chargifypay.com/subscribe/5x8sbq29vgkn/monthly-product"},
{"id"=>312068,
"return_url"=>"",
"return_params"=>"",
"url"=>
"https://general-goods.chargifypay.com/subscribe/vsmzkwvmfqqx/monthly-product"}]},
"credit_card"=>
{"id"=>10881632,
"first_name"=>"Test",
"last_name"=>"Page",
"masked_card_number"=>"XXXX-XXXX-XXXX-1",
"card_type"=>"bogus",
"expiration_month"=>1,
"expiration_year"=>2027,
"customer_id"=>15780191,
"current_vault"=>"bogus",
"vault_token"=>"1",
"billing_address"=>nil,
"billing_city"=>nil,
"billing_state"=>nil,
"billing_zip"=>"",
"billing_country"=>nil,
"customer_vault_token"=>nil,
"billing_address_2"=>nil,
"payment_type"=>"credit_card"}},
"site"=>{"id"=>31615, "subdomain"=>"general-goods"},
"event_id"=>377575304}
```
## signup_success
**Trigger:** Any successful signup (Subscription created) through the API, application, or Public Pages.
**Payload Fields:** event_id, site, subscription
The subscription object also contains information on the Customer and Product. Component allocations are not currently included in the signup_success webhook.
## Full payload example
```json
{"id"=>16372192,
"state"=>"active",
"trial_started_at"=>nil,
"trial_ended_at"=>nil,
"activated_at"=>Mon, 13 Feb 2025 11:50:57 EST -05:00,
"created_at"=>Mon, 13 Feb 2025 11:50:55 EST -05:00,
"updated_at"=>Mon, 13 Feb 2025 11:50:57 EST -05:00,
"expires_at"=>nil,
"balance_in_cents"=>6000,
"current_period_ends_at"=>Mon, 13 Mar 2025 12:50:55 EDT -04:00,
"next_assessment_at"=>Mon, 13 Mar 2025 12:50:55 EDT -04:00,
"canceled_at"=>nil,
"cancellation_message"=>nil,
"next_product_id"=>nil,
"cancel_at_end_of_period"=>false,
"payment_collection_method"=>"automatic",
"snap_day"=>nil,
"cancellation_method"=>nil,
"current_period_started_at"=>Mon, 13 Feb 2025 11:50:55 EST -05:00,
"previous_state"=>"active",
"signup_payment_id"=>173961106,
"signup_revenue"=>"60.00",
"delayed_cancel_at"=>nil,
"coupon_code"=>nil,
"total_revenue_in_cents"=>0,
"product_price_in_cents"=>5000,
"product_version_number"=>1,
"payment_type"=>"credit_card",
"referral_code"=>"cz8wdq",
"coupon_use_count"=>nil,
"coupon_uses_allowed"=>nil,
"product_price_point_id"=>1,
"next_product_price_point_id"=>nil,
"reason_code"=>nil,
"automatically_resume_at"=>nil,
"coupon_codes"=>[],
"offer_id"=>64,
"payer_id"=>15826583,
"currency"=>"USD",
"customer"=>
{"id"=>15826583,
"first_name"=>"Doris",
"last_name"=>"Tester",
"organization"=>"Acme",
"email"=>"doris@example.com",
"created_at"=>Mon, 13 Feb 2025 11:50:55 EST -05:00,
"updated_at"=>Mon, 13 Feb 2025 11:50:55 EST -05:00,
"reference"=>"123456789",
"address"=>"123 Anywhere Street",
"address_2"=>"",
"city"=>"Boston",
"state"=>"MA",
"zip"=>"02120",
"country"=>"US",
"phone"=>"555-555-1212",
"portal_invite_last_sent_at"=>nil,
"portal_invite_last_accepted_at"=>nil,
"vat_number"=>"123456789"
"verified"=>nil,
"portal_customer_created_at"=>nil,
"vat_number"=>"123456789"
"cc_emails"=>nil,
"tax_exempt"=>false},
"product"=>
{"id"=>4442358,
"name"=>"Gold Product",
"handle"=>"gold-product",
"description"=>"",
"accounting_code"=>"",
"request_credit_card"=>true,
"expiration_interval"=>nil,
"expiration_interval_unit"=>"never",
"created_at"=>Thu, 15 Dec 2024 09:32:36 EST -05:00,
"updated_at"=>Thu, 15 Dec 2024 09:32:36 EST -05:00,
"price_in_cents"=>5000,
"interval"=>1,
"interval_unit"=>"month",
"initial_charge_in_cents"=>nil,
"trial_price_in_cents"=>nil,
"trial_interval"=>nil,
"trial_interval_unit"=>"month",
"archived_at"=>nil,
"require_credit_card"=>true,
"return_params"=>"",
"taxable"=>false,
"update_return_url"=>"http://www.example.com",
"tax_code"=>"PC040100",
"initial_charge_after_trial"=>false,
"version_number"=>1,
"update_return_params"=>"id={subscription_id}&ref={customer_reference}",
"default_product_price_point_id"=>1,
"product_price_point_id"=>1,
"product_price_point_handle"=>nil,
"product_family"=>
{"id"=>986840,
"name"=>"Acme Products",
"description"=>"",
"handle"=>"acme-products",
"accounting_code"=>nil},
"public_signup_pages"=>
[{"id"=>306012,
"return_url"=>"",
"return_params"=>"",
"url"=>
"https://general-goods.chargifypay.com/subscribe/7dbsnjd8t8cx/gold-product"},
{"id"=>310598,
"return_url"=>"",
"return_params"=>"",
"url"=>
"https://general-goods.chargifypay.com/subscribe/ksjh9py5fn5h/gold-product"},
{"id"=>311132,
"return_url"=>"",
"return_params"=>"",
"url"=>
"https://general-goods.chargifypay.com/subscribe/kjmks49g8d3d/gold-product"}]},
"credit_card"=>
{"id"=>10911728,
"first_name"=>"Doris",
"last_name"=>"Tester",
"masked_card_number"=>"XXXX-XXXX-XXXX-1111",
"card_type"=>"visa",
"expiration_month"=>1,
"expiration_year"=>2027,
"customer_id"=>15826583,
"current_vault"=>"bogus",
"vault_token"=>"1",
"billing_address"=>"123 Anywhere Street",
"billing_city"=>"Boston",
"billing_state"=>"MA",
"billing_zip"=>"02120",
"billing_country"=>"US",
"customer_vault_token"=>nil,
"billing_address_2"=>"",
"payment_type"=>"credit_card"}},
"site"=>{"id"=>31615, "subdomain"=>"general-goods"},
"event_id"=>377569865}
```
## signup_failure
**Trigger:** Any failed signup (Subscription failed to begin) through the API, application, or Public Pages. This is usually caused by a failure at the payment gateway. This event is not generated for input validation errors (i.e. forgetting to fill in a field).
**Payload Fields:** event_id, site, subscription
The subscription object also contains information on the Customer and Product.
## Full payload example
```json
{"id"=>16374036,
"state"=>"failed_to_create",
"trial_started_at"=>nil,
"trial_ended_at"=>nil,
"activated_at"=>nil,
"created_at"=>Mon, 13 Feb 2025 13:08:30 EST -05:00,
"updated_at"=>Mon, 13 Feb 2025 13:08:31 EST -05:00,
"expires_at"=>nil,
"balance_in_cents"=>6900,
"current_period_ends_at"=>Wed, 08 Mar 2025 12:00:00 EST -05:00,
"next_assessment_at"=>nil,
"canceled_at"=>nil,
"cancellation_message"=>nil,
"next_product_id"=>nil,
"cancel_at_end_of_period"=>false,
"payment_collection_method"=>"automatic",
"snap_day"=>"8",
"cancellation_method"=>nil,
"current_period_started_at"=>Mon, 13 Feb 2025 13:08:30 EST -05:00,
"previous_state"=>"failed_to_create",
"signup_payment_id"=>173970546,
"signup_revenue"=>"69.00",
"delayed_cancel_at"=>nil,
"coupon_code"=>nil,
"total_revenue_in_cents"=>0,
"product_price_in_cents"=>6900,
"product_version_number"=>1,
"payment_type"=>"credit_card",
"referral_code"=>"k9f3h5",
"coupon_use_count"=>nil,
"coupon_uses_allowed"=>nil,
"product_price_point_id"=>1,
"next_product_price_point_id"=>nil,
"payer_id"=>15828506,
"currency"=>"USD",
"customer"=>
{"id"=>15828506,
"first_name"=>"Joe",
"last_name"=>"Tester",
"organization"=>"Acme",
"email"=>"joetester@example.com",
"created_at"=>Mon, 13 Feb 2025 13:08:30 EST -05:00,
"updated_at"=>Mon, 13 Feb 2025 13:08:30 EST -05:00,
"reference"=>nil,
"address"=>nil,
"address_2"=>nil,
"city"=>nil,
"state"=>nil,
"zip"=>nil,
"country"=>nil,
"phone"=>"555-555-1212",
"portal_invite_last_sent_at"=>nil,
"portal_invite_last_accepted_at"=>nil,
"verified"=>false,
"portal_customer_created_at"=>nil,
"vat_number"=>"123456789"
"cc_emails"=>nil,
"tax_exempt"=>false,
"parent_id"=>nil},
"product"=>
{"id"=>4458204,
"name"=>"Monthly product ",
"handle"=>"monthly-product",
"description"=>"",
"accounting_code"=>"",
"request_credit_card"=>true,
"expiration_interval"=>nil,
"expiration_interval_unit"=>"never",
"created_at"=>Wed, 08 Feb 2025 16:48:54 EST -05:00,
"updated_at"=>Wed, 08 Feb 2025 16:48:54 EST -05:00,
"price_in_cents"=>6900,
"interval"=>1,
"interval_unit"=>"month",
"initial_charge_in_cents"=>nil,
"trial_price_in_cents"=>nil,
"trial_interval"=>nil,
"trial_interval_unit"=>"month",
"archived_at"=>nil,
"require_credit_card"=>true,
"return_params"=>"",
"taxable"=>false,
"update_return_url"=>"http://www.example.com",
"initial_charge_after_trial"=>false,
"version_number"=>1,
"update_return_params"=>"id={subscription_id}&ref={customer_reference}",
"default_product_price_point_id"=>1,
"product_price_point_id"=>1,
"product_price_point_handle"=>nil,
"product_family"=>
{"id"=>986840,
"name"=>"Acme Products",
"description"=>"",
"handle"=>"acme-products",
"accounting_code"=>nil},
"public_signup_pages"=>
[{"id"=>312067,
"return_url"=>nil,
"return_params"=>"",
"url"=>
"https://general-goods.chargifypay.com/subscribe/5x8sbq29vgkn/monthly-product"},
{"id"=>312068,
"return_url"=>"",
"return_params"=>"",
"url"=>
"https://general-goods.chargifypay.com/subscribe/vsmzkwvmfqqx/monthly-product"}]},
"credit_card"=>
{"id"=>10913241,
"first_name"=>"Joe",
"last_name"=>"Tester",
"masked_card_number"=>"XXXX-XXXX-XXXX-2",
"card_type"=>"bogus",
"expiration_month"=>1,
"expiration_year"=>2027,
"customer_id"=>15828506,
"current_vault"=>"bogus",
"vault_token"=>"2",
"billing_address"=>nil,
"billing_city"=>nil,
"billing_state"=>nil,
"billing_zip"=>"02120",
"billing_country"=>nil,
"customer_vault_token"=>nil,
"billing_address_2"=>nil,
"payment_type"=>"credit_card"}},
"site"=>{"id"=>31615, "subdomain"=>"general-goods"},
"event_id"=>377594843}
```
## subscription_bank_account_update
**Trigger:** When a Subscription adds or updates a bank account.
**Payload Fields:** See payload example
## Full payload example
```json
{"site"=>{"id"=>60050, "subdomain"=>"chargify-sandbox-141"},
"subscription"=>{"id"=>58501928, "state"=>"active", "balance_in_cents"=>442},
"product"=>
{"id"=>6316229,
"name"=>"Base Subscription",
"product_family_id"=>2417171,
"product_family_name"=>"Billing Scenario Testing"},
"customer"=>
{"id"=>59176626,
"first_name"=>"Samara",
"last_name"=>"Hills",
"reference"=>nil,
"organization"=>"Becker - Lynch",
"email"=>"Jesus.Jacobs@example.org"},
"previous_payment_profile"=>{},
"updated_payment_profile"=>
{"id"=>50298431,
"first_name"=>"John",
"last_name"=>"Smith",
"billing_address"=>"123 main st",
"billing_address_2"=>nil,
"billing_city"=>"Roseville",
"billing_state"=>"CA",
"billing_zip"=>"95747",
"billing_country"=>"US",
"bank_name"=>"Chase",
"masked_bank_routing_number"=>"XXXX1111",
"masked_bank_account_number"=>"XXXX1111",
"bank_account_holder_type"=>"personal",
"current_vault"=>"bogus",
"vault_token"=>"4111111111111111",
"customer_vault_token"=>nil},
"event_id"=>2946290595}
```
## subscription_card_update
**Trigger:** Any change to the active credit card–type payment profile. This includes partial card/billing address updates and deletion of PayPal payment profiles. Additions of new PayPal accounts, changes/deletions of bank account / ACH type payment profiles do not currently generate any webhooks.
**Payload Fields:** event_id, site, subscription, product, previous_payment_profile, updated_payment_profile, customer
## Full payload example
```json
"subscription"=>{"id"=>16372192, "state"=>"active", "balance_in_cents"=>0},
"product"=>
{"id"=>4442358,
"name"=>"Gold Product",
"product_family_id"=>986840,
"product_family_name"=>"Acme Products"},
"customer"=>
{"id"=>15826583,
"first_name"=>"Doris",
"last_name"=>"Tester",
"reference"=>"123456789",
"organization"=>"Acme",
"email"=>"doris@example.com"},
"previous_payment_profile"=>{},
"updated_payment_profile"=>
{"id"=>10914352,
"first_name"=>"Doris",
"last_name"=>"Tester",
"masked_card_number"=>"XXXX-XXXX-XXXX-1111",
"card_type"=>"visa",
"expiration_month"=>2,
"expiration_year"=>2025,
"current_vault"=>"bogus",
"vault_token"=>"1",
"customer_vault_token"=>nil,
"billing_address"=>"",
"billing_address_2"=>"",
"billing_city"=>"",
"billing_state"=>"",
"billing_zip"=>"",
"billing_country"=>""},
"event_id"=>377602844}
```
## subscription_group_card_update
**Trigger:** Any change to the active credit card–type payment profile on the Subscription group.
**Payload Fields:** event_id, site, subscription_group, previous_payment_profile, updated_payment_profile, customer
## Full payload example
```json
"subscription_group"=>{"uid"=>"grp_96w3wg7hhnbjk", "state"=>"active"},
"customer"=>
{"id"=>15826583,
"first_name"=>"Doris",
"last_name"=>"Tester",
"reference"=>"123456789",
"organization"=>"Acme",
"email"=>"doris@example.com"},
"previous_payment_profile"=>{},
"updated_payment_profile"=>
{"id"=>10914352,
"first_name"=>"Doris",
"last_name"=>"Tester",
"masked_card_number"=>"XXXX-XXXX-XXXX-1111",
"card_type"=>"visa",
"expiration_month"=>2,
"expiration_year"=>2025,
"current_vault"=>"bogus",
"vault_token"=>"1",
"customer_vault_token"=>nil,
"billing_address"=>"",
"billing_address_2"=>"",
"billing_city"=>"",
"billing_state"=>"",
"billing_zip"=>"",
"billing_country"=>""},
"event_id"=>377602844}
```
## subscription_group_signup_failure
**Trigger:** When a Subscription group signup fails via the Subscription Group Signup endpoint.
**Payload Fields:** See payload example
## Full payload example
```json
{"site"=>{"id"=>60050, "subdomain"=>"chargify-sandbox-141"},
"subscription_group"=>
{"payer_attributes"=>
{"first_name"=>"John",
"last_name"=>"Doe",
"email"=>"john@example.com",
"organization"=>"Acme, Inc"},
"credit_card_attributes"=>
{"full_number"=>"3", "expiration_month"=>"12", "expiration_year"=>"2031"},
"subscriptions"=>
[{"product_id"=>6323196, "primary"=>true},
{"product_id"=>6323196},
{"product_id"=>6323196}]},
"customer"=>nil,
"event_id"=>2948348361}
```
## subscription_group_signup_success
**Trigger:** When a Subscription group signup is successful via the Subscription Group Signup endpoint.
**Payload Fields:** See payload example
## Full payload example
```json
{"site"=>{"id"=>60050, "subdomain"=>"chargify-sandbox-141"},
"subscription_group"=>
{"uid"=>"grp_b32ztn6vbyh5q",
"scheme"=>1,
"customer_id"=>64261470,
"payment_profile_id"=>50310133,
"subscription_ids"=>[63100002, 63100003, 63100004],
"primary_subscription_id"=>63100002,
"next_assessment_at"=>Sun, 09 Apr 2023 10:43:49 PDT -07:00,
"state"=>"active",
"cancel_at_end_of_period"=>false},
"customer"=>
{"id"=>64261470,
"phone"=>nil,
"reference"=>nil,
"email"=>"john@example.com",
"first_name"=>"John",
"last_name"=>"Doe",
"cc_emails"=>nil,
"vat_number"=>nil,
"address"=>nil,
"address_2"=>nil,
"city"=>nil,
"country"=>nil,
"organization"=>"Acme, Inc",
"state"=>nil,
"zip"=>nil,
"parent_id"=>nil,
"created_at"=>Thu, 09 Mar 2023 09:43:49 PST -08:00,
"updated_at"=>Thu, 09 Mar 2023 09:43:49 PST -08:00,
"portal_invite_last_sent_at"=>nil,
"portal_invite_last_accepted_at"=>nil,
"verified"=>false,
"portal_customer_created_at"=>nil,
"tax_exempt"=>false,
"locale"=>nil},
"event_id"=>2948335113}
```
## subscription_prepayment_account_balance_changed
**Trigger:** When a Subscription prepayment account balance changes—either when a prepayment is applied (increasing the balance) or used to make a payment on an invoice (decreasing the balance).
**Payload Fields:** See payload example
## Full payload example
```json
{"site"=>{"id"=>60050, "subdomain"=>"chargify-sandbox-141"},
"prepayments_account"=>
{"at_time"=>Wed, 08 Mar 2023 15:18:11 PST -08:00,
"balance_in_cents"=>25000,
"balance_change_in_cents"=>25000},
"prepayments"=>
{"0"=>
{"id"=>816132545,
"applications"=>{},
"amount_in_cents"=>25000,
"external"=>"external",
"memo"=>"A memo is here"}},
"subscription"=>{"id"=>63081463},
"reason"=>"prepayment created",
"event_id"=>2946242689}
```
## subscription_product_change
**Trigger:** A successful change from an old product to a new product for a subscription. This webhook will fire for a product version change.
**Payload Fields:** event_id, site, previous_product, subscription
The subscription object also contains information on the Customer and Product.
## Full payload example
```json
{"id"=>16372192,
"state"=>"active",
"trial_started_at"=>nil,
"trial_ended_at"=>nil,
"activated_at"=>Mon, 13 Feb 2025 11:50:57 EST -05:00,
"created_at"=>Mon, 13 Feb 2025 11:50:55 EST -05:00,
"updated_at"=>Mon, 13 Feb 2025 13:40:29 EST -05:00,
"expires_at"=>nil,
"balance_in_cents"=>0,
"current_period_ends_at"=>Thu, 13 Apr 2025 14:28:00 EDT -04:00,
"next_assessment_at"=>Thu, 13 Apr 2025 14:28:00 EDT -04:00,
"canceled_at"=>nil,
"cancellation_message"=>nil,
"next_product_id"=>nil,
"cancel_at_end_of_period"=>false,
"payment_collection_method"=>"automatic",
"snap_day"=>nil,
"cancellation_method"=>nil,
"current_period_started_at"=>Mon, 13 Feb 2025 13:28:05 EST -05:00,
"previous_state"=>"active",
"signup_payment_id"=>173961106,
"signup_revenue"=>"60.00",
"delayed_cancel_at"=>nil,
"coupon_code"=>nil,
"total_revenue_in_cents"=>22000,
"product_price_in_cents"=>4900,
"product_version_number"=>1,
"payment_type"=>"credit_card",
"referral_code"=>"cz8wdq",
"coupon_use_count"=>nil,
"coupon_uses_allowed"=>nil,
"product_price_point_id"=>1,
"next_product_price_point_id"=>nil,
"customer"=>
{"id"=>15826583,
"first_name"=>"Doris",
"last_name"=>"Tester",
"organization"=>"Acme",
"email"=>"doris@example.com",
"created_at"=>Mon, 13 Feb 2025 11:50:55 EST -05:00,
"updated_at"=>Mon, 13 Feb 2025 11:50:58 EST -05:00,
"reference"=>"123456789",
"address"=>"123 Anywhere Street",
"address_2"=>"",
"city"=>"Boston",
"state"=>"MA",
"zip"=>"02120",
"country"=>"US",
"phone"=>"555-555-1212",
"portal_invite_last_sent_at"=>Mon, 13 Feb 2025 11:50:58 EST -05:00,
"portal_invite_last_accepted_at"=>nil,
"vat_number"=>"123456789"
"verified"=>nil,
"portal_customer_created_at"=>Mon, 13 Feb 2025 11:50:58 EST -05:00,
"vat_number"=>"123456789"
"cc_emails"=>nil,
"tax_exempt"=>false},
"product"=>
{"id"=>4443536,
"name"=>"Business Monthly",
"handle"=>"pd_plans_v2_business_mn_1_10",
"description"=>"Business Monthly",
"accounting_code"=>"",
"request_credit_card"=>true,
"expiration_interval"=>nil,
"expiration_interval_unit"=>"never",
"created_at"=>Mon, 19 Dec 2024 15:58:09 EST -05:00,
"updated_at"=>Mon, 19 Dec 2024 15:58:09 EST -05:00,
"price_in_cents"=>4900,
"interval"=>1,
"interval_unit"=>"month",
"initial_charge_in_cents"=>nil,
"trial_price_in_cents"=>0,
"trial_interval"=>1,
"trial_interval_unit"=>"day",
"archived_at"=>nil,
"require_credit_card"=>false,
"return_params"=>"",
"taxable"=>false,
"update_return_url"=>"http://www.example.com",
"initial_charge_after_trial"=>false,
"version_number"=>1,
"update_return_params"=>"id={subscription_id}&ref={customer_reference}",
"default_product_price_point_id"=>1,
"product_price_point_id"=>1,
"product_price_point_handle"=>nil,
"product_family"=>
{"id"=>986840,
"name"=>"Acme Products",
"description"=>"",
"handle"=>"acme-products",
"accounting_code"=>nil},
"public_signup_pages"=>
[{"id"=>306548,
"return_url"=>"",
"return_params"=>"",
"url"=>
"https://general-goods.chargifypay.com/subscribe/jtvkftj84jsq/pd_plans_v2_business_mn_1_10"}]},
"credit_card"=>
{"id"=>10914352,
"first_name"=>"Doris",
"last_name"=>"Tester",
"masked_card_number"=>"XXXX-XXXX-XXXX-1111",
"card_type"=>"visa",
"expiration_month"=>2,
"expiration_year"=>2018,
"customer_id"=>15826583,
"current_vault"=>"bogus",
"vault_token"=>"1",
"billing_address"=>"",
"billing_city"=>"",
"billing_state"=>"",
"billing_zip"=>"",
"billing_country"=>"",
"customer_vault_token"=>nil,
"billing_address_2"=>"",
"payment_type"=>"credit_card"}},
"previous_product"=>
{"id"=>4442358,
"name"=>"Gold Product",
"handle"=>"gold-product",
"description"=>"",
"accounting_code"=>"",
"request_credit_card"=>true,
"expiration_interval"=>nil,
"expiration_interval_unit"=>"never",
"created_at"=>Thu, 15 Dec 2024 09:32:36 EST -05:00,
"updated_at"=>Thu, 15 Dec 2024 09:32:36 EST -05:00,
"price_in_cents"=>5000,
"interval"=>1,
"interval_unit"=>"month",
"initial_charge_in_cents"=>nil,
"trial_price_in_cents"=>nil,
"trial_interval"=>nil,
"trial_interval_unit"=>"month",
"archived_at"=>nil,
"require_credit_card"=>true,
"return_params"=>"",
"taxable"=>false,
"update_return_url"=>"http://www.example.com",
"initial_charge_after_trial"=>false,
"version_number"=>1,
"update_return_params"=>"id={subscription_id}&ref={customer_reference}",
"default_product_price_point_id"=>1,
"product_family"=>
{"id"=>986840,
"name"=>"Acme Products",
"description"=>"",
"handle"=>"acme-products",
"accounting_code"=>nil},
"public_signup_pages"=>
[{"id"=>306012,
"return_url"=>"",
"return_params"=>"",
"url"=>
"https://general-goods.chargifypay.com/subscribe/7dbsnjd8t8cx/gold-product"},
{"id"=>310598,
"return_url"=>"",
"return_params"=>"",
"url"=>
"https://general-goods.chargifypay.com/subscribe/ksjh9py5fn5h/gold-product"},
{"id"=>311132,
"return_url"=>"",
"return_params"=>"",
"url"=>
"https://general-goods.chargifypay.com/subscribe/kjmks49g8d3d/gold-product"}]},
"site"=>{"id"=>31615, "subdomain"=>"general-goods"},
"event_id"=>377604632}
```
## subscription_product_change_scheduled
**Trigger:** A delayed product change has been successfully scheduled for a subscription — the product change is set to take effect at the subscription's next renewal rather than immediately. The webhook fires as soon as the scheduled change is created, so you can react to an upcoming product change ahead of renewal instead of waiting for `subscription_product_change`.
**Payload Fields:** event_id, site, subscription, current_product, scheduled_product, effective_at
The `current_product` object is the subscription's product today; `scheduled_product` is the product it will change to at `effective_at`. The subscription object also contains information on the Customer and Product.
## Full payload example
```json
{
"site": {
"id": 31615,
"subdomain": "general-goods"
},
"subscription": {
"id": 16372192,
"state": "active",
"balance_in_cents": 0,
"current_period_ends_at": "2025-04-13T14:28:00-04:00",
"next_assessment_at": "2025-04-13T14:28:00-04:00",
"product_price_point_id": 1,
"next_product_id": 4443537,
"next_product_price_point_id": 5,
"customer": {
"id": 15826583,
"first_name": "Doris",
"last_name": "Tester",
"email": "doris@example.com",
"reference": "123456789"
},
"product": {
"id": 4443536,
"name": "Business Monthly",
"handle": "business-monthly",
"price_in_cents": 4900,
"interval": 1,
"interval_unit": "month"
}
},
"current_product": {
"id": 4443536,
"name": "Business Monthly",
"handle": "business-monthly",
"price_in_cents": 4900,
"interval": 1,
"interval_unit": "month"
},
"scheduled_product": {
"id": 4443537,
"name": "Enterprise Monthly",
"handle": "enterprise-monthly",
"price_in_cents": 9900,
"interval": 1,
"interval_unit": "month"
},
"effective_at": "2025-04-13T14:28:00-04:00",
"event_id": 377604633
}
```
## subscription_service_credit_account_balance_changed
**Trigger:** Any change to the Subscription service credit account balance—either when credit is applied (increase) or used for payment (decrease).
**Payload Fields:** See payload example
## Full payload example
```json
{"site"=>{"id"=>60050, "subdomain"=>"chargify-sandbox-141"},
"subscription"=>{"id"=>63081463},
"reason"=>"service credit given",
"service_credits"=>
[{"id"=>1992348,
"invoice_uid"=>nil,
"entry_type"=>"Credit",
"amount_in_cents"=>1000,
"memo"=>"A memo is here"}],
"service_credit_account"=>
{"at_time"=>Wed, 08 Mar 2023 15:17:55 PST -08:00,
"balance_in_cents"=>1000,
"balance_change_in_cents"=>1000},
"event_id"=>2946242578}
```
## subscription_state_change
**Trigger:** Any change to the Subscription state. This is the “workhorse” event. Watching this event can tell you if a Subscription moves to a “bad” state, such as `past_due`.
**Payload Fields:** event_id, site, subscription
The subscription object also contains information on the Customer and Product. Note that the `subscription` object you are given contains keys for both `previous_state` and state so you can track the changes.
## Full payload example
```json
{"id"=>16372192,
"state"=>"active",
"trial_started_at"=>nil,
"trial_ended_at"=>nil,
"activated_at"=>Mon, 13 Feb 2025 11:50:57 EST -05:00,
"created_at"=>Mon, 13 Feb 2025 11:50:55 EST -05:00,
"updated_at"=>Mon, 13 Feb 2025 13:33:14 EST -05:00,
"expires_at"=>nil,
"balance_in_cents"=>16000,
"current_period_ends_at"=>Mon, 13 Mar 2025 14:28:05 EDT -04:00,
"next_assessment_at"=>Tue, 14 Feb 2025 13:28:06 EST -05:00,
"canceled_at"=>nil,
"cancellation_message"=>nil,
"next_product_id"=>nil,
"cancel_at_end_of_period"=>false,
"payment_collection_method"=>"automatic",
"snap_day"=>nil,
"cancellation_method"=>nil,
"current_period_started_at"=>Mon, 13 Feb 2025 13:28:05 EST -05:00,
"previous_state"=>"past_due",
"signup_payment_id"=>173961106,
"signup_revenue"=>"60.00",
"delayed_cancel_at"=>nil,
"coupon_code"=>nil,
"total_revenue_in_cents"=>6000,
"product_price_in_cents"=>5000,
"product_version_number"=>1,
"payment_type"=>"credit_card",
"referral_code"=>"cz8wdq",
"coupon_use_count"=>nil,
"coupon_uses_allowed"=>nil,
"product_price_point_id"=>1,
"next_product_price_point_id"=>nil,
"customer"=>
{"id"=>15826583,
"first_name"=>"Doris",
"last_name"=>"Tester",
"organization"=>"Acme",
"email"=>"doris@example.com",
"created_at"=>Mon, 13 Feb 2025 11:50:55 EST -05:00,
"updated_at"=>Mon, 13 Feb 2025 11:50:58 EST -05:00,
"reference"=>"123456789",
"address"=>"123 Anywhere Street",
"address_2"=>"",
"city"=>"Boston",
"state"=>"MA",
"zip"=>"02120",
"country"=>"US",
"phone"=>"555-555-1212",
"portal_invite_last_sent_at"=>Mon, 13 Feb 2025 11:50:58 EST -05:00,
"portal_invite_last_accepted_at"=>nil,
"vat_number"=>"123456789"
"verified"=>nil,
"portal_customer_created_at"=>Mon, 13 Feb 2025 11:50:58 EST -05:00,
"vat_number"=>"123456789"
"cc_emails"=>nil,
"tax_exempt"=>false},
"product"=>
{"id"=>4442358,
"name"=>"Gold Product",
"handle"=>"gold-product",
"description"=>"",
"accounting_code"=>"",
"request_credit_card"=>true,
"expiration_interval"=>nil,
"expiration_interval_unit"=>"never",
"created_at"=>Thu, 15 Dec 2024 09:32:36 EST -05:00,
"updated_at"=>Thu, 15 Dec 2024 09:32:36 EST -05:00,
"price_in_cents"=>5000,
"interval"=>1,
"interval_unit"=>"month",
"initial_charge_in_cents"=>nil,
"trial_price_in_cents"=>nil,
"trial_interval"=>nil,
"trial_interval_unit"=>"month",
"archived_at"=>nil,
"require_credit_card"=>true,
"return_params"=>"",
"taxable"=>false,
"update_return_url"=>"http://www.example.com",
"initial_charge_after_trial"=>false,
"version_number"=>1,
"update_return_params"=>"id={subscription_id}&ref={customer_reference}",
"default_product_price_point_id"=>1,
"product_price_point_id"=>1,
"product_price_point_handle"=>nil,
"product_family"=>
{"id"=>986840,
"name"=>"Acme Products",
"description"=>"",
"handle"=>"acme-products",
"accounting_code"=>nil},
"public_signup_pages"=>
[{"id"=>306012,
"return_url"=>"",
"return_params"=>"",
"url"=>
"https://general-goods.chargifypay.com/subscribe/7dbsnjd8t8cx/gold-product"},
{"id"=>310598,
"return_url"=>"",
"return_params"=>"",
"url"=>
"https://general-goods.chargifypay.com/subscribe/ksjh9py5fn5h/gold-product"},
{"id"=>311132,
"return_url"=>"",
"return_params"=>"",
"url"=>
"https://general-goods.chargifypay.com/subscribe/kjmks49g8d3d/gold-product"}]},
"credit_card"=>
{"id"=>10914352,
"first_name"=>"Doris",
"last_name"=>"Tester",
"masked_card_number"=>"XXXX-XXXX-XXXX-1111",
"card_type"=>"visa",
"expiration_month"=>2,
"expiration_year"=>2018,
"customer_id"=>15826583,
"current_vault"=>"bogus",
"vault_token"=>"1",
"billing_address"=>"",
"billing_city"=>"",
"billing_state"=>"",
"billing_zip"=>"",
"billing_country"=>"",
"customer_vault_token"=>nil,
"billing_address_2"=>"",
"payment_type"=>"credit_card"}},
"site"=>{"id"=>31615, "subdomain"=>"general-goods"},
"event_id"=>377602840}
```
## upcoming_renewal_notice
**Trigger:** A webhook will be generated 3 days before a subscription is set to renew.
**Payload Fields:** event_id, site, customer, email_sent, estimated_renewal_amount_in_cents, message, payment_profile, product, subscription
## Full payload example
```json
"customer" => {
"id" => 15146757,
"first_name" => "Katharine",
"last_name" => "Ross",
"reference" => nil,
"organization" => "",
"email" => "kross@example.com"},
"email_sent" => true,
"estimated_renewal_amount_in_cents" => 5000,
"message" =>
"Upcoming renewal notice sent for period ending on 02/20/2025 for Katharine Ross's subscription to Gold Product",
"payment_profile" => {
"id" => 10485399,
"first_name" => "Katharine",
"last_name" => "Ross",
"card_type" => "bogus",
"masked_card_number" => "XXXX-XXXX-XXXX-1",
"expiration_month" => 1,
"expiration_year" => 2026},
"product" => {
"id" => 4442358,
"name" => "Gold Product",
"product_family_id" => 986840,
"product_family_name" => "Acme Products"},
"subscription" => {
"id" => 15690494,
"state" => "active",
"current_period_ends_at" => Mon, 20 Feb 2025 12: 00: 00 EST - 05: 00},
"event_id" => 378968302}
```
## upgrade_downgrade_failure
**Trigger:** Any failed upgrade or downgrade.
**Payload Fields:** event_id, site, subscription, previous_product
The subscription object also contains information on the Customer and Product.
## Full payload example
```json
{"id"=>16372192,
"state"=>"active",
"trial_started_at"=>nil,
"trial_ended_at"=>nil,
"activated_at"=>Mon, 13 Feb 2025 11:50:57 EST -05:00,
"created_at"=>Mon, 13 Feb 2025 11:50:55 EST -05:00,
"updated_at"=>Mon, 13 Feb 2025 14:59:39 EST -05:00,
"expires_at"=>nil,
"balance_in_cents"=>0,
"current_period_ends_at"=>Fri, 17 Feb 2025 14:28:00 EST -05:00,
"next_assessment_at"=>Fri, 17 Feb 2025 14:28:00 EST -05:00,
"canceled_at"=>nil,
"cancellation_message"=>nil,
"next_product_id"=>nil,
"cancel_at_end_of_period"=>false,
"payment_collection_method"=>"automatic",
"snap_day"=>nil,
"cancellation_method"=>nil,
"current_period_started_at"=>Mon, 13 Feb 2025 13:28:05 EST -05:00,
"previous_state"=>"active",
"signup_payment_id"=>173961106,
"signup_revenue"=>"60.00",
"delayed_cancel_at"=>nil,
"coupon_code"=>nil,
"total_revenue_in_cents"=>6000,
"product_price_in_cents"=>4900,
"product_version_number"=>1,
"payment_type"=>nil,
"referral_code"=>"cz8wdq",
"coupon_use_count"=>nil,
"coupon_uses_allowed"=>nil,
"product_price_point_id"=>1,
"next_product_price_point_id"=>nil,
"customer"=>
{"id"=>15826583,
"first_name"=>"Doris",
"last_name"=>"Tester",
"organization"=>"Acme",
"email"=>"doristester@example.com",
"created_at"=>Mon, 13 Feb 2025 11:50:55 EST -05:00,
"updated_at"=>Mon, 13 Feb 2025 13:42:07 EST -05:00,
"reference"=>"123456789",
"address"=>"123 Anywhere Street",
"address_2"=>"",
"city"=>"Boston",
"state"=>"MA",
"zip"=>"02120",
"country"=>"US",
"phone"=>"555-555-1212",
"portal_invite_last_sent_at"=>Mon, 13 Feb 2025 11:50:58 EST -05:00,
"portal_invite_last_accepted_at"=>nil,
"verified"=>false,
"portal_customer_created_at"=>Mon, 13 Feb 2025 11:50:58 EST -05:00,
"vat_number"=>"123456789"
"cc_emails"=>"",
"tax_exempt"=>false},
"product"=>
{"id"=>4443536,
"name"=>"Business Monthly",
"handle"=>"pd_plans_v2_business_mn_1_10",
"description"=>"Business Monthly",
"accounting_code"=>"",
"request_credit_card"=>true,
"expiration_interval"=>nil,
"expiration_interval_unit"=>"never",
"created_at"=>Mon, 19 Dec 2024 15:58:09 EST -05:00,
"updated_at"=>Mon, 19 Dec 2024 15:58:09 EST -05:00,
"price_in_cents"=>4900,
"interval"=>1,
"interval_unit"=>"month",
"initial_charge_in_cents"=>nil,
"trial_price_in_cents"=>0,
"trial_interval"=>1,
"trial_interval_unit"=>"day",
"archived_at"=>nil,
"require_credit_card"=>false,
"return_params"=>"",
"taxable"=>false,
"update_return_url"=>"http://www.example.com",
"initial_charge_after_trial"=>false,
"version_number"=>1,
"update_return_params"=>"id={subscription_id}&ref={customer_reference}",
"default_product_price_point_id"=>1,
"product_price_point_id"=>1,
"product_price_point_handle"=>nil,
"product_family"=>
{"id"=>986840,
"name"=>"Acme Products",
"description"=>"",
"handle"=>"acme-products",
"accounting_code"=>nil},
"public_signup_pages"=>
[{"id"=>306548,
"return_url"=>"",
"return_params"=>"",
"url"=>
"https://general-goods.chargifypay.com/subscribe/jtvkftj84jsq/pd_plans_v2_business_mn_1_10"}]}},
"site"=>{"id"=>31615, "subdomain"=>"general-goods"},
"target_product"=>
{"id"=>4458204,
"name"=>"Monthly product ",
"handle"=>"monthly-product",
"description"=>"",
"accounting_code"=>"",
"request_credit_card"=>true,
"expiration_interval"=>nil,
"expiration_interval_unit"=>"never",
"created_at"=>Wed, 08 Feb 2025 16:48:54 EST -05:00,
"updated_at"=>Wed, 08 Feb 2025 16:48:54 EST -05:00,
"price_in_cents"=>6900,
"interval"=>1,
"interval_unit"=>"month",
"initial_charge_in_cents"=>nil,
"trial_price_in_cents"=>nil,
"trial_interval"=>nil,
"trial_interval_unit"=>"month",
"archived_at"=>nil,
"require_credit_card"=>true,
"return_params"=>"",
"taxable"=>false,
"update_return_url"=>"http://www.example.com",
"initial_charge_after_trial"=>false,
"version_number"=>1,
"update_return_params"=>"id={subscription_id}&ref={customer_reference}",
"default_product_price_point_id"=>1,
"product_price_point_id"=>1,
"product_price_point_handle"=>nil,
"product_family"=>
{"id"=>986840,
"name"=>"Acme Products",
"description"=>"",
"handle"=>"acme-products",
"accounting_code"=>nil},
"public_signup_pages"=>
[{"id"=>312067,
"return_url"=>nil,
"return_params"=>"",
"url"=>
"https://general-goods.chargifypay.com/subscribe/5x8sbq29vgkn/monthly-product"},
{"id"=>312068,
"return_url"=>"",
"return_params"=>"",
"url"=>
"https://general-goods.chargifypay.com/subscribe/vsmzkwvmfqqx/monthly-product"}]},
"event_id"=>377635953}
```
## upgrade_downgrade_success
**Trigger:** Any successful upgrade or downgrade.
**Payload Fields:** event_id, site, subscription, previous_product
The subscription object also contains information on the Customer and Product.
## Full payload example
```json
{"id"=>16297395,
"state"=>"trialing",
"trial_started_at"=>Mon, 13 Feb 2025 15:00:02 EST -05:00,
"trial_ended_at"=>Tue, 14 Feb 2025 15:00:02 EST -05:00,
"activated_at"=>Wed, 08 Feb 2025 16:23:22 EST -05:00,
"created_at"=>Tue, 07 Feb 2025 16:06:06 EST -05:00,
"updated_at"=>Mon, 13 Feb 2025 15:00:02 EST -05:00,
"expires_at"=>nil,
"balance_in_cents"=>177,
"current_period_ends_at"=>Tue, 14 Feb 2025 15:00:02 EST -05:00,
"next_assessment_at"=>Tue, 14 Feb 2025 15:00:02 EST -05:00,
"canceled_at"=>nil,
"cancellation_message"=>nil,
"next_product_id"=>nil,
"cancel_at_end_of_period"=>false,
"payment_collection_method"=>"invoice",
"snap_day"=>nil,
"cancellation_method"=>nil,
"current_period_started_at"=>Mon, 13 Feb 2025 15:00:01 EST -05:00,
"previous_state"=>"active",
"signup_payment_id"=>173249657,
"signup_revenue"=>"0.00",
"delayed_cancel_at"=>nil,
"coupon_code"=>nil,
"total_revenue_in_cents"=>0,
"product_price_in_cents"=>4900,
"product_version_number"=>1,
"payment_type"=>"credit_card",
"referral_code"=>"j63942",
"coupon_use_count"=>nil,
"coupon_uses_allowed"=>nil,
"product_price_point_id"=>1,
"next_product_price_point_id"=>nil,
"customer"=>
{"id"=>15751842,
"first_name"=>"Steve",
"last_name"=>"Test",
"organization"=>"",
"email"=>"steve@example.com",
"created_at"=>Tue, 07 Feb 2025 16:06:06 EST -05:00,
"updated_at"=>Tue, 07 Feb 2025 16:06:10 EST -05:00,
"reference"=>nil,
"address"=>nil,
"address_2"=>nil,
"city"=>nil,
"state"=>nil,
"zip"=>nil,
"country"=>nil,
"phone"=>"",
"portal_invite_last_sent_at"=>Tue, 07 Feb 2025 16:06:10 EST -05:00,
"portal_invite_last_accepted_at"=>nil,
"verified"=>false,
"portal_customer_created_at"=>Tue, 07 Feb 2025 16:06:10 EST -05:00,
"cc_emails"=>nil,
"tax_exempt"=>false},
"product"=>
{"id"=>4443536,
"name"=>"Business Monthly",
"handle"=>"pd_plans_v2_business_mn_1_10",
"description"=>"Business Monthly",
"accounting_code"=>"",
"request_credit_card"=>true,
"expiration_interval"=>nil,
"expiration_interval_unit"=>"never",
"created_at"=>Mon, 19 Dec 2024 15:58:09 EST -05:00,
"updated_at"=>Mon, 19 Dec 2024 15:58:09 EST -05:00,
"price_in_cents"=>4900,
"interval"=>1,
"interval_unit"=>"month",
"initial_charge_in_cents"=>nil,
"trial_price_in_cents"=>0,
"trial_interval"=>1,
"trial_interval_unit"=>"day",
"archived_at"=>nil,
"require_credit_card"=>false,
"return_params"=>"",
"taxable"=>false,
"update_return_url"=>"http://www.example.com",
"initial_charge_after_trial"=>false,
"version_number"=>1,
"update_return_params"=>"id={subscription_id}&ref={customer_reference}",
"default_product_price_point_id"=>1,
"product_price_point_id"=>1,
"product_price_point_handle"=>nil,
"product_family"=>
{"id"=>986840,
"name"=>"Acme Products",
"description"=>"",
"handle"=>"acme-products",
"accounting_code"=>nil},
"public_signup_pages"=>
[{"id"=>306548,
"return_url"=>"",
"return_params"=>"",
"url"=>
"https://general-goods.chargifypay.com/subscribe/jtvkftj84jsq/pd_plans_v2_business_mn_1_10"}]},
"credit_card"=>
{"id"=>10865912,
"first_name"=>"Steve",
"last_name"=>"Test",
"masked_card_number"=>"XXXX-XXXX-XXXX-1",
"card_type"=>"bogus",
"expiration_month"=>1,
"expiration_year"=>2027,
"customer_id"=>15751842,
"current_vault"=>"bogus",
"vault_token"=>"1",
"billing_address"=>nil,
"billing_city"=>nil,
"billing_state"=>nil,
"billing_zip"=>"",
"billing_country"=>nil,
"customer_vault_token"=>nil,
"billing_address_2"=>nil,
"payment_type"=>"credit_card"}},
"site"=>{"id"=>31615, "subdomain"=>"general-goods"},
"previous_product"=>
{"id"=>4453830,
"name"=>"Trial No obligation",
"handle"=>"trial-no-obligation",
"description"=>"",
"accounting_code"=>"",
"request_credit_card"=>true,
"expiration_interval"=>nil,
"expiration_interval_unit"=>"never",
"created_at"=>Mon, 23 Jan 2025 09:53:23 EST -05:00,
"updated_at"=>Thu, 26 Jan 2025 13:35:29 EST -05:00,
"price_in_cents"=>1000,
"interval"=>1,
"interval_unit"=>"month",
"initial_charge_in_cents"=>nil,
"trial_price_in_cents"=>0,
"trial_interval"=>1,
"trial_interval_unit"=>"day",
"archived_at"=>nil,
"require_credit_card"=>false,
"return_params"=>"",
"taxable"=>false,
"update_return_url"=>"http://www.example.com",
"initial_charge_after_trial"=>false,
"version_number"=>1,
"update_return_params"=>"id={subscription_id}&ref={customer_reference}",
"default_product_price_point_id"=>1,
"product_price_point_id"=>1,
"product_price_point_handle"=>nil,
"product_family"=>
{"id"=>986840,
"name"=>"Acme Products",
"description"=>"",
"handle"=>"acme-products",
"accounting_code"=>nil},
"public_signup_pages"=>
[{"id"=>310559,
"return_url"=>"",
"return_params"=>"",
"url"=>
"https://general-goods.chargifypay.com/subscribe/ngbsvxv4hq7q/trial-no-obligation"}]},
"event_id"=>377636059}
```
## statement_settled
**Trigger:** At the end of every period (e.g., at renewal). The statement_settled webhook indicates that the statement closed and payment was successfully received (or payment was not required).
## statement_closed
**Trigger:** At the end of every period (e.g., at renewal). The statement_closed webhook indicates that the statement closed but payment was not successfully received. If you receive a statement_closed webhook for a statement, you may also receive a statement_settled webhook for the statement at a later time if the statement becomes paid (e.g., after a dunning retry or card update).
## direct_debit_payment_pending
**Trigger:** When a payment is created in Stripe (waiting to be processed).
## direct_debit_payment_paid_out
**Trigger:** When a payment is successfully processed in Stripe.
## direct_debit_payment_rejected
**Trigger:** When a payment is rejected in Stripe (e.g., due to insufficient funds).
## direct_debit_payment_paid_out
**Trigger:** When a payment is successfully processed in Stripe.
## Advanced Billing API
### API Endpoints
#### List of APIs
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints
* [API Exports](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/api-exports/list-exported-proforma-invoices)
* [Advance Invoice](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/advance-invoice/issue-advance-invoice)
* [Billing Portal](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/billing-portal/enable-billing-portal-for-customer)
* [Coupons](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/coupons/create-coupon)
* [Component Features](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/component-features/list-component-features)
* [Components](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/components/create-metered-component)
* [Component Price Points](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/component-price-points/promote-component-price-point-to-default)
* [Customers](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/customers/create-customer)
* [Custom Fields](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/custom-fields/create-metafields)
* [Entitlements](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/entitlements/read-subscription-entitlements)
* [Events](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/events/list-events)
* [Events-Based Billing Segments](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/events-based-billing-segments/create-segment)
* [Feature Templates](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/feature-templates/list-feature-templates)
* [Insights](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/insights/read-site-stats)
* [Invoices](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/invoices/refund-invoice)
* [Offers](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/offers/create-offer)
* [Payment Profiles](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/payment-profiles/create-payment-profile)
* [Product Families](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/product-families/list-products-for-product-family)
* [Product Features](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/product-features/list-product-features)
* [Products](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/products/create-product)
* [Product Price Points](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/product-price-points/create-product-price-point)
* [Proforma Invoices](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/proforma-invoices/create-consolidated-proforma-invoice)
* [Reason Codes](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/reason-codes/create-reason-code)
* [Referral Codes](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/referral-codes/validate-referral-code)
* [Sales Commissions](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/sales-commissions/list-sales-commission-settings)
* [Sites](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/sites/read-site)
* [Subscriptions](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscriptions/create-subscription)
* [Subscription Components](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-components/read-subscription-component)
* [Subscription Groups](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-groups/signup-with-subscription-group)
* [Subscription Group Invoice Account](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-group-invoice-account/create-subscription-group-prepayment)
* [Subscription Group Status](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-group-status/cancel-subscriptions-in-group)
* [Subscription Invoice Account](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-invoice-account/read-account-balances)
* [Subscription Notes](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-notes/create-subscription-note)
* [Subscription Products](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-products/migrate-subscription-product)
* [Subscription Renewals](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-renewals/create-scheduled-renewal-configuration)
* [Subscription Status](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-status/retry-subscription)
* [Webhooks](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/webhooks/list-webhooks)
#### API Exports
##### List Exported Proforma Invoices
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/api-exports/list-exported-proforma-invoices
Lists exported proforma invoices for a provided `batch_id`. Use pagination to control responses returned from the server.
Example: `GET https://{subdomain}.chargify.com/api_exports/proforma_invoices/123/rows?per_page=10000&page=1`.
```http
GET /api_exports/proforma_invoices/{batch_id}/rows.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `batch_id` | `String` | Template, Required | Id of a Batch Job. |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 100. The maximum allowed values is 10000; any per_page value over 10000 will be changed to 10000.
**Default**: `100`
**Constraints**: `>= 1`, `<= 10000` |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
# Response Type
**200**: OK
[`array`](https://developers.maxio.com/http/advanced-billing-api/models/structures/proforma-invoice)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/api_exports/proforma_invoices/batch_id8/rows.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'per_page=100' \
-d 'page=1'
```
# Errors
| HTTP Status Code | Error Description |
| --- | --- |
| 404 | Not Found |
##### List Exported Invoices
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/api-exports/list-exported-invoices
Lists exported invoices for a provided `batch_id`. Use pagination to control responses returned from the server.
Example: `GET https://{subdomain}.chargify.com/api_exports/invoices/123/rows?per_page=10000&page=1`.
```http
GET /api_exports/invoices/{batch_id}/rows.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `batch_id` | `String` | Template, Required | Id of a Batch Job. |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 100. The maximum allowed values is 10000; any per_page value over 10000 will be changed to 10000.
**Default**: `100`
**Constraints**: `>= 1`, `<= 10000` |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
# Response Type
**200**: OK
[`array`](https://developers.maxio.com/http/advanced-billing-api/models/structures/invoice)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/api_exports/invoices/batch_id8/rows.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'per_page=100' \
-d 'page=1'
```
# Errors
| HTTP Status Code | Error Description |
| --- | --- |
| 404 | Not Found |
##### List Exported Subscriptions
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/api-exports/list-exported-subscriptions
Lists exported subscriptions for a provided `batch_id`. Use pagination to control responses returned from the server.
Example: `GET https://{subdomain}.chargify.com/api_exports/subscriptions/123/rows?per_page=200&page=1`.
```http
GET /api_exports/subscriptions/{batch_id}/rows.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `batch_id` | `String` | Template, Required | Id of a Batch Job. |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 100. The maximum allowed values is 10000; any per_page value over 10000 will be changed to 10000.
**Default**: `100`
**Constraints**: `>= 1`, `<= 10000` |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
# Response Type
**200**: OK
[`array`](https://developers.maxio.com/http/advanced-billing-api/models/structures/subscription)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/api_exports/subscriptions/batch_id8/rows.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'per_page=100' \
-d 'page=1'
```
# Errors
| HTTP Status Code | Error Description |
| --- | --- |
| 404 | Not Found |
##### Export Proforma Invoices
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/api-exports/export-proforma-invoices
Creates a proforma invoices export and returns a batch job object. Proforma invoices are only available on Relationship Invoicing sites.
```http
POST /api_exports/proforma_invoices.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Response Type
**201**: Created
[`Batch Job Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/batch-job-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/api_exports/proforma_invoices.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | |
| 409 | Conflict | [`Single Error ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/single-error-response) |
##### Export Invoices
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/api-exports/export-invoices
Creates an invoices export and returns a batch job object.
```http
POST /api_exports/invoices.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Response Type
**201**: Created
[`Batch Job Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/batch-job-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/api_exports/invoices.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | |
| 409 | Conflict | [`Single Error ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/single-error-response) |
##### Export Subscriptions
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/api-exports/export-subscriptions
Creates a subscriptions export and returns a batch job object.
```http
POST /api_exports/subscriptions.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Response Type
**201**: Created
[`Batch Job Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/batch-job-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/api_exports/subscriptions.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 409 | Conflict | [`Single Error ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/single-error-response) |
##### Read Proforma Invoices Export
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/api-exports/read-proforma-invoices-export
Returns a batch job object for a proforma invoices export. Proforma invoices are only available on Relationship Invoicing sites.
```http
GET /api_exports/proforma_invoices/{batch_id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `batch_id` | `String` | Template, Required | Id of a Batch Job. |
# Response Type
**200**: OK
[`Batch Job Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/batch-job-response)
# Example Usage
```bash
curl -X GET \
--url 'https://subdomain.chargify.com/api_exports/proforma_invoices/batch_id8.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description |
| --- | --- |
| 404 | Not Found |
##### Read Invoices Export
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/api-exports/read-invoices-export
Returns a batch job object for an invoices export.
```http
GET /api_exports/invoices/{batch_id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `batch_id` | `String` | Template, Required | Id of a Batch Job. |
# Response Type
**200**: OK
[`Batch Job Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/batch-job-response)
# Example Usage
```bash
curl -X GET \
--url 'https://subdomain.chargify.com/api_exports/invoices/batch_id8.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description |
| --- | --- |
| 404 | Not Found |
##### Read Subscriptions Export
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/api-exports/read-subscriptions-export
Returns a batch job object for a subscriptions export.
```http
GET /api_exports/subscriptions/{batch_id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `batch_id` | `String` | Template, Required | Id of a Batch Job. |
# Response Type
**200**: OK
[`Batch Job Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/batch-job-response)
# Example Usage
```bash
curl -X GET \
--url 'https://subdomain.chargify.com/api_exports/subscriptions/batch_id8.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description |
| --- | --- |
| 404 | Not Found |
#### Advance Invoice
##### Issue Advance Invoice
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/advance-invoice/issue-advance-invoice
Issues an invoice in advance for a subscription's next renewal date. For the most part, advance invoices function like any other invoice, except they are issued early and have special behavior upon being voided. For more information on advance invoices, including eligibility for generating one, see [Issue Invoice In Advance](https://maxio.zendesk.com/hc/en-us/articles/24252026404749-Issue-Invoice-In-Advance).
A subscription can only have one advance invoice per billing period. Attempting to issue an advance invoice when one already exists returns an error.
Regeneration of the invoice can be forced with the params `force: true`, which voids an advance invoice if one exists and generates a new one. If no advance invoice exists, a new one is generated.
Consider using either the create or preview endpoints for proforma invoices to preview this advance invoice before using this endpoint to generate it.
```http
POST /subscriptions/{subscription_id}/advance_invoice/issue.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `body` | [`Issue Advance Invoice Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/issue-advance-invoice-request) | Body, Optional | - |
# Response Type
**201**: Created
[`Invoice`](https://developers.maxio.com/http/advanced-billing-api/models/structures/invoice)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscriptions/222/advance_invoice/issue.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"force": true
}'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Read Advance Invoice
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/advance-invoice/read-advance-invoice
Returns the advance invoice generated for a subscription's upcoming renewal. There can only be one advance invoice per subscription per billing cycle.
```http
GET /subscriptions/{subscription_id}/advance_invoice.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
# Response Type
**200**: OK
[`Invoice`](https://developers.maxio.com/http/advanced-billing-api/models/structures/invoice)
# Example Usage
```bash
curl -X GET \
--url 'https://subdomain.chargify.com/subscriptions/222/advance_invoice.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description |
| --- | --- |
| 404 | Not Found |
##### Void Advance Invoice
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/advance-invoice/void-advance-invoice
Voids a subscription's existing advance invoice. Once voided, it can later be regenerated if desired.
A `reason` is required to void, and the invoice must have an open status. Voiding causes any prepayments and credits that were applied to the invoice to be returned to the subscription.
For a full overview of the impact of voiding, see [Invoice](https://developers.maxio.com/http/advanced-billing-api/models/structures/invoice).
```http
POST /subscriptions/{subscription_id}/advance_invoice/void.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `body` | [`Void Invoice Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/void-invoice-request) | Body, Optional | - |
# Response Type
**201**: Created
[`Invoice`](https://developers.maxio.com/http/advanced-billing-api/models/structures/invoice)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscriptions/222/advance_invoice/void.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description |
| --- | --- |
| 404 | Not Found |
#### Billing Portal
##### Enable Billing Portal for Customer
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/billing-portal/enable-billing-portal-for-customer
Enables Billing Portal access for a customer, with an option to send an invitation email at the same time.
## Billing Portal Security
If your customer has been invited to the Billing Portal, they receive a link to manage their subscription (the “Management URL”) automatically at the bottom of their statements, invoices, and receipts. **This link changes periodically for security and is only valid for 65 days.**
If you need to provide your customer their Management URL through other means, you can retrieve it [via the API](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/billing-portal/read-billing-portal-link). Because the URL is cryptographically signed with a timestamp, merchants cannot generate the URL without requesting it through the API.
To prevent abuse and overuse, request a new URL only when absolutely necessary. Management URLs are good for 65 days, so you should re-use a previously generated one as much as possible. If you use the URL frequently (such as to display on your website), **do not** make an API request every time.
For more information configuring the Billing Portal, see [Billing Portal Overview](https://maxio.zendesk.com/hc/en-us/articles/24252412965133-Billing-Portal-Overview).
```http
POST /portal/customers/{customer_id}/enable.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `customer_id` | `Number` | Template, Required | The Chargify id of the customer |
| `auto_invite` | [`Auto Invite`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/auto-invite) | Query, Optional | When set to 1, an Invitation email will be sent to the Customer. When set to 0, or not sent, an email will not be sent. Use in query: `auto_invite=1`. |
# Response Type
**200**: OK
[`Customer Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/customer-response)
# Example Usage
```bash
curl -X POST -G \
--url 'https://subdomain.chargify.com/portal/customers/150/enable.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Read Billing Portal Link
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/billing-portal/read-billing-portal-link
Returns the exact URL required for a subscriber to access the Billing Portal.
## Management Link Request Rules
+ When retrieving a management URL, multiple requests for the same customer in a short period return the **same** URL
+ A new URL is not generated for 15 days
+ You must cache and remember this URL if you are going to need it again within 15 days
+ Only request a new URL after the `new_link_available_at` date
+ You are limited to 15 requests for the same URL. If you make more than 15 requests before `new_link_available_at`, you are blocked from further Management URL requests (with a response code `429`).
```http
GET /portal/customers/{customer_id}/management_link.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `customer_id` | `Number` | Template, Required | The Chargify id of the customer |
# Response Type
**200**: OK
[`Portal Management Link`](https://developers.maxio.com/http/advanced-billing-api/models/structures/portal-management-link)
# Example Usage
```bash
curl -X GET \
--url 'https://subdomain.chargify.com/portal/customers/150/management_link.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"url": "https://www.billingportal.com/manage/19804639/1517596469/bd16498719a7d3e6",
"fetch_count": 1,
"created_at": "2018-02-02T18:34:29Z",
"new_link_available_at": "2018-02-17T18:34:29Z",
"expires_at": "2018-04-08T17:34:29Z",
"last_invite_sent_at": "2018-02-02T18:34:29Z"
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
| 429 | Too Many Requests | [`Too Many Management Link Requests ErrorException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/too-many-management-link-requests-error) |
##### Resend Billing Portal Invitation
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/billing-portal/resend-billing-portal-invitation
Resends a customer's Billing Portal invitation.
If you attempt to resend an invitation 5 times within 30 minutes, you will receive a `422` response with an `error` message in the body.
If you attempt to resend an invitation when the Billing Portal is already disabled for a Customer, you will receive a `422` error response.
If you attempt to resend an invitation when the Customer does not exist, you will receive a `404` error response.
## Limitations
This endpoint will only return a JSON response.
```http
POST /portal/customers/{customer_id}/invitations/invite.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `customer_id` | `Number` | Template, Required | The Chargify id of the customer |
# Response Type
**200**: OK
[`Resent Invitation`](https://developers.maxio.com/http/advanced-billing-api/models/structures/resent-invitation)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/portal/customers/150/invitations/invite.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"last_sent_at": "enim Duis esse dolore",
"last_accepted_at": "adipisicing magna do in irure",
"send_invite_link_text": "veniam sit",
"uninvited_count": 66254678
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Revoke Billing Portal Access
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/billing-portal/revoke-billing-portal-access
Revokes a customer's Billing Portal invitation.
If you attempt to revoke an invitation when the Billing Portal is already disabled for a Customer, you will receive a 422 error response.
## Limitations
This endpoint will only return a JSON response.
```http
DELETE /portal/customers/{customer_id}/invitations/revoke.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `customer_id` | `Number` | Template, Required | The Chargify id of the customer |
# Response Type
**200**: OK
[`Revoked Invitation`](https://developers.maxio.com/http/advanced-billing-api/models/structures/revoked-invitation)
# Example Usage
```bash
curl -X DELETE \
--url 'https://subdomain.chargify.com/portal/customers/150/invitations/revoke.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"last_sent_at": "Not Invited",
"last_accepted_at": "Invite Revoked",
"uninvited_count": 8
}
```
#### Coupons
##### Create Coupon
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/coupons/create-coupon
Creates a coupon under the specified product family.
You can create either a flat amount coupon, by specifying `amount_in_cents`, or percentage coupon by specifying `percentage`.
See [Apply Coupons to Subscriptions](https://maxio.zendesk.com/hc/en-us/articles/24261259337101-Coupons-and-Subscriptions) for information on applying a coupon to a subscription in the Advanced Billing UI.
```http
POST /product_families/{product_family_id}/coupons.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `product_family_id` | `Number` | Template, Required | The Advanced Billing id of the product family to which the coupon belongs |
| `body` | [`Coupon Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/coupon-request) | Body, Optional | - |
# Response Type
**201**: Created
[`Coupon Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/coupon-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/product_families/140/coupons.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"coupon": {
"name": "15% off",
"code": "15OFF",
"description": "15% off for life",
"percentage": 15.0,
"allow_negative_balance": false,
"recurring": false,
"end_date": "2012-08-29",
"product_family_id": "2",
"stackable": true,
"compounding_strategy": "compound",
"exclude_mid_period_allocations": true,
"apply_on_cancel_at_end_of_period": true
},
"restricted_products": {
"1": true
},
"restricted_components": {
"1": true,
"2": false
}
}'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### List Coupons for Product Family
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/coupons/list-coupons-for-product-family
Lists coupons for a specific product family in a site.
```http
GET /product_families/{product_family_id}/coupons.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `product_family_id` | `Number` | Template, Required | The Advanced Billing id of the product family to which the coupon belongs |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 30. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query `per_page=200`.
**Default**: `30`
**Constraints**: `<= 200` |
| `filter` | [`List Coupons Filter`](https://developers.maxio.com/http/advanced-billing-api/models/structures/list-coupons-filter) | Query, Optional | Filter to use for List Coupons operations |
| `currency_prices` | `Boolean` | Query, Optional | (Optional) If you have defined multiple currencies at the site level, you can pass `?currency_prices=true` to include an array of currency price data in the response. Use in query `currency_prices=true`. |
# Response Type
**200**: OK
[`array`](https://developers.maxio.com/http/advanced-billing-api/models/structures/coupon-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/product_families/140/coupons.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'page=1' \
-d 'per_page=50' \
-d 'filter[start_date]=2011-12-17' \
-d 'filter[end_date]=2011-12-15' \
-d 'filter[start_datetime]=2011-12-19T10%3A15%3A30%2B01%3A00' \
-d 'filter[end_datetime]=2019-06-07T17%3A20%3A06Z' \
-d 'filter[ids]=1%2C2%2C3' \
-d 'filter[codes]=free%2Cfree_trial' \
-d 'currency_prices=true'
```
# Example Response *(as JSON)*
```json
[
{
"coupon": {
"id": 999999,
"name": "50% coupon",
"code": "50PERCENT",
"description": "50 PERCENT OFF",
"amount_in_cents": null,
"product_family_id": 527890,
"created_at": "2016-10-21T17:02:08-04:00",
"updated_at": "2016-10-21T17:06:11-04:00",
"start_date": "2016-10-21T17:02:08-04:00",
"end_date": null,
"percentage": "50",
"recurring": true,
"duration_period_count": null,
"duration_interval": 1,
"duration_interval_unit": "day",
"allow_negative_balance": true,
"archived_at": null,
"conversion_limit": "100",
"stackable": false,
"compounding_strategy": "compound",
"use_site_exchange_rate": true
}
},
{
"coupon": {
"id": 123456,
"name": "100% coupon",
"code": "100PERCENT",
"description": "100 PERCENT OFF",
"amount_in_cents": null,
"product_family_id": 527890,
"created_at": "2016-10-21T17:02:08-04:00",
"updated_at": "2016-10-21T17:06:11-04:00",
"start_date": "2016-10-21T17:02:08-04:00",
"end_date": null,
"percentage": "50",
"recurring": true,
"duration_period_count": null,
"duration_interval": 1,
"duration_interval_unit": "day",
"allow_negative_balance": true,
"archived_at": null,
"conversion_limit": "100",
"stackable": false,
"compounding_strategy": "compound",
"use_site_exchange_rate": true
}
},
{
"coupon": {
"id": 888888,
"name": "25% coupon",
"code": "25PERCENT",
"description": "25 PERCENT OFF",
"amount_in_cents": null,
"product_family_id": 527890,
"created_at": "2016-10-21T17:02:08-04:00",
"updated_at": "2016-10-21T17:06:11-04:00",
"start_date": "2016-10-21T17:02:08-04:00",
"end_date": null,
"percentage": "25",
"recurring": true,
"duration_period_count": null,
"duration_interval": 1,
"duration_interval_unit": "day",
"allow_negative_balance": true,
"archived_at": null,
"conversion_limit": "100",
"stackable": false,
"compounding_strategy": "compound",
"coupon_restrictions": [
{
"id": 37,
"item_type": "Component",
"item_id": 519,
"name": "test",
"handle": null
}
],
"use_site_exchange_rate": true
}
}
]
```
##### Find Coupon
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/coupons/find-coupon
Searches for a coupon by code.
If you have more than one product family and if the coupon you are trying to find does not belong to the default product family in your site, you need to specify (either in the URL or as a query string param) the `product_family_id`.
```http
GET /coupons/find.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `product_family_id` | `Number` | Query, Optional | The Advanced Billing id of the product family to which the coupon belongs |
| `code` | `String` | Query, Optional | The code of the coupon |
| `currency_prices` | `Boolean` | Query, Optional | (Optional) If you have defined multiple currencies at the site level, you can pass `?currency_prices=true` to include an array of currency price data in the response. |
# Response Type
**200**: OK
[`Coupon Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/coupon-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/coupons/find.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'currency_prices=true'
```
##### Read Coupon
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/coupons/read-coupon
Returns a coupon by its system-assigned ID. You must identify the Coupon in this call by the ID parameter assigned to it.
If instead you would like to find a Coupon using a Coupon code, use the [Find Coupon](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/coupons/find-coupon) endpoint.
If the coupon is set to `use_site_exchange_rate: true`, it returns pricing based on the current exchange rate. If the flag is set to false, it returns all of the defined prices for each currency.
```http
GET /product_families/{product_family_id}/coupons/{coupon_id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `product_family_id` | `Number` | Template, Required | The Advanced Billing id of the product family to which the coupon belongs |
| `coupon_id` | `Number` | Template, Required | The Advanced Billing id of the coupon |
| `currency_prices` | `Boolean` | Query, Optional | (Optional) If you have defined multiple currencies at the site level, you can pass `?currency_prices=true` to include an array of currency price data in the response. |
# Response Type
**200**: OK
[`Coupon Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/coupon-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/product_families/140/coupons/162.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'currency_prices=true'
```
# Example Response *(as JSON)*
```json
{
"coupon": {
"id": 67,
"name": "Foo Bar",
"code": "YEPPER99934",
"description": "my cool coupon",
"amount_in_cents": null,
"product_family_id": 4,
"product_family_name": "Billing Plans",
"created_at": "2017-11-08T10:01:15-05:00",
"updated_at": "2017-11-08T10:01:15-05:00",
"start_date": "2017-11-08T10:01:15-05:00",
"end_date": null,
"percentage": "33.3333",
"duration_period_count": null,
"duration_interval": null,
"duration_interval_unit": null,
"allow_negative_balance": false,
"archived_at": null,
"conversion_limit": null,
"stackable": true,
"compounding_strategy": "compound"
}
}
```
##### Update Coupon
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/coupons/update-coupon
Updates a coupon.
You can restrict a coupon to only apply to specific products / components by optionally passing in hashes of `restricted_products` and/or `restricted_components` in the format:
`{ "": boolean_value }`
```http
PUT /product_families/{product_family_id}/coupons/{coupon_id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `product_family_id` | `Number` | Template, Required | The Advanced Billing id of the product family to which the coupon belongs |
| `coupon_id` | `Number` | Template, Required | The Advanced Billing id of the coupon |
| `body` | [`Coupon Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/coupon-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Coupon Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/coupon-response)
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/product_families/140/coupons/162.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"coupon": {
"name": "15% off",
"code": "15OFF",
"description": "15% off for life",
"percentage": 15.0,
"allow_negative_balance": false,
"recurring": false,
"end_date": "2012-08-29",
"product_family_id": "2",
"stackable": true,
"compounding_strategy": "compound"
},
"restricted_products": {
"1": true
},
"restricted_components": {
"1": true,
"2": false
}
}'
```
# Example Response *(as JSON)*
```json
{
"coupon": {
"id": 67,
"name": "Foo Bar",
"code": "YEPPER99934",
"description": "my cool coupon",
"amount_in_cents": 10000,
"product_family_id": 4,
"created_at": "2017-11-08T10:01:15-05:00",
"updated_at": "2017-11-08T10:01:15-05:00",
"start_date": "2017-11-08T10:01:15-05:00",
"end_date": null,
"percentage": null,
"recurring": false,
"duration_period_count": null,
"duration_interval": null,
"duration_interval_unit": null,
"allow_negative_balance": false,
"archived_at": null,
"conversion_limit": null,
"stackable": true,
"compounding_strategy": "compound"
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Archive Coupon
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/coupons/archive-coupon
Archives a coupon, making it unavailable for future use while remaining active on existing subscriptions.
Archiving makes that Coupon unavailable for future use, but allows it to remain attached and functional on existing Subscriptions that are using it.
The `archived_at` date and time will be assigned.
```http
DELETE /product_families/{product_family_id}/coupons/{coupon_id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `product_family_id` | `Number` | Template, Required | The Advanced Billing id of the product family to which the coupon belongs |
| `coupon_id` | `Number` | Template, Required | The Advanced Billing id of the coupon |
# Response Type
**200**: OK
[`Coupon Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/coupon-response)
# Example Usage
```bash
curl -X DELETE \
--url 'https://subdomain.chargify.com/product_families/140/coupons/162.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"coupon": {
"id": 67,
"name": "Foo Bar",
"code": "YEPPER99934",
"description": "my cool coupon",
"amount_in_cents": 10000,
"product_family_id": 4,
"created_at": "2017-11-08T10:01:15-05:00",
"updated_at": "2017-11-08T10:01:15-05:00",
"start_date": "2017-11-08T10:01:15-05:00",
"end_date": null,
"percentage": null,
"recurring": false,
"duration_period_count": null,
"duration_interval": null,
"duration_interval_unit": null,
"allow_negative_balance": false,
"archived_at": "2016-12-02T13:09:33-05:00",
"conversion_limit": null,
"stackable": true,
"compounding_strategy": "compound"
}
}
```
##### List Coupons
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/coupons/list-coupons
Lists coupons for a site.
```http
GET /coupons.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 30. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query `per_page=200`.
**Default**: `30`
**Constraints**: `<= 200` |
| `filter` | [`List Coupons Filter`](https://developers.maxio.com/http/advanced-billing-api/models/structures/list-coupons-filter) | Query, Optional | Filter to use for List Coupons operations |
| `currency_prices` | `Boolean` | Query, Optional | (Optional) If you have defined multiple currencies at the site level, you can pass `?currency_prices=true` to include an array of currency price data in the response. Use in query `currency_prices=true`. |
# Response Type
**200**: OK
[`array`](https://developers.maxio.com/http/advanced-billing-api/models/structures/coupon-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/coupons.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'page=1' \
-d 'per_page=50' \
-d 'filter[start_date]=2011-12-17' \
-d 'filter[end_date]=2011-12-15' \
-d 'filter[start_datetime]=2011-12-19T10%3A15%3A30%2B01%3A00' \
-d 'filter[end_datetime]=2019-06-07T17%3A20%3A06Z' \
-d 'filter[ids]=1%2C2%2C3' \
-d 'filter[codes]=free%2Cfree_trial' \
-d 'currency_prices=true'
```
# Example Response *(as JSON)*
```json
[
{
"coupon": {
"id": 0,
"name": "string",
"code": "string",
"description": "string",
"amount": 0,
"amount_in_cents": 0,
"product_family_id": 0,
"product_family_name": "string",
"start_date": "2021-05-03T16:00:21-04:00",
"end_date": "2023-05-05T16:00:21-04:00",
"percentage": "10",
"recurring": true,
"recurring_scheme": "do_not_recur",
"duration_period_count": 0,
"duration_interval": 0,
"duration_interval_unit": "string",
"duration_interval_span": "string",
"allow_negative_balance": true,
"archived_at": null,
"conversion_limit": "string",
"stackable": true,
"compounding_strategy": "compound",
"use_site_exchange_rate": true,
"created_at": "2021-05-05T16:00:21-04:00",
"updated_at": "2021-05-05T16:00:21-04:00",
"discount_type": "amount",
"exclude_mid_period_allocations": true,
"apply_on_cancel_at_end_of_period": true,
"coupon_restrictions": [
{
"id": 0,
"item_type": "Component",
"item_id": 0,
"name": "string",
"handle": "string"
}
]
}
}
]
```
##### Read Coupon Usage
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/coupons/read-coupon-usage
Lists coupon usage details, one entry per product.
```http
GET /product_families/{product_family_id}/coupons/{coupon_id}/usage.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `product_family_id` | `Number` | Template, Required | The Advanced Billing id of the product family to which the coupon belongs. |
| `coupon_id` | `Number` | Template, Required | The Advanced Billing id of the coupon. |
# Response Type
**200**: OK
[`array`](https://developers.maxio.com/http/advanced-billing-api/models/structures/coupon-usage)
# Example Usage
```bash
curl -X GET \
--url 'https://subdomain.chargify.com/product_families/140/coupons/162/usage.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
[
{
"name": "No cost product",
"id": 3903594,
"signups": 0,
"savings": 0,
"savings_in_cents": 0,
"revenue": 0,
"revenue_in_cents": 0
},
{
"name": "Product that expires",
"id": 3853680,
"signups": 0,
"savings": 0,
"savings_in_cents": 0,
"revenue": 0,
"revenue_in_cents": 0
},
{
"name": "Trial Product",
"id": 3861800,
"signups": 1,
"savings": 30,
"savings_in_cents": 3000,
"revenue": 20,
"revenue_in_cents": 2000
}
]
```
##### Validate Coupon
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/coupons/validate-coupon
Verifies whether a specific coupon code is valid. This method is useful for validating coupon codes that are entered by a customer.
If you have more than one product family and if the coupon you are validating does not belong to the first product family in your site, you need to specify the product family, either in the URL or as a query string param. This can be done by supplying the id or the handle in the `handle:my-family` format.
Supplying the `product_family_handle` in the URL:
```
https://.chargify.com/product_families/handle:/coupons/validate.?code=
```
Supplying the `product_family_id` as a query parameter:
```
https://.chargify.com/coupons/validate.?code=&product_family_id=
```
```http
GET /coupons/validate.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `code` | `String` | Query, Required | The code of the coupon |
| `product_family_id` | `Number` | Query, Optional | The Advanced Billing id of the product family to which the coupon belongs |
# Response Type
**200**: OK
[`Coupon Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/coupon-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/coupons/validate.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'code=code8'
```
# Example Response *(as JSON)*
```json
{
"coupon": {
"id": 66,
"name": "Foo Bar",
"code": "YEPPER9993",
"description": "my cool coupon",
"amount_in_cents": 10000,
"product_family_id": 4,
"created_at": "2017-11-07T14:51:52-05:00",
"updated_at": "2017-11-07T15:14:24-05:00",
"start_date": "2017-11-07T14:51:52-05:00",
"end_date": null,
"percentage": null,
"recurring": false,
"duration_period_count": null,
"duration_interval": null,
"duration_interval_unit": null,
"allow_negative_balance": false,
"archived_at": null,
"conversion_limit": null,
"stackable": true,
"compounding_strategy": "full-price"
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | [`Single String Error ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/single-string-error-response) |
##### Create or Update Coupon Currency Prices
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/coupons/create-or-update-coupon-currency-prices
Creates and/or updates currency prices for an existing coupon. Multiple prices can be created or updated in a single request but each of the currencies must be defined on the site level already and the coupon must be an amount-based coupon, not percentage.
Currency pricing for coupons must mirror the setup of the primary coupon pricing - if the primary coupon is percentage based, you will not be able to define pricing in non-primary currencies.
```http
PUT /coupons/{coupon_id}/currency_prices.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `coupon_id` | `Number` | Template, Required | The Advanced Billing id of the coupon |
| `body` | [`Coupon Currency Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/coupon-currency-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Coupon Currency Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/coupon-currency-response)
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/coupons/162/currency_prices.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"currency_prices": [
{
"currency": "EUR",
"price": 10
},
{
"currency": "GBP",
"price": 9
}
]
}'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error String Map ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-string-map-response) |
##### Create Coupon Subcodes
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/coupons/create-coupon-subcodes
Creates subcodes for an existing coupon.
Coupon Subcodes allow you to create a set of unique codes that allow you to expand the use of one coupon.
For example:
Master Coupon Code:
+ SPRING2020
Coupon Subcodes:
+ SPRING90210
+ DP80302
+ SPRINGBALTIMORE
When creating a coupon subcode, you must specify a coupon to attach it to using the coupon_id. Valid coupon subcodes are all capital letters, contain only letters and numbers, and do not have any spaces. Lowercase letters are capitalized before the subcode is created.
Note: If you are using any of the allowed special characters ("%", "@", "+", "-", "_", and "."), you must encode them for use in the URL.
% to %25
@ to %40
+ to %2B
- to %2D
_ to %5F
. to %2E
So, if the coupon subcode is `20%OFF`, the URL to delete this coupon subcode would be: `https://.chargify.com/coupons/567/codes/20%25OFF.`.
For more information on coupon codes and applying coupons to subscriptions, see [Coupon Codes](https://maxio.zendesk.com/hc/en-us/articles/24261208729229-Coupon-Codes) and [Coupons and Subscriptions](https://maxio.zendesk.com/hc/en-us/articles/24261259337101-Coupons-and-Subscriptions).
```http
POST /coupons/{coupon_id}/codes.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `coupon_id` | `Number` | Template, Required | The Advanced Billing id of the coupon |
| `body` | [`Coupon Subcodes`](https://developers.maxio.com/http/advanced-billing-api/models/structures/coupon-subcodes) | Body, Optional | - |
# Response Type
**200**: OK
[`Coupon Subcodes Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/coupon-subcodes-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/coupons/162/codes.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"codes": [
"BALTIMOREFALL",
"ORLANDOFALL",
"DETROITFALL"
]
}'
```
# Example Response *(as JSON)*
```json
{
"created_codes": [
"BALTIMOREFALL",
"ORLANDOFALL",
"DETROITFALL"
]
}
```
##### List Coupon Subcodes
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/coupons/list-coupon-subcodes
Lists the subcodes attached to a coupon.
```http
GET /coupons/{coupon_id}/codes.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `coupon_id` | `Number` | Template, Required | The Advanced Billing id of the coupon |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query `per_page=200`.
**Default**: `20`
**Constraints**: `<= 200` |
# Response Type
**200**: OK
[`Coupon Subcodes`](https://developers.maxio.com/http/advanced-billing-api/models/structures/coupon-subcodes)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/coupons/162/codes.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'page=1' \
-d 'per_page=50'
```
# Example Response *(as JSON)*
```json
{
"codes": [
"3JU6PR",
"9RO6MP",
"8OG1VV",
"5FL7VV",
"2SV8XK",
"4LW8LH",
"3VL4GZ",
"9UI9XO",
"0LZ0CC",
"8XI9JV",
"9UV5YE",
"3UI4GX",
"6SL5ST",
"9WC8IJ",
"2KA3PZ",
"7WR1VR",
"3VY7MN",
"6KC3KB",
"7DF7YT",
"9FH1ED"
]
}
```
##### Update Coupon Subcodes
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/coupons/update-coupon-subcodes
Updates the subcodes for a coupon, replacing all existing subcodes with the new list.
Send an array of new coupon subcodes.
**Note**: All current subcodes for that Coupon will be deleted first, and replaced with the list of subcodes sent to this endpoint.
The response will contain:
+ The created subcodes,
+ Subcodes that were not created because they already exist,
+ Any subcodes not created because they are invalid.
```http
PUT /coupons/{coupon_id}/codes.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `coupon_id` | `Number` | Template, Required | The Advanced Billing id of the coupon |
| `body` | [`Coupon Subcodes`](https://developers.maxio.com/http/advanced-billing-api/models/structures/coupon-subcodes) | Body, Optional | - |
# Response Type
**200**: OK
[`Coupon Subcodes Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/coupon-subcodes-response)
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/coupons/162/codes.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"codes": [
"AAAA",
"BBBB",
"CCCC"
]
}'
```
##### Delete Coupon Subcode
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/coupons/delete-coupon-subcode
Deletes a specific subcode from a coupon.
## Example
Given a coupon with an ID of 567, and a coupon subcode of 20OFF, the URL to `DELETE` this coupon subcode would be:
```
http://subdomain.chargify.com/coupons/567/codes/20OFF.
```
Note: If you are using any of the allowed special characters (“%”, “@”, “+”, “-”, “_”, and “.”), you must encode them for use in the URL.
| Special character | Encoding |
|-------------------|----------|
| % | %25 |
| @ | %40 |
| + | %2B |
| – | %2D |
| _ | %5F |
| . | %2E |
## Percent Encoding Example
Or if the coupon subcode is 20%OFF, the URL to delete this coupon subcode would be: @https://.chargify.com/coupons/567/codes/20%25OFF..
```http
DELETE /coupons/{coupon_id}/codes/{subcode}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `coupon_id` | `Number` | Template, Required | The Advanced Billing id of the coupon to which the subcode belongs |
| `subcode` | `String` | Template, Required | The subcode of the coupon |
# Response Type
**200**: OK
`Void`
# Example Usage
```bash
curl -X DELETE \
--url 'https://subdomain.chargify.com/coupons/162/codes/subcode4.json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description |
| --- | --- |
| 404 | Not Found |
#### Component Features
##### List Component Features
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/component-features/list-component-features
Returns the feature catalog items attached to this component, including price-point-specific overrides.
```http
GET /components/{component_id}/features.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `component_id` | `Number` | Template, Required | The Advanced Billing id of the component. |
# Response Type
**200**: OK
[`Feature Catalog Items List Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/feature-catalog-items-list-response)
# Example Usage
```bash
curl -X GET \
--url 'https://subdomain.chargify.com/components/222/features.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 403 | Forbidden | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
| 404 | Not Found | |
##### Create Component Feature
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/component-features/create-component-feature
Attaches a feature template to this component with a concrete value. Pass `price_point_type: "PricePoint"` and `price_point_id` to create an override scoped to a single component price point instead of the whole component.
```http
POST /components/{component_id}/features.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `component_id` | `Number` | Template, Required | The Advanced Billing id of the component. |
| `body` | [`Create Feature Catalog Item Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/create-feature-catalog-item-request) | Body, Optional | The owning product or component is taken from the URL and must not be included in the request body. |
# Response Type
**201**: Created
[`Feature Catalog Item Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/feature-catalog-item-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/components/222/features.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"feature": {
"feature_template_id": 196,
"value": "value6",
"propagate_to_subscriptions": false
}
}'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 403 | Forbidden | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
| 404 | Not Found | |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Read Component Feature
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/component-features/read-component-feature
Returns a single feature catalog item attached to this component.
```http
GET /components/{component_id}/features/{id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `component_id` | `Number` | Template, Required | The Advanced Billing id of the component. |
| `id` | `Number` | Template, Required | The Advanced Billing id of the feature catalog item. |
# Response Type
**200**: OK
[`Feature Catalog Item Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/feature-catalog-item-response)
# Example Usage
```bash
curl -X GET \
--url 'https://subdomain.chargify.com/components/222/features/112.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 403 | Forbidden | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
| 404 | Not Found | |
##### Update Component Feature
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/component-features/update-component-feature
Updates the value or periodicity of a feature catalog item attached to this component.
```http
PUT /components/{component_id}/features/{id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `component_id` | `Number` | Template, Required | The Advanced Billing id of the component. |
| `id` | `Number` | Template, Required | The Advanced Billing id of the feature catalog item. |
| `body` | [`Update Feature Catalog Item Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/update-feature-catalog-item-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Feature Catalog Item Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/feature-catalog-item-response)
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/components/222/features/112.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"feature": {
"propagate_to_subscriptions": false
}
}'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 403 | Forbidden | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
| 404 | Not Found | |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Remove Component Feature
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/component-features/remove-component-feature
Removes a feature catalog item from this component.
```http
DELETE /components/{component_id}/features/{id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `component_id` | `Number` | Template, Required | The Advanced Billing id of the component. |
| `id` | `Number` | Template, Required | The Advanced Billing id of the feature catalog item. |
| `destroy_entitlements` | `Boolean` | Query, Optional | When `true`, permanently deletes this feature catalog item and every entitlement it created, revoking subscriber access immediately. When `false` (default), the feature catalog item is archived and existing entitlements are preserved.
**Default**: `false` |
# Response Type
**204**: No Content
`Void`
# Example Usage
```bash
curl -X DELETE -G \
--url 'https://subdomain.chargify.com/components/222/features/112.json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'destroy_entitlements=false'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 403 | Forbidden | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
| 404 | Not Found | |
##### Restore Component Feature
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/component-features/restore-component-feature
Returns `422` if the parent feature template is still archived — restore the feature template first.
```http
POST /components/{component_id}/features/{id}/restore.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `component_id` | `Number` | Template, Required | The Advanced Billing id of the component. |
| `id` | `Number` | Template, Required | The Advanced Billing id of the feature catalog item. |
# Response Type
**200**: OK
[`Feature Catalog Item Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/feature-catalog-item-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/components/222/features/112/restore.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 403 | Forbidden | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
| 404 | Not Found | |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
#### Components
##### Create Metered Component
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/components/create-metered-component
Creates a metered component definition under the specified product family. A metered component can then be added and “allocated” for a subscription.
Metered components are used to bill for any type of unit that resets to 0 at the end of the billing period (think daily Google Ads clicks or monthly cell phone minutes). This is most commonly associated with usage-based billing and many other pricing schemes.
Note that this is different from recurring quantity-based components, which DO NOT reset to zero at the start of every billing period. If you want to bill for a quantity of something that does not change unless you change it, then you want quantity components, instead.
#### Hybrid Pricing
A `volume`, `tiered`, or `stairstep` metered component can combine its primary pricing with a secondary pricing model (the `overage_pricing` parameter) so both bill as a single invoice line item instead of two. This does not apply to metered components configured for event-based billing (metric, meter, or formula). See [Hybrid Pricing](https://developers.maxio.com/http/getting-started/advanced-billing-concepts/hybrid-pricing) for requirements and configuration details.
For more information on components, see our documentation [here](https://maxio.zendesk.com/hc/en-us/articles/24261141522189-Components-Overview).
If you have the new [Catalog experience](https://developers.maxio.com/http/help/announcements/2026-announcements#new-catalog-experience-and-terminology) enabled, taxable components must include a non-blank `tax_code`. Sending `"tax_code": ""` returns `422`.
```http
POST /product_families/{product_family_id}/metered_components.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `product_family_id` | `String` | Template, Required | Either the product family's id or its handle prefixed with `handle:` |
| `body` | [`Create Metered Component`](https://developers.maxio.com/http/advanced-billing-api/models/structures/create-metered-component) | Body, Optional | - |
# Response Type
**201**: Created
[`Component Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/component-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/product_families/product_family_id4/metered_components.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"metered_component": {
"name": "Text messages",
"unit_name": "text message",
"pricing_scheme": "per_unit",
"taxable": false,
"prices": [
{
"starting_quantity": 1,
"unit_price": 1.0
}
]
}
}'
```
# Example Response *(as JSON)*
```json
{
"component": {
"id": 292609,
"name": "Text messages",
"handle": "text-messages",
"pricing_scheme": "per_unit",
"unit_name": "unit",
"unit_price": "10.0",
"product_family_id": 528484,
"product_family_name": "Cloud Compute Servers",
"price_per_unit_in_cents": null,
"kind": "metered_component",
"archived": false,
"taxable": false,
"description": null,
"default_price_point_id": 2944263,
"prices": [
{
"id": 55423,
"component_id": 30002,
"starting_quantity": 1,
"ending_quantity": null,
"unit_price": "10.0",
"price_point_id": 2944263,
"formatted_unit_price": "$10.00",
"segment_id": null
}
],
"price_point_count": 1,
"price_points_url": "https://demo-3238403362.chargify.com/components/30002/price_points",
"default_price_point_name": "Original",
"tax_code": null,
"recurring": false,
"upgrade_charge": null,
"downgrade_credit": null,
"created_at": "2024-01-23T06:08:05-05:00",
"updated_at": "2024-01-23T06:08:05-05:00",
"archived_at": null,
"hide_date_range_on_invoice": false,
"allow_fractional_quantities": false,
"use_site_exchange_rate": true,
"item_category": null,
"accounting_code": null
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Create Quantity Based Component
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/components/create-quantity-based-component
Creates a Quantity Based component definition under the specified product family. A Quantity Based component can then be added and “allocated” for a subscription.
When defining a Quantity Based component, you can choose one of two types:
#### Recurring
Recurring quantity-based components are used to bill for the number of some unit (think monthly software user licenses or the number of pairs of socks in a box-a-month club). This is most commonly associated with billing for user licenses, number of users, number of employees, etc.
#### One-time
One-time quantity-based components are used to create ad hoc usage charges that do not recur. For example, at the time of signup, you might want to charge your customer a one-time fee for onboarding or other services.
The allocated quantity for one-time quantity-based components immediately gets reset back to zero after the allocation is made.
For more information, see [Components Overview](https://maxio.zendesk.com/hc/en-us/articles/24261141522189-Components-Overview).
#### Hybrid Pricing
A `volume`, `tiered`, or `stairstep` component can combine its primary pricing with a secondary pricing model (the `overage_pricing` parameter) so both bill as a single invoice line item instead of two. See [Hybrid Pricing](https://developers.maxio.com/http/getting-started/advanced-billing-concepts/hybrid-pricing) for requirements and configuration details.
For more information on components, see our documentation [here](https://maxio.zendesk.com/hc/en-us/articles/24261141522189-Components-Overview).
If you have the new [Catalog experience](https://developers.maxio.com/http/help/announcements/2026-announcements#new-catalog-experience-and-terminology) enabled, taxable components must include a non-blank `tax_code`. Sending `"tax_code": ""` returns `422`.
```http
POST /product_families/{product_family_id}/quantity_based_components.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `product_family_id` | `String` | Template, Required | Either the product family's id or its handle prefixed with `handle:` |
| `body` | [`Create Quantity Based Component`](https://developers.maxio.com/http/advanced-billing-api/models/structures/create-quantity-based-component) | Body, Optional | - |
# Response Type
**201**: Created
[`Component Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/component-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/product_families/product_family_id4/quantity_based_components.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"quantity_based_component": {
"name": "Quantity Based Component",
"unit_name": "Component",
"description": "Example of JSON per-unit component example",
"pricing_scheme": "per_unit",
"unit_price": "10",
"taxable": true,
"display_on_hosted_page": true,
"allow_fractional_quantities": true,
"public_signup_page_ids": [
323397
]
}
}'
```
# Example Response *(as JSON)*
```json
{
"component": {
"id": 292609,
"name": "Text messages",
"handle": "text-messages",
"pricing_scheme": "per_unit",
"unit_name": "unit",
"unit_price": "10.0",
"product_family_id": 528484,
"product_family_name": "Cloud Compute Servers",
"price_per_unit_in_cents": null,
"kind": "quantity_based_component",
"archived": false,
"taxable": false,
"description": null,
"default_price_point_id": 2944263,
"prices": [
{
"id": 55423,
"component_id": 30002,
"starting_quantity": 1,
"ending_quantity": null,
"unit_price": "10.0",
"price_point_id": 2944263,
"formatted_unit_price": "$10.00",
"segment_id": null
}
],
"price_point_count": 1,
"price_points_url": "https://demo-3238403362.chargify.com/components/30002/price_points",
"default_price_point_name": "Original",
"tax_code": null,
"recurring": false,
"upgrade_charge": null,
"downgrade_credit": null,
"created_at": "2024-01-23T06:08:05-05:00",
"updated_at": "2024-01-23T06:08:05-05:00",
"archived_at": null,
"hide_date_range_on_invoice": false,
"allow_fractional_quantities": false,
"use_site_exchange_rate": true,
"item_category": null,
"accounting_code": null
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Create On Off Component
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/components/create-on-off-component
Creates an On/Off component definition under the specified product family. An On/Off component can then be added and “allocated” for a subscription.
On/off components are used for any flat fee, recurring add on (think $99/month for tech support or a flat add on shipping fee).
For more information on components, see our documentation [here](https://maxio.zendesk.com/hc/en-us/articles/24261141522189-Components-Overview).
If you have the new [Catalog experience](https://developers.maxio.com/http/help/announcements/2026-announcements#new-catalog-experience-and-terminology) enabled, taxable components must include a non-blank `tax_code`. Sending `"tax_code": ""` returns `422`.
```http
POST /product_families/{product_family_id}/on_off_components.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `product_family_id` | `String` | Template, Required | Either the product family's id or its handle prefixed with `handle:` |
| `body` | [`Create on Off Component`](https://developers.maxio.com/http/advanced-billing-api/models/structures/create-on-off-component) | Body, Optional | - |
# Response Type
**201**: Created
[`Component Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/component-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/product_families/product_family_id4/on_off_components.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"on_off_component": {
"name": "Annual Support Services",
"description": "Prepay for support services",
"taxable": true,
"unit_price": "100.00",
"display_on_hosted_page": true,
"public_signup_page_ids": [
320495
]
}
}'
```
# Example Response *(as JSON)*
```json
{
"component": {
"id": 292609,
"name": "Test On-Off Component 46124",
"handle": "test-on-off-component-4612422802",
"pricing_scheme": null,
"unit_name": "on/off",
"unit_price": "10.0",
"product_family_id": 528484,
"product_family_name": "Cloud Compute Servers",
"price_per_unit_in_cents": null,
"kind": "on_off_component",
"archived": false,
"taxable": false,
"description": null,
"default_price_point_id": 2944263,
"price_point_count": 1,
"price_points_url": "https://demo-3238403362.chargify.com/components/30002/price_points",
"default_price_point_name": "Original",
"tax_code": null,
"recurring": true,
"upgrade_charge": null,
"downgrade_credit": null,
"created_at": "2024-01-23T06:08:05-05:00",
"updated_at": "2024-01-23T06:08:05-05:00",
"archived_at": null,
"hide_date_range_on_invoice": false,
"allow_fractional_quantities": false,
"use_site_exchange_rate": true,
"item_category": null,
"accounting_code": null
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Create Prepaid Usage Component
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/components/create-prepaid-usage-component
Creates a prepaid usage component definition under the specified product family. A prepaid component can then be added and “allocated” for a subscription.
Prepaid components allow customers to pre-purchase units that can be used up over time on their subscription. In a sense, they are the mirror image of metered components; while metered components charge at the end of the period for the amount of units used, prepaid components are charged for at the time of purchase, and usage is subsequently tracked against the amount purchased.
For more information, see [Components Overview](https://maxio.zendesk.com/hc/en-us/articles/24261141522189-Components-Overview).
If you have the new [Catalog experience](https://developers.maxio.com/http/help/announcements/2026-announcements#new-catalog-experience-and-terminology) enabled, taxable components must include a non-blank `tax_code`; sending a blank value results in a validation error.
```http
POST /product_families/{product_family_id}/prepaid_usage_components.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `product_family_id` | `String` | Template, Required | Either the product family's id or its handle prefixed with `handle:` |
| `body` | [`Create Prepaid Component`](https://developers.maxio.com/http/advanced-billing-api/models/structures/create-prepaid-component) | Body, Optional | - |
# Response Type
**201**: Created
[`Component Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/component-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/product_families/product_family_id4/prepaid_usage_components.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"prepaid_usage_component": {
"name": "Minutes",
"unit_name": "minutes",
"unit_price": 2.0,
"pricing_scheme": "per_unit",
"rollover_prepaid_remainder": true,
"renew_prepaid_allocation": true,
"expiration_interval": 15.0,
"expiration_interval_unit": "day",
"overage_pricing": {
"pricing_scheme": "stairstep",
"prices": [
{
"starting_quantity": 1,
"ending_quantity": 100,
"unit_price": 3.0
},
{
"starting_quantity": 101,
"unit_price": 5.0
}
]
}
}
}'
```
# Example Response *(as JSON)*
```json
{
"component": {
"id": 292609,
"name": "Test Prepaid Component 98505",
"handle": "test-prepaid-component-9850584842",
"pricing_scheme": "per_unit",
"unit_name": "unit",
"unit_price": "10.0",
"product_family_id": 528484,
"product_family_name": "Test Product Family 27791",
"price_per_unit_in_cents": null,
"kind": "prepaid_usage_component",
"archived": false,
"taxable": false,
"description": "Description for: Test Prepaid Component 98505",
"default_price_point_id": 2944263,
"overage_prices": [
{
"id": 55964,
"component_id": 30427,
"starting_quantity": 1,
"ending_quantity": null,
"unit_price": "1.0",
"price_point_id": 2944756,
"formatted_unit_price": "$1.00",
"segment_id": null
}
],
"prices": [
{
"id": 55963,
"component_id": 30427,
"starting_quantity": 1,
"ending_quantity": null,
"unit_price": "1.0",
"price_point_id": 2944756,
"formatted_unit_price": "$1.00",
"segment_id": null
}
],
"price_point_count": 1,
"price_points_url": "https://demo-3238403362.chargify.com/components/30002/price_points",
"default_price_point_name": "Original",
"tax_code": null,
"recurring": true,
"upgrade_charge": null,
"downgrade_credit": null,
"created_at": "2024-01-23T06:08:05-05:00",
"updated_at": "2024-01-23T06:08:05-05:00",
"archived_at": null,
"hide_date_range_on_invoice": false,
"allow_fractional_quantities": false,
"use_site_exchange_rate": true,
"item_category": null,
"accounting_code": null
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Create Event Based Component
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/components/create-event-based-component
Creates an event-based component definition under the specified product family. An event-based component can then be added and “allocated” for a subscription.
Event-based components are similar to other component types, in that you define the component parameters (such as name and taxability) and the pricing. A key difference for the event-based component is that it must be attached to a metric. This is because the metric provides the component with the actual quantity used in computing what and how much will be billed each period for each subscription.
So, instead of reporting usage directly for each component (as you would with metered components), the usage is derived from analysis of your events.
For more information, see [Components Overview](https://maxio.zendesk.com/hc/en-us/articles/24261141522189-Components-Overview).
If you have the new [Catalog experience](https://developers.maxio.com/http/help/announcements/2026-announcements#new-catalog-experience-and-terminology) enabled, taxable components must include a non-blank `tax_code`; sending a blank value results in a validation error.
```http
POST /product_families/{product_family_id}/event_based_components.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `product_family_id` | `String` | Template, Required | Either the product family's id or its handle prefixed with `handle:` |
| `body` | [`Create EBB Component`](https://developers.maxio.com/http/advanced-billing-api/models/structures/create-ebb-component) | Body, Optional | - |
# Response Type
**201**: Created
[`Component Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/component-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/product_families/product_family_id4/event_based_components.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"event_based_component": {
"name": "Component Name",
"unit_name": "string",
"description": "string",
"handle": "some_handle",
"taxable": true,
"pricing_scheme": "per_unit",
"prices": [
{
"starting_quantity": 1,
"unit_price": "0.49"
}
],
"event_based_billing_metric_id": 123
}
}'
```
# Example Response *(as JSON)*
```json
{
"component": {
"id": 1489581,
"name": "stripeCharges",
"handle": null,
"pricing_scheme": null,
"unit_name": "charge",
"unit_price": null,
"product_family_id": 1517093,
"product_family_name": "Billing Plans",
"price_per_unit_in_cents": null,
"kind": "event_based_component",
"archived": false,
"taxable": false,
"description": null,
"default_price_point_id": null,
"price_point_count": 0,
"price_points_url": "https://staging.chargify.com/components/1489581/price_points",
"default_price_point_name": "Original",
"tax_code": null,
"recurring": false,
"upgrade_charge": null,
"downgrade_credit": null,
"created_at": "2021-10-12T07:33:24-05:00",
"updated_at": "2021-10-12T07:33:24-05:00",
"archived_at": null,
"hide_date_range_on_invoice": false,
"allow_fractional_quantities": false,
"use_site_exchange_rate": null,
"item_category": null,
"accounting_code": null,
"event_based_billing_metric_id": 1163
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Find Component
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/components/find-component
Returns information for a component matching the provided handle. You can identify your components with a handle so you don't have to save or reference the IDs we generate.
```http
GET /components/lookup.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `handle` | `String` | Query, Required | The handle of the component to find |
# Response Type
**200**: OK
[`Component Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/component-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/components/lookup.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'handle=handle6'
```
# Example Response *(as JSON)*
```json
{
"component": {
"id": 399853,
"name": "Annual Support Services",
"pricing_scheme": null,
"unit_name": "on/off",
"unit_price": "100.0",
"product_family_id": 997233,
"price_per_unit_in_cents": null,
"kind": "on_off_component",
"archived": false,
"taxable": true,
"description": "Prepay for support services",
"default_price_point_id": 121003,
"price_point_count": 4,
"price_points_url": "https://general-goods.chargify.com/components/399853/price_points",
"tax_code": "D0000000",
"recurring": true,
"upgrade_charge": null,
"downgrade_credit": null,
"created_at": "2019-08-02T05:54:53-04:00",
"default_price_point_name": "Original",
"product_family_name": "Chargify"
}
}
```
##### Read Component
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/components/read-component
Returns information regarding a component from a specific product family.
You can read the component by either the component's id or handle. When using the handle, it must be prefixed with `handle:`.
```http
GET /product_families/{product_family_id}/components/{component_id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `product_family_id` | `Number` | Template, Required | The Advanced Billing id of the product family to which the component belongs |
| `component_id` | `String` | Template, Required | Either the Advanced Billing id of the component or the handle for the component prefixed with `handle:`
**Constraints**: *Pattern*: `/\A(?:\d+\|handle:(?:uuid:\|[a-z])(?:\w\|-)+)\z/` |
| `include_features` | `Boolean` | Query, Optional | When `true`, embeds the active feature catalog items for each result in a `features` array. Default value is `false`.
**Default**: `false` |
# Response Type
**200**: OK
[`Component Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/component-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/product_families/140/components/component_id8.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'include_features=false'
```
# Example Response *(as JSON)*
```json
{
"component": {
"id": 399853,
"name": "Annual Support Services",
"pricing_scheme": null,
"unit_name": "on/off",
"unit_price": "100.0",
"product_family_id": 997233,
"price_per_unit_in_cents": null,
"kind": "on_off_component",
"archived": false,
"taxable": true,
"description": "Prepay for support services",
"default_price_point_id": 121003,
"price_point_count": 4,
"price_points_url": "https://general-goods.chargify.com/components/399853/price_points",
"tax_code": "D0000000",
"recurring": true,
"upgrade_charge": null,
"downgrade_credit": null,
"created_at": "2019-08-02T05:54:53-04:00",
"default_price_point_name": "Original",
"product_family_name": "Chargify",
"product_family_handle": "chargify"
}
}
```
##### Update Product Family Component
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/components/update-product-family-component
Updates a component from a specific product family.
You may read the component by either the component's id or handle. When using the handle, it must be prefixed with `handle:`.
If you have the new [Catalog experience](https://developers.maxio.com/http/help/announcements/2026-announcements#new-catalog-experience-and-terminology) enabled, taxable components must include a non-blank `tax_code`. Sending `"tax_code": ""` returns `422`.
```http
PUT /product_families/{product_family_id}/components/{component_id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `product_family_id` | `Number` | Template, Required | The Advanced Billing id of the product family to which the component belongs |
| `component_id` | `String` | Template, Required | Either the Advanced Billing id of the component or the handle for the component prefixed with `handle:`
**Constraints**: *Pattern*: `/\A(?:\d+\|handle:(?:uuid:\|[a-z])(?:\w\|-)+)\z/` |
| `body` | [`Update Component Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/update-component-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Component Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/component-response)
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/product_families/140/components/component_id8.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"component": {
"item_category": "Business Software"
}
}'
```
# Example Response *(as JSON)*
```json
{
"component": {
"id": 399853,
"name": "Annual Support Services",
"pricing_scheme": null,
"unit_name": "on/off",
"unit_price": "100.0",
"product_family_id": 997233,
"price_per_unit_in_cents": null,
"kind": "on_off_component",
"archived": false,
"taxable": true,
"description": "Prepay for support services",
"default_price_point_id": 121003,
"price_point_count": 4,
"price_points_url": "https://general-goods.chargify.com/components/399853/price_points",
"tax_code": "D0000000",
"recurring": true,
"upgrade_charge": null,
"downgrade_credit": null,
"created_at": "2019-08-02T05:54:53-04:00",
"default_price_point_name": "Original",
"product_family_name": "Chargify"
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Archive Component
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/components/archive-component
Archives the component; all current subscribers will continue to be charged as usual.
```http
DELETE /product_families/{product_family_id}/components/{component_id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `product_family_id` | `Number` | Template, Required | The Advanced Billing id of the product family to which the component belongs |
| `component_id` | `String` | Template, Required | Either the Advanced Billing id of the component or the handle for the component prefixed with `handle:`
**Constraints**: *Pattern*: `/\A(?:\d+\|handle:(?:uuid:\|[a-z])(?:\w\|-)+)\z/` |
# Response Type
**200**: OK
[`Component`](https://developers.maxio.com/http/advanced-billing-api/models/structures/component)
# Example Usage
```bash
curl -X DELETE \
--url 'https://subdomain.chargify.com/product_families/140/components/component_id8.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"id": 25407138,
"name": "cillum aute",
"pricing_scheme": "stairstep",
"unit_name": "nulla in",
"unit_price": "Excepteur veniam",
"product_family_id": -56705047,
"kind": "prepaid_usage_component",
"archived": true,
"taxable": false,
"description": "reprehenderit laborum qui fugiat",
"default_price_point_id": -64328176,
"price_point_count": 15252407,
"price_points_url": "dolor mollit consequat",
"tax_code": "ea nisi",
"recurring": false,
"created_at": "2016-11-08T16:22:26-05:00",
"default_price_point_name": "cupidatat Lorem non aliqua",
"product_family_name": "do elit",
"hide_date_range_on_invoice": false
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### List Components
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/components/list-components
Lists components for a site.
```http
GET /components.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `date_field` | [`Basic Date Field`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/basic-date-field) | Query, Optional | The type of filter you would like to apply to your search. |
| `start_date` | `String` | Query, Optional | The start date (format YYYY-MM-DD) with which to filter the date_field. Returns components with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified. |
| `end_date` | `String` | Query, Optional | The end date (format YYYY-MM-DD) with which to filter the date_field. Returns components with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified. |
| `start_datetime` | `String` | Query, Optional | The start date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns components with a timestamp at or after exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of start_date. |
| `end_datetime` | `String` | Query, Optional | The end date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns components with a timestamp at or before exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of end_date. |
| `include_archived` | `Boolean` | Query, Optional | Include archived items. |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query `per_page=200`.
**Default**: `20`
**Constraints**: `<= 200` |
| `filter` | [`List Components Filter`](https://developers.maxio.com/http/advanced-billing-api/models/structures/list-components-filter) | Query, Optional | Filter to use for List Components operations |
# Response Type
**200**: OK
[`array`](https://developers.maxio.com/http/advanced-billing-api/models/structures/component-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/components.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'date_field=updated_at' \
-d 'page=1' \
-d 'per_page=50' \
-d 'filter[ids]=1%2C2%2C3'
```
# Example Response *(as JSON)*
```json
[
{
"component": {
"id": 399850,
"name": "$1.00 component",
"pricing_scheme": "per_unit",
"unit_name": "Component",
"unit_price": "1.0",
"product_family_id": 997233,
"price_per_unit_in_cents": null,
"kind": "quantity_based_component",
"archived": false,
"taxable": false,
"description": "Component",
"default_price_point_id": 121000,
"prices": [
{
"id": 630687,
"component_id": 399850,
"starting_quantity": 1,
"ending_quantity": null,
"unit_price": "1.0",
"price_point_id": 121000,
"formatted_unit_price": "$1.00"
}
],
"price_point_count": 2,
"price_points_url": "https://general-goods.chargify.com/components/399850/price_points",
"tax_code": null,
"recurring": true,
"upgrade_charge": null,
"downgrade_credit": null,
"created_at": "2019-08-01T09:35:38-04:00",
"default_price_point_name": "Original",
"product_family_name": "Chargify",
"product_family_handle": "chargify",
"use_site_exchange_rate": true
}
},
{
"component": {
"id": 399853,
"name": "Annual Support Services",
"pricing_scheme": null,
"unit_name": "on/off",
"unit_price": "100.0",
"product_family_id": 997233,
"price_per_unit_in_cents": null,
"kind": "on_off_component",
"archived": false,
"taxable": true,
"description": "Prepay for support services",
"default_price_point_id": 121003,
"price_point_count": 4,
"price_points_url": "https://general-goods.chargify.com/components/399853/price_points",
"tax_code": "D0000000",
"recurring": true,
"upgrade_charge": null,
"downgrade_credit": null,
"created_at": "2019-08-01T09:35:37-04:00",
"default_price_point_name": "Original",
"product_family_name": "Chargify",
"product_family_handle": "chargify",
"use_site_exchange_rate": true
}
},
{
"component": {
"id": 386937,
"name": "Cancellation fee",
"pricing_scheme": null,
"unit_name": "on/off",
"unit_price": "35.0",
"product_family_id": 997233,
"price_per_unit_in_cents": null,
"kind": "on_off_component",
"archived": false,
"taxable": false,
"description": "",
"default_price_point_id": 108307,
"price_point_count": 1,
"price_points_url": "https://general-goods.chargify.com/components/386937/price_points",
"tax_code": null,
"recurring": true,
"upgrade_charge": null,
"downgrade_credit": null,
"created_at": "2019-08-01T09:35:38-04:00",
"default_price_point_name": "Original",
"product_family_name": "Chargify",
"product_family_handle": "chargify",
"use_site_exchange_rate": true
}
}
]
```
##### Update Component
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/components/update-component
Updates a component.
You may read the component by either the component's id or handle. When using the handle, it must be prefixed with `handle:`.
If you have the new [Catalog experience](https://developers.maxio.com/http/help/announcements/2026-announcements#new-catalog-experience-and-terminology) enabled, taxable components must include a non-blank `tax_code`. Sending `"tax_code": ""` returns `422`.
```http
PUT /components/{component_id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `component_id` | `String` | Template, Required | The id or handle of the component |
| `body` | [`Update Component Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/update-component-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Component Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/component-response)
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/components/component_id8.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"component": {
"item_category": "Business Software"
}
}'
```
# Example Response *(as JSON)*
```json
{
"component": {
"id": 399853,
"name": "Annual Support Services",
"pricing_scheme": null,
"unit_name": "on/off",
"unit_price": "100.0",
"product_family_id": 997233,
"price_per_unit_in_cents": null,
"kind": "on_off_component",
"archived": false,
"taxable": true,
"description": "Prepay for support services",
"default_price_point_id": 121003,
"price_point_count": 4,
"price_points_url": "https://general-goods.chargify.com/components/399853/price_points",
"tax_code": "D0000000",
"recurring": true,
"upgrade_charge": null,
"downgrade_credit": null,
"created_at": "2019-08-02T05:54:53-04:00",
"default_price_point_name": "Original",
"product_family_name": "Chargify"
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### List Components for Product Family
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/components/list-components-for-product-family
Lists components for a particular product family.
```http
GET /product_families/{product_family_id}/components.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `product_family_id` | `Number` | Template, Required | The Advanced Billing id of the product family |
| `include_archived` | `Boolean` | Query, Optional | Include archived items. |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query `per_page=200`.
**Default**: `20`
**Constraints**: `<= 200` |
| `filter` | [`List Components Filter`](https://developers.maxio.com/http/advanced-billing-api/models/structures/list-components-filter) | Query, Optional | Filter to use for List Components operations |
| `date_field` | [`Basic Date Field`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/basic-date-field) | Query, Optional | The type of filter you would like to apply to your search. Use in query `date_field=created_at`. |
| `end_date` | `String` | Query, Optional | The end date (format YYYY-MM-DD) with which to filter the date_field. Returns components with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified. |
| `end_datetime` | `String` | Query, Optional | The end date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns components with a timestamp at or before exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of end_date. |
| `start_date` | `String` | Query, Optional | The start date (format YYYY-MM-DD) with which to filter the date_field. Returns components with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified. |
| `start_datetime` | `String` | Query, Optional | The start date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns components with a timestamp at or after exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of start_date. |
# Response Type
**200**: OK
[`array`](https://developers.maxio.com/http/advanced-billing-api/models/structures/component-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/product_families/140/components.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'page=1' \
-d 'per_page=50' \
-d 'filter[ids]=1%2C2%2C3' \
-d 'date_field=updated_at'
```
# Example Response *(as JSON)*
```json
[
{
"component": {
"id": 399850,
"name": "$1.00 component",
"pricing_scheme": "per_unit",
"unit_name": "Component",
"unit_price": "1.0",
"product_family_id": 997233,
"price_per_unit_in_cents": null,
"kind": "quantity_based_component",
"archived": false,
"taxable": false,
"description": "Component",
"default_price_point_id": 121000,
"prices": [
{
"id": 630687,
"component_id": 399850,
"starting_quantity": 1,
"ending_quantity": null,
"unit_price": "1.0",
"price_point_id": 121000,
"formatted_unit_price": "$1.00"
}
],
"price_point_count": 2,
"price_points_url": "https://general-goods.chargify.com/components/399850/price_points",
"tax_code": null,
"recurring": true,
"upgrade_charge": null,
"downgrade_credit": null,
"created_at": "2019-08-01T09:35:38-04:00",
"default_price_point_name": "Original",
"product_family_name": "Chargify",
"use_site_exchange_rate": true
}
},
{
"component": {
"id": 399853,
"name": "Annual Support Services",
"pricing_scheme": null,
"unit_name": "on/off",
"unit_price": "100.0",
"product_family_id": 997233,
"price_per_unit_in_cents": null,
"kind": "on_off_component",
"archived": false,
"taxable": true,
"description": "Prepay for support services",
"default_price_point_id": 121003,
"price_point_count": 4,
"price_points_url": "https://general-goods.chargify.com/components/399853/price_points",
"tax_code": "D0000000",
"recurring": true,
"upgrade_charge": null,
"downgrade_credit": null,
"created_at": "2019-08-01T09:35:37-04:00",
"default_price_point_name": "Original",
"product_family_name": "Chargify",
"use_site_exchange_rate": true
}
},
{
"component": {
"id": 386937,
"name": "Cancellation fee",
"pricing_scheme": null,
"unit_name": "on/off",
"unit_price": "35.0",
"product_family_id": 997233,
"price_per_unit_in_cents": null,
"kind": "on_off_component",
"archived": false,
"taxable": false,
"description": "",
"default_price_point_id": 108307,
"price_point_count": 1,
"price_points_url": "https://general-goods.chargify.com/components/386937/price_points",
"tax_code": null,
"recurring": true,
"upgrade_charge": null,
"downgrade_credit": null,
"created_at": "2019-08-01T09:35:38-04:00",
"default_price_point_name": "Original",
"product_family_name": "Chargify",
"use_site_exchange_rate": true
}
}
]
```
#### Component Price Points
##### Promote Component Price Point to Default
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/component-price-points/promote-component-price-point-to-default
Sets a new default price point for the component. This new default will apply to all new subscriptions going forward - existing subscriptions will remain on their current price point.
See [Price Points Documentation](https://maxio.zendesk.com/hc/en-us/articles/24261191737101-Price-Points-Components) for more information on price points and moving subscriptions between price points.
Note: Custom price points are not able to be set as the default for a component.
```http
PUT /components/{component_id}/price_points/{price_point_id}/default.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `component_id` | `Number` | Template, Required | The Advanced Billing id of the component to which the price point belongs |
| `price_point_id` | `Number` | Template, Required | The Advanced Billing id of the price point |
# Response Type
**200**: OK
[`Component Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/component-response)
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/components/222/price_points/10/default.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"component": {
"id": 292609,
"name": "Text messages",
"pricing_scheme": "stairstep",
"unit_name": "text message",
"unit_price": null,
"product_family_id": 528484,
"price_per_unit_in_cents": null,
"kind": "metered_component",
"archived": false,
"taxable": false,
"description": null,
"created_at": "2019-08-02T05:54:53-04:00",
"prices": [
{
"id": 47,
"component_id": 292609,
"starting_quantity": 1,
"ending_quantity": null,
"unit_price": "1.0",
"price_point_id": 173,
"formatted_unit_price": "$1.00"
}
],
"default_price_point_name": "Original"
}
}
```
##### Create Component Price Point
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/component-price-points/create-component-price-point
Creates a price point for an existing component.
```http
POST /components/{component_id}/price_points.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `component_id` | `Number` | Template, Required | The Advanced Billing id of the component |
| `body` | [`Create Component Price Point Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/create-component-price-point-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Component Price Point Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/component-price-point-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/components/222/price_points.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"price_point": {
"name": "Wholesale",
"handle": "wholesale-handle",
"pricing_scheme": "stairstep",
"use_site_exchange_rate": false,
"prices": [
{
"starting_quantity": "1",
"ending_quantity": "100",
"unit_price": "5.00"
},
{
"starting_quantity": "101",
"ending_quantity": "200",
"unit_price": "4.00"
}
]
}
}'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error Array Map ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-array-map-response) |
##### List Component Price Points
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/component-price-points/list-component-price-points
Lists the price points associated with a component.
You may specify the component by using either the numeric id or the `handle:gold` syntax.
If the price point is set to `use_site_exchange_rate: true`, it will return pricing based on the current exchange rate. If the flag is set to false, it will return all of the defined prices for each currency.
```http
GET /components/{component_id}/price_points.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `component_id` | `Number` | Template, Required | The Advanced Billing id of the component |
| `currency_prices` | `Boolean` | Query, Optional | Include an array of currency price data. |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query `per_page=200`.
**Default**: `20`
**Constraints**: `<= 200` |
| `filter[type]` | [`array`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/price-point-type) | Query, Optional | Use in query: `filter[type]=catalog,default`. |
# Response Type
**201**: Created
[`Component Price Points Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/component-price-points-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/components/222/price_points.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'page=1' \
-d 'per_page=50' \
-d 'filter[type]=Liquid error: Value cannot be null. (Parameter 'key')'
```
# Example Response *(as JSON)*
```json
{
"price_points": [
{
"id": 80,
"default": false,
"name": "Wholesale Two",
"pricing_scheme": "per_unit",
"component_id": 74,
"handle": "wholesale-two",
"archived_at": null,
"created_at": "2017-07-05T13:55:40-04:00",
"updated_at": "2017-07-05T13:55:40-04:00",
"prices": [
{
"id": 121,
"component_id": 74,
"starting_quantity": 1,
"ending_quantity": null,
"unit_price": "5.0"
}
]
},
{
"id": 81,
"default": false,
"name": "MSRP",
"pricing_scheme": "per_unit",
"component_id": 74,
"handle": "msrp",
"archived_at": null,
"created_at": "2017-07-05T13:55:40-04:00",
"updated_at": "2017-07-05T13:55:40-04:00",
"prices": [
{
"id": 122,
"component_id": 74,
"starting_quantity": 1,
"ending_quantity": null,
"unit_price": "4.0"
}
]
}
]
}
```
##### Bulk Create Component Price Points
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/component-price-points/bulk-create-component-price-points
Creates multiple component price points in one request.
```http
POST /components/{component_id}/price_points/bulk.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `component_id` | `String` | Template, Required | The Advanced Billing id of the component for which you want to fetch price points. |
| `body` | [`Create Component Price Points Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/create-component-price-points-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Component Price Points Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/component-price-points-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/components/component_id8/price_points/bulk.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"price_points": [
{
"name": "Wholesale",
"handle": "wholesale",
"pricing_scheme": "per_unit",
"prices": [
{
"starting_quantity": 1,
"unit_price": 5.0
}
]
},
{
"name": "MSRP",
"handle": "msrp",
"pricing_scheme": "per_unit",
"prices": [
{
"starting_quantity": 1,
"unit_price": 4.0
}
]
},
{
"name": "Special Pricing",
"handle": "special",
"pricing_scheme": "per_unit",
"prices": [
{
"starting_quantity": 1,
"unit_price": 5.0
}
]
}
]
}'
```
# Example Response *(as JSON)*
```json
{
"price_points": [
{
"id": 80,
"default": false,
"name": "Wholesale Two",
"pricing_scheme": "per_unit",
"component_id": 74,
"handle": "wholesale-two",
"archived_at": null,
"created_at": "2017-07-05T13:55:40-04:00",
"updated_at": "2017-07-05T13:55:40-04:00",
"prices": [
{
"id": 121,
"component_id": 74,
"starting_quantity": 1,
"ending_quantity": null,
"unit_price": "5.0"
}
]
},
{
"id": 81,
"default": false,
"name": "MSRP",
"pricing_scheme": "per_unit",
"component_id": 74,
"handle": "msrp",
"archived_at": null,
"created_at": "2017-07-05T13:55:40-04:00",
"updated_at": "2017-07-05T13:55:40-04:00",
"prices": [
{
"id": 122,
"component_id": 74,
"starting_quantity": 1,
"ending_quantity": null,
"unit_price": "4.0"
}
]
}
]
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Clone Component Price Point
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/component-price-points/clone-component-price-point
Clones a component price point. Custom price points (tied to a specific subscription) cannot be cloned. The following attributes are copied from the source price point:
- Pricing scheme
- All price tiers (with starting/ending quantities and unit prices)
- Tax included setting
- Currency prices (if definitive pricing is set)
- Overage pricing (for prepaid usage components)
- Interval settings (if multi-frequency is enabled)
- Event-based billing segments (if applicable)
```http
POST /components/{component_id}/price_points/{price_point_id}/clone.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `component_id` | [`Number \| String`](https://developers.maxio.com/http/advanced-billing-api/models/oneof-anyof-definitions/clone-component-price-point-component-id) | Template, Required | The id or handle of the component. When using the handle, it must be prefixed with `handle:`. Example: `123` for an integer ID, or `handle:example-product-handle` for a string handle. |
| `price_point_id` | [`Number \| String`](https://developers.maxio.com/http/advanced-billing-api/models/oneof-anyof-definitions/clone-component-price-point-price-point-id) | Template, Required | The id or handle of the price point. When using the handle, it must be prefixed with `handle:`. Example: `123` for an integer ID, or `handle:example-price_point-handle` for a string handle. |
| `body` | [`Clone Component Price Point Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/clone-component-price-point-request) | Body, Optional | - |
# Response Type
**201**: Created
[`Component Price Point Currency Overage Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/component-price-point-currency-overage-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/components/144/price_points/188/clone.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"price_point": {
"name": "Pro Usage Tiered Clone"
}
}'
```
# Example Response *(as JSON)*
```json
{
"price_point": {
"id": 9012,
"name": "Pro Usage Tiered Clone",
"type": "catalog",
"pricing_scheme": "tiered",
"component_id": 1234,
"handle": "pro-usage-tiered-clone",
"archived_at": null,
"created_at": "2024-05-01T12:34:56-04:00",
"updated_at": "2024-05-01T12:34:56-04:00",
"use_site_exchange_rate": false,
"currency_prices": [
{
"id": 3001,
"currency": "EUR",
"price": "9.99",
"formatted_price": "€9.99",
"price_id": 4001,
"price_point_id": 9012
}
],
"currency_overage_prices": [
{
"id": 3002,
"currency": "EUR",
"price": "2.50",
"formatted_price": "€2.50",
"price_id": 4002,
"price_point_id": 9012
}
],
"renew_prepaid_allocation": true,
"rollover_prepaid_remainder": false,
"expiration_interval": 1,
"expiration_interval_unit": "month",
"overage_pricing_scheme": "tiered",
"subscription_id": 4321,
"prices": [
{
"id": 4001,
"component_id": 1234,
"starting_quantity": 1,
"ending_quantity": 100,
"unit_price": "9.99",
"price_point_id": 9012,
"formatted_unit_price": "$9.99",
"segment_id": null
}
],
"overage_prices": [
{
"id": 4002,
"component_id": 1234,
"starting_quantity": 101,
"ending_quantity": null,
"unit_price": "2.50",
"price_point_id": 9012,
"formatted_unit_price": "$2.50",
"segment_id": null
}
],
"tax_included": false,
"interval": 1,
"interval_unit": "month"
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Update Component Price Point
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/component-price-points/update-component-price-point
Updates a component price point and its associated prices.
Passing in a price bracket without an `id` will attempt to create a new price.
Including an `id` will update the corresponding price, and including the `_destroy` flag set to true along with the `id` will remove that price.
Note: Custom price points cannot be updated directly. They must be edited through the Subscription.
```http
PUT /components/{component_id}/price_points/{price_point_id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `component_id` | [`Number \| String`](https://developers.maxio.com/http/advanced-billing-api/models/oneof-anyof-definitions/update-component-price-point-component-id) | Template, Required | The id or handle of the component. When using the handle, it must be prefixed with `handle:`. Example: `123` for an integer ID, or `handle:example-product-handle` for a string handle. |
| `price_point_id` | [`Number \| String`](https://developers.maxio.com/http/advanced-billing-api/models/oneof-anyof-definitions/update-component-price-point-price-point-id) | Template, Required | The id or handle of the price point. When using the handle, it must be prefixed with `handle:`. Example: `123` for an integer ID, or `handle:example-price_point-handle` for a string handle. |
| `body` | [`Update Component Price Point Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/update-component-price-point-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Component Price Point Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/component-price-point-response)
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/components/144/price_points/188.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"price_point": {
"name": "Default",
"prices": [
{
"id": 1,
"ending_quantity": 100,
"unit_price": 5.0
},
{
"id": 2,
"_destroy": true
},
{
"starting_quantity": 101,
"unit_price": 4.0
}
]
}
}'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error Array Map ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-array-map-response) |
##### Read Component Price Point
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/component-price-points/read-component-price-point
Returns details for a specific component price point. You can achieve this by using either the component price point ID or handle.
```http
GET /components/{component_id}/price_points/{price_point_id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `component_id` | [`Number \| String`](https://developers.maxio.com/http/advanced-billing-api/models/oneof-anyof-definitions/read-component-price-point-component-id) | Template, Required | The id or handle of the component. When using the handle, it must be prefixed with `handle:`. Example: `123` for an integer ID, or `handle:example-product-handle` for a string handle. |
| `price_point_id` | [`Number \| String`](https://developers.maxio.com/http/advanced-billing-api/models/oneof-anyof-definitions/read-component-price-point-price-point-id) | Template, Required | The id or handle of the price point. When using the handle, it must be prefixed with `handle:`. Example: `123` for an integer ID, or `handle:example-price_point-handle` for a string handle. |
| `currency_prices` | `Boolean` | Query, Optional | Include an array of currency price data. |
# Response Type
**200**: OK
[`Component Price Point Currency Overage Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/component-price-point-currency-overage-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/components/144/price_points/188.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
##### Archive Component Price Point
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/component-price-points/archive-component-price-point
Archives a component price point. Subscriptions using a price point that has been archived will continue using it until they're moved to another price point.
```http
DELETE /components/{component_id}/price_points/{price_point_id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `component_id` | [`Number \| String`](https://developers.maxio.com/http/advanced-billing-api/models/oneof-anyof-definitions/archive-component-price-point-component-id) | Template, Required | The id or handle of the component. When using the handle, it must be prefixed with `handle:`. Example: `123` for an integer ID, or `handle:example-product-handle` for a string handle. |
| `price_point_id` | [`Number \| String`](https://developers.maxio.com/http/advanced-billing-api/models/oneof-anyof-definitions/archive-component-price-point-price-point-id) | Template, Required | The id or handle of the price point. When using the handle, it must be prefixed with `handle:`. Example: `123` for an integer ID, or `handle:example-price_point-handle` for a string handle. |
# Response Type
**200**: OK
[`Component Price Point Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/component-price-point-response)
# Example Usage
```bash
curl -X DELETE \
--url 'https://subdomain.chargify.com/components/144/price_points/188.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"price_point": {
"id": 79,
"default": false,
"name": "Wholesale",
"pricing_scheme": "stairstep",
"component_id": 74,
"handle": "wholesale-handle",
"archived_at": "2017-07-06T15:04:00-04:00",
"created_at": "2017-07-05T13:44:30-04:00",
"updated_at": "2017-07-05T13:44:30-04:00",
"prices": [
{
"id": 119,
"component_id": 74,
"starting_quantity": 1,
"ending_quantity": 100,
"unit_price": "5.0"
},
{
"id": 120,
"component_id": 74,
"starting_quantity": 101,
"ending_quantity": null,
"unit_price": "4.0"
}
]
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Unarchive Component Price Point
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/component-price-points/unarchive-component-price-point
Unarchives a component price point.
```http
PUT /components/{component_id}/price_points/{price_point_id}/unarchive.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `component_id` | `Number` | Template, Required | The Advanced Billing id of the component to which the price point belongs |
| `price_point_id` | `Number` | Template, Required | The Advanced Billing id of the price point |
# Response Type
**200**: OK
[`Component Price Point Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/component-price-point-response)
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/components/222/price_points/10/unarchive.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"price_point": {
"id": 79,
"default": false,
"name": "Wholesale",
"pricing_scheme": "stairstep",
"component_id": 74,
"handle": "wholesale-handle",
"archived_at": null,
"created_at": "2017-07-05T13:44:30-04:00",
"updated_at": "2017-07-05T13:44:30-04:00",
"prices": [
{
"id": 119,
"component_id": 74,
"starting_quantity": 1,
"ending_quantity": 100,
"unit_price": "5.0"
},
{
"id": 120,
"component_id": 74,
"starting_quantity": 101,
"ending_quantity": null,
"unit_price": "4.0"
}
]
}
}
```
##### Create Currency Prices
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/component-price-points/create-currency-prices
Creates currency prices for a given currency defined at the site level.
When creating currency prices, they need to mirror the structure of your primary pricing. For each price level defined on the component price point, there should be a matching price level created in the given currency.
Note: Currency Prices are not able to be created for custom price points.
```http
POST /price_points/{price_point_id}/currency_prices.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `price_point_id` | `Number` | Template, Required | The Advanced Billing id of the price point |
| `body` | [`Create Currency Prices Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/create-currency-prices-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Component Currency Prices Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/component-currency-prices-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/price_points/10/currency_prices.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"currency_prices": [
{
"currency": "EUR",
"price": 50.0,
"price_id": 20
},
{
"currency": "EUR",
"price": 40.0,
"price_id": 21
}
]
}'
```
# Example Response *(as JSON)*
```json
{
"currency_prices": [
{
"id": 100,
"currency": "EUR",
"price": "123",
"formatted_price": "€123,00",
"price_id": 32669,
"price_point_id": 25554
}
]
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error Array Map ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-array-map-response) |
##### Update Currency Prices
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/component-price-points/update-currency-prices
Updates currency prices for a given currency defined at the site level.
Note: Currency Prices are not able to be updated for custom price points.
```http
PUT /price_points/{price_point_id}/currency_prices.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `price_point_id` | `Number` | Template, Required | The Advanced Billing id of the price point |
| `body` | [`Update Currency Prices Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/update-currency-prices-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Component Currency Prices Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/component-currency-prices-response)
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/price_points/10/currency_prices.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"currency_prices": [
{
"id": 100,
"price": 51.0
},
{
"id": 101,
"price": 41.0
}
]
}'
```
# Example Response *(as JSON)*
```json
{
"currency_prices": [
{
"id": 100,
"currency": "EUR",
"price": "123",
"formatted_price": "€123,00",
"price_id": 32669,
"price_point_id": 25554
}
]
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error Array Map ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-array-map-response) |
##### List All Component Price Points
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/component-price-points/list-all-component-price-points
Lists all component price points belonging to a site.
```http
GET /components_price_points.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `include` | [`List Components Price Points Include`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/list-components-price-points-include) | Query, Optional | Allows including additional data in the response. Use in query: `include=currency_prices`. |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query `per_page=200`.
**Default**: `20`
**Constraints**: `<= 200` |
| `direction` | [`Sorting Direction`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/sorting-direction) | Query, Optional | Controls the order in which results are returned. Use in query `direction=asc`. |
| `filter` | [`List Price Points Filter`](https://developers.maxio.com/http/advanced-billing-api/models/structures/list-price-points-filter) | Query, Optional | Filter to use for List PricePoints operations |
# Response Type
**200**: OK
[`List Components Price Points Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/list-components-price-points-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/components_price_points.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'include=currency_prices' \
-d 'page=1' \
-d 'per_page=50' \
-d 'filter[start_date]=2011-12-17' \
-d 'filter[end_date]=2011-12-15' \
-d 'filter[start_datetime]=2011-12-19T10%3A15%3A30%2B01%3A00' \
-d 'filter[end_datetime]=2019-06-07T17%3A20%3A06Z' \
-d 'filter[type]=catalog%2Cdefault%2Ccustom' \
-d 'filter[ids]=1%2C2%2C3'
```
# Example Response *(as JSON)*
```json
{
"price_points": [
{
"id": 1,
"name": "Auto-created",
"type": "default",
"pricing_scheme": "per_unit",
"component_id": 2,
"handle": "auto-created",
"archived_at": null,
"created_at": "2021-02-21T11:05:57-05:00",
"updated_at": "2021-02-21T11:05:57-05:00",
"prices": [
{
"id": 3,
"component_id": 2,
"starting_quantity": 0,
"ending_quantity": null,
"unit_price": "1.0",
"price_point_id": 1,
"formatted_unit_price": "$1.00",
"segment_id": null
}
],
"tax_included": false
}
]
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
#### Customers
##### Create Customer
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/customers/create-customer
Creates a new customer; can also be created alongside a new subscription. The only validation restriction is that you can only create one customer for a given reference value.
If provided, the `reference` value must be unique. It represents a unique identifier for the customer from your own app, i.e. the customer’s ID. This allows you to retrieve a given customer via a piece of shared information. Alternatively, you can choose to leave `reference` blank, and store the system-assigned unique ID for the customer, which is in the `id` attribute.
For more information, see [Customer Details](https://maxio.zendesk.com/hc/en-us/articles/24252190590093-Customer-Details).
## Required Country Format
Format the country attribute of the customer using the ISO Standard Country codes.
Countries should be formatted as two characters. For more information, see [ISO 3166-1](http://en.wikipedia.org/wiki/ISO_3166-1#Current_codes).
## Required State Format
Format the state attribute of the customer using the ISO Standard State codes.
+ US States (two characters): see [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2:US).
+ States Outside the US (two to three characters): To find the correct state codes outside the US, go to [ISO 3166-1](http://en.wikipedia.org/wiki/ISO_3166-1#Current_codes) and click on the link in the “ISO 3166-2 codes” column next to the country you wish to populate.
## Locale
You can attribute a language/region to the customer to deliver invoices in any required language. For more information, see [Customer Locale](https://maxio.zendesk.com/hc/en-us/articles/24286672013709-Customer-Locale).
```http
POST /customers.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `body` | [`Create Customer Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/create-customer-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Customer Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/customer-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/customers.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"customer": {
"first_name": "Martha",
"last_name": "Washington",
"email": "martha@example.com",
"cc_emails": "george@example.com",
"organization": "ABC, Inc.",
"reference": "1234567890",
"address": "123 Main Street",
"address_2": "Unit 10",
"city": "Anytown",
"state": "MA",
"zip": "02120",
"country": "US",
"phone": "555-555-1212",
"locale": "es-MX"
}
}'
```
# Example Response *(as JSON)*
```json
{
"customer": {
"first_name": "Cathryn",
"last_name": "Parisian",
"email": "Stella.McLaughlin6@example.net",
"cc_emails": null,
"organization": "Greenholt - Oberbrunner",
"reference": null,
"id": 76,
"created_at": "2021-03-29T07:47:00-04:00",
"updated_at": "2021-03-29T07:47:00-04:00",
"address": "739 Stephon Bypass",
"address_2": "Apt. 386",
"city": "Sedrickchester",
"state": "KY",
"state_name": "Kentucky",
"zip": "46979-7719",
"country": "US",
"country_name": "United States",
"phone": "230-934-3685",
"verified": false,
"portal_customer_created_at": null,
"portal_invite_last_sent_at": null,
"portal_invite_last_accepted_at": null,
"tax_exempt": false,
"surcharging": false,
"vat_number": null,
"parent_id": null,
"locale": "en-US"
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Customer Error ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/customer-error-response) |
##### List Customers
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/customers/list-customers
Lists all customers associated with your site, or filters results using the search parameter.
## Find Customer
Use the search feature with the `q` query parameter to retrieve an array of customers that matches the search query.
Common use cases are:
+ Search by an email
+ Search by an Advanced Billing ID
+ Search by an organization
+ Search by a reference value from your application
+ Search by a first or last name
To retrieve a single, exact match by reference, use the [lookup endpoint](https://developers.chargify.com/docs/api-docs/b710d8fbef104-read-customer-by-reference).
```http
GET /customers.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `direction` | [`Sorting Direction`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/sorting-direction) | Query, Optional | Direction to sort customers by time of creation |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 50. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query `per_page=200`.
**Default**: `50`
**Constraints**: `<= 200` |
| `date_field` | [`Basic Date Field`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/basic-date-field) | Query, Optional | The type of filter you would like to apply to your search. Use in query: `date_field=created_at`. |
| `start_date` | `String` | Query, Optional | The start date (format YYYY-MM-DD) with which to filter the date_field. Returns subscriptions with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified. |
| `end_date` | `String` | Query, Optional | The end date (format YYYY-MM-DD) with which to filter the date_field. Returns subscriptions with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified. |
| `start_datetime` | `String` | Query, Optional | The start date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns subscriptions with a timestamp at or after exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of start_date. |
| `end_datetime` | `String` | Query, Optional | The end date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns subscriptions with a timestamp at or before exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of end_date. |
| `q` | `String` | Query, Optional | A search query by which to filter customers (can be an email, an ID, a reference, organization) |
# Response Type
**200**: OK
[`array`](https://developers.maxio.com/http/advanced-billing-api/models/structures/customer-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/customers.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'page=1' \
-d 'per_page=30' \
-d 'date_field=updated_at'
```
# Example Response *(as JSON)*
```json
[
{
"customer": {
"first_name": "Kayla",
"last_name": "Test",
"email": "kayla@example.com",
"cc_emails": "john@example.com, sue@example.com",
"organization": "",
"reference": null,
"id": 14126091,
"created_at": "2016-10-04T15:22:27-04:00",
"updated_at": "2016-10-04T15:22:30-04:00",
"address": "",
"address_2": "",
"city": "",
"state": "",
"zip": "",
"country": "",
"phone": "",
"verified": null,
"portal_customer_created_at": "2016-10-04T15:22:29-04:00",
"portal_invite_last_sent_at": "2016-10-04T15:22:30-04:00",
"portal_invite_last_accepted_at": null,
"tax_exempt": false,
"surcharging": false
}
},
{
"customer": {
"first_name": "Nick ",
"last_name": "Test",
"email": "nick@example.com",
"cc_emails": "john@example.com, sue@example.com",
"organization": "",
"reference": null,
"id": 14254093,
"created_at": "2016-10-13T16:52:51-04:00",
"updated_at": "2016-10-13T16:52:54-04:00",
"address": "",
"address_2": "",
"city": "",
"state": "",
"zip": "",
"country": "",
"phone": "",
"verified": null,
"portal_customer_created_at": "2016-10-13T16:52:54-04:00",
"portal_invite_last_sent_at": "2016-10-13T16:52:54-04:00",
"portal_invite_last_accepted_at": null,
"tax_exempt": false,
"surcharging": true,
"parent_id": 123
}
},
{
"customer": {
"first_name": "Don",
"last_name": "Test",
"email": "don@example.com",
"cc_emails": "john@example.com, sue@example.com",
"organization": "",
"reference": null,
"id": 14332342,
"created_at": "2016-10-19T10:49:13-04:00",
"updated_at": "2016-10-19T10:49:19-04:00",
"address": "1737 15th St",
"address_2": "",
"city": "Boulder",
"state": "CO",
"zip": "80302",
"country": "US",
"phone": "",
"verified": null,
"portal_customer_created_at": "2016-10-19T10:49:19-04:00",
"portal_invite_last_sent_at": "2016-10-19T10:49:19-04:00",
"portal_invite_last_accepted_at": null,
"tax_exempt": false,
"surcharging": false,
"parent_id": null
}
}
]
```
##### Read Customer
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/customers/read-customer
Retrieves the Customer properties by Advanced Billing-generated Customer ID.
```http
GET /customers/{id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `id` | `Number` | Template, Required | The Advanced Billing id of the customer |
# Response Type
**200**: OK
[`Customer Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/customer-response)
# Example Usage
```bash
curl -X GET \
--url 'https://subdomain.chargify.com/customers/112.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"customer": {
"first_name": "Jane",
"last_name": "Doe",
"email": "jane@example.com",
"cc_emails": "joe@example.com",
"organization": "ABC, Inc.",
"reference": "1234567890",
"id": 88833369,
"created_at": "2025-05-08T11:39:18-04:00",
"updated_at": "2025-05-08T11:39:18-04:00",
"address": "123 Main Street",
"address_2": "Unit 10",
"city": "Anytown",
"state": "MA",
"state_name": "Massachusetts",
"zip": "02120",
"country": "US",
"country_name": "United States",
"phone": "555-555-1212",
"verified": false,
"portal_customer_created_at": null,
"portal_invite_last_sent_at": null,
"portal_invite_last_accepted_at": null,
"tax_exempt": false,
"surcharging": false,
"vat_number": null,
"parent_id": null,
"locale": "es-MX",
"salesforce_id": null,
"default_auto_renewal_profile_id": null
}
}
```
##### Update Customer
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/customers/update-customer
Updates the customer.
```http
PUT /customers/{id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `id` | `Number` | Template, Required | The Advanced Billing id of the customer |
| `body` | [`Update Customer Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/update-customer-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Customer Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/customer-response)
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/customers/112.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"customer": {
"first_name": "Martha",
"last_name": "Washington",
"email": "martha.washington@example.com"
}
}'
```
# Example Response *(as JSON)*
```json
{
"customer": {
"first_name": "Martha",
"last_name": "Washington",
"email": "martha.washington@example.com",
"cc_emails": "george.washington@example.com",
"organization": null,
"reference": null,
"id": 14967442,
"created_at": "2016-12-05T10:33:07-05:00",
"updated_at": "2016-12-05T10:38:00-05:00",
"address": null,
"address_2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone": null,
"verified": false,
"portal_customer_created_at": null,
"portal_invite_last_sent_at": null,
"portal_invite_last_accepted_at": null,
"tax_exempt": false,
"surcharging": false,
"vat_number": "012345678"
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | |
| 422 | Unprocessable Entity (WebDAV) | [`Customer Error ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/customer-error-response) |
##### Delete Customer
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/customers/delete-customer
Deletes the customer.
```http
DELETE /customers/{id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `id` | `Number` | Template, Required | The Advanced Billing id of the customer |
# Response Type
**204**: No Content
`Void`
# Example Usage
```bash
curl -X DELETE \
--url 'https://subdomain.chargify.com/customers/112.json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
##### Read Customer by Reference
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/customers/read-customer-by-reference
Returns a customer by their unique reference ID. It will return a single match.
```http
GET /customers/lookup.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `reference` | `String` | Query, Required | Customer reference |
# Response Type
**200**: OK
[`Customer Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/customer-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/customers/lookup.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'reference=reference4'
```
##### List Customer Subscriptions
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/customers/list-customer-subscriptions
Lists all subscriptions that belong to a customer.
If you have the new [Catalog experience](https://developers.maxio.com/http/help/announcements/2026-announcements#new-catalog-experience-and-terminology) enabled, subscriptions no longer require an associated product. For subscriptions without an associated product, 'product', 'product_price_point_id', and 'product_price_point_type' are returned as 'null'.
```http
GET /customers/{customer_id}/subscriptions.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `customer_id` | `Number` | Template, Required | The Chargify id of the customer |
# Response Type
**200**: OK
[`array`](https://developers.maxio.com/http/advanced-billing-api/models/structures/subscription-response)
# Example Usage
```bash
curl -X GET \
--url 'https://subdomain.chargify.com/customers/150/subscriptions.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
#### Custom Fields
##### Create Metafields
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/custom-fields/create-metafields
Creates metafields on a Site for either the Subscriptions or Customers resource.
Metafields and their metadata are created in the Custom Fields configuration page on your Site. Metafields can be populated with metadata when you create them or later with the [Update Metafield](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/custom-fields/update-metafield), [Create Metadata](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/custom-fields/create-metadata), or [Update Metadata](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/custom-fields/update-metadata) endpoints. The Create Metadata and Update Metadata endpoints allow you to add metafields and metadata values to a specific subscription or customer.
Each site is limited to 100 unique metafields per resource. This means you can have 100 metafields for Subscriptions and another 100 for Customers.
> Note: After creating a metafield, the resource type cannot be modified.
In the UI and product documentation, metafields and metadata are called Custom Fields.
- Metafield is the custom field
- Metadata is the data populating the custom field.
See [Custom Fields Reference](https://docs.maxio.com/hc/en-us/articles/24266140850573-Custom-Fields-Reference) and [Custom Fields Tab](https://maxio.zendesk.com/hc/en-us/articles/24251701302925-Subscription-Summary-Custom-Fields-Tab) for information on using Custom Fields in the Advanced Billing UI.
```http
POST /{resource_type}/metafields.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `resource_type` | [`Resource Type`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/resource-type) | Template, Required | The resource type to which the metafields belong. |
| `body` | [`Create Metafields Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/create-metafields-request) | Body, Optional | - |
# Response Type
**200**: OK
[`array`](https://developers.maxio.com/http/advanced-billing-api/models/structures/metafield)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscriptions/metafields.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"metafields": {
"name": "Dropdown field",
"input_type": "dropdown",
"enum": [
"option 1",
"option 2"
],
"scope": {
"csv": "0",
"invoices": "0",
"statements": "0",
"portal": "1"
}
}
}'
```
# Example Response *(as JSON)*
```json
[
{
"name": "Color",
"scope": {
"csv": "0",
"statements": "0",
"invoices": "0",
"portal": "0"
},
"data_count": 0,
"input_type": "text",
"enum": null
},
{
"name": "Brand",
"scope": {
"csv": "0",
"statements": "0",
"invoices": "0",
"portal": "0"
},
"data_count": 0,
"input_type": "text",
"enum": null
}
]
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Single Error ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/single-error-response) |
##### List Metafields
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/custom-fields/list-metafields
Lists the metafields and their associated details for a Site and resource type. You can filter the request to a specific metafield.
```http
GET /{resource_type}/metafields.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `resource_type` | [`Resource Type`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/resource-type) | Template, Required | The resource type to which the metafields belong. |
| `name` | `String` | Query, Optional | Filter by the name of the metafield. |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query `per_page=200`.
**Default**: `20`
**Constraints**: `<= 200` |
| `direction` | [`Sorting Direction`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/sorting-direction) | Query, Optional | Controls the order in which results are returned. Use in query `direction=asc`. |
# Response Type
**200**: OK
[`List Metafields Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/list-metafields-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/subscriptions/metafields.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'page=1' \
-d 'per_page=50'
```
# Example Response *(as JSON)*
```json
{
"total_count": 1,
"current_page": 1,
"total_pages": 0,
"per_page": 50,
"metafields": [
{
"id": 0,
"name": "string",
"scope": {
"csv": "0",
"statements": "0",
"invoices": "0",
"portal": "0",
"public_show": "0",
"public_edit": "0"
},
"data_count": 0,
"input_type": "text",
"enum": null
}
]
}
```
##### Update Metafield
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/custom-fields/update-metafield
Updates metafields on your Site for a resource type. Depending on the request structure, you can update or add metafields and metadata to the Subscriptions or Customers resource.
With this endpoint, you can:
- Add metafields. If the metafield specified in current_name does not exist, a new metafield is added.
> Note: Each site is limited to 100 unique metafields per resource. This means you can have 100 metafields for Subscriptions and another 100 for Customers.
- Change the name of a metafield.
> Note: To keep the metafield name the same and only update the metadata for the metafield, you must use the current metafield name in both the `current_name` and `name` parameters.
- Change the input type for the metafield. For example, you can change a metafield input type from text to a dropdown. If you change the input type from text to a dropdown or radio, you must update the specific subscriptions or customers where the metafield was used to reflect the updated metafield and metadata.
- Add metadata values to the existing metadata for a dropdown or radio metafield.
> Note: Updates to metadata overwrite. To add one or more values, you must specify all metadata values including the new value you want to add.
- Add new metadata to a dropdown or radio for a metafield that was created without metadata.
- Remove metadata for a dropdown or radio for a metafield.
> Note: Updates to metadata overwrite existing values. To remove one or more values, specify all metadata values except those you want to remove.
- Add or update scope settings for a metafield.
> Note: Scope changes overwrite existing settings. You must specify the complete scope, including the changes you want to make.
```http
PUT /{resource_type}/metafields.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `resource_type` | [`Resource Type`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/resource-type) | Template, Required | The resource type to which the metafields belong. |
| `body` | [`Update Metafields Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/update-metafields-request) | Body, Optional | - |
# Response Type
**200**: OK
[`array`](https://developers.maxio.com/http/advanced-billing-api/models/structures/metafield)
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/subscriptions/metafields.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Single Error ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/single-error-response) |
##### Delete Metafield
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/custom-fields/delete-metafield
Deletes a metafield from your Site. Removes the metafield and associated metadata from all Subscriptions or Customers resources on the Site.
```http
DELETE /{resource_type}/metafields.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `resource_type` | [`Resource Type`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/resource-type) | Template, Required | The resource type to which the metafields belong. |
| `name` | `String` | Query, Optional | The name of the metafield to be deleted |
# Response Type
**200**: OK
`Void`
# Example Usage
```bash
curl -X DELETE -G \
--url 'https://subdomain.chargify.com/subscriptions/metafields.json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description |
| --- | --- |
| 404 | Not Found |
##### Create Metadata
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/custom-fields/create-metadata
Creates metadata and metafields for a specific subscription or customer, or updates metadata values of existing metafields for a subscription or customer. Metadata values are limited to 2 KB in size.
If you create metadata on a subscription or customer with a metafield that does not already exist, the metafield is created with the metadata you specify and it is always added as a text field. You can update the input_type for the metafield with the [Update Metafield](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/custom-fields/update-metafield) endpoint.
> Note: Each site is limited to 100 unique metafields per resource. This means you can have 100 metafields for Subscriptions and another 100 for Customers.
```http
POST /{resource_type}/{resource_id}/metadata.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `resource_type` | [`Resource Type`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/resource-type) | Template, Required | The resource type to which the metafields belong. |
| `resource_id` | `Number` | Template, Required | The Advanced Billing id of the customer or the subscription for which the metadata applies |
| `body` | [`Create Metadata Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/create-metadata-request) | Body, Optional | - |
# Response Type
**200**: OK
[`array`](https://developers.maxio.com/http/advanced-billing-api/models/structures/metadata)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscriptions/60/metadata.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"metadata": [
{
"name": "Color",
"value": "Blue"
},
{
"name": "Something",
"value": "Useful"
}
]
}'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Single Error ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/single-error-response) |
##### List Metadata
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/custom-fields/list-metadata
Lists metadata and metafields for a specific customer or subscription.
```http
GET /{resource_type}/{resource_id}/metadata.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `resource_type` | [`Resource Type`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/resource-type) | Template, Required | The resource type to which the metafields belong. |
| `resource_id` | `Number` | Template, Required | The Advanced Billing id of the customer or the subscription for which the metadata applies |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query `per_page=200`.
**Default**: `20`
**Constraints**: `<= 200` |
# Response Type
**200**: OK
[`Paginated Metadata`](https://developers.maxio.com/http/advanced-billing-api/models/structures/paginated-metadata)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/subscriptions/60/metadata.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'page=1' \
-d 'per_page=50'
```
# Example Response *(as JSON)*
```json
{
"total_count": 1,
"current_page": 1,
"total_pages": 1,
"per_page": 50,
"metadata": [
{
"id": 77889911,
"value": "green",
"resource_id": 1234567,
"metafield_id": 112233,
"deleted_at": null,
"name": "Color"
}
]
}
```
##### Update Metadata
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/custom-fields/update-metadata
Updates metadata and metafields on the Site and the customer or subscription specified, and updates the metadata value on a subscription or customer.
If you update metadata on a subscription or customer with a metafield that does not already exist, the metafield is created with the metadata you specify and it is always added as a text field to the Site and to the subscription or customer you specify. You can update the input_type for the metafield with the Update Metafield endpoint.
Each site is limited to 100 unique metafields per resource. This means you can have 100 metafields for the Subscription resource and another 100 for the Customer resource.
```http
PUT /{resource_type}/{resource_id}/metadata.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `resource_type` | [`Resource Type`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/resource-type) | Template, Required | The resource type to which the metafields belong. |
| `resource_id` | `Number` | Template, Required | The Advanced Billing id of the customer or the subscription for which the metadata applies |
| `body` | [`Update Metadata Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/update-metadata-request) | Body, Optional | - |
# Response Type
**200**: OK
[`array`](https://developers.maxio.com/http/advanced-billing-api/models/structures/metadata)
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/subscriptions/60/metadata.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Single Error ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/single-error-response) |
##### Delete Metadata
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/custom-fields/delete-metadata
Deletes one or more metafields (and associated metadata) from the specified subscription or customer.
```http
DELETE /{resource_type}/{resource_id}/metadata.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `resource_type` | [`Resource Type`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/resource-type) | Template, Required | The resource type to which the metafields belong. |
| `resource_id` | `Number` | Template, Required | The Advanced Billing id of the customer or the subscription for which the metadata applies |
| `name` | `String` | Query, Optional | Name of field to be removed. |
| `names` | `array` | Query, Optional | Names of fields to be removed. Use in query: `names[]=field1&names[]=my-field&names[]=another-field`. |
# Response Type
**200**: OK
`Void`
# Example Usage
```bash
curl -X DELETE -G \
--url 'https://subdomain.chargify.com/subscriptions/60/metadata.json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description |
| --- | --- |
| 404 | Not Found |
##### List Metadata for Resource Type
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/custom-fields/list-metadata-for-resource-type
Lists metadata for a specified array of subscriptions or customers.
```http
GET /{resource_type}/metadata.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `resource_type` | [`Resource Type`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/resource-type) | Template, Required | The resource type to which the metafields belong. |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query `per_page=200`.
**Default**: `20`
**Constraints**: `<= 200` |
| `date_field` | [`Basic Date Field`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/basic-date-field) | Query, Optional | The type of filter you would like to apply to your search. |
| `start_date` | `Date` | Query, Optional | The start date (format YYYY-MM-DD) with which to filter the date_field. Returns metadata with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified. |
| `end_date` | `Date` | Query, Optional | The end date (format YYYY-MM-DD) with which to filter the date_field. Returns metadata with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified. |
| `start_datetime` | `DateTime` | Query, Optional | The start date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns metadata with a timestamp at or after exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of start_date. |
| `end_datetime` | `DateTime` | Query, Optional | The end date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns metadata with a timestamp at or before exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of end_date. |
| `with_deleted` | `Boolean` | Query, Optional | Allow to fetch deleted metadata. |
| `resource_ids` | `array` | Query, Optional | Allow to fetch metadata for multiple records based on provided ids. Use in query: `resource_ids[]=122&resource_ids[]=123&resource_ids[]=124`.
**Constraints**: *Maximum Items*: `50` |
| `direction` | [`Sorting Direction`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/sorting-direction) | Query, Optional | Controls the order in which results are returned. Use in query `direction=asc`. |
# Response Type
**200**: OK
[`Paginated Metadata`](https://developers.maxio.com/http/advanced-billing-api/models/structures/paginated-metadata)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/subscriptions/metadata.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'page=1' \
-d 'per_page=50' \
-d 'date_field=updated_at'
```
#### Entitlements
##### Read Subscription Entitlements
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/entitlements/read-subscription-entitlements
Returns every feature a subscription is entitled to, aggregated per (feature key, periodicity window) across all of its products and components — a `usage_limit` feature granted with two different periodicities comes back as two entries sharing one `feature_key`, each identified by its own `periodicity_key`.
When more than one product or component grants the same feature key and periodicity, the values are combined:
- **`access_right`** features are combined with a boolean OR — if any contributor grants access, the aggregate is `true`. `source_products` only lists the contributors that granted `true`.
- **`usage_limit`** features are summed across every contributor sharing the same periodicity window. `source_products` lists every contributor. Grants with different periodicities are not summed together — they are returned as separate entries.
- **`service_right`** features are not combined: one contributor's value wins. Do not rely on which one when several grant the same feature key.
`enabled` reflects both the aggregated value and the subscription's state: it is `false` whenever the subscription is not in a live state (`active`, `trialing`, `assessing`, `past_due`, `soft_failure`), regardless of the aggregated value. Entitlements deliberately stay enabled through dunning.
```http
GET /subscriptions/{subscription_id}/entitlements.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
# Response Type
**200**: OK
[`Aggregated Entitlements Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/aggregated-entitlements-response)
# Example Usage
```bash
curl -X GET \
--url 'https://subdomain.chargify.com/subscriptions/222/entitlements.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"subscription_id": 12345,
"customer_id": 678,
"status": "active",
"entitlements": [
{
"feature_key": "feature.sso",
"periodicity_key": "feature.sso",
"name": "SSO",
"type": "access_right",
"value": true,
"enabled": true,
"periodicity": null,
"source_products": [
"Gold Plan"
]
},
{
"feature_key": "usage.api_calls",
"periodicity_key": "usage.api_calls:1:month",
"name": "API Calls",
"type": "usage_limit",
"value": 50000,
"enabled": true,
"periodicity": {
"interval": 1,
"unit": "month"
},
"source_products": [
"Gold Plan"
]
}
]
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 403 | Forbidden | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
| 404 | Not Found | |
#### Events
##### List Events
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/events/list-events
Lists events for a site.
Events include various activity that happens around a Site. This information is **especially** useful to track down issues that arise when subscriptions are not created due to errors.
Within the UI, Events are referred to as Site Activity. For more information, see [Site Activity](https://maxio.zendesk.com/hc/en-us/articles/24250671733517-Site-Activity).
Use query string filters to narrow down results. You can use the `filter` parameter to filter by event key.
### Legacy Filters
The following keys are no longer supported.
+ `payment_failure_recreated`
+ `payment_success_recreated`
+ `renewal_failure_recreated`
+ `renewal_success_recreated`
+ `zferral_revenue_post_failure` - (Specific to the deprecated Zferral integration)
+ `zferral_revenue_post_success` - (Specific to the deprecated Zferral integration)
## Event Key
The event type is identified by the key property. See [Event Key](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/event-key) for a complete list of supported keys.
## Event Specific Data
Different event types may include additional data in `event_specific_data` property.
While some events share the same schema for `event_specific_data`, others may not include it at all.
For precise mappings from key to event_specific_data, refer to [Event](https://developers.maxio.com/http/advanced-billing-api/models/structures/event).
### Example
Here’s an example event for the `subscription_product_change` event:
```
{
"event": {
"id": 351,
"key": "subscription_product_change",
"message": "Product changed on Mark Alan's subscription from 'Basic' to 'Pro'",
"subscription_id": 205,
"event_specific_data": {
"new_product_id": 3,
"previous_product_id": 2
},
"created_at": "2012-01-30T10:43:31-05:00"
}
}
```
Here’s an example event for the `subscription_state_change` event:
```
{
"event": {
"id": 353,
"key": "subscription_state_change",
"message": "State changed on Mark Alan's subscription to Pro from trialing to active",
"subscription_id": 205,
"event_specific_data": {
"new_subscription_state": "active",
"previous_subscription_state": "trialing"
},
"created_at": "2012-01-30T10:43:33-05:00"
}
}
```
## Enhanced Catalog Experience
If you’re using the [enhanced Catalog experience](https://developers.maxio.com/http/help/announcements/2026-announcements#new-catalog-experience-and-terminology), you’ll see updated naming in webhook events and messages.
Event name changes:
- subscription_product_change → subscription_plan_change
- component_allocation_change → allocation_change
- component_billing_date_change → product_billing_date_change
Message updates:
- “Plan changed on Subscription from previous plan to new plan”
- “Successful payment for allocation changes to Product on Subscription”
- “Failed payment for allocation changes to Product on Subscription”
```http
GET /events.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query `per_page=200`.
**Default**: `20`
**Constraints**: `<= 200` |
| `since_id` | `Long` | Query, Optional | Returns events with an id greater than or equal to the one specified. |
| `max_id` | `Long` | Query, Optional | Returns events with an id less than or equal to the one specified. |
| `direction` | [`Direction`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/direction) | Query, Optional | The sort direction of the returned events.
**Default**: `desc` |
| `filter` | [`array`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/event-key) | Query, Optional | You can pass multiple event keys after comma. Use in query `filter=signup_success,payment_success`. |
| `date_field` | [`List Events Date Field`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/list-events-date-field) | Query, Optional | The type of filter you would like to apply to your search. |
| `start_date` | `String` | Query, Optional | The start date (format YYYY-MM-DD) with which to filter the date_field. Returns components with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified. |
| `end_date` | `String` | Query, Optional | The end date (format YYYY-MM-DD) with which to filter the date_field. Returns components with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified. |
| `start_datetime` | `String` | Query, Optional | The start date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns components with a timestamp at or after exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of start_date. |
| `end_datetime` | `String` | Query, Optional | The end date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns components with a timestamp at or before exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of end_date. |
# Response Type
**200**: OK
[`array`](https://developers.maxio.com/http/advanced-billing-api/models/structures/event-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/events.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'page=1' \
-d 'per_page=50' \
-d 'direction=desc' \
-d 'filter=custom_field_value_change%2Cpayment_success' \
-d 'date_field=created_at'
```
# Example Response *(as JSON)*
```json
[
{
"event": {
"id": 343087780,
"key": "subscription_state_change",
"message": "State changed on Test subscription to Monthly Product from active to past_due",
"subscription_id": 14950962,
"customer_id": 12345678,
"created_at": "2016-10-27T16:42:22-04:00",
"event_specific_data": {
"previous_subscription_state": "active",
"new_subscription_state": "past_due"
}
}
},
{
"event": {
"id": 343087742,
"key": "billing_date_change",
"message": "Billing date changed on Test's subscription to Monthly Product from 11/27/2016 to 10/27/2016",
"subscription_id": 14950962,
"customer_id": 12345678,
"created_at": "2016-10-27T16:42:19-04:00",
"event_specific_data": null
}
},
{
"event": {
"id": 343085267,
"key": "statement_closed",
"message": "Statement 79401838 closed (but not settled) for Test's subscription to ANNUAL product",
"subscription_id": 14950975,
"customer_id": 87654321,
"created_at": "2016-10-27T16:40:40-04:00",
"event_specific_data": null
}
},
{
"event": {
"id": 4481,
"key": "custom_field_value_change",
"message": "Custom field (Extra support included) changed for Subscription 117 from 'Yes' to 'No'.",
"subscription_id": 117,
"customer_id": 22334455,
"created_at": "2022-03-24T07:55:06-04:00",
"event_specific_data": {
"event_type": "updated",
"metafield_name": "Extra support included",
"metafield_id": 2,
"old_value": "Yes",
"new_value": "No",
"resource_type": "Subscription",
"resource_id": 117
}
}
}
]
```
##### List Subscription Events
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/events/list-subscription-events
Lists events for a subscription.
## Event Key
The event type is identified by the key property. See [Event Key](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/event-key) for a complete list of supported keys.
## Event Specific Data
Different event types may include additional data in `event_specific_data` property.
While some events share the same schema for `event_specific_data`, others may not include it at all.
For precise mappings from key to event_specific_data, refer to [Event](https://developers.maxio.com/http/advanced-billing-api/models/structures/event).
## Enhanced Catalog Experience
If you’re using the [enhanced Catalog experience](https://developers.maxio.com/http/help/announcements/2026-announcements#new-catalog-experience-and-terminology), you’ll see updated naming in webhook events and messages.
Event name changes:
- subscription_product_change → subscription_plan_change
- component_allocation_change → allocation_change
- component_billing_date_change → product_billing_date_change
Message updates:
- “Successful payment for allocation changes to Product on Subscription”
- “Failed payment for allocation changes to Product on Subscription”
- “Plan changed on Subscription from previous plan to new plan”
```http
GET /subscriptions/{subscription_id}/events.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query `per_page=200`.
**Default**: `20`
**Constraints**: `<= 200` |
| `since_id` | `Long` | Query, Optional | Returns events with an id greater than or equal to the one specified. |
| `max_id` | `Long` | Query, Optional | Returns events with an id less than or equal to the one specified. |
| `direction` | [`Direction`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/direction) | Query, Optional | The sort direction of the returned events.
**Default**: `desc` |
| `filter` | [`array`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/event-key) | Query, Optional | You can pass multiple event keys after comma. Use in query `filter=signup_success,payment_success`. |
# Response Type
**200**: OK
[`array`](https://developers.maxio.com/http/advanced-billing-api/models/structures/event-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/subscriptions/222/events.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'page=1' \
-d 'per_page=50' \
-d 'direction=desc' \
-d 'filter=custom_field_value_change%2Cpayment_success'
```
# Example Response *(as JSON)*
```json
[
{
"event": {
"id": 344799837,
"key": "statement_settled",
"message": "Statement 79702531 settled successfully for Amelia Example's subscription to Basic Plan",
"subscription_id": 14900541,
"customer_id": 77223344,
"created_at": "2016-11-01T12:41:29-04:00",
"event_specific_data": null
}
},
{
"event": {
"id": 344799815,
"key": "renewal_success",
"message": "Successful renewal for Amelia Example's subscription to Basic Plan",
"subscription_id": 14900541,
"customer_id": 77223344,
"created_at": "2016-11-01T12:41:28-04:00",
"event_specific_data": {
"product_id": 3792003,
"account_transaction_id": 7590246
}
}
},
{
"event": {
"id": 344799705,
"key": "billing_date_change",
"message": "Billing date changed on Amelia Example's subscription to Basic Plan from 11/26/2016 to 11/01/2016",
"subscription_id": 14900541,
"customer_id": 77223344,
"created_at": "2016-11-01T12:41:25-04:00",
"event_specific_data": null
}
}
]
```
##### Read Events Count
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/events/read-events-count
Returns the total count of events for a given site.
If you’re using the [enhanced Catalog experience](https://developers.maxio.com/http/help/announcements/2026-announcements#new-catalog-experience-and-terminology), you’ll see updated naming in webhook events and messages.
Event name changes:
- subscription_product_change → subscription_plan_change
- component_allocation_change → allocation_change
- component_billing_date_change → product_billing_date_change
Message updates:
- “Successful payment for allocation changes to Product on Subscription”
- “Failed payment for allocation changes to Product on Subscription”
- “Plan changed on Subscription from previous plan to new plan”
```http
GET /events/count.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query `per_page=200`.
**Default**: `20`
**Constraints**: `<= 200` |
| `since_id` | `Long` | Query, Optional | Returns events with an id greater than or equal to the one specified. |
| `max_id` | `Long` | Query, Optional | Returns events with an id less than or equal to the one specified. |
| `direction` | [`Direction`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/direction) | Query, Optional | The sort direction of the returned events.
**Default**: `desc` |
| `filter` | [`array`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/event-key) | Query, Optional | You can pass multiple event keys after comma. Use in query `filter=signup_success,payment_success`. |
# Response Type
**200**: OK
[`Count Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/count-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/events/count.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'page=1' \
-d 'per_page=50' \
-d 'direction=desc' \
-d 'filter=custom_field_value_change%2Cpayment_success'
```
# Example Response *(as JSON)*
```json
{
"count": 144
}
```
#### Events-Based Billing Segments
##### Create Segment
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/events-based-billing-segments/create-segment
Creates a new segment for a component with a segmented metric. It allows you to specify properties to bill upon and prices for each Segment. You can only pass as many "property_values" as the related Metric has segmenting properties defined.
You may specify component and/or price point by using either the numeric ID or the `handle:gold` syntax.
```http
POST /components/{component_id}/price_points/{price_point_id}/segments.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `component_id` | `String` | Template, Required | ID or Handle for the Component |
| `price_point_id` | `String` | Template, Required | ID or Handle for the Price Point belonging to the Component |
| `body` | [`Create Segment Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/create-segment-request) | Body, Optional | - |
# Response Type
**201**: Created
[`Segment Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/segment-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/components/component_id8/price_points/price_point_id8/segments.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"segment": {
"segment_property_1_value": "France",
"segment_property_2_value": "Spain",
"pricing_scheme": "volume",
"prices": [
{
"starting_quantity": 1,
"ending_quantity": 10000,
"unit_price": 0.19
},
{
"starting_quantity": 10001,
"unit_price": 0.09
}
]
}
}'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | |
| 422 | Unprocessable Entity (WebDAV) | [`Event Based Billing Segment ErrorsException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/event-based-billing-segment-errors) |
##### List Segments for Price Point
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/events-based-billing-segments/list-segments-for-price-point
Lists segments created for a given price point, in order of creation.
You can pass `page` and `per_page` parameters in order to access all of the segments. By default it will return `30` records. You can set `per_page` to `200` at most.
You may specify component and/or price point by using either the numeric ID or the `handle:gold` syntax.
```http
GET /components/{component_id}/price_points/{price_point_id}/segments.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `component_id` | `String` | Template, Required | ID or Handle for the Component |
| `price_point_id` | `String` | Template, Required | ID or Handle for the Price Point belonging to the Component |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 30. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query `per_page=200`.
**Default**: `30`
**Constraints**: `<= 200` |
| `filter` | [`List Segments Filter`](https://developers.maxio.com/http/advanced-billing-api/models/structures/list-segments-filter) | Query, Optional | Filter to use for List Segments for a Price Point operation |
# Response Type
**200**: OK
[`List Segments Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/list-segments-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/components/component_id8/price_points/price_point_id8/segments.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'page=1' \
-d 'per_page=50' \
-d 'filter[segment_property_1_value]=EU'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | |
| 422 | Unprocessable Entity (WebDAV) | [`Event Based Billing List Segments ErrorsException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/event-based-billing-list-segments-errors) |
##### Update Segment
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/events-based-billing-segments/update-segment
Updates a single segment for a component with a segmented metric. You can also update the pricing for the segment.
You can specify component and/or price point by using either the numeric ID or the `handle:gold` syntax.
```http
PUT /components/{component_id}/price_points/{price_point_id}/segments/{id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `component_id` | `String` | Template, Required | ID or Handle of the Component |
| `price_point_id` | `String` | Template, Required | ID or Handle of the Price Point belonging to the Component |
| `id` | `Decimal` | Template, Required | The ID of the Segment |
| `body` | [`Update Segment Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/update-segment-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Segment Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/segment-response)
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/components/component_id8/price_points/price_point_id8/segments/60.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | |
| 422 | Unprocessable Entity (WebDAV) | [`Event Based Billing Segment ErrorsException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/event-based-billing-segment-errors) |
##### Delete Segment
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/events-based-billing-segments/delete-segment
Deletes a segment with the specified ID.
You may specify component and/or price point by using either the numeric ID or the `handle:gold` syntax.
```http
DELETE /components/{component_id}/price_points/{price_point_id}/segments/{id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `component_id` | `String` | Template, Required | ID or Handle of the Component |
| `price_point_id` | `String` | Template, Required | ID or Handle of the Price Point belonging to the Component |
| `id` | `Decimal` | Template, Required | The ID of the Segment |
# Response Type
**204**: No Content
`Void`
# Example Usage
```bash
curl -X DELETE \
--url 'https://subdomain.chargify.com/components/component_id8/price_points/price_point_id8/segments/60.json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description |
| --- | --- |
| 404 | Not Found |
| 422 | Unprocessable Entity (WebDAV) |
##### Bulk Create Segments
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/events-based-billing-segments/bulk-create-segments
Creates multiple segments in one request. The array of segments can contain up to `2000` records.
If any of the records contain an error the whole request would fail and none of the requested segments get created. The error response contains a message for only the one segment that failed validation, with the corresponding index in the array.
You may specify component and/or price point by using either the numeric ID or the `handle:gold` syntax.
```http
POST /components/{component_id}/price_points/{price_point_id}/segments/bulk.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `component_id` | `String` | Template, Required | ID or Handle for the Component |
| `price_point_id` | `String` | Template, Required | ID or Handle for the Price Point belonging to the Component |
| `body` | [`Bulk Create Segments`](https://developers.maxio.com/http/advanced-billing-api/models/structures/bulk-create-segments) | Body, Optional | - |
# Response Type
**201**: Created
[`List Segments Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/list-segments-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/components/component_id8/price_points/price_point_id8/segments/bulk.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | |
| 422 | Unprocessable Entity (WebDAV) | [`Event Based Billing SegmentException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/event-based-billing-segment) |
##### Bulk Update Segments
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/events-based-billing-segments/bulk-update-segments
Updates multiple segments in one request. The array of segments can contain up to `1000` records.
If any of the records contain an error the whole request would fail and none of the requested segments get updated. The error response contains a message for only the one segment that failed validation, with the corresponding index in the array.
You may specify component and/or price point by using either the numeric ID or the `handle:gold` syntax.
```http
PUT /components/{component_id}/price_points/{price_point_id}/segments/bulk.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `component_id` | `String` | Template, Required | ID or Handle for the Component |
| `price_point_id` | `String` | Template, Required | ID or Handle for the Price Point belonging to the Component |
| `body` | [`Bulk Update Segments`](https://developers.maxio.com/http/advanced-billing-api/models/structures/bulk-update-segments) | Body, Optional | - |
# Response Type
**200**: OK
[`List Segments Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/list-segments-response)
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/components/component_id8/price_points/price_point_id8/segments/bulk.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | |
| 422 | Unprocessable Entity (WebDAV) | [`Event Based Billing SegmentException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/event-based-billing-segment) |
#### Feature Templates
##### List Feature Templates
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/feature-templates/list-feature-templates
Returns the feature templates defined for your site. Returns active (non-archived) templates by default; pass `status=archived` or `status=all` to widen the result set.
Paginated when `page` or `per_page` is supplied; otherwise returns the full result set.
```http
GET /features.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query `per_page=200`.
**Default**: `asc` |
# Response Type
**200**: OK
[`Feature Templates List Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/feature-templates-list-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/features.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'page=1' \
-d 'per_page=50' \
-d 'status=active' \
-d 'sort_by=name' \
-d 'sort_direction=asc'
```
# Example Response *(as JSON)*
```json
{
"items": [
{
"id": 1001,
"key": "sso",
"name": "Single Sign-On",
"description": null,
"kind": "access_right",
"unit": null,
"value_type": "boolean",
"default_value": "true",
"default_periodicity_interval": null,
"default_periodicity_unit": null,
"archived_at": null,
"created_at": "2024-01-15T10:00:00-05:00",
"updated_at": "2024-01-15T10:00:00-05:00",
"products_count": 2,
"plans_count": 5
}
],
"total_count": 1,
"archived_count": 0
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 403 | Forbidden | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Create Feature Template
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/feature-templates/create-feature-template
Defines a new feature at the site level. Feature templates aren't billable on their own — attach them to products or components to grant them to subscribers.
```http
POST /features.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `body` | [`Create Feature Template Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/create-feature-template-request) | Body, Optional | - |
# Response Type
**201**: Created
[`Feature Template Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/feature-template-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/features.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"feature": {
"key": "sso",
"name": "Single Sign-On",
"kind": "access_right"
}
}'
```
# Example Response *(as JSON)*
```json
{
"feature": {
"id": 1001,
"key": "sso",
"name": "Single Sign-On",
"description": null,
"kind": "access_right",
"unit": null,
"value_type": "boolean",
"default_value": "true",
"default_periodicity_interval": null,
"default_periodicity_unit": null,
"archived_at": null,
"created_at": "2024-01-15T10:00:00-05:00",
"updated_at": "2024-01-15T10:00:00-05:00",
"products_count": 0,
"plans_count": 0
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 403 | Forbidden | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Read Feature Template
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/feature-templates/read-feature-template
Returns a single feature template. Archived feature templates are not addressable here and return `404` — restore one first to read or update it.
```http
GET /features/{id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `id` | `Number` | Template, Required | The Advanced Billing id of the feature template. |
# Response Type
**200**: OK
[`Feature Template Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/feature-template-response)
# Example Usage
```bash
curl -X GET \
--url 'https://subdomain.chargify.com/features/112.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 403 | Forbidden | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
| 404 | Not Found | |
##### Update Feature Template
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/feature-templates/update-feature-template
`key` is rejected on every update. `kind` is rejected once any feature catalog item has been created from this template. Archived feature templates are not addressable here and return `404` — restore one first to update it.
```http
PUT /features/{id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `id` | `Number` | Template, Required | The Advanced Billing id of the feature template. |
| `body` | [`Update Feature Template Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/update-feature-template-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Feature Template Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/feature-template-response)
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/features/112.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 403 | Forbidden | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
| 404 | Not Found | |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Archive Feature Template
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/feature-templates/archive-feature-template
Archived feature templates are not addressable via [Read Feature Template](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/feature-templates/read-feature-template) or [Update Feature Template](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/feature-templates/update-feature-template) — both return `404` until the template is restored.
The feature template record itself is never hard-deleted, and can always be restored with [Restore Feature Template](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/feature-templates/restore-feature-template). Reversibility does not extend to `remove_from_catalog=true`: the feature catalog items and entitlements it destroys are gone permanently, and restoring the template will not bring subscriber access back.
```http
DELETE /features/{id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `id` | `Number` | Template, Required | The Advanced Billing id of the feature template. |
| `remove_from_catalog` | `Boolean` | Query, Optional | When `true`, also destroys every feature catalog item created from this template and cascades to their entitlements, revoking subscriber access immediately. When `false` (default), the feature template and its feature catalog items are archived, and existing entitlements are preserved.
**Default**: `false` |
# Response Type
**204**: No Content
`Void`
# Example Usage
```bash
curl -X DELETE -G \
--url 'https://subdomain.chargify.com/features/112.json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'remove_from_catalog=false'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 403 | Forbidden | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
| 404 | Not Found | |
##### Restore Feature Template
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/feature-templates/restore-feature-template
Clears the feature template's archived state. Feature catalog items created from this template are not automatically restored — restore each one individually.
```http
POST /features/{id}/restore.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `id` | `Number` | Template, Required | The Advanced Billing id of the feature template. |
# Response Type
**200**: OK
[`Feature Template Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/feature-template-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/features/112/restore.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 403 | Forbidden | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
| 404 | Not Found | |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
#### Insights
##### Read Site Stats
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/insights/read-site-stats
Returns basic site-level stats. This API call only answers with JSON responses. An XML version is not provided.
## Stats Documentation
There currently is not a complimentary matching set of documentation that compliments this endpoint. However, each Site's dashboard will reflect the summary of information provided in the Stats response.
```
https://subdomain.chargify.com/dashboard
```
```http
GET /stats.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Response Type
**200**: OK
[`Site Summary`](https://developers.maxio.com/http/advanced-billing-api/models/structures/site-summary)
# Example Usage
```bash
curl -X GET \
--url 'https://subdomain.chargify.com/stats.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"seller_name": "Acme, Inc.",
"site_name": "Production",
"site_id": 12345,
"site_currency": "USD",
"stats": {
"total_subscriptions": 120,
"subscriptions_today": 4,
"total_revenue": "$45,978.81",
"revenue_today": "$1,405.12",
"revenue_this_month": "$10,000.00",
"revenue_this_year": "$27,935.24"
}
}
```
##### Read Mrr
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/insights/read-mrr
**This endpoint is deprecated.**
Returns your site's current MRR, including plan and usage breakouts.
```http
GET /mrr.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `at_time` | `DateTime` | Query, Optional | submit a timestamp in ISO8601 format to request MRR for a historic time. |
| `subscription_id` | `Number` | Query, Optional | submit the id of a subscription in order to limit results. |
# Response Type
**200**: OK
[`MRR Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/mrr-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/mrr.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"mrr": {
"amount_in_cents": 9915593,
"amount_formatted": "$99,155.93",
"currency": "USD",
"currency_symbol": "$",
"at_time": "2021-02-03T14:23:17-05:00",
"breakouts": {
"plan_amount_in_cents": 9913593,
"plan_amount_formatted": "$99,135.93",
"usage_amount_in_cents": 2000,
"usage_amount_formatted": "$20.00"
}
}
}
```
##### List Mrr Movements
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/insights/list-mrr-movements
**This endpoint is deprecated.**
Lists your site's MRR movements.
## Understanding MRR movements
This endpoint will aid in accessing your site's [MRR Report](https://maxio.zendesk.com/hc/en-us/articles/24285894587021-MRR-Analytics) data.
Whenever a subscription event occurs that causes your site's MRR to change (such as a signup or upgrade), we record an MRR movement. These records are accessible via the MRR Movements endpoint.
Each MRR Movement belongs to a subscription and contains a timestamp, category, and an amount. `line_items` represent the subscription's product configuration at the time of the movement.
### Plan & Usage Breakouts
In the MRR Report UI, we support a setting to [include or exclude](https://maxio.zendesk.com/hc/en-us/articles/24285894587021-MRR-Analytics#displaying-component-based-metered-usage-in-mrr) usage revenue. In the MRR APIs, responses include `plan` and `usage` breakouts.
Plan includes revenue from:
* Products
* Quantity-Based Components
* On/Off Components
Usage includes revenue from:
* Metered Components
* Prepaid Usage Components
```http
GET /mrr_movements.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Query, Optional | (Optional) Filter results by subscription. |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 10. The maximum allowed values is 50; any per_page value over 50 will be changed to 50. Use in query `per_page=20`.
**Default**: `10`
**Constraints**: `<= 50` |
| `direction` | [`Sorting Direction`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/sorting-direction) | Query, Optional | Controls the order in which results are returned. Use in query `direction=asc`. |
# Response Type
**200**: OK
[`List MRR Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/list-mrr-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/mrr_movements.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'page=1' \
-d 'per_page=20'
```
# Example Response *(as JSON)*
```json
{
"mrr": {
"page": 0,
"per_page": 10,
"total_pages": 80,
"total_entries": 791,
"currency": "USD",
"currency_symbol": "$",
"movements": [
{
"timestamp": "2014-12-03T13:59:46-05:00",
"amount_in_cents": 2173,
"amount_formatted": "$21.73",
"description": "Awesome Company signed up for Super Product ($21.73/mo)",
"category": "new_business",
"breakouts": {
"plan_amount_in_cents": 2173,
"plan_amount_formatted": "$21.73",
"usage_amount_in_cents": 0,
"usage_amount_formatted": "$0.00"
},
"line_items": [
{
"product_id": 306386,
"component_id": 0,
"price_point_id": 3856987,
"name": "Cached Queries",
"mrr": 2173,
"mrr_movements": [
{
"amount": 2173,
"category": "new_business",
"subscriber_delta": 0,
"lead_delta": 0
}
],
"quantity": 1,
"prev_quantity": 0,
"recurring": true
}
],
"subscription_id": 12355,
"subscriber_name": "Amy Smith"
}
]
}
}
```
##### List Mrr per Subscription
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/insights/list-mrr-per-subscription
**This endpoint is deprecated.**
Lists your site's current MRR, including plan and usage breakouts split per subscription.
```http
GET /subscriptions_mrr.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `filter` | [`List Mrr Filter`](https://developers.maxio.com/http/advanced-billing-api/models/structures/list-mrr-filter) | Query, Optional | Filter to use for List MRR per subscription operation |
| `at_time` | `String` | Query, Optional | Submit a timestamp in ISO8601 format to request MRR for a historic time. Use in query: `at_time=2022-01-10T10:00:00-05:00`. |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query `per_page=200`.
**Default**: `20`
**Constraints**: `<= 200` |
| `direction` | [`Direction`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/direction) | Query, Optional | Controls the order in which results are returned. Records are ordered by subscription_id in ascending order by default. Use in query `direction=desc`. |
# Response Type
**200**: OK
[`Subscription MRR Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/subscription-mrr-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/subscriptions_mrr.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'filter[subscription_ids]=1%2C2%2C3' \
-d 'at_time=at_time%3D2022-01-10T10%3A00%3A00-05%3A00' \
-d 'page=1' \
-d 'per_page=50' \
-d 'direction=desc'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 400 | Bad Request | [`Subscriptions Mrr Error ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/subscriptions-mrr-error-response) |
#### Invoices
##### Refund Invoice
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/invoices/refund-invoice
Refunds an invoice, segment, or consolidated invoice.
## Partial Refund for Consolidated Invoice
A refund less than the total of a consolidated invoice will be split across its segments.
For a $50.00 refund on a $100.00 consolidated invoice with one $60.00 segment and one $40.00 segment, the refunded amount will be applied as 50% of each ($30.00 and $20.00, respectively).
```http
POST /invoices/{uid}/refunds.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `uid` | `String` | Template, Required | The unique identifier for the invoice, this does not refer to the public facing invoice number. |
| `body` | [`Refund Invoice Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/refund-invoice-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Invoice`](https://developers.maxio.com/http/advanced-billing-api/models/structures/invoice)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/invoices/uid0/refunds.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"refund": {
"amount": "100.00",
"memo": "Refund for Basic Plan renewal",
"payment_id": 12345,
"external": false,
"apply_credit": false,
"void_invoice": true
}
}'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### List Invoices
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/invoices/list-invoices
Lists invoices for a site. By default, invoices returned on the index will only include totals, not detailed breakdowns for `line_items`, `discounts`, `taxes`, `credits`, `payments`, `custom_fields`, or `refunds`. To include breakdowns, pass the specific field as a key in the query with a value set to `true`.
```http
GET /invoices.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `start_date` | `String` | Query, Optional | The start date (format YYYY-MM-DD) with which to filter the date_field. Returns invoices with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified. |
| `end_date` | `String` | Query, Optional | The end date (format YYYY-MM-DD) with which to filter the date_field. Returns invoices with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified. |
| `status` | [`Invoice Status`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/invoice-status) | Query, Optional | The current status of the invoice. Allowed Values: draft, open, paid, pending, voided |
| `subscription_id` | `Number` | Query, Optional | The subscription's ID. |
| `subscription_group_uid` | `String` | Query, Optional | The UID of the subscription group you want to fetch consolidated invoices for. This will return a paginated list of consolidated invoices for the specified group. |
| `consolidation_level` | `String` | Query, Optional | The consolidation level of the invoice. Allowed Values: none, parent, child or comma-separated lists of thereof, e.g. none,parent. |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query `per_page=200`.
**Default**: `20`
**Constraints**: `<= 200` |
| `direction` | [`Direction`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/direction) | Query, Optional | The sort direction of the returned invoices.
**Default**: `desc` |
| `line_items` | `Boolean` | Query, Optional | Include line items data.
**Default**: `false` |
| `date_field` | [`Invoice Date Field`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/invoice-date-field) | Query, Optional | The type of filter you would like to apply to your search. Use in query `date_field=issue_date`.
**Default**: `due_date` |
| `start_datetime` | `String` | Query, Optional | The start date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns invoices with a timestamp at or after exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of start_date. Allowed to be used only along with date_field set to created_at or updated_at. |
| `end_datetime` | `String` | Query, Optional | The end date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns invoices with a timestamp at or before exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of end_date. Allowed to be used only along with date_field set to created_at or updated_at. |
| `customer_ids` | `array` | Query, Optional | Allows fetching invoices with matching customer id based on provided values. Use in query `customer_ids=1,2,3`. |
| `number` | `array` | Query, Optional | Allows fetching invoices with matching invoice number based on provided values. Use in query `number=1234,1235`. |
| `product_ids` | `array` | Query, Optional | Allows fetching invoices with matching line items product ids based on provided values. Use in query `product_ids=23,34`. |
| `sort` | [`Invoice Sort Field`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/invoice-sort-field) | Query, Optional | Allows specification of the order of the returned list. Use in query `sort=total_amount`.
**Default**: `number` |
# Response Type
**200**: OK
[`List Invoices Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/list-invoices-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/invoices.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'page=1' \
-d 'per_page=50' \
-d 'direction=desc' \
-d 'line_items=false' \
-d 'discounts=false' \
-d 'taxes=false' \
-d 'credits=false' \
-d 'payments=false' \
-d 'custom_fields=false' \
-d 'refunds=false' \
-d 'date_field=issue_date' \
-d 'customer_ids=1%2C2%2C3' \
-d 'number=1234%2C1235' \
-d 'product_ids=23%2C34' \
-d 'sort=total_amount'
```
# Example Response *(as JSON)*
```json
{
"invoices": [
{
"uid": "inv_8htcd29wcq3q6",
"site_id": 51288,
"customer_id": 20153415,
"subscription_id": 23277588,
"number": "125",
"sequence_number": 125,
"issue_date": "2018-09-20",
"due_date": "2018-09-20",
"paid_date": "2018-09-20",
"status": "paid",
"collection_method": "automatic",
"payment_instructions": "Make checks payable to Acme, Inc.",
"currency": "USD",
"consolidation_level": "parent",
"parent_invoice_uid": null,
"parent_invoice_number": null,
"group_primary_subscription_id": 23277588,
"product_name": "Trial and setup fee",
"product_family_name": "Billing Plans",
"seller": {
"name": "General Goods",
"address": {
"street": "123 General Goods Way",
"line2": "Apt. 10",
"city": "Boston",
"state": "MA",
"zip": "02120",
"country": "US"
},
"phone": "555-555-1212"
},
"customer": {
"chargify_id": 20153415,
"first_name": "Meg",
"last_name": "Example",
"organization": "",
"email": "meg@example.com"
},
"memo": "Payment due within 15 days of receipt.",
"billing_address": {
"street": "123 I Love Cats Way",
"line2": "",
"city": "Boston",
"state": "MA",
"zip": "90210",
"country": "US"
},
"shipping_address": {
"street": "123 I Love Cats Way",
"line2": "",
"city": "Boston",
"state": "MA",
"zip": "90210",
"country": "US"
},
"subtotal_amount": "100.0",
"discount_amount": "0.0",
"tax_amount": "0.0",
"total_amount": "100.0",
"credit_amount": "0.0",
"paid_amount": "100.0",
"refund_amount": "0.0",
"due_amount": "0.0",
"public_url": "https://www.chargifypay.com/invoice/inv_8htcd29wcq3q6?token=n9fr5fxff5v74c7h9srg3cwd"
},
{
"uid": "inv_8hr3546xp4h8n",
"site_id": 51288,
"customer_id": 21687686,
"subscription_id": 22007644,
"number": "124",
"sequence_number": 124,
"issue_date": "2018-09-18",
"due_date": "2018-09-18",
"paid_date": null,
"status": "open",
"collection_method": "remittance",
"payment_instructions": "Make checks payable to Acme, Inc.",
"currency": "USD",
"consolidation_level": "none",
"parent_invoice_uid": null,
"parent_invoice_number": null,
"group_primary_subscription_id": null,
"product_name": "Trial and setup fee",
"product_family_name": "Billing Plans",
"seller": {
"name": "General Goods",
"address": {
"street": "123 General Goods Way",
"line2": "Apt. 10",
"city": "Boston",
"state": "MA",
"zip": "02120",
"country": "US"
},
"phone": "555-555-1212"
},
"customer": {
"chargify_id": 21687686,
"first_name": "Charlene",
"last_name": "Tester",
"organization": "",
"email": "food@example.com"
},
"memo": "Payment due within 15 days of receipt.",
"billing_address": {
"street": "",
"line2": "",
"city": "",
"state": "",
"zip": "",
"country": ""
},
"shipping_address": {
"street": "",
"line2": "",
"city": "",
"state": "",
"zip": "",
"country": ""
},
"subtotal_amount": "100.0",
"discount_amount": "0.0",
"tax_amount": "0.0",
"total_amount": "100.0",
"credit_amount": "0.0",
"paid_amount": "0.0",
"refund_amount": "0.0",
"due_amount": "100.0",
"public_url": "https://www.chargifypay.com/invoice/inv_8hr3546xp4h8n?token=n9fr5fxff5v74c7h9srg3cwd"
},
{
"uid": "inv_8hr3546wdwxkr",
"site_id": 51288,
"customer_id": 21687670,
"subscription_id": 22007627,
"number": "123",
"sequence_number": 123,
"issue_date": "2018-09-18",
"due_date": "2018-09-18",
"paid_date": "2018-09-18",
"status": "paid",
"collection_method": "automatic",
"payment_instructions": "Make checks payable to Acme, Inc.",
"currency": "USD",
"consolidation_level": "none",
"parent_invoice_uid": null,
"parent_invoice_number": null,
"group_primary_subscription_id": null,
"product_name": "Trial End - Free",
"product_family_name": "Billing Plans",
"seller": {
"name": "General Goods",
"address": {
"street": "123 General Goods Way",
"line2": "Apt. 10",
"city": "Boston",
"state": "MA",
"zip": "02120",
"country": "US"
},
"phone": "555-555-1212"
},
"customer": {
"chargify_id": 21687670,
"first_name": "Hello",
"last_name": "World",
"organization": "123",
"email": "example@example.com"
},
"memo": "Payment due within 15 days of receipt.",
"billing_address": {
"street": "123 Anywhere Street",
"line2": "",
"city": "Boston",
"state": "MA",
"zip": "02120",
"country": "US"
},
"shipping_address": {
"street": "",
"line2": "",
"city": "Boston",
"state": "AL",
"zip": "02120",
"country": "US"
},
"subtotal_amount": "0.0",
"discount_amount": "0.0",
"tax_amount": "0.0",
"total_amount": "0.0",
"credit_amount": "0.0",
"paid_amount": "0.0",
"refund_amount": "0.0",
"due_amount": "0.0",
"public_url": "https://www.chargifypay.com/invoice/inv_8hr3546wdwxkr?token=n9fr5fxff5v74c7h9srg3cwd"
},
{
"uid": "inv_8hjtk8bz56bbp",
"site_id": 51288,
"customer_id": 20137757,
"subscription_id": 20541100,
"number": "122",
"sequence_number": 122,
"issue_date": "2018-09-10",
"due_date": "2018-09-10",
"paid_date": "2018-09-10",
"status": "paid",
"collection_method": "automatic",
"payment_instructions": "Make checks payable to Acme, Inc.",
"currency": "USD",
"consolidation_level": "none",
"parent_invoice_uid": null,
"parent_invoice_number": null,
"group_primary_subscription_id": null,
"product_name": "$0 Product",
"product_family_name": "Billing Plans",
"seller": {
"name": "General Goods",
"address": {
"street": "123 General Goods Way",
"line2": "Apt. 10",
"city": "Boston",
"state": "MA",
"zip": "02120",
"country": "US"
},
"phone": "555-555-1212"
},
"customer": {
"chargify_id": 20137757,
"first_name": "Sasha",
"last_name": "Example",
"organization": "",
"email": "example@example.com"
},
"memo": "Payment due within 15 days of receipt.",
"billing_address": {
"street": "123 I Love Cats Way",
"line2": "",
"city": "Catville",
"state": "MA",
"zip": "90210",
"country": "US"
},
"shipping_address": {
"street": "123 I Love Cats Way",
"line2": "",
"city": "Catville",
"state": "AL",
"zip": "90210",
"country": "US"
},
"subtotal_amount": "0.0",
"discount_amount": "0.0",
"tax_amount": "0.0",
"total_amount": "0.0",
"credit_amount": "0.0",
"paid_amount": "0.0",
"refund_amount": "0.0",
"due_amount": "0.0",
"public_url": "https://www.chargifypay.com/invoice/inv_8hjtk8bz56bbp?token=fb6kpjz5rcr2vttyjs4rcv6y"
}
]
}
```
##### Read Invoice
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/invoices/read-invoice
Returns the details for an invoice.
## PDF Invoice retrieval
Individual PDF Invoices can be retrieved by using the "Accept" header application/pdf or appending .pdf as the format portion of the URL:
```curl -u :x -H
Accept:application/pdf -H
https://acme.chargify.com/invoices/inv_8gd8tdhtd3hgr.pdf > output_file.pdf
URL: `https://.chargify.com/invoices/.`
Method: GET
Required parameters: `uid`
Response: A single Invoice.
```
```http
GET /invoices/{uid}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `uid` | `String` | Template, Required | The unique identifier for the invoice, this does not refer to the public facing invoice number. |
# Response Type
**200**: OK
[`Invoice`](https://developers.maxio.com/http/advanced-billing-api/models/structures/invoice)
# Example Usage
```bash
curl -X GET \
--url 'https://subdomain.chargify.com/invoices/uid0.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"uid": "inv_8gd8tdhtd3hgr",
"site_id": 51288,
"customer_id": 20194505,
"subscription_id": 20597774,
"number": "117",
"sequence_number": 117,
"issue_date": "2018-07-26",
"due_date": "2018-07-26",
"paid_date": "2018-07-26",
"status": "paid",
"collection_method": "automatic",
"payment_instructions": "Make checks payable to Acme, Inc.",
"currency": "USD",
"consolidation_level": "none",
"parent_invoice_uid": null,
"parent_invoice_number": null,
"group_primary_subscription_id": null,
"product_name": "Monthly Product",
"product_family_name": "Billing Plans",
"seller": {
"name": "General Goods",
"address": {
"street": "123 General Goods Way",
"line2": "Apt. 10",
"city": "Boston",
"state": "MA",
"zip": "02120",
"country": "US"
},
"phone": "555-555-1212"
},
"customer": {
"chargify_id": 20194505,
"first_name": "Joe",
"last_name": "Example",
"organization": null,
"email": "joe@example.com"
},
"memo": "Payment due within 15 days of receipt.",
"billing_address": {
"street": null,
"line2": null,
"city": null,
"state": null,
"zip": null,
"country": null
},
"shipping_address": {
"street": null,
"line2": null,
"city": null,
"state": null,
"zip": null,
"country": null
},
"subtotal_amount": "100.0",
"discount_amount": "0.0",
"tax_amount": "0.0",
"total_amount": "100.0",
"credit_amount": "0.0",
"paid_amount": "100.0",
"refund_amount": "0.0",
"due_amount": "0.0",
"line_items": [
{
"uid": "li_8gd8tdhhgk55k",
"title": "Monthly Product",
"description": "Jul 26, 2018 - Aug 26, 2018",
"quantity": "1.0",
"unit_price": "100.0",
"subtotal_amount": "100.0",
"discount_amount": "0.0",
"tax_amount": "0.0",
"tax_included": false,
"total_amount": "100.0",
"tiered_unit_price": false,
"period_range_start": "2018-07-26",
"period_range_end": "2018-08-26",
"product_id": 4607632,
"product_version": 1,
"component_id": null,
"price_point_id": null
}
],
"payments": [
{
"transaction_time": "2018-07-26T15:22:02Z",
"memo": "Joe Example - Monthly Product: Renewal payment",
"original_amount": "100.0",
"applied_amount": "100.0",
"payment_method": {
"card_brand": "bogus",
"card_expiration": "10/2020",
"last_four": null,
"masked_card_number": "XXXX-XXXX-XXXX-1",
"type": "credit_card"
},
"transaction_id": 253028955,
"prepayment": false,
"received_on": "2018-07-26"
}
],
"public_url": "https://www.chargifypay.com/invoice/inv_8jzrw74xq8kxr?token=fb6kpjz5rcr2vttyjs4rcv6y"
}
```
##### List Invoice Events
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/invoices/list-invoice-events
Lists invoice events for a site. Each event contains event "data" (such as an applied payment) as well as a snapshot of the `invoice` at the time of event completion.
Exposed event types are:
+ issue_invoice
+ apply_credit_note
+ apply_payment
+ refund_invoice
+ void_invoice
+ void_remainder
+ backport_invoice
+ change_invoice_status
+ change_invoice_collection_method
+ remove_payment
+ failed_payment
+ apply_debit_note
+ create_debit_note
+ change_chargeback_status
Invoice events are returned in ascending order.
If both a `since_date` and `since_id` are provided in request parameters, the `since_date` will be used.
Note - invoice events that occurred prior to 09/05/2018 __will not__ contain an `invoice` snapshot.
```http
GET /invoices/events.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `since_date` | `String` | Query, Optional | The timestamp in a format `YYYY-MM-DD T HH:MM:SS Z`, or `YYYY-MM-DD`(in this case, it returns data from the beginning of the day). of the event from which you want to start the search. All the events before the `since_date` timestamp are not returned in the response. |
| `since_id` | `Long` | Query, Optional | The ID of the event from which you want to start the search(ID is not included. e.g. if ID is set to 2, then all events with ID 3 and more will be shown) This parameter is not used if since_date is defined. |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 100. The maximum allowed values is 200; any per_page value over 200 will be changed to 200.
**Default**: `100` |
| `invoice_uid` | `String` | Query, Optional | Providing an invoice_uid allows for scoping of the invoice events to a single invoice or credit note. |
| `with_change_invoice_status` | `String` | Query, Optional | Use this parameter if you want to fetch also invoice events with change_invoice_status type. |
| `event_types` | [`array`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/invoice-event-type) | Query, Optional | Filter results by event_type. Supply a comma separated list of event types (listed above). Use in query: `event_types=void_invoice,void_remainder`. |
# Response Type
**200**: OK
[`List Invoice Events Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/list-invoice-events-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/invoices/events.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'page=1' \
-d 'per_page=100'
```
# Example Response *(as JSON)*
```json
{
"events": [
{
"id": 83,
"event_type": "apply_payment",
"event_data": {
"memo": "Non-Resumable Canceled On Purpose - Standard Plan: Renewal payment",
"original_amount": "168.61",
"applied_amount": "168.61",
"transaction_time": "2018-08-01T16:00:00Z",
"payment_method": {
"card_brand": "visa",
"card_expiration": "12/2022",
"last_four": null,
"masked_card_number": "XXXX-XXXX-XXXX-1111",
"type": "credit_card"
},
"consolidation_level": "none"
},
"timestamp": "2018-08-01T16:00:00Z",
"invoice": {
"id": 614942008934401500,
"uid": "inv_8gk5bwkct3gqt",
"site_id": 20,
"customer_id": 6,
"subscription_id": 10,
"number": "25",
"sequence_number": 25,
"transaction_time": "2018-08-01T16:00:00Z",
"created_at": "2018-08-01T16:00:00Z",
"updated_at": "2018-08-01T16:00:00Z",
"issue_date": "2018-08-01",
"due_date": "2018-08-01",
"paid_date": "2018-08-01",
"status": "paid",
"role": "renewal",
"collection_method": "automatic",
"payment_instructions": "Please make checks payable to \"Acme, Inc.\"",
"currency": "USD",
"consolidation_level": "none",
"parent_invoice_id": null,
"subscription_group_id": null,
"parent_invoice_number": null,
"product_name": "Standard Plan",
"product_family_name": "Cloud Compute Servers",
"seller": {
"name": "Acme, Inc.",
"address": {
"street": null,
"line2": null,
"city": null,
"state": null,
"zip": null,
"country": null
},
"phone": "555-555-1234 x137",
"logo_url": null
},
"customer": {
"chargify_id": 6,
"first_name": "Non-Resumable",
"last_name": "Canceled On Purpose",
"organization": null,
"email": "evan4@example.com"
},
"payer": {
"chargify_id": 6,
"first_name": "Non-Resumable",
"last_name": "Canceled On Purpose",
"organization": null,
"email": "evan4@example.com"
},
"net_terms": 0,
"memo": "Thanks for your business! If you have any questions, please contact your account manager.",
"billing_address": {
"street": "200 Billing Rd.",
"line2": "Suite 100",
"city": "Needham",
"state": "MA",
"zip": "02494",
"country": "US"
},
"shipping_address": {
"street": "100 Shipping St.",
"line2": "Apt 200",
"city": "Pleasantville",
"state": "NC",
"zip": "12345",
"country": "US"
},
"line_items": [
{
"uid": "li_8gk5bwkct3gqk",
"title": "Standard Plan",
"description": "08/01/2018 - 09/01/2018",
"quantity": "1.0",
"unit_price": "99.0",
"subtotal_amount": "99.0",
"discount_amount": "9.9",
"tax_amount": "6.01425",
"tax_included": false,
"total_amount": "95.11425",
"tiered_unit_price": false,
"period_range_start": "2018-08-01",
"period_range_end": "2018-09-01",
"transaction_id": 120,
"product_id": 84,
"product_version": 1,
"component_id": null,
"price_point_id": null,
"hide": false
},
{
"uid": "li_8gk5bwkct3gqm",
"title": "Small Instance (Hourly)",
"description": "07/22/2018 - 08/01/2018",
"quantity": "162.0",
"unit_price": "0.09567901",
"subtotal_amount": "15.5",
"discount_amount": "1.55",
"tax_amount": "0.941625",
"tax_included": false,
"total_amount": "14.891625",
"tiered_unit_price": true,
"period_range_start": "2018-07-22",
"period_range_end": "2018-08-01",
"transaction_id": 121,
"product_id": 84,
"product_version": 1,
"component_id": 76,
"price_point_id": null,
"hide": false,
"component_cost_data": {
"rates": [
{
"component_code_id": null,
"price_point_id": 160,
"product_id": 84,
"quantity": "162.0",
"amount": "15.5",
"pricing_scheme": "tiered",
"tiers": [
{
"starting_quantity": 1,
"ending_quantity": 100,
"quantity": "100.0",
"unit_price": "0.0",
"amount": "0.0"
},
{
"starting_quantity": 101,
"ending_quantity": null,
"quantity": "62.0",
"unit_price": "0.25",
"amount": "15.5"
}
]
}
]
}
},
{
"uid": "li_8gk5bwkct3gqn",
"title": "Large Instance (Hourly)",
"description": "07/22/2018 - 08/01/2018",
"quantity": "194.0",
"unit_price": "0.24226804",
"subtotal_amount": "47.0",
"discount_amount": "4.7",
"tax_amount": "2.85525",
"tax_included": false,
"total_amount": "45.15525",
"tiered_unit_price": true,
"period_range_start": "2018-07-22",
"period_range_end": "2018-08-01",
"transaction_id": 122,
"product_id": 84,
"product_version": 1,
"component_id": 77,
"price_point_id": null,
"hide": false,
"component_cost_data": {
"rates": [
{
"component_code_id": null,
"price_point_id": 161,
"product_id": 84,
"quantity": "194.0",
"amount": "47.0",
"pricing_scheme": "tiered",
"tiers": [
{
"starting_quantity": 1,
"ending_quantity": 100,
"quantity": "100.0",
"unit_price": "0.0",
"amount": "0.0"
},
{
"starting_quantity": 101,
"ending_quantity": null,
"quantity": "94.0",
"unit_price": "0.5",
"amount": "47.0"
}
]
}
]
}
},
{
"uid": "li_8gk5bwkct3gqp",
"title": "IP Addresses",
"description": "08/01/2018 - 09/01/2018",
"quantity": "7.0",
"unit_price": "2.0",
"subtotal_amount": "14.0",
"discount_amount": "1.4",
"tax_amount": "0.8505",
"tax_included": false,
"total_amount": "13.4505",
"tiered_unit_price": false,
"period_range_start": "2018-08-01",
"period_range_end": "2018-09-01",
"transaction_id": 123,
"product_id": 84,
"product_version": 1,
"component_id": 79,
"price_point_id": 163,
"hide": false,
"component_cost_data": {
"rates": [
{
"component_code_id": null,
"price_point_id": 163,
"product_id": 84,
"quantity": "7.0",
"amount": "14.0",
"pricing_scheme": "per_unit",
"tiers": [
{
"starting_quantity": 1,
"ending_quantity": null,
"quantity": "7.0",
"unit_price": "2.0",
"amount": "14.0"
}
]
}
]
}
}
],
"subtotal_amount": "175.5",
"discount_amount": "17.55",
"discounts": [
{
"uid": "dli_8gk5bwkct3gqq",
"title": "Multi-service discount (10%)",
"description": null,
"code": "MULTI3",
"source_type": "Coupon",
"source_id": 40,
"discount_type": "percentage",
"percentage": "10.0",
"eligible_amount": "175.5",
"discount_amount": "17.55",
"transaction_id": 124,
"line_item_breakouts": [
{
"uid": "li_8gk5bwkct3gqk",
"eligible_amount": "99.0",
"discount_amount": "9.9"
},
{
"uid": "li_8gk5bwkct3gqm",
"eligible_amount": "15.5",
"discount_amount": "1.55"
},
{
"uid": "li_8gk5bwkct3gqn",
"eligible_amount": "47.0",
"discount_amount": "4.7"
},
{
"uid": "li_8gk5bwkct3gqp",
"eligible_amount": "14.0",
"discount_amount": "1.4"
}
]
}
],
"tax_amount": "10.66",
"taxes": [
{
"uid": "tli_8gk5bwkct3gqr",
"title": "NC Sales Tax",
"description": null,
"source_type": "Tax",
"source_id": 1,
"percentage": "6.75",
"taxable_amount": "157.95",
"tax_amount": "10.66",
"transaction_id": 125,
"line_item_breakouts": [
{
"uid": "li_8gk5bwkct3gqk",
"taxable_amount": "89.1",
"tax_amount": "6.01425"
},
{
"uid": "li_8gk5bwkct3gqm",
"taxable_amount": "13.95",
"tax_amount": "0.941625"
},
{
"uid": "li_8gk5bwkct3gqn",
"taxable_amount": "42.3",
"tax_amount": "2.85525"
},
{
"uid": "li_8gk5bwkct3gqp",
"taxable_amount": "12.6",
"tax_amount": "0.8505"
}
],
"tax_component_breakouts": [
{
"tax_rule_id": 1,
"percentage": "6.75",
"country_code": "US",
"subdivision_code": "NC",
"tax_amount": "10.66",
"taxable_amount": "157.95",
"tax_exempt_amount": "0.0",
"non_taxable_amount": "0.0",
"tax_name": "NC STATE TAX",
"tax_type": "Sales",
"rate_type": "General",
"tax_authority_type": 45,
"state_assigned_no": "",
"tax_sub_type": "S"
}
],
"eu_vat": false,
"type": "Sales",
"tax_exempt_amount": "0.0"
}
],
"credit_amount": "0.0",
"refund_amount": "0.0",
"total_amount": "168.61",
"paid_amount": "168.61",
"due_amount": "0.0",
"payments": [
{
"memo": "Non-Resumable Canceled On Purpose - Standard Plan: Renewal payment",
"original_amount": "168.61",
"applied_amount": "168.61",
"transaction_time": "2018-08-01T16:00:00Z",
"payment_method": {
"card_brand": "visa",
"card_expiration": "12/2022",
"last_four": null,
"masked_card_number": "XXXX-XXXX-XXXX-1111",
"type": "credit_card"
},
"transaction_id": 126,
"prepayment": false
}
],
"display_settings": {
"hide_zero_subtotal_lines": false,
"include_discounts_on_lines": false
}
}
}
],
"page": 48,
"per_page": 1,
"total_pages": 102
}
```
##### Record Payment for Invoice
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/invoices/record-payment-for-invoice
Applies a payment of a given type against a specific invoice. If you would like to apply a payment across multiple invoices, you can use the [Record Payment for Multiple Invoices](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/invoices/record-payment-for-multiple-invoices) endpoint.
```http
POST /invoices/{uid}/payments.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `uid` | `String` | Template, Required | The unique identifier for the invoice, this does not refer to the public facing invoice number. |
| `body` | [`Create Invoice Payment Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/create-invoice-payment-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Invoice`](https://developers.maxio.com/http/advanced-billing-api/models/structures/invoice)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/invoices/uid0/payments.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"payment": {
"amount": 124.33,
"memo": "for John Smith",
"method": "check",
"details": "#0102"
}
}'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Record Payment for Multiple Invoices
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/invoices/record-payment-for-multiple-invoices
Records an external payment against multiple invoices.
To apply a payment to multiple invoices, at minimum, specify the `amount` and `applications` (i.e., `invoice_uid` and `amount`) details.
Note that the invoice payment amounts must be greater than 0. Total amount must be greater or equal to invoices payment amount sum.
```http
POST /invoices/payments.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `body` | [`Create Multi Invoice Payment Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/create-multi-invoice-payment-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Multi Invoice Payment Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/multi-invoice-payment-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/invoices/payments.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"payment": {
"memo": "to pay the bills",
"details": "check number 8675309",
"method": "check",
"amount": "100.00",
"applications": [
{
"invoice_uid": "inv_8gk5bwkct3gqt",
"amount": "50.00"
},
{
"invoice_uid": "inv_7bc6bwkct3lyt",
"amount": "50.00"
}
]
}
}'
```
# Example Response *(as JSON)*
```json
{
"payment": {
"transaction_id": 1,
"total_amount": "100.00",
"currency_code": "USD",
"applications": [
{
"invoice_uid": "inv_8gk5bwkct3gqt",
"application_uid": "pmt_1tr0hgsct3ybx",
"applied_amount": "50.00"
},
{
"invoice_uid": "inv_7bc6bwkct3lyt",
"application_uid": "pmt_2",
"applied_amount": "50.00"
}
]
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### List Credit Notes
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/invoices/list-credit-notes
Lists credit notes for a site. Credit Notes are like inverse invoices. They reduce the amount a customer owes.
By default, the credit notes returned by this endpoint will exclude the arrays of `line_items`, `discounts`, `taxes`, `applications`, or `refunds`. To include these arrays, pass the specific field as a key in the query with a value set to `true`.
```http
GET /credit_notes.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Query, Optional | The subscription's Advanced Billing id |
| `date_field` | [`Credit Note Date Field`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/credit-note-date-field) | Query, Optional | The type of filter you would like to apply to your search. Use in query `date_field=issue_date`. If a date range is provided without an explicit `date_field`, it defaults to `issue_date`. If only `start_datetime`/`end_datetime` are provided without an explicit `date_field`, it defaults to `created_at` instead. An unrecognized `date_field` is ignored rather than raising an error.
**Default**: `issue_date` |
| `start_date` | `String` | Query, Optional | The start date (format YYYY-MM-DD) with which to filter the date_field. Returns credit notes with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified. |
| `end_date` | `String` | Query, Optional | The end date (format YYYY-MM-DD) with which to filter the date_field. Returns credit notes with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified. |
| `start_datetime` | `String` | Query, Optional | The start date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns credit notes with a timestamp at or after exact time provided in query. If provided, this parameter will be used instead of start_date. If no timezone offset is included in the value, it is interpreted as UTC. Allowed to be used only along with date_field set to created_at or updated_at. |
| `end_datetime` | `String` | Query, Optional | The end date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns credit notes with a timestamp at or before exact time provided in query. If provided, this parameter will be used instead of end_date. If no timezone offset is included in the value, it is interpreted as UTC. Allowed to be used only along with date_field set to created_at or updated_at. |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query `per_page=200`.
**Default**: `20`
**Constraints**: `<= 200` |
| `direction` | [`Direction`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/direction) | Query, Optional | The sort direction of the returned credit notes, sorted by sequence_number.
**Default**: `desc` |
| `line_items` | `Boolean` | Query, Optional | Include line items data.
**Default**: `false` |
# Response Type
**200**: OK
[`List Credit Notes Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/list-credit-notes-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/credit_notes.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'date_field=issue_date' \
-d 'page=1' \
-d 'per_page=50' \
-d 'direction=desc' \
-d 'line_items=false' \
-d 'discounts=false' \
-d 'taxes=false' \
-d 'refunds=false' \
-d 'applications=false'
```
# Example Response *(as JSON)*
```json
{
"credit_notes": [
{
"uid": "cn_8m9vbd5kkv7kr",
"site_id": 20,
"customer_id": 3,
"subscription_id": 2,
"number": "77",
"sequence_number": 78,
"issue_date": "2018-12-31",
"applied_date": "2018-12-31",
"status": "applied",
"currency": "USD",
"memo": "Refund for overpayment",
"seller": {
"name": "Acme, Inc.",
"address": {
"street": "122 E Houston St",
"line2": "Suite 105",
"city": "San Antonio",
"state": "TX",
"zip": "78205",
"country": "US"
},
"phone": "555-555-1234 x137"
},
"customer": {
"chargify_id": 3,
"first_name": "Marty",
"last_name": "McFly",
"organization": "Time Travellers, Inc.",
"email": "timetraveller1985@example.com",
"reference": null
},
"billing_address": {
"street": "200 Billing Rd.",
"line2": "Suite 100",
"city": "Needham",
"state": "MA",
"zip": "02494",
"country": "US"
},
"shipping_address": {
"street": "100 Shipping St.",
"line2": "Apt 200",
"city": "Pleasantville",
"state": "NC",
"zip": "12345",
"country": "US"
},
"subtotal_amount": "208.69341779",
"discount_amount": "20.87125167",
"tax_amount": "12.67783387",
"total_amount": "200.5",
"applied_amount": "200.5",
"remaining_amount": "0.0",
"line_items": [
{
"uid": "cnli_8k5jvdzct4h9x",
"title": "IP Addresses: 5 to 10 addresses",
"description": "38.2% credit",
"quantity": "0.9855",
"unit_price": "2.0",
"subtotal_amount": "1.971004",
"discount_amount": "0.19862831",
"tax_amount": "0.11963536",
"tax_included": false,
"total_amount": "1.89201105",
"tiered_unit_price": false,
"period_range_start": "2018-11-30",
"period_range_end": "2018-11-30",
"product_id": 85,
"product_version": 1,
"component_id": 81,
"price_point_id": 165
},
{
"uid": "cnli_8kjttvjcjx8b4",
"title": "Professional Plan",
"description": "38.2% credit",
"quantity": "0.382",
"unit_price": "299.0",
"subtotal_amount": "114.21127834",
"discount_amount": "11.42112783",
"tax_amount": "6.93833516",
"tax_included": false,
"total_amount": "109.72848567",
"tiered_unit_price": false,
"period_range_start": "2018-12-30",
"period_range_end": "2018-12-30",
"product_id": 85,
"product_version": 1,
"component_id": null,
"price_point_id": null
},
{
"uid": "cnli_8kjttvjknzhx7",
"title": "Small Instance (Hourly)",
"description": "38.2% credit",
"quantity": "74.8676",
"unit_price": "0.12244898",
"subtotal_amount": "9.16746047",
"discount_amount": "0.91674605",
"tax_amount": "0.55692322",
"tax_included": false,
"total_amount": "8.80763764",
"tiered_unit_price": true,
"period_range_start": "2018-11-30",
"period_range_end": "2018-11-30",
"product_id": 85,
"product_version": 1,
"component_id": 78,
"price_point_id": null
},
{
"uid": "cnli_8kjttvjnmh25w",
"title": "Large Instance (Hourly)",
"description": "38.2% credit",
"quantity": "183.3492",
"unit_price": "0.39583333",
"subtotal_amount": "72.57572871",
"discount_amount": "7.25757287",
"tax_amount": "4.40897552",
"tax_included": false,
"total_amount": "69.72713136",
"tiered_unit_price": true,
"period_range_start": "2018-11-30",
"period_range_end": "2018-11-30",
"product_id": 85,
"product_version": 1,
"component_id": 79,
"price_point_id": null
},
{
"uid": "cnli_8kjttvjqn86kc",
"title": "Email Messages",
"description": "38.2% credit",
"quantity": "10076.9489",
"unit_price": "0.00031045",
"subtotal_amount": "3.12839588",
"discount_amount": "0.31322157",
"tax_amount": "0.19002427",
"tax_included": false,
"total_amount": "3.00519858",
"tiered_unit_price": true,
"period_range_start": "2018-11-30",
"period_range_end": "2018-11-30",
"product_id": 85,
"product_version": 1,
"component_id": 80,
"price_point_id": null
},
{
"uid": "cnli_8kjttvjtxxbdd",
"title": "IP Addresses",
"description": "38.2% credit",
"quantity": "3.8198",
"unit_price": "2.0",
"subtotal_amount": "7.63955039",
"discount_amount": "0.76395504",
"tax_amount": "0.46410269",
"tax_included": false,
"total_amount": "7.33969804",
"tiered_unit_price": false,
"period_range_start": "2018-12-30",
"period_range_end": "2018-12-30",
"product_id": 85,
"product_version": 1,
"component_id": 81,
"price_point_id": 165
}
],
"discounts": [
{
"uid": "cndli_8k5jvdzct4h9y",
"title": "Multi-service discount (10%)",
"code": "MULTI3",
"source_type": "Coupon",
"source_id": 40,
"discount_type": "percentage",
"percentage": "10.0",
"eligible_amount": "208.69341779",
"discount_amount": "20.87125167",
"line_item_breakouts": [
{
"uid": "cnli_8k5jvdzct4h9x",
"eligible_amount": "1.971004",
"discount_amount": "0.19862831"
},
{
"uid": "cnli_8kjttvjcjx8b4",
"eligible_amount": "114.21127834",
"discount_amount": "11.42112783"
},
{
"uid": "cnli_8kjttvjknzhx7",
"eligible_amount": "9.16746047",
"discount_amount": "0.91674605"
},
{
"uid": "cnli_8kjttvjnmh25w",
"eligible_amount": "72.57572871",
"discount_amount": "7.25757287"
},
{
"uid": "cnli_8kjttvjqn86kc",
"eligible_amount": "3.12839588",
"discount_amount": "0.31322157"
},
{
"uid": "cnli_8kjttvjtxxbdd",
"eligible_amount": "7.63955039",
"discount_amount": "0.76395504"
}
]
}
],
"taxes": [
{
"uid": "cntli_8k5jvdzct4h9z",
"title": "NC Sales Tax",
"source_type": "Tax",
"source_id": 1,
"percentage": "6.75",
"taxable_amount": "187.82216613",
"tax_amount": "12.67783387",
"line_item_breakouts": [
{
"uid": "cnli_8k5jvdzct4h9x",
"taxable_amount": "1.77237569",
"tax_amount": "0.11963536"
},
{
"uid": "cnli_8kjttvjcjx8b4",
"taxable_amount": "102.7901505",
"tax_amount": "6.93833516"
},
{
"uid": "cnli_8kjttvjknzhx7",
"taxable_amount": "8.25071442",
"tax_amount": "0.55692322"
},
{
"uid": "cnli_8kjttvjnmh25w",
"taxable_amount": "65.31815584",
"tax_amount": "4.40897552"
},
{
"uid": "cnli_8kjttvjqn86kc",
"taxable_amount": "2.81517432",
"tax_amount": "0.19002427"
},
{
"uid": "cnli_8kjttvjtxxbdd",
"taxable_amount": "6.87559535",
"tax_amount": "0.46410269"
}
],
"tax_component_breakouts": [
{
"tax_rule_id": 1,
"percentage": "6.75",
"country_code": "US",
"subdivision_code": "NC",
"tax_amount": "10.66",
"taxable_amount": "157.95",
"tax_exempt_amount": "0.0",
"non_taxable_amount": "0.0",
"tax_name": "NC STATE TAX",
"tax_type": "Sales",
"rate_type": "General",
"tax_authority_type": 45,
"state_assigned_no": "",
"tax_sub_type": "S"
}
],
"eu_vat": false,
"type": "Sales",
"tax_exempt_amount": "0.0"
}
],
"applications": [
{
"uid": "cdt_8m9vbdbdwd28n",
"transaction_time": "2018-12-31T21:19:28Z",
"invoice_uid": "inv_8k5jvdzct4hb2",
"memo": "Refund for overpayment",
"applied_amount": "200.5"
}
],
"refunds": [
{
"transaction_id": 329,
"payment_id": 39,
"memo": "Refund for overpayment",
"original_amount": "524.9",
"applied_amount": "200.5"
}
]
}
]
}
```
##### Read Credit Note
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/invoices/read-credit-note
Returns the details for a credit note.
```http
GET /credit_notes/{uid}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `uid` | `String` | Template, Required | The unique identifier of the credit note |
# Response Type
**200**: OK
[`Credit Note`](https://developers.maxio.com/http/advanced-billing-api/models/structures/credit-note)
# Example Usage
```bash
curl -X GET \
--url 'https://subdomain.chargify.com/credit_notes/uid0.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"uid": "cn_8m9vbd5kkv7kr",
"site_id": 20,
"customer_id": 3,
"subscription_id": 2,
"number": "77",
"sequence_number": 78,
"issue_date": "2018-12-31",
"applied_date": "2018-12-31",
"status": "applied",
"currency": "USD",
"memo": "Refund for overpayment",
"seller": {
"name": "Acme, Inc.",
"address": {
"street": "122 E Houston St",
"line2": "Suite 105",
"city": "San Antonio",
"state": "TX",
"zip": "78205",
"country": "US"
},
"phone": "555-555-1234 x137"
},
"customer": {
"chargify_id": 3,
"first_name": "Marty",
"last_name": "McFly",
"organization": "Time Travellers, Inc.",
"email": "timetraveller1985@example.com",
"reference": null
},
"billing_address": {
"street": "200 Billing Rd.",
"line2": "Suite 100",
"city": "Needham",
"state": "MA",
"zip": "02494",
"country": "US"
},
"shipping_address": {
"street": "100 Shipping St.",
"line2": "Apt 200",
"city": "Pleasantville",
"state": "NC",
"zip": "12345",
"country": "US"
},
"subtotal_amount": "208.69341779",
"discount_amount": "20.87125167",
"tax_amount": "12.67783387",
"total_amount": "200.5",
"applied_amount": "200.5",
"remaining_amount": "0.0",
"line_items": [
{
"uid": "cnli_8k5jvdzct4h9x",
"title": "IP Addresses: 5 to 10 addresses",
"description": "38.2% credit",
"quantity": "0.9855",
"unit_price": "2.0",
"subtotal_amount": "1.971004",
"discount_amount": "0.19862831",
"tax_amount": "0.11963536",
"tax_included": false,
"total_amount": "1.89201105",
"tiered_unit_price": false,
"period_range_start": "2018-11-30",
"period_range_end": "2018-11-30",
"product_id": 85,
"product_version": 1,
"component_id": 81,
"price_point_id": 165,
"billing_schedule_item_id": null,
"custom_item": false
},
{
"uid": "cnli_8kjttvjcjx8b4",
"title": "Professional Plan",
"description": "38.2% credit",
"quantity": "0.382",
"unit_price": "299.0",
"subtotal_amount": "114.21127834",
"discount_amount": "11.42112783",
"tax_amount": "6.93833516",
"tax_included": false,
"total_amount": "109.72848567",
"tiered_unit_price": false,
"period_range_start": "2018-12-30",
"period_range_end": "2018-12-30",
"product_id": 85,
"product_version": 1,
"component_id": null,
"price_point_id": null,
"billing_schedule_item_id": null,
"custom_item": false
},
{
"uid": "cnli_8kjttvjknzhx7",
"title": "Small Instance (Hourly)",
"description": "38.2% credit",
"quantity": "74.8676",
"unit_price": "0.12244898",
"subtotal_amount": "9.16746047",
"discount_amount": "0.91674605",
"tax_amount": "0.55692322",
"tax_included": false,
"total_amount": "8.80763764",
"tiered_unit_price": true,
"period_range_start": "2018-11-30",
"period_range_end": "2018-11-30",
"product_id": 85,
"product_version": 1,
"component_id": 78,
"price_point_id": null,
"billing_schedule_item_id": null,
"custom_item": false
},
{
"uid": "cnli_8kjttvjnmh25w",
"title": "Large Instance (Hourly)",
"description": "38.2% credit",
"quantity": "183.3492",
"unit_price": "0.39583333",
"subtotal_amount": "72.57572871",
"discount_amount": "7.25757287",
"tax_amount": "4.40897552",
"tax_included": false,
"total_amount": "69.72713136",
"tiered_unit_price": true,
"period_range_start": "2018-11-30",
"period_range_end": "2018-11-30",
"product_id": 85,
"product_version": 1,
"component_id": 79,
"price_point_id": null,
"billing_schedule_item_id": null,
"custom_item": false
},
{
"uid": "cnli_8kjttvjqn86kc",
"title": "Email Messages",
"description": "38.2% credit",
"quantity": "10076.9489",
"unit_price": "0.00031045",
"subtotal_amount": "3.12839588",
"discount_amount": "0.31322157",
"tax_amount": "0.19002427",
"tax_included": false,
"total_amount": "3.00519858",
"tiered_unit_price": true,
"period_range_start": "2018-11-30",
"period_range_end": "2018-11-30",
"product_id": 85,
"product_version": 1,
"component_id": 80,
"price_point_id": null,
"billing_schedule_item_id": null,
"custom_item": false
},
{
"uid": "cnli_8kjttvjtxxbdd",
"title": "IP Addresses",
"description": "38.2% credit",
"quantity": "3.8198",
"unit_price": "2.0",
"subtotal_amount": "7.63955039",
"discount_amount": "0.76395504",
"tax_amount": "0.46410269",
"tax_included": false,
"total_amount": "7.33969804",
"tiered_unit_price": false,
"period_range_start": "2018-12-30",
"period_range_end": "2018-12-30",
"product_id": 85,
"product_version": 1,
"component_id": 81,
"price_point_id": 165,
"billing_schedule_item_id": null,
"custom_item": false
}
],
"discounts": [
{
"uid": "cndli_8k5jvdzct4h9y",
"title": "Multi-service discount (10%)",
"code": "MULTI3",
"source_type": "Coupon",
"source_id": 40,
"discount_type": "percentage",
"percentage": "10.0",
"eligible_amount": "208.69341779",
"discount_amount": "20.87125167",
"line_item_breakouts": [
{
"uid": "cnli_8k5jvdzct4h9x",
"eligible_amount": "1.971004",
"discount_amount": "0.19862831"
},
{
"uid": "cnli_8kjttvjcjx8b4",
"eligible_amount": "114.21127834",
"discount_amount": "11.42112783"
},
{
"uid": "cnli_8kjttvjknzhx7",
"eligible_amount": "9.16746047",
"discount_amount": "0.91674605"
},
{
"uid": "cnli_8kjttvjnmh25w",
"eligible_amount": "72.57572871",
"discount_amount": "7.25757287"
},
{
"uid": "cnli_8kjttvjqn86kc",
"eligible_amount": "3.12839588",
"discount_amount": "0.31322157"
},
{
"uid": "cnli_8kjttvjtxxbdd",
"eligible_amount": "7.63955039",
"discount_amount": "0.76395504"
}
]
}
],
"taxes": [
{
"uid": "cntli_8k5jvdzct4h9z",
"title": "NC Sales Tax",
"source_type": "Tax",
"source_id": 1,
"percentage": "6.75",
"taxable_amount": "187.82216613",
"tax_amount": "12.67783387",
"line_item_breakouts": [
{
"uid": "cnli_8k5jvdzct4h9x",
"taxable_amount": "1.77237569",
"tax_amount": "0.11963536"
},
{
"uid": "cnli_8kjttvjcjx8b4",
"taxable_amount": "102.7901505",
"tax_amount": "6.93833516"
},
{
"uid": "cnli_8kjttvjknzhx7",
"taxable_amount": "8.25071442",
"tax_amount": "0.55692322"
},
{
"uid": "cnli_8kjttvjnmh25w",
"taxable_amount": "65.31815584",
"tax_amount": "4.40897552"
},
{
"uid": "cnli_8kjttvjqn86kc",
"taxable_amount": "2.81517432",
"tax_amount": "0.19002427"
},
{
"uid": "cnli_8kjttvjtxxbdd",
"taxable_amount": "6.87559535",
"tax_amount": "0.46410269"
}
],
"tax_component_breakouts": [
{
"tax_rule_id": 1,
"percentage": "6.75",
"country_code": "US",
"subdivision_code": "NC",
"tax_amount": "10.66",
"taxable_amount": "157.95",
"tax_exempt_amount": "0.0",
"non_taxable_amount": "0.0",
"tax_name": "NC STATE TAX",
"tax_type": "Sales",
"rate_type": "General",
"tax_authority_type": 45,
"state_assigned_no": "",
"tax_sub_type": "S"
}
],
"eu_vat": false,
"type": "Sales",
"tax_exempt_amount": "0.0"
}
],
"applications": [
{
"uid": "cdt_8m9vbdbdwd28n",
"transaction_time": "2018-12-31T21:19:28Z",
"invoice_uid": "inv_8k5jvdzct4hb2",
"memo": "Refund for overpayment",
"applied_amount": "200.5"
}
],
"refunds": [
{
"transaction_id": 329,
"payment_id": 39,
"memo": "Refund for overpayment",
"original_amount": "524.9",
"applied_amount": "200.5"
}
]
}
```
##### Record Payment for Subscription
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/invoices/record-payment-for-subscription
Records an external payment made against a subscription that will pay partially or in full one or more invoices.
Payment will be applied starting with the oldest open invoice and then next oldest, and so on until the amount of the payment is fully consumed.
Excess payment will result in the creation of a prepayment on the Invoice Account.
Only ungrouped or primary subscriptions may be paid using the "bulk" payment request.
```http
POST /subscriptions/{subscription_id}/payments.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `body` | [`Record Payment Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/record-payment-request) | Body, Optional | - |
# Response Type
**201**: OK
[`Record Payment Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/record-payment-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscriptions/222/payments.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"payment": {
"amount": "10.0",
"memo": "to pay the bills",
"payment_details": "check number 8675309",
"payment_method": "check"
}
}'
```
# Example Response *(as JSON)*
```json
{
"paid_invoices": [
{
"invoice_id": "inv_bchyhr6z5grby",
"status": "paid",
"due_amount": "0.0",
"paid_amount": "50.0"
},
{
"invoice_id": "inv_bchyhrgvyb6vm",
"status": "paid",
"due_amount": "0.0",
"paid_amount": "50.0"
}
],
"prepayment": null
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Reopen Invoice
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/invoices/reopen-invoice
Reopens any invoice with the "canceled" status. Invoices enter "canceled" status if they were open at the time the subscription was canceled (whether through dunning or an intentional cancellation).
Invoices with "canceled" status are no longer considered to be due. Once reopened, they are considered due for payment. Payment may then be captured in one of the following ways:
- Reactivating the subscription, which will capture all open invoices (See note below about automatic reopening of invoices.)
- Recording a payment directly against the invoice
A note about reactivations: any canceled invoices from the most recent active period are automatically opened as a part of the reactivation process. Reactivating via this endpoint prior to reactivation is only necessary when you wish to capture older invoices from previous periods during the reactivation.
### Reopening Consolidated Invoices
When reopening a consolidated invoice, all of its canceled segments will also be reopened.
```http
POST /invoices/{uid}/reopen.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `uid` | `String` | Template, Required | The unique identifier for the invoice, this does not refer to the public facing invoice number. |
# Response Type
**200**: OK
[`Invoice`](https://developers.maxio.com/http/advanced-billing-api/models/structures/invoice)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/invoices/uid0/reopen.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Void Invoice
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/invoices/void-invoice
Voids any invoice with the "open" or "canceled" status. It will also allow voiding of an invoice with the "pending" status if it is not a consolidated invoice.
```http
POST /invoices/{uid}/void.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `uid` | `String` | Template, Required | The unique identifier for the invoice, this does not refer to the public facing invoice number. |
| `body` | [`Void Invoice Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/void-invoice-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Invoice`](https://developers.maxio.com/http/advanced-billing-api/models/structures/invoice)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/invoices/uid0/void.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"void": {
"reason": "Duplicate invoice"
}
}'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### List Consolidated Invoice Segments
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/invoices/list-consolidated-invoice-segments
Lists segments for a consolidated invoice. Invoice segments returned on the index will only include totals, not detailed breakdowns for `line_items`, `discounts`, `taxes`, `credits`, `payments`, or `custom_fields`.
```http
GET /invoices/{invoice_uid}/segments.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `invoice_uid` | `String` | Template, Required | The unique identifier of the consolidated invoice |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query `per_page=200`.
**Default**: `20`
**Constraints**: `<= 200` |
| `direction` | [`Direction`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/direction) | Query, Optional | Sort direction of the returned segments.
**Default**: `asc` |
# Response Type
**200**: OK
[`Consolidated Invoice`](https://developers.maxio.com/http/advanced-billing-api/models/structures/consolidated-invoice)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/invoices/invoice_uid0/segments.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'page=1' \
-d 'per_page=50' \
-d 'direction=asc'
```
# Example Response *(as JSON)*
```json
{
"invoices": [
{
"uid": "inv_8htcd29wcq3q6",
"site_id": 51288,
"customer_id": 20153415,
"subscription_id": 23277588,
"number": "125",
"sequence_number": 125,
"issue_date": "2018-09-20",
"due_date": "2018-09-20",
"paid_date": "2018-09-20",
"status": "paid",
"collection_method": "automatic",
"payment_instructions": "Make checks payable to Acme, Inc.",
"currency": "USD",
"consolidation_level": "parent",
"parent_invoice_uid": null,
"parent_invoice_number": null,
"group_primary_subscription_id": 23277588,
"product_name": "Trial and setup fee",
"product_family_name": "Billing Plans",
"seller": {
"name": "General Goods",
"address": {
"street": "123 General Goods Way",
"line2": "Apt. 10",
"city": "Boston",
"state": "MA",
"zip": "02120",
"country": "US"
},
"phone": "555-555-1212"
},
"customer": {
"chargify_id": 20153415,
"first_name": "Meg",
"last_name": "Example",
"organization": "",
"email": "meg@example.com"
},
"memo": "Payment due within 15 days of receipt.",
"billing_address": {
"street": "123 I Love Cats Way",
"line2": "",
"city": "Boston",
"state": "MA",
"zip": "90210",
"country": "US"
},
"shipping_address": {
"street": "123 I Love Cats Way",
"line2": "",
"city": "Boston",
"state": "MA",
"zip": "90210",
"country": "US"
},
"subtotal_amount": "100.0",
"discount_amount": "0.0",
"tax_amount": "0.0",
"total_amount": "100.0",
"credit_amount": "0.0",
"paid_amount": "100.0",
"refund_amount": "0.0",
"due_amount": "0.0",
"public_url": "https://www.chargifypay.com/invoice/inv_8htcd29wcq3q6?token=fb6kpjz5rcr2vttyjs4rcv6y"
},
{
"uid": "inv_8hr3546xp4h8n",
"site_id": 51288,
"customer_id": 21687686,
"subscription_id": 22007644,
"number": "124",
"sequence_number": 124,
"issue_date": "2018-09-18",
"due_date": "2018-09-18",
"paid_date": null,
"status": "open",
"collection_method": "remittance",
"payment_instructions": "Make checks payable to Acme, Inc.",
"currency": "USD",
"consolidation_level": "none",
"parent_invoice_uid": null,
"parent_invoice_number": null,
"group_primary_subscription_id": null,
"product_name": "Trial and setup fee",
"product_family_name": "Billing Plans",
"seller": {
"name": "General Goods",
"address": {
"street": "123 General Goods Way",
"line2": "Apt. 10",
"city": "Boston",
"state": "MA",
"zip": "02120",
"country": "US"
},
"phone": "555-555-1212"
},
"customer": {
"chargify_id": 21687686,
"first_name": "Charlene",
"last_name": "Tester",
"organization": "",
"email": "food@example.com"
},
"memo": "Payment due within 15 days of receipt.",
"billing_address": {
"street": "",
"line2": "",
"city": "",
"state": "",
"zip": "",
"country": ""
},
"shipping_address": {
"street": "",
"line2": "",
"city": "",
"state": "",
"zip": "",
"country": ""
},
"subtotal_amount": "100.0",
"discount_amount": "0.0",
"tax_amount": "0.0",
"total_amount": "100.0",
"credit_amount": "0.0",
"paid_amount": "0.0",
"refund_amount": "0.0",
"due_amount": "100.0",
"public_url": "https://www.chargifypay.com/invoice/inv_8hr3546xp4h8n?token=fb6kpjz5rcr2vttyjs4rcv6y"
},
{
"uid": "inv_8hr3546wdwxkr",
"site_id": 51288,
"customer_id": 21687670,
"subscription_id": 22007627,
"number": "123",
"sequence_number": 123,
"issue_date": "2018-09-18",
"due_date": "2018-09-18",
"paid_date": "2018-09-18",
"status": "paid",
"collection_method": "automatic",
"payment_instructions": "Make checks payable to Acme, Inc.",
"currency": "USD",
"consolidation_level": "none",
"parent_invoice_uid": null,
"parent_invoice_number": null,
"group_primary_subscription_id": null,
"product_name": "Trial End - Free",
"product_family_name": "Billing Plans",
"seller": {
"name": "General Goods",
"address": {
"street": "123 General Goods Way",
"line2": "Apt. 10",
"city": "Boston",
"state": "MA",
"zip": "02120",
"country": "US"
},
"phone": "555-555-1212"
},
"customer": {
"chargify_id": 21687670,
"first_name": "Hello",
"last_name": "World",
"organization": "123",
"email": "example@example.com"
},
"memo": "Payment due within 15 days of receipt.",
"billing_address": {
"street": "123 Anywhere Street",
"line2": "",
"city": "Boston",
"state": "MA",
"zip": "02120",
"country": "US"
},
"shipping_address": {
"street": "",
"line2": "",
"city": "Boston",
"state": "AL",
"zip": "02120",
"country": "US"
},
"subtotal_amount": "0.0",
"discount_amount": "0.0",
"tax_amount": "0.0",
"total_amount": "0.0",
"credit_amount": "0.0",
"paid_amount": "0.0",
"refund_amount": "0.0",
"due_amount": "0.0",
"public_url": "https://www.chargifypay.com/invoice/inv_8hr3546wdwxkr?token=fb6kpjz5rcr2vttyjs4rcv6y"
},
{
"uid": "inv_8hjtk8bz56bbp",
"site_id": 51288,
"customer_id": 20137757,
"subscription_id": 20541100,
"number": "122",
"sequence_number": 122,
"issue_date": "2018-09-10",
"due_date": "2018-09-10",
"paid_date": "2018-09-10",
"status": "paid",
"collection_method": "automatic",
"payment_instructions": "Make checks payable to Acme, Inc.",
"currency": "USD",
"consolidation_level": "none",
"parent_invoice_uid": null,
"parent_invoice_number": null,
"group_primary_subscription_id": null,
"product_name": "$0 Product",
"product_family_name": "Billing Plans",
"seller": {
"name": "General Goods",
"address": {
"street": "123 General Goods Way",
"line2": "Apt. 10",
"city": "Boston",
"state": "MA",
"zip": "02120",
"country": "US"
},
"phone": "555-555-1212"
},
"customer": {
"chargify_id": 20137757,
"first_name": "Sasha",
"last_name": "Example",
"organization": "",
"email": "example@example.com"
},
"memo": "Payment due within 15 days of receipt.",
"billing_address": {
"street": "123 I Love Cats Way",
"line2": "",
"city": "Catville",
"state": "MA",
"zip": "90210",
"country": "US"
},
"shipping_address": {
"street": "123 I Love Cats Way",
"line2": "",
"city": "Catville",
"state": "AL",
"zip": "90210",
"country": "US"
},
"subtotal_amount": "0.0",
"discount_amount": "0.0",
"tax_amount": "0.0",
"total_amount": "0.0",
"credit_amount": "0.0",
"paid_amount": "0.0",
"refund_amount": "0.0",
"due_amount": "0.0",
"public_url": "https://www.chargifypay.com/invoice/inv_8jzrw74xq8kxr?token=fb6kpjz5rcr2vttyjs4rcv6y"
}
]
}
```
##### Create Invoice
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/invoices/create-invoice
Creates an ad hoc invoice.
### Basic Behavior
You can create a basic invoice by sending an array of line items to this endpoint. Each line item, at a minimum, must include a title, a quantity and a unit price. Example:
```json
{
"invoice": {
"line_items": [
{
"title": "A Product",
"quantity": 12,
"unit_price": "150.00"
}
]
}
}
```
### Catalog items
Instead of creating custom products like in above example, You can pass existing items like products, components.
```json
{
"invoice": {
"line_items": [
{
"product_id": "handle:gold-product",
"quantity": 2,
}
]
}
}
```
The price for each line item will be calculated as well as a total due amount for the invoice. Multiple line items can be sent.
### Line item types
When defining a line item, You can choose one of 3 types for a line item:
#### Custom item
As shown in the basic behavior example, You can pass `title` and `unit_price` for custom item.
#### Product id
Product handle (with handle: prefix) or id from the scope of current subscription's site can be provided with `product_id`. By default `unit_price` is taken from product's default price point, but can be overwritten by passing `unit_price` or `product_price_point_id`. If `product_id` is used, following fields cannot be used: `title`, `component_id`.
#### Component id
Component handle (with handle: prefix) or id from the scope of current subscription's site can be provided with `component_id`. If `component_id` is used, following fields cannot be used: `title`, `product_id`. By default `unit_price` is taken from product's default price point, but can be overwritten by passing `unit_price` or `price_point_id`. At this moment price points are supported only for quantity based, on/off and metered components. For prepaid and event based billing components `unit_price` is required.
### Coupons
When creating ad hoc invoice, new discounts can be applied in following way:
```json
{
"invoice": {
"line_items": [
{
"product_id": "handle:gold-product",
"quantity": 1
}
],
"coupons": [
{
"code": "COUPONCODE",
"percentage": 50.0
}
]
}
}
```
If You want to use existing coupon for discount creation, only `code` and optional `product_family_id` is needed
```json
...
"coupons": [
{
"code": "FREESETUP",
"product_family_id": 1
}
]
...
```
#### Using Coupon Subcodes
You can also use coupon subcodes to apply existing coupons with specific subcodes:
```json
...
"coupons": [
{
"subcode": "SUB1",
"product_family_id": 1
}
]
...
```
**Important:** You cannot specify both `code` and `subcode` for the same coupon. Use either:
- `code` to apply a main coupon
- `subcode` to apply a specific coupon subcode
The API response will include both the main coupon code and the subcode used:
```json
...
"coupons": [
{
"code": "MAIN123",
"subcode": "SUB1",
"product_family_id": 1,
"percentage": 10,
"description": "Special discount"
}
]
...
```
### Coupon options
#### Code
Coupon `code` will be displayed on invoice discount section.
Coupon code can only contain uppercase letters, numbers, and allowed special characters.
Lowercase letters will be converted to uppercase. It can be used to select an existing coupon from the catalog, or as an ad hoc coupon when passed with `percentage` or `amount`.
#### Subcode
Coupon `subcode` allows you to apply existing coupons using their subcodes. When a subcode is used, the API response will include both the main coupon code and the specific subcode that was applied. Subcodes are case-insensitive and will be converted to uppercase automatically.
#### Percentage
Coupon `percentage` can take values from 0 to 100 and up to 4 decimal places. It cannot be used with `amount`. Only for ad hoc coupons, will be ignored if `code` is used to select an existing coupon from the catalog.
#### Amount
Coupon `amount` takes number value. It cannot be used with `percentage`. Used only when not matching existing coupon by `code`.
#### Description
Optional `description` will be displayed with coupon `code`. Used only when not matching existing coupon by `code`.
#### Product Family id
Optional `product_family_id` handle (with handle: prefix) or id is used to match existing coupon within site, when codes are not unique.
#### Compounding Strategy
Optional `compounding_strategy` for percentage coupons, can take values `compound` or `full-price`.
For amount coupons, discounts will be always calculated against the original item price, before other discounts are applied.
`compound` strategy:
Percentage-based discounts will be calculated against the remaining price, after prior discounts have been calculated. It is set by default.
`full-price` strategy:
Percentage-based discounts will always be calculated against the original item price, before other discounts are applied.
### Line Item Options
#### Period Date Range
A custom period date range can be defined for each line item with the `period_range_start` and `period_range_end` parameters. Dates must be sent in the `YYYY-MM-DD` format.
`period_range_end` must be greater or equal `period_range_start`.
#### Taxes
The `taxable` parameter can be sent as `true` if taxes should be calculated for a specific line item. For this to work, the site should be configured to use and calculate taxes. Further, if the site uses Avalara for tax calculations, a `tax_code` parameter should also be sent. For existing catalog items: products/components taxes cannot be overwritten.
#### Price Point
Price point handle (with handle: prefix) or id from the scope of current subscription's site can be provided with `price_point_id` for components with `component_id` or `product_price_point_id` for products with `product_id` parameter. If price point is passed `unit_price` cannot be used. It can be used only with catalog items products and components.
#### Description
Optional `description` parameter, it will overwrite default generated description for line item.
### Invoice Options
#### Issue Date
By default, invoices will be created with a issue date set to today in your site's time zone. The `issue_date` parameter can be sent to alter the default. Only today or dates in the past are accepted. This date is interpreted and validated in your site's time zone. The format for `issue_date` is `YYYY-MM-DD`.
#### Net Terms
By default, invoices will be created with a due date matching the date of invoice creation. If a different due date is desired, the `net_terms` parameter can be sent indicating the number of days in advance the due date should be.
#### Addresses
The seller, shipping and billing addresses can be sent to override the site's defaults. Each address requires to send a `first_name` at a minimum in order to work. See below for the details on which parameters can be sent for each address object.
#### Memo and Payment Instructions
A custom memo can be sent with the `memo` parameter to override the site's default. Likewise, custom payment instructions can be sent with the `payment_instructions` parameter.
#### Status
By default, invoices will be created with open status. Possible alternative is `draft`.
```http
POST /subscriptions/{subscription_id}/invoices.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `body` | [`Create Invoice Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/create-invoice-request) | Body, Optional | - |
# Response Type
**200**: OK
**201**: Created
[`Invoice Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/invoice-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscriptions/222/invoices.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"invoice": {
"line_items": [
{
"title": "A Product",
"quantity": 12.0,
"unit_price": "150.00"
}
]
}
}'
```
# Example Response *(as JSON)*
```json
{
"invoice": {
"uid": "inv_98nbmb93gxjz8",
"site_id": 5,
"customer_id": 13,
"subscription_id": 17,
"number": "1",
"sequence_number": 1,
"issue_date": "2020-12-02",
"due_date": "2020-12-02",
"paid_date": null,
"status": "open",
"collection_method": "remittance",
"payment_instructions": "",
"currency": "USD",
"consolidation_level": "none",
"parent_invoice_uid": null,
"parent_invoice_number": null,
"group_primary_subscription_id": null,
"product_name": "Digitized discrete initiative",
"product_family_name": "Networked bottom-line orchestration",
"role": "adhoc",
"seller": {
"name": "Steuber, West and Hegmann 1",
"address": {
"street": null,
"line2": null,
"city": null,
"state": null,
"zip": null,
"country": null
},
"phone": "(766) 316-0492"
},
"customer": {
"chargify_id": 13,
"first_name": "Dean",
"last_name": "Adams",
"organization": null,
"email": "brandi1@example.com",
"vat_number": null,
"reference": null
},
"memo": "",
"billing_address": {
"street": null,
"line2": null,
"city": null,
"state": null,
"zip": null,
"country": null
},
"shipping_address": {
"street": null,
"line2": null,
"city": null,
"state": null,
"zip": null,
"country": null
},
"subtotal_amount": "1800.0",
"discount_amount": "0.0",
"tax_amount": "0.0",
"total_amount": "1800.0",
"credit_amount": "0.0",
"paid_amount": "0.0",
"refund_amount": "0.0",
"due_amount": "1800.0",
"line_items": [
{
"uid": "li_98nbmb9jgz84c",
"title": "Some product",
"description": "12/02/2020 - 12/02/2020",
"quantity": "12.0",
"unit_price": "150.0",
"subtotal_amount": "1800.0",
"discount_amount": "0.0",
"tax_amount": "0.0",
"tax_included": false,
"total_amount": "1800.0",
"tiered_unit_price": false,
"period_range_start": "2020-12-02",
"period_range_end": "2020-12-02",
"product_id": null,
"product_version": null,
"product_price_point_id": null,
"component_id": null,
"price_point_id": null
}
],
"public_url": "https://www.test-chargifypay.com/invoice/inv_98nbmb93gxjz8?token=rmfmwvbdy4xmyw5f29j5gc6x"
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error Array Map ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-array-map-response) |
##### Update Invoice
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/invoices/update-invoice
Updates an ad hoc invoice while it is in the `draft` state.
**Important: only invoices with the `adhoc` role and `draft` status can be updated.** Any other invoice — issued, or with a different role (e.g. `renewal`, `signup`) — cannot be updated through this endpoint and the request returns a `422` error. If the invoice does not belong to the provided subscription, a `404` error is returned.
Only the attributes submitted in the request are changed — omitted attributes keep their current values.
### Line Items
The `line_items` array describes changes to the invoice's line items. Line items not referenced in the array remain unchanged.
#### Adding a line item
A line item without a `uid` is added to the invoice. The same line item types and options as on invoice creation are supported (custom items, `product_id`, `component_id`, price points, period date ranges, taxes).
#### Updating a line item
A line item with the `uid` of an existing line item updates that line item with the submitted attributes. Amounts and taxes are recalculated.
#### Removing a line item
A line item with a `uid` and `"_destroy": true` is removed from the invoice. Other line items remain unchanged.
Referencing a `uid` which does not exist on the invoice returns a `422` error.
### Coupons
When the `coupons` key is present, the submitted coupons replace all discounts currently applied to the invoice. Send an empty array to remove all discounts. Coupon options are the same as on invoice creation.
### Invoice Options
#### Issue Date and Net Terms
The `issue_date` parameter can be sent to change the invoice's issue date. Only today or dates in the past are accepted. The date is interpreted and validated in your site's time zone, using the `YYYY-MM-DD` format. The `net_terms` parameter indicates the number of days after the issue date on which the invoice is due. The due date is recalculated whenever the issue date or net terms change.
#### Addresses
The seller, shipping and billing addresses can be sent to replace the addresses on the invoice. Each address requires to send a `first_name` at a minimum in order to work. Taxes are recalculated after an address change.
#### Memo and Payment Instructions
A custom memo can be sent with the `memo` parameter. Likewise, custom payment instructions can be sent with the `payment_instructions` parameter.
```http
PUT /subscriptions/{subscription_id}/invoices/{uid}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `uid` | `String` | Template, Required | The unique identifier for the invoice, this does not refer to the public facing invoice number. |
| `body` | [`Update Invoice Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/update-invoice-request) | Body, Optional | Request payload for updating a draft ad hoc invoice. |
# Response Type
**200**: OK
[`Invoice Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/invoice-response)
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/subscriptions/222/invoices/uid0.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"invoice": {
"memo": "Updated memo",
"net_terms": 30
}
}'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
| 422 | Unprocessable Entity (WebDAV) | [`Error Array Map ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-array-map-response) |
##### Delete Invoice
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/invoices/delete-invoice
Deletes an ad hoc invoice while it is in the `draft` state.
**Important: only invoices with the `adhoc` role and `draft` status can be deleted.** Any other invoice — issued, or with a different role (e.g. `renewal`, `signup`) — cannot be deleted through this endpoint and the request returns a `422` error. Issued invoices should be voided instead. If the invoice does not belong to the provided subscription, a `404` error is returned.
A successful deletion returns a `204 No Content` response and the invoice is permanently removed.
```http
DELETE /subscriptions/{subscription_id}/invoices/{uid}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `uid` | `String` | Template, Required | The unique identifier for the invoice, this does not refer to the public facing invoice number. |
# Response Type
**204**: No Content
`Void`
# Example Usage
```bash
curl -X DELETE \
--url 'https://subdomain.chargify.com/subscriptions/222/invoices/uid0.json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Send Invoice
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/invoices/send-invoice
Sends an invoice to the customer via email. This endpoint supports the delivery of both ad-hoc and automatically generated invoices. Additionally, this endpoint supports email delivery to direct recipients, carbon-copy (cc) recipients, and blind carbon-copy (bcc) recipients.
**File Attachments**: You can attach files to invoice emails using `attachment_urls[]` parameter by providing URLs to the files you want to attach. When using attachments, the request must use `multipart/form-data` content type. Max 10 files, 10MB per file.
If no recipient email addresses are specified in the request, then the subscription's default email configuration will be used. For example, if `recipient_emails` is left blank, then the invoice will be delivered to the subscription's customer email address.
On success, a 204 no-content response will be returned. The response does not indicate that email(s) have been delivered, but instead indicates that emails have been successfully queued for delivery. If _any_ invalid or malformed email address is found in the request body, the entire request will be rejected and a 422 response will be returned.
```http
POST /invoices/{uid}/deliveries.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `uid` | `String` | Template, Required | The unique identifier for the invoice, this does not refer to the public facing invoice number. |
| `body` | [`Send Invoice Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/send-invoice-request) | Body, Optional | - |
# Response Type
**204**: No Content
`Void`
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/invoices/uid0/deliveries.json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"recipient_emails": [
"user0@example.com"
],
"cc_recipient_emails": [
"user1@example.com"
],
"bcc_recipient_emails": [
"user2@example.com"
]
}'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Preview Customer Information Changes
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/invoices/preview-customer-information-changes
Previews the effect of customer information changes on an open invoice. Customer information may change after an invoice is issued, which may lead to a mismatch between customer information that is present on an open invoice and actual customer information. This endpoint allows you to preview these differences, if any.
The endpoint doesn't accept a request body. Customer information differences are calculated on the application side.
```http
POST /invoices/{uid}/customer_information/preview.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `uid` | `String` | Template, Required | The unique identifier for the invoice, this does not refer to the public facing invoice number. |
# Response Type
**200**: OK
[`Customer Changes Preview Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/customer-changes-preview-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/invoices/uid0/customer_information/preview.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"changes": {
"payer": {
"before": {
"last_name": "Beatty"
},
"after": {
"last_name": "Doe"
}
},
"shipping_address": {
"before": {
"line2": "Suite 703"
},
"after": {
"line2": "Suite 702"
}
},
"billing_address": {
"before": {
"line2": "Suite 703"
},
"after": {
"line2": "Suite 702"
}
},
"custom_fields": {
"before": [
{
"owner_id": 1002,
"owner_type": "Customer",
"name": "Color",
"value": "blue",
"metadatum_id": 20
}
],
"after": [
{
"owner_id": 1002,
"owner_type": "Customer",
"name": "Color",
"value": "green",
"metadatum_id": 20
}
]
}
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Update Customer Information
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/invoices/update-customer-information
Updates customer information on an open invoice and returns the updated invoice. If you would like to preview changes that will be applied, use the `/invoices/{uid}/customer_information/preview.json` endpoint first.
The endpoint doesn't accept a request body. Customer information differences are calculated on the application side.
```http
PUT /invoices/{uid}/customer_information.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `uid` | `String` | Template, Required | The unique identifier for the invoice, this does not refer to the public facing invoice number. |
# Response Type
**200**: OK
[`Invoice`](https://developers.maxio.com/http/advanced-billing-api/models/structures/invoice)
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/invoices/uid0/customer_information.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"uid": "elit Ut",
"site_id": 46283786,
"customer_id": -62349460,
"subscription_id": 12801726,
"number": "dolore et ut",
"sequence_number": -84210096,
"issue_date": "2017-01-01",
"due_date": "2017-01-30",
"paid_date": "2017-01-28",
"status": "open",
"collection_method": "automatic",
"payment_instructions": "enim officia",
"currency": "dolore",
"consolidation_level": "none",
"product_name": "occaecat veniam culpa",
"product_family_name": "qui commodo ea dolore cillum",
"seller": {
"name": "co",
"phone": "ullamco in officia"
},
"customer": {
"chargify_id": -55826334,
"first_name": "deserunt",
"last_name": "velit dolore",
"email": "aliquip sed velit Lorem"
},
"memo": "ea cupidatat deserunt",
"billing_address": {
"street": "qui commodo cupidatat sunt",
"line2": "ut officia enim",
"city": "velit minim dolore sint nulla",
"state": "velit",
"zip": "ullamco",
"country": "irure est laborum deserun"
},
"shipping_address": {
"street": "do fugiat dolore deserunt officia",
"line2": "ipsum cillum",
"city": "aliqua laboris incididunt ut",
"state": "et fugiat sit",
"zip": "dolore do",
"country": "Excepteur consequat cillum"
},
"subtotal_amount": "dolore mollit",
"discount_amount": "aute",
"tax_amount": "eu aliqua est velit ea",
"total_amount": "ut non",
"credit_amount": "sit",
"refund_amount": "et eiusmod qui sed",
"paid_amount": "amet nulla s",
"due_amount": "non esse ullamco",
"line_items": [
{
"description": "qui",
"price_point_id": 123,
"tax_amount": "occaecat deserunt veniam",
"subtotal_amount": "commodo consequat tempor et Duis"
},
{
"uid": "",
"subtotal_amount": "ven"
},
{
"price_point_id": 94750853,
"product_id": 79058036,
"tax_amount": "1.0",
"subtotal_amount": "128.5"
},
{
"unit_price": "eiusmod consequat ut nostrud",
"tax_amount": "quis nulla proident"
},
{
"period_range_end": "2022-02-02",
"product_id": 57352537,
"description": "minim in dolore Ut Excepteur",
"uid": "sit qui in ullamco anim"
}
],
"discounts": [
{
"title": "nostrud"
}
],
"taxes": [
{
"source_type": "Tax",
"line_item_breakouts": [
{
"uid": "in ipsum",
"tax_amount": "velit",
"taxable_amount": "quis sint"
},
{
"uid": "co"
}
]
},
{
"uid": "enim irure in",
"title": "incididunt est mollit irure"
}
],
"credits": [
{
"uid": "exercitation eiusmod",
"transaction_time": "2024-01-23T13:51:27Z",
"credit_note_number": "qui fugiat labore laborum",
"credit_note_uid": "ipsum sunt"
},
{
"memo": "dolor"
}
],
"refunds": [
{
"memo": "deserunt elit"
},
{
"original_amount": "Duis nulla"
}
],
"payments": [
{
"prepayment": false,
"memo": "enim Excepteur Lorem magna sit"
},
{
"transaction_time": "2024-01-23T13:51:27Z",
"prepayment": false,
"payment_method": {
"details": "labore ut et",
"kind": "dolor qui",
"memo": "ea commodo",
"type": "fugiat veniam",
"card_brand": "consequat",
"card_expiration": "aliqua a",
"last_four": "ut in consectetur sed",
"masked_card_number": "minim ea ullamco nostrud tempor"
}
},
{
"prepayment": true,
"transaction_id": 67527234
},
{
"original_amount": "c",
"memo": "dolore fugiat labore"
}
],
"custom_fields": [
{
"name": "CustomerStatus",
"value": "Gold",
"owner_type": "Customer",
"owner_id": 18482224,
"metadatum_id": 13924
},
{
"name": "SubscriptionTag",
"value": "Special Subscriber",
"owner_type": "Subscription",
"owner_id": 21344,
"metadatum_id": 139245
}
],
"public_url": "dolo",
"previous_balance_data": {
"captured_at": "2024-01-09T11:22:23-05:00",
"invoices": [
{
"number": "veniam dolore labore ipsum cupidatat",
"uid": "tempor",
"outstanding_amount": "Excepteur nostrud irur"
},
{
"outstanding_amount": "id"
}
]
},
"public_url_expires_on": "2024-11-21"
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Issue Invoice
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/invoices/issue-invoice
Issues an invoice that is in "pending" or "draft" status. For example, you can issue an invoice that was created when allocating new quantity on a component and using "accrue charges" option.
You cannot issue a pending child invoice that was created for a member subscription in a group.
For Remittance subscriptions, the invoice will go into "open" status and payment won't be attempted. The value for `on_failed_payment` would be rejected if sent. Any prepayments or service credits that exist on the subscription will be automatically applied. Additionally, if the setting is enabled, an email will be sent for the issued invoice.
For Automatic subscriptions, prepayments and service credits will apply to the invoice before payment is attempted. On successful payment, the invoice will go into "paid" status and email will be sent to the customer (if setting applies). When payment fails, the next event depends on the `on_failed_payment` value:
- `leave_open_invoice` - prepayments and credits applied to invoice; invoice status set to "open"; email sent to the customer for the issued invoice (if setting applies); payment failure recorded in the invoice history. This is the default option.
- `rollback_to_pending` - prepayments and credits not applied; invoice remains in "pending" status; no email sent to the customer; payment failure recorded in the invoice history.
- `initiate_dunning` - prepayments and credits applied to the invoice; invoice status set to "open"; email sent to the customer for the issued invoice (if setting applies); payment failure recorded in the invoice history; subscription will most likely go into "past_due" or "canceled" state (depending upon net terms and dunning settings).
```http
POST /invoices/{uid}/issue.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `uid` | `String` | Template, Required | The unique identifier for the invoice, this does not refer to the public facing invoice number. |
| `body` | [`Issue Invoice Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/issue-invoice-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Invoice`](https://developers.maxio.com/http/advanced-billing-api/models/structures/invoice)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/invoices/uid0/issue.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"on_failed_payment": "leave_open_invoice"
}'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
#### Offers
##### Create Offer
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/offers/create-offer
Creates an offer within your site.
Offers allow you to package complicated combinations of products, components and coupons into a convenient package which can then be subscribed to just like products.
Once an offer is defined it can be used as an alternative to the product when creating subscriptions.
For more information, see [Offers](https://maxio.zendesk.com/hc/en-us/articles/24261295098637-Offers-Overview) in the product documentation.
## Using a Product Price Point
You can optionally pass in a `product_price_point_id` that corresponds with the `product_id` and the offer will use that price point. If a `product_price_point_id` is not passed in, the product's default price point will be used.
```http
POST /offers.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `body` | [`Create Offer Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/create-offer-request) | Body, Optional | - |
# Response Type
**201**: Created
[`Offer Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/offer-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/offers.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"offer": {
"name": "Solo",
"handle": "han_shot_first",
"description": "A Star Wars Story",
"product_id": 31,
"product_price_point_id": 102,
"components": [
{
"component_id": 24,
"starting_quantity": 1
}
],
"coupons": [
"DEF456"
]
}
}'
```
# Example Response *(as JSON)*
```json
{
"offer": {
"id": 3,
"site_id": 2,
"product_family_id": 4,
"product_family_name": "Chargify",
"product_id": 31,
"product_name": "30-Day Square Trial",
"product_price_in_cents": 2000,
"product_revisable_number": 0,
"name": "Solo",
"handle": "han_shot_first",
"description": "A Star Wars Story",
"created_at": "2018-06-08T14:51:52-04:00",
"updated_at": "2018-06-08T14:51:52-04:00",
"archived_at": null,
"product_price_point_name": "Default",
"offer_items": [
{
"component_id": 24,
"component_name": "Invoices",
"component_unit_price": "3.0",
"price_point_id": 104,
"price_point_name": "Original",
"starting_quantity": "1.0",
"editable": false
}
],
"offer_discounts": [
{
"coupon_id": 3,
"coupon_code": "DEF456",
"coupon_name": "IB Loyalty"
}
]
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error Array Map ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-array-map-response) |
##### List Offers
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/offers/list-offers
Lists offers for a site.
```http
GET /offers.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query `per_page=200`.
**Default**: `20`
**Constraints**: `<= 200` |
| `include_archived` | `Boolean` | Query, Optional | Include archived products. Use in query: `include_archived=true`. |
# Response Type
**200**: OK
[`List Offers Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/list-offers-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/offers.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'page=1' \
-d 'per_page=50' \
-d 'include_archived=true'
```
# Example Response *(as JSON)*
```json
{
"offers": [
{
"id": 239,
"site_id": 48110,
"product_family_id": 1025627,
"product_family_name": "Gold",
"product_id": 110,
"product_name": "Pro",
"product_price_in_cents": 1000,
"product_revisable_number": 0,
"product_price_point_id": 138,
"product_price_point_name": "Default",
"name": "Third Offer",
"handle": "third",
"description": "",
"created_at": "2018-08-03T09:56:11-05:00",
"updated_at": "2018-08-03T09:56:11-05:00",
"archived_at": null,
"offer_items": [
{
"component_id": 426665,
"component_name": "Database Size (GB)",
"component_unit_price": "1.0",
"price_point_id": 149438,
"price_point_name": "Auto-created",
"starting_quantity": "0.0",
"editable": false
}
],
"offer_discounts": [
{
"coupon_id": 234,
"coupon_code": "GR8_CUSTOMER",
"coupon_name": "Multi-service Discount"
}
],
"offer_signup_pages": [
{
"id": 356482,
"nickname": "ggoods",
"enabled": true,
"return_url": "",
"return_params": "",
"url": "https://general-goods.chargifypay.com/subscribe/hjpvhnw63tzy"
}
]
}
]
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Read Offer
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/offers/read-offer
Returns a specific offer's attributes. This is different from listing all offers for a site, as it requires an `offer_id`.
```http
GET /offers/{offer_id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `offer_id` | `Number` | Template, Required | The Chargify id of the offer |
# Response Type
**200**: OK
[`Offer Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/offer-response)
# Example Usage
```bash
curl -X GET \
--url 'https://subdomain.chargify.com/offers/130.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
##### Archive Offer
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/offers/archive-offer
Archives an existing offer. Please provide an `offer_id` in order to archive the correct item.
```http
PUT /offers/{offer_id}/archive.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `offer_id` | `Number` | Template, Required | The Chargify id of the offer |
# Response Type
**200**: OK
`Void`
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/offers/130/archive.json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
##### Unarchive Offer
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/offers/unarchive-offer
Unarchives a previously archived offer. Please provide an `offer_id` in order to unarchive the correct item.
```http
PUT /offers/{offer_id}/unarchive.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `offer_id` | `Number` | Template, Required | The Chargify id of the offer |
# Response Type
**200**: OK
`Void`
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/offers/130/unarchive.json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
#### Payment Profiles
##### Create Payment Profile
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/payment-profiles/create-payment-profile
Creates a payment profile for a customer.
When you create a new payment profile for a customer via the API, it does not automatically make the profile current for any of the customer’s subscriptions. To use the payment profile as the default, you must set it explicitly for the subscription or subscription group.
Select an option from the **Request Examples** drop-down on the right side of the portal to see examples of common scenarios for creating payment profiles.
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.
See the following articles to learn more about subscriptions and payments:
+ [Subscriber Payment Details](https://maxio.zendesk.com/hc/en-us/articles/24251599929613-Subscription-Summary-Payment-Details-Tab)
+ [Self Service Pages](https://maxio.zendesk.com/hc/en-us/articles/24261425318541-Self-Service-Pages) (Allows credit card updates by Subscriber)
+ [Public Signup Pages payment settings](https://maxio.zendesk.com/hc/en-us/articles/24261368332557-Individual-Page-Settings)
+ [Taxes](https://developers.chargify.com/docs/developer-docs/d2e9e34db740e-signups#taxes)
+ [Maxio.js (formerly Chargify.js)](https://docs.maxio.com/hc/en-us/articles/38163190843789-Chargify-js-Overview)
+ [Maxio.js with GoCardless - minimal example](https://docs.maxio.com/hc/en-us/articles/38206331271693-Examples#h_01K0PJ15QQZKCER8CFK40MR6XJ)
+ [Maxio.js with GoCardless - full example](https://docs.maxio.com/hc/en-us/articles/38206331271693-Examples#h_01K0PJ15QR09JVHWW0MCA7HVJV)
+ [Maxio.js with Stripe Direct Debit - minimal example](https://docs.maxio.com/hc/en-us/articles/38206331271693-Examples#h_01K0PJ15QQFKKN8Z7B7DZ9AJS5)
+ [Maxio.js with Stripe Direct Debit - full example](https://docs.maxio.com/hc/en-us/articles/38206331271693-Examples#h_01K0PJ15QRECQQ4ECS3ZA55GY7)
+ [Maxio.js with Stripe BECS Direct Debit - minimal example](https://developers.chargify.com/docs/developer-docs/ZG9jOjE0NjAzNDIy-examples#minimal-example-with-sepa-or-becs-direct-debit-stripe-gateway)
+ [Maxio.js with Stripe BECS Direct Debit - full example](https://developers.chargify.com/docs/developer-docs/ZG9jOjE0NjAzNDIy-examples#full-example-with-sepa-direct-debit-stripe-gateway)
+ [Full documentation on GoCardless](https://maxio.zendesk.com/hc/en-us/articles/24176159136909-GoCardless)
+ [Full documentation on Stripe SEPA Direct Debit](https://maxio.zendesk.com/hc/en-us/articles/24176170430093-Stripe-SEPA-and-BECS-Direct-Debit)
+ [Full documentation on Stripe BECS Direct Debit](https://maxio.zendesk.com/hc/en-us/articles/24176170430093-Stripe-SEPA-and-BECS-Direct-Debit)
+ [Full documentation on Stripe BACS Direct Debit](https://maxio.zendesk.com/hc/en-us/articles/24176170430093-Stripe-SEPA-and-BECS-Direct-Debit)
## 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.
```http
POST /payment_profiles.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `body` | [`Create Payment Profile Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/create-payment-profile-request) | Body, Optional | When following the IBAN or the Local Bank details examples, a customer, bank account and mandate will be created in your current vault. If the customer, bank account, and mandate already exist in your vault, follow the Import example to link the payment profile into Advanced Billing. |
# Response Type
**200**: OK
[`Payment Profile Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/payment-profile-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/payment_profiles.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"payment_profile": {
"customer_id": 1036,
"chargify_token": "tok_w68qcpnftyv53jk33jv6wk3w"
}
}'
```
# Example Response *(as JSON)*
```json
{
"payment_profile": {
"first_name": "Jessica",
"last_name": "Test",
"card_type": "visa",
"masked_card_number": "XXXX-XXXX-XXXX-1111",
"expiration_month": 10,
"expiration_year": 2018,
"customer_id": 19195410,
"current_vault": "bogus",
"vault_token": "1",
"billing_address": "123 Main St.",
"billing_city": "Boston",
"billing_state": "MA",
"billing_zip": "02120",
"billing_country": "US",
"customer_vault_token": null,
"billing_address_2": null,
"payment_type": "credit_card",
"site_gateway_setting_id": 1,
"gateway_handle": "handle",
"disabled": false
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### List Payment Profiles
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/payment-profiles/list-payment-profiles
Lists all active payment profiles for a site, or for one customer within a site. If no payment profiles are found, this endpoint returns an empty array.
```http
GET /payment_profiles.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query `per_page=200`.
**Default**: `20`
**Constraints**: `<= 200` |
| `customer_id` | `Number` | Query, Optional | The ID of the customer for which you wish to list payment profiles |
# Response Type
**200**: OK
[`array`](https://developers.maxio.com/http/advanced-billing-api/models/structures/payment-profile-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/payment_profiles.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'page=1' \
-d 'per_page=50'
```
# Example Response *(as JSON)*
```json
[
{
"payment_profile": {
"id": 10089892,
"first_name": "Chester",
"last_name": "Tester",
"created_at": "2025-01-01T00:00:00-05:00",
"updated_at": "2025-01-01T00:00:00-05:00",
"customer_id": 14543792,
"current_vault": "bogus",
"vault_token": "0011223344",
"billing_address": "456 Juniper Court",
"billing_city": "Boulder",
"billing_state": "CO",
"billing_zip": "80302",
"billing_country": "US",
"customer_vault_token": null,
"billing_address_2": "",
"bank_name": "Bank of Kansas City",
"masked_bank_routing_number": "XXXX6789",
"masked_bank_account_number": "XXXX3344",
"bank_account_type": "checking",
"bank_account_holder_type": "personal",
"payment_type": "bank_account",
"verified": true,
"site_gateway_setting_id": 1,
"gateway_handle": "handle"
}
},
{
"payment_profile": {
"id": 10188522,
"first_name": "Frankie",
"last_name": "Tester",
"created_at": "2025-01-01T00:00:00-05:00",
"updated_at": "2025-01-01T00:00:00-05:00",
"customer_id": 14543712,
"current_vault": "bogus",
"vault_token": "123456789",
"billing_address": "123 Montana Way",
"billing_city": "Los Angeles",
"billing_state": "CA",
"billing_zip": "90210",
"billing_country": "US",
"customer_vault_token": null,
"billing_address_2": "",
"bank_name": "Bank of Kansas City",
"masked_bank_routing_number": "XXXX6789",
"masked_bank_account_number": "XXXX6789",
"bank_account_type": "checking",
"bank_account_holder_type": "personal",
"payment_type": "bank_account",
"verified": true,
"site_gateway_setting_id": 1,
"gateway_handle": "handle"
}
}
]
```
##### Read Payment Profile
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/payment-profiles/read-payment-profile
Returns a payment profile identified by its unique ID.
Note that a different JSON object will be returned if the card method on file is a bank account.
### Response for Bank Account
Example response for Bank Account:
```
{
"payment_profile": {
"id": 10089892,
"first_name": "Chester",
"last_name": "Tester",
"created_at": "2025-01-01T00:00:00-05:00",
"updated_at": "2025-01-01T00:00:00-05:00",
"customer_id": 14543792,
"current_vault": "bogus",
"vault_token": "0011223344",
"billing_address": "456 Juniper Court",
"billing_city": "Boulder",
"billing_state": "CO",
"billing_zip": "80302",
"billing_country": "US",
"customer_vault_token": null,
"billing_address_2": "",
"bank_name": "Bank of Kansas City",
"masked_bank_routing_number": "XXXX6789",
"masked_bank_account_number": "XXXX3344",
"bank_account_type": "checking",
"bank_account_holder_type": "personal",
"payment_type": "bank_account",
"site_gateway_setting_id": 1,
"gateway_handle": null
}
}
```
```http
GET /payment_profiles/{payment_profile_id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `payment_profile_id` | `Number` | Template, Required | The Chargify id of the payment profile |
# Response Type
**200**: OK
[`Payment Profile Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/payment-profile-response)
# Example Usage
```bash
curl -X GET \
--url 'https://subdomain.chargify.com/payment_profiles/198.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"payment_profile": {
"id": 10088716,
"first_name": "Test",
"last_name": "Subscription",
"masked_card_number": "XXXX-XXXX-XXXX-1",
"card_type": "bogus",
"expiration_month": 1,
"expiration_year": 2022,
"created_at": "2025-01-01T00:00:00-05:00",
"updated_at": "2025-01-01T00:00:00-05:00",
"customer_id": 14543792,
"current_vault": "bogus",
"vault_token": "1",
"billing_address": "123 Montana Way",
"billing_city": "Billings",
"billing_state": "MT",
"billing_zip": "59101",
"billing_country": "US",
"customer_vault_token": null,
"billing_address_2": "",
"payment_type": "credit_card",
"site_gateway_setting_id": 1,
"gateway_handle": null
}
}
```
# Errors
| HTTP Status Code | Error Description |
| --- | --- |
| 404 | Not Found |
##### Update Payment Profile
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/payment-profiles/update-payment-profile
Updates a payment profile.
## Partial Card Updates
In the event that you are using the Authorize.net, Stripe, Cybersource, Forte or Braintree Blue payment gateways, you can update just the billing and contact information for a payment method. Note the lack of credit-card related data contained in the JSON payload.
In this case, the following JSON is acceptable:
```
{
"payment_profile": {
"first_name": "Kelly",
"last_name": "Test",
"billing_address": "789 Juniper Court",
"billing_city": "Boulder",
"billing_state": "CO",
"billing_zip": "80302",
"billing_country": "US",
"billing_address_2": null
}
}
```
The result will be that you have updated the billing information for the card, yet retained the original card number data.
## Specific notes on updating payment profiles
- Merchants with **Authorize.net**, **Cybersource**, **Forte**, **Braintree Blue** or **Stripe** as their payment gateway can update their Customer’s credit cards without passing in the full credit card number and CVV.
- If you are using **Authorize.net**, **Cybersource**, **Forte**, **Braintree Blue** or **Stripe**, Advanced Billing will ignore the credit card number and CVV when processing an update via the API, and attempt a partial update instead. If you wish to change the card number on a payment profile, you will need to create a new payment profile for the given customer.
- A Payment Profile cannot be updated with the attributes of another type of Payment Profile. For example, if the payment profile you are attempting to update is a credit card, you cannot pass in bank account attributes (like `bank_account_number`), and vice versa.
- Updating a payment profile directly will not trigger an attempt to capture a past-due balance. If this is the intent, update the card details via the Subscription instead.
- If you are using Authorize.net or Stripe, you may elect to manually trigger a retry for a past due subscription after a partial update.
```http
PUT /payment_profiles/{payment_profile_id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `payment_profile_id` | `Number` | Template, Required | The Chargify id of the payment profile |
| `body` | [`Update Payment Profile Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/update-payment-profile-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Payment Profile Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/payment-profile-response)
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/payment_profiles/198.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"payment_profile": {
"first_name": "Graham",
"last_name": "Test",
"billing_address": "456 Juniper Court",
"billing_city": "Boulder",
"billing_state": "CO",
"billing_zip": "80302",
"billing_country": "US",
"billing_address_2": "billing_address_22"
}
}'
```
# Example Response *(as JSON)*
```json
{
"payment_profile": {
"id": 10088716,
"first_name": "Test",
"last_name": "Subscription",
"billing_address": "123 Montana Way",
"billing_city": "Billings",
"billing_state": "MT",
"billing_zip": "59101",
"billing_country": "US",
"billing_address_2": "",
"payment_type": "bank_account"
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | |
| 422 | Unprocessable Entity (WebDAV) | [`Error String Map ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-string-map-response) |
##### Delete Unused Payment Profile
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/payment-profiles/delete-unused-payment-profile
Deletes an unused payment profile.
If the payment profile is in use by one or more subscriptions or groups, an error message is returned.
```http
DELETE /payment_profiles/{payment_profile_id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `payment_profile_id` | `Number` | Template, Required | The Chargify id of the payment profile |
# Response Type
**204**: No Content
`Void`
# Example Usage
```bash
curl -X DELETE \
--url 'https://subdomain.chargify.com/payment_profiles/198.json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Delete Subscriptions Payment Profile
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/payment-profiles/delete-subscriptions-payment-profile
Deletes a payment profile belonging to the customer on the subscription.
If the customer has multiple subscriptions, the payment profile is removed from all of them.
If you delete the default payment profile for a subscription, you need to specify another payment profile to be the default through the API, or either prompt the user to enter a card in the billing portal or on the self-service page, or visit the Payment Details tab on the subscription in the Admin UI and use the “Add New Credit Card” or “Make Active Payment Method” link, (depending on whether there are other cards present).
```http
DELETE /subscriptions/{subscription_id}/payment_profiles/{payment_profile_id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `payment_profile_id` | `Number` | Template, Required | The Chargify id of the payment profile |
# Response Type
**204**: No Content
`Void`
# Example Usage
```bash
curl -X DELETE \
--url 'https://subdomain.chargify.com/subscriptions/222/payment_profiles/198.json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
##### Verify Bank Account
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/payment-profiles/verify-bank-account
Verifies a bank account. Submit the two small deposit amounts the customer received in their bank account to verify the bank account. (Stripe only)
```http
PUT /bank_accounts/{bank_account_id}/verification.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `bank_account_id` | `Number` | Template, Required | Identifier of the bank account in the system. |
| `body` | [`Bank Account Verification Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/bank-account-verification-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Bank Account Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/bank-account-response)
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/bank_accounts/252/verification.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"bank_account_verification": {
"deposit_1_in_cents": 32,
"deposit_2_in_cents": 45
}
}'
```
# Example Response *(as JSON)*
```json
{
"payment_profile": {
"id": 10089892,
"first_name": "John",
"last_name": "Doe",
"customer_id": 14543792,
"current_vault": "stripe_connect",
"vault_token": "cus_0123abc456def",
"billing_address": "456 Juniper Court",
"billing_city": "Boulder",
"billing_state": "CO",
"billing_zip": "80302",
"billing_country": "US",
"customer_vault_token": null,
"billing_address_2": "",
"bank_name": "Bank of Kansas City",
"masked_bank_routing_number": "XXXX6789",
"masked_bank_account_number": "XXXX3344",
"bank_account_type": "checking",
"bank_account_holder_type": "personal",
"payment_type": "bank_account"
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Delete Subscription Group Payment Profile
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/payment-profiles/delete-subscription-group-payment-profile
Deletes a Payment Profile belonging to a Subscription Group.
**Note**: If the Payment Profile belongs to multiple Subscription Groups and/or Subscriptions, it will be removed from all of them.
```http
DELETE /subscription_groups/{uid}/payment_profiles/{payment_profile_id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `uid` | `String` | Template, Required | The uid of the subscription group |
| `payment_profile_id` | `Number` | Template, Required | The Chargify id of the payment profile |
# Response Type
**204**: No Content
`Void`
# Example Usage
```bash
curl -X DELETE \
--url 'https://subdomain.chargify.com/subscription_groups/uid0/payment_profiles/198.json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
##### Change Subscription Default Payment Profile
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/payment-profiles/change-subscription-default-payment-profile
Changes the default payment profile on the subscription to the existing payment profile with the specified ID.
You must elect to change the existing payment profile to a new payment profile ID in order to receive a satisfactory response from this endpoint.
```http
POST /subscriptions/{subscription_id}/payment_profiles/{payment_profile_id}/change_payment_profile.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `payment_profile_id` | `Number` | Template, Required | The Chargify id of the payment profile |
# Response Type
**201**: Created
[`Payment Profile Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/payment-profile-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscriptions/222/payment_profiles/198/change_payment_profile.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"payment_profile": {
"id": 10211899,
"first_name": "Amelia",
"last_name": "Example",
"masked_card_number": "XXXX-XXXX-XXXX-1",
"card_type": "bogus",
"expiration_month": 2,
"expiration_year": 2018,
"customer_id": 14399371,
"current_vault": "bogus",
"vault_token": "1",
"billing_address": "",
"billing_city": "",
"billing_state": "",
"billing_zip": "",
"billing_country": "",
"customer_vault_token": null,
"billing_address_2": "",
"payment_type": "credit_card",
"site_gateway_setting_id": 1,
"gateway_handle": null
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Change Subscription Group Default Payment Profile
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/payment-profiles/change-subscription-group-default-payment-profile
Changes the default payment profile on the subscription group to the existing payment profile with the specified ID.
You must elect to change the existing payment profile to a new payment profile ID in order to receive a satisfactory response from this endpoint.
The new payment profile must belong to the subscription group's customer, otherwise you will receive an error.
```http
POST /subscription_groups/{uid}/payment_profiles/{payment_profile_id}/change_payment_profile.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `uid` | `String` | Template, Required | The uid of the subscription group |
| `payment_profile_id` | `Number` | Template, Required | The Chargify id of the payment profile |
# Response Type
**201**: Created
[`Payment Profile Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/payment-profile-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscription_groups/uid0/payment_profiles/198/change_payment_profile.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"payment_profile": {
"id": 10211899,
"first_name": "Amelia",
"last_name": "Example",
"masked_card_number": "XXXX-XXXX-XXXX-1",
"card_type": "bogus",
"expiration_month": 2,
"expiration_year": 2018,
"customer_id": 14399371,
"current_vault": "bogus",
"vault_token": "1",
"billing_address": "",
"billing_city": "",
"billing_state": "",
"billing_zip": "",
"billing_country": "",
"customer_vault_token": null,
"billing_address_2": "",
"payment_type": "credit_card",
"site_gateway_setting_id": 1,
"gateway_handle": null
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Read One Time Token
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/payment-profiles/read-one-time-token
Returns the one-time token data, including credit card or ACH details, associated with the provided token ID. One Time Tokens aka Advanced Billing Tokens house the credit card or ACH (Authorize.Net or Stripe only) data for a customer.
You can use One Time Tokens while creating a subscription or payment profile instead of passing all bank account or credit card data directly to a given API endpoint.
To obtain a One Time Token you have to use [Chargify.js](https://docs.maxio.com/hc/en-us/articles/38163190843789-Chargify-js-Overview#chargify-js-overview-0-0).
```http
GET /one_time_tokens/{chargify_token}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `chargify_token` | `String` | Template, Required | Advanced Billing Token |
# Response Type
**200**: OK
[`Get One Time Token Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/get-one-time-token-request)
# Example Usage
```bash
curl -X GET \
--url 'https://subdomain.chargify.com/one_time_tokens/chargify_token8.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Send Request Update Payment Email
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/payment-profiles/send-request-update-payment-email
Sends a "request payment update" email to the customer associated with the subscription.
If you attempt to send a "request payment update" email more than five times within a 30-minute period, you will receive a `422` response with an error message in the body. This error message will indicate that the request has been rejected due to excessive attempts, and will provide instructions on how to resubmit the request.
Additionally, if you attempt to send a "request payment update" email for a subscription that does not exist, you will receive a `404` error response. This error message will indicate that the subscription could not be found, and will provide instructions on how to correct the error and resubmit the request.
These error responses are designed to prevent excessive or invalid requests, and to provide clear and helpful information to users who encounter errors during the request process.
```http
POST /subscriptions/{subscription_id}/request_payment_profiles_update.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
# Response Type
**201**: Created
`Void`
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscriptions/222/request_payment_profiles_update.json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
#### Product Families
##### List Products for Product Family
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/product-families/list-products-for-product-family
Retrieves a list of Products belonging to a Product Family.
```http
GET /product_families/{product_family_id}/products.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `product_family_id` | `String` | Template, Required | Either the product family's id or its handle prefixed with `handle:` |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query `per_page=200`.
**Default**: `20`
**Constraints**: `<= 200` |
| `date_field` | [`Basic Date Field`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/basic-date-field) | Query, Optional | The type of filter you would like to apply to your search. Use in query: `date_field=created_at`. |
| `filter` | [`List Products Filter`](https://developers.maxio.com/http/advanced-billing-api/models/structures/list-products-filter) | Query, Optional | Filter to use for List Products operations |
| `start_date` | `Date` | Query, Optional | The start date (format YYYY-MM-DD) with which to filter the date_field. Returns products with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified. |
| `end_date` | `Date` | Query, Optional | The end date (format YYYY-MM-DD) with which to filter the date_field. Returns products with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified. |
| `start_datetime` | `DateTime` | Query, Optional | The start date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns products with a timestamp at or after exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of start_date. |
| `end_datetime` | `DateTime` | Query, Optional | The end date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns products with a timestamp at or before exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of end_date. |
| `include_archived` | `Boolean` | Query, Optional | Include archived products. |
| `include` | [`List Products Include`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/list-products-include) | Query, Optional | Allows including additional data in the response. Use in query `include=prepaid_product_price_point`. |
# Response Type
**200**: OK
[`array`](https://developers.maxio.com/http/advanced-billing-api/models/structures/product-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/product_families/product_family_id4/products.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'page=1' \
-d 'per_page=50' \
-d 'date_field=updated_at' \
-d 'filter[ids]=1%2C2%2C3' \
-d 'include=prepaid_product_price_point'
```
# Example Response *(as JSON)*
```json
[
{
"product": {
"id": 3801242,
"name": "Free product",
"handle": "zero-dollar-product",
"description": "",
"accounting_code": "",
"request_credit_card": true,
"expiration_interval": null,
"expiration_interval_unit": "never",
"created_at": "2016-04-21T16:08:39-04:00",
"updated_at": "2016-08-03T11:27:53-04:00",
"price_in_cents": 10000,
"interval": 1,
"interval_unit": "month",
"initial_charge_in_cents": 0,
"trial_price_in_cents": null,
"trial_interval": null,
"trial_interval_unit": "month",
"archived_at": null,
"require_credit_card": false,
"return_params": "",
"taxable": false,
"update_return_url": "",
"initial_charge_after_trial": false,
"version_number": 4,
"update_return_params": "",
"product_family": {
"id": 527890,
"name": "Acme Projects",
"description": "",
"handle": "billing-plans",
"accounting_code": null
},
"public_signup_pages": [
{
"id": 283460,
"return_url": null,
"return_params": "",
"url": "https://general-goods.chargify.com/subscribe/smcc4j3d2w6h/zero-dollar-product"
}
],
"product_price_point_name": "Default",
"use_site_exchange_rate": true
}
},
{
"product": {
"id": 3858146,
"name": "Calendar Billing Product",
"handle": "calendar-billing-product",
"description": "",
"accounting_code": "",
"request_credit_card": true,
"expiration_interval": null,
"expiration_interval_unit": "never",
"created_at": "2016-07-05T13:07:38-04:00",
"updated_at": "2016-07-05T13:07:38-04:00",
"price_in_cents": 10000,
"interval": 1,
"interval_unit": "month",
"initial_charge_in_cents": null,
"trial_price_in_cents": null,
"trial_interval": null,
"trial_interval_unit": "month",
"archived_at": null,
"require_credit_card": true,
"return_params": "",
"taxable": false,
"update_return_url": "",
"initial_charge_after_trial": false,
"version_number": 1,
"update_return_params": "",
"product_family": {
"id": 527890,
"name": "Acme Projects",
"description": "",
"handle": "billing-plans",
"accounting_code": null
},
"public_signup_pages": [
{
"id": 289193,
"return_url": "",
"return_params": "",
"url": "https://general-goods.chargify.com/subscribe/gxdbfxzxhcjq/calendar-billing-product"
}
],
"product_price_point_name": "Default",
"use_site_exchange_rate": true
}
}
]
```
# Errors
| HTTP Status Code | Error Description |
| --- | --- |
| 404 | Not Found |
##### Create Product Family
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/product-families/create-product-family
Creates a Product Family within your site. Create a Product Family to act as a container for your products, components, and coupons.
Full documentation on how Product Families operate within the Advanced Billing UI can be located [here](https://maxio.zendesk.com/hc/en-us/articles/24261098936205-Product-Families).
```http
POST /product_families.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `body` | [`Create Product Family Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/create-product-family-request) | Body, Optional | - |
# Response Type
**201**: Created
[`Product Family Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/product-family-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/product_families.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"product_family": {
"name": "Acme Projects",
"description": "Amazing project management tool",
"surcharging": false
}
}'
```
# Example Response *(as JSON)*
```json
{
"product_family": {
"id": 933860,
"name": "Acme Projects",
"description": "Amazing project management tool",
"handle": "acme-projects",
"accounting_code": null,
"surcharging": false
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### List Product Families
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/product-families/list-product-families
Lists Product Families for a site.
```http
GET /product_families.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `date_field` | [`Basic Date Field`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/basic-date-field) | Query, Optional | The type of filter you would like to apply to your search. Use in query: `date_field=created_at`. |
| `start_date` | `Date` | Query, Optional | The start date (format YYYY-MM-DD) with which to filter the date_field. Returns products with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified. |
| `end_date` | `Date` | Query, Optional | The end date (format YYYY-MM-DD) with which to filter the date_field. Returns products with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified. |
| `start_datetime` | `DateTime` | Query, Optional | The start date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns products with a timestamp at or after exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of start_date. |
| `end_datetime` | `DateTime` | Query, Optional | The end date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns products with a timestamp at or before exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of end_date. |
# Response Type
**200**: OK
[`array`](https://developers.maxio.com/http/advanced-billing-api/models/structures/product-family-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/product_families.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'date_field=updated_at'
```
# Example Response *(as JSON)*
```json
[
{
"product_family": {
"id": 37,
"name": "Acme Projects",
"description": null,
"handle": "acme-projects",
"accounting_code": null,
"surcharging": false,
"created_at": "2013-02-20T15:05:51-07:00",
"updated_at": "2013-02-20T15:05:51-07:00",
"archived_at": null
}
},
{
"product_family": {
"id": 155,
"name": "Bat Family",
"description": "Another family.",
"handle": "bat-family",
"accounting_code": null,
"surcharging": true,
"created_at": "2014-04-16T12:41:13-06:00",
"updated_at": "2014-04-16T12:41:13-06:00",
"archived_at": "2024-11-05T09:30:00-07:00"
}
}
]
```
##### Read Product Family
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/product-families/read-product-family
Retrieves a Product Family via the `product_family_id`. The response will contain a Product Family object.
The product family can be specified either with the id number, or with the `handle:my-family` format.
```http
GET /product_families/{id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `id` | `Number` | Template, Required | The Advanced Billing id of the product family |
# Response Type
**200**: OK
[`Product Family Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/product-family-response)
# Example Usage
```bash
curl -X GET \
--url 'https://subdomain.chargify.com/product_families/112.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"product_family": {
"id": 527890,
"name": "Acme Projects",
"description": "",
"handle": "billing-plans",
"accounting_code": null,
"surcharging": false,
"archived_at": null
}
}
```
#### Product Features
##### List Product Features
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/product-features/list-product-features
Returns the feature catalog items attached to this product, including price-point-specific overrides.
```http
GET /products/{product_id}/features.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `product_id` | `Number` | Template, Required | The Advanced Billing id of the product. |
# Response Type
**200**: OK
[`Feature Catalog Items List Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/feature-catalog-items-list-response)
# Example Usage
```bash
curl -X GET \
--url 'https://subdomain.chargify.com/products/202/features.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 403 | Forbidden | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
| 404 | Not Found | |
##### Create Product Feature
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/product-features/create-product-feature
Attaches a feature template to this product with a concrete value. Pass `price_point_type: "ProductPricePoint"` and `price_point_id` to create an override scoped to a single product price point instead of the whole product.
```http
POST /products/{product_id}/features.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `product_id` | `Number` | Template, Required | The Advanced Billing id of the product. |
| `body` | [`Create Feature Catalog Item Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/create-feature-catalog-item-request) | Body, Optional | The owning product or component is taken from the URL and must not be included in the request body. |
# Response Type
**201**: Created
[`Feature Catalog Item Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/feature-catalog-item-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/products/202/features.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"feature": {
"feature_template_id": 196,
"value": "value6",
"propagate_to_subscriptions": false
}
}'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 403 | Forbidden | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
| 404 | Not Found | |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Read Product Feature
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/product-features/read-product-feature
Returns a single feature catalog item attached to this product.
```http
GET /products/{product_id}/features/{id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `product_id` | `Number` | Template, Required | The Advanced Billing id of the product. |
| `id` | `Number` | Template, Required | The Advanced Billing id of the feature catalog item. |
# Response Type
**200**: OK
[`Feature Catalog Item Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/feature-catalog-item-response)
# Example Usage
```bash
curl -X GET \
--url 'https://subdomain.chargify.com/products/202/features/112.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 403 | Forbidden | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
| 404 | Not Found | |
##### Update Product Feature
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/product-features/update-product-feature
Updates the value or periodicity of a feature catalog item attached to this product.
```http
PUT /products/{product_id}/features/{id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `product_id` | `Number` | Template, Required | The Advanced Billing id of the product. |
| `id` | `Number` | Template, Required | The Advanced Billing id of the feature catalog item. |
| `body` | [`Update Feature Catalog Item Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/update-feature-catalog-item-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Feature Catalog Item Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/feature-catalog-item-response)
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/products/202/features/112.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"feature": {
"propagate_to_subscriptions": false
}
}'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 403 | Forbidden | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
| 404 | Not Found | |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Remove Product Feature
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/product-features/remove-product-feature
Removes a feature catalog item from this product.
```http
DELETE /products/{product_id}/features/{id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `product_id` | `Number` | Template, Required | The Advanced Billing id of the product. |
| `id` | `Number` | Template, Required | The Advanced Billing id of the feature catalog item. |
| `destroy_entitlements` | `Boolean` | Query, Optional | When `true`, permanently deletes this feature catalog item and every entitlement it created, revoking subscriber access immediately. When `false` (default), the feature catalog item is archived and existing entitlements are preserved.
**Default**: `false` |
# Response Type
**204**: No Content
`Void`
# Example Usage
```bash
curl -X DELETE -G \
--url 'https://subdomain.chargify.com/products/202/features/112.json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'destroy_entitlements=false'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 403 | Forbidden | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
| 404 | Not Found | |
##### Restore Product Feature
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/product-features/restore-product-feature
Returns `422` if the parent feature template is still archived — restore the feature template first.
```http
POST /products/{product_id}/features/{id}/restore.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `product_id` | `Number` | Template, Required | The Advanced Billing id of the product. |
| `id` | `Number` | Template, Required | The Advanced Billing id of the feature catalog item. |
# Response Type
**200**: OK
[`Feature Catalog Item Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/feature-catalog-item-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/products/202/features/112/restore.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 403 | Forbidden | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
| 404 | Not Found | |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
#### Products
##### Create Product
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/products/create-product
Creates a product in your site.
If you have the new [Catalog experience](https://developers.maxio.com/http/help/announcements/2026-announcements#new-catalog-experience-and-terminology) enabled, the `auto_create_signup_page` parameter is not supported. If `auto_create_signup_page` is included (with any value) an error is returned.
For more information, see:
+ [Products Overview](https://maxio.zendesk.com/hc/en-us/articles/24261090117645-Products-Overview)
+ [Changing a Subscription's Product](https://maxio.zendesk.com/hc/en-us/articles/24252069837581-Product-Changes-and-Migrations)
```http
POST /product_families/{product_family_id}/products.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `product_family_id` | `String` | Template, Required | Either the product family's id or its handle prefixed with `handle:` |
| `body` | [`Create or Update Product Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/create-or-update-product-request) | Body, Optional | - |
# Response Type
**201**: Created
[`Product Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/product-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/product_families/product_family_id4/products.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"product": {
"name": "Gold Plan",
"handle": "gold",
"description": "This is our gold plan.",
"accounting_code": "123",
"require_credit_card": true,
"price_in_cents": 1000,
"interval": 1,
"interval_unit": "month",
"auto_create_signup_page": true,
"tax_code": "D0000000"
}
}'
```
# Example Response *(as JSON)*
```json
{
"product": {
"id": 4364984,
"name": "Gold Plan",
"handle": "gold",
"description": "This is our gold plan.",
"accounting_code": "123",
"request_credit_card": true,
"created_at": "2016-11-04T16:31:15-04:00",
"updated_at": "2016-11-04T16:31:15-04:00",
"price_in_cents": 1000,
"interval": 1,
"interval_unit": "month",
"expiration_interval_unit": null,
"initial_charge_in_cents": null,
"trial_price_in_cents": null,
"trial_interval": null,
"trial_interval_unit": null,
"archived_at": null,
"require_credit_card": true,
"return_params": null,
"taxable": false,
"update_return_url": null,
"initial_charge_after_trial": false,
"version_number": 1,
"update_return_params": null,
"product_family": {
"id": 527890,
"name": "Acme Projects",
"description": "",
"handle": "billing-plans",
"accounting_code": null
},
"public_signup_pages": [
{
"id": 301078,
"return_url": null,
"return_params": null,
"url": "https://general-goods.chargify.com/subscribe/ftgbpq7f5qpr/gold"
}
],
"product_price_point_name": "Default"
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Read Product
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/products/read-product
Reads the current details of a product.
```http
GET /products/{product_id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `product_id` | `Number` | Template, Required | The Advanced Billing id of the product |
| `include_features` | `Boolean` | Query, Optional | When `true`, embeds the active feature catalog items for each result in a `features` array. Default value is `false`.
**Default**: `false` |
# Response Type
**200**: OK
[`Product Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/product-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/products/202.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'include_features=false'
```
# Example Response *(as JSON)*
```json
{
"product": {
"id": 4535635,
"name": "Paid Annual Seats",
"handle": "paid-annual-seats",
"description": "Paid annual seats for our commercial enterprise product",
"accounting_code": "paid-annual-seats",
"request_credit_card": true,
"expiration_interval": 1,
"expiration_interval_unit": "day",
"created_at": "2017-08-25T10:25:31-05:00",
"updated_at": "2018-01-16T12:58:04-06:00",
"price_in_cents": 10000,
"interval": 12,
"interval_unit": "month",
"initial_charge_in_cents": 4900,
"trial_price_in_cents": 1000,
"trial_interval": 14,
"trial_interval_unit": "day",
"archived_at": null,
"require_credit_card": true,
"return_params": "id={subscription_id}&ref={customer_reference}",
"taxable": true,
"update_return_url": "http://www.example.com",
"tax_code": "D0000000",
"initial_charge_after_trial": false,
"version_number": 4,
"update_return_params": "id={subscription_id}&ref={customer_reference}",
"product_family": {
"id": 1025627,
"name": "Acme Products",
"description": "",
"handle": "acme-products",
"accounting_code": null
},
"product_price_point_name": "Default"
}
}
```
##### Update Product
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/products/update-product
Updates aspects of an existing product.
### Input Attributes Update Notes
+ `update_return_params` The parameters we will append to your `update_return_url`. See Return URLs and Parameters
### Product Price Point
Updating a product using this endpoint will create a new price point and set it as the default price point for this product. If you should like to update an existing product price point, that must be done separately.
```http
PUT /products/{product_id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `product_id` | `Number` | Template, Required | The Advanced Billing id of the product |
| `body` | [`Create or Update Product Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/create-or-update-product-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Product Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/product-response)
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/products/202.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"product": {
"id": 4365034,
"name": "Platinum Plan",
"handle": "platinum",
"description": "This is our platinum plan.",
"accounting_code": "123",
"request_credit_card": true,
"created_at": "2016-11-04T16:34:29-04:00",
"updated_at": "2016-11-04T16:37:11-04:00",
"price_in_cents": 1000,
"interval": 1,
"interval_unit": "month",
"initial_charge_in_cents": null,
"trial_price_in_cents": null,
"trial_interval": null,
"trial_interval_unit": null,
"archived_at": null,
"require_credit_card": true,
"return_params": null,
"taxable": false,
"update_return_url": null,
"initial_charge_after_trial": false,
"version_number": 1,
"update_return_params": null,
"product_family": {
"id": 527890,
"name": "Acme Projects",
"description": "",
"handle": "billing-plans",
"accounting_code": null
},
"public_signup_pages": [
{
"id": 301079,
"return_url": null,
"return_params": null,
"url": "https://general-goods.chargify.com/subscribe/wgyd96tb5pj9/platinum"
}
],
"product_price_point_name": "Original"
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Archive Product
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/products/archive-product
Archives the product. All current subscribers will be unaffected; their subscription/purchase will continue to be charged monthly.
This will restrict the option to chose the product for purchase via the Billing Portal, as well as disable Public Signup Pages for the product.
```http
DELETE /products/{product_id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `product_id` | `Number` | Template, Required | The Advanced Billing id of the product |
# Response Type
**200**: OK
[`Product Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/product-response)
# Example Usage
```bash
curl -X DELETE \
--url 'https://subdomain.chargify.com/products/202.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"product": {
"id": 4535638,
"name": "Business Monthly",
"handle": null,
"description": "Business Monthly",
"accounting_code": "",
"request_credit_card": true,
"expiration_interval": null,
"expiration_interval_unit": "never",
"created_at": "2017-08-25T10:25:31-05:00",
"updated_at": "2018-01-16T13:02:44-06:00",
"price_in_cents": 4900,
"interval": 1,
"interval_unit": "month",
"initial_charge_in_cents": null,
"trial_price_in_cents": 0,
"trial_interval": 1,
"trial_interval_unit": "day",
"archived_at": "2018-01-16T13:02:44-06:00",
"require_credit_card": false,
"return_params": "",
"taxable": false,
"update_return_url": "",
"tax_code": "",
"initial_charge_after_trial": false,
"version_number": 1,
"update_return_params": "",
"product_family": {
"id": 1025627,
"name": "Acme Products",
"description": "",
"handle": "acme-products",
"accounting_code": null
},
"product_price_point_name": "Default"
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Read Product by Handle
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/products/read-product-by-handle
Retrieves a Product object by its `api_handle`.
```http
GET /products/handle/{api_handle}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `api_handle` | `String` | Template, Required | The handle of the product |
# Response Type
**200**: OK
[`Product Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/product-response)
# Example Usage
```bash
curl -X GET \
--url 'https://subdomain.chargify.com/products/handle/api_handle6.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"product": {
"id": 3903594,
"name": "No cost product",
"handle": "no-cost-product",
"description": "",
"accounting_code": "",
"request_credit_card": true,
"expiration_interval": null,
"expiration_interval_unit": "never",
"created_at": "2016-09-02T17:11:29-04:00",
"updated_at": "2016-11-30T11:46:13-05:00",
"price_in_cents": 0,
"interval": 1,
"interval_unit": "month",
"initial_charge_in_cents": null,
"trial_price_in_cents": 5,
"trial_interval": 1,
"trial_interval_unit": "month",
"archived_at": null,
"require_credit_card": false,
"return_params": "reference=5678",
"taxable": false,
"update_return_url": "",
"initial_charge_after_trial": false,
"version_number": 1,
"update_return_params": "reference=5678",
"product_family": {
"id": 527890,
"name": "Acme Projects",
"description": "",
"handle": "billing-plans",
"accounting_code": null
},
"public_signup_pages": [
{
"id": 281174,
"return_url": "",
"return_params": "",
"url": "https://general-goods.chargify.com/subscribe/xgdxtk4vhtbz/no-cost-product"
},
{
"id": 282270,
"return_url": "",
"return_params": "",
"url": "https://general-goods.chargify.com/subscribe/xxqmrgtsbd9k/no-cost-product"
},
{
"id": 291587,
"return_url": "",
"return_params": "",
"url": "https://general-goods.chargify.com/subscribe/pvhwss7zjjnh/no-cost-product"
},
{
"id": 294832,
"return_url": "http://www.example.com/",
"return_params": "engine=md7a",
"url": "https://general-goods.chargify.com/subscribe/m6tbcq4mcgpw/no-cost-product"
}
],
"product_price_point_name": "Default"
}
}
```
##### List Products
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/products/list-products
Lists products belonging to a site.
```http
GET /products.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `date_field` | [`Basic Date Field`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/basic-date-field) | Query, Optional | The type of filter you would like to apply to your search. Use in query: `date_field=created_at`. |
| `filter` | [`List Products Filter`](https://developers.maxio.com/http/advanced-billing-api/models/structures/list-products-filter) | Query, Optional | Filter to use for List Products operations |
| `end_date` | `Date` | Query, Optional | The end date (format YYYY-MM-DD) with which to filter the date_field. Returns products with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified. |
| `end_datetime` | `DateTime` | Query, Optional | The end date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns products with a timestamp at or before exact time provided in query. You can specify timezone in query - otherwise your site''s time zone will be used. If provided, this parameter will be used instead of end_date. |
| `start_date` | `Date` | Query, Optional | The start date (format YYYY-MM-DD) with which to filter the date_field. Returns products with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified. |
| `start_datetime` | `DateTime` | Query, Optional | The start date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns products with a timestamp at or after exact time provided in query. You can specify timezone in query - otherwise your site''s time zone will be used. If provided, this parameter will be used instead of start_date. |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query `per_page=200`.
**Default**: `20`
**Constraints**: `<= 200` |
| `include_archived` | `Boolean` | Query, Optional | Include archived products. Use in query: `include_archived=true`. |
| `include` | [`List Products Include`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/list-products-include) | Query, Optional | Allows including additional data in the response. Use in query `include=prepaid_product_price_point`. |
| `include_features` | `Boolean` | Query, Optional | When `true`, embeds the active feature catalog items for each result in a `features` array. Default value is `false`.
**Default**: `false` |
# Response Type
**200**: OK
[`array`](https://developers.maxio.com/http/advanced-billing-api/models/structures/product-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/products.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'date_field=updated_at' \
-d 'filter[ids]=1%2C2%2C3' \
-d 'page=1' \
-d 'per_page=50' \
-d 'include_archived=true' \
-d 'include=prepaid_product_price_point' \
-d 'include_features=false'
```
# Example Response *(as JSON)*
```json
[
{
"product": {
"id": 0,
"name": "string",
"handle": "string",
"description": "string",
"accounting_code": "string",
"request_credit_card": true,
"expiration_interval": 0,
"expiration_interval_unit": "month",
"created_at": "2023-11-23T10:28:34-05:00",
"updated_at": "2023-11-23T10:28:34-05:00",
"price_in_cents": 0,
"interval": 0,
"interval_unit": "month",
"initial_charge_in_cents": 0,
"trial_price_in_cents": 0,
"trial_interval": 0,
"trial_interval_unit": "month",
"archived_at": null,
"require_credit_card": true,
"return_params": "string",
"taxable": true,
"update_return_url": "string",
"initial_charge_after_trial": true,
"version_number": 0,
"update_return_params": "string",
"product_family": {
"id": 0,
"name": "string",
"handle": "string",
"accounting_code": null,
"description": "string",
"created_at": "2021-05-05T16:00:21-04:00",
"updated_at": "2021-05-05T16:00:21-04:00"
},
"public_signup_pages": [
{
"id": 0,
"return_url": "string",
"return_params": "string",
"url": "string"
}
],
"product_price_point_name": "string",
"request_billing_address": true,
"require_billing_address": true,
"require_shipping_address": true,
"use_site_exchange_rate": true,
"tax_code": "string",
"default_product_price_point_id": 0
}
}
]
```
#### Product Price Points
##### Create Product Price Point
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/product-price-points/create-product-price-point
Creates a Product Price Point. See the [Product Price Point](https://maxio.zendesk.com/hc/en-us/articles/24261111947789-Product-Price-Points) documentation for details.
```http
POST /products/{product_id}/price_points.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `product_id` | [`Number \| String`](https://developers.maxio.com/http/advanced-billing-api/models/oneof-anyof-definitions/create-product-price-point-product-id) | Template, Required | The id or handle of the product. When using the handle, it must be prefixed with `handle:` |
| `body` | [`Create Product Price Point Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/create-product-price-point-request) | Body, Optional | - |
# Response Type
**201**: Created
[`Product Price Point Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/product-price-point-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/products/124/price_points.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"price_point": {
"name": "Educational",
"handle": "educational",
"price_in_cents": 1000,
"interval": 1,
"interval_unit": "month",
"trial_price_in_cents": 4900,
"trial_interval": 1,
"trial_interval_unit": "month",
"trial_type": "payment_expected",
"initial_charge_in_cents": 120000,
"initial_charge_after_trial": false,
"expiration_interval": 12,
"expiration_interval_unit": "month"
}
}'
```
# Example Response *(as JSON)*
```json
{
"price_point": {
"id": 283,
"name": "Educational",
"handle": "educational",
"price_in_cents": 1000,
"interval": 1,
"interval_unit": "month",
"trial_price_in_cents": 4900,
"trial_interval": 1,
"trial_interval_unit": "month",
"trial_type": "payment_expected",
"initial_charge_in_cents": 120000,
"initial_charge_after_trial": false,
"expiration_interval": 12,
"expiration_interval_unit": "month",
"product_id": 901,
"archived_at": "2023-11-30T06:37:20-05:00",
"created_at": "2023-11-27T06:37:20-05:00",
"updated_at": "2023-11-27T06:37:20-05:00"
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Product Price Point Error ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/product-price-point-error-response) |
##### List Product Price Points
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/product-price-points/list-product-price-points
Retrieves a list of product price points.
```http
GET /products/{product_id}/price_points.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `product_id` | [`Number \| String`](https://developers.maxio.com/http/advanced-billing-api/models/oneof-anyof-definitions/list-product-price-points-product-id) | Template, Required | The id or handle of the product. When using the handle, it must be prefixed with `handle:` |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 10. The maximum allowed values is 200; any per_page value over 200 will be changed to 200.
**Default**: `10`
**Constraints**: `<= 200` |
| `currency_prices` | `Boolean` | Query, Optional | (Optional) If you have defined multiple currencies at the site level, you can pass ?currency_prices=true to include an array of currency price data in the response. If the product price point is set to use_site_exchange_rate: true, it will return pricing based on the current exchange rate. If the flag is set to false, it will return all of the defined prices for each currency. |
| `filter[type]` | [`array`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/price-point-type) | Query, Optional | Use in query: `filter[type]=catalog,default`. |
| `archived` | `Boolean` | Query, Optional | Set to include archived price points in the response. |
# Response Type
**200**: OK
[`List Product Price Points Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/list-product-price-points-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/products/124/price_points.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'page=1' \
-d 'per_page=10' \
-d 'filter[type]=Liquid error: Value cannot be null. (Parameter 'key')'
```
# Example Response *(as JSON)*
```json
{
"price_points": [
{
"id": 283,
"name": "Educational",
"handle": "educational",
"price_in_cents": 1000,
"interval": 1,
"interval_unit": "month",
"trial_price_in_cents": 4900,
"trial_interval": 1,
"trial_interval_unit": "month",
"trial_type": "payment_expected",
"initial_charge_in_cents": 120000,
"initial_charge_after_trial": false,
"expiration_interval": 12,
"expiration_interval_unit": "month",
"product_id": 901,
"archived_at": "2023-11-30T06:37:20-05:00",
"created_at": "2023-11-27T06:37:20-05:00",
"updated_at": "2023-11-27T06:37:20-05:00"
}
]
}
```
##### Update Product Price Point
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/product-price-points/update-product-price-point
Updates a product price point.
Note: Custom product price points cannot be updated.
```http
PUT /products/{product_id}/price_points/{price_point_id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `product_id` | [`Number \| String`](https://developers.maxio.com/http/advanced-billing-api/models/oneof-anyof-definitions/update-product-price-point-product-id) | Template, Required | The id or handle of the product. When using the handle, it must be prefixed with `handle:`. Example: `123` for an integer ID, or `handle:example-product-handle` for a string handle. |
| `price_point_id` | [`Number \| String`](https://developers.maxio.com/http/advanced-billing-api/models/oneof-anyof-definitions/update-product-price-point-price-point-id) | Template, Required | The id or handle of the price point. When using the handle, it must be prefixed with `handle:`. Example: `123` for an integer ID, or `handle:example-product-price-point-handle` for a string handle. |
| `body` | [`Update Product Price Point Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/update-product-price-point-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Product Price Point Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/product-price-point-response)
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/products/124/price_points/188.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"price_point": {
"handle": "educational",
"price_in_cents": 1250
}
}'
```
# Example Response *(as JSON)*
```json
{
"price_point": {
"id": 283,
"name": "Educational",
"handle": "educational",
"price_in_cents": 1000,
"interval": 1,
"interval_unit": "month",
"trial_price_in_cents": 4900,
"trial_interval": 1,
"trial_interval_unit": "month",
"trial_type": "payment_expected",
"initial_charge_in_cents": 120000,
"initial_charge_after_trial": false,
"expiration_interval": 12,
"expiration_interval_unit": "month",
"product_id": 901,
"archived_at": "2023-11-30T06:37:20-05:00",
"created_at": "2023-11-27T06:37:20-05:00",
"updated_at": "2023-11-27T06:37:20-05:00"
}
}
```
##### Read Product Price Point
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/product-price-points/read-product-price-point
Returns details for a specific product price point. You can achieve this by using either the product price point ID or handle.
```http
GET /products/{product_id}/price_points/{price_point_id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `product_id` | [`Number \| String`](https://developers.maxio.com/http/advanced-billing-api/models/oneof-anyof-definitions/read-product-price-point-product-id) | Template, Required | The id or handle of the product. When using the handle, it must be prefixed with `handle:`. Example: `123` for an integer ID, or `handle:example-product-handle` for a string handle. |
| `price_point_id` | [`Number \| String`](https://developers.maxio.com/http/advanced-billing-api/models/oneof-anyof-definitions/read-product-price-point-price-point-id) | Template, Required | The id or handle of the price point. When using the handle, it must be prefixed with `handle:`. Example: `123` for an integer ID, or `handle:example-product-price-point-handle` for a string handle. |
| `currency_prices` | `Boolean` | Query, Optional | (Optional) If you have defined multiple currencies at the site level, you can pass ?currency_prices=true to include an array of currency price data in the response. If the product price point is set to use_site_exchange_rate: true, it will return pricing based on the current exchange rate. If the flag is set to false, it will return all of the defined prices for each currency. |
# Response Type
**200**: OK
[`Product Price Point Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/product-price-point-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/products/124/price_points/188.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"price_point": {
"id": 283,
"name": "Educational",
"handle": "educational",
"price_in_cents": 1000,
"interval": 1,
"interval_unit": "month",
"trial_price_in_cents": 4900,
"trial_interval": 1,
"trial_interval_unit": "month",
"trial_type": "payment_expected",
"initial_charge_in_cents": 120000,
"initial_charge_after_trial": false,
"expiration_interval": 12,
"expiration_interval_unit": "month",
"product_id": 901,
"archived_at": "2023-11-30T06:37:20-05:00",
"created_at": "2023-11-27T06:37:20-05:00",
"updated_at": "2023-11-27T06:37:20-05:00"
}
}
```
##### Archive Product Price Point
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/product-price-points/archive-product-price-point
Archives a product price point.
```http
DELETE /products/{product_id}/price_points/{price_point_id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `product_id` | [`Number \| String`](https://developers.maxio.com/http/advanced-billing-api/models/oneof-anyof-definitions/archive-product-price-point-product-id) | Template, Required | The id or handle of the product. When using the handle, it must be prefixed with `handle:`. Example: `123` for an integer ID, or `handle:example-product-handle` for a string handle. |
| `price_point_id` | [`Number \| String`](https://developers.maxio.com/http/advanced-billing-api/models/oneof-anyof-definitions/archive-product-price-point-price-point-id) | Template, Required | The id or handle of the price point. When using the handle, it must be prefixed with `handle:`. Example: `123` for an integer ID, or `handle:example-product-price-point-handle` for a string handle. |
# Response Type
**200**: OK
[`Product Price Point Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/product-price-point-response)
# Example Usage
```bash
curl -X DELETE \
--url 'https://subdomain.chargify.com/products/124/price_points/188.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"price_point": {
"id": 283,
"name": "Educational",
"handle": "educational",
"price_in_cents": 1000,
"interval": 1,
"interval_unit": "month",
"trial_price_in_cents": 4900,
"trial_interval": 1,
"trial_interval_unit": "month",
"trial_type": "payment_expected",
"initial_charge_in_cents": 120000,
"initial_charge_after_trial": false,
"expiration_interval": 12,
"expiration_interval_unit": "month",
"product_id": 901,
"archived_at": "2023-11-30T06:37:20-05:00",
"created_at": "2023-11-27T06:37:20-05:00",
"updated_at": "2023-11-27T06:37:20-05:00"
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Unarchive Product Price Point
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/product-price-points/unarchive-product-price-point
Unarchives an archived product price point.
```http
PATCH /products/{product_id}/price_points/{price_point_id}/unarchive.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `product_id` | `Number` | Template, Required | The Advanced Billing id of the product to which the price point belongs |
| `price_point_id` | `Number` | Template, Required | The Advanced Billing id of the product price point |
# Response Type
**200**: OK
[`Product Price Point Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/product-price-point-response)
# Example Usage
```bash
curl -X PATCH \
--url 'https://subdomain.chargify.com/products/202/price_points/10/unarchive.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"price_point": {
"id": 283,
"name": "Educational",
"handle": "educational",
"price_in_cents": 1000,
"interval": 1,
"interval_unit": "month",
"trial_price_in_cents": 4900,
"trial_interval": 1,
"trial_interval_unit": "month",
"trial_type": "payment_expected",
"initial_charge_in_cents": 120000,
"initial_charge_after_trial": false,
"expiration_interval": 12,
"expiration_interval_unit": "month",
"product_id": 901,
"archived_at": "2023-11-30T06:37:20-05:00",
"created_at": "2023-11-27T06:37:20-05:00",
"updated_at": "2023-11-27T06:37:20-05:00"
}
}
```
##### Promote Product Price Point to Default
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/product-price-points/promote-product-price-point-to-default
Sets a product price point as the default for the product.
Note: Custom product price points cannot be set as the default for a product.
```http
PATCH /products/{product_id}/price_points/{price_point_id}/default.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `product_id` | `Number` | Template, Required | The Advanced Billing id of the product to which the price point belongs |
| `price_point_id` | `Number` | Template, Required | The Advanced Billing id of the product price point |
# Response Type
**200**: OK
[`Product Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/product-response)
# Example Usage
```bash
curl -X PATCH \
--url 'https://subdomain.chargify.com/products/202/price_points/10/default.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"product": {
"id": 29778,
"name": "Educational",
"handle": "educational",
"description": null,
"accounting_code": null,
"request_credit_card": true,
"expiration_interval": 12,
"expiration_interval_unit": "month",
"created_at": "2023-12-01T06:56:12-05:00",
"updated_at": "2023-12-01T06:56:26-05:00",
"price_in_cents": 100,
"interval": 2,
"interval_unit": "month",
"initial_charge_in_cents": 120000,
"trial_price_in_cents": 4900,
"trial_interval": 1,
"trial_interval_unit": "month",
"archived_at": null,
"require_credit_card": true,
"return_params": null,
"taxable": false,
"update_return_url": null,
"tax_code": null,
"initial_charge_after_trial": false,
"version_number": 1,
"update_return_params": null,
"default_product_price_point_id": 32395,
"request_billing_address": false,
"require_billing_address": false,
"require_shipping_address": false,
"use_site_exchange_rate": true,
"item_category": null,
"product_price_point_id": 32395,
"product_price_point_name": "Default",
"product_price_point_handle": "uuid:8c878f50-726e-013c-c71b-0286551bb34f",
"product_family": {
"id": 933860,
"name": "Acme Projects",
"description": "Amazing project management tool",
"handle": "acme-projects",
"accounting_code": null,
"created_at": "2023-12-01T06:56:12-05:00",
"updated_at": "2023-12-01T06:56:12-05:00"
}
}
}
```
##### Bulk Create Product Price Points
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/product-price-points/bulk-create-product-price-points
Creates multiple product price points in one request.
```http
POST /products/{product_id}/price_points/bulk.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `product_id` | `Number` | Template, Required | The Advanced Billing id of the product to which the price points belong |
| `body` | [`Bulk Create Product Price Points Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/bulk-create-product-price-points-request) | Body, Optional | - |
# Response Type
**201**: Created
[`Bulk Create Product Price Points Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/bulk-create-product-price-points-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/products/202/price_points/bulk.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"price_points": [
{
"name": "Educational",
"handle": "educational",
"price_in_cents": 1000,
"interval": 1,
"interval_unit": "month",
"trial_price_in_cents": 4900,
"trial_interval": 1,
"trial_interval_unit": "month",
"trial_type": "payment_expected",
"initial_charge_in_cents": 120000,
"initial_charge_after_trial": false,
"expiration_interval": 12,
"expiration_interval_unit": "month"
},
{
"name": "More Educational",
"handle": "more-educational",
"price_in_cents": 2000,
"interval": 1,
"interval_unit": "month",
"trial_price_in_cents": 4900,
"trial_interval": 1,
"trial_interval_unit": "month",
"trial_type": "payment_expected",
"initial_charge_in_cents": 120000,
"initial_charge_after_trial": false,
"expiration_interval": 12,
"expiration_interval_unit": "month"
}
]
}'
```
# Example Response *(as JSON)*
```json
{
"price_points": [
{
"id": 283,
"name": "Educational",
"handle": "educational",
"price_in_cents": 1000,
"interval": 1,
"interval_unit": "month",
"trial_price_in_cents": 4900,
"trial_interval": 1,
"trial_interval_unit": "month",
"trial_type": "payment_expected",
"initial_charge_in_cents": 120000,
"initial_charge_after_trial": false,
"expiration_interval": 12,
"expiration_interval_unit": "month",
"product_id": 901,
"archived_at": "2023-11-30T06:37:20-05:00",
"created_at": "2023-11-27T06:37:20-05:00",
"updated_at": "2023-11-27T06:37:20-05:00"
}
]
}
```
# Errors
| HTTP Status Code | Error Description |
| --- | --- |
| 422 | Unprocessable Entity (WebDAV) |
##### Create Product Currency Prices
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/product-price-points/create-product-currency-prices
Creates currency prices for a given currency that has been defined on the site level in your settings.
When creating currency prices, they need to mirror the structure of your primary pricing. If the product price point defines a trial and/or setup fee, each currency must also define a trial and/or setup fee.
Note: Currency Prices are not able to be created for custom product price points.
```http
POST /product_price_points/{product_price_point_id}/currency_prices.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `product_price_point_id` | `Number` | Template, Required | The Advanced Billing id of the product price point |
| `body` | [`Create Product Currency Prices Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/create-product-currency-prices-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Currency Prices Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/currency-prices-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/product_price_points/234/currency_prices.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"currency_prices": [
{
"currency": "EUR",
"price": 60,
"role": "baseline"
},
{
"currency": "EUR",
"price": 30,
"role": "trial"
},
{
"currency": "EUR",
"price": 100,
"role": "initial"
}
]
}'
```
# Example Response *(as JSON)*
```json
{
"currency_prices": [
{
"id": 100,
"currency": "EUR",
"price": 123,
"formatted_price": "€123,00",
"product_price_point_id": 32669,
"role": "baseline"
}
]
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error Array Map ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-array-map-response) |
##### Update Product Currency Prices
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/product-price-points/update-product-currency-prices
Updates the `price`s of currency prices for a given currency that exists on the product price point.
When updating the pricing, it needs to mirror the structure of your primary pricing. If the product price point defines a trial and/or setup fee, each currency must also define a trial and/or setup fee.
Note: Currency Prices cannot be updated for custom product price points.
```http
PUT /product_price_points/{product_price_point_id}/currency_prices.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `product_price_point_id` | `Number` | Template, Required | The Advanced Billing id of the product price point |
| `body` | [`Update Currency Prices Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/update-currency-prices-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Currency Prices Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/currency-prices-response)
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/product_price_points/234/currency_prices.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"currency_prices": [
{
"id": 200,
"price": 15.0
},
{
"id": 201,
"price": 5.0
}
]
}'
```
# Example Response *(as JSON)*
```json
{
"currency_prices": [
{
"id": 123,
"currency": "EUR",
"price": 100,
"formatted_price": "€123,00",
"product_price_point_id": 32669,
"role": "baseline"
}
]
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error Array Map ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-array-map-response) |
##### List All Product Price Points
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/product-price-points/list-all-product-price-points
Lists Product Price Points belonging to a site.
```http
GET /products_price_points.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `direction` | [`Sorting Direction`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/sorting-direction) | Query, Optional | Controls the order in which results are returned. Use in query `direction=asc`. |
| `filter` | [`List Price Points Filter`](https://developers.maxio.com/http/advanced-billing-api/models/structures/list-price-points-filter) | Query, Optional | Filter to use for List PricePoints operations |
| `include` | [`List Products Price Points Include`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/list-products-price-points-include) | Query, Optional | Allows including additional data in the response. Use in query: `include=currency_prices`. |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query `per_page=200`.
**Default**: `20`
**Constraints**: `<= 200` |
# Response Type
**200**: OK
[`List Product Price Points Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/list-product-price-points-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/products_price_points.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'filter[start_date]=2011-12-17' \
-d 'filter[end_date]=2011-12-15' \
-d 'filter[start_datetime]=2011-12-19T10%3A15%3A30%2B01%3A00' \
-d 'filter[end_datetime]=2019-06-07T17%3A20%3A06Z' \
-d 'filter[type]=catalog%2Cdefault%2Ccustom' \
-d 'filter[ids]=1%2C2%2C3' \
-d 'include=currency_prices' \
-d 'page=1' \
-d 'per_page=50'
```
# Example Response *(as JSON)*
```json
{
"price_points": [
{
"id": 0,
"name": "My pricepoint",
"handle": "handle",
"price_in_cents": 10,
"interval": 5,
"interval_unit": "month",
"trial_price_in_cents": 10,
"trial_interval": 1,
"trial_interval_unit": "month",
"trial_type": "payment_expected",
"introductory_offer": true,
"initial_charge_in_cents": 0,
"initial_charge_after_trial": true,
"expiration_interval": 0,
"expiration_interval_unit": "month",
"product_id": 1230,
"created_at": "2021-04-02T17:52:09-04:00",
"updated_at": "2021-04-02T17:52:09-04:00",
"use_site_exchange_rate": true
}
]
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
#### Proforma Invoices
##### Create Consolidated Proforma Invoice
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/proforma-invoices/create-consolidated-proforma-invoice
Creates a consolidated proforma invoice asynchronously. To find and view the new consolidated proforma invoice, you can poll the subscription group listing for proforma invoices; only one consolidated proforma invoice can be created per group at a time.
If the information becomes outdated, simply void the old consolidated proforma invoice and generate a new one.
## Restrictions
Proforma invoices are only available on Relationship Invoicing sites. To create a proforma invoice, the subscription must not be prepaid, and must be in a live state.
```http
POST /subscription_groups/{uid}/proforma_invoices.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `uid` | `String` | Template, Required | The uid of the subscription group |
# Response Type
**201**: Created
`Void`
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscription_groups/uid0/proforma_invoices.json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### List Subscription Group Proforma Invoices
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/proforma-invoices/list-subscription-group-proforma-invoices
Lists proforma invoices with a `consolidation_level` of parent for the subscription group.
By default, proforma invoices returned on the index will only include totals, not detailed breakdowns for `line_items`, `discounts`, `taxes`, `credits`, `payments`, `custom_fields`. To include breakdowns, pass the specific field as a key in the query with a value set to true.
```http
GET /subscription_groups/{uid}/proforma_invoices.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `uid` | `String` | Template, Required | The uid of the subscription group |
| `line_items` | `Boolean` | Query, Optional | Include line items data.
**Default**: `false` |
# Response Type
**200**: OK
[`List Proforma Invoices Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/list-proforma-invoices-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/subscription_groups/uid0/proforma_invoices.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'line_items=false' \
-d 'discounts=false' \
-d 'taxes=false' \
-d 'credits=false' \
-d 'payments=false' \
-d 'custom_fields=false'
```
# Errors
| HTTP Status Code | Error Description |
| --- | --- |
| 404 | Not Found |
##### Read Proforma Invoice
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/proforma-invoices/read-proforma-invoice
Returns the details of an existing proforma invoice.
## Restrictions
Proforma invoices are only available on Relationship Invoicing sites.
```http
GET /proforma_invoices/{proforma_invoice_uid}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `proforma_invoice_uid` | `String` | Template, Required | The uid of the proforma invoice |
# Response Type
**200**: OK
[`Proforma Invoice`](https://developers.maxio.com/http/advanced-billing-api/models/structures/proforma-invoice)
# Example Usage
```bash
curl -X GET \
--url 'https://subdomain.chargify.com/proforma_invoices/proforma_invoice_uid4.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description |
| --- | --- |
| 404 | Not Found |
##### Create Proforma Invoice
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/proforma-invoices/create-proforma-invoice
Creates a proforma invoice and returns it as a response. If the information becomes outdated, simply void the old proforma invoice and generate a new one.
If you would like to preview the next billing amounts without generating a full proforma invoice, use the renewal preview endpoint.
## Restrictions
Proforma invoices are only available on Relationship Invoicing sites. To create a proforma invoice, the subscription must not be in a group, must not be prepaid, and must be in a live state.
```http
POST /subscriptions/{subscription_id}/proforma_invoices.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
# Response Type
**200**: OK
[`Proforma Invoice`](https://developers.maxio.com/http/advanced-billing-api/models/structures/proforma-invoice)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscriptions/222/proforma_invoices.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### List Proforma Invoices
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/proforma-invoices/list-proforma-invoices
Lists proforma invoices for a subscription. By default, results only include totals, not detailed breakdowns for `line_items`, `discounts`, `taxes`, `credits`, `payments`, or `custom_fields`. To include breakdowns, pass the specific field as a key in the query with a value set to `true`.
```http
GET /subscriptions/{subscription_id}/proforma_invoices.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `start_date` | `String` | Query, Optional | The beginning date range for the invoice's Due Date, in the YYYY-MM-DD format. |
| `end_date` | `String` | Query, Optional | The ending date range for the invoice's Due Date, in the YYYY-MM-DD format. |
| `status` | [`Proforma Invoice Status`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/proforma-invoice-status) | Query, Optional | The current status of the invoice. Allowed Values: draft, open, paid, pending, voided |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query `per_page=200`.
**Default**: `20`
**Constraints**: `<= 200` |
| `direction` | [`Direction`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/direction) | Query, Optional | The sort direction of the returned invoices.
**Default**: `desc` |
| `line_items` | `Boolean` | Query, Optional | Include line items data.
**Default**: `false` |
# Response Type
**200**: OK
[`List Proforma Invoices Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/list-proforma-invoices-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/subscriptions/222/proforma_invoices.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'page=1' \
-d 'per_page=50' \
-d 'direction=desc' \
-d 'line_items=false' \
-d 'discounts=false' \
-d 'taxes=false' \
-d 'credits=false' \
-d 'payments=false' \
-d 'custom_fields=false'
```
##### Deliver Proforma Invoice
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/proforma-invoices/deliver-proforma-invoice
Delivers a proforma invoice programmatically via email. Supports email
delivery to direct recipients, carbon-copy (cc) recipients, and blind carbon-copy (bcc) recipients.
If `recipient_emails` is omitted, the system will fall back to the primary recipient derived from the invoice or
subscription. At least one recipient must be present, either via the request body or via this default behavior, so an
empty body may still succeed when defaults are available.
```http
POST /proforma_invoices/{proforma_invoice_uid}/deliveries.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `proforma_invoice_uid` | `String` | Template, Required | The uid of the proforma invoice |
| `body` | [`Deliver Proforma Invoice Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/deliver-proforma-invoice-request) | Body, Optional | - |
# Response Type
**201**: Created
[`Proforma Invoice`](https://developers.maxio.com/http/advanced-billing-api/models/structures/proforma-invoice)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/proforma_invoices/proforma_invoice_uid4/deliveries.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"recipient_emails": [
"user0@example.com"
],
"cc_recipient_emails": [
"user1@example.com"
],
"bcc_recipient_emails": [
"user2@example.com"
]
}'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Void Proforma Invoice
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/proforma-invoices/void-proforma-invoice
Voids a proforma invoice that has the status "draft".
## Restrictions
Proforma invoices are only available on Relationship Invoicing sites.
Only proforma invoices that have the appropriate status may be reopened. If the invoice identified by {uid} does not have the appropriate status, the response will have HTTP status code 422 and an error message.
A reason for the void operation is required to be included in the request body. If one is not provided, the response will have HTTP status code 422 and an error message.
```http
POST /proforma_invoices/{proforma_invoice_uid}/void.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `proforma_invoice_uid` | `String` | Template, Required | The uid of the proforma invoice |
| `body` | [`Void Invoice Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/void-invoice-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Proforma Invoice`](https://developers.maxio.com/http/advanced-billing-api/models/structures/proforma-invoice)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/proforma_invoices/proforma_invoice_uid4/void.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Preview Proforma Invoice
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/proforma-invoices/preview-proforma-invoice
Previews the data that will be included on a given subscription's proforma invoice if one were to be generated. It will have similar line items and totals as a renewal preview, but the response will be presented in the format of a proforma invoice. Consequently it will include additional information such as the name and addresses that will appear on the proforma invoice.
The preview endpoint is subject to all the same conditions as the proforma invoice endpoint. For example, previews are only available on the Relationship Invoicing architecture, and previews cannot be made for end-of-life subscriptions.
If all the data returned in the preview is as expected, you may then create a static proforma invoice and send it to your customer. The data within a preview will not be saved and will not be accessible after the call is made.
Alternatively, if you have some proforma invoices already, you may make a preview call to determine whether any billing information for the subscription's upcoming renewal has changed.
```http
POST /subscriptions/{subscription_id}/proforma_invoices/preview.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
# Response Type
**200**: OK
[`Proforma Invoice`](https://developers.maxio.com/http/advanced-billing-api/models/structures/proforma-invoice)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscriptions/222/proforma_invoices/preview.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Create Signup Proforma Invoice
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/proforma-invoices/create-signup-proforma-invoice
Creates a proforma invoice to preview costs before a subscription's signup. This endpoint is only available for Relationship Invoicing sites and cannot be used to create consolidated proforma invoices or preview prepaid subscriptions. Like other proforma invoices, it can be emailed to the customer, voided, and publicly viewed on the chargifypay domain.
Pass a payload that resembles a subscription create or signup preview request. For example, you can specify components, coupons/a referral, offers, custom pricing, and an existing customer or payment profile to populate a shipping or billing address.
A product and customer first name, last name, and email are the minimum requirements. We recommend associating the proforma invoice with a customer_id to easily find their proforma invoices, since the subscription_id will always be blank.
```http
POST /subscriptions/proforma_invoices.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `body` | [`Create Subscription Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/create-subscription-request) | Body, Optional | - |
# Response Type
**201**: Created
[`Proforma Invoice`](https://developers.maxio.com/http/advanced-billing-api/models/structures/proforma-invoice)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscriptions/proforma_invoices.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"subscription": {
"product_handle": "gold-product",
"customer_attributes": {
"first_name": "Myra",
"last_name": "Maisel",
"email": "mmaisel@example.com"
}
}
}'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 400 | Bad Request | [`Proforma Bad Request Error ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/proforma-bad-request-error-response) |
| 422 | Unprocessable Entity (WebDAV) | [`Error Array Map ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-array-map-response) |
##### Preview Signup Proforma Invoice
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/proforma-invoices/preview-signup-proforma-invoice
Creates a signup preview in the format of a proforma invoice to preview costs before a subscription's signup. This endpoint is only available for Relationship Invoicing sites and cannot be used to create consolidated proforma invoice previews or preview prepaid subscriptions. You have the option of previewing the first renewal's costs as well. The proforma invoice preview will not be persisted.
Pass a payload that resembles a subscription create or signup preview request. For example, you can specify components, coupons/a referral, offers, custom pricing, and an existing customer or payment profile to populate a shipping or billing address.
A product and customer first name, last name, and email are the minimum requirements.
```http
POST /subscriptions/proforma_invoices/preview.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `include` | [`Create Signup Proforma Preview Include`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/create-signup-proforma-preview-include) | Query, Optional | Choose to include a proforma invoice preview for the first renewal. Use in query `include=next_proforma_invoice`. |
| `body` | [`Create Subscription Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/create-subscription-request) | Body, Optional | - |
# Response Type
**201**: Created
[`Signup Proforma Preview Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/signup-proforma-preview-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscriptions/proforma_invoices/preview.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"subscription": {
"product_handle": "gold-plan",
"customer_attributes": {
"first_name": "first",
"last_name": "last",
"email": "flast@example.com"
}
}
}'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 400 | Bad Request | [`Proforma Bad Request Error ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/proforma-bad-request-error-response) |
| 422 | Unprocessable Entity (WebDAV) | [`Error Array Map ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-array-map-response) |
#### Reason Codes
##### Create Reason Code
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/reason-codes/create-reason-code
Creates a reason code for a given site.
Reason Codes are a way to gain a high-level view of why your customers are cancelling the subscription to your product or service.
Add a set of churn reason codes to be displayed in-app and/or the Maxio Billing Portal. As your subscribers decide to cancel their subscription, learn why they decided to cancel.
For more information, see [Churn Reason Codes](https://maxio.zendesk.com/hc/en-us/articles/24286647554701-Churn-Reason-Codes).
```http
POST /reason_codes.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `body` | [`Create Reason Code Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/create-reason-code-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Reason Code Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/reason-code-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/reason_codes.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"reason_code": {
"code": "NOTHANKYOU",
"description": "No thank you!",
"position": 5
}
}'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### List Reason Codes
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/reason-codes/list-reason-codes
Lists all current churn codes for a given site.
```http
GET /reason_codes.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query `per_page=200`.
**Default**: `20`
**Constraints**: `<= 200` |
# Response Type
**200**: OK
[`array`](https://developers.maxio.com/http/advanced-billing-api/models/structures/reason-code-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/reason_codes.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'page=1' \
-d 'per_page=50'
```
# Example Response *(as JSON)*
```json
[
{
"reason_code": {
"id": 2,
"site_id": 2,
"code": "LARGE",
"description": "This is too complicated",
"position": 1,
"created_at": "2017-02-16T16:49:07-05:00",
"updated_at": "2017-02-17T16:29:51-05:00"
}
},
{
"reason_code": {
"id": 1,
"site_id": 2,
"code": "CH1",
"description": "This does not meet my needs",
"position": 2,
"created_at": "2017-02-16T16:48:45-05:00",
"updated_at": "2017-02-17T16:29:59-05:00"
}
},
{
"reason_code": {
"id": 5,
"site_id": 2,
"code": "HAN99",
"description": "Hard to setup",
"position": 3,
"created_at": "2017-02-17T16:29:42-05:00",
"updated_at": "2017-02-17T16:29:59-05:00"
}
}
]
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Read Reason Code
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/reason-codes/read-reason-code
Returns a particular churn reason code for a given site by its unique ID.
```http
GET /reason_codes/{reason_code_id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `reason_code_id` | `Number` | Template, Required | The Advanced Billing id of the reason code |
# Response Type
**200**: OK
[`Reason Code Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/reason-code-response)
# Example Usage
```bash
curl -X GET \
--url 'https://subdomain.chargify.com/reason_codes/32.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description |
| --- | --- |
| 404 | Not Found |
##### Update Reason Code
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/reason-codes/update-reason-code
Updates an existing reason code for a given site.
```http
PUT /reason_codes/{reason_code_id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `reason_code_id` | `Number` | Template, Required | The Advanced Billing id of the reason code |
| `body` | [`Update Reason Code Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/update-reason-code-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Reason Code Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/reason-code-response)
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/reason_codes/32.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Delete Reason Code
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/reason-codes/delete-reason-code
Deletes a reason code from the Churn Reason Codes. This code will be immediately removed. This action is not reversible.
```http
DELETE /reason_codes/{reason_code_id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `reason_code_id` | `Number` | Template, Required | The Advanced Billing id of the reason code |
# Response Type
**200**: OK
[`Ok Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/ok-response)
# Example Usage
```bash
curl -X DELETE \
--url 'https://subdomain.chargify.com/reason_codes/32.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"ok": "ok"
}
```
# Errors
| HTTP Status Code | Error Description |
| --- | --- |
| 404 | Not Found |
#### Referral Codes
##### Validate Referral Code
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/referral-codes/validate-referral-code
Validates whether a referral code is valid and applicable within your site. This method is useful for validating referral codes that are entered by a customer.
For more information, see [Understanding Referrals](https://docs.maxio.com/hc/en-us/articles/24286981223693-Understanding-Referrals) in the product documentation.
```http
GET /referral_codes/validate.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `code` | `String` | Query, Required | The referral code you are trying to validate |
# Response Type
**200**: OK
[`Referral Validation Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/referral-validation-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/referral_codes/validate.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'code=code8'
```
# Example Response *(as JSON)*
```json
{
"referral_code": {
"id": 1032514,
"site_id": 31615,
"subscription_id": 16254270,
"code": "9b6cdw"
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | [`Single String Error ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/single-string-error-response) |
#### Sales Commissions
##### List Sales Commission Settings
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/sales-commissions/list-sales-commission-settings
Lists subscriptions with associated sales reps.
## Modified Authentication Process
The Sales Commission API differs from other Chargify API endpoints. This resource is associated with the seller itself. Up to now all available resources were at the level of the site, therefore creating the API Key per site was a sufficient solution. To share resources at the seller level, a new authentication method was introduced, which is user authentication. Creating an API Key for a user is a required step to correctly use the Sales Commission API, more details [here](https://developers.chargify.com/docs/developer-docs/ZG9jOjMyNzk5NTg0-2020-04-20-new-api-authentication).
Access to the Sales Commission API endpoints is available to users with financial access, where the seller has the Advanced Analytics component enabled. For further information on getting access to Advanced Analytics contact Maxio support.
> Note: The request is at seller level, it means `<>` variable will be replaced by `app`.
```http
GET /sellers/{seller_id}/sales_commission_settings.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `seller_id` | `String` | Template, Required | The Chargify id of your seller account |
| `Authorization` | `String` | Header, Optional | For authorization use user API key. See details [here](https://developers.chargify.com/docs/developer-docs/ZG9jOjMyNzk5NTg0-2020-04-20-new-api-authentication).
**Default**: `Bearer <>` |
| `live_mode` | `Boolean` | Query, Optional | This parameter indicates if records should be fetched from live mode sites. Default value is true. |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 100.
**Default**: `100` |
# Response Type
**200**: OK
[`array`](https://developers.maxio.com/http/advanced-billing-api/models/structures/sale-rep-settings)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/sellers/seller_id8/sales_commission_settings.json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <>' \
-d 'page=1' \
-d 'per_page=100'
```
# Example Response *(as JSON)*
```json
[
{
"customer_name": "Ziomek Ziomeczek",
"subscription_id": 81746,
"site_link": "https://chargify9.staging-chargify.com/dashboard",
"site_name": "Chargify",
"subscription_mrr": "$200.00",
"sales_rep_id": 48,
"sales_rep_name": "John Candy"
},
{
"customer_name": "Ziom Kom",
"subscription_id": 83758,
"site_link": "https://chargify9.staging-chargify.com/dashboard",
"site_name": "Chargify",
"subscription_mrr": "$200.00",
"sales_rep_id": 49,
"sales_rep_name": "Josh Acme"
},
{
"customer_name": "George Bush",
"subscription_id": 83790,
"site_link": "https://chargify9.staging-chargify.com/dashboard",
"site_name": "Chargify",
"subscription_mrr": "$200.00",
"sales_rep_id": 48,
"sales_rep_name": "John Candy"
}
]
```
##### List Sales Reps
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/sales-commissions/list-sales-reps
Lists sales reps with details.
## Modified Authentication Process
The Sales Commission API differs from other Chargify API endpoints. This resource is associated with the seller itself. Up to now all available resources were at the level of the site, therefore creating the API Key per site was a sufficient solution. To share resources at the seller level, a new authentication method was introduced, which is user authentication. Creating an API Key for a user is a required step to correctly use the Sales Commission API, more details [here](https://developers.chargify.com/docs/developer-docs/ZG9jOjMyNzk5NTg0-2020-04-20-new-api-authentication).
Access to the Sales Commission API endpoints is available to users with financial access, where the seller has the Advanced Analytics component enabled. For further information on getting access to Advanced Analytics contact Maxio support.
> Note: The request is at seller level, it means `<>` variable will be replaced by `app`.
```http
GET /sellers/{seller_id}/sales_reps.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `seller_id` | `String` | Template, Required | The Chargify id of your seller account |
| `Authorization` | `String` | Header, Optional | For authorization use user API key. See details [here](https://developers.chargify.com/docs/developer-docs/ZG9jOjMyNzk5NTg0-2020-04-20-new-api-authentication).
**Default**: `Bearer <>` |
| `live_mode` | `Boolean` | Query, Optional | This parameter indicates if records should be fetched from live mode sites. Default value is true. |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 100.
**Default**: `100` |
# Response Type
**200**: OK
[`array`](https://developers.maxio.com/http/advanced-billing-api/models/structures/list-sale-rep-item)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/sellers/seller_id8/sales_reps.json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <>' \
-d 'page=1' \
-d 'per_page=100'
```
# Example Response *(as JSON)*
```json
[
{
"id": 48,
"full_name": "John Candy",
"subscriptions_count": 2,
"mrr_data": {
"november_2019": {
"mrr": "$0.00",
"usage": "$0.00",
"recurring": "$0.00"
},
"december_2019": {
"mrr": "$0.00",
"usage": "$0.00",
"recurring": "$0.00"
},
"january_2020": {
"mrr": "$400.00",
"usage": "$0.00",
"recurring": "$400.00"
},
"february_2020": {
"mrr": "$400.00",
"usage": "$0.00",
"recurring": "$400.00"
},
"march_2020": {
"mrr": "$400.00",
"usage": "$0.00",
"recurring": "$400.00"
},
"april_2020": {
"mrr": "$400.00",
"usage": "$0.00",
"recurring": "$400.00"
}
},
"test_mode": true
},
{
"id": 49,
"full_name": "Josh Acme",
"subscriptions_count": 1,
"mrr_data": {
"november_2019": {
"mrr": "$0.00",
"usage": "$0.00",
"recurring": "$0.00"
},
"december_2019": {
"mrr": "$0.00",
"usage": "$0.00",
"recurring": "$0.00"
},
"january_2020": {
"mrr": "$200.00",
"usage": "$0.00",
"recurring": "$200.00"
},
"february_2020": {
"mrr": "$200.00",
"usage": "$0.00",
"recurring": "$200.00"
},
"march_2020": {
"mrr": "$200.00",
"usage": "$0.00",
"recurring": "$200.00"
},
"april_2020": {
"mrr": "$200.00",
"usage": "$0.00",
"recurring": "$200.00"
}
},
"test_mode": true
}
]
```
##### Read Sales Rep
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/sales-commissions/read-sales-rep
Returns a sales rep and attached subscription details.
## Modified Authentication Process
The Sales Commission API differs from other Chargify API endpoints. This resource is associated with the seller itself. Up to now all available resources were at the level of the site, therefore creating the API Key per site was a sufficient solution. To share resources at the seller level, a new authentication method was introduced, which is user authentication. Creating an API Key for a user is a required step to correctly use the Sales Commission API, more details [here](https://developers.chargify.com/docs/developer-docs/ZG9jOjMyNzk5NTg0-2020-04-20-new-api-authentication).
Access to the Sales Commission API endpoints is available to users with financial access, where the seller has the Advanced Analytics component enabled. For further information on getting access to Advanced Analytics contact Maxio support.
> Note: The request is at seller level, it means `<>` variable will be replaced by `app`.
```http
GET /sellers/{seller_id}/sales_reps/{sales_rep_id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `seller_id` | `String` | Template, Required | The Chargify id of your seller account |
| `sales_rep_id` | `String` | Template, Required | The Advanced Billing id of sales rep. |
| `Authorization` | `String` | Header, Optional | For authorization use user API key. See details [here](https://developers.chargify.com/docs/developer-docs/ZG9jOjMyNzk5NTg0-2020-04-20-new-api-authentication).
**Default**: `Bearer <>` |
| `live_mode` | `Boolean` | Query, Optional | This parameter indicates if records should be fetched from live mode sites. Default value is true. |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 100.
**Default**: `100` |
# Response Type
**200**: OK
[`Sale Rep`](https://developers.maxio.com/http/advanced-billing-api/models/structures/sale-rep)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/sellers/seller_id8/sales_reps/sales_rep_id4.json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <>' \
-d 'page=1' \
-d 'per_page=100'
```
# Example Response *(as JSON)*
```json
{
"id": 48,
"full_name": "John Candy",
"subscriptions_count": 2,
"test_mode": true,
"subscriptions": [
{
"id": 81746,
"site_name": "Chargify",
"subscription_url": "https://chargify9.staging-chargify.com/subscriptions/81746",
"customer_name": "Ziomek Ziomeczek",
"created_at": "2020-01-03T02:36:27-05:00",
"mrr": "$200.00",
"usage": "$0.00",
"recurring": "$200.00",
"last_payment": "2020-04-03T03:40:27-04:00",
"churn_date": null
},
{
"id": 83790,
"site_name": "Chargify",
"subscription_url": "https://chargify9.staging-chargify.com/subscriptions/83790",
"customer_name": "George Bush",
"created_at": "2020-01-17T07:34:32-05:00",
"mrr": "$200.00",
"usage": "$0.00",
"recurring": "$200.00",
"last_payment": "2020-04-17T08:41:03-04:00",
"churn_date": null
}
]
}
```
#### Sites
##### Read Site
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/sites/read-site
Retrieves site data.
For more information, see [Sites](https://maxio.zendesk.com/hc/en-us/sections/24250550707085-Sites) in the product documentation. Specifically, the [Clearing Site Data](https://maxio.zendesk.com/hc/en-us/articles/24250617028365-Clearing-Site-Data) section is relevant to this endpoint.
#### Relationship invoicing enabled
If the site has Relationship invoicing enabled, additional properties are returned in the response:
```
"customer_hierarchy_enabled": true,
"whopays_enabled": true,
"whopays_default_payer": "self"
```
For more information, see [Who Pays & Customer Hierarchy](https://maxio.zendesk.com/hc/en-us/articles/24252185211533-Customer-Hierarchies-WhoPays).
```http
GET /site.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Response Type
**200**: OK
[`Site Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/site-response)
# Example Usage
```bash
curl -X GET \
--url 'https://subdomain.chargify.com/site.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"site": {
"id": 0,
"name": "string",
"subdomain": "string",
"currency": "string",
"seller_id": 0,
"non_primary_currencies": [
"string"
],
"relationship_invoicing_enabled": true,
"schedule_subscription_cancellation_enabled": true,
"customer_hierarchy_enabled": true,
"whopays_enabled": true,
"whopays_default_payer": "string",
"default_payment_collection_method": "string",
"organization_address": {
"street": null,
"line2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"name": "string",
"phone": "string"
},
"tax_configuration": {
"kind": "custom",
"fully_configured": true,
"destination_address": "shipping_then_billing"
},
"net_terms": {
"default_net_terms": 0,
"automatic_net_terms": 0,
"remittance_net_terms": 0,
"net_terms_on_remittance_signups_enabled": false,
"custom_net_terms_enabled": false
},
"test": true,
"allocation_settings": {
"upgrade_charge": "prorated",
"downgrade_credit": "none",
"accrue_charge": "true"
}
}
}
```
##### Clear Site
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/sites/clear-site
Clears all data from a test site asynchronously. This call is asynchronous and there may be a delay before the site data is fully deleted. If you are clearing site data for an automated test, you will need to build in a delay and/or check that there are no products, etc., in the site before proceeding.
**This functionality will only work on sites in TEST mode. Attempts to perform this on sites in “live” mode will result in a response of 403 FORBIDDEN.**
```http
POST /sites/clear_data.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `cleanup_scope` | [`Cleanup Scope`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/cleanup-scope) | Query, Optional | `all`: Will clear all products, customers, and related subscriptions from the site. `customers`: Will clear only customers and related subscriptions (leaving the products untouched) for the site. Revenue will also be reset to 0. Use in query `cleanup_scope=all`.
**Default**: `all` |
# Response Type
**200**: OK
`Void`
# Example Usage
```bash
curl -X POST -G \
--url 'https://subdomain.chargify.com/sites/clear_data.json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'cleanup_scope=all'
```
##### List Chargify Js Public Keys
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/sites/list-chargify-js-public-keys
Lists public keys used for Maxio.js (formerly Chargify.js).
```http
GET /chargify_js_keys.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query `per_page=200`.
**Default**: `20`
**Constraints**: `<= 200` |
# Response Type
**200**: OK
[`List Public Keys Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/list-public-keys-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/chargify_js_keys.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'page=1' \
-d 'per_page=50'
```
# Example Response *(as JSON)*
```json
{
"chargify_js_keys": [
{
"public_key": "chjs_ftrxt7c4fv6f74wchjs_5zyn7gnwv",
"requires_security_token": false,
"created_at": "2021-01-01T05:00:00-04:00"
}
],
"meta": {
"total_count": 1,
"current_page": 1,
"total_pages": 1,
"per_page": 10
}
}
```
#### Subscriptions
##### Create Subscription
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscriptions/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](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://developers.maxio.com/http/help/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://developers.maxio.com/http/advanced-billing-api/api-endpoints/payment-profiles/create-payment-profile) endpoint for details on payment parameters.
See the [Subscription Signups](https://developers.maxio.com/http/getting-started/advanced-billing-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://developers.maxio.com/http/advanced-billing-api/api-endpoints/payment-profiles/create-payment-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](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.
```http
POST /subscriptions.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `body` | [`Create Subscription Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/create-subscription-request) | Body, Optional | - |
# Response Type
**201**: Created
[`Subscription Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/subscription-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscriptions.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"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": "address_24",
"address": "123 Mass Ave."
},
"payment_collection_method": "remittance"
}
}'
```
# Example Response *(as JSON)*
```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": "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)"
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### List Subscriptions
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscriptions/list-subscriptions
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://developers.maxio.com/http/help/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.
```http
GET /subscriptions.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query `per_page=200`.
**Default**: `20`
**Constraints**: `<= 200` |
| `sort` | [`Subscription Sort`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/subscription-sort) | Query, Optional | The attribute by which to sort
**Default**: `signup_date` |
| `direction` | [`Sorting Direction`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/sorting-direction) | Query, Optional | Controls the order in which results are returned. Use in query `direction=asc`. |
| `state` | [`Subscription State Filter`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/subscription-state-filter) | Query, Optional | The current state of the subscription |
| `product` | [`Number \| String`](https://developers.maxio.com/http/advanced-billing-api/models/oneof-anyof-definitions/list-subscriptions-product) | Query, Optional | Filter subscriptions by product. Accepts product ID or exact product name. Product handle is not supported. |
| `q` | `String` | Query, Optional | Search string. |
| `q_scope` | [`Q Scope`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/q-scope) | Query, Optional | Scope of fields used by the q search. |
| `customer_id` | `Number` | Query, Optional | The Advanced Billing id of the customer. |
| `product_price_point_id` | `Number` | Query, Optional | The ID of the product price point. If supplied, product is required. |
| `coupon` | `Number` | Query, Optional | The numeric id of the coupon currently applied to the subscription. (This can be found in the URL when editing a coupon. Note that the coupon code cannot be used.) |
| `coupon_code` | `String` | Query, Optional | The coupon code currently applied to the subscription |
| `collection_method` | [`Collection Method 1`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/collection-method-1) | Query, Optional | The collection method for the subscription. |
| `branding_theme_id` | `Number` | Query, Optional | Filter subscriptions by the ID of an assigned Branding Theme. Branding Themes is a beta feature. See [Understand Branding Themes](https://docs.maxio.com/hc/en-us/articles/43796895662093-Understand-Branding-Themes#understand-branding-themes-0-0) for more information. |
| `date_field` | [`Subscription Date Field`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/subscription-date-field) | Query, Optional | The type of filter you'd like to apply to your search. Allowed Values: , current_period_ends_at, current_period_starts_at, created_at, activated_at, canceled_at, expires_at, trial_started_at, trial_ended_at, updated_at |
| `start_date` | `Date` | Query, Optional | The start date (format YYYY-MM-DD) with which to filter the date_field. Returns subscriptions with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified. Use in query `start_date=2022-07-01`. |
| `end_date` | `Date` | Query, Optional | The end date (format YYYY-MM-DD) with which to filter the date_field. Returns subscriptions with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified. Use in query `end_date=2022-08-01`. |
| `start_datetime` | `DateTime` | Query, Optional | The start date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns subscriptions with a timestamp at or after exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of start_date. Use in query `start_datetime=2022-07-01 09:00:05`. |
| `end_datetime` | `DateTime` | Query, Optional | The end date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns subscriptions with a timestamp at or before exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of end_date. Use in query `end_datetime=2022-08-01 10:00:05`. |
| `metadata` | `map` | Query, Optional | The value of the metadata field specified in the parameter. Use in query `metadata[my-field]=value&metadata[other-field]=another_value`. |
| `group_status` | [`Group Status`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/group-status) | Query, Optional | Filter by whether a subscription is in a group. |
| `dunning_exemption` | `Boolean` | Query, Optional | Filter by dunning exemption status. |
| `payment_gateways` | `String` | Query, Optional | Comma-separated payment gateway identifiers. |
| `currencies` | `String` | Query, Optional | Comma-separated currency codes. |
| `include` | [`array`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/subscription-list-include) | Query, Optional | Allows including additional data in the response. Use in query: `include[]=self_service_page_token`. |
# Response Type
**200**: OK
[`array`](https://developers.maxio.com/http/advanced-billing-api/models/structures/subscription-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/subscriptions.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'page=1' \
-d 'per_page=50' \
-d 'sort=signup_date' \
-d 'include[]=self_service_page_token'
```
##### Update Subscription
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscriptions/update-subscription
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://developers.maxio.com/http/help/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`.
```http
PUT /subscriptions/{subscription_id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `body` | [`Update Subscription Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/update-subscription-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Subscription Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/subscription-response)
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/subscriptions/222.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"subscription": {
"payment_collection_method": "remittance",
"next_billing_at": "2010-08-06T15:34:00Z"
}
}'
```
# Example Response *(as JSON)*
```json
{
"subscription": {
"id": 18220670,
"state": "active",
"trial_started_at": null,
"trial_ended_at": null,
"activated_at": "2017-06-27T13:45:15-05:00",
"created_at": "2017-06-27T13:45:13-05:00",
"updated_at": "2017-06-30T09:26:50-05:00",
"expires_at": null,
"balance_in_cents": 10000,
"current_period_ends_at": "2017-06-30T12:00:00-05:00",
"next_assessment_at": "2017-06-30T12:00:00-05:00",
"canceled_at": null,
"cancellation_message": null,
"next_product_id": null,
"cancel_at_end_of_period": false,
"payment_collection_method": "automatic",
"snap_day": "end",
"cancellation_method": null,
"current_period_started_at": "2017-06-27T13:45:13-05:00",
"previous_state": "active",
"signup_payment_id": 191819284,
"signup_revenue": "0.00",
"delayed_cancel_at": null,
"coupon_code": null,
"total_revenue_in_cents": 0,
"product_price_in_cents": 0,
"product_version_number": 1,
"payment_type": null,
"referral_code": "d3pw7f",
"coupon_use_count": null,
"coupon_uses_allowed": null,
"reason_code": null,
"automatically_resume_at": null,
"current_billing_amount_in_cents": 10000,
"receives_invoice_emails": false,
"customer": {
"id": 17780587,
"first_name": "Catie",
"last_name": "Test",
"organization": "Acme, Inc.",
"email": "catie@example.com",
"created_at": "2017-06-27T13:01:05-05:00",
"updated_at": "2017-06-30T09:23:10-05:00",
"reference": "123ABC",
"address": "123 Anywhere Street",
"address_2": "Apartment #10",
"city": "Los Angeles",
"state": "CA",
"zip": "90210",
"country": "US",
"phone": "555-555-5555",
"portal_invite_last_sent_at": "2017-06-27T13:45:16-05:00",
"portal_invite_last_accepted_at": null,
"verified": true,
"portal_customer_created_at": "2017-06-27T13:01:08-05:00",
"cc_emails": "support@example.com",
"tax_exempt": true
},
"product": {
"id": 4470347,
"name": "Zero Dollar Product",
"handle": "zero-dollar-product",
"description": "",
"accounting_code": "",
"request_credit_card": true,
"expiration_interval": null,
"expiration_interval_unit": "never",
"created_at": "2017-03-23T10:54:12-05:00",
"updated_at": "2017-04-20T15:18:46-05:00",
"price_in_cents": 0,
"interval": 1,
"interval_unit": "month",
"initial_charge_in_cents": null,
"trial_price_in_cents": null,
"trial_interval": null,
"trial_interval_unit": "month",
"archived_at": null,
"require_credit_card": false,
"return_params": "",
"taxable": false,
"update_return_url": "",
"tax_code": "",
"initial_charge_after_trial": false,
"version_number": 1,
"update_return_params": "",
"product_family": {
"id": 997233,
"name": "Acme Products",
"description": "",
"handle": "acme-products",
"accounting_code": null
},
"public_signup_pages": [
{
"id": 316810,
"return_url": "",
"return_params": "",
"url": "https://general-goods.chargify.com/subscribe/69x825m78v3d/zero-dollar-product"
}
]
}
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Read Subscription
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscriptions/read-subscription
Retrieves subscription details.
If you have the new [Catalog experience](https://developers.maxio.com/http/help/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.
```http
GET /subscriptions/{subscription_id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `include` | [`array`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/subscription-include) | Query, Optional | Allows including additional data in the response. Use in query: `include[]=coupons&include[]=self_service_page_token`. |
# Response Type
**200**: OK
[`Subscription Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/subscription-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/subscriptions/222.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'include[]=coupons' \
-d 'include[]=self_service_page_token'
```
# Example Response *(as JSON)*
```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"
}
}
```
##### Override Subscription
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscriptions/override-subscription
Sets certain subscription fields that are usually managed automatically. Some of the fields can be set via the normal Subscriptions Update API, but others can only be set using this endpoint.
This endpoint is provided for cases where you need to “align” Advanced Billing data with data that happened in your system, perhaps before you started using Advanced Billing. For example, you may choose to import your historical subscription data, and would like the activation and cancellation dates in Advanced Billing to match your existing historical dates. Advanced Billing does not backfill historical events (i.e. from the Events API), but some static data can be changed via this API.
Why are some fields only settable from this endpoint, and not the normal subscription create and update endpoints? Because we want users of this endpoint to be aware that these fields are usually managed by Advanced Billing, and using this API means **you are stepping out on your own.**
Changing these fields will not affect any other attributes. For example, adding an expiration date will not affect the next assessment date on the subscription.
If you regularly need to override the current_period_starts_at for new subscriptions, this can also be accomplished by setting both `previous_billing_at` and `next_billing_at` at subscription creation. See the documentation on [Importing Subscriptions](./b3A6MTQxMDgzODg-create-subscription#subscriptions-import) for more information.
## Limitations
When passing `current_period_starts_at` some validations are made:
1. The subscription needs to be unbilled (no statements or invoices).
2. The value passed must be a valid date/time. We recommend using the iso 8601 format.
3. The value passed must be before the current date/time.
If unpermitted parameters are sent, a 400 HTTP response is sent along with a string giving the reason for the problem.
```http
PUT /subscriptions/{subscription_id}/override.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `body` | [`Override Subscription Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/override-subscription-request) | Body, Optional | Only these fields are available to be set. |
# Response Type
**204**: No Content
`Void`
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/subscriptions/222/override.json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"subscription": {
"activated_at": "1999-12-01T10:28:34-05:00",
"canceled_at": "2000-12-31T10:28:34-05:00",
"cancellation_message": "Original cancellation in 2000",
"expires_at": "2001-07-15T10:28:34-05:00"
}
}'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Single Error ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/single-error-response) |
##### Find Subscription
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscriptions/find-subscription
Finds a subscription by its reference.
```http
GET /subscriptions/lookup.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `reference` | `String` | Query, Optional | Subscription reference |
# Response Type
**200**: OK
[`Subscription Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/subscription-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/subscriptions/lookup.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description |
| --- | --- |
| 404 | Not Found |
##### Purge Subscription
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscriptions/purge-subscription
Purges an individual subscription for sites in test mode.
Provide the subscription ID in the URL. To confirm, supply the customer ID in the query string `ack` parameter. You may also delete the customer record and/or payment profiles by passing `cascade` parameters. For example, to delete just the customer record, the query params would be: `?ack={customer_id}&cascade[]=customer`
If you need to remove subscriptions from a live site, contact support to discuss your use case.
### Delete customer and payment profile
The query params will be: `?ack={customer_id}&cascade[]=customer&cascade[]=payment_profile`
```http
POST /subscriptions/{subscription_id}/purge.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `ack` | `Number` | Query, Required | id of the customer. |
| `cascade` | [`array`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/subscription-purge-type) | Query, Optional | Options are "customer" or "payment_profile". Use in query: `cascade[]=customer&cascade[]=payment_profile`. |
# Response Type
**200**: OK
[`Subscription Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/subscription-response)
# Example Usage
```bash
curl -X POST -G \
--url 'https://subdomain.chargify.com/subscriptions/222/purge.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'ack=252' \
-d 'cascade[]=customer' \
-d 'cascade[]=payment_profile'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 400 | Bad Request | [`Subscription Response_ErrorException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/subscription-response-error) |
##### Update Prepaid Subscription Configuration
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscriptions/update-prepaid-subscription-configuration
Updates a subscription's prepaid configuration.
```http
POST /subscriptions/{subscription_id}/prepaid_configurations.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `body` | [`Upsert Prepaid Configuration Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/upsert-prepaid-configuration-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Prepaid Configuration Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/prepaid-configuration-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscriptions/222/prepaid_configurations.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"prepaid_configuration": {
"initial_funding_amount_in_cents": 50000,
"replenish_to_amount_in_cents": 50000,
"auto_replenish": true,
"replenish_threshold_amount_in_cents": 10000
}
}'
```
# Example Response *(as JSON)*
```json
{
"prepaid_configuration": {
"id": 55,
"initial_funding_amount_in_cents": 2500,
"auto_replenish": true,
"replenish_to_amount_in_cents": 50000,
"replenish_threshold_amount_in_cents": 10000
}
}
```
# Errors
| HTTP Status Code | Error Description |
| --- | --- |
| 422 | Unprocessable Entity (WebDAV) |
##### Preview Subscription
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscriptions/preview-subscription
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](https://maxio.zendesk.com/hc/en-us/articles/24252493695757-Subscriber-Interface-Overview).
## Subscriptions can now work independently from the catalog
If you have the new [Catalog experience](https://developers.maxio.com/http/help/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)
`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](https://maxio.zendesk.com/hc/en-us/sections/24287012349325-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.
```http
POST /subscriptions/preview.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `body` | [`Create Subscription Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/create-subscription-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Subscription Preview Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/subscription-preview-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscriptions/preview.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"subscription": {
"product_handle": "gold-product"
}
}'
```
# Example Response *(as JSON)*
```json
{
"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
}
}
}
```
##### Apply Coupons to Subscription
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscriptions/apply-coupons-to-subscription
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.
```http
POST /subscriptions/{subscription_id}/add_coupon.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `code` | `String` | Query, Optional | A code for the coupon that would be applied to a subscription |
| `body` | [`Add Coupons Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/add-coupons-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Subscription Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/subscription-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscriptions/222/add_coupon.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"codes": [
"COUPON_1",
"COUPON_2"
]
}'
```
# Example Response *(as JSON)*
```json
{
"subscription": {
"id": 21607180,
"state": "active",
"trial_started_at": null,
"trial_ended_at": null,
"activated_at": "2018-04-20T14:20:57-05:00",
"created_at": "2018-04-20T14:20:57-05:00",
"updated_at": "2018-05-11T13:53:44-05:00",
"expires_at": null,
"balance_in_cents": 49000,
"current_period_ends_at": "2018-05-12T11:33:03-05:00",
"next_assessment_at": "2018-05-12T11:33:03-05:00",
"canceled_at": null,
"cancellation_message": null,
"next_product_id": null,
"cancel_at_end_of_period": false,
"payment_collection_method": "remittance",
"snap_day": null,
"cancellation_method": null,
"current_period_started_at": "2018-05-11T11:33:03-05:00",
"previous_state": "active",
"signup_payment_id": 237154761,
"signup_revenue": "0.00",
"delayed_cancel_at": null,
"coupon_code": "COUPONA",
"total_revenue_in_cents": 52762,
"product_price_in_cents": 100000,
"product_version_number": 2,
"payment_type": "credit_card",
"referral_code": "x45nc8",
"coupon_use_count": 0,
"coupon_uses_allowed": 1,
"reason_code": null,
"automatically_resume_at": null,
"coupon_codes": [
"COUPONA",
"COUPONB"
],
"customer": {
"id": 21259051,
"first_name": "K",
"last_name": "C",
"organization": "",
"email": "example@chargify.com",
"created_at": "2018-04-20T14:20:57-05:00",
"updated_at": "2018-04-23T15:29:28-05:00",
"reference": null,
"address": "",
"address_2": "",
"city": "",
"state": "",
"zip": "",
"country": "",
"phone": "",
"portal_invite_last_sent_at": "2018-04-20T14:20:59-05:00",
"portal_invite_last_accepted_at": null,
"verified": false,
"portal_customer_created_at": "2018-04-20T14:20:59-05:00",
"cc_emails": "",
"tax_exempt": false
},
"product": {
"id": 4581816,
"name": "Basic",
"handle": "basic",
"description": "",
"accounting_code": "",
"request_credit_card": true,
"expiration_interval": null,
"expiration_interval_unit": "never",
"created_at": "2017-11-02T15:00:11-05:00",
"updated_at": "2018-04-10T09:02:59-05:00",
"price_in_cents": 100000,
"interval": 1,
"interval_unit": "month",
"initial_charge_in_cents": 100000,
"trial_price_in_cents": 1000,
"trial_interval": 10,
"trial_interval_unit": "month",
"archived_at": null,
"require_credit_card": true,
"return_params": "",
"taxable": false,
"update_return_url": "",
"tax_code": "",
"initial_charge_after_trial": false,
"version_number": 2,
"update_return_params": "",
"product_family": {
"id": 1025627,
"name": "My Product Family",
"description": "",
"handle": "acme-products",
"accounting_code": null
},
"public_signup_pages": [
{
"id": 333589,
"return_url": "",
"return_params": "",
"url": "https://general-goods.chargifypay.com/subscribe/hbwtd98j3hk2/basic"
},
{
"id": 335926,
"return_url": "",
"return_params": "",
"url": "https://general-goods.chargifypay.com/subscribe/g366zy67c7rm/basic"
},
{
"id": 345555,
"return_url": "",
"return_params": "",
"url": "https://general-goods.chargifypay.com/subscribe/txqyyqk7d8rz/basic"
},
{
"id": 345556,
"return_url": "",
"return_params": "",
"url": "https://general-goods.chargifypay.com/subscribe/2zss3qpf4249/basic"
}
]
},
"credit_card": {
"id": 14839830,
"first_name": "John",
"last_name": "Doe",
"masked_card_number": "XXXX-XXXX-XXXX-1",
"card_type": "bogus",
"expiration_month": 1,
"expiration_year": 2028,
"customer_id": 21259051,
"current_vault": "bogus",
"vault_token": "1",
"billing_address": null,
"billing_city": null,
"billing_state": null,
"billing_zip": "99999",
"billing_country": null,
"customer_vault_token": null,
"billing_address_2": null,
"payment_type": "credit_card"
}
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Subscription Add Coupon ErrorException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/subscription-add-coupon-error) |
##### Remove Coupon from Subscription
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscriptions/remove-coupon-from-subscription
Removes a coupon from an existing subscription.
For more information on the expected behavior of removing a coupon from a subscription, see [Coupons and Subscriptions](https://maxio.zendesk.com/hc/en-us/articles/24261259337101-Coupons-and-Subscriptions#removing-a-coupon).
```http
DELETE /subscriptions/{subscription_id}/remove_coupon.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `coupon_code` | `String` | Query, Optional | The coupon code |
# Response Type
**200**: OK
`String`
# Example Usage
```bash
curl -X DELETE -G \
--url 'https://subdomain.chargify.com/subscriptions/222/remove_coupon.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response
```
"Coupon successfully removed"
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Subscription Remove Coupon ErrorsException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/subscription-remove-coupon-errors) |
##### Activate Subscription
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscriptions/activate-subscription
Activates awaiting signup and trialing subscriptions. This feature is only available on the Relationship Invoicing architecture. Subscriptions in a group cannot be activated immediately.
The `revert_on_failure` parameter controls the behavior upon activation failure.
- If set to `true` and something goes wrong i.e. payment fails, the subscription's state does not change. The subscription’s billing period also remains the same.
- If set to `false` and something goes wrong i.e. payment fails, the activation continues and enters an end of life state. For trialing subscriptions, that is either trial ended (if the trial is no obligation), past due (if the trial has an obligation), or canceled (if the site has no dunning strategy, or has a strategy that says to cancel immediately). For awaiting signup subscriptions, that is always canceled.
The default activation failure behavior can be configured per activation attempt, or you can set a default value under Config > Settings > Subscription Activation Settings.
## Activation Scenarios
### Activate Awaiting Signup subscription
- Given you have a product without trial
- Given you have a site without dunning strategy
```mermaid
flowchart LR
AS[Awaiting Signup] --> A{Activate}
A -->|Success| Active
A -->|Failure| ROF{revert_on_failure}
ROF -->|true| AS
ROF -->|false| Canceled
```
- Given you have a product with trial
- Given you have a site with dunning strategy
```mermaid
flowchart LR
AS[Awaiting Signup] --> A{Activate}
A -->|Success| Trialing
A -->|Failure| ROF{revert_on_failure}
ROF -->|true| AS
ROF -->|false| PD[Past Due]
```
### Activate Trialing subscription
For more information about the behavior of trialing subscriptions, see [Trialing Subscriptions](https://maxio.zendesk.com/hc/en-us/articles/24252155721869-Trialing-Subscriptions).
When the `revert_on_failure` parameter is set to `true`, the subscription's state remains Trialing; the invoice from activation is voided, and any prepayments and credits applied to the invoice are returned to the subscription.
```http
PUT /subscriptions/{subscription_id}/activate.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `body` | [`Activate Subscription Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/activate-subscription-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Subscription Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/subscription-response)
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/subscriptions/222/activate.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 400 | Bad Request | [`Error Array Map ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-array-map-response) |
#### Subscription Components
##### Read Subscription Component
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-components/read-subscription-component
Returns information for a specific component on a subscription.
```http
GET /subscriptions/{subscription_id}/components/{component_id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `component_id` | `Number` | Template, Required | The Advanced Billing id of the component. Alternatively, the component's handle prefixed by `handle:` |
# Response Type
**200**: OK
[`Subscription Component Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/subscription-component-response)
# Example Usage
```bash
curl -X GET \
--url 'https://subdomain.chargify.com/subscriptions/222/components/222.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"component": {
"component_id": 193028,
"subscription_id": 14593192,
"allocated_quantity": 1,
"pricing_scheme": "per_unit",
"name": "Users",
"kind": "quantity_based_component",
"unit_name": "Users",
"price_point_id": 1,
"price_point_handle": "top-tier",
"enabled": true
}
}
```
# Errors
| HTTP Status Code | Error Description |
| --- | --- |
| 404 | Not Found |
##### List Subscription Components
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-components/list-subscription-components
Lists a subscription's applied components.
## Archived Components
When requesting to list components for a given subscription, if the subscription contains **archived** components they will be listed in the server response.
```http
GET /subscriptions/{subscription_id}/components.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `date_field` | [`Subscription List Date Field`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/subscription-list-date-field) | Query, Optional | The type of filter you'd like to apply to your search. Use in query `date_field=updated_at`. |
| `direction` | [`Sorting Direction`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/sorting-direction) | Query, Optional | Controls the order in which results are returned. Use in query `direction=asc`. |
| `filter` | [`List Subscription Components Filter`](https://developers.maxio.com/http/advanced-billing-api/models/structures/list-subscription-components-filter) | Query, Optional | Filter to use for List Subscription Components operation |
| `end_date` | `String` | Query, Optional | The end date (format YYYY-MM-DD) with which to filter the date_field. Returns components with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified. |
| `end_datetime` | `String` | Query, Optional | The end date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns components with a timestamp at or before exact time provided in query. You can specify timezone in query - otherwise your site''s time zone will be used. If provided, this parameter will be used instead of end_date. |
| `price_point_ids` | [`Include Not Null`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/include-not-null) | Query, Optional | Allows fetching components allocation only if price point id is present. Use in query `price_point_ids=not_null`. |
| `product_family_ids` | `array` | Query, Optional | Allows fetching components allocation with matching product family id based on provided ids. Use in query `product_family_ids=1,2,3`. |
| `sort` | [`List Subscription Components Sort`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/list-subscription-components-sort) | Query, Optional | The attribute by which to sort. Use in query `sort=updated_at`. |
| `start_date` | `String` | Query, Optional | The start date (format YYYY-MM-DD) with which to filter the date_field. Returns components with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified. |
| `start_datetime` | `String` | Query, Optional | The start date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns components with a timestamp at or after exact time provided in query. You can specify timezone in query - otherwise your site''s time zone will be used. If provided, this parameter will be used instead of start_date. |
| `include` | [`array`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/list-subscription-components-include) | Query, Optional | Allows including additional data in the response. Use in query `include=subscription,historic_usages`. |
| `in_use` | `Boolean` | Query, Optional | If in_use is set to true, it returns only components that are currently in use. However, if it's set to false or not provided, it returns all components connected with the subscription. |
# Response Type
**200**: OK
[`array`](https://developers.maxio.com/http/advanced-billing-api/models/structures/subscription-component-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/subscriptions/222/components.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'date_field=updated_at' \
-d 'filter[currencies]=EUR%2CUSD' \
-d 'price_point_ids=not_null' \
-d 'product_family_ids=1%2C2%2C3' \
-d 'sort=updated_at' \
-d 'include=subscription%2Chistoric_usages' \
-d 'in_use=true'
```
# Example Response *(as JSON)*
```json
[
{
"component": {
"component_id": 0,
"subscription_id": 0,
"allocated_quantity": 0,
"pricing_scheme": "per_unit",
"name": "string",
"kind": "quantity_based_component",
"unit_name": "string",
"price_point_id": 0,
"price_point_handle": "string",
"price_point_type": "default",
"price_point_name": "string",
"enabled": true,
"unit_balance": 0,
"id": 0,
"created_at": "2022-02-22T14:07:00-05:00",
"updated_at": "2022-02-22T14:07:00-05:00",
"component_handle": "string",
"archived_at": null
}
}
]
```
##### Bulk Update Subscription Components Price Points
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-components/bulk-update-subscription-components-price-points
Updates the price points on one or more of a subscription's components.
The `price_point` key can take either a:
1. Price point id (integer)
2. Price point handle (string)
3. `"_default"` string, which will reset the price point to the component's current default price point.
```http
POST /subscriptions/{subscription_id}/price_points.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `body` | [`Bulk Components Price Point Assignment`](https://developers.maxio.com/http/advanced-billing-api/models/structures/bulk-components-price-point-assignment) | Body, Optional | - |
# Response Type
**200**: OK
[`Bulk Components Price Point Assignment`](https://developers.maxio.com/http/advanced-billing-api/models/structures/bulk-components-price-point-assignment)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscriptions/222/price_points.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"components": [
{
"component_id": 997,
"price_point": 1022
},
{
"component_id": 998,
"price_point": "wholesale-handle"
},
{
"component_id": 999,
"price_point": "_default"
}
]
}'
```
# Example Response *(as JSON)*
```json
{
"components": [
{
"component_id": 123,
"price_point": 456
},
{
"component_id": 789,
"price_point": 987
}
]
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Component PricePoint ErrorException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/component-price-point-error) |
##### Bulk Reset Subscription Components Price Points
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-components/bulk-reset-subscription-components-price-points
Resets all of a subscription's components to use the current default.
**Note**: this will update the price point for all of the subscription's components, even ones that have not been allocated yet.
```http
POST /subscriptions/{subscription_id}/price_points/reset.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
# Response Type
**201**: Created
[`Subscription Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/subscription-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscriptions/222/price_points/reset.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"subscription": {
"id": 80293620,
"state": "active",
"trial_started_at": null,
"trial_ended_at": null,
"activated_at": "2023-11-23T10:28:34-05:00",
"created_at": "2023-11-23T10:28:34-05:00",
"updated_at": "2023-11-23T10:28:34-05:00",
"expires_at": null,
"balance_in_cents": 50504234,
"current_period_ends_at": "2023-11-23T10:28:34-05:00",
"next_assessment_at": "2023-11-23T10:28:34-05:00",
"canceled_at": null,
"cancellation_message": "lorem ipsum",
"next_product_id": null,
"cancel_at_end_of_period": false,
"payment_collection_method": "remittance",
"snap_day": null,
"cancellation_method": "dunning",
"current_period_started_at": "2023-11-23T10:28:34-05:00",
"previous_state": "active",
"signup_payment_id": -45156092,
"signup_revenue": "do aliquip ea",
"delayed_cancel_at": null,
"coupon_code": null,
"total_revenue_in_cents": -49740952,
"product_price_in_cents": 87617888,
"product_version_number": 13656635,
"payment_type": null,
"referral_code": null,
"coupon_use_count": null,
"coupon_uses_allowed": null,
"reason_code": null,
"automatically_resume_at": null,
"current_billing_amount_in_cents": -26151968,
"customer": {
"id": 15208337,
"first_name": "ipsum culpa in labore eiusmod",
"last_name": "esse",
"organization": null,
"email": "ex eiusmod",
"created_at": "2021-05-05T16:00:21-04:00",
"updated_at": "2021-05-05T16:00:21-04:00",
"reference": "laboris ea cupidatat",
"address": null,
"address_2": null,
"city": "id eiusmod proident",
"state": "magna eiusmod anim non",
"zip": null,
"country": null,
"phone": null,
"portal_invite_last_sent_at": null,
"portal_invite_last_accepted_at": "2021-05-05T20:00:21-04:00",
"portal_customer_created_at": "2021-05-05T16:00:21-04:00",
"cc_emails": "eiusmod sunt",
"tax_exempt": true
},
"product": {
"id": -74447756,
"name": "eu mollit nulla ut aute",
"handle": "esse dolor anim",
"description": "Lorem ut et non",
"accounting_code": "nisi",
"request_credit_card": false,
"expiration_interval": 1,
"expiration_interval_unit": "day",
"created_at": "2022-11-23T10:28:34-05:00",
"updated_at": "2022-11-23T10:28:34-05:00",
"price_in_cents": -4151649,
"interval": 20680876,
"interval_unit": "day",
"initial_charge_in_cents": null,
"trial_price_in_cents": null,
"trial_interval": null,
"trial_interval_unit": "day",
"archived_at": null,
"require_credit_card": true,
"return_params": "magna eu",
"taxable": true,
"update_return_url": "exercitation in",
"tax_code": "Excepteur aliqua sunt in",
"initial_charge_after_trial": true,
"version_number": 41642597,
"update_return_params": "dolore labore",
"product_family": {
"id": -5356997,
"name": "officia amet Lorem proident enim",
"description": "Duis",
"handle": "ea dolore dolore sunt",
"accounting_code": null
}
}
}
}
```
##### Allocate Component
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-components/allocate-component
Creates an allocation, sets the current allocated quantity for the component, and records a memo. Allocations can only be updated for Quantity, On/Off, and Prepaid Components.
When creating an allocation via the API, you can pass the `upgrade_charge`, `downgrade_credit`, and `accrue_charge` to be applied.
> **Note:** These proration and accrual fields are ignored for Prepaid Components since this component type always generates charges immediately without proration.
For information on prorated components and upgrade/downgrade schemes, see [Setting Component Allocations.](https://maxio.zendesk.com/hc/en-us/articles/24251906165133-Component-Allocations-Proration)
### Order of Resolution for upgrade_charge and downgrade_credit
1. Per allocation in API call (within a single allocation of the `allocations` array)
2. [Component-level default value](https://maxio.zendesk.com/hc/en-us/articles/24251883961485-Component-Allocations-Overview)
3. Allocation API call top level (outside of the `allocations` array)
4. [Site-level default value](https://maxio.zendesk.com/hc/en-us/articles/24251906165133-Component-Allocations-Proration#proration-schemes)
### Order of Resolution for accrue charge
1. Allocation API call top level (outside of the `allocations` array)
2. [Site-level default value](https://maxio.zendesk.com/hc/en-us/articles/24251906165133-Component-Allocations-Proration#proration-schemes)
> **Note:** Proration uses the current price of the component as well as the current tax rates. Changes to either may cause the prorated charge/credit to be wrong.
For more information, see the [Component Allocations](https://maxio.zendesk.com/hc/en-us/articles/24251883961485-Component-Allocations-Overview) product Documentation.
```http
POST /subscriptions/{subscription_id}/components/{component_id}/allocations.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `component_id` | `Number` | Template, Required | The Advanced Billing id of the component |
| `body` | [`Create Allocation Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/create-allocation-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Allocation Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/allocation-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscriptions/222/components/222/allocations.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"allocation": {
"quantity": 10.0,
"decimal_quantity": "10.0",
"previous_quantity": 5.0,
"decimal_previous_quantity": "5.0",
"memo": "Increase seats to 10",
"proration_upgrade_scheme": "full-price-attempt-capture",
"proration_downgrade_scheme": "prorate",
"accrue_charge": false,
"upgrade_charge": "full",
"downgrade_credit": "prorated",
"price_point_id": 789,
"billing_schedule": {
"initial_billing_at": "2025-02-28"
},
"custom_price": {
"pricing_scheme": "per_unit",
"tax_included": false,
"renew_prepaid_allocation": false,
"rollover_prepaid_remainder": false,
"expiration_interval": 150,
"expiration_interval_unit": "never",
"interval": 1,
"interval_unit": "month",
"list_price_point_id": 4321,
"use_default_list_price": false,
"prices": [
{
"starting_quantity": 1,
"ending_quantity": 25,
"unit_price": "49.00"
},
{
"starting_quantity": 26,
"ending_quantity": null,
"unit_price": "39.00"
}
]
}
}
}'
```
# Example Response *(as JSON)*
```json
{
"allocation": {
"component_id": 4034995,
"subscription_id": 23737320,
"quantity": 3,
"previous_quantity": 2,
"memo": "dolore cupidatat elit",
"timestamp": "2022-11-23T10:28:34-05:00",
"proration_upgrade_scheme": "laboris ipsum dolore",
"proration_downgrade_scheme": "eiusmod dolore",
"price_point_id": -69720370,
"previous_price_point_id": -76493052,
"accrue_charge": true,
"upgrade_charge": "full",
"downgrade_credit": "full",
"payment": {
"id": -44566528,
"amount_in_cents": 123,
"success": false,
"memo": "aliqua"
}
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### List Allocations
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-components/list-allocations
Lists the 50 most recent Allocations, ordered by most recent first.
## On/Off Components
When a subscription's on/off component has been toggled to on (`1`) or off (`0`), usage will be logged in this response.
```http
GET /subscriptions/{subscription_id}/components/{component_id}/allocations.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `component_id` | `Number` | Template, Required | The Advanced Billing id of the component |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
# Response Type
**200**: OK
[`array`](https://developers.maxio.com/http/advanced-billing-api/models/structures/allocation-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/subscriptions/222/components/222/allocations.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'page=1'
```
# Example Response *(as JSON)*
```json
[
{
"allocation": {
"allocation_id": 2370199,
"component_id": 41028,
"subscription_id": 352827,
"quantity": 10,
"previous_quantity": 0,
"memo": "Recoding component allocation",
"timestamp": "2024-02-28T09:31:05Z",
"proration_upgrade_scheme": "full-price-attempt-capture",
"proration_downgrade_scheme": "no-prorate",
"price_point_id": 2957424,
"price_point_handle": "uuid:03190e20-b84a-013c-ca77-0286551bb34f",
"price_point_name": "Original",
"previous_price_point_id": 2957424,
"component_handle": "test-prepaid-component-4982065948",
"accrue_charge": false,
"upgrade_charge": "full",
"downgrade_credit": "none",
"created_at": "2024-02-28T04:31:05-05:00",
"initiate_dunning": false,
"expires_at": "2024-08-03T20:00:00-04:00",
"used_quantity": 5,
"charge_id": 11586076
}
},
{
"allocation": {
"memo": null,
"timestamp": "2012-11-20T21:48:09Z",
"quantity": 3,
"previous_quantity": 0,
"component_id": 11960,
"subscription_id": 2585595,
"proration_upgrade_scheme": "no-prorate",
"proration_downgrade_scheme": "no-prorate"
}
}
]
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Allocate Components
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-components/allocate-components
Creates multiple allocations, sets the current allocated quantity for each of the components, and records a memo. A `component_id` is required for each allocation.
The charges and/or credits that are created will be rolled up into a single total which is used to determine whether this is an upgrade or a downgrade.
### Order of Resolution for upgrade_charge and downgrade_credit
1. Per allocation in API call (within a single allocation of the `allocations` array)
2. [Component-level default value](https://maxio.zendesk.com/hc/en-us/articles/24251883961485-Component-Allocations-Overview)
3. Allocation API call top level (outside of the `allocations` array)
4. [Site-level default value](https://maxio.zendesk.com/hc/en-us/articles/24251906165133-Component-Allocations-Proration#proration-schemes)
### Order of Resolution for accrue charge
1. Allocation API call top level (outside of the `allocations` array)
2. [Site-level default value](https://maxio.zendesk.com/hc/en-us/articles/24251906165133-Component-Allocations-Proration#proration-schemes)
> **Note:** Proration uses the current price of the component as well as the current tax rates. Changes to either may cause the prorated charge/credit to be wrong.
For more information, see the [Component Allocations](https://maxio.zendesk.com/hc/en-us/articles/24251883961485-Component-Allocations-Overview) product documentation.
```http
POST /subscriptions/{subscription_id}/allocations.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `body` | [`Allocate Components`](https://developers.maxio.com/http/advanced-billing-api/models/structures/allocate-components) | Body, Optional | - |
# Response Type
**200**: OK
[`array`](https://developers.maxio.com/http/advanced-billing-api/models/structures/allocation-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscriptions/222/allocations.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"proration_upgrade_scheme": "prorate-attempt-capture",
"proration_downgrade_scheme": "no-prorate",
"allocations": [
{
"component_id": 123,
"quantity": 10.0,
"memo": "foo"
},
{
"component_id": 456,
"quantity": 5.0,
"memo": "bar"
}
]
}'
```
# Example Response *(as JSON)*
```json
[
{
"allocation": {
"component_id": 193159,
"subscription_id": 15540611,
"quantity": 10,
"previous_quantity": 0,
"memo": "foo",
"timestamp": "2016-12-08T19:09:15Z",
"proration_upgrade_scheme": "prorate-attempt-capture",
"proration_downgrade_scheme": "no-prorate",
"payment": {
"amount_in_cents": 1451,
"success": true,
"memo": "Payment for: Prorated component allocation changes.",
"id": 165473487
}
}
},
{
"allocation": {
"component_id": 277221,
"subscription_id": 15540611,
"quantity": 5,
"previous_quantity": 0,
"memo": "bar",
"timestamp": "2016-12-08T19:09:15Z",
"proration_upgrade_scheme": "prorate-attempt-capture",
"proration_downgrade_scheme": "no-prorate",
"payment": {
"amount_in_cents": 1451,
"success": true,
"memo": "Payment for: Prorated component allocation changes.",
"id": 165473487
}
}
}
]
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Preview Allocations
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-components/preview-allocations
Previews a potential subscription's **quantity-based** or **on/off** component allocation in the middle of the current billing period. This is useful if you want users to be able to see the effect of a component operation before actually doing it.
## Fine-grained Component Control: Use with multiple `upgrade_charge`s or `downgrade_credits`
When the allocation uses multiple different types of `upgrade_charge`s or `downgrade_credit`s, the Allocation is viewed as an Allocation which uses "Fine-Grained Component Control". As a result, the response will not include `direction` and `proration` within the `allocation_preview`, but at the `line_items` and `allocations` level respectfully.
See example below for Fine-Grained Component Control response.
```http
POST /subscriptions/{subscription_id}/allocations/preview.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `body` | [`Preview Allocations Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/preview-allocations-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Allocation Preview Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/allocation-preview-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscriptions/222/allocations/preview.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"allocations": [
{
"proration_upgrade_scheme": "prorate-attempt-capture",
"proration_downgrade_scheme": "prorate",
"component_id": 554108,
"price_point_id": 325826,
"quantity": 10.0,
"memo": "NOW"
}
],
"effective_proration_date": "2023-11-01"
}'
```
# Example Response *(as JSON)*
```json
{
"allocation_preview": {
"start_date": "2019-05-02T15:26:46Z",
"end_date": "2019-05-08T15:26:46Z",
"period_type": "prorated",
"total_in_cents": 150,
"total_discount_in_cents": 0,
"total_tax_in_cents": 0,
"subtotal_in_cents": 150,
"existing_balance_in_cents": 0,
"accrue_charge": true,
"line_items": [
{
"direction": "upgrade",
"transaction_type": "charge",
"kind": "quantity_based_component",
"amount_in_cents": 100,
"taxable_amount_in_cents": 0,
"discount_amount_in_cents": 0,
"memo": "Foo: 0 to 10 foo",
"component_id": 123,
"component_handle": "foo"
},
{
"direction": "downgrade",
"transaction_type": "credit",
"kind": "quantity_based_component",
"amount_in_cents": -20,
"taxable_amount_in_cents": 0,
"discount_amount_in_cents": 0,
"memo": "Foo: 10 to 5 bar",
"component_id": 456,
"component_handle": "bar"
},
{
"direction": "upgrade",
"transaction_type": "credit",
"kind": "quantity_based_component",
"amount_in_cents": 70,
"taxable_amount_in_cents": 0,
"discount_amount_in_cents": 0,
"memo": "Foo: 0 to 10 baz",
"component_id": 789,
"component_handle": "baz"
}
],
"allocations": [
{
"accrue_charge": true,
"upgrade_charge": "prorated",
"downgrade_credit": "full",
"component_handle": "foo",
"component_id": 123,
"memo": "foo",
"previous_price_point_id": 123,
"previous_quantity": 0,
"price_point_id": 123,
"proration_downgrade_scheme": "full",
"proration_upgrade_scheme": "prorate-delay-capture",
"quantity": 10,
"subscription_id": 123456,
"timestamp": null
},
{
"accrue_charge": true,
"upgrade_charge": "full",
"downgrade_credit": "prorated",
"component_handle": "bar",
"component_id": 456,
"memo": "foo",
"previous_price_point_id": 456,
"previous_quantity": 10,
"price_point_id": 456,
"proration_downgrade_scheme": "prorate",
"proration_upgrade_scheme": "full-price-delay-capture",
"quantity": 5,
"subscription_id": 123456,
"timestamp": null
},
{
"accrue_charge": true,
"upgrade_charge": "full",
"downgrade_credit": "none",
"component_handle": "baz",
"component_id": 789,
"memo": "foo",
"previous_price_point_id": 789,
"previous_quantity": 0,
"price_point_id": 789,
"proration_downgrade_scheme": "no-prorate",
"proration_upgrade_scheme": "full-price-delay-capture",
"quantity": 10,
"subscription_id": 123456,
"timestamp": null
}
]
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Component Allocation ErrorException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/component-allocation-error) |
##### Update Prepaid Usage Allocation Expiration Date
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-components/update-prepaid-usage-allocation-expiration-date
Updates the expiration date for a prepaid usage allocation. This expiration date can be changed after the fact to allow for extending or shortening the allocation's active window.
In order to change a prepaid usage allocation's expiration date, a PUT call must be made to the allocation's endpoint with a new expiration date.
## Limitations
A few limitations exist when changing an allocation's expiration date:
- An expiration date can only be changed for an allocation that belongs to a price point with expiration interval options explicitly set.
- An expiration date can be changed towards the future with no limitations.
- An expiration date can be changed towards the past (essentially expiring it) up to the subscription's current period beginning date.
```http
PUT /subscriptions/{subscription_id}/components/{component_id}/allocations/{allocation_id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `component_id` | `Number` | Template, Required | The Advanced Billing id of the component |
| `allocation_id` | `Number` | Template, Required | The Advanced Billing id of the allocation |
| `body` | [`Update Allocation Expiration Date`](https://developers.maxio.com/http/advanced-billing-api/models/structures/update-allocation-expiration-date) | Body, Optional | - |
# Response Type
**204**: OK
`Void`
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/subscriptions/222/components/222/allocations/24.json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"allocation": {
"expires_at": "2021-05-05T16:00:00"
}
}'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | |
| 422 | Unprocessable Entity (WebDAV) | [`Subscription Component Allocation ErrorException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/subscription-component-allocation-error) |
##### Delete Prepaid Usage Allocation
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-components/delete-prepaid-usage-allocation
Deletes a prepaid usage allocation.
Prepaid Usage components are unique in that their allocations are always additive. In order to reduce a subscription's allocated quantity for a prepaid usage component, each allocation must be destroyed individually via this endpoint.
## Credit Scheme
By default, destroying an allocation will generate a service credit on the subscription. This behavior can be modified with the optional `credit_scheme` parameter on this endpoint. The accepted values are:
1. `none`: The allocation will be destroyed and the balances will be updated but no service credit or refund will be created.
2. `credit`: The allocation will be destroyed and the balances will be updated and a service credit will be generated. This is also the default behavior if the `credit_scheme` param is not passed.
3. `refund`: The allocation will be destroyed and the balances will be updated and a refund will be issued along with a Credit Note.
```http
DELETE /subscriptions/{subscription_id}/components/{component_id}/allocations/{allocation_id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `component_id` | `Number` | Template, Required | The Advanced Billing id of the component |
| `allocation_id` | `Number` | Template, Required | The Advanced Billing id of the allocation |
| `body` | [`Credit Scheme Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/credit-scheme-request) | Body, Optional | - |
# Response Type
**200**: OK
`Void`
# Example Usage
```bash
curl -X DELETE \
--url 'https://subdomain.chargify.com/subscriptions/222/components/222/allocations/24.json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"credit_scheme": "none"
}'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | |
| 422 | Unprocessable Entity (WebDAV) | [`Subscription Component Allocation ErrorException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/subscription-component-allocation-error) |
##### Create Usage
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-components/create-usage
Records an instance of metered or prepaid usage for a subscription.
You can report metered or prepaid usage to Advanced Billing as often as you wish. You can report usage as it happens or periodically, such as each night or once per billing period.
Full documentation on how to create Components in the Advanced Billing UI can be located [here](https://maxio.zendesk.com/hc/en-us/articles/24261149711501-Create-Edit-and-Archive-Components). Additionally, for information on how to record component usage against a subscription, see the following resources:
It is not possible to record metered usage for more than one component at a time. Usage should be reported as one API call per component on a single subscription. For example, to record that a subscriber has sent both an SMS Message and an Email, send an API call for each.
See the following product documentation articles for more information:
- [Create and Manage Components](https://maxio.zendesk.com/hc/en-us/articles/24261149711501-Create-Edit-and-Archive-Components)
- [Recording Metered Component Usage](https://maxio.zendesk.com/hc/en-us/articles/24251890500109-Reporting-Component-Allocations#reporting-metered-component-usage)
- [Reporting Prepaid Component Status](https://maxio.zendesk.com/hc/en-us/articles/24251890500109-Reporting-Component-Allocations#reporting-prepaid-component-status)
The `quantity` from usage for each component is accumulated to the `unit_balance` on the [Component Line Item](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-components/read-subscription-component) for the subscription.
## Price Point ID usage
If you are using price points, for metered and prepaid usage components Advanced Billing gives you the option to specify a price point in your request.
You do not need to specify a price point ID. If a price point is not included, the default price point for the component will be used when the usage is recorded.
## Deducting Usage
If you need to reverse a previous usage report or otherwise deduct from the current usage balance, you can provide a negative quantity.
Example:
Previously recorded quantity was 5000:
```json
{
"usage": {
"quantity": 5000,
"memo": "Recording 5000 units"
}
}
```
To reduce the quantity to `0`, POST the following payload:
```json
{
"usage": {
"quantity": -5000,
"memo": "Deducting 5000 units"
}
}
```
The `unit_balance` has a floor of `0`; negative unit balances are never allowed. For example, if the usage balance is 100 and you deduct 200 units, the unit balance would then be `0`, not `-100`.
```http
POST /subscriptions/{subscription_id_or_reference}/components/{component_id}/usages.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id_or_reference` | [`Number \| String`](https://developers.maxio.com/http/advanced-billing-api/models/oneof-anyof-definitions/create-usage-subscription-id-or-reference) | Template, Required | Either the Advanced Billing subscription ID (integer) or the subscription reference (string). Important: In cases where a numeric string value matches both an existing subscription ID and an existing subscription reference, the system will prioritize the subscription ID lookup. For example, if both subscription ID 123 and subscription reference "123" exist, passing "123" will return the subscription with ID 123. |
| `component_id` | [`Number \| String`](https://developers.maxio.com/http/advanced-billing-api/models/oneof-anyof-definitions/create-usage-component-id) | Template, Required | Either the Advanced Billing id for the component or the component's handle prefixed by `handle:` |
| `body` | [`Create Usage Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/create-usage-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Usage Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/usage-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscriptions/234/components/144/usages.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"usage": {
"quantity": 1000.0,
"price_point_id": "149416",
"memo": "My memo"
}
}'
```
# Example Response *(as JSON)*
```json
{
"usage": {
"id": 138522957,
"memo": "My memo",
"created_at": "2017-11-13T10:05:32-06:00",
"price_point_id": 149416,
"quantity": 1000,
"component_id": 500093,
"component_handle": "handle",
"subscription_id": 22824464
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### List Usages
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-components/list-usages
Lists usages associated with a subscription for a particular metered component. This will display the previously recorded components for a subscription.
This endpoint is not compatible with quantity-based components.
## Since Date and Until Date Usage
Note: The `since_date` and `until_date` attributes each default to midnight on the date specified. For example, in order to list usages for January 20th, you would need to append the following to the URL.
```
?since_date=2016-01-20&until_date=2016-01-21
```
## Read Usage by Handle
Use this endpoint to read the previously recorded components for a subscription. You can now specify either the component id (integer) or the component handle prefixed by "handle:" to specify the unique identifier for the component you are working with.
```http
GET /subscriptions/{subscription_id_or_reference}/components/{component_id}/usages.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id_or_reference` | [`Number \| String`](https://developers.maxio.com/http/advanced-billing-api/models/oneof-anyof-definitions/list-usages-subscription-id-or-reference) | Template, Required | Either the Advanced Billing subscription ID (integer) or the subscription reference (string). Important: In cases where a numeric string value matches both an existing subscription ID and an existing subscription reference, the system will prioritize the subscription ID lookup. For example, if both subscription ID 123 and subscription reference "123" exist, passing "123" will return the subscription with ID 123. |
| `component_id` | [`Number \| String`](https://developers.maxio.com/http/advanced-billing-api/models/oneof-anyof-definitions/list-usages-component-id) | Template, Required | Either the Advanced Billing id for the component or the component's handle prefixed by `handle:` |
| `since_id` | `Long` | Query, Optional | Returns usages with an id greater than or equal to the one specified. |
| `max_id` | `Long` | Query, Optional | Returns usages with an id less than or equal to the one specified. |
| `since_date` | `Date` | Query, Optional | Returns usages with a created_at date greater than or equal to midnight (12:00 AM) on the date specified. |
| `until_date` | `Date` | Query, Optional | Returns usages with a created_at date less than or equal to midnight (12:00 AM) on the date specified. |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query `per_page=200`.
**Default**: `20`
**Constraints**: `<= 200` |
# Response Type
**200**: OK
[`array`](https://developers.maxio.com/http/advanced-billing-api/models/structures/usage-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/subscriptions/234/components/144/usages.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'page=1' \
-d 'per_page=50'
```
# Example Response *(as JSON)*
```json
[
{
"usage": {
"id": 178534642,
"memo": "20",
"created_at": "2018-08-03T11:58:42-05:00",
"price_point_id": 242632,
"quantity": "20.0",
"component_id": 500093,
"component_handle": "handle",
"subscription_id": 22824464
}
},
{
"usage": {
"id": 178534591,
"memo": "10",
"created_at": "2018-08-03T11:58:29-05:00",
"price_point_id": 242632,
"quantity": "10.0",
"component_id": 500093,
"component_handle": "handle",
"subscription_id": 22824464
}
}
]
```
##### Activate Event Based Component
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-components/activate-event-based-component
Activates an event-based component for a single subscription.
To bill your subscribers on your Events data under the Events-Based Billing feature, the components must be activated for the subscriber.
For more information, see [Design Your Catalog](https://docs.maxio.com/hc/en-us/articles/24181036583053-Design-Your-Catalog?method=componenttypes).
Use this endpoint to activate an event-based component for a single subscription. Activating an event-based component causes billing for events when the subscription is renewed.
Note: it is possible to stream events for a subscription at any time, regardless of component activation status. The activation status only determines if the subscription should be billed for event-based component usage at renewal.
```http
POST /event_based_billing/subscriptions/{subscription_id}/components/{component_id}/activate.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Advanced Billing id of the subscription |
| `component_id` | `Number` | Template, Required | The Advanced Billing id of the component |
| `body` | [`Activate Event-Based Component`](https://developers.maxio.com/http/advanced-billing-api/models/structures/activate-event-based-component) | Body, Optional | - |
# Response Type
**200**: OK
`Void`
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/event_based_billing/subscriptions/222/components/222/activate.json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"price_point_id": 1,
"billing_schedule": {
"initial_billing_at": "2022-01-01"
},
"custom_price": {
"tax_included": false,
"pricing_scheme": "per_unit",
"interval": 30,
"interval_unit": "day",
"prices": [
{
"starting_quantity": 1,
"ending_quantity": null,
"unit_price": "5.0"
}
]
}
}'
```
##### Deactivate Event Based Component
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-components/deactivate-event-based-component
Deactivates an event-based component for a single subscription. Deactivating the event-based component causes Advanced Billing to ignore related events at subscription renewal.
```http
POST /event_based_billing/subscriptions/{subscription_id}/components/{component_id}/deactivate.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Advanced Billing id of the subscription |
| `component_id` | `Number` | Template, Required | The Advanced Billing id of the component |
# Response Type
**200**: OK
`Void`
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/event_based_billing/subscriptions/222/components/222/deactivate.json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
##### Record Event
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-components/record-event
Records a single event for Events-Based Billing.
Events-Based Billing is an evolved form of metered billing that is based on data-rich events streamed in real-time from your system to Advanced Billing.
These events can then be transformed, enriched, or analyzed to form the computed totals of usage charges billed to your customers.
This API allows you to stream events into the Advanced Billing data ingestion engine.
For more information, see [Design Your Catalog](https://docs.maxio.com/hc/en-us/articles/24181036583053-Design-Your-Catalog?method=componenttypes).
Note: this endpoint differs from the standard URL for this API in that `events` and your site subdomain are included in the path. For example:
```
https://events.chargify.com/my-site-subdomain/events/my-stream-api-handle
```
```http
POST /events/{api_handle}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `api_handle` | `String` | Template, Required | Identifies the Stream for which the event should be published. |
| `store_uid` | `String` | Query, Optional | If you've attached your own Keen project as an Advanced Billing event data-store, use this parameter to indicate the data-store. This applies to Legacy Metering sites only — it has no effect on Maxio Metering sites. |
| `body` | [`EBB Event`](https://developers.maxio.com/http/advanced-billing-api/models/structures/ebb-event) | Body, Optional | - |
# Server
`ebb`
# Response Type
**201**: Created
`Void`
# Example Usage
```bash
curl -X POST \
--url 'https://events.chargify.com/subdomain/events/api_handle6.json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"chargify": {
"subscription_id": 1,
"timestamp": "2020-02-27T17:45:50-05:00"
},
"messages": 150,
"country": "US",
"customer": {
"name": "John",
"lastName": "Doe",
"address": {
"street": "Maple Street",
"zip": 4888,
"state": "MA"
}
}
}'
```
##### Bulk Record Events
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-components/bulk-record-events
Records a collection of events.
Note: this endpoint differs from the standard URL for this API in that `events` and your site subdomain are included in the path.
A maximum of 1000 events can be published in a single request. A 422 will be returned if this limit is exceeded.
```http
POST /events/{api_handle}/bulk.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `api_handle` | `String` | Template, Required | Identifies the Stream for which the events should be published. |
| `store_uid` | `String` | Query, Optional | If you've attached your own Keen project as an Advanced Billing event data-store, use this parameter to indicate the data-store. This applies to Legacy Metering sites only — it has no effect on Maxio Metering sites. |
| `body` | [`array`](https://developers.maxio.com/http/advanced-billing-api/models/structures/ebb-event) | Body, Optional | - |
# Server
`ebb`
# Response Type
**201**: Created
`Void`
# Example Usage
```bash
curl -X POST \
--url 'https://events.chargify.com/subdomain/events/api_handle6/bulk.json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '[
{
"chargify": {
"subscription_id": 1,
"timestamp": "2020-02-27T17:45:50-05:00"
},
"messages": 150,
"country": "US",
"customer": {
"name": "John",
"lastName": "Doe",
"address": {
"street": "Maple Street",
"zip": 4888,
"state": "MA"
}
}
}
]'
```
##### List Subscription Components for Site
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-components/list-subscription-components-for-site
Lists components applied to each subscription.
```http
GET /subscriptions_components.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query `per_page=200`.
**Default**: `20`
**Constraints**: `<= 200` |
| `sort` | [`List Subscription Components Sort`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/list-subscription-components-sort) | Query, Optional | The attribute by which to sort. Use in query: `sort=updated_at`. |
| `direction` | [`Sorting Direction`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/sorting-direction) | Query, Optional | Controls the order in which results are returned. Use in query `direction=asc`. |
| `filter` | [`List Subscription Components for Site Filter`](https://developers.maxio.com/http/advanced-billing-api/models/structures/list-subscription-components-for-site-filter) | Query, Optional | Filter to use for List Subscription Components For Site operation |
| `date_field` | [`Subscription List Date Field`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/subscription-list-date-field) | Query, Optional | The type of filter you'd like to apply to your search. Use in query: `date_field=updated_at`. |
| `start_date` | `String` | Query, Optional | The start date (format YYYY-MM-DD) with which to filter the date_field. Returns components with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified. Use in query `start_date=2011-12-15`. |
| `start_datetime` | `String` | Query, Optional | The start date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns components with a timestamp at or after exact time provided in query. You can specify timezone in query - otherwise your site''s time zone will be used. If provided, this parameter will be used instead of start_date. Use in query `start_datetime=2022-07-01 09:00:05`. |
| `end_date` | `String` | Query, Optional | The end date (format YYYY-MM-DD) with which to filter the date_field. Returns components with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified. Use in query `end_date=2011-12-16`. |
| `end_datetime` | `String` | Query, Optional | The end date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns components with a timestamp at or before exact time provided in query. You can specify timezone in query - otherwise your site''s time zone will be used. If provided, this parameter will be used instead of end_date. Use in query `end_datetime=2022-07-01 09:00:05`. |
| `subscription_ids` | `array` | Query, Optional | Allows fetching components allocation with matching subscription id based on provided ids. Use in query `subscription_ids=1,2,3`.
**Constraints**: *Minimum Items*: `1`, *Maximum Items*: `200` |
| `price_point_ids` | [`Include Not Null`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/include-not-null) | Query, Optional | Allows fetching components allocation only if price point id is present. Use in query `price_point_ids=not_null`. |
| `product_family_ids` | `array` | Query, Optional | Allows fetching components allocation with matching product family id based on provided ids. Use in query `product_family_ids=1,2,3`. |
| `include` | [`List Subscription Components Include`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/list-subscription-components-include) | Query, Optional | Allows including additional data in the response. Use in query `include=subscription,historic_usages`. |
# Response Type
**200**: OK
[`List Subscription Components Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/list-subscription-components-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/subscriptions_components.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'page=1' \
-d 'per_page=50' \
-d 'sort=updated_at' \
-d 'filter[currencies]=EUR%2CUSD' \
-d 'date_field=updated_at' \
-d 'subscription_ids=1%2C2%2C3' \
-d 'price_point_ids=not_null' \
-d 'product_family_ids=1%2C2%2C3' \
-d 'include=subscription'
```
#### Subscription Groups
##### Signup with Subscription Group
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-groups/signup-with-subscription-group
Creates multiple subscriptions at once under the same customer and consolidates them into a subscription group.
You must provide one and only one of the `payer_id`/`payer_reference`/`payer_attributes` for the customer attached to the group.
You must provide one and only one of the `payment_profile_id`/`credit_card_attributes`/`bank_account_attributes` for the payment profile attached to the group.
Only one of the `subscriptions` can have `"primary": true` attribute set.
When passing a product to a subscription you can use either `product_id` or `product_handle` or `offer_id`. You can also use `custom_price` instead.
The subscription request examples below will be split into two sections.
The first section, "Subscription Customization", will focus on passing different information with a subscription, such as components, calendar billing, and custom fields. These examples will presume you are using a secure chargify_token generated by Maxio.js (formerly Chargify.js).
```http
POST /subscription_groups/signup.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `body` | [`Subscription Group Signup Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/subscription-group-signup-request) | Body, Optional | - |
# Response Type
**201**: Created
[`Subscription Group Signup Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/subscription-group-signup-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscription_groups/signup.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"subscription_group": {
"payment_profile_id": 123,
"payer_id": 123,
"subscriptions": [
{
"product_id": 11,
"primary": true
},
{
"product_id": 12
},
{
"product_id": 13
}
]
}
}'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Subscription Group Signup Error ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/subscription-group-signup-error-response) |
##### Create Subscription Group
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-groups/create-subscription-group
Creates a subscription group with given members.
```http
POST /subscription_groups.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `body` | [`Create Subscription Group Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/create-subscription-group-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Subscription Group Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/subscription-group-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscription_groups.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"subscription_group": {
"subscription_id": 1,
"member_ids": [
2,
3,
4
]
}
}'
```
# Example Response *(as JSON)*
```json
{
"subscription_group": {
"uid": "grp_952mvqcnk53wq",
"customer_id": 1,
"payment_profile": {
"id": 1,
"first_name": "t",
"last_name": "t",
"masked_card_number": "XXXX-XXXX-XXXX-1"
},
"payment_collection_method": "automatic",
"subscription_ids": [
1,
2
],
"created_at": "2021-01-21T05:47:38-05:00"
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Subscription Group Create Error ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/subscription-group-create-error-response) |
##### List Subscription Groups
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-groups/list-subscription-groups
Lists subscription groups for the site. The response is paginated and will return a `meta` key with pagination information.
#### Account Balance Information
Account balance information for the subscription groups is not returned by default. If this information is desired, the `include[]=account_balances` parameter must be provided with the request.
```http
GET /subscription_groups.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query `per_page=200`.
**Default**: `20`
**Constraints**: `<= 200` |
| `include` | [`array`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/subscription-groups-list-include) | Query, Optional | A list of additional information to include in the response. The following values are supported:
- `account_balances`: Account balance information for the subscription groups. Use in query: `include[]=account_balances` |
# Response Type
**200**: OK
[`List Subscription Groups Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/list-subscription-groups-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/subscription_groups.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'page=1' \
-d 'per_page=50' \
-d 'include[]=account_balances'
```
# Example Response *(as JSON)*
```json
{
"subscription_groups": [
{
"uid": "grp_952mvqcnk53wq",
"scheme": 1,
"customer_id": 88498000,
"payment_profile_id": 93063018,
"subscription_ids": [
42768907,
82370782
],
"primary_subscription_id": 69844395,
"next_assessment_at": "2021-05-05T16:00:21-04:00",
"state": "active",
"cancel_at_end_of_period": false,
"account_balances": {
"prepayments": {
"balance_in_cents": 0
},
"service_credits": {
"balance_in_cents": 0
},
"pending_discounts": {
"balance_in_cents": 0
}
}
}
],
"meta": {
"current_page": 1,
"total_count": 1
}
}
```
##### Read Subscription Group
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-groups/read-subscription-group
Returns subscription group details.
#### Current Billing Amount in Cents
Current billing amount for the subscription group is not returned by default. If this information is desired, the `include[]=current_billing_amount_in_cents` parameter must be provided with the request.
```http
GET /subscription_groups/{uid}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `uid` | `String` | Template, Required | The uid of the subscription group |
| `include` | [`array`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/subscription-group-include) | Query, Optional | Allows including additional data in the response. Use in query: `include[]=current_billing_amount_in_cents`. |
# Response Type
**200**: OK
[`Full Subscription Group Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/full-subscription-group-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/subscription_groups/uid0.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'include[]=current_billing_amount_in_cents'
```
# Example Response *(as JSON)*
```json
{
"uid": "grp_939ktzq8v4477",
"scheme": 1,
"customer_id": 400,
"payment_profile_id": 567,
"subscription_ids": [
101,
102,
103
],
"primary_subscription_id": 101,
"next_assessment_at": "2020-08-01T14:00:00-05:00",
"state": "active",
"cancel_at_end_of_period": false,
"current_billing_amount_in_cents": 11500,
"customer": {
"first_name": "Mark",
"last_name": "Smith",
"organization": "Acme Inc.",
"email": "smith@example.com",
"reference": "4c92223b-bc16-4d0d-87ff-b177a89a2655"
},
"account_balances": {
"prepayments": {
"balance_in_cents": 0
},
"service_credits": {
"balance_in_cents": 0
},
"open_invoices": {
"balance_in_cents": 4400
},
"pending_discounts": {
"balance_in_cents": 0
}
}
}
```
##### Update Subscription Group Members
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-groups/update-subscription-group-members
Updates subscription group members.
`"member_ids"` should contain an array of both subscription IDs to set as group members and subscription IDs already present in the groups. Not including them will result in removing them from the subscription group. To clean up members, just leave the array empty.
```http
PUT /subscription_groups/{uid}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `uid` | `String` | Template, Required | The uid of the subscription group |
| `body` | [`Update Subscription Group Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/update-subscription-group-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Subscription Group Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/subscription-group-response)
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/subscription_groups/uid0.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"subscription_group": {
"member_ids": [
1,
2,
3
]
}
}'
```
# Example Response *(as JSON)*
```json
{
"subscription_group": {
"customer_id": 1,
"payment_profile": {
"id": 1,
"first_name": "t",
"last_name": "t",
"masked_card_number": "XXXX-XXXX-XXXX-1"
},
"payment_collection_method": "automatic",
"subscription_ids": [
1
],
"created_at": "2021-01-21T05:47:38-05:00"
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Subscription Group Update Error ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/subscription-group-update-error-response) |
##### Delete Subscription Group
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-groups/delete-subscription-group
Deletes a subscription group.
Only groups without members can be deleted.
```http
DELETE /subscription_groups/{uid}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `uid` | `String` | Template, Required | The uid of the subscription group |
# Response Type
**200**: OK
[`Delete Subscription Group Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/delete-subscription-group-response)
# Example Usage
```bash
curl -X DELETE \
--url 'https://subdomain.chargify.com/subscription_groups/uid0.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"uid": "grp_99w5xp9y5xycy",
"deleted": true
}
```
# Errors
| HTTP Status Code | Error Description |
| --- | --- |
| 404 | Not Found |
##### Find Subscription Group
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-groups/find-subscription-group
Finds the subscription group associated with a subscription.
If the subscription is not in a group, this endpoint returns an error.
```http
GET /subscription_groups/lookup.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `String` | Query, Required | The Advanced Billing id of the subscription associated with the subscription group |
# Response Type
**200**: OK
[`Full Subscription Group Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/full-subscription-group-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/subscription_groups/lookup.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'subscription_id=subscription_id0'
```
# Example Response *(as JSON)*
```json
{
"uid": "grp_939ktzq8v4477",
"scheme": 1,
"customer_id": 400,
"payment_profile_id": 567,
"subscription_ids": [
101,
102,
103
],
"primary_subscription_id": 101,
"next_assessment_at": "2020-08-01T14:00:00-05:00",
"state": "active",
"cancel_at_end_of_period": false,
"customer": {
"first_name": "Mark",
"last_name": "Smith",
"organization": "Acme Inc.",
"email": "smith@example.com",
"reference": "4c92223b-bc16-4d0d-87ff-b177a89a2655"
},
"account_balances": {
"prepayments": {
"balance_in_cents": 0
},
"service_credits": {
"balance_in_cents": 0
},
"open_invoices": {
"balance_in_cents": 4400
},
"pending_discounts": {
"balance_in_cents": 0
}
}
}
```
# Errors
| HTTP Status Code | Error Description |
| --- | --- |
| 404 | Not Found |
##### Add Subscription to Group
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-groups/add-subscription-to-group
Adds an existing subscription to a subscription group. For sites making use of the [Relationship Billing](https://maxio.zendesk.com/hc/en-us/articles/24252287829645-Advanced-Billing-Invoices-Overview) and [Customer Hierarchy](https://maxio.zendesk.com/hc/en-us/articles/24252185211533-Customer-Hierarchies-WhoPays#customer-hierarchies) features, it is possible to add existing subscriptions to subscription groups.
Passing `group` parameters with a `target` containing a `type` and optional `id` is all that's needed. When the `target` parameter specifies a `"customer"` or `"subscription"` that is already part of a hierarchy, the subscription will become a member of the customer's subscription group. If the target customer or subscription is not part of a subscription group, a new group will be created and the subscription will become part of the group with the specified target customer set as the responsible payer for the group's subscriptions.
**Note:** In order to add an existing subscription to a subscription group, it must belong to either the same customer record as the target, or be within the same customer hierarchy.
Rather than specifying a customer, the `target` parameter could instead simply have a value of
* `"self"` which indicates the subscription will be paid for not by some other customer, but by the subscribing customer,
* `"parent"` which indicates the subscription will be paid for by the subscribing customer's parent within a customer hierarchy, or
* `"eldest"` which indicates the subscription will be paid for by the root-level customer in the subscribing customer's hierarchy.
To create a new subscription into a subscription group, reference the following:
[Create Subscription in a Subscription Group](https://developers.chargify.com/docs/api-docs/d571659cf0f24-create-subscription#subscription-in-a-subscription-group)
```http
POST /subscriptions/{subscription_id}/group.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `body` | [`Add Subscription to a Group`](https://developers.maxio.com/http/advanced-billing-api/models/structures/add-subscription-to-a-group) | Body, Optional | - |
# Response Type
**200**: OK
[`Subscription Group Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/subscription-group-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscriptions/222/group.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"group": {
"target": {
"type": "subscription",
"id": 32987
},
"billing": {
"accrue": true,
"align_date": true,
"prorate": true
}
}
}'
```
# Example Response *(as JSON)*
```json
{
"subscription_group": {
"customer_id": 130690,
"payment_profile": {
"id": 32055,
"first_name": "Marty",
"last_name": "McFly",
"masked_card_number": "XXXX-XXXX-XXXX-1111"
},
"subscription_ids": [
32988,
33060,
32986
],
"created_at": "2018-08-30T17:14:30-04:00"
}
}
```
##### Remove Subscription from Group
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-groups/remove-subscription-from-group
Removes an existing subscription from a subscription group. For sites making use of the [Relationship Billing](https://maxio.zendesk.com/hc/en-us/articles/24252287829645-Advanced-Billing-Invoices-Overview) and [Customer Hierarchy](https://maxio.zendesk.com/hc/en-us/articles/24252185211533-Customer-Hierarchies-WhoPays#customer-hierarchies) features, it is possible to remove an existing subscription from a subscription group.
```http
DELETE /subscriptions/{subscription_id}/group.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
# Response Type
**204**: No Content
`Void`
# Example Usage
```bash
curl -X DELETE \
--url 'https://subdomain.chargify.com/subscriptions/222/group.json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
#### Subscription Group Invoice Account
##### Create Subscription Group Prepayment
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-group-invoice-account/create-subscription-group-prepayment
Adds a prepayment for a subscription group. This endpoint requires an `amount`, `details`, `method`, and `memo`. On success, the prepayment will be added to the group's prepayment balance.
```http
POST /subscription_groups/{uid}/prepayments.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `uid` | `String` | Template, Required | The uid of the subscription group |
| `body` | [`Subscription Group Prepayment Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/subscription-group-prepayment-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Subscription Group Prepayment Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/subscription-group-prepayment-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscription_groups/uid0/prepayments.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"id": 6049554,
"amount_in_cents": 10000,
"ending_balance_in_cents": 5000,
"entry_type": "Debit",
"memo": "Debit from invoice account."
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### List Prepayments for Subscription Group
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-group-invoice-account/list-prepayments-for-subscription-group
Lists a subscription group's prepayments.
```http
GET /subscription_groups/{uid}/prepayments.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `uid` | `String` | Template, Required | The uid of the subscription group |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query `per_page=200`.
**Default**: `20`
**Constraints**: `<= 200` |
| `filter` | [`List Prepayments Filter`](https://developers.maxio.com/http/advanced-billing-api/models/structures/list-prepayments-filter) | Query, Optional | Filter to use for List Prepayments operations |
# Response Type
**200**: OK
[`List Subscription Group Prepayment Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/list-subscription-group-prepayment-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/subscription_groups/uid0/prepayments.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'page=1' \
-d 'per_page=50' \
-d 'filter[date_field]=created_at' \
-d 'filter[start_date]=2024-01-01' \
-d 'filter[end_date]=2024-01-31'
```
# Example Response *(as JSON)*
```json
{
"prepayments": [
{
"prepayment": {
"id": 142,
"subscription_group_uid": "grp_b4qhx3bvx72t8",
"amount_in_cents": 10000,
"remaining_amount_in_cents": 10000,
"details": "test",
"external": true,
"memo": "test",
"payment_type": "cash",
"created_at": "2023-06-21T04:37:02-04:00"
}
}
]
}
```
# Errors
| HTTP Status Code | Error Description |
| --- | --- |
| 404 | Not Found |
##### Issue Subscription Group Service Credit
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-group-invoice-account/issue-subscription-group-service-credit
Issues service credit for a subscription group. Credit will be added to the group in the amount specified in the request body. The credit will be applied to group member invoices as they are generated.
```http
POST /subscription_groups/{uid}/service_credits.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `uid` | `String` | Template, Required | The uid of the subscription group |
| `body` | [`Issue Service Credit Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/issue-service-credit-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Service Credit Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/service-credit-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscription_groups/uid0/service_credits.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"service_credit": {
"amount": 10.0,
"memo": "Credit the group account"
}
}'
```
# Example Response *(as JSON)*
```json
{
"service_credit": {
"id": 101,
"amount_in_cents": 1000,
"ending_balance_in_cents": 2000,
"entry_type": "Credit",
"memo": "Credit to group account"
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Deduct Subscription Group Service Credit
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-group-invoice-account/deduct-subscription-group-service-credit
Deducts service credit for a subscription group. Credit will be deducted from the group in the amount specified in the request body.
```http
POST /subscription_groups/{uid}/service_credit_deductions.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `uid` | `String` | Template, Required | The uid of the subscription group |
| `body` | [`Deduct Service Credit Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/deduct-service-credit-request) | Body, Optional | - |
# Response Type
**201**: Created
[`Service Credit`](https://developers.maxio.com/http/advanced-billing-api/models/structures/service-credit)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscription_groups/uid0/service_credit_deductions.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"deduction": {
"amount": 10.0,
"memo": "Deduct from group account"
}
}'
```
# Example Response *(as JSON)*
```json
{
"id": 100,
"amount_in_cents": 1000,
"ending_balance_in_cents": 0,
"entry_type": "Debit",
"memo": "Debit from group account"
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
#### Subscription Group Status
##### Cancel Subscriptions in Group
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-group-status/cancel-subscriptions-in-group
Cancels all subscriptions within the specified group immediately. The group is identified by the `uid` that is passed in the URL. To successfully cancel the group, the primary subscription must be on automatic billing. The group members must be on automatic billing or prepaid.
To cancel a subscription group while also charging for any unbilled usage on metered or prepaid components, the `charge_unbilled_usage=true` parameter must be included in the request.
```http
POST /subscription_groups/{uid}/cancel.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `uid` | `String` | Template, Required | The uid of the subscription group |
| `body` | [`Cancel Grouped Subscriptions Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/cancel-grouped-subscriptions-request) | Body, Optional | - |
# Response Type
**200**: OK
`Void`
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscription_groups/uid0/cancel.json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"charge_unbilled_usage": true
}'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Initiate Delayed Cancellation for Group
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-group-status/initiate-delayed-cancellation-for-group
Schedules all subscriptions within the specified group to be canceled at the end of their billing period. The group is identified by its uid passed in the URL.
All subscriptions in the group must be on automatic billing in order to successfully cancel them, and the group must not be in a "past_due" state.
```http
POST /subscription_groups/{uid}/delayed_cancel.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `uid` | `String` | Template, Required | The uid of the subscription group |
# Response Type
**200**: OK
`Void`
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscription_groups/uid0/delayed_cancel.json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Cancel Delayed Cancellation for Group
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-group-status/cancel-delayed-cancellation-for-group
Removes the delayed cancellation on a subscription group.
Removing the delayed cancellation on a subscription group will ensure that the subscriptions do not get canceled at the end of the period. The request will reset the `cancel_at_end_of_period` flag to false on each member in the group.
```http
DELETE /subscription_groups/{uid}/delayed_cancel.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `uid` | `String` | Template, Required | The uid of the subscription group |
# Response Type
**200**: OK
`Void`
# Example Usage
```bash
curl -X DELETE \
--url 'https://subdomain.chargify.com/subscription_groups/uid0/delayed_cancel.json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Reactivate Subscription Group
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-group-status/reactivate-subscription-group
Reactivates or resumes a cancelled subscription group. Upon reactivation, any canceled invoices created after the beginning of the primary subscription's billing period will be reopened and payment will be attempted on them. If the subscription group is being reactivated (as opposed to resumed), new charges will also be assessed for the new billing period.
Whether a subscription group is reactivated (a new billing period is created) or resumed (the current billing period is respected) will depend on the parameters that are sent with the request as well as the date of the request relative to the primary subscription's period.
## Reactivating within the current period
If a subscription group is cancelled and reactivated within the primary subscription's current period, we can choose to either start a new billing period or maintain the existing one. If we want to maintain the existing billing period, the `resume=true` option must be passed in request parameters.
An exception to the above are subscriptions that are on calendar billing. These subscriptions cannot be reactivated within the current period. If the `resume=true` option is not passed, the request will return an error.
The `resume_members` option is ignored in this case. All eligible group members will be automatically resumed.
## Reactivating beyond the current period
In this case, a subscription group can only be reactivated with a new billing period. If the `resume=true` option is passed it will be ignored.
Member subscriptions can have billing periods that are longer than the primary (e.g. a monthly primary with annual group members). If the primary subscription in a group cannot be reactivated within the current period, but other group members can be, passing `resume_members=true` will resume the existing billing period for eligible group members. The primary subscription will begin a new billing period.
For calendar billing subscriptions, the new billing period created will be a partial one, spanning from the date of reactivation to the next corresponding calendar renewal date.
## 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.
```http
POST /subscription_groups/{uid}/reactivate.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `uid` | `String` | Template, Required | The uid of the subscription group |
| `body` | [`Reactivate Subscription Group Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/reactivate-subscription-group-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Reactivate Subscription Group Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/reactivate-subscription-group-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscription_groups/uid0/reactivate.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"resume": true
}'
```
# Example Response *(as JSON)*
```json
{
"uid": "grp_93wgm89cbjkw6",
"scheme": 1,
"customer_id": 1,
"payment_profile_id": 1,
"subscription_ids": [
1,
2
],
"primary_subscription_id": 1,
"next_assessment_at": "2020-06-18T12:00:00-04:00",
"state": "active",
"cancel_at_end_of_period": false
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
#### Subscription Invoice Account
##### Read Account Balances
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-invoice-account/read-account-balances
Returns the `balance_in_cents` of the Subscription's Pending Discount, Service Credit, and Prepayment accounts, as well as the sum of the Subscription's open, payable invoices.
```http
GET /subscriptions/{subscription_id}/account_balances.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
# Response Type
**200**: OK
[`Account Balances`](https://developers.maxio.com/http/advanced-billing-api/models/structures/account-balances)
# Example Usage
```bash
curl -X GET \
--url 'https://subdomain.chargify.com/subscriptions/222/account_balances.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
##### Create Prepayment
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-invoice-account/create-prepayment
Creates a prepayment for a subscription.
In order to specify a prepayment made against a subscription, specify the `amount, memo, details, method`.
When the `method` specified is `"credit_card_on_file"`, the prepayment amount will be collected using the default credit card payment profile and applied to the prepayment account balance. This is especially useful for manual replenishment of prepaid subscriptions.
Note that passing `amount_in_cents` is now allowed.
## 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.
```http
POST /subscriptions/{subscription_id}/prepayments.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `body` | [`Create Prepayment Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/create-prepayment-request) | Body, Optional | - |
# Response Type
**201**: Created
[`Create Prepayment Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/create-prepayment-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscriptions/222/prepayments.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"prepayment": {
"amount": 100.0,
"details": "John Doe signup for $100",
"memo": "Signup for $100",
"method": "check"
}
}'
```
# Example Response *(as JSON)*
```json
{
"prepayment": {
"id": 1,
"subscription_id": 1,
"amount_in_cents": 10000,
"memo": "John Doe - Prepayment",
"created_at": "2020-07-31T05:52:32-04:00",
"starting_balance_in_cents": 0,
"ending_balance_in_cents": -10000
}
}
```
# Errors
| HTTP Status Code | Error Description |
| --- | --- |
| 422 | Unprocessable Entity (WebDAV) |
##### List Prepayments
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-invoice-account/list-prepayments
Lists a subscription's prepayments.
```http
GET /subscriptions/{subscription_id}/prepayments.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query `per_page=200`.
**Default**: `20`
**Constraints**: `<= 200` |
| `filter` | [`List Prepayments Filter`](https://developers.maxio.com/http/advanced-billing-api/models/structures/list-prepayments-filter) | Query, Optional | Filter to use for List Prepayments operations |
# Response Type
**200**: OK
[`Prepayments Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/prepayments-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/subscriptions/222/prepayments.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'page=1' \
-d 'per_page=50' \
-d 'filter[date_field]=created_at' \
-d 'filter[start_date]=2024-01-01' \
-d 'filter[end_date]=2024-01-31'
```
# Example Response *(as JSON)*
```json
{
"prepayments": [
{
"id": 17,
"subscription_id": 3558750,
"amount_in_cents": 2000,
"remaining_amount_in_cents": 1100,
"refunded_amount_in_cents": 0,
"external": true,
"memo": "test",
"details": "test details",
"payment_type": "cash",
"created_at": "2022-01-18T22:45:41+11:00"
}
]
}
```
# Errors
| HTTP Status Code | Error Description |
| --- | --- |
| 404 | Not Found |
##### Issue Service Credit
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-invoice-account/issue-service-credit
Adds a service credit to the subscription in the specified amount. The credit is subsequently applied to the next generated invoice.
```http
POST /subscriptions/{subscription_id}/service_credits.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `body` | [`Issue Service Credit Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/issue-service-credit-request) | Body, Optional | - |
# Response Type
**201**: Created
[`Service Credit`](https://developers.maxio.com/http/advanced-billing-api/models/structures/service-credit)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscriptions/222/service_credits.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"service_credit": {
"amount": "1"
}
}'
```
# Example Response *(as JSON)*
```json
{
"id": 101,
"amount_in_cents": 1000,
"ending_balance_in_cents": 2000,
"entry_type": "Credit",
"memo": "Credit to group account"
}
```
# Errors
| HTTP Status Code | Error Description |
| --- | --- |
| 422 | Unprocessable Entity (WebDAV) |
##### Deduct Service Credit
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-invoice-account/deduct-service-credit
Deducts a service credit from the subscription in the specified amount. The credit amount being deducted must be equal to or less than the current credit balance.
```http
POST /subscriptions/{subscription_id}/service_credit_deductions.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `body` | [`Deduct Service Credit Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/deduct-service-credit-request) | Body, Optional | - |
# Response Type
**201**: OK
`Void`
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscriptions/222/service_credit_deductions.json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"deduction": {
"amount": "1",
"memo": "Deduction"
}
}'
```
# Errors
| HTTP Status Code | Error Description |
| --- | --- |
| 422 | Unprocessable Entity (WebDAV) |
##### List Service Credits
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-invoice-account/list-service-credits
Lists a subscription's service credits.
```http
GET /subscriptions/{subscription_id}/service_credits/list.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query `per_page=200`.
**Default**: `20`
**Constraints**: `<= 200` |
| `direction` | [`Sorting Direction`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/sorting-direction) | Query, Optional | Controls the order in which results are returned. Use in query `direction=asc`. |
# Response Type
**200**: OK
[`List Service Credits Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/list-service-credits-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/subscriptions/222/service_credits/list.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'page=1' \
-d 'per_page=50'
```
# Example Response *(as JSON)*
```json
{
"service_credits": [
{
"id": 68,
"amount_in_cents": 2200,
"ending_balance_in_cents": 1100,
"entry_type": "Debit",
"memo": "Service credit memo",
"invoice_uid": "inv_brntdvmmqxc3j",
"remaining_balance_in_cents": 1100,
"created_at": "2025-04-01T09:54:49-04:00"
},
{
"id": 67,
"amount_in_cents": 3300,
"ending_balance_in_cents": 3300,
"entry_type": "Credit",
"memo": "Service credit memo",
"invoice_uid": null,
"remaining_balance_in_cents": 1100,
"created_at": "2025-03-05T16:06:08-05:00"
}
]
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | |
| 422 | Unprocessable Entity | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Refund Prepayment
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-invoice-account/refund-prepayment
Refunds a prepayment applied to a subscription, either fully or partially. The `prepayment_id` will be the account transaction ID of the original payment. The prepayment must have some amount remaining in order to be refunded.
The amount may be passed either as a decimal, with `amount`, or an integer in cents, with `amount_in_cents`.
```http
POST /subscriptions/{subscription_id}/prepayments/{prepayment_id}/refunds.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `prepayment_id` | `Long` | Template, Required | id of prepayment |
| `body` | [`Refund Prepayment Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/refund-prepayment-request) | Body, Optional | - |
# Response Type
**201**: Created
[`Prepayment Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/prepayment-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscriptions/222/prepayments/228/refunds.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 400 | Bad Request | [`Refund Prepayment Base Errors ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/refund-prepayment-base-errors-response) |
| 404 | Not Found | |
| 422 | Unprocessable Entity | |
#### Subscription Notes
##### Create Subscription Note
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-notes/create-subscription-note
Creates a note for a subscription.
Notes allow you to record information about a particular Subscription in a free text format.
If you have structured data such as birth date, color, etc., consider using [Metadata](https://developers.maxio.com/http/advanced-billing-api/api-endpoints/custom-fields/create-metadata) instead.
For more information, see [Adding Notes](https://docs.maxio.com/hc/en-us/articles/24251654953997-Understanding-the-Subscription-Summary-Page#billing-portal-status:~:text=documentation%20for%20more.-,Adding%20Notes,-Notes%20are%20optional) in the product documentation.
```http
POST /subscriptions/{subscription_id}/notes.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `body` | [`Update Subscription Note Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/update-subscription-note-request) | Body, Optional | Updatable fields for Subscription Note |
# Response Type
**200**: OK
[`Subscription Note Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/subscription-note-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscriptions/222/notes.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"note": {
"body": "New test note.",
"sticky": true
}
}'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### List Subscription Notes
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-notes/list-subscription-notes
Retrieves a list of notes associated with a subscription. The response will be an array of Notes.
```http
GET /subscriptions/{subscription_id}/notes.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query `per_page=200`.
**Default**: `20`
**Constraints**: `<= 200` |
# Response Type
**200**: OK
[`array`](https://developers.maxio.com/http/advanced-billing-api/models/structures/subscription-note-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/subscriptions/222/notes.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
-d 'page=1' \
-d 'per_page=50'
```
# Example Response *(as JSON)*
```json
[
{
"note": {
"body": "Test note.",
"created_at": "2015-06-15T13:26:47-04:00",
"id": 5,
"sticky": false,
"subscription_id": 100046,
"updated_at": "2015-06-15T13:28:12-04:00"
}
},
{
"note": {
"body": "Another test note.",
"created_at": "2015-06-15T12:04:46-04:00",
"id": 4,
"sticky": false,
"subscription_id": 100046,
"updated_at": "2015-06-15T13:26:33-04:00"
}
}
]
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Read Subscription Note
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-notes/read-subscription-note
Retrieves a specific note attached to a subscription.
```http
GET /subscriptions/{subscription_id}/notes/{note_id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `note_id` | `Number` | Template, Required | The Advanced Billing id of the note |
# Response Type
**200**: OK
[`Subscription Note Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/subscription-note-response)
# Example Usage
```bash
curl -X GET \
--url 'https://subdomain.chargify.com/subscriptions/222/notes/66.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"note": {
"body": "Test note.",
"created_at": "2015-06-15T13:26:47-04:00",
"id": 5,
"sticky": false,
"subscription_id": 100046,
"updated_at": "2015-06-15T13:28:12-04:00"
}
}
```
##### Update Subscription Note
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-notes/update-subscription-note
Updates a note for a subscription.
```http
PUT /subscriptions/{subscription_id}/notes/{note_id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `note_id` | `Number` | Template, Required | The Advanced Billing id of the note |
| `body` | [`Update Subscription Note Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/update-subscription-note-request) | Body, Optional | Updatable fields for Subscription Note |
# Response Type
**200**: OK
[`Subscription Note Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/subscription-note-response)
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/subscriptions/222/notes/66.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"note": {
"body": "Modified test note.",
"sticky": true
}
}'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Delete Subscription Note
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-notes/delete-subscription-note
Deletes a note for a Subscription.
```http
DELETE /subscriptions/{subscription_id}/notes/{note_id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `note_id` | `Number` | Template, Required | The Advanced Billing id of the note |
# Response Type
**200**: OK
`Void`
# Example Usage
```bash
curl -X DELETE \
--url 'https://subdomain.chargify.com/subscriptions/222/notes/66.json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
#### Subscription Products
##### Migrate Subscription Product
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-products/migrate-subscription-product
Migrates a subscription to a different product.
To create a migration, you must pass the `product_id` or `product_handle` in the object when you send a POST request. You can also pass either a `product_price_point_id` or `product_price_point_handle` to choose which price point the subscription is moved to. If no price point identifier is passed, the subscription is moved to the product's default price point. The response is the updated subscription.
## Valid Subscriptions
Subscriptions should be in the `active` or `trialing` state to be migrated.
(For backwards compatibility reasons, it is possible to migrate a subscription that is in the `trial_ended` state via the API, however this is not recommended. Since `trial_ended` is an end-of-life state, the subscription should be canceled, the product changed, and then the subscription can be reactivated.)
For more information, see [Product Changes and Migrations](https://docs.maxio.com/hc/en-us/articles/24252069837581-Product-Changes-and-Migrations).
## Failed Migrations
Important note: One of the most common ways that a migration can fail is when the attempt is made to migrate a subscription to its current product.
## 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.
```http
POST /subscriptions/{subscription_id}/migrations.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `body` | [`Subscription Product Migration Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/subscription-product-migration-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Subscription Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/subscription-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscriptions/222/migrations.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"migration": {
"product_id": 3801242,
"include_trial": false,
"include_initial_charge": false,
"include_coupons": true,
"preserve_period": true
}
}'
```
# Example Response *(as JSON)*
```json
{
"subscription": {
"id": 15054201,
"state": "trialing",
"trial_started_at": "2016-11-03T13:43:36-04:00",
"trial_ended_at": "2016-11-10T12:43:36-05:00",
"activated_at": "2016-11-02T10:20:57-04:00",
"created_at": "2016-11-02T10:20:55-04:00",
"updated_at": "2016-11-03T13:43:36-04:00",
"expires_at": null,
"balance_in_cents": -13989,
"current_period_ends_at": "2016-11-10T12:43:36-05:00",
"next_assessment_at": "2016-11-10T12:43:36-05:00",
"canceled_at": null,
"cancellation_message": null,
"next_product_id": null,
"cancel_at_end_of_period": false,
"payment_collection_method": "automatic",
"snap_day": null,
"cancellation_method": null,
"current_period_started_at": "2016-11-03T13:43:35-04:00",
"previous_state": "active",
"signup_payment_id": 160680121,
"signup_revenue": "0.00",
"delayed_cancel_at": null,
"coupon_code": null,
"total_revenue_in_cents": 14000,
"product_price_in_cents": 1000,
"product_version_number": 6,
"payment_type": "credit_card",
"referral_code": "ghnhvy",
"coupon_use_count": null,
"coupon_uses_allowed": null,
"customer": {
"id": 14543792,
"first_name": "Frankie",
"last_name": "Test",
"organization": null,
"email": "testfrankie111@test.com",
"created_at": "2016-11-02T10:20:55-04:00",
"updated_at": "2016-11-02T10:20:58-04:00",
"reference": null,
"address": null,
"address_2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone": "5555551212",
"portal_invite_last_sent_at": "2016-11-02T10:20:58-04:00",
"portal_invite_last_accepted_at": null,
"verified": false,
"portal_customer_created_at": "2016-11-02T10:20:58-04:00",
"cc_emails": null
},
"product": {
"id": 3861800,
"name": "Trial Product",
"handle": "trial-product",
"description": "Trial period with payment expected at end of trial.",
"accounting_code": "",
"request_credit_card": true,
"expiration_interval": null,
"expiration_interval_unit": "never",
"created_at": "2016-07-08T09:53:55-04:00",
"updated_at": "2016-09-05T13:00:36-04:00",
"price_in_cents": 1000,
"interval": 1,
"interval_unit": "month",
"initial_charge_in_cents": null,
"trial_price_in_cents": 0,
"trial_interval": 7,
"trial_interval_unit": "day",
"archived_at": null,
"require_credit_card": true,
"return_params": "",
"taxable": false,
"update_return_url": "",
"initial_charge_after_trial": false,
"version_number": 6,
"update_return_params": "",
"product_family": {
"id": 527890,
"name": "Acme Projects",
"description": "",
"handle": "billing-plans",
"accounting_code": null
},
"public_signup_pages": [
{
"id": 294791,
"return_url": "",
"return_params": "",
"url": "https://general-goods.chargify.com/subscribe/xv52yrcc3byx/trial-product"
}
]
},
"credit_card": {
"id": 10088716,
"first_name": "F",
"last_name": "NB",
"masked_card_number": "XXXX-XXXX-XXXX-1",
"card_type": "bogus",
"expiration_month": 1,
"expiration_year": 2017,
"customer_id": 14543792,
"current_vault": "bogus",
"vault_token": "1",
"billing_address": "123 Montana Way",
"billing_city": "Billings",
"billing_state": "MT",
"billing_zip": "59101",
"billing_country": "US",
"customer_vault_token": null,
"billing_address_2": "Apt. 10",
"payment_type": "credit_card"
}
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Preview Subscription Product Migration
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-products/preview-subscription-product-migration
Previews the charges resulting from migrating a subscription to a different product.
## Previewing a future date
It is also possible to preview the migration for a date in the future, as long as it's still within the subscription's current billing period, by passing a `proration_date` along with the request (e.g., `"proration_date": "2020-12-18T18:25:43.511Z"`).
This will calculate the prorated adjustment, charge, payment and credit applied values assuming the migration is done at that date in the future as opposed to right now.
```http
POST /subscriptions/{subscription_id}/migrations/preview.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `body` | [`Subscription Migration Preview Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/subscription-migration-preview-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Subscription Migration Preview Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/subscription-migration-preview-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscriptions/222/migrations/preview.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"migration": {
"include_trial": false,
"include_initial_charge": false,
"include_coupons": true,
"preserve_period": false
}
}'
```
# Example Response *(as JSON)*
```json
{
"migration": {
"prorated_adjustment_in_cents": 0,
"charge_in_cents": 5000,
"payment_due_in_cents": 0,
"credit_applied_in_cents": 0
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
#### Subscription Renewals
##### Create Scheduled Renewal Configuration
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-renewals/create-scheduled-renewal-configuration
Creates a scheduled renewal configuration for a subscription. The scheduled renewal is based on the subscription’s current product and component setup.
```http
POST /subscriptions/{subscription_id}/scheduled_renewals.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `body` | [`Scheduled Renewal Configuration Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/scheduled-renewal-configuration-request) | Body, Optional | - |
# Response Type
**201**: Created
[`Scheduled Renewal Configuration Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/scheduled-renewal-configuration-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscriptions/222/scheduled_renewals.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"renewal_configuration": {
"starts_at": "2024-12-01T00:00:00Z",
"ends_at": "2025-12-01T00:00:00Z",
"lock_in_at": "2024-11-15T00:00:00Z",
"contract_id": 222
}
}'
```
# Example Response *(as JSON)*
```json
{
"scheduled_renewal_configuration": {
"id": 123,
"site_id": 456,
"subscription_id": 12345,
"starts_at": "2024-12-01T00:00:00Z",
"ends_at": "2025-12-01T00:00:00Z",
"lock_in_at": "2024-11-15T00:00:00Z",
"created_at": "2024-09-01T12:00:00Z",
"status": "scheduled",
"scheduled_renewal_configuration_items": [
{
"id": 789,
"subscription_id": 12345,
"subscription_renewal_configuration_id": 123,
"item_id": 4,
"item_type": "Product",
"item_subclass": "Product",
"price_point_id": 7,
"price_point_type": "ProductPricePoint",
"quantity": 1,
"decimal_quantity": "1.0",
"created_at": "2024-09-01T12:00:00Z"
}
],
"contract": {
"id": 107,
"maxio_id": "maxio-id",
"number": null,
"register": {
"id": 12,
"maxio_id": "maxio_id-id",
"name": "Register",
"currency_code": "USD"
}
}
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### List Scheduled Renewal Configurations
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-renewals/list-scheduled-renewal-configurations
Lists scheduled renewal configurations for the subscription and permits an optional status query filter.
```http
GET /subscriptions/{subscription_id}/scheduled_renewals.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `status` | [`Status`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/status) | Query, Optional | (Optional) Status filter for scheduled renewal configurations. |
# Response Type
**200**: OK
[`Scheduled Renewal Configurations Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/scheduled-renewal-configurations-response)
# Example Usage
```bash
curl -X GET -G \
--url 'https://subdomain.chargify.com/subscriptions/222/scheduled_renewals.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"scheduled_renewal_configurations": [
{
"id": 123,
"site_id": 456,
"subscription_id": 12345,
"starts_at": "2024-12-01T00:00:00Z",
"ends_at": "2025-12-01T00:00:00Z",
"lock_in_at": "2024-11-15T00:00:00Z",
"created_at": "2024-09-01T12:00:00Z",
"status": "scheduled",
"scheduled_renewal_configuration_items": [
{
"id": 789,
"subscription_id": 12345,
"subscription_renewal_configuration_id": 123,
"item_id": 4,
"item_type": "Product",
"item_subclass": "Product",
"price_point_id": 7,
"price_point_type": "ProductPricePoint",
"quantity": 1,
"decimal_quantity": "1.0",
"created_at": "2024-09-01T12:00:00Z"
}
],
"contract": {
"id": 107,
"maxio_id": "maxio-id",
"number": null,
"register": {
"id": 12,
"maxio_id": "maxio-id",
"name": "Register",
"currency_code": "USD"
}
}
}
]
}
```
##### Read Scheduled Renewal Configuration
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-renewals/read-scheduled-renewal-configuration
Retrieves the configuration settings for the scheduled renewal.
```http
GET /subscriptions/{subscription_id}/scheduled_renewals/{id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `id` | `Number` | Template, Required | The renewal id. |
# Response Type
**200**: OK
[`Scheduled Renewal Configuration Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/scheduled-renewal-configuration-response)
# Example Usage
```bash
curl -X GET \
--url 'https://subdomain.chargify.com/subscriptions/222/scheduled_renewals/112.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"scheduled_renewal_configuration": {
"id": 123,
"site_id": 456,
"subscription_id": 12345,
"starts_at": "2024-12-01T00:00:00Z",
"ends_at": "2025-12-01T00:00:00Z",
"lock_in_at": "2024-11-15T00:00:00Z",
"created_at": "2024-09-01T12:00:00Z",
"status": "scheduled",
"scheduled_renewal_configuration_items": [
{
"id": 789,
"subscription_id": 12345,
"subscription_renewal_configuration_id": 123,
"item_id": 4,
"item_type": "Product",
"item_subclass": "Product",
"price_point_id": 7,
"price_point_type": "ProductPricePoint",
"quantity": 1,
"decimal_quantity": "1.0",
"created_at": "2024-09-01T12:00:00Z"
}
],
"contract": {
"id": 107,
"maxio_id": "maxio-id",
"number": null,
"register": {
"id": 12,
"maxio_id": "maxio-id",
"name": "Register",
"currency_code": "USD"
}
}
}
}
```
##### Update Scheduled Renewal Configuration
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-renewals/update-scheduled-renewal-configuration
Updates an existing configuration.
```http
PUT /subscriptions/{subscription_id}/scheduled_renewals/{id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `id` | `Number` | Template, Required | The renewal id. |
| `body` | [`Scheduled Renewal Configuration Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/scheduled-renewal-configuration-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Scheduled Renewal Configuration Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/scheduled-renewal-configuration-response)
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/subscriptions/222/scheduled_renewals/112.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"renewal_configuration": {
"starts_at": "2025-12-01T00:00:00Z",
"ends_at": "2026-12-01T00:00:00Z",
"lock_in_at": "2025-11-15T00:00:00Z"
}
}'
```
# Example Response *(as JSON)*
```json
{
"scheduled_renewal_configuration": {
"id": 123,
"site_id": 456,
"subscription_id": 12345,
"starts_at": "2025-12-01T00:00:00Z",
"ends_at": "2026-12-01T00:00:00Z",
"lock_in_at": "2025-11-15T00:00:00Z",
"created_at": "2025-09-01T12:00:00Z",
"status": "scheduled",
"scheduled_renewal_configuration_items": [
{
"id": 789,
"subscription_id": 12345,
"subscription_renewal_configuration_id": 123,
"item_id": 4,
"item_type": "Product",
"item_subclass": "Product",
"price_point_id": 7,
"price_point_type": "ProductPricePoint",
"quantity": 1,
"decimal_quantity": "1.0",
"created_at": "2025-09-01T12:00:00Z"
}
],
"contract": {
"id": 107,
"maxio_id": "maxio-id",
"number": null,
"register": {
"id": 12,
"maxio_id": "maxio-id",
"name": "Register",
"currency_code": "USD"
}
}
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Schedule Scheduled Renewal Lock In
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-renewals/schedule-scheduled-renewal-lock-in
Schedules a future lock-in date for the renewal.
```http
PUT /subscriptions/{subscription_id}/scheduled_renewals/{id}/schedule_lock_in.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `id` | `Number` | Template, Required | The renewal id. |
| `body` | [`Scheduled Renewal Lock in Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/scheduled-renewal-lock-in-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Scheduled Renewal Configuration Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/scheduled-renewal-configuration-response)
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/subscriptions/222/scheduled_renewals/112/schedule_lock_in.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"lock_in_at": "2025-11-15"
}'
```
# Example Response *(as JSON)*
```json
{
"scheduled_renewal_configuration": {
"id": 123,
"site_id": 456,
"subscription_id": 12345,
"starts_at": "2025-12-01T00:00:00Z",
"ends_at": "2026-12-01T00:00:00Z",
"lock_in_at": "2025-11-15T00:00:00Z",
"created_at": "2025-09-01T12:00:00Z",
"status": "scheduled",
"scheduled_renewal_configuration_items": [
{
"id": 789,
"subscription_id": 12345,
"subscription_renewal_configuration_id": 123,
"item_id": 4,
"item_type": "Product",
"item_subclass": "Product",
"price_point_id": 7,
"price_point_type": "ProductPricePoint",
"quantity": 1,
"decimal_quantity": "1.0",
"created_at": "2025-09-01T12:00:00Z"
}
],
"contract": {
"id": 107,
"maxio_id": "maxio-id",
"number": null,
"register": {
"id": 12,
"maxio_id": "maxio-id",
"name": "Register",
"currency_code": "USD"
}
}
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Lock in Scheduled Renewal Immediately
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-renewals/lock-in-scheduled-renewal-immediately
Locks in the renewal immediately.
```http
PUT /subscriptions/{subscription_id}/scheduled_renewals/{id}/immediate_lock_in.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `id` | `Number` | Template, Required | The renewal id. |
# Response Type
**200**: OK
[`Scheduled Renewal Configuration Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/scheduled-renewal-configuration-response)
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/subscriptions/222/scheduled_renewals/112/immediate_lock_in.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"scheduled_renewal_configuration": {
"id": 987,
"site_id": 321,
"subscription_id": 12345,
"starts_at": "2025-12-01T00:00:00Z",
"ends_at": "2026-12-01T00:00:00Z",
"lock_in_at": "2025-11-15T00:00:00Z",
"created_at": "2025-09-01T12:00:00Z",
"status": "scheduled",
"scheduled_renewal_configuration_items": [
{
"id": 555,
"subscription_id": 12345,
"subscription_renewal_configuration_id": 987,
"item_id": 42,
"item_type": "Product",
"price_point_id": 73,
"price_point_type": "ProductPricePoint",
"quantity": 1,
"decimal_quantity": "1.0",
"created_at": "2025-09-01T12:00:00Z"
}
],
"contract": {
"id": 222,
"maxio_id": "maxio-id",
"number": null,
"register": {
"id": 12,
"maxio_id": "maxio-id",
"name": "Register",
"currency_code": "USD"
}
}
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Unpublish Scheduled Renewal Configuration
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-renewals/unpublish-scheduled-renewal-configuration
Restores a scheduled renewal configuration to an editable state.
```http
PUT /subscriptions/{subscription_id}/scheduled_renewals/{id}/unpublish.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `id` | `Number` | Template, Required | The renewal id. |
# Response Type
**200**: OK
[`Scheduled Renewal Configuration Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/scheduled-renewal-configuration-response)
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/subscriptions/222/scheduled_renewals/112/unpublish.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"scheduled_renewal_configuration": {
"id": 987,
"site_id": 321,
"subscription_id": 12345,
"starts_at": "2025-12-01T00:00:00Z",
"ends_at": "2026-12-01T00:00:00Z",
"lock_in_at": "2025-11-15T00:00:00Z",
"created_at": "2025-09-01T12:00:00Z",
"status": "draft",
"scheduled_renewal_configuration_items": [
{
"id": 555,
"subscription_id": 12345,
"subscription_renewal_configuration_id": 987,
"item_id": 42,
"item_type": "Product",
"price_point_id": 73,
"price_point_type": "ProductPricePoint",
"quantity": 1,
"decimal_quantity": "1.0",
"created_at": "2025-09-01T12:00:00Z"
}
],
"contract": {
"id": 222
}
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Cancel Scheduled Renewal Configuration
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-renewals/cancel-scheduled-renewal-configuration
Cancels a scheduled renewal configuration.
```http
PUT /subscriptions/{subscription_id}/scheduled_renewals/{id}/cancel.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `id` | `Number` | Template, Required | The renewal id. |
# Response Type
**200**: OK
[`Scheduled Renewal Configuration Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/scheduled-renewal-configuration-response)
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/subscriptions/222/scheduled_renewals/112/cancel.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"scheduled_renewal_configuration": {
"id": 987,
"site_id": 321,
"subscription_id": 12345,
"starts_at": "2025-12-01T00:00:00Z",
"ends_at": "2026-12-01T00:00:00Z",
"lock_in_at": "2025-11-15T00:00:00Z",
"created_at": "2025-09-01T12:00:00Z",
"status": "canceled",
"scheduled_renewal_configuration_items": [
{
"id": 555,
"subscription_id": 12345,
"subscription_renewal_configuration_id": 987,
"item_id": 42,
"item_type": "Product",
"price_point_id": 73,
"price_point_type": "ProductPricePoint",
"quantity": 1,
"decimal_quantity": "1.0",
"created_at": "2025-09-01T12:00:00Z"
}
],
"contract": {
"id": 222
}
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Create Scheduled Renewal Configuration Item
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-renewals/create-scheduled-renewal-configuration-item
Adds product and component line items to the scheduled renewal.
If your site has list vs sales pricing enabled, accepts renewal_configuration_item.custom_price.list_price_point_id, validates and persists it; omitted value follows existing/default behavior; with list vs sales pricing disabled, parameter is ignored (no validation/behavioral impact). This functionality is supported in the API, but is not currently supported in SDKs.
```http
POST /subscriptions/{subscription_id}/scheduled_renewals/{scheduled_renewals_configuration_id}/configuration_items.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `scheduled_renewals_configuration_id` | `Number` | Template, Required | The scheduled renewal configuration id. |
| `body` | [`Scheduled Renewal Configuration Item Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/scheduled-renewal-configuration-item-request) | Body, Optional | - |
# Response Type
**201**: Created
[`Scheduled Renewal Configuration Item Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/scheduled-renewal-configuration-item-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscriptions/222/scheduled_renewals/250/configuration_items.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"renewal_configuration_item": {
"item_type": "Component",
"item_id": 57,
"quantity": 1,
"custom_price": {
"pricing_scheme": "stairstep",
"prices": [
{
"starting_quantity": 1,
"ending_quantity": null,
"unit_price": 5.0
}
]
}
}
}'
```
# Example Response *(as JSON)*
```json
{
"scheduled_renewal_configuration_item": {
"id": 555,
"subscription_id": 12345,
"subscription_renewal_configuration_id": 987,
"item_id": 42,
"item_type": "Product",
"item_subclass": "SubscriptionProduct",
"price_point_id": 73,
"price_point_type": "ProductPricePoint",
"quantity": 1,
"decimal_quantity": "1.0",
"created_at": "2025-09-01T12:00:00Z"
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Update Scheduled Renewal Configuration Item
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-renewals/update-scheduled-renewal-configuration-item
Updates an existing configuration item’s pricing and quantity.
If you site has list vs sales pricing enabled, accepts renewal_configuration_item.custom_price.list_price_point_id, validates and persists it; omitted value follows existing/default behavior; with list vs sales pricing disabled, parameter is ignored (no validation/behavioral impact). This functionality is supported in the API, but is not currently supported in SDKs.
```http
PUT /subscriptions/{subscription_id}/scheduled_renewals/{scheduled_renewals_configuration_id}/configuration_items/{id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `scheduled_renewals_configuration_id` | `Number` | Template, Required | The scheduled renewal configuration id. |
| `id` | `Number` | Template, Required | The scheduled renewal configuration item id. |
| `body` | [`Scheduled Renewal Update Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/scheduled-renewal-update-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Scheduled Renewal Configuration Item Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/scheduled-renewal-configuration-item-response)
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/subscriptions/222/scheduled_renewals/250/configuration_items/112.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"renewal_configuration_item": {
"item_type": "Component",
"item_id": 57,
"quantity": 2,
"custom_price": {
"pricing_scheme": "stairstep",
"prices": [
{
"starting_quantity": 1,
"ending_quantity": null,
"unit_price": 5.0
}
]
}
}
}'
```
# Example Response *(as JSON)*
```json
{
"scheduled_renewal_configuration_item": {
"id": 555,
"subscription_id": 12345,
"subscription_renewal_configuration_id": 987,
"item_id": 42,
"item_type": "Component",
"item_subclass": "SubscriptionComponent",
"price_point_id": 73,
"price_point_type": "ComponentPricePoint",
"quantity": 3,
"decimal_quantity": "3.0",
"created_at": "2025-09-01T12:00:00Z"
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Delete Scheduled Renewal Configuration Item
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-renewals/delete-scheduled-renewal-configuration-item
Removes an item from the pending renewal configuration.
```http
DELETE /subscriptions/{subscription_id}/scheduled_renewals/{scheduled_renewals_configuration_id}/configuration_items/{id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `scheduled_renewals_configuration_id` | `Number` | Template, Required | The scheduled renewal configuration id. |
| `id` | `Number` | Template, Required | The scheduled renewal configuration item id. |
# Response Type
**204**: No Content
`Void`
# Example Usage
```bash
curl -X DELETE \
--url 'https://subdomain.chargify.com/subscriptions/222/scheduled_renewals/250/configuration_items/112.json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
#### Subscription Status
##### Retry Subscription
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-status/retry-subscription
Retries collecting the balance due on a past-due subscription without waiting for the next scheduled attempt.
## 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.
```http
PUT /subscriptions/{subscription_id}/retry.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
# Response Type
**200**: OK
[`Subscription Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/subscription-response)
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/subscriptions/222/retry.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"subscription": {
"id": 46330,
"state": "active",
"trial_started_at": null,
"trial_ended_at": null,
"activated_at": "2018-10-22T13:10:46-06:00",
"created_at": "2018-10-22T13:10:46-06:00",
"updated_at": "2021-06-10T09:23:43-06:00",
"expires_at": null,
"balance_in_cents": 18600,
"current_period_ends_at": "2021-06-22T13:10:46-06:00",
"next_assessment_at": "2021-06-22T13:10:46-06:00",
"canceled_at": null,
"cancellation_message": null,
"next_product_id": null,
"cancel_at_end_of_period": null,
"payment_collection_method": "automatic",
"snap_day": null,
"cancellation_method": null,
"product_price_point_id": 3464,
"next_product_price_point_id": null,
"receives_invoice_emails": null,
"net_terms": null,
"locale": null,
"currency": "USD",
"reference": null,
"scheduled_cancellation_at": null,
"current_period_started_at": "2021-05-22T13:10:46-06:00",
"previous_state": "past_due",
"signup_payment_id": 651268,
"signup_revenue": "6.00",
"delayed_cancel_at": null,
"coupon_code": null,
"total_revenue_in_cents": 600,
"product_price_in_cents": 600,
"product_version_number": 501,
"payment_type": null,
"referral_code": "rzqvrx",
"coupon_use_count": null,
"coupon_uses_allowed": null,
"reason_code": null,
"automatically_resume_at": null,
"offer_id": null,
"credit_balance_in_cents": 0,
"prepayment_balance_in_cents": 0,
"payer_id": 142365,
"stored_credential_transaction_id": null,
"next_product_handle": null,
"on_hold_at": null,
"prepaid_dunning": false,
"customer": {
"id": 142365,
"first_name": "Lavern",
"last_name": "Fahey",
"organization": null,
"email": "millie2@example.com",
"created_at": "2018-10-22T13:10:46-06:00",
"updated_at": "2018-10-22T13:10:46-06:00",
"reference": null,
"address": null,
"address_2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone": null,
"portal_invite_last_sent_at": null,
"portal_invite_last_accepted_at": null,
"verified": false,
"portal_customer_created_at": "2018-10-22T13:10:46-06:00",
"vat_number": null,
"cc_emails": "john@example.com, sue@example.com",
"tax_exempt": false,
"parent_id": null,
"locale": null
},
"product": {
"id": 8080,
"name": "Pro Versions",
"handle": null,
"description": "",
"accounting_code": "",
"request_credit_card": true,
"expiration_interval": null,
"expiration_interval_unit": "month",
"created_at": "2019-02-15T10:15:00-07:00",
"updated_at": "2019-02-15T10:30:34-07:00",
"price_in_cents": 600,
"interval": 1,
"interval_unit": "month",
"initial_charge_in_cents": null,
"trial_price_in_cents": null,
"trial_interval": null,
"trial_interval_unit": "month",
"archived_at": null,
"require_credit_card": true,
"return_params": "",
"require_shipping_address": false,
"request_billing_address": false,
"require_billing_address": false,
"taxable": false,
"update_return_url": "",
"tax_code": "",
"initial_charge_after_trial": false,
"default_product_price_point_id": 3464,
"version_number": 501,
"update_return_params": "",
"product_price_point_id": 3464,
"product_price_point_name": "Default",
"product_price_point_handle": "uuid:5305c3f0-1375-0137-5619-065dfbfdc636",
"product_family": {
"id": 37,
"name": "Acme Projects",
"description": null,
"handle": "acme-projects",
"accounting_code": null,
"created_at": "2013-02-20T15:05:51-07:00",
"updated_at": "2013-02-20T15:05:51-07:00"
},
"public_signup_pages": [
{
"id": 1540,
"return_url": null,
"return_params": "",
"url": "https://acme-test.staging-chargifypay.com/subscribe/2f6y53rrqgsf"
}
]
}
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Cancel Subscription
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-status/cancel-subscription
Cancels the Subscription. The Delete method sets the Subscription state to `canceled`.
To cancel the subscription immediately, omit any schedule parameters from the request. To use the schedule options, the Schedule Subscription Cancellation feature must be enabled on your site.
```http
DELETE /subscriptions/{subscription_id}.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `body` | [`Cancellation Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/cancellation-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Subscription Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/subscription-response)
# Example Usage
```bash
curl -X DELETE \
--url 'https://subdomain.chargify.com/subscriptions/222.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"subscription": {
"id": 15254809,
"state": "canceled",
"trial_started_at": null,
"trial_ended_at": null,
"activated_at": "2016-11-15T15:33:44-05:00",
"created_at": "2016-11-15T15:33:44-05:00",
"updated_at": "2016-11-15T17:13:06-05:00",
"expires_at": null,
"balance_in_cents": 0,
"current_period_ends_at": "2017-08-29T12:00:00-04:00",
"next_assessment_at": "2017-08-29T12:00:00-04:00",
"canceled_at": "2016-11-15T17:13:06-05:00",
"cancellation_message": "Canceling the subscription via the API",
"next_product_id": null,
"cancel_at_end_of_period": false,
"payment_collection_method": "automatic",
"snap_day": null,
"cancellation_method": "merchant_api",
"current_period_started_at": "2016-11-15T15:33:44-05:00",
"previous_state": "active",
"signup_payment_id": 0,
"signup_revenue": "0.00",
"delayed_cancel_at": null,
"coupon_code": null,
"total_revenue_in_cents": 0,
"product_price_in_cents": 1000,
"product_version_number": 7,
"payment_type": "credit_card",
"referral_code": "tg8qbq",
"coupon_use_count": null,
"coupon_uses_allowed": null,
"customer": {
"id": 14731081,
"first_name": "John",
"last_name": "Doe",
"organization": "Acme Widgets",
"email": "john.doe@example.com",
"created_at": "2016-11-15T15:33:44-05:00",
"updated_at": "2016-11-15T15:33:45-05:00",
"reference": "123",
"address": null,
"address_2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone": null,
"portal_invite_last_sent_at": "2016-11-15T15:33:45-05:00",
"portal_invite_last_accepted_at": null,
"verified": false,
"portal_customer_created_at": "2016-11-15T15:33:45-05:00",
"cc_emails": null
},
"product": {
"id": 3792003,
"name": "$10 Basic Plan",
"handle": "basic",
"description": "lorem ipsum",
"accounting_code": "basic",
"request_credit_card": false,
"expiration_interval": null,
"expiration_interval_unit": "never",
"created_at": "2016-03-24T13:38:39-04:00",
"updated_at": "2016-11-03T13:03:05-04:00",
"price_in_cents": 1000,
"interval": 1,
"interval_unit": "day",
"initial_charge_in_cents": null,
"trial_price_in_cents": null,
"trial_interval": null,
"trial_interval_unit": "month",
"archived_at": null,
"require_credit_card": false,
"return_params": "",
"taxable": false,
"update_return_url": "",
"initial_charge_after_trial": false,
"version_number": 7,
"update_return_params": "",
"product_family": {
"id": 527890,
"name": "Acme Projects",
"description": "",
"handle": "billing-plans",
"accounting_code": null
},
"public_signup_pages": [
{
"id": 281054,
"return_url": "http://www.example.com?successfulsignup",
"return_params": "",
"url": "https://general-goods.chargify.com/subscribe/kqvmfrbgd89q/basic"
},
{
"id": 281240,
"return_url": "",
"return_params": "",
"url": "https://general-goods.chargify.com/subscribe/dkffht5dxfd8/basic"
},
{
"id": 282694,
"return_url": "",
"return_params": "",
"url": "https://general-goods.chargify.com/subscribe/jwffwgdd95s8/basic"
}
]
},
"credit_card": {
"id": 10202898,
"first_name": "John",
"last_name": "Doe",
"masked_card_number": "XXXX-XXXX-XXXX-1111",
"card_type": "visa",
"expiration_month": 12,
"expiration_year": 2020,
"customer_id": 14731081,
"current_vault": "authorizenet",
"vault_token": "12345",
"billing_address": null,
"billing_city": null,
"billing_state": null,
"billing_zip": null,
"billing_country": null,
"customer_vault_token": "67890",
"billing_address_2": null,
"payment_type": "credit_card"
}
}
}
```
# Errors
| HTTP Status Code | Error Description |
| --- | --- |
| 404 | Not Found |
| 422 | Unprocessable Entity (WebDAV) |
##### Resume Subscription
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-status/resume-subscription
Resumes a paused (on-hold) subscription. If the normal next renewal date has not passed, the subscription will return to active and will renew on that date. Otherwise, it will behave like a reactivation, setting the billing date to 'now' and charging the subscriber.
```http
POST /subscriptions/{subscription_id}/resume.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `calendar_billing['resumption_charge']` | [`Resumption Charge`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/resumption-charge) | Query, Optional | (For calendar billing subscriptions only) The way that the resumed subscription's charge should be handled.
**Default**: `prorated` |
# Response Type
**200**: OK
[`Subscription Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/subscription-response)
# Example Usage
```bash
curl -X POST -G \
--url 'https://subdomain.chargify.com/subscriptions/222/resume.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"subscription": {
"id": 18220670,
"state": "active",
"trial_started_at": null,
"trial_ended_at": null,
"activated_at": "2017-06-27T13:45:15-05:00",
"created_at": "2017-06-27T13:45:13-05:00",
"updated_at": "2017-06-30T09:26:50-05:00",
"expires_at": null,
"balance_in_cents": 10000,
"current_period_ends_at": "2017-06-30T12:00:00-05:00",
"next_assessment_at": "2017-06-30T12:00:00-05:00",
"canceled_at": null,
"cancellation_message": null,
"next_product_id": null,
"cancel_at_end_of_period": false,
"payment_collection_method": "automatic",
"snap_day": "end",
"cancellation_method": null,
"current_period_started_at": "2017-06-27T13:45:13-05:00",
"previous_state": "active",
"signup_payment_id": 191819284,
"signup_revenue": "0.00",
"delayed_cancel_at": null,
"coupon_code": null,
"total_revenue_in_cents": 0,
"product_price_in_cents": 0,
"product_version_number": 1,
"payment_type": null,
"referral_code": "d3pw7f",
"coupon_use_count": null,
"coupon_uses_allowed": null,
"reason_code": null,
"automatically_resume_at": null,
"current_billing_amount_in_cents": 10000,
"customer": {
"id": 17780587,
"first_name": "Catie",
"last_name": "Test",
"organization": "Acme, Inc.",
"email": "catie@example.com",
"created_at": "2017-06-27T13:01:05-05:00",
"updated_at": "2017-06-30T09:23:10-05:00",
"reference": "123ABC",
"address": "123 Anywhere Street",
"address_2": "Apartment #10",
"city": "Los Angeles",
"state": "CA",
"zip": "90210",
"country": "US",
"phone": "555-555-5555",
"portal_invite_last_sent_at": "2017-06-27T13:45:16-05:00",
"portal_invite_last_accepted_at": null,
"verified": true,
"portal_customer_created_at": "2017-06-27T13:01:08-05:00",
"cc_emails": "support@example.com",
"tax_exempt": true
},
"product": {
"id": 4470347,
"name": "Zero Dollar Product",
"handle": "zero-dollar-product",
"description": "",
"accounting_code": "",
"request_credit_card": true,
"expiration_interval": null,
"expiration_interval_unit": "never",
"created_at": "2017-03-23T10:54:12-05:00",
"updated_at": "2017-04-20T15:18:46-05:00",
"price_in_cents": 0,
"interval": 1,
"interval_unit": "month",
"initial_charge_in_cents": null,
"trial_price_in_cents": null,
"trial_interval": null,
"trial_interval_unit": "month",
"archived_at": null,
"require_credit_card": false,
"return_params": "",
"taxable": false,
"update_return_url": "",
"tax_code": "",
"initial_charge_after_trial": false,
"version_number": 1,
"update_return_params": "",
"product_family": {
"id": 997233,
"name": "Acme Products",
"description": "",
"handle": "acme-products",
"accounting_code": null
},
"public_signup_pages": [
{
"id": 316810,
"return_url": "",
"return_params": "",
"url": "https://general-goods.chargify.com/subscribe/69x825m78v3d/zero-dollar-product"
}
]
}
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Pause Subscription
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-status/pause-subscription
Places the subscription on hold, preventing it from renewing.
## Limitations
You may not place a subscription on hold if the `next_billing_at` date is within 24 hours.
```http
POST /subscriptions/{subscription_id}/hold.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `body` | [`Pause Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/pause-request) | Body, Optional | Allows you to pause a Subscription. |
# Response Type
**200**: OK
[`Subscription Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/subscription-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscriptions/222/hold.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"hold": {
"automatically_resume_at": "2017-05-25T11:25:00Z"
}
}'
```
# Example Response *(as JSON)*
```json
{
"subscription": {
"id": 18220670,
"state": "on_hold",
"trial_started_at": null,
"trial_ended_at": null,
"activated_at": "2017-06-27T13:45:15-05:00",
"created_at": "2017-06-27T13:45:13-05:00",
"updated_at": "2017-06-30T09:26:50-05:00",
"expires_at": null,
"balance_in_cents": 10000,
"current_period_ends_at": "2017-06-30T12:00:00-05:00",
"next_assessment_at": "2017-06-30T12:00:00-05:00",
"canceled_at": null,
"cancellation_message": null,
"next_product_id": null,
"cancel_at_end_of_period": false,
"payment_collection_method": "automatic",
"snap_day": "end",
"cancellation_method": null,
"current_period_started_at": "2017-06-27T13:45:13-05:00",
"previous_state": "active",
"signup_payment_id": 191819284,
"signup_revenue": "0.00",
"delayed_cancel_at": null,
"coupon_code": null,
"total_revenue_in_cents": 0,
"product_price_in_cents": 0,
"product_version_number": 1,
"payment_type": null,
"referral_code": "d3pw7f",
"coupon_use_count": null,
"coupon_uses_allowed": null,
"reason_code": null,
"automatically_resume_at": null,
"current_billing_amount_in_cents": 10000,
"customer": {
"id": 17780587,
"first_name": "Catie",
"last_name": "Test",
"organization": "Acme, Inc.",
"email": "catie@example.com",
"created_at": "2017-06-27T13:01:05-05:00",
"updated_at": "2017-06-30T09:23:10-05:00",
"reference": "123ABC",
"address": "123 Anywhere Street",
"address_2": "Apartment #10",
"city": "Los Angeles",
"state": "CA",
"zip": "90210",
"country": "US",
"phone": "555-555-5555",
"portal_invite_last_sent_at": "2017-06-27T13:45:16-05:00",
"portal_invite_last_accepted_at": null,
"verified": true,
"portal_customer_created_at": "2017-06-27T13:01:08-05:00",
"cc_emails": "support@example.com",
"tax_exempt": true
},
"product": {
"id": 4470347,
"name": "Zero Dollar Product",
"handle": "zero-dollar-product",
"description": "",
"accounting_code": "",
"request_credit_card": true,
"expiration_interval": null,
"expiration_interval_unit": "never",
"created_at": "2017-03-23T10:54:12-05:00",
"updated_at": "2017-04-20T15:18:46-05:00",
"price_in_cents": 0,
"interval": 1,
"interval_unit": "month",
"initial_charge_in_cents": null,
"trial_price_in_cents": null,
"trial_interval": null,
"trial_interval_unit": "month",
"archived_at": null,
"require_credit_card": false,
"return_params": "",
"taxable": false,
"update_return_url": "",
"tax_code": "",
"initial_charge_after_trial": false,
"version_number": 1,
"update_return_params": "",
"product_family": {
"id": 997233,
"name": "Acme Products",
"description": "",
"handle": "acme-products",
"accounting_code": null
},
"public_signup_pages": [
{
"id": 316810,
"return_url": "",
"return_params": "",
"url": "https://general-goods.chargify.com/subscribe/69x825m78v3d/zero-dollar-product"
}
]
}
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Update Automatic Subscription Resumption
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-status/update-automatic-subscription-resumption
Updates the date on which a paused subscription will automatically resume.
To update a subscription's resume date, use this method to change or update the `automatically_resume_at` date.
### Remove the resume date
Alternatively, you can change the `automatically_resume_at` to `null` if you would like the subscription to not have a resume date.
```http
PUT /subscriptions/{subscription_id}/hold.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `body` | [`Pause Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/pause-request) | Body, Optional | Allows you to pause a Subscription. |
# Response Type
**200**: OK
[`Subscription Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/subscription-response)
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/subscriptions/222/hold.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"hold": {
"automatically_resume_at": "2019-01-20T00:00:00"
}
}'
```
# Example Response *(as JSON)*
```json
{
"subscription": {
"id": 20359140,
"state": "on_hold",
"trial_started_at": null,
"trial_ended_at": null,
"activated_at": "2018-01-05T17:15:50-06:00",
"created_at": "2018-01-05T17:15:49-06:00",
"updated_at": "2018-01-09T10:26:14-06:00",
"expires_at": null,
"balance_in_cents": 0,
"current_period_ends_at": "2023-01-05T17:15:00-06:00",
"next_assessment_at": "2023-01-05T17:15:00-06:00",
"canceled_at": null,
"cancellation_message": null,
"next_product_id": null,
"cancel_at_end_of_period": false,
"payment_collection_method": "automatic",
"snap_day": null,
"cancellation_method": null,
"current_period_started_at": "2018-01-05T17:15:49-06:00",
"previous_state": "active",
"signup_payment_id": 219829722,
"signup_revenue": "100.00",
"delayed_cancel_at": null,
"coupon_code": null,
"total_revenue_in_cents": 10009991,
"product_price_in_cents": 10000,
"product_version_number": 1,
"payment_type": "credit_card",
"referral_code": "8y7jqr",
"coupon_use_count": null,
"coupon_uses_allowed": null,
"reason_code": null,
"automatically_resume_at": "2019-01-20T00:00:00-06:00",
"customer": {
"id": 19948683,
"first_name": "Vanessa",
"last_name": "Test",
"organization": "",
"email": "vanessa@example.com",
"created_at": "2018-01-05T17:15:49-06:00",
"updated_at": "2018-01-05T17:15:51-06:00",
"reference": null,
"address": "123 Anywhere Ln",
"address_2": "",
"city": "Boston",
"state": "MA",
"zip": "02120",
"country": "US",
"phone": "555-555-1212",
"portal_invite_last_sent_at": "2018-01-05T17:15:51-06:00",
"portal_invite_last_accepted_at": null,
"verified": null,
"portal_customer_created_at": "2018-01-05T17:15:51-06:00",
"cc_emails": null,
"tax_exempt": false
},
"product": {
"id": 4535643,
"name": "Annual Product",
"handle": "annual-product",
"description": "",
"accounting_code": "",
"request_credit_card": true,
"expiration_interval": null,
"expiration_interval_unit": "never",
"created_at": "2017-08-25T10:25:31-05:00",
"updated_at": "2017-08-25T10:25:31-05:00",
"price_in_cents": 10000,
"interval": 12,
"interval_unit": "month",
"initial_charge_in_cents": null,
"trial_price_in_cents": null,
"trial_interval": null,
"trial_interval_unit": "month",
"archived_at": null,
"require_credit_card": true,
"return_params": "",
"taxable": false,
"update_return_url": "",
"tax_code": "",
"initial_charge_after_trial": false,
"version_number": 1,
"update_return_params": "",
"product_family": {
"id": 1025627,
"name": "Acme Products",
"description": "",
"handle": "acme-products",
"accounting_code": null
}
},
"credit_card": {
"id": 13826563,
"first_name": "Bomb 3",
"last_name": "Test",
"masked_card_number": "XXXX-XXXX-XXXX-1",
"card_type": "bogus",
"expiration_month": 1,
"expiration_year": 2028,
"customer_id": 19948683,
"current_vault": "bogus",
"vault_token": "1",
"billing_address": "123 Anywhere Lane",
"billing_city": "Boston",
"billing_state": "Ma",
"billing_zip": "02120",
"billing_country": "US",
"customer_vault_token": null,
"billing_address_2": "",
"payment_type": "credit_card"
}
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Reactivate Subscription
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-status/reactivate-subscription
Reactivates a previously canceled subscription. For details on how the reactivation works, and how to reactivate subscriptions through the application, see [reactivation](https://maxio.zendesk.com/hc/en-us/articles/24252109503629-Reactivating-and-Resuming).
**Note: The term "resume" is used also during another process in Advanced Billing. This occurs when an on-hold subscription is "resumed". This returns the subscription to an active state.**
+ The response returns the subscription object in the `active` or `trialing` state.
+ The `canceled_at` and `cancellation_message` fields do not have values.
+ The method works for "Canceled" or "Trial Ended" subscriptions.
+ It will not work for items not marked as "Canceled", "Unpaid", or "Trial Ended".
## Resume the current billing period for a subscription
A subscription is considered "resumable" if you are attempting to reactivate within the billing period the subscription was canceled in.
A resumed subscription's billing date remains the same as before it was canceled. In other words, it does not start a new billing period. Payment may or may not be collected for a resumed subscription, depending on whether or not the subscription had a balance when it was canceled (for example, if it was canceled because of dunning).
Consider a subscription which was created on June 1st, and would renew on July 1st. The subscription is then canceled on June 15.
If a reactivation with `resume: true` were attempted _before_ what would have been the next billing date of July 1st, then Advanced Billing would resume the subscription.
If a reactivation with `resume: true` were attempted _after_ what would have been the next billing date of July 1st, then Advanced Billing would not resume the subscription, and instead it would be reactivated with a new billing period.
If a reactivation with `resume: false`, or where 'resume' is omitted were attempted, then Advanced Billing would reactivate the subscription with a new billing period regardless of whether or not resuming the previous billing period was possible.
| Canceled | Reactivation | Resumable? |
|---|---|---|
| Jun 15 | June 28 | Yes |
| Jun 15 | July 2 | No |
## Reactivation Scenarios
### Reactivating Canceled Subscription While Preserving Balance
+ Given you have a product that costs $20
+ Given you have a canceled subscription to the $20 product
+ 1 charge should exist for $20
+ 1 payment should exist for $20
+ When the subscription has canceled due to dunning, it retained a negative balance of $20
#### Results
The resulting charges upon reactivation will be:
+ 1 charge for $20 for the new product
+ 1 charge for $20 for the balance due
+ Total charges = $40
+ The subscription will transition to active
+ The subscription balance will be zero
### Reactivating a Canceled Subscription With Coupon
+ Given you have a canceled subscription
+ It has no current period defined
+ You have a coupon code "EARLYBIRD"
+ The coupon is set to recur for 6 periods
PUT request sent to:
`https://acme.chargify.com/subscriptions/{subscription_id}/reactivate.json?coupon_code=EARLYBIRD`
#### Results
+ The subscription will transition to active
+ The subscription should have applied a coupon with code "EARLYBIRD"
### Reactivating Canceled Subscription With a Trial, Without the include_trial Flag
+ Given you have a canceled subscription
+ The product associated with the subscription has a trial
+ PUT request to
`https://acme.chargify.com/subscriptions/{subscription_id}/reactivate.json`
#### Results
+ The subscription will transition to active
### Reactivating Canceled Subscription With Trial, With the include_trial Flag
+ Given you have a canceled subscription
+ The product associated with the subscription has a trial
+ Send a PUT request to `https://acme.chargify.com/subscriptions/{subscription_id}/reactivate.json?include_trial=1`
#### Results
+ The subscription will transition to trialing
### Reactivating Trial Ended Subscription
+ Given you have a trial_ended subscription
+ Send a PUT request to `https://acme.chargify.com/subscriptions/{subscription_id}/reactivate.json`
#### Results
+ The subscription will transition to active
### Resuming a Canceled Subscription
+ Given you have a `canceled` subscription and it is resumable
+ Send a PUT request to `https://acme.chargify.com/subscriptions/{subscription_id}/reactivate.json?resume=true`
#### Results
+ The subscription will transition to active
+ The next billing date should not have changed
### Attempting to resume a subscription which is not resumable
+ Given you have a `canceled` subscription, and it is not resumable
+ Send a PUT request to `https://acme.chargify.com/subscriptions/{subscription_id}/reactivate.json?resume=true`
#### Results
+ The subscription will transition to active, with a new billing period.
### Attempting to resume but not reactivate a subscription which is not resumable
+ Given you have a `canceled` subscription, and it is not resumable
+ Send a PUT request to `https://acme.chargify.com/subscriptions/{subscription_id}/reactivate.json?resume[require_resume]=true`
+ The response status should be "422 UNPROCESSABLE ENTITY"
+ The subscription should be canceled with the following response
```
{
"errors": ["Request was 'resume only', but this subscription cannot be resumed."]
}
```
#### Results
+ The subscription should remain `canceled`
+ The next billing date should not have changed
### Resuming Subscription Which Was Trialing
+ Given you have a `trial_ended` subscription, and it is resumable
+ And the subscription was canceled in the middle of a trial
+ And there is still time left on the trial
+ Send a PUT request to `https://acme.chargify.com/subscriptions/{subscription_id}/reactivate.json?resume=true`
#### Results
+ The subscription will transition to trialing
+ The next billing date should not have changed
### Resuming Subscription Which Was trial_ended
+ Given you have a `trial_ended` subscription, and it is resumable
+ Send a PUT request to `https://acme.chargify.com/subscriptions/{subscription_id}/reactivate.json?resume=true`
#### Results
+ The subscription will transition to active
+ The next billing date should not have changed
+ Any product-related charges should have been collected
## 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.
```http
PUT /subscriptions/{subscription_id}/reactivate.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `body` | [`Reactivate Subscription Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/reactivate-subscription-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Subscription Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/subscription-response)
# Example Usage
```bash
curl -X PUT \
--url 'https://subdomain.chargify.com/subscriptions/222/reactivate.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"calendar_billing": {
"reactivation_charge": "prorated"
},
"include_trial": true,
"preserve_balance": true,
"coupon_code": "10OFF",
"use_credits_and_prepayments": true,
"resume": true
}'
```
# Example Response *(as JSON)*
```json
{
"subscription": {
"id": 18220670,
"state": "active",
"trial_started_at": null,
"trial_ended_at": null,
"activated_at": "2017-06-27T13:45:15-05:00",
"created_at": "2017-06-27T13:45:13-05:00",
"updated_at": "2017-06-30T09:26:50-05:00",
"expires_at": null,
"balance_in_cents": 10000,
"current_period_ends_at": "2017-06-30T12:00:00-05:00",
"next_assessment_at": "2017-06-30T12:00:00-05:00",
"canceled_at": null,
"cancellation_message": null,
"next_product_id": null,
"cancel_at_end_of_period": false,
"payment_collection_method": "automatic",
"snap_day": "end",
"cancellation_method": null,
"current_period_started_at": "2017-06-27T13:45:13-05:00",
"previous_state": "active",
"signup_payment_id": 191819284,
"signup_revenue": "0.00",
"delayed_cancel_at": null,
"coupon_code": null,
"total_revenue_in_cents": 0,
"product_price_in_cents": 0,
"product_version_number": 1,
"payment_type": null,
"referral_code": "d3pw7f",
"coupon_use_count": null,
"coupon_uses_allowed": null,
"reason_code": null,
"automatically_resume_at": null,
"current_billing_amount_in_cents": 10000,
"customer": {
"id": 17780587,
"first_name": "Catie",
"last_name": "Test",
"organization": "Acme, Inc.",
"email": "catie@example.com",
"created_at": "2017-06-27T13:01:05-05:00",
"updated_at": "2017-06-30T09:23:10-05:00",
"reference": "123ABC",
"address": "123 Anywhere Street",
"address_2": "Apartment #10",
"city": "Los Angeles",
"state": "CA",
"zip": "90210",
"country": "US",
"phone": "555-555-5555",
"portal_invite_last_sent_at": "2017-06-27T13:45:16-05:00",
"portal_invite_last_accepted_at": null,
"verified": true,
"portal_customer_created_at": "2017-06-27T13:01:08-05:00",
"cc_emails": "support@example.com",
"tax_exempt": true,
"vat_number": "012345678"
},
"product": {
"id": 4470347,
"name": "Zero Dollar Product",
"handle": "zero-dollar-product",
"description": "",
"accounting_code": "",
"request_credit_card": true,
"expiration_interval": null,
"expiration_interval_unit": "never",
"created_at": "2017-03-23T10:54:12-05:00",
"updated_at": "2017-04-20T15:18:46-05:00",
"price_in_cents": 0,
"interval": 1,
"interval_unit": "month",
"initial_charge_in_cents": null,
"trial_price_in_cents": null,
"trial_interval": null,
"trial_interval_unit": "month",
"archived_at": null,
"require_credit_card": false,
"return_params": "",
"taxable": false,
"update_return_url": "",
"tax_code": "",
"initial_charge_after_trial": false,
"version_number": 1,
"update_return_params": "",
"product_family": {
"id": 997233,
"name": "Acme Products",
"description": "",
"handle": "acme-products",
"accounting_code": null
},
"public_signup_pages": [
{
"id": 316810,
"return_url": "",
"return_params": "",
"url": "https://general-goods.chargify.com/subscribe/69x825m78v3d/zero-dollar-product"
}
]
}
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Initiate Delayed Cancellation
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-status/initiate-delayed-cancellation
Cancels a subscription at the end of the current billing period based on the subscription's current product. You cannot set `cancel_at_end_of_period` at subscription creation, or if the subscription is past due.
```http
POST /subscriptions/{subscription_id}/delayed_cancel.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `body` | [`Cancellation Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/cancellation-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Delayed Cancellation Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/delayed-cancellation-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscriptions/222/delayed_cancel.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 404 | Not Found | |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Cancel Delayed Cancellation
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-status/cancel-delayed-cancellation
Removes the delayed cancellation from a subscription, ensuring it is not canceled at the end of the current period. The request will reset the `cancel_at_end_of_period` flag to `false`.
This endpoint is idempotent. If the subscription was not set to cancel in the future, removing the delayed cancellation has no effect and the call will be successful.
```http
DELETE /subscriptions/{subscription_id}/delayed_cancel.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
# Response Type
**200**: OK
[`Delayed Cancellation Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/delayed-cancellation-response)
# Example Usage
```bash
curl -X DELETE \
--url 'https://subdomain.chargify.com/subscriptions/222/delayed_cancel.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Example Response *(as JSON)*
```json
{
"message": "This subscription will no longer be canceled"
}
```
# Errors
| HTTP Status Code | Error Description |
| --- | --- |
| 404 | Not Found |
##### Cancel Dunning
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-status/cancel-dunning
Cancels the active dunning process for a subscription and sets it to active.
```http
POST /subscriptions/{subscription_id}/cancel_dunning.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
# Response Type
**200**: OK
[`Subscription Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/subscription-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscriptions/222/cancel_dunning.json' \
-H 'Accept: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword'
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
##### Preview Renewal
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/subscription-status/preview-renewal
Previews a subscription’s next renewal assessment. Renewal Preview is an object representing a subscription’s next assessment. You can retrieve it to see a snapshot of how much your customer will be charged on their next renewal.
The "Next Billing" amount and "Next Billing" date are already represented in the UI on each Subscriber's Summary. For more information, see [Subscriber Interface Overview](https://maxio.zendesk.com/hc/en-us/articles/24252493695757-Subscriber-Interface-Overview).
## Optional Component Fields
This endpoint is particularly useful because it returns the computed billing amount for the base product and the components which are in use by a subscriber.
By default, the preview includes billing details for all components _at their **current** quantities_. This means:
* Current `allocated_quantity` for quantity-based components
* Current enabled/disabled status for on/off components
* Current metered usage `unit_balance` for metered components
* Current metric quantity value for events recorded thus far for events-based components
In the above statements, "current" means the quantity or value as of the call to the renewal preview endpoint. End-of-period values for components are not predicted, so metered or events-based usage may be less than it will eventually be at the end of the period.
Optionally, **you can provide your own custom quantities** for any component to see a billing preview for non-current quantities. This is accomplished by sending a request body with data under the `components` key. See the request body documentation below.
## Preview Behavior
Sending a `POST` request to this endpoint returns preview data without modifying the subscription. This method previews data, but does not log any changes against a subscription.
```http
POST /subscriptions/{subscription_id}/renewals/preview.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Template, Required | The Chargify id of the subscription. |
| `body` | [`Renewal Preview Request`](https://developers.maxio.com/http/advanced-billing-api/models/structures/renewal-preview-request) | Body, Optional | - |
# Response Type
**200**: OK
[`Renewal Preview Response`](https://developers.maxio.com/http/advanced-billing-api/models/structures/renewal-preview-response)
# Example Usage
```bash
curl -X POST \
--url 'https://subdomain.chargify.com/subscriptions/222/renewals/preview.json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'BasicAuthUserName:BasicAuthPassword' \
--data-raw '{
"components": [
{
"component_id": 10708,
"quantity": 10000
},
{
"component_id": "handle:small-instance-hours",
"quantity": 10000,
"price_point_id": 8712
},
{
"component_id": "handle:large-instance-hours",
"quantity": 100,
"price_point_id": "handle:startup-pricing"
}
]
}'
```
# Example Response *(as JSON)*
```json
{
"renewal_preview": {
"next_assessment_at": "2017-03-13T12:50:55-04:00",
"subtotal_in_cents": 6000,
"total_tax_in_cents": 0,
"total_discount_in_cents": 0,
"total_in_cents": 6000,
"existing_balance_in_cents": 0,
"total_amount_due_in_cents": 6000,
"uncalculated_taxes": false,
"line_items": [
{
"transaction_type": "charge",
"kind": "baseline",
"amount_in_cents": 5000,
"memo": "Gold Product (03/13/2017 - 04/13/2017)",
"discount_amount_in_cents": 0,
"taxable_amount_in_cents": 0,
"product_id": 1,
"product_handle": "gold-product",
"product_name": "Gold Product",
"period_range_start": "01/10/2024",
"period_range_end": "02/10/2024"
},
{
"transaction_type": "charge",
"kind": "quantity_based_component",
"amount_in_cents": 1000,
"memo": "Quantity Component: 10 Quantity Components",
"discount_amount_in_cents": 0,
"taxable_amount_in_cents": 0,
"component_id": 104,
"component_handle": "quantity-component",
"component_name": "Quantity Component",
"period_range_start": "01/10/2024",
"period_range_end": "02/10/2024"
}
]
}
}
```
# Errors
| HTTP Status Code | Error Description | Exception Class |
| --- | --- | --- |
| 422 | Unprocessable Entity (WebDAV) | [`Error List ResponseException`](https://developers.maxio.com/http/advanced-billing-api/models/exceptions/error-list-response) |
#### Webhooks
##### List Webhooks
Source: https://developers.maxio.com/http/advanced-billing-api/api-endpoints/webhooks/list-webhooks
Retrieves a list of webhooks. You can pass query parameters if you want to filter webhooks. See the [Webhooks](https://developers.maxio.com/http/getting-started/webhooks/webhooks) documentation for more information.
```http
GET /webhooks.json
```
# Authentication
This endpoint requires [BasicAuth](https://developers.maxio.com/http/getting-started/how-to-get-started#authorization)
# Parameters
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `status` | [`Webhook Status`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/webhook-status) | Query, Optional | Webhooks with matching status would be returned. |
| `since_date` | `String` | Query, Optional | Format YYYY-MM-DD. Returns Webhooks with the created_at date greater than or equal to the one specified. |
| `until_date` | `String` | Query, Optional | Format YYYY-MM-DD. Returns Webhooks with the created_at date less than or equal to the one specified. |
| `page` | `Number` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query `page=1`.
**Default**: `1`
**Constraints**: `>= 1` |
| `per_page` | `Number` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query `per_page=200`.
**Default**: `false` |
| `site_gateway_setting_id` | `Number` | Optional | - |
| `gateway_handle` | `String` | Optional | - |
| `created_at` | `DateTime` | Optional | A timestamp indicating when this payment profile was created |
| `updated_at` | `DateTime` | Optional | A timestamp indicating when this payment profile was last updated |
# Example (as JSON)
```json
{
"payment_type": "bank_account",
"verified": false,
"id": 188,
"first_name": "first_name6",
"last_name": "last_name4",
"customer_id": 226,
"current_vault": "authorizenet"
}
```
##### Credit Card Payment Profile
Source: https://developers.maxio.com/http/advanced-billing-api/models/structures/credit-card-payment-profile
# Fields
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `id` | `Number` | Optional | The Chargify-assigned ID of the stored card. This value can be used as an input to payment_profile_id when creating a subscription, in order to re-use a stored payment profile for the same customer. |
| `first_name` | `String` | Optional | The first name of the card holder. |
| `last_name` | `String` | Optional | The last name of the card holder. |
| `masked_card_number` | `String` | Optional | A string representation of the credit card number with all but the last 4 digits masked with X’s (e.g., ‘XXXX-XXXX-XXXX-1234’). |
| `card_type` | [`Card Type`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/card-type) | Optional | The type of card used. |
| `expiration_month` | `Number` | Optional | An integer representing the expiration month of the card(1 – 12). |
| `expiration_year` | `Number` | Optional | An integer representing the 4-digit expiration year of the card(e.g., ‘2012’). |
| `customer_id` | `Number` | Optional | The Chargify-assigned id for the customer record to which the card belongs. |
| `current_vault` | [`Credit Card Vault`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/credit-card-vault) | Optional | The vault that stores the payment profile with the provided `vault_token`. Use `bogus` for testing. |
| `vault_token` | `String` | Optional | The “token” provided by your vault storage for an already stored payment profile. |
| `billing_address` | `String` | Optional | The current billing street address for the card. |
| `billing_city` | `String` | Optional | The current billing address city for the card. |
| `billing_state` | `String` | Optional | The current billing address state for the card. |
| `billing_zip` | `String` | Optional | The current billing address zip code for the card. |
| `billing_country` | `String` | Optional | The current billing address country for the card. |
| `customer_vault_token` | `String` | Optional | (only for Authorize.Net CIM storage): the customerProfileId for the owner of the customerPaymentProfileId provided as the vault_token. |
| `billing_address_2` | `String` | Optional | The current billing street address, second line, for the card. |
| `payment_type` | [`Payment Type`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/payment-type) | Required | **Default**: `credit_card` |
| `disabled` | `Boolean` | Optional | - |
| `chargify_token` | `String` | Optional | Token received after sending billing information using Maxio.js (formerly Chargify.js). This token will only be received if passed as a sole attribute of credit_card_attributes (e.g., tok_9g6hw85pnpt6knmskpwp4ttt). |
| `site_gateway_setting_id` | `Number` | Optional | - |
| `gateway_handle` | `String` | Optional | An identifier of connected gateway. |
| `created_at` | `DateTime` | Optional | A timestamp indicating when this payment profile was created |
| `updated_at` | `DateTime` | Optional | A timestamp indicating when this payment profile was last updated |
# Example (as JSON)
```json
{
"id": 10088716,
"first_name": "Test",
"last_name": "Subscription",
"masked_card_number": "XXXX-XXXX-XXXX-1",
"card_type": "bogus",
"expiration_month": 1,
"expiration_year": 2022,
"customer_id": 14543792,
"current_vault": "bogus",
"vault_token": "1",
"billing_address": "123 Montana Way",
"billing_city": "Billings",
"billing_state": "MT",
"billing_zip": "59101",
"billing_country": "US",
"customer_vault_token": null,
"billing_address_2": "",
"payment_type": "credit_card",
"site_gateway_setting_id": 1,
"gateway_handle": null
}
```
##### Paypal Payment Profile
Source: https://developers.maxio.com/http/advanced-billing-api/models/structures/paypal-payment-profile
# Fields
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `id` | `Number` | Optional | The Chargify-assigned ID of the stored PayPal payment profile. |
| `first_name` | `String` | Optional | The first name of the PayPal account holder |
| `last_name` | `String` | Optional | The last name of the PayPal account holder |
| `customer_id` | `Number` | Optional | The Chargify-assigned id for the customer record to which the PayPal account belongs |
| `current_vault` | [`Pay Pal Vault`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/pay-pal-vault) | Optional | The vault that stores the payment profile with the provided vault_token. |
| `vault_token` | `String` | Optional | The “token” provided by your vault storage for an already stored payment profile |
| `billing_address` | `String` | Optional | The current billing street address for the PayPal account |
| `billing_city` | `String` | Optional | The current billing address city for the PayPal account |
| `billing_state` | `String` | Optional | The current billing address state for the PayPal account |
| `billing_zip` | `String` | Optional | The current billing address zip code for the PayPal account |
| `billing_country` | `String` | Optional | The current billing address country for the PayPal account |
| `customer_vault_token` | `String` | Optional | - |
| `billing_address_2` | `String` | Optional | The current billing street address, second line, for the PayPal account |
| `payment_type` | [`Payment Type`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/payment-type) | Required | **Default**: `paypal_account` |
| `site_gateway_setting_id` | `Number` | Optional | - |
| `gateway_handle` | `String` | Optional | - |
| `paypal_email` | `String` | Optional | - |
| `created_at` | `DateTime` | Optional | A timestamp indicating when this payment profile was created |
| `updated_at` | `DateTime` | Optional | A timestamp indicating when this payment profile was last updated |
# Example (as JSON)
```json
{
"payment_type": "paypal_account",
"id": 10,
"first_name": "first_name0",
"last_name": "last_name8",
"customer_id": 48,
"current_vault": "moduslink"
}
```
##### Account Balance
Source: https://developers.maxio.com/http/advanced-billing-api/models/structures/account-balance
# Fields
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `balance_in_cents` | `Long` | Optional | The balance in cents. |
| `automatic_balance_in_cents` | `Long` | Optional | The automatic balance in cents. |
| `remittance_balance_in_cents` | `Long` | Optional | The remittance balance in cents. |
# Example (as JSON)
```json
{
"balance_in_cents": 16,
"automatic_balance_in_cents": 226,
"remittance_balance_in_cents": 62
}
```
##### Account Balances
Source: https://developers.maxio.com/http/advanced-billing-api/models/structures/account-balances
# Fields
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `open_invoices` | [`Account Balance`](https://developers.maxio.com/http/advanced-billing-api/models/structures/account-balance) | Optional | The balance, in cents, of the sum of the subscription's open, payable invoices. |
| `pending_invoices` | [`Account Balance`](https://developers.maxio.com/http/advanced-billing-api/models/structures/account-balance) | Optional | The balance, in cents, of the sum of the subscription's pending, payable invoices. |
| `pending_discounts` | [`Account Balance`](https://developers.maxio.com/http/advanced-billing-api/models/structures/account-balance) | Optional | The balance, in cents, of the subscription's Pending Discount account. |
| `service_credits` | [`Account Balance`](https://developers.maxio.com/http/advanced-billing-api/models/structures/account-balance) | Optional | The balance, in cents, of the subscription's Service Credit account. |
| `prepayments` | [`Account Balance`](https://developers.maxio.com/http/advanced-billing-api/models/structures/account-balance) | Optional | The balance, in cents, of the subscription's Prepayment account. |
# Example (as JSON)
```json
{
"open_invoices": {
"balance_in_cents": 40,
"automatic_balance_in_cents": 202,
"remittance_balance_in_cents": 170
},
"pending_invoices": {
"balance_in_cents": 0,
"automatic_balance_in_cents": 242,
"remittance_balance_in_cents": 46
},
"pending_discounts": {
"balance_in_cents": 88,
"automatic_balance_in_cents": 154,
"remittance_balance_in_cents": 134
},
"service_credits": {
"balance_in_cents": 84,
"automatic_balance_in_cents": 70,
"remittance_balance_in_cents": 38
},
"prepayments": {
"balance_in_cents": 192,
"automatic_balance_in_cents": 178,
"remittance_balance_in_cents": 146
}
}
```
##### ACH Agreement
Source: https://developers.maxio.com/http/advanced-billing-api/models/structures/ach-agreement
(Optional) If passed, the proof of the authorized ACH agreement terms will be persisted.
# Fields
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `agreement_terms` | `String` | Optional | (Required when providing ACH agreement params) The ACH authorization agreement terms. |
| `authorizer_first_name` | `String` | Optional | (Required when providing ACH agreement params) The first name of the person authorizing the ACH agreement. |
| `authorizer_last_name` | `String` | Optional | (Required when providing ACH agreement params) The last name of the person authorizing the ACH agreement. |
| `ip_address` | `String` | Optional | (Required when providing ACH agreement params) The IP address of the person authorizing the ACH agreement. |
# Example (as JSON)
```json
{
"agreement_terms": "agreement_terms4",
"authorizer_first_name": "authorizer_first_name2",
"authorizer_last_name": "authorizer_last_name2",
"ip_address": "ip_address2"
}
```
##### Activate Event-Based Component
Source: https://developers.maxio.com/http/advanced-billing-api/models/structures/activate-event-based-component
# Fields
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `price_point_id` | `Number` | Optional | The Chargify id of the price point |
| `billing_schedule` | [`Billing Schedule`](https://developers.maxio.com/http/advanced-billing-api/models/structures/billing-schedule) | Optional | Billing schedule settings for component allocations or usages on multi-frequency subscriptions. Use this to start a component's billing period on a custom date instead of aligning with the product charge schedule. |
| `custom_price` | [`Component Custom Price`](https://developers.maxio.com/http/advanced-billing-api/models/structures/component-custom-price) | Optional | Create or update custom pricing unique to the subscription. Used in place of `price_point_id`. |
# Example (as JSON)
```json
{
"price_point_id": 44,
"billing_schedule": {
"initial_billing_at": "2016-03-13"
},
"custom_price": {
"tax_included": false,
"pricing_scheme": "stairstep",
"interval": 66,
"interval_unit": "day",
"list_price_point_id": 174,
"prices": [
{
"starting_quantity": 242,
"ending_quantity": 40,
"unit_price": 23.26
},
{
"starting_quantity": 242,
"ending_quantity": 40,
"unit_price": 23.26
}
]
}
}
```
##### Activate Subscription Request
Source: https://developers.maxio.com/http/advanced-billing-api/models/structures/activate-subscription-request
# Fields
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `revert_on_failure` | `Boolean` | Optional | You may choose how to handle the activation failure. `true` means do not change the subscription’s state and billing period. `false` means to continue through with the activation and enter an end-of-life state. If this parameter is omitted or `null` is passed it will default to the value set in the site settings (default: `true`). |
# Example (as JSON)
```json
{
"revert_on_failure": false
}
```
##### Add Coupons Request
Source: https://developers.maxio.com/http/advanced-billing-api/models/structures/add-coupons-request
# Fields
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `codes` | `array` | Optional | - |
# Example (as JSON)
```json
{
"codes": [
"codes0",
"codes1"
]
}
```
##### Add Subscription to a Group
Source: https://developers.maxio.com/http/advanced-billing-api/models/structures/add-subscription-to-a-group
# Fields
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `group` | [`Group Settings`](https://developers.maxio.com/http/advanced-billing-api/models/structures/group-settings) | Optional | - |
# Example (as JSON)
```json
{
"group": {
"target": {
"type": "parent",
"id": 236
},
"billing": {
"accrue": false,
"align_date": false,
"prorate": false
}
}
}
```
##### Address Change
Source: https://developers.maxio.com/http/advanced-billing-api/models/structures/address-change
# Fields
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `before` | [`Invoice Address`](https://developers.maxio.com/http/advanced-billing-api/models/structures/invoice-address) | Required | - |
| `after` | [`Invoice Address`](https://developers.maxio.com/http/advanced-billing-api/models/structures/invoice-address) | Required | - |
# Example (as JSON)
```json
{
"before": {
"street": "street0",
"line2": "line24",
"city": "city0",
"state": "state6",
"zip": "zip4"
},
"after": {
"street": "street2",
"line2": "line26",
"city": "city8",
"state": "state2",
"zip": "zip4"
}
}
```
##### Aggregated Entitlement
Source: https://developers.maxio.com/http/advanced-billing-api/models/structures/aggregated-entitlement
One entitlement in a subscriber's aggregated entitlements list. Entries are aggregated per (feature key, periodicity window), not per feature key alone — a `usage_limit` feature granted with two different periodicities yields two entries sharing one `feature_key`. Use `periodicity_key` to identify an entry uniquely.
# Fields
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `feature_key` | `String` | Optional | The feature's key, prefixed by kind: `feature.*` for `access_right`, `usage.*` for `usage_limit`, `service.*` for `service_right`. |
| `periodicity_key` | `String` | Optional | Uniquely identifies this aggregated entry: the prefixed feature key, suffixed with `:{interval}:{unit}` when the entitlement has a periodicity window. Equal to `feature_key` when `periodicity` is `null`. |
| `name` | `String` | Optional | - |
| `type` | [`Feature Kind`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/feature-kind) | Optional | The behavior of a feature:
- `access_right`: a boolean entitlement — a subscriber either has access or does not. - `usage_limit`: a quantified allowance measured over a recurring period (for example, "10,000 API calls per month"). - `service_right`: a free-form value (text, boolean, or number) that isn't a simple access flag or a metered limit. |
| `value` | [`Boolean \| Decimal \| String`](https://developers.maxio.com/http/advanced-billing-api/models/oneof-anyof-definitions/aggregated-entitlement-value) | Optional | The aggregated value, coerced according to `type`: a boolean for `access_right` (and boolean `service_right`), a number for `usage_limit` (and numeric `service_right`), or a string for text `service_right`. |
| `enabled` | `Boolean` | Optional | `true` only when the aggregated value is truthy for this feature's kind, and the subscription is in a live state (`active`, `trialing`, `assessing`, `past_due`, or `soft_failure`). `false` otherwise — including `awaiting_signup`, canceled, expired, and on-hold subscriptions. Entitlements deliberately stay enabled through dunning. |
| `periodicity` | [`Aggregated Entitlement Periodicity`](https://developers.maxio.com/http/advanced-billing-api/models/structures/aggregated-entitlement-periodicity) | Optional | - |
| `source_products` | `array` | Optional | The names of the products/components contributing to this entitlement. For `access_right` features, only contributors that granted `true` are listed. |
# Example (as JSON)
```json
{
"feature_key": "feature.sso",
"periodicity_key": "usage.api_calls:1:month",
"name": "name4",
"type": "access_right",
"value": true
}
```
##### Aggregated Entitlement Periodicity
Source: https://developers.maxio.com/http/advanced-billing-api/models/structures/aggregated-entitlement-periodicity
# Fields
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `interval` | `Number` | Optional | - |
| `unit` | [`Entitlement Periodicity Unit`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/entitlement-periodicity-unit) | Optional | The recurring window over which a `usage_limit` feature's allowance resets. |
# Example (as JSON)
```json
{
"interval": 2,
"unit": "hour"
}
```
##### Aggregated Entitlements Response
Source: https://developers.maxio.com/http/advanced-billing-api/models/structures/aggregated-entitlements-response
# Fields
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `subscription_id` | `Number` | Required | - |
| `customer_id` | `Number` | Required | - |
| `status` | `String` | Required | The subscription's current state, e.g. `active`, `trialing`, `canceled`. |
| `entitlements` | [`array`](https://developers.maxio.com/http/advanced-billing-api/models/structures/aggregated-entitlement) | Required | - |
# Example (as JSON)
```json
{
"subscription_id": 10,
"customer_id": 194,
"status": "status6",
"entitlements": [
{
"feature_key": "feature.sso",
"periodicity_key": "usage.api_calls:1:month",
"name": "name6",
"type": "service_right",
"value": true
}
]
}
```
##### Agreement Acceptance
Source: https://developers.maxio.com/http/advanced-billing-api/models/structures/agreement-acceptance
Required when creating a subscription with Maxio Payments.
# Fields
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `ip_address` | `String` | Optional | Required when providing agreement acceptance params. |
| `terms_url` | `String` | Optional | Required when creating a subscription with Maxio Payments. Either terms_url or privacy_policy_url is required when providing agreement_acceptance params. |
| `privacy_policy_url` | `String` | Optional | - |
| `return_refund_policy_url` | `String` | Optional | - |
| `delivery_policy_url` | `String` | Optional | - |
| `secure_checkout_policy_url` | `String` | Optional | - |
# Example (as JSON)
```json
{
"ip_address": "ip_address2",
"terms_url": "terms_url0",
"privacy_policy_url": "privacy_policy_url0",
"return_refund_policy_url": "return_refund_policy_url4",
"delivery_policy_url": "delivery_policy_url8"
}
```
##### Allocate Components
Source: https://developers.maxio.com/http/advanced-billing-api/models/structures/allocate-components
# Fields
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `proration_upgrade_scheme` | `String` | Optional | - |
| `proration_downgrade_scheme` | `String` | Optional | - |
| `allocations` | [`array`](https://developers.maxio.com/http/advanced-billing-api/models/structures/create-allocation) | Optional | - |
| `accrue_charge` | `Boolean` | Optional | - |
| `upgrade_charge` | [`Credit Type`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/credit-type) | Optional | The type of credit to be created when upgrading/downgrading. Defaults to the component and then site setting if one is not provided. |
| `downgrade_credit` | [`Credit Type`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/credit-type) | Optional | The type of credit to be created when upgrading/downgrading. Defaults to the component and then site setting if one is not provided. |
| `payment_collection_method` | [`Collection Method`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/collection-method) | Optional | (Optional) If not passed, the allocation(s) will use the payment collection method on the subscription. |
| `initiate_dunning` | `Boolean` | Optional | If true, if the immediate component payment fails, initiate dunning for the subscription. Otherwise, leave the charges on the subscription to pay for at renewal. |
# Example (as JSON)
```json
{
"proration_upgrade_scheme": "proration_upgrade_scheme2",
"proration_downgrade_scheme": "proration_downgrade_scheme0",
"allocations": [
{
"quantity": 26.48,
"decimal_quantity": "decimal_quantity8",
"previous_quantity": 55.5,
"decimal_previous_quantity": "decimal_previous_quantity2",
"component_id": 242,
"memo": "memo6"
},
{
"quantity": 26.48,
"decimal_quantity": "decimal_quantity8",
"previous_quantity": 55.5,
"decimal_previous_quantity": "decimal_previous_quantity2",
"component_id": 242,
"memo": "memo6"
}
],
"accrue_charge": false,
"upgrade_charge": "full"
}
```
##### Allocation
Source: https://developers.maxio.com/http/advanced-billing-api/models/structures/allocation
# Fields
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `allocation_id` | `Number` | Optional | The allocation unique ID |
| `component_id` | `Number` | Optional | The integer component ID for the allocation. This references a component that you have created in your Product setup. |
| `component_handle` | `String` | Optional | The handle of the component. This references a component that you have created in your Product setup. |
| `subscription_id` | `Number` | Optional | The integer subscription ID for the allocation. This references a unique subscription in your Site. |
| `quantity` | [`Number \| String`](https://developers.maxio.com/http/advanced-billing-api/models/oneof-anyof-definitions/allocation-quantity) | Optional | The allocated quantity set into effect by the allocation. String for components supporting fractional quantities |
| `previous_quantity` | [`Number \| String`](https://developers.maxio.com/http/advanced-billing-api/models/oneof-anyof-definitions/allocation-previous-quantity) | Optional | The allocated quantity that was in effect before this allocation was created. String for components supporting fractional quantities |
| `memo` | `String` | Optional | The memo passed when the allocation was created |
| `timestamp` | `DateTime` | Optional | The time that the allocation was recorded, in ISO 8601 format and UTC timezone, e.g., 2012-11-20T22:00:37Z |
| `created_at` | `DateTime` | Optional | Timestamp indicating when this allocation was created |
| `proration_upgrade_scheme` | `String` | Optional | The scheme used if the proration was an upgrade. This is only present when the allocation was created mid-period. |
| `proration_downgrade_scheme` | `String` | Optional | The scheme used if the proration was a downgrade. This is only present when the allocation was created mid-period. |
| `price_point_id` | `Number` | Optional | - |
| `price_point_name` | `String` | Optional | - |
| `price_point_handle` | `String` | Optional | - |
| `interval` | `Number` | Optional | The numerical interval. e.g., an interval of ‘30’ coupled with an interval_unit of day would mean this component price point would renew every 30 days. This property is only available for sites with Multifrequency enabled. |
| `interval_unit` | [`Interval Unit`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/interval-unit) | Optional | A string representing the interval unit for this component price point, either month or day. This property is only available for sites with Multifrequency enabled. |
| `previous_price_point_id` | `Number` | Optional | - |
| `accrue_charge` | `Boolean` | Optional | If the change in cost is an upgrade, this determines if the charge should accrue to the next renewal or if capture should be attempted immediately. |
| `initiate_dunning` | `Boolean` | Optional | If true, if the immediate component payment fails, initiate dunning for the subscription. Otherwise, leave the charges on the subscription to pay for at renewal. |
| `upgrade_charge` | [`Credit Type`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/credit-type) | Optional | The type of credit to be created when upgrading/downgrading. Defaults to the component and then site setting if one is not provided. |
| `downgrade_credit` | [`Credit Type`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/credit-type) | Optional | The type of credit to be created when upgrading/downgrading. Defaults to the component and then site setting if one is not provided. |
| `payment` | [`Payment for Allocation`](https://developers.maxio.com/http/advanced-billing-api/models/structures/payment-for-allocation) | Optional | - |
| `expires_at` | `DateTime` | Optional | - |
| `used_quantity` | `Long` | Optional | - |
| `charge_id` | `Long` | Optional | - |
# Example (as JSON)
```json
{
"allocation_id": 102,
"component_id": 144,
"component_handle": "component_handle0",
"subscription_id": 144,
"quantity": 168
}
```
##### Allocation Expiration Date
Source: https://developers.maxio.com/http/advanced-billing-api/models/structures/allocation-expiration-date
# Fields
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `expires_at` | `DateTime` | Optional | - |
# Example (as JSON)
```json
{
"expires_at": "2016-03-13T12:52:32.123Z"
}
```
##### Allocation Preview
Source: https://developers.maxio.com/http/advanced-billing-api/models/structures/allocation-preview
# Fields
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `start_date` | `DateTime` | Optional | - |
| `end_date` | `DateTime` | Optional | - |
| `subtotal_in_cents` | `Long` | Optional | - |
| `total_tax_in_cents` | `Long` | Optional | - |
| `total_discount_in_cents` | `Long` | Optional | - |
| `total_in_cents` | `Long` | Optional | - |
| `direction` | [`Allocation Preview Direction`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/allocation-preview-direction) | Optional | - |
| `proration_scheme` | `String` | Optional | - |
| `line_items` | [`array`](https://developers.maxio.com/http/advanced-billing-api/models/structures/allocation-preview-line-item) | Optional | - |
| `accrue_charge` | `Boolean` | Optional | - |
| `allocations` | [`array`](https://developers.maxio.com/http/advanced-billing-api/models/structures/allocation-preview-item) | Optional | - |
| `period_type` | `String` | Optional | - |
| `existing_balance_in_cents` | `Long` | Optional | An integer representing the amount of the subscription's current balance |
# Example (as JSON)
```json
{
"start_date": "2016-03-13T12:52:32.123Z",
"end_date": "2016-03-13T12:52:32.123Z",
"subtotal_in_cents": 4,
"total_tax_in_cents": 128,
"total_discount_in_cents": 122
}
```
##### Allocation Preview Item
Source: https://developers.maxio.com/http/advanced-billing-api/models/structures/allocation-preview-item
# Fields
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `component_id` | `Number` | Optional | - |
| `subscription_id` | `Number` | Optional | - |
| `quantity` | [`Number \| String`](https://developers.maxio.com/http/advanced-billing-api/models/oneof-anyof-definitions/allocation-preview-item-quantity) | Optional | - |
| `previous_quantity` | [`Number \| String`](https://developers.maxio.com/http/advanced-billing-api/models/oneof-anyof-definitions/allocation-preview-item-previous-quantity) | Optional | - |
| `memo` | `String` | Optional | - |
| `timestamp` | `String` | Optional | - |
| `proration_upgrade_scheme` | `String` | Optional | - |
| `proration_downgrade_scheme` | `String` | Optional | - |
| `accrue_charge` | `Boolean` | Optional | - |
| `upgrade_charge` | [`Credit Type`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/credit-type) | Optional | The type of credit to be created when upgrading/downgrading. Defaults to the component and then site setting if one is not provided. |
| `downgrade_credit` | [`Credit Type`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/credit-type) | Optional | The type of credit to be created when upgrading/downgrading. Defaults to the component and then site setting if one is not provided. |
| `price_point_id` | `Number` | Optional | - |
| `interval` | `Number` | Optional | The numerical interval. e.g., an interval of ‘30’ coupled with an interval_unit of day would mean this component price point would renew every 30 days. This property is only available for sites with Multifrequency enabled. |
| `interval_unit` | [`Interval Unit`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/interval-unit) | Optional | A string representing the interval unit for this component price point, either month or day. This property is only available for sites with Multifrequency enabled. |
| `previous_price_point_id` | `Number` | Optional | - |
| `price_point_handle` | `String` | Optional | - |
| `price_point_name` | `String` | Optional | - |
| `component_handle` | `String` | Optional | - |
# Example (as JSON)
```json
{
"component_id": 54,
"subscription_id": 54,
"quantity": 78,
"previous_quantity": 192,
"memo": "memo6"
}
```
##### Allocation Preview Line Item
Source: https://developers.maxio.com/http/advanced-billing-api/models/structures/allocation-preview-line-item
# Fields
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `transaction_type` | [`Line Item Transaction Type`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/line-item-transaction-type) | Optional | A handle for the line item transaction type |
| `kind` | [`Allocation Preview Line Item Kind`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/allocation-preview-line-item-kind) | Optional | A handle for the line item kind for allocation preview |
| `amount_in_cents` | `Long` | Optional | - |
| `memo` | `String` | Optional | - |
| `discount_amount_in_cents` | `Long` | Optional | - |
| `taxable_amount_in_cents` | `Long` | Optional | - |
| `component_id` | `Number` | Optional | - |
| `component_handle` | `String` | Optional | - |
| `direction` | [`Allocation Preview Direction`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/allocation-preview-direction) | Optional | Visible when using Fine-grained Component Control. |
# Example (as JSON)
```json
{
"transaction_type": "credit",
"kind": "quantity_based_component",
"amount_in_cents": 24,
"memo": "memo6",
"discount_amount_in_cents": 172
}
```
##### Allocation Preview Response
Source: https://developers.maxio.com/http/advanced-billing-api/models/structures/allocation-preview-response
# Fields
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `allocation_preview` | [`Allocation Preview`](https://developers.maxio.com/http/advanced-billing-api/models/structures/allocation-preview) | Required | - |
# Example (as JSON)
```json
{
"allocation_preview": {
"start_date": "2016-03-13T12:52:32.123Z",
"end_date": "2016-03-13T12:52:32.123Z",
"subtotal_in_cents": 240,
"total_tax_in_cents": 108,
"total_discount_in_cents": 142
}
}
```
##### Allocation Response
Source: https://developers.maxio.com/http/advanced-billing-api/models/structures/allocation-response
# Fields
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `allocation` | [`Allocation`](https://developers.maxio.com/http/advanced-billing-api/models/structures/allocation) | Optional | - |
# Example (as JSON)
```json
{
"allocation": {
"allocation_id": 238,
"component_id": 8,
"component_handle": "component_handle8",
"subscription_id": 8,
"quantity": 32
}
}
```
##### Allocation Settings
Source: https://developers.maxio.com/http/advanced-billing-api/models/structures/allocation-settings
# Fields
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `upgrade_charge` | [`Credit Type`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/credit-type) | Optional | The type of credit to be created when upgrading/downgrading. Defaults to the component and then site setting if one is not provided. |
| `downgrade_credit` | [`Credit Type`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/credit-type) | Optional | The type of credit to be created when upgrading/downgrading. Defaults to the component and then site setting if one is not provided. |
| `accrue_charge` | `String` | Optional | Either "true" or "false". |
# Example (as JSON)
```json
{
"upgrade_charge": "none",
"downgrade_credit": "prorated",
"accrue_charge": "accrue_charge0"
}
```
##### Applied Credit Note Data
Source: https://developers.maxio.com/http/advanced-billing-api/models/structures/applied-credit-note-data
# Fields
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `uid` | `String` | Optional | The UID of the credit note |
| `number` | `String` | Optional | The number of the credit note |
# Example (as JSON)
```json
{
"uid": "uid2",
"number": "number0"
}
```
##### Apply Credit Note Event Data
Source: https://developers.maxio.com/http/advanced-billing-api/models/structures/apply-credit-note-event-data
Example schema for an `apply_credit_note` event
# Fields
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `uid` | `String` | Required | Unique identifier for the credit note application. It is generated automatically by Chargify and has the prefix "cdt_" followed by alphanumeric characters. |
| `credit_note_number` | `String` | Required | A unique, identifying string that appears on the credit note and in places it is referenced. |
| `credit_note_uid` | `String` | Required | Unique identifier for the credit note. It is generated automatically by Chargify and has the prefix "cn_" followed by alphanumeric characters. |
| `original_amount` | `String` | Required | The full, original amount of the credit note. |
| `applied_amount` | `String` | Required | The amount of the credit note applied to invoice. |
| `transaction_time` | `DateTime` | Optional | The time the credit note was applied, in ISO 8601 format, i.e. "2019-06-07T17:20:06Z" |
| `memo` | `String` | Optional | The credit note memo. |
| `role` | `String` | Optional | The role of the credit note (e.g. 'general') |
| `consolidated_invoice` | `Boolean` | Optional | Shows whether it was applied to consolidated invoice or not. |
| `applied_credit_notes` | [`array`](https://developers.maxio.com/http/advanced-billing-api/models/structures/applied-credit-note-data) | Optional | List of credit notes applied to children invoices (if consolidated invoice) |
# Example (as JSON)
```json
{
"uid": "uid2",
"credit_note_number": "credit_note_number4",
"credit_note_uid": "credit_note_uid4",
"original_amount": "original_amount6",
"applied_amount": "applied_amount6",
"transaction_time": "2016-03-13T12:52:32.123Z",
"memo": "memo6",
"role": "role4",
"consolidated_invoice": false,
"applied_credit_notes": [
{
"uid": "uid4",
"number": "number8"
},
{
"uid": "uid4",
"number": "number8"
}
]
}
```
##### Apply Debit Note Event Data
Source: https://developers.maxio.com/http/advanced-billing-api/models/structures/apply-debit-note-event-data
Example schema for an `apply_debit_note` event
# Fields
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `debit_note_number` | `String` | Required | A unique, identifying string that appears on the debit note and in places it is referenced. |
| `debit_note_uid` | `String` | Required | Unique identifier for the debit note. It is generated automatically by Chargify and has the prefix "db_" followed by alphanumeric characters. |
| `original_amount` | `String` | Required | The full, original amount of the debit note. |
| `applied_amount` | `String` | Required | The amount of the debit note applied to invoice. |
| `memo` | `String` | Optional | The debit note memo. |
| `transaction_time` | `DateTime` | Optional | The time the debit note was applied, in ISO 8601 format, i.e. "2019-06-07T17:20:06Z" |
# Example (as JSON)
```json
{
"debit_note_number": "debit_note_number0",
"debit_note_uid": "debit_note_uid6",
"original_amount": "original_amount4",
"applied_amount": "applied_amount8",
"memo": "memo4",
"transaction_time": "2016-03-13T12:52:32.123Z"
}
```
##### Apply Payment Event Data
Source: https://developers.maxio.com/http/advanced-billing-api/models/structures/apply-payment-event-data
Example schema for an `apply_payment` event
# Fields
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `consolidation_level` | [`Invoice Consolidation Level`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/invoice-consolidation-level) | Required | - |
| `memo` | `String` | Required | The payment memo |
| `original_amount` | `String` | Required | The full, original amount of the payment transaction as a string in full units. Incoming payments can be split amongst several invoices, which will result in a `applied_amount` less than the `original_amount`. Example: A $100.99 payment, of which $40.11 is applied to this invoice, will have an `original_amount` of `"100.99"`. |
| `applied_amount` | `String` | Required | The amount of the payment applied to this invoice. Incoming payments can be split amongst several invoices, which will result in a `applied_amount` less than the `original_amount`. Example: A $100.99 payment, of which $40.11 is applied to this invoice, will have an `applied_amount` of `"40.11"`. |
| `transaction_time` | `DateTime` | Required | The time the payment was applied, in ISO 8601 format, i.e. "2019-06-07T17:20:06Z" |
| `payment_method` | [`Payment Method Apple Pay \| Payment Method Bank Account \| Payment Method Credit Card \| Payment Method External \| Payment Method Paypal`](https://developers.maxio.com/http/advanced-billing-api/models/oneof-anyof-definitions/invoice-event-payment) | Required | A nested data structure detailing the method of payment |
| `transaction_id` | `Number` | Optional | The Chargify id of the original payment |
| `parent_invoice_number` | `Number` | Optional | - |
| `remaining_prepayment_amount` | `String` | Optional | - |
| `prepayment` | `Boolean` | Optional | - |
| `external` | `Boolean` | Optional | - |
# Example (as JSON)
```json
{
"consolidation_level": "child",
"memo": "memo8",
"original_amount": "original_amount8",
"applied_amount": "applied_amount4",
"transaction_time": "2016-03-13T12:52:32.123Z",
"payment_method": {
"type": "apple_pay"
},
"transaction_id": 196,
"parent_invoice_number": 174,
"remaining_prepayment_amount": "remaining_prepayment_amount6",
"prepayment": false,
"external": false
}
```
##### Attribute Error
Source: https://developers.maxio.com/http/advanced-billing-api/models/structures/attribute-error
# Fields
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `attribute` | `array` | Required | - |
# Example (as JSON)
```json
{
"attribute": [
"attribute6",
"attribute7"
]
}
```
##### Auto Resume
Source: https://developers.maxio.com/http/advanced-billing-api/models/structures/auto-resume
# Fields
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `automatically_resume_at` | `DateTime` | Optional | - |
# Example (as JSON)
```json
{
"automatically_resume_at": "2016-03-13T12:52:32.123Z"
}
```
##### Available Actions
Source: https://developers.maxio.com/http/advanced-billing-api/models/structures/available-actions
# Fields
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `send_email` | [`Send Email`](https://developers.maxio.com/http/advanced-billing-api/models/structures/send-email) | Optional | - |
# Example (as JSON)
```json
{
"send_email": {
"can_execute": false,
"url": "url0"
}
}
```
##### Bank Account Attributes
Source: https://developers.maxio.com/http/advanced-billing-api/models/structures/bank-account-attributes
# Fields
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `chargify_token` | `String` | Optional | - |
| `bank_name` | `String` | Optional | (Required when creating a subscription with ACH or GoCardless) The name of the bank where the customer’s account resides |
| `bank_routing_number` | `String` | Optional | (Required when creating a subscription with ACH; optional when creating a subscription with GoCardless). The routing number of the bank. It becomes bank_code while passing via GoCardless API. |
| `bank_account_number` | `String` | Optional | (Required when creating a subscription with ACH. Required when creating a subscription with GoCardless and bank_iban is blank) The customerʼs bank account number |
| `bank_account_type` | [`Bank Account Type`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/bank-account-type) | Optional | Defaults to checking |
| `bank_branch_code` | `String` | Optional | (Optional when creating a subscription with GoCardless) Branch code. Alternatively, an IBAN can be provided. |
| `bank_iban` | `String` | Optional | (Optional when creating a subscription with GoCardless). International Bank Account Number. Alternatively, local bank details can be provided. |
| `bank_account_holder_type` | [`Bank Account Holder Type`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/bank-account-holder-type) | Optional | Defaults to personal |
| `payment_type` | [`Payment Type`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/payment-type) | Optional | - |
| `current_vault` | [`Bank Account Vault`](https://developers.maxio.com/http/advanced-billing-api/models/enumerations/bank-account-vault) | Optional | The vault that stores the payment profile with the provided vault_token. Use `bogus` for testing. |
| `vault_token` | `String` | Optional | - |
| `customer_vault_token` | `String` | Optional | (only for Authorize.Net CIM storage or Square) The customerProfileId for the owner of the customerPaymentProfileId provided as the vault_token |
# Example (as JSON)
```json
{
"chargify_token": "chargify_token0",
"bank_name": "bank_name2",
"bank_routing_number": "bank_routing_number8",
"bank_account_number": "bank_account_number4",
"bank_account_type": "checking"
}
```
##### Bank Account Response
Source: https://developers.maxio.com/http/advanced-billing-api/models/structures/bank-account-response
# Fields
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `payment_profile` | [`Bank Account Payment Profile`](https://developers.maxio.com/http/advanced-billing-api/models/structures/bank-account-payment-profile) | Required | - |
# Example (as JSON)
```json
{
"payment_profile": {
"payment_type": "bank_account",
"verified": false,
"id": 44,
"first_name": "first_name4",
"last_name": "last_name2",
"customer_id": 82,
"current_vault": "authorizenet"
}
}
```
##### Bank Account Verification
Source: https://developers.maxio.com/http/advanced-billing-api/models/structures/bank-account-verification
# Fields
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `deposit_1_in_cents` | `Long` | Optional | - |
| `deposit_2_in_cents` | `Long` | Optional | - |
# Example (as JSON)
```json
{
"deposit_1_in_cents": 142,
"deposit_2_in_cents": 132
}
```
##### Bank Account Verification Request
Source: https://developers.maxio.com/http/advanced-billing-api/models/structures/bank-account-verification-request
# Fields
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `bank_account_verification` | [`Bank Account Verification`](https://developers.maxio.com/http/advanced-billing-api/models/structures/bank-account-verification) | Required | - |
# Example (as JSON)
```json
{
"bank_account_verification": {
"deposit_1_in_cents": 244,
"deposit_2_in_cents": 6
}
}
```
##### Base Refund Error
Source: https://developers.maxio.com/http/advanced-billing-api/models/structures/base-refund-error
# Fields
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `base` | `array