# Maxio Advanced Billing > 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](page:development-tools/client-libraries). 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](page:development-tools/client-libraries#make-your-first-maxio-advanced-billing-api-request). 5. Test the Advanced Billing [integrations](https://www.maxio.com/integrations). Next, you can explore [authentication methods](page:introduction/authentication), [basic concepts](page:introduction/basic-concepts/connected-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 Authentication - **Basic Authentication**: - Username: The username to use with basic authentication - Password: The password to use with basic authentication # Overview Landing Page
Integrate Maxio into your workflow Understand how we enable your subscription management workflow through these commonly used API endpoints
Subscriptions Learn more
Components Learn more
Allocations Learn more
Price Points Learn more
Events Learn more
Best-in-class tooling to get you up and running Explore our security, reliability, and building tools
99.9% uptime Maxio guarantees security and reliability to launch a world-class billing experience
Learn more
Ecosystem Advanced Billing has partnered with many SaaS solutions to help you manage your business.
Learn more
Security A winning combination of enterprise-grade security to protect your customers.
Learn more
Chargify.js Streamline your existing API-based workflows in Maxio's Advanced Billing module.
Learn more
Frequently Asked Questions
What is the application’s uptime SLA?
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 perfomance.
How many out-of-the-box webhooks do you support?
We currently support 33 out-of-the-box webhooks.
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 ## 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](page:development-tools/client-libraries). 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](page:development-tools/client-libraries#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](page:introduction/authentication), [basic concepts](page:introduction/basic-concepts/connected-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)`]($h/__auth_BasicAuth) ### 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 ## 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: - [Chargify API]($e/Subscriptions) - [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 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 you've mastered authentication, you should check out the following articles: - Managing [sites](page:introduction/basic-concepts/connected-sites) - Creating [products](page:introduction/basic-concepts/product-catalog#product) and how they control what you bill customers - Creating [subscriptions](page:introduction/basic-concepts/subscription-signup), (ie. signing up customers) # Sites ## Site Subdomains Learn how to use sites to organize your business and provide the setup necessary to interact with Advanced Billing via the API. If you need help after reading this, [let us know](page:help/getting-support) so we can help and also improve this documentation. --- When you are new to Advanced Billing, we will create your first site for you after you choose a currency. Sites are simply "containers" for your products, customers, and subscriptions. You can use Advanced Billing with just one site, although most merchants will want two sites at a minimum – one for **testing** and one for **production.** ### Site Access To manage your sites, [login to Advanced Billing](https://app.chargify.com/login) and view your sites. From here you can: - Create a new site - Go to any site dashboard - Clone any site (ie. Make a copy of the structure of a site, including: products, components, families, etc) - Edit any site (currency, name, date/time format, timezone, etc) - Delete any 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" then 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 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]($e/Sites/clearSite). --- ## What's next? After you've created a new site, you should check out the following articles: - [Products](page:introduction/basic-concepts/product-catalog#product) - [Subscriptions](page:introduction/basic-concepts/subscription-signup) # 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](page: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](page:introduction/basic-concepts/product-catalog#product-family) - Creating the [product](page:introduction/basic-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]($e/Product%20Families/createProductFamily) 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]($e/Product%20Families/createProductFamily) 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]($e/Products/createProduct) 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”, upsold features, or pay-per-use items. There are two basic concepts needed to use components that we will discuss: 1. [Creating](page:introduction/basic-concepts/product-catalog#creating-components) components 2. The [usage/allocation](page:introduction/basic-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]($e/Components/createMeteredComponent) ### 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 then you would add usage for 10 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: ie. 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]($e/Coupons/createCoupon). - Use a coupon when creating a new subscription [via the API]($e/Subscriptions/createSubscription). # Subscription Signup You can create signups (also called subscriptions) by signing up customers to products on your site. This guide focuses the basics on creating subscriptions, though Advanced Billing can almost handle any scenario using API integration. - Advanced Billing [signup methods](page:introduction/basic-concepts/subscription-signup#signup-methods) - The [payment methods](page:introduction/basic-concepts/subscription-signup#payment-methods) available for subscriptions - How to handle customers with [multiple subscriptions](page:introduction/basic-concepts/subscription-signup#multiple-subscriptions) - Component [quantities](page:introduction/basic-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](page:introduction/basic-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 [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](page:introduction/basic-concepts/subscription-signup#payment-methods) billing, payments are collected through a credit card or Automated Clearing House (ACH) details. > **Note:** > Use [Chargify.js]($e/development-tools/chargify-js-overview) 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]($e/Subscriptions/createSubscription). For advanced subscription creation scenarios, see [Advanced Subscription Creation Examples](page:introduction/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]($e/Subscriptions/createSubscription). ## 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](page:core-concepts/product-catalog#components). 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 change 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]($e/Subscriptions/updateSubscription) 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](page:introduction/basic-concepts/Signups#taxes). You can update the payment details via: - [Self-Service Pages](page:introduction/basic-concepts/subscription-signup#updating-via-self-service-pages) - [API](page:introduction/basic-concepts/subscription-signup#updating-via-api) - [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 the 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]($e/Payment%20Profiles/updatePaymentProfile) and [Update Subscription]($e/Subscriptions/updateSubscription)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]($e/Subscription%20Status/cancelSubscription). 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. # Tips and Best Practices > 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](page:development-tools/client-libraries#code-language-selection-and-sdk-access). > 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. Our merchants use our API for different purposes. API access is included on all plans at no charge because we believe that you are the owner of your data and you should never feel like your data is "locked up". However, because the API means there is little or no user-interaction, it can be very easy to create a program or routine that causes an unnecessarily high burden on our system. Even small accounts can generate huge numbers of expensive API requests by accident. In order to maintain a high quality of service for everyone, we ask that you be cautious when implementing your API integration to avoid run-away usage that is disproportionate to the size of your account. Here are some tips and best-practices to help keep both your site and ours running smoothly. ## Development If you’re having difficulty executing a request via our API, try the simplest thing and attempt your request via the curl command-line tool, as shown in the below example. Add the `--verbose` flag to your request to receive even more debugging information. Another handy tool is [Webhook.site](https://webhook.site/). You could send your request to their temporary URL instead of us to see visually what it is you’re sending, if you’re not sure. While you can certainly write your own code to interact with Advanced Billing, it's likely someone has already written code for your platform. ## Getting Subscription States You likely want to check if your customer has an active account, has cancelled, or is behind on his/her payments. The best approach is to keep a local cached copy of the subscription’s state in your own database. You can use [Webhooks]($e/Webhooks/createEndpoint) to keep up-to-date in near real-time on any changes that occur. This keeps your website up, reduces your coupling to Advanced Billing, and ensures both sites remain as fast as possible. Avoid querying Advanced Billing in-line as part of a customer’s request to your site. Doing so could result in: - Slowing down your own site while the customer waits for a check to Advanced Billing on every request. - If there is a network connectivity issue or in the unlikely event that Advanced Billing is down, your site will also break. - As you grow and your customers are more active, you will use up huge numbers of API requests that could result in being blocked because of our automatic abuse prevention. ## Synchronizing Your Database Normally, you would keep your local customer database in sync by using [Webhooks]($e/Webhooks/createEndpoint). But if you think your database has become out of sync with Advanced Billing, then using the API to check the state of all subscriptions may be the only way to ensure consistency. It’s perfectly okay to do this as needed. But it should generally only be relied upon in exceptional circumstances or for periodic reconciliation (usually no more than once a month). ## Reporting Usage When reporting component usage, avoid sending lots of tiny usage amounts. For example, if you charge by the minute for phone calls: - **Don’t** send in a usage for every minute or every phone call individually. - **Don’t** send all usage for all customers all at once. Spread it out or wait a short period of time between each request Instead: - **Do** send a usage report once a day with how much a customer used for the whole day. For more information on reporting component usage or allocations, see the specific section for the type of component used: - [API docs for reporting metered usage]($e/Subscription%20Components/createUsage) - [API docs for allocating quantity-based components]($e/Subscription%20Components/allocateComponent) ## Downloading Bulk Data Periodically exporting transaction, subscription, or customer data is a common use case. When possible, we recommend using 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. This can often be much faster and can significantly lower your API usage. ## Secure Applications It is NOT possible to make API requests directly from the customer's browser or device. Doing so would expose your API key on the client side, and anyone who has that key has full access to all of your Advanced Billing data. Instead, take care to tokenize sensitive information by using [Chargify.js](https://docs.maxio.com/hc/en-us/articles/38163190843789-Chargify-js-Overview), or a similar JavaScript library provided by your gateway, and then post the token and other information to your own server, from which you can make the API call to Advanced Billing. ### Troubleshooting If you attempt to make a Chargify 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. ``` This is an error message indicating that Cross-Origin Resource Sharing (CORS) is not enabled on the Advanced Billing server. ## Sync After creating and managing subscriptions, you might need a way for your application to know about the state of a customers subscription. This can be done either directly through the API or by Advanced Billing notifying your application using the handy [Webhooks](https://maxio.zendesk.com/hc/en-us/articles/24266143173901-Webhooks-Overview) feature. --- There are three basic methods of either allowing or notifying your application about the state of a customers subscription: - Using the [API]($e/Subscriptions/readSubscription) to retrieve subscription information - Recieving [webhooks](page:introduction/about-the-api/webhooks#receiving-a-webhook-notification) - Manually [export](https://maxio.zendesk.com/hc/en-us/articles/24285931839757-Exporting-Data#locating-exports) One of the easiest methods is just to have your application request the current state (or history) of a subscription using the API. This will provide the current state of the subscription at the time of the request. ### Subscription State To get the current state of a subscription, it's as simple as the following: HTTP GET https://{subdomain}.chargify.com/subscriptions/{subscription_id}.{format} You will receive all the current information about the subscription, including (but not limited to): - Subscription details (subscription state, creation, balance, next assessment date, cancellation information, etc). - Customer details - Payment details For more detailed information, see API documentation on [reading the subscription]($e/Subscriptions/readSubscription). ### Best Practices The following are some best practices that we would suggest regarding using API and how you synchronize your application with your Advanced Billing data: 1. Your application should not depend on another service to control access directly. Should your API call fail, for any reason, then your customer might not receive the best user experience depending on how you've implemented this. 2. Limit the direct calls to Advanced Billing if (and when) possible as there is a limit to how fast (and how often) the Chargify API will respond to very quick and numerous API calls. For more information, see [rate limits and blocks](page:introduction/about-the-api/error-handling). ## Large Imports We always enjoy (and appreciate) hearing about larger integrations ahead of time. If you’re planning on importing a large amount of data into Maxio via our API, we suggest sending a “heads up” to [support@maxio.com](mailto:support@maxio.com) so we can coordinate with you to ensure your import process goes smoothly. # 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 uses 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 provided, Advanced Billing uses that absolute date and displays it in the site’s time zone. See XXX for more information. ## 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 ## 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 params 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 ## 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 limit / seconds. Rather, we handle call limiting based on concurrency, and API calls can be requested at a max of 4 concurrent requests. This does not mean that only 4 requests are allowed per second - rather, 4 server threads / 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. | ![Concurrency Graphic](static/images/about-the-api/concurrency_graphic.jpg) | | --------------------------------------------------------------------------------------- | | **Diagram of concurrency-based rate limiting presuming a limit of 2 threads at a time** | ### Rate-based Blocks When doing 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 [contact support and open a support ticket](https://maxio.zendesk.com/hc/en-us/requests/new) so we can help describe what happened and why the request was blocked. ### Account-based Blocks There are a few scenarios that may end up in causing an API request to be blocked even with correct credentials. You can read about them [here](page:introduction/about-the-api/error-handling#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 in 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 and 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 ## 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 ## 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 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 re-try 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 re-try 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 re-try, 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 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]($e/Subscriptions/createSubscription) 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 custome fields that store information in a customer or subscription resource in Advanced Billing. Metafeilds 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]($e/Custom%20Fields/createMetafields). ## 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]($e/Custom%20Fields/createMetafields). 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]($e/Subscription%20Notes/createSubscriptionNote). # 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](page:introduction/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](page:introduction/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/pair value 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]($e/Webhooks/createEndpoint). You can enable or disable webhooks as needed. Each webhook includes: - A URL - A set of [events](page:introduction/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 through 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]($e/Webhooks/replayWebhooks) 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 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 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. ## 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]($e/Webhooks/listWebhooks) 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} ``` ### 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} ``` ### 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_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 statementat 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. # This is a Guided Walkthrough File This is the starter content # This is a Guided Walkthrough File This is the starter content # This is a Guided Walkthrough File This is the starter content # Using the Developer Portal Maxio Advanced Billing provides an HTTP-based API that conforms to the principles of REST. You can use the Developer Portal to test API requests with your sandbox setup. Maxio also offers Advanced Billing SDKs to support the following community tech stacks: - [Python](https://pypi.org/project/maxio-advanced-billing-sdk/) - [Ruby](https://rubygems.org/gems/maxio-advanced-billing-sdk/) - [PHP](https://packagist.org/packages/maxio/advanced-billing-sdk) - [C#/.NET](https://www.nuget.org/packages/Maxio.AdvancedBillingSdk/) - [Typescript](https://www.npmjs.com/package/@maxio-com/advanced-billing-sdk/) - [Java](https://central.sonatype.com/artifact/com.maxio/advanced-billing-sdk) - [Go](https://pkg.go.dev/github.com/maxio-com/ab-golang-sdk) This page walks you through how to use the developer portal to make API requests and [access the SDKs](page:development-tools/client-libraries#code-language-selection-and-sdk-access). ## Make your first Maxio Advanced Billing API request Follow these steps to make a simple request to get a list of Sites in your sandbox. ### Step 1: Set up your sandbox [Sign-up](https://app.chargify.com/signup/maxio-billing-sandbox) for your [test site](https://maxio.zendesk.com/hc/en-us/articles/24250712113165-Testing-Overview). ### Step 2: Get an API key [Configure your Advanced Billing API credentials](https://maxio.zendesk.com/hc/en-us/articles/24294819360525-API-Keys). You'll use the generated API key to authenticate requests. ### Step 3: Configure your first API request Use the cURL command-line tool to make an HTTP [Get Site]($e/Sites/readSite) request. 1. Copy the command below into your terminal. 2. Replace "your-maxio-ab-subdomain" with the subdomain of your Maxio Advanced Billing sandbox. 3. Replace "your-api-key" with the API key you configured in Step 2. This is your `BasicAuthUserName`, and for testing your `BasicAuthPassword` is x. See [Authentication](page:introduction/authentication) for more information. 4. Run the command. ``` curl -X GET \ --url 'https://"your-maxio-ab-subdomain".chargify.com/site.json' \ -H 'Accept: application/json' \ -u '"your-api-key":x' ``` ### Step 4: Validate the response The Maxio API returns JSON responses similar to the one shown. JSON is returned as the primary and recommended format. XML is also provided as a backwards compatible option for merchants who require it. ```JSON { "site": { "id": 00000, "name": "test-b2b-site", "subdomain": "test-acme-clone", "currency": "USD", "seller_id": 00000, "non_primary_currencies": ["BRL"], "relationship_invoicing_enabled": true, "customer_hierarchy_enabled": false, "whopays_enabled": false, "whopays_default_payer": "self-ungrouped", "default_payment_collection_method": "automatic", "organization_address": { "street": null, "line2": null, "city": null, "state": null, "zip": null, "country": null, "name": "Your Org Name", "phone": null, }, "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, }, } ``` ## Test endpoints in the Developer Portal Now that you've made a simple request using the command line, you have the configuration information (an API key and subdomain) to test endpoints directly in the Developer Portal. Creating a customer is a good place to start. The following steps show an HTTP formatted API request to create a customer. You can [select a coding language](page:development-tools/client-libraries#code-language-selection-and-sdk-access) to view the examples in the language for your choice. 1. Open the [Create Customer]($e/Customers/createCustomer) reference page in a new window or tab. 2. To configure the subdomain for the API requests, click the **API Configurations** dropdown and edit the **Base URL** with the subdomain for your sandbox site.
![Configure window](static/images/about-the-api/configure.png)
3. To configure [authentication](page:introduction/authentication), click the **Authentication** dropdown and enter the the API key for your sandbox site in `BasicAuthUserName`. Enter _X_ in `BasicAuthPassword`.
![BasicAuth dropdown](static/images/about-the-api/basic-auth-dropdown.png)
4. View the customer parameters in the **API Code Playground** section. You can leave the default example parameters or change them. The request is updated with your changes.
![API Code Playground](static/images/about-the-api/code-playground.png)
5. Once the parameters are set, click **TRY IT OUT**. You should get a response in the format documented in the **Responses** section.
![Configure window](static/images/about-the-api/response.png)
> **Note:** > You can expand the Request and Response window for easier viewing: >
> ![Expand option](static/images/about-the-api/expand.png) >
> You can also copy the request to run in your local terminal, or developer environment if you have selected a coding language: >
> ![Copy option](static/images/about-the-api/copy.png) >
>
## Code language selection and SDK access The developer portal allows you to view the documentation examples in the code language of your choice and access an SDK for your selected language. 1. Select a language from the language selector located at the top right of the portal. The documentation examples throughout the portal are updated to reflect the selection.
![Language selector](static/images/about-the-api/dev-portal-lang-selector-ex.png)
2. To view SDK access options, click **Get SDK**.
![Get SDK](static/images/about-the-api/dev-portal-get-sdk.png)
3. To install the SDK you can run the install command, or click the link to the package manager where you can download and install the SDK. ## What's next? Now that you've learned the basics, try these detailed walkthroughs to learn key concepts of Advanced Billing and the API: - Managing [sites](page:introduction/basic-concepts/connected-sites). - Creating [products](page:introduction/basic-concepts/product-catalog#product) and how they control what you bill customers. - Creating [subscriptions](page:introduction/basic-concepts/subscription-signup), (ie. signing up customers). # Chargify.js Chargify.js is a powerful tool that can be used to streamline your existing API-based workflows in Advanced Billing. Chargify.js can be used to easily construct signup and payment profile updates on your existing sites. For complete details on configuration, examples, and release history, see the [product documentation articles](https://docs.maxio.com/hc/en-us/articles/38163190843789-Chargify-js-Overview#chargify-js-overview-0-0). # Overview ## Embeddable Components for Self-Service Subscription Management Embeddable Components (also known as Reusable Components) are self-service, headless components that can be used by Developers to setup and customize a subscription journey with in-app experiences. This is done through the delivery of a typescript Software Development Kit (SDK). This set of front-end interface tools is geared to enhance both the Developer Experience (DX) and the Subscriber end-user experience. ## Technical Details Under the Hood The Embeddable Components module doesn't directly communicate with the Maxio Advanced Billing API. Rather, it leverages the **Embeddable Components Backend** (ECB) to handle all frontend requests, perform authentication, and transform the data into a format that can be consumed by the Advanced Billing API. The responses are then mapped back to the Embeddable Components module, in suitable form. ![Technical Details Under The Hood](static/images/embeddable-components/overview/technical-details-under-the-hood.png) ### Communication Between Frontend and the Backend All requests made by the Embeddable Components come from a web browser application provided by the Merchant. To authenticate with the Embeddable Components Backend, Merchants must provide a JSON Web Token (JWT) signed with the **Token Sign in Key**, which is generated when launching the integration. This generated sign-in key is Base64 encoded. The token should contain a subject claim equal to the Maxio customer reference (which maps the Merchant's internal user representation to the customer reference at Maxio). The Embeddable Components Backend verifies the token signature, using the Token Sign in Key. This allows requests to be executed on behalf of a specific user while maintaining security. The token's claim issued at date is validated using the site's maximum token expiration time, which is currently one hour. This can be lowered using the `exp` claim, _but it cannot be longer than one hour_. It's possible to add a _second_ Token Sign in Key to allow for key rotation without downtime. The Embeddable Components Backend would accept both keys to verify the token signature. The Embeddable Components Backend also uses Cross-Origin Resource Sharing (CORS) to filter and match requests. Merchants can configure a set of Origin patterns that specify the sites where they want to embed the components. When a request is received by the backend, it first filters the provided Origin against all the patterns stored in the database. It then proceeds to the next step of JWT authorization for sites that only match the filtered patterns. The domain patterns can either be exact domains (for example, keen.io, sub.keen.io) or patterns that use **wildcards** ( like *keen.io or *n.io). > The wildcard asterisk (`*`) must be the first character and two segments must be provided. The wildcard > cannot match the entire first segment. For example, `*.com` is not allowed. ### Authentication Endpoint The Authentication Endpoint is a minimal backend component that merchants need to provide for their Embeddable Components. This **endpoint** is used by the components to fetch the token required to sign requests to the Embeddable Components Backend using the Merchant Application backend for the authenticated user. Merchants need to specify the URL of this endpoint in the components' frontend initialization code so that the components know where to fetch the token from. The endpoint should return a JSON object with the `token` field containing the signed token value. For example: ```json { "token": "eyJg…" } ``` The token should be signed using the Base64 decoded Token Sign in Key. The subject of the token should be set to the Maxio customer reference of a customer referring to an authenticated user in the Merchant's application. The iat (issued at) claim must be included in the token. Token payload: - **sub** (subject)
_Required string_. Matches the customer reference in Advanced Billing. - **iat** (issued at)
_Required timestamp_. Used for token expiration validation. By default, the token is rejected if it's older than one hour. - **exp** (expiration)
_Optional timestamp._ Used for token expiration validation. Due to security reasons, you can only decrease the default token expiration to less than an hour. The token is rejected if `exp` is set to a time that is greater than one hour. For Authentication endpoint examples, see the [Code Samples](https://maxio.zendesk.com/hc/en-us/articles/24294708528653) article. ## Why use Embeddable Components Embeddable Components allow Sellers and decision-makers to create custom subscriber experiences that meet the specific needs of the end-user, which are helpful for self-servicing Subscriptions in a product-led strategy approach. They are configured within your billing portal configuration settings. You can enable or disable functionalities through Advanced Billing or through code customization. Embeddable Components are highly configurable and can be styled using dynamic or static code to match a company's brand or the website's look-and-feel. Embeddable Components are categorized into three distinct functions: - **Billing History**
Allows viewing, sorting and filtering of Customer Invoices. - **Subscription Manager**
Enables the end-customer to self-serve and manage the subscription. (including, but not limited to, subscription details, payment profiles, product migrations, coupon application, and so forth). - **Customer Details**
Allows viewing and editing of Customer contact details, address, and custom fields. # Configurations ## Step 1: Enable and Setup Embeddable Components in Advanced Billing > _For **Early Access**, contact the Maxio Support Team for assistance._ First, you will need to identify the domain where you will host the website and generate a sign-in key for authenticated access to the host server. > _The localhost domain will need to be added to develop the integration on a local machine. Once development is done, > remove the localhost domain._ 1. From Advanced Billing, go to **Config > Integrations > Embeddable Components**.
![Enable Components Integration](static/images/embeddable-components/configurations/enable-components-integration.png) 2. Enter a **Domain** and click **Enable Maxio Components**.
This automatically generates a Base64 encoded Token Sign in Key.
![Token Sign in Key](static/images/embeddable-components/configurations/token-sign-in-key.png) 3. Copy and store this token for later access.
Should you lose this key, you will need to generate a new one. 4. Go to **Config** > **Settings** > **Billing Portal** and click **Enabled for this site**.
![Enable Billing Portal Setting](static/images/embeddable-components/configurations/enable-billing-portal-setting.png) 5. Select which **Features** will be available to your Customers. > Some unchecked Advanced Billing configurations are not needed for Embeddable Components. For example, **Remove > Maxio Advanced Billing Logo** does not have influence on your self-hosted application. Others, like **Allow > Plan Changes** will have an impact on your self-hosted application. The Seller must make sure the necessary > features > are enabled. 6. Click **Save**. ## Step 2: Pull the Components from Node Packaged Modules (NPM) Package Manager NPM is the main package manager for [node.js](https://nodejs.org/en), the JavaScript runtime environment. > _Installing node.js also installs npm._ 1. With node.js and npm installed, go to [nmpjs.com](https://www.npmjs.com/) and search for the "maxio" packages or click [this link](https://www.npmjs.com/package/@maxio-com/self-service) to go directly to the self-service package. > _You will also need node.js installed to run the vue.js or react.js examples._ 2. Select the **@maxio-com/self-service** package.
![self-service npm package](static/images/embeddable-components/configurations/self-service-npm-package-1.png)
This opens the "Headless Billing Portal", which covers installation instructions, points to vue.js and react.js examples, and goes through repository setup and use.
![self-service npm package](static/images/embeddable-components/configurations/self-service-npm-package-2.png) 3. Create a project directory, locally on your machine. 4. Open a command window/terminal and navigate to the local project directory you just created. 5. To download and install the dependencies, run the given npm CLI command:
`npm install @maxio-com/self-service`
![npm install terminal](static/images/embeddable-components/configurations/npm-install-terminal.png)
A successful installation creates the **node_modules** directory in your local project folder. In this directory, you will find the `@maxio-com\self-service` directory.
![npm modules directory](static/images/embeddable-components/configurations/node-modules-directory.png) ## Step 3: Use the Examples To start using these components right away, use the out-of-the-box Vue or React examples provided. > _The following set-up example uses vue.js on localhost._ ### Setting up the Vue.js Self-Service Example 1. From **npmjs.com** > **Headless Billing Portal** page > **Installation and usage**, go to #4 Examples and click the **vue-self-service-example** link.
![Vue.js Self-Service Example](static/images/embeddable-components/configurations/vue-js-self-service-example.png)
This takes you to the maxio-com vue.js example git repository. 2. Clone the repository to your local environment:
`git clone https://github.com/maxio-com/vue-self-service-example` 3. Open the cloned repository and install the dependencies:
`pnpm install`
or
`npm install` 4. Run the development server (respectively):
`pnpm run dev`
or
`npm run dev` ### Viewing the Example Application To view the Embeddable Components from an example application, open http://localhost:3000/. ![Embeddable Components localhost](static/images/embeddable-components/configurations/embeddable-components-localhost.png) ### Configuring the Example 1. From your editor, go to **src** > **components**, and open **BillingHistory.vue**. 2. Edit the following options: | **Option** | **Description** | **Example** | | :---------------- | :------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------- | | itemsPerPage | Sets the number of items to list per page. | itemsPerPage: 10, | | paginationVariant | Sets the pagination type:
- simple (infinite scroll)
- pages (page pagination) | paginationVariant: 'simple', | | enableFiltering | Enable (true)/disable (false) billing history filtering. | enableFiltering: true, | | visibleColumns | Set the array for the billing history fields (columns) to show on the table. | visibleColumns: [
"invoice_number",
"issue_date",
"due_date",
"total_amount",
"amount_due",
"status"
] | _Example of Billing History Component options:_
![Example of Billing History Component options](static/images/embeddable-components/configurations/example-of-billing-history-component-options.png) 3. Go back to the example application in your browser, open the **Billing History** page, http://localhost:3000/billing-history, and note the changes you made. 4. Next, open **CustomerDetails.vue** and edit the following options: | **Option** | **Description** | **Example** | | :------------------------ | :------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | customerDataVisibleFields | Set the array that contains the customer data fields visible to the user. | customerDataVisibleFields: [
"address",
"address2",
"city",
"state",
"zip",
"firsName",
"lastName",
"email",
"ccEmails",
"organization",
"vatNumber",
"phoneNumber",
"country"
] | _Example of Customer Details Component options:_
![Example of Customer Details Component options](static/images/embeddable-components/configurations/example-of-customer-details-component-options.png) 5. Finally, open **SubscrjptionManager.vue** and edit the following options: | **Option** | **Description** | **Example** | | ---------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | | allocationFlow | Set how component allocation flow is presented:
- modal
- page | | | subscription | Subscription settings object:
- details
Set how subscription details are presented. | | | paymentProfileEditFlow | Set which form payment profile edit flow is presented.
- modal
- page | | | paymentProfileRequiredFields | Set the array that contains the _required_ payment profile address fields. | | | addressFields | Set the array that contains the payment profile address fields visible to the user. | addressfields: [
"address",
"address2",
"city",
"state",
"zip",
"country"
] | _Example of Subscription Manager Component options:_
![Example of Customer Details Component options](static/images/embeddable-components/configurations/example-of-subscription-manager-component-options.png) ## Step 4: Optional Configurations ### Use as a Standalone Library from CDN To use Embeddable Components as a standalone library from a Content Delivery Network (CDN) do the following. 1. Add this script that points to the library in CDN to your page:
`` 2. Initialize Components. ```javascript const factory = new window.Maxio.Components(options); // Render Billing History to the document.body element let element = factory.create("billing-history"); element.render(document.body); ``` 3. Your local environment should match the domain you configured (add localhost if you want to run it locally).
Example: ```html ``` ### Additional Advanced Billing Configurations #### Custom Fields (Metafields) Merchants can set the level of access for each custom field (or metafield) to be viewable and editable for customers using Embeddable Components. These settings apply to both subscription- and customer-level custom fields. The new scopes are named **public_show** and **public_edit**, respectively. Setting 'public_show' to '1' makes the custom field visible in the Embeddable Components application, while setting 'public_edit' to '1' makes it editable. > _Editing and viewing these metafields settings are currently only supported using the API._ #### Individual Component Configuration Apart from the global components update setting, each individual component has an additional property controlling whether it can be updated using a billing portal. This property option is also respected by Embeddable Components. Do the following to enable the Billing Portal for a component. 1. From Advanced Billing, go to **Catalog** > **Products**. 2. Select the **Products family** to which the component belongs. 3. Click the **Components** tab.
![Components tab](static/images/embeddable-components/configurations/components-tab.png) 4. Choose a component. 5. Scroll to the bottom of the component page, and for **Advanced Options** click **Edit**. 6. Enable the **Billing Portal** option.
![Enable Billing Portal option](static/images/embeddable-components/configurations/enable-billing-portal-option.png) # Version History The latest version of `Embeddable Components` is available at the following url: [@maxio-com/self-service](https://www.npmjs.com/package/@maxio-com/self-service) ## 2024-12-02 (1.15.0 Latest) Improved subscription management by ensuring expired credit cards are linked to the active payment method. - [feature] Exclude active cc from rest - [feature] Move expired credit card to active payment method ## 2024-11-20 (1.14.1) Fixed a typo in messaging on the configure subscription form. - [bugfix] Correct wording on configure subscription page ## 2024-11-13 (1.14.0) Added versioning for translations while maintaining backward compatibility. Introduced versioned URLs. - [feature] Translations versioning ## 2024-11-13 (1.13.3) Improved credit card validation form to properly highlight invalid fields. - [bugfix] Add expiration value to CreditCardPCIFields - [bugfix] Add missing field in createFieldsConfig - [bugfix] Change use of expiration value - [bugfix] Fix state select field - [bugfix] Get rid of selectedCountry state - [bugfix] Handle editing address - [bugfix] Make card expiration and card number always required ## 2024-11-06 (1.13.2) Improved payment profile functionality by ensuring dropdowns stay open until an option is selected, and allowing forms to close when clicking the close button or outside the window. - [bugfix] Close select when user clicks outside element - [bugfix] Make solution global - [bugfix] Payment profile defects ## 2024-11-05 (1.13.1) Fixed an issue where expired credit cards were not correctly marked as "expired." - [bugfix] Reflect expired flag ## 2024-10-25 (1.13.0) Ensured that the subscription is immediately active after reactivation, regardless of whether the payment profile is new, expired, or up-to-date, providing a seamless experience for users. - [feature] Add card and active right away - [feature] Add dynamic content of createPaymentProfile - [feature] Add new reactivate subscription flow - [feature] Update case with up-to-date payment profile - [feature] Update subscription when add payment profile ## 2024-10-16 (1.12.1) Added missing currency property for Subscription resource. - [bugfix] Add missing prop - [bugfix] Currency of subscriptions price ## 2024-10-11 (1.12.0) Resolved problems with the form autocomplete feature to ensure smoother user input. - [bugfix] Add missing cvv - [feature] Make autocomplete disable ## 2024-08-14 (1.11.6) Added Subscription components settings. - [bugfix] usedInBilling prop is null ## 2024-07-30 (1.11.5) Made i18nSettings properties default. - [bugfix] Add new key for button - [bugfix] Defaults for i18nSettings - [bugfix] Make i18nSettings properties default ## 2024-07-30 (1.11.4) Added i18nSettings properties to load default translations. Bug fixes and improvements. - [bugfix] Added DEFAULT_LOAD_PATH - [bugfix] Broken tests - [bugfix] Change content of cancel button - [bugfix] Change incorrect - [bugfix] Change to close - [bugfix] Define loadPath for i18n - [bugfix] Fix nextBillingAmount price after adding a coupon - [bugfix] Fixed CouponErrorCodes import - [bugfix] Issue with wrong refreshing next billing amount field - [bugfix] Issues with displaying subscriptionDetails - [bugfix] Remove instance of deleted file - [bugfix] Remove unnecessary useCoupons hook - [bugfix] Remove unused file - [bugfix] Translations - [bugfix] Typo - [bugfix] Use capital letter - [bugfix] Use static en in default_load_path ## 2024-07-12 (1.11.3) Fixed total price value being displayed for Subscription resource. - [bugfix] Change total price value ## 2024-07-02 (1.11.2) - [bugfix] Include plan_change_scheduled to the nextBillingAmount ## 2024-06-28 (1.11.1) - [bugfix] Change reactive subscription error message ## 2024-06-27 (1.11.0) Updated the Embeddable Components to respect billing portal settings. The discount section is now hidden when applying coupons is disabled. - [feature] Hide discount section when coupons setting is false ## 2024-06-26 (1.10.1) Added a mechanism for fetching and handling subscription details in the app.
Introduced a new coupons prop to render coupon data in the Subscription component.
Implemented a custom hook `useSubscriptionDetailsService` for managing subscription details retrieval.
Updated test cases with `subscriptionDetails` constant for simulating subscription detail responses.
Enhanced API-related configurations and mock setups in SubscriptionContainer tests. - [bugfix] Fixed state result after fetch subscription details - [bugfix] invalid-billing-amount ## 2024-06-03 (1.10.0) Improvement in session manager to refresh auth token if `exp` claim is missing - [bugfix] Set properly api url and request headers - [feature] Handle refresh token if exp date is missing ## 2024-05-22 (1.9.6) - [bugfix] Update Content-Type header ## 2024-04-29 (1.9.5) - [bugfix] Extend SessionManager to include async headers hook # Getting Help and Support Access The Maxio Advanced Billing API, while considered stable, is continually being improved. If you have issues integrating with the API or questions regarding the documentation, there are quite a few options to help you get the answers you need: - [Read the developer docs](page:introduction/landing.html) - [Search the product documentation](https://maxio.zendesk.com/hc/en-us#availability) - [Contact support](https://docs.maxio.com/hc/en-us/articles/36005349562765-Contacting-Support) - [Open a support ticket](https://maxio.zendesk.com/hc/en-us/requests/new) - [Contact the sales team](mailto:sales@maxio.com) # 2025 Announcements ## Improved Configurations UX on endpoint pages Configurations to Try Out API calls are now conveniently located in a new section, allowing you to set up your environment, subdomain and credentials all in one place. ![Configuration section dropdown](static/images/announcements/config-section.png) You can view release information on the package manager for a client library: - [Python](https://pypi.org/project/maxio-advanced-billing-sdk/) - [Ruby](https://rubygems.org/gems/maxio-advanced-billing-sdk/) - [PHP](https://packagist.org/packages/maxio/advanced-billing-sdk) - [C#/.NET](https://www.nuget.org/packages/Maxio.AdvancedBillingSdk/) - [Typescript](https://www.npmjs.com/package/@maxio-com/advanced-billing-sdk/) - [Java](https://central.sonatype.com/artifact/com.maxio/advanced-billing-sdk) - [Go](https://pkg.go.dev/github.com/maxio-com/ab-golang-sdk) Or you can visit the client library's release page in source control for release details: ## December SDK Release Notes - C#/.Net: https://github.com/maxio-com/ab-dotnet-sdk/releases/tag/8.0.0 - Go: https://github.com/maxio-com/ab-golang-sdk/releases/tag/v0.8.0 - PHP: https://github.com/maxio-com/ab-php-sdk/releases/tag/8.0.0 - Python: https://github.com/maxio-com/ab-python-sdk/releases/tag/8.0.0 - Java: https://github.com/maxio-com/ab-java-sdk/releases/tag/8.0.0 - Ruby: https://github.com/maxio-com/ab-ruby-sdk/releases/tag/8.0.0 - Typescript: https://github.com/maxio-com/ab-typescript-sdk/releases/tag/8.0.0 ## September SDK Release Notes - C#/.Net:https://github.com/maxio-com/ab-dotnet-sdk/releases/tag/7.0.1 - Go: https://github.com/maxio-com/ab-golang-sdk/releases/tag/v0.7.1 - PHP: https://github.com/maxio-com/ab-php-sdk/releases/tag/7.0.1 - Python: https://github.com/maxio-com/ab-python-sdk/releases/tag/7.0.1 - Java:https://github.com/maxio-com/ab-java-sdk/releases/tag/7.0.1 - Ruby:https://github.com/maxio-com/ab-ruby-sdk/releases/tag/7.0.1 - Typescript: https://github.com/maxio-com/ab-typescript-sdk/releases/tag/7.0.1 ## July SDK Release Notes - C#/.Net:https://github.com/maxio-com/ab-dotnet-sdk/releases/tag/7.0.0 - Go: https://github.com/maxio-com/ab-golang-sdk/releases/tag/v0.7.0 - PHP: https://github.com/maxio-com/ab-php-sdk/releases/tag/7.0.0 - Python: https://github.com/maxio-com/ab-python-sdk/releases/tag/7.0.0 - Java:https://github.com/maxio-com/ab-java-sdk/releases/tag/7.0.0 - Ruby:https://github.com/maxio-com/ab-ruby-sdk/releases/tag/7.0.0 - Typescript: https://github.com/maxio-com/ab-typescript-sdk/releases/tag/7.0.0 ## January SDK Release Notes - C#/.Net: https://github.com/maxio-com/ab-dotnet-sdk/releases/tag/6.1.0 - Go: https://github.com/maxio-com/ab-golang-sdk/releases/tag/v0.6.0 - PHP: https://github.com/maxio-com/ab-php-sdk/releases/tag/6.1.0 - Python: https://github.com/maxio-com/ab-python-sdk/releases/tag/6.1.0 - Java: https://github.com/maxio-com/ab-java-sdk/releases/tag/6.1.0 - Ruby: https://github.com/maxio-com/ab-ruby-sdk/releases/tag/6.1.0 - Typescript: https://github.com/maxio-com/ab-typescript-sdk/releases/tag/6.1.0 # 2024 Announcements You can view release information on the package manager for a client library: - [Python](https://pypi.org/project/maxio-advanced-billing-sdk/) - [Ruby](https://rubygems.org/gems/maxio-advanced-billing-sdk/) - [PHP](https://packagist.org/packages/maxio/advanced-billing-sdk) - [C#/.NET](https://www.nuget.org/packages/Maxio.AdvancedBillingSdk/) - [Typescript](https://www.npmjs.com/package/@maxio-com/advanced-billing-sdk/) - [Java](https://central.sonatype.com/artifact/com.maxio/advanced-billing-sdk) - [Go](https://pkg.go.dev/github.com/maxio-com/ab-golang-sdk) Or you can visit the client library's release page in source control for release details: ## December SDK Release Notes - C#/.Net: https://github.com/maxio-com/ab-dotnet-sdk/releases/tag/6.0.0 - Go: https://github.com/maxio-com/ab-golang-sdk/releases/tag/v0.5.0 - PHP: https://github.com/maxio-com/ab-php-sdk/releases/tag/6.0.0 - Python: https://github.com/maxio-com/ab-python-sdk/releases/tag/6.0.0 - Java: https://github.com/maxio-com/ab-java-sdk/releases/tag/6.0.0 - Ruby: https://github.com/maxio-com/ab-ruby-sdk/releases/tag/6.0.0 - Typescript: https://github.com/maxio-com/ab-typescript-sdk/releases/tag/6.0.1 & https://github.com/maxio-com/ab-typescript-sdk/releases/tag/6.0.0 ## October SDK Release Notes - C#/.Net: https://github.com/maxio-com/ab-dotnet-sdk/releases/tag/5.2.0 - Go: https://github.com/maxio-com/ab-golang-sdk/releases/tag/v0.4.2 - PHP: https://github.com/maxio-com/ab-php-sdk/releases/tag/5.2.0 - Python: https://github.com/maxio-com/ab-python-sdk/releases/tag/5.2.0 - Java: https://github.com/maxio-com/ab-java-sdk/releases/tag/5.2.0 - Ruby: https://github.com/maxio-com/ab-ruby-sdk/releases/tag/5.2.0 - Typescript: https://github.com/maxio-com/ab-typescript-sdk/releases/tag/5.2.0 ## September SDK Release Notes - C#/.Net: https://github.com/maxio-com/ab-dotnet-sdk/releases/tag/5.1.0 - Go: https://github.com/maxio-com/ab-golang-sdk/releases/tag/v0.4.1 - PHP: https://github.com/maxio-com/ab-php-sdk/releases/tag/5.1.0 - Python: https://github.com/maxio-com/ab-python-sdk/releases/tag/5.1.0 & https://github.com/maxio-com/ab-python-sdk/releases/tag/5.0.1 - Java: https://github.com/maxio-com/ab-java-sdk/releases/tag/5.1.0 - Ruby: https://github.com/maxio-com/ab-ruby-sdk/releases/tag/5.1.0 - Typescript: https://github.com/maxio-com/ab-typescript-sdk/releases/tag/5.1.0 ## August SDK Release Notes - C#/.Net: https://github.com/maxio-com/ab-dotnet-sdk/releases/tag/5.0.0 - Go: https://github.com/maxio-com/ab-golang-sdk/releases/tag/v0.4.0 - PHP: https://github.com/maxio-com/ab-php-sdk/releases/tag/5.0.0 - Python: https://github.com/maxio-com/ab-python-sdk/releases/tag/5.0.0 - Java: https://github.com/maxio-com/ab-java-sdk/releases/tag/5.0.0 - Ruby: https://github.com/maxio-com/ab-ruby-sdk/releases/tag/5.0.0 - Typescript: https://github.com/maxio-com/ab-typescript-sdk/releases/tag/5.0.0 ## July SDK Release Notes - C#/.Net: https://github.com/maxio-com/ab-dotnet-sdk/releases/tag/4.0.0 - Go: https://github.com/maxio-com/ab-golang-sdk/releases/tag/v0.3.0 - PHP: https://github.com/maxio-com/ab-php-sdk/releases/tag/4.0.0 - Python: https://github.com/maxio-com/ab-python-sdk/releases/tag/4.0.0 - Java: https://github.com/maxio-com/ab-java-sdk/releases/tag/4.0.0 - Ruby: https://github.com/maxio-com/ab-ruby-sdk/releases/tag/4.0.0 - Typescript: https://github.com/maxio-com/ab-typescript-sdk/releases/tag/4.0.0 ## June SDK Release Notes - C#/.Net: https://github.com/maxio-com/ab-dotnet-sdk/releases/tag/3.0.0 - Go: https://github.com/maxio-com/ab-golang-sdk/releases/tag/v0.2.1 & https://github.com/maxio-com/ab-golang-sdk/releases/tag/v0.2.0 - PHP: https://github.com/maxio-com/ab-php-sdk/releases/tag/3.0.0 - Python: https://github.com/maxio-com/ab-python-sdk/releases/tag/3.0.1 & https://github.com/maxio-com/ab-python-sdk/releases/tag/3.0.0 - Java: https://github.com/maxio-com/ab-java-sdk/releases/tag/3.0.0 - Ruby: https://github.com/maxio-com/ab-ruby-sdk/releases/tag/3.0.0 - Typescript: https://github.com/maxio-com/ab-typescript-sdk/releases/tag/3.0.0 ## March SDK Release Notes - C#/.Net: https://github.com/maxio-com/ab-dotnet-sdk/releases/tag/2.0.0 - Go: https://github.com/maxio-com/ab-golang-sdk/releases/tag/v0.1.0 % https://github.com/maxio-com/ab-golang-sdk/releases/tag/v1.0.1-alpha.1 - PHP: https://github.com/maxio-com/ab-php-sdk/releases/tag/2.0.0 - Python: https://github.com/maxio-com/ab-python-sdk/releases/tag/2.0.0 - Java: https://github.com/maxio-com/ab-java-sdk/releases/tag/2.0.0 - Ruby: https://github.com/maxio-com/ab-ruby-sdk/releases/tag/2.0.0 - Typescript: https://github.com/maxio-com/ab-typescript-sdk/releases/tag/2.0.0 ## February Announcement and SDK Release Notes Starting Feb 2024, Maxio offers Advanced Billing-managed SDKs to support the following community tech stacks: - [Python](https://pypi.org/project/maxio-advanced-billing-sdk/) - [Ruby](https://rubygems.org/gems/maxio-advanced-billing-sdk/) - [PHP](https://packagist.org/packages/maxio/advanced-billing-sdk) - [C#/.NET](https://www.nuget.org/packages/Maxio.AdvancedBillingSdk/) - [Typescript](https://www.npmjs.com/package/@maxio-com/advanced-billing-sdk/) - [Java](https://central.sonatype.com/artifact/com.maxio/advanced-billing-sdk) - [Go (Beta)](https://pkg.go.dev/github.com/maxio-com/ab-golang-sdk@v0.6.0) Maxio's managed SDKs are a commitment to evolve and remove the friction in the Developer Experience (DX). We are excited to announce that with these Software Development Kits (SDKs), sellers can extend Maxio’s functionality to meet the desired level of integration. Decision-makers will be empowered to run a 15-minute evaluation. Release notes: - C#/.Net: https://github.com/maxio-com/ab-dotnet-sdk/releases/tag/1.0.0 - Go: https://github.com/maxio-com/ab-golang-sdk/releases/tag/v1.0.0-alpha.1 - PHP: https://github.com/maxio-com/ab-php-sdk/releases/tag/1.0.0 - Python: https://github.com/maxio-com/ab-python-sdk/releases/tag/1.0.0 - Java: https://github.com/maxio-com/ab-java-sdk/releases/tag/1.0.0 - Ruby: https://github.com/maxio-com/ab-ruby-sdk/releases/tag/1.0.0 - Typescript: https://github.com/maxio-com/ab-typescript-sdk/releases/tag/1.0.0 # 2023 Announcements ## 2023-05-18 Change in the refund_success and refund_failure webhooks Starting May 18th, 2023, Maxio will undergo a change in the refund_success and refund_failure webhooks. The subscription_id parameter will no longer be supported. Instead, sellers can access the subscription ID through the subscription nested hash: subscription => { id => 1}. Please note that existing sites are unaffected by this change. ## 2023-05-16 Enable Chargify.js Security Token by default As of May 16th, 2023, all new Sellers will have enabled Chargify.js Security Token by default. Additionally, merchants will not be able to change the related security settings by themselves. In order to do that they will need to reach out to the support. This change has been made in order to improve the security of sites using Chargify.js and will reduce the exposure of Chargify.js as a target for attack. ## 2023-05-10 SSL Badge Removal We would like to inform you that we have decided to immediately discontinue the use of Comodo SSL certificates for our Maxio platform. This decision was made after careful consideration and analysis of our security measures, and we are confident that it will not have any adverse impact on the security or performance of our platform. ## 2023-03-09 Rate of Declined Requests for Stripe Gateway On March 9th, 2023, a feature was released that removes the temporary email submitted to Stripe by Chargify.js during the initial tokenization process. During our developer's review, we compared requests made via Chargify's hosted Self-Service pages which were processing these cards with success versus the requests made via Chargify.js, only finding the temporary email as the common differentiation between these requests. The feature in question was slowly rolled out to sites as requested.That being said, it appears that the rate of declined requests from Stripe has recently decreased for affected merchants independent of this feature, indicating that another change has likely occurred on Stripe's end. As a result of these findings, we are marking this issue as resolved for the time being. Apart from the feature outlined above that was released proactively by our developers to hopefully aid in reducing the number of declines, no other changes were made on our end. Additionally, due to the success rates increase without the need for this feature, we will not be rolling out the feature previously mentioned unless requested. If the feature to disable temporary Chargify.js emails is needed for your site's configuration, please reach out to Support. If there are any additional questions on the cause of this issue,please reach out to Stripe support for further clarification as we are unable to verify the changes they made on their end to resolve this issue. ## 2023-02-28 Increase in Declines from Stripe Gateway We have multiple merchants experiencing an increase in declines when storing credit cards within the Stripe payment gateway beginning in early February. Further investigation by our developers did not find any changes on our end that would result in these declines. Until we receive more direct insight from Stripe on this matter, we recommend that any affected merchants contact Stripe directly. Additionally, customers encountering declines may reach out to their card issuing bank for more information. We have also found multiple instances where a decline succeeds in the future after some time, suggesting these declines may not be permanent errors. We understand the inconvenience these increased declines may cause, and will provide further updates as soon as we have more information to share. ## 2023-02-03 Unintended Renewal Event After The First Dunning Attempt We recently released a fix for renewal webhooks on 2023-01-24, however, we regret to inform you that this resulted in unintended consequences causing the webhooks to trigger daily after the first dunning attempt. Our development team quickly identified and resolved the issue, ensuring that the renewal webhooks will now only trigger on the normal renewal dates. We understand that this situation may have caused some inconvenience, and we would like to extend our sincerest apologies for any disruption. We are committed to providing our customers with the best possible service, and we appreciate your patience and understanding during this time. ## 2023-02-01 Limitations to custom fields As of February 13th, 2023, we will implement a change limiting custom fields to 2048 characters. This decision has been made with the aim of improving the stability and performance of our system. ## 2023-01-30 "Access Denied" 401 HTTP responses in UI and API Between 12:54 UTC and 13:21 UTC, a routine system update being rolled out incrementally inadvertently caused a small number of customers to experience "Access Denied" 401 HTTP status code responses in the UI and API. As soon as our engineers determined the 401 responses were associated with the system upgrade, the upgrade was immediately rolled back. Due to the incremental rollout of this system upgrade, only a small number of customers were affected within the 25-minute window between the initial rollout and subsequent reversion. Customers were able to work around this issue by refreshing the page or retrying API calls until a successful response was received. While this issue was corrected by the reversion of the system update, we sincerely apologize for any inconveniences this matter caused, and thank you for your patience and understanding as our engineers worked toward a resolution. ## 2023-01-24 Renewal Success and Renewal Failure events changes We have recently been made aware of an issue with our subscription renewals and webhook events. Specifically, that subscription renewal did not trigger a webhook event while the subscription was in a past_due state. This was caused by a mid-period component allocation failure or the renewal occurred a couple of days after the subscription entered dunning. Even when the subscription's state changed to active, no event was triggered to note the next renewal, and issue an invoice. We have made changes to our system to ensure that renewal webhooks will be triggered even when a subscription is in a past-due state. This means that our customers will receive the most up-to-date information on their subscriptions. ## 2023-01-18 Ability to set custom settings for applying prepayments to invoices As of January 18th, 2023, we have added additional options for the manner in which prepayments are applied to invoices. The new options may be found under Config > Settings > Prepayments and the custom settings for applying prepayments to invoices are as follows: Automatic Payment Collection Method: - Do not automatically apply prepayments - Apply available prepayments automatically immediately upon issuance of invoice - Apply prepayments automatically on the due date (default setting) Remittance Payment Collection Method: - Do not automatically apply prepayments - Apply available prepayments automatically immediately upon issuance of invoice (default setting) This change was made to allow merchants greater flexibility to ensure prepayments are applied to invoices in a manner that best fits their individual workflow. ## 2023-01-16 Ability to sort results for List Metafields endpoint As of January 16th, 2023, List Metafields endpoint response will be sorted defaultly by id, ascending. Sorting can be changed to descending by providing direction parameter. ## 2023-01-10 Ability to sort results for List Metadata for Resource Type endpoint As of January 10th, 2023, List Metadata for Resource Type endpoint response will be sorted defaultly by id, ascending. Sorting can be changed to descending by providing direction parameter. # 2022 Announcements ## 2022-12-07 Preserve Period for Subscriptions with Allocated Components During Migration Preview On December 7th, 2022, we will start preserving the period for subscriptions with allocated components during migration preview. Previously, this was not done, but we have made this change to ensure that the preview migration behavior matches the actual migration. ## 2022-12-07 "Cancel_at_end_of_period" Set To True Is No Longer Respected During Subscription Creation Via API When It Is Not Intended To Be. As of December 7th, 2022, the "cancel_at_end_of_period" parameter set to "true" will no longer be respected during subscription creation via API if the "next_billing_at" parameter is also present. Previously, this combination of parameters resulted in a subscription with the status of "Active (Pending Cancellation)". Now, this combination of parameters will be invalid and will result in an error with a status code of 422 and a proper error message. This change is being made to ensure that the subscription creation process is consistent and predictable, and to prevent unintended subscription status changes. ## 2022-11-21 Create Successful And Failure Payment Events For Subscription Group Renewal As of November 21st, 2022, we will now create Successful and Failure Payment Events for the primary subscription after renewal. This change was made to ensure the renewal behavior works the same as the initial signup making it easier to track subscription group payment activity through the group’s lifetime. ## 2022-11-03 Prepayments No Longer Applied Automatically For Remittance Invoice with Net Terms As of November 3rd, 2022, the logic of applying prepayments automatically is being changed for Remittance Invoices. Previously, we applied prepayments automatically when issuing an invoice only in the cases of the collection method set to "remittance", or when the invoice didn't have net terms set. Now, we apply prepayments automatically only in the case when net terms are not set, regardless of the collection method. This change was made to ensure the prepayment behavior upon issuance of invoices with net terms is consistent for invoices of both "automatic" and "remittance" collection methods. ## 2022-05-19 Products Price Points Interval Validation Changes As of May 19th, 2022, validation on the `interval` attribute (POST/PATCH products/:id/price_points) is being changed. Previously, we required the `interval` attribute to be greater than 0, so if you provided 0.5 value, there was a misleading error message with text: "Recurring interval: must be greater than 0.". Now, we require this field to be greater than or equal to 1. The new validation message is "Recurring Interval: must be greater than or equal to 1.". ## 2022-02-09 Component Allocation Events Backfilled With Transaction Exchange Rate An issue was recently resolved which involved MRR changes for no-charge component allocations on a subscription using a currency other than the site's primary. The MRR changes resulting from these events will be the proper amount going forward. Past event records with the key `component_allocation_change` for such subscriptions have been backfilled with the proper values for component's `transaction_exchange_rate`. If MRR updates for the past events are desired, please reach out to support. # 2021 Announcements ## 2021-12-16 Current Vault Validation Between approximately 3:30 AM on November 9th, 2021, and 2:00 PM on November 10, 2021,the value of `current_vault` was being validated to see if it matched one of the gateways configured for the site. In most cases the value did match and there was no effect. For a few sites, we discovered that an incorrect value was being submitted. For example, we were receiving `stripe` when the correct value is `stripe_connect`. This change has been reverted, and we are reaching out to a limited number of merchants who experienced signup failures due to this validation. We apologize for any disruption and are taking steps to ensure that notification is provided in advance if we must make a change that breaks backwards compatibility in the API. This change will be re-introduced in the future. ## 2021-11-23 Issue Service Credit Response Body Change As of November 23rd, 2021, the [Issue Service Credit API endpoint]($e/Subscription%20Invoice%20Account/issueServiceCredit) will respond with a new body: ```json { "id": "Integer", "amount_in_cents": "Integer", "ending_balance_in_cents": "Integer", "entry_type": "String", "memo": "String" } ``` Previously, this endpoint was returning just a status code without body. ## 2021-11-18 Renewal Preview Returns Free Non-Zero Components As of November 18th, 2021, the renewal preview API endpoint will return additional component line items. Previously, only components with a cost greater than 0 were returned. With the new behavior, free components will be returned as line items so long as their recorded quantity is greater than 0. ## 2021-11-05 Payment Collection Validation Changes As of October 26th, 2021, subscription's attribute "payment_collection_method" is being validated accordingly to site's architecture: - on statement-based sites valid options are: - "automatic" - "invoice" - on Relationship Invoicing architecture valid options are: - "automatic" - "remittance" - "prepaid" ## 2021-10-01 Update Price Point Prices Error Response Code Change Currently, when [updating a price point]($e/Components/updateComponentPricePoint) with changes to its prices and referencing an id of a price which does not belong to the specified price point, the API returns a 404. The response for this case is changing to a 422. ## 2021-09-13 Subscription Reactivation Payment Decline Error Change The error messages returned when a subscription's reactivation payment has been declined will change on October 4, 2021, both within the API and the admin UI. The current behavior returns one of two generic messages. If the payment profile was declined, the message is: “The payment method on file could not be charged.” If no payment profile is on file, the message is: “The customer does not have a credit card on file.” With the upcoming changes, reactivations that fail due to a payment decline will return the payment gateway’s decline message. When no payment profile is on file, the message will be: “No payment method was on file for the X balance,” where X is the appropriate currency marker and amount due at time of reactivation. For API users, failed reactivation calls will still return a 422, and the structure of the error hash remains the same. Only the error messages in the case of a failed payment or missing payment profile will change to better reflect the cause of failure. These errors will also begin to appear in the admin UI. ## 2021-02-12 Subscription Reactivation Behavior Change As of February 22nd, 2021, reactivation of subscription within the current billing period will by default apply service credits and prepayments to the invoice. There will be an optional checkbox to reactivate the subscription in the old way without using service credits and prepayments. In the API the behavior also will change - service credits and prepayments will be applied by default, to block that action the `use_credits_and_prepayments` attribute must be set to `false`. Previously, service credits and prepayments haven't been considered during reactivation with resuming the current billing period. # 2020 Announcements ## 2020-12-18 Changes to date_field Validation As of December 18th, 2020, we have added validation on the `date_field` attribute. Previously, we did not validate the date_field, and if it was other than `created_at` or `updated_at`, we would allow the query update to proceed, but the result was an empty response. Now if other values as `created_at` or `updated_at` are passed in `date_field`, we just ignore them, and filters are not applied. If other params are correct and records exist, they should appear in the response. If you have any questions or concerns please contact us at [support@maxio.com,](mailto:support@maxio.com) and we’ll be glad to assist. ## 2020-07-13 API Subscriptions XML Response Change As of July 13th, 2020, the XML response for reading multiple subscriptions has changed. Before, dates and integers with no value still displayed a type: ``` ``` Now, the type will no longer be returned for a nil field. ``` ``` Note: This same change was already previously made when reading a single subscription in 2018. ## 2020-04-20 New API Authentication As of April 20 2020, the new authentication method will be enabled. 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, the new authentication method was introduced which is user authentication. Obtaining the User API Key is described below. **Enable API Token View for Admin and Team Member** API Token View is a form with the API settings in the user#edit page. Support, Manager or the Owner of the Seller all have the API Token View enabled by default, in addition, they have the possibility to manage who has access to the API Token View. In case the site Admin or a Team Member leaves the company the API Key can be easily deactivated. In order to enable the API Token View, the support/owner should go to the user's list, click edit on the selected user and mark the checkbox. The API Token View will be enabled for the selected user. ![Enable User API Auth](static/images/announcements/2020-04-20-new-api-authentication/enable-user-api-auth.png) API Token View access can be denied, by unchecking the checkbox. The API Key will be automatically DISABLED, and the user will not have access to the API Token View anymore. ![Disable User API Auth](static/images/announcements/2020-04-20-new-api-authentication/disable-user-api-auth.png) **Generate the API Key** When the API Token View is enabled the generation of the API Key is possible. To do so, go to your profile: ![My Profile](static/images/announcements/2020-04-20-new-api-authentication/my-profile.png) Scroll to the API Token View and click "Generate API Key" ![Generate API Key](static/images/announcements/2020-04-20-new-api-authentication/generate-api-key.png) You'll be directed to the page with a new API Key which should be copied. It will be used to get Sales Reps data. ![Copy API Key](static/images/announcements/2020-04-20-new-api-authentication/copy-api-key.png) After this step, we are ready to perform seller level API queries. **Deprecate the API Key** Deprecating the API Key is possible on the API Token View ![Deprecate API Key](static/images/announcements/2020-04-20-new-api-authentication/deprecate-key.png) By clicking the “Deprecate” button. Additional popup with confirmation will be displayed ![Confirmation Popup](static/images/announcements/2020-04-20-new-api-authentication/confirmation-popup.png) Deprecate option is also available for Chargify Staff and Owner of the Seller. It can be especially useful when API Key is compromised. **Regenerate the API Key** Another option when the key has been compromised is to regenerate the API Key. This is done in the API Token View by clicking on the “Regenerate” button. The old API Key will be deprecated and only the new key will be valid. ![Regenerate API Key](static/images/announcements/2020-04-20-new-api-authentication/regenerate-api-key.png) In order to retrieve sales commission resources, [check out sales commission API documentation.]($e/Sales%20Commissions/listSalesCommissionSettings) ## 2020-04-01 Coupon Endpoint Change As of April 13th, 2020, the coupon endpoint in the API will change. Previously when retrieving coupons from this endpoint, only coupons from the default product family would be returned. The default product family is the one that was created first for the site, provided it has not been archived. Moving forward, retrieving coupons from this endpoint will return all coupons for a given site. [Click here to review documentation for the API endpoint that we will be updating.]($e/Coupons/updateCoupon) With this in mind, it's recommended to review your integration with Chargify and determine whether any calls retrieving coupons need to be updated. Because more coupons may be returned with this change, we recommend using our pagination functionality. The default number of coupons returned per page would be 30. The maximum allowed value is 200 results per page. In order to only retrieve coupons from a specific product family, [the endpoint documented here may be used.]($e/Coupons/listCouponsForProductFamily) ## 2020-01-27 Product Price Point Order As of January 27th, 2020, we will be updating the API response when fetching a list of price points for a product. Moving forward the `GET` request will now always be returned in `DESC` order of `created_at`, ensuring results are consistent across pages. Previously if you included `page=1` in your request the first result of the response was the default price point for that product. This will no longer be the case and the default will appear based on its `created_at` date and time. ## 2020-01-16 Coupon Validation Changes On December 17th, 2019, we made an update to how coupon pricing is validated. Previously we would allow a coupon to be created with a negative amount. If a coupon with a negative amount was applied to a subscription it would get ignored and not attempt to generate a discount, which is the expected behavior. In order to bring coupon validations in line with the expected behavior, we no longer allow coupons to be created with a negative amount. There were a small percentage of these coupons that we've updated from a negative amount to `0` in order to maintain the existing behavior but keep them valid. If you have any questions or concerns please contact us at [support@maxio.com,](mailto:support@maxio.com) and we’ll be glad to assist. # API Endpoints ## API Exports ### listExportedProformaInvoices This API returns an array of exported proforma invoices for a provided `batch_id`. Pay close attention to pagination in order to control responses from the server. Example: `GET https://{subdomain}.chargify.com/api_exports/proforma_invoices/123/rows?per_page=10000&page=1`. #### Code Sample ```Http 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' ``` #### Request Parameters - batch_id (`String`): Id of a Batch Job. - per_page (`Number`): 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. - page (`Number`): 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`. #### Response Type - array #### Response Properties - response (`array`): OK ### listExportedInvoices This API returns an array of exported invoices for a provided `batch_id`. Pay close attention to pagination in order to control responses from the server. Example: `GET https://{subdomain}.chargify.com/api_exports/invoices/123/rows?per_page=10000&page=1`. #### Code Sample ```Http 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' ``` #### Request Parameters - batch_id (`String`): Id of a Batch Job. - per_page (`Number`): 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. - page (`Number`): 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`. #### Response Type - array #### Response Properties - response (`array`): OK ### listExportedSubscriptions This API returns an array of exported subscriptions for a provided `batch_id`. Pay close attention to pagination in order to control responses from the server. Example: `GET https://{subdomain}.chargify.com/api_exports/subscriptions/123/rows?per_page=200&page=1`. #### Code Sample ```Http 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' ``` #### Request Parameters - batch_id (`String`): Id of a Batch Job. - per_page (`Number`): 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. - page (`Number`): 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`. #### Response Type - array #### Response Properties - response (`array`): OK ### exportProformaInvoices This API creates a proforma invoices export and returns a batchjob object. It is only available for Relationship Invoicing architecture. #### Code Sample ```Http curl -X POST \ --url 'https://subdomain.chargify.com/api_exports/proforma_invoices.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Response Type - Batch Job Response #### Response Properties - response (`Batch Job Response`): Created ### exportInvoices This API creates an invoices export and returns a batchjob object. #### Code Sample ```Http curl -X POST \ --url 'https://subdomain.chargify.com/api_exports/invoices.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Response Type - Batch Job Response #### Response Properties - response (`Batch Job Response`): Created ### exportSubscriptions This API creates a subscriptions export and returns a batchjob object. #### Code Sample ```Http curl -X POST \ --url 'https://subdomain.chargify.com/api_exports/subscriptions.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Response Type - Batch Job Response #### Response Properties - response (`Batch Job Response`): Created ### readProformaInvoicesExport This API returns a batchjob object for proforma invoices export. #### Code Sample ```Http curl -X GET \ --url 'https://subdomain.chargify.com/api_exports/proforma_invoices/batch_id8.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - batch_id (`String`): Id of a Batch Job. #### Response Type - Batch Job Response #### Response Properties - response (`Batch Job Response`): OK ### readInvoicesExport This API returns a batchjob object for invoices export. #### Code Sample ```Http curl -X GET \ --url 'https://subdomain.chargify.com/api_exports/invoices/batch_id8.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - batch_id (`String`): Id of a Batch Job. #### Response Type - Batch Job Response #### Response Properties - response (`Batch Job Response`): OK ### readSubscriptionsExport This API returns a batchjob object for subscriptions export. #### Code Sample ```Http curl -X GET \ --url 'https://subdomain.chargify.com/api_exports/subscriptions/batch_id8.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - batch_id (`String`): Id of a Batch Job. #### Response Type - Batch Job Response #### Response Properties - response (`Batch Job Response`): OK ## Advance Invoice ### issueAdvanceInvoice Generate an invoice in advance for a subscription's next renewal date. [See our docs](https://maxio.zendesk.com/hc/en-us/articles/24252026404749-Issue-Invoice-In-Advance) for more information on advance invoices, including eligibility on generating one; for the most part, they function like any other invoice, except they are issued early and have special behavior upon being voided. A subscription may only have one advance invoice per billing period. Attempting to issue an advance invoice when one already exists will return an error. That said, regeneration of the invoice may be forced with the params `force: true`, which will void an advance invoice if one exists and generate a new one. If no advance invoice exists, a new one will be generated. We recommend using either the create or preview endpoints for proforma invoices to preview this advance invoice before using this endpoint to generate it. #### Code Sample ```Http 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 }' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - body (`Issue Advance Invoice Request`) #### Response Type - Invoice #### Response Properties - response (`Invoice`): Created ### readAdvanceInvoice Once an advance invoice has been generated for a subscription's upcoming renewal, it can be viewed through this endpoint. There can only be one advance invoice per subscription per billing cycle. #### Code Sample ```Http curl -X GET \ --url 'https://subdomain.chargify.com/subscriptions/222/advance_invoice.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription #### Response Type - Invoice #### Response Properties - response (`Invoice`): OK ### voidAdvanceInvoice Void a subscription's existing advance invoice. Once voided, it can later be regenerated if desired. A `reason` is required in order to void, and the invoice must have an open status. Voiding will cause 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 our help docs]($m/Invoice). #### Code Sample ```Http 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' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - body (`Void Invoice Request`) #### Response Type - Invoice #### Response Properties - response (`Invoice`): Created ## Billing Portal ### enableBillingPortalForCustomer ## Billing Portal Documentation Full documentation on how the Billing Portal operates within the Advanced Billing UI can be located [here](https://maxio.zendesk.com/hc/en-us/articles/24252412965133-Billing-Portal-Overview). This documentation is focused on how the to configure the Billing Portal Settings, as well as Subscriber Interaction and Merchant Management of the Billing Portal. You can use this endpoint to enable Billing Portal access for a Customer, with the option of sending the Customer an Invitation email at the same time. ## Billing Portal Security If your customer has been invited to the Billing Portal, then they will 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. Because the URL is cryptographically signed with a timestamp, it is not possible for merchants to generate the URL without requesting it from Advanced Billing. In order to prevent abuse & overuse, we ask that you 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 to Advanced Billing every time. #### Code Sample ```Http curl -X POST -G \ --url 'https://subdomain.chargify.com/portal/customers/150/enable.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - customer_id (`Number`): The Chargify id of the customer - auto_invite (`Auto Invite`): 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 - Customer Response #### Response Properties - response (`Customer Response`): OK ### readBillingPortalLink This method will provide to the API user the exact URL required for a subscriber to access the Billing Portal. ## Rules for Management Link API + When retrieving a management URL, multiple requests for the same customer in a short period will return the **same** URL + We will not generate a new URL 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 will be blocked from further Management URL requests (with a response code `429`) #### Code Sample ```Http curl -X GET \ --url 'https://subdomain.chargify.com/portal/customers/150/management_link.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - customer_id (`Number`): The Chargify id of the customer #### Response Type - Portal Management Link #### Response Properties - response (`Portal Management Link`): OK ### resendBillingPortalInvitation You can resend 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 `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 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 a Customer, you will receive a `404` error response. ## Limitations This endpoint will only return a JSON response. #### Code Sample ```Http curl -X POST \ --url 'https://subdomain.chargify.com/portal/customers/150/invitations/invite.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - customer_id (`Number`): The Chargify id of the customer #### Response Type - Resent Invitation #### Response Properties - response (`Resent Invitation`): OK ### revokeBillingPortalAccess You can revoke 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. #### Code Sample ```Http curl -X DELETE \ --url 'https://subdomain.chargify.com/portal/customers/150/invitations/revoke.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - customer_id (`Number`): The Chargify id of the customer #### Response Type - Revoked Invitation #### Response Properties - response (`Revoked Invitation`): OK ## Coupons ### createCoupon ## Coupons Documentation Coupons can be administered in the Advanced Billing application or created via API. View our section on [creating coupons](https://maxio.zendesk.com/hc/en-us/articles/24261212433165-Creating-Editing-Deleting-Coupons) for more information. Additionally, for documentation on how to apply a coupon to a subscription within the Advanced Billing UI, see our documentation [here](https://maxio.zendesk.com/hc/en-us/articles/24261259337101-Coupons-and-Subscriptions). ## Create Coupon This request will create a coupon, based on the provided information. You can create either a flat amount coupon, by specyfing `amount_in_cents`, or percentage coupon by specyfing `percentage`. You can restrict a coupon to only apply to specific products / components by optionally passing in `restricted_products` and/or `restricted_components` objects in the format: `{ "": boolean_value }` #### Code Sample ```Http 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 } }' ``` #### Request Parameters - product_family_id (`Number`): The Advanced Billing id of the product family to which the coupon belongs - body (`Coupon Request`) #### Response Type - Coupon Response #### Response Properties - response (`Coupon Response`): Created ### listCouponsForProductFamily List coupons for a specific Product Family in a Site. #### Code Sample ```Http 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' ``` #### Request Parameters - product_family_id (`Number`): The Advanced Billing id of the product family to which the coupon belongs - page (`Number`): 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`. - per_page (`Number`): 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`. - filter (`List Coupons Filter`): Filter to use for List Coupons operations - currency_prices (`Boolean`): When fetching coupons, if you have defined multiple currencies at the site level, you can optionally pass the `?currency_prices=true` query param to include an array of currency price data in the response. Use in query `currency_prices=true`. #### Response Type - array #### Response Properties - response (`array`): OK ### findCoupon You can search for a coupon via the API with the find method. By passing a code parameter, the find will attempt to locate a coupon that matches that code. If no coupon is found, a 404 is returned. 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, then you will need to specify (either in the url or as a query string param) the product family id. #### Code Sample ```Http curl -X GET -G \ --url 'https://subdomain.chargify.com/coupons/find.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' \ -d 'currency_prices=true' ``` #### Request Parameters - product_family_id (`Number`): The Advanced Billing id of the product family to which the coupon belongs - code (`String`): The code of the coupon - currency_prices (`Boolean`): When fetching coupons, if you have defined multiple currencies at the site level, you can optionally pass the `?currency_prices=true` query param to include an array of currency price data in the response. #### Response Type - Coupon Response #### Response Properties - response (`Coupon Response`): OK ### readCoupon You can retrieve the Coupon via the API with the Show method. You must identify the Coupon in this call by the ID parameter that Advanced Billing assigns. If instead you would like to find a Coupon using a Coupon code, see the Coupon Find method. When fetching a coupon, if you have defined multiple currencies at the site level, you can optionally pass the `?currency_prices=true` query param to include an array of currency price data in the response. If the coupon 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. #### Code Sample ```Http 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' ``` #### Request Parameters - product_family_id (`Number`): The Advanced Billing id of the product family to which the coupon belongs - coupon_id (`Number`): The Advanced Billing id of the coupon - currency_prices (`Boolean`): When fetching coupons, if you have defined multiple currencies at the site level, you can optionally pass the `?currency_prices=true` query param to include an array of currency price data in the response. #### Response Type - Coupon Response #### Response Properties - response (`Coupon Response`): OK ### updateCoupon ## Update Coupon You can update a Coupon via the API with a PUT request to the resource endpoint. 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 }` #### Code Sample ```Http 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 } }' ``` #### Request Parameters - product_family_id (`Number`): The Advanced Billing id of the product family to which the coupon belongs - coupon_id (`Number`): The Advanced Billing id of the coupon - body (`Coupon Request`) #### Response Type - Coupon Response #### Response Properties - response (`Coupon Response`): OK ### archiveCoupon You can archive a Coupon via the API with the archive method. 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. #### Code Sample ```Http curl -X DELETE \ --url 'https://subdomain.chargify.com/product_families/140/coupons/162.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - product_family_id (`Number`): The Advanced Billing id of the product family to which the coupon belongs - coupon_id (`Number`): The Advanced Billing id of the coupon #### Response Type - Coupon Response #### Response Properties - response (`Coupon Response`): OK ### listCoupons You can retrieve a list of coupons. #### Code Sample ```Http 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' ``` #### Request Parameters - page (`Number`): 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`. - per_page (`Number`): 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`. - filter (`List Coupons Filter`): Filter to use for List Coupons operations - currency_prices (`Boolean`): When fetching coupons, if you have defined multiple currencies at the site level, you can optionally pass the `?currency_prices=true` query param to include an array of currency price data in the response. Use in query `currency_prices=true`. #### Response Type - array #### Response Properties - response (`array`): OK ### readCouponUsage This request will provide details about the coupon usage as an array of data hashes, one per product. #### Code Sample ```Http curl -X GET \ --url 'https://subdomain.chargify.com/product_families/140/coupons/162/usage.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - product_family_id (`Number`): The Advanced Billing id of the product family to which the coupon belongs. - coupon_id (`Number`): The Advanced Billing id of the coupon. #### Response Type - array #### Response Properties - response (`array`): OK ### validateCoupon You can verify if a specific coupon code is valid using the `validate` method. This method is useful for validating coupon codes that are entered by a customer. If the coupon is found and is valid, the coupon will be returned with a 200 status code. If the coupon is invalid, the status code will be 404 and the response will say why it is invalid. If the coupon is valid, the status code will be 200 and the coupon will be returned. The following reasons for invalidity are supported: + Coupon not found + Coupon is invalid + Coupon expired 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, then you will 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. Eg. ``` https://.chargify.com/product_families/handle:/coupons/validate.?code= ``` Or: ``` https://.chargify.com/coupons/validate.?code=&product_family_id= ``` #### Code Sample ```Http curl -X GET -G \ --url 'https://subdomain.chargify.com/coupons/validate.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' \ -d 'code=code8' ``` #### Request Parameters - code (`String`): The code of the coupon - product_family_id (`Number`): The Advanced Billing id of the product family to which the coupon belongs #### Response Type - Coupon Response #### Response Properties - response (`Coupon Response`): OK ### createOrUpdateCouponCurrencyPrices This endpoint allows you to create and/or update 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. #### Code Sample ```Http 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 } ] }' ``` #### Request Parameters - coupon_id (`Number`): The Advanced Billing id of the coupon - body (`Coupon Currency Request`) #### Response Type - Coupon Currency Response #### Response Properties - response (`Coupon Currency Response`): OK ### createCouponSubcodes ## Coupon Subcodes Intro 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 Coupon subcodes can be administered in the Admin Interface or via the API. 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 will be capitalized before the subcode is created. ## Coupon Subcodes Documentation Full documentation on how to create coupon subcodes in the Advanced Billing UI can be located [here](https://maxio.zendesk.com/hc/en-us/articles/24261208729229-Coupon-Codes). Additionally, for documentation on how to apply a coupon to a Subscription within the Advanced Billing UI, see our documentation [here](https://maxio.zendesk.com/hc/en-us/articles/24261259337101-Coupons-and-Subscriptions). ## Create Coupon Subcode This request allows you to create specific subcodes underneath an existing coupon code. *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.` #### Code Sample ```Http 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" ] }' ``` #### Request Parameters - coupon_id (`Number`): The Advanced Billing id of the coupon - body (`Coupon Subcodes`) #### Response Type - Coupon Subcodes Response #### Response Properties - response (`Coupon Subcodes Response`): OK ### listCouponSubcodes This request allows you to request the subcodes that are attached to a coupon. #### Code Sample ```Http 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' ``` #### Request Parameters - coupon_id (`Number`): The Advanced Billing id of the coupon - page (`Number`): 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`. - per_page (`Number`): 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`. #### Response Type - Coupon Subcodes #### Response Properties - response (`Coupon Subcodes`): OK ### updateCouponSubcodes You can update the subcodes for the given Coupon via the API with a PUT request to the resource endpoint. 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. #### Code Sample ```Http 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" ] }' ``` #### Request Parameters - coupon_id (`Number`): The Advanced Billing id of the coupon - body (`Coupon Subcodes`) #### Response Type - Coupon Subcodes Response #### Response Properties - response (`Coupon Subcodes Response`): OK ### deleteCouponSubcode ## 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. #### Code Sample ```Http curl -X DELETE \ --url 'https://subdomain.chargify.com/coupons/162/codes/subcode4.json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - coupon_id (`Number`): The Advanced Billing id of the coupon to which the subcode belongs - subcode (`String`): The subcode of the coupon #### Response Type - Void #### Response Properties - response (`Void`): OK ## Components ### createMeteredComponent This request will create a component definition of kind **metered_component** under the specified product family. 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 Adwords 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. For more information on components, see our documentation [here](https://maxio.zendesk.com/hc/en-us/articles/24261141522189-Components-Overview). #### Code Sample ```Http 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 } ] } }' ``` #### Request Parameters - product_family_id (`String`): Either the product family's id or its handle prefixed with `handle:` - body (`Create Metered Component`) #### Response Type - Component Response #### Response Properties - response (`Component Response`): Created ### createQuantityBasedComponent This request will create a component definition of kind **quantity_based_component** under the specified product family. Quantity Based component can then be added and “allocated” for a subscription. When defining Quantity Based component, You can choose one of 2 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 on components, see our documentation [here](https://maxio.zendesk.com/hc/en-us/articles/24261141522189-Components-Overview). #### Code Sample ```Http 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 ] } }' ``` #### Request Parameters - product_family_id (`String`): Either the product family's id or its handle prefixed with `handle:` - body (`Create Quantity Based Component`) #### Response Type - Component Response #### Response Properties - response (`Component Response`): Created ### createOnOffComponent This request will create a component definition of kind **on_off_component** under the specified product family. 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). #### Code Sample ```Http 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 ] } }' ``` #### Request Parameters - product_family_id (`String`): Either the product family's id or its handle prefixed with `handle:` - body (`Create on Off Component`) #### Response Type - Component Response #### Response Properties - response (`Component Response`): Created ### createPrepaidUsageComponent This request will create a component definition of kind **prepaid_usage_component** under the specified product family. 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 we subsequently keep track of the usage against the amount purchased. For more information on components, see our documentation [here](https://maxio.zendesk.com/hc/en-us/articles/24261141522189-Components-Overview). #### Code Sample ```Http 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 } ] } } }' ``` #### Request Parameters - product_family_id (`String`): Either the product family's id or its handle prefixed with `handle:` - body (`Create Prepaid Component`) #### Response Type - Component Response #### Response Properties - response (`Component Response`): Created ### createEventBasedComponent This request will create a component definition of kind **event_based_component** under the specified product family. 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 on components, see our documentation [here](https://maxio.zendesk.com/hc/en-us/articles/24261141522189-Components-Overview). #### Code Sample ```Http 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 } }' ``` #### Request Parameters - product_family_id (`String`): Either the product family's id or its handle prefixed with `handle:` - body (`Create EBB Component`) #### Response Type - Component Response #### Response Properties - response (`Component Response`): Created ### findComponent This request will return information regarding a component having the handle you provide. You can identify your components with a handle so you don't have to save or reference the IDs we generate. #### Code Sample ```Http curl -X GET -G \ --url 'https://subdomain.chargify.com/components/lookup.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' \ -d 'handle=handle6' ``` #### Request Parameters - handle (`String`): The handle of the component to find #### Response Type - Component Response #### Response Properties - response (`Component Response`): OK ### readComponent 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:`. #### Code Sample ```Http curl -X GET \ --url 'https://subdomain.chargify.com/product_families/140/components/component_id8.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - product_family_id (`Number`): The Advanced Billing id of the product family to which the component belongs - component_id (`String`): Either the Advanced Billing id of the component or the handle for the component prefixed with `handle:` #### Response Type - Component Response #### Response Properties - response (`Component Response`): OK ### updateProductFamilyComponent This request will update 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:`. #### Code Sample ```Http 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" } }' ``` #### Request Parameters - product_family_id (`Number`): The Advanced Billing id of the product family to which the component belongs - component_id (`String`): Either the Advanced Billing id of the component or the handle for the component prefixed with `handle:` - body (`Update Component Request`) #### Response Type - Component Response #### Response Properties - response (`Component Response`): OK ### archiveComponent Sending a DELETE request to this endpoint will archive the component. All current subscribers will be unffected; their subscription/purchase will continue to be charged as usual. #### Code Sample ```Http curl -X DELETE \ --url 'https://subdomain.chargify.com/product_families/140/components/component_id8.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - product_family_id (`Number`): The Advanced Billing id of the product family to which the component belongs - component_id (`String`): Either the Advanced Billing id of the component or the handle for the component prefixed with `handle:` #### Response Type - Component #### Response Properties - response (`Component`): OK ### listComponents This request will return a list of components for a site. #### Code Sample ```Http 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' ``` #### Request Parameters - date_field (`Basic Date Field`): The type of filter you would like to apply to your search. - start_date (`String`): 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`): 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`): 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`): 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. optional - include_archived (`Boolean`): Include archived items - page (`Number`): 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`. - per_page (`Number`): 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`. - filter (`List Components Filter`): Filter to use for List Components operations #### Response Type - array #### Response Properties - response (`array`): OK ### updateComponent This request will update 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:`. #### Code Sample ```Http 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" } }' ``` #### Request Parameters - component_id (`String`): The id or handle of the component - body (`Update Component Request`) #### Response Type - Component Response #### Response Properties - response (`Component Response`): OK ### listComponentsForProductFamily This request will return a list of components for a particular product family. #### Code Sample ```Http 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' ``` #### Request Parameters - product_family_id (`Number`): The Advanced Billing id of the product family - include_archived (`Boolean`): Include archived items. - page (`Number`): 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`. - per_page (`Number`): 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`. - filter (`List Components Filter`): Filter to use for List Components operations - date_field (`Basic Date Field`): The type of filter you would like to apply to your search. Use in query `date_field=created_at`. - end_date (`String`): 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`): 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. optional. - start_date (`String`): 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`): 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 - array #### Response Properties - response (`array`): OK ## Component: Price Points ### promoteComponentPricePointToDefault 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. #### Code Sample ```Http curl -X PUT \ --url 'https://subdomain.chargify.com/components/222/price_points/10/default.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - component_id (`Number`): The Advanced Billing id of the component to which the price point belongs - price_point_id (`Number`): The Advanced Billing id of the price point #### Response Type - Component Response #### Response Properties - response (`Component Response`): OK ### createComponentPricePoint Creates a price point for an existing component. #### Code Sample ```Http 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" } ] } }' ``` #### Request Parameters - component_id (`Number`): The Advanced Billing id of the component - body (`Create Component Price Point Request`) #### Response Type - Component Price Point Response #### Response Properties - response (`Component Price Point Response`): OK ### listComponentPricePoints Use this endpoint to read current price points that are associated with a component. You may specify the component by using either the numeric id or the `handle:gold` syntax. When fetching a component's price points, if you have defined multiple currencies at the site level, you can optionally pass the `?currency_prices=true` query param to include an array of currency price data in the response. 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. #### Code Sample ```Http 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')' ``` #### Request Parameters - component_id (`Number`): The Advanced Billing id of the component - currency_prices (`Boolean`): Include an array of currency price data - page (`Number`): 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`. - per_page (`Number`): 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`. - filter[type] (`array`): Use in query: `filter[type]=catalog,default`. #### Response Type - Component Price Points Response #### Response Properties - response (`Component Price Points Response`): Created ### bulkCreateComponentPricePoints Use this endpoint to create multiple component price points in one request. #### Code Sample ```Http 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 } ] } ] }' ``` #### Request Parameters - component_id (`String`): The Advanced Billing id of the component for which you want to fetch price points. - body (`Create Component Price Points Request`) #### Response Type - Component Price Points Response #### Response Properties - response (`Component Price Points Response`): OK ### updateComponentPricePoint When updating a price point, prices can be updated as well by creating new prices or editing / removing existing ones. 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. #### Code Sample ```Http 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 } ] } }' ``` #### Request Parameters - component_id (`Number | String`): 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`): 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`) #### Response Type - Component Price Point Response #### Response Properties - response (`Component Price Point Response`): OK ### readComponentPricePoint Use this endpoint to retrieve details for a specific component price point. You can achieve this by using either the component price point ID or handle. #### Code Sample ```Http curl -X GET -G \ --url 'https://subdomain.chargify.com/components/144/price_points/188.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - component_id (`Number | String`): 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`): 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`): Include an array of currency price data #### Response Type - Component Price Point Response #### Response Properties - response (`Component Price Point Response`): OK ### archiveComponentPricePoint A price point can be archived at any time. Subscriptions using a price point that has been archived will continue using it until they're moved to another price point. #### Code Sample ```Http curl -X DELETE \ --url 'https://subdomain.chargify.com/components/144/price_points/188.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - component_id (`Number | String`): 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`): 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 - Component Price Point Response #### Response Properties - response (`Component Price Point Response`): OK ### unarchiveComponentPricePoint Use this endpoint to unarchive a component price point. #### Code Sample ```Http curl -X PUT \ --url 'https://subdomain.chargify.com/components/222/price_points/10/unarchive.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - component_id (`Number`): The Advanced Billing id of the component to which the price point belongs - price_point_id (`Number`): The Advanced Billing id of the price point #### Response Type - Component Price Point Response #### Response Properties - response (`Component Price Point Response`): OK ### createCurrencyPrices This endpoint allows you to create 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. 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. #### Code Sample ```Http 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 } ] }' ``` #### Request Parameters - price_point_id (`Number`): The Advanced Billing id of the price point - body (`Create Currency Prices Request`) #### Response Type - Component Currency Prices Response #### Response Properties - response (`Component Currency Prices Response`): OK ### updateCurrencyPrices This endpoint allows you to update currency prices for a given currency that has been defined on the site level in your settings. Note: Currency Prices are not able to be updated for custom price points. #### Code Sample ```Http 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 } ] }' ``` #### Request Parameters - price_point_id (`Number`): The Advanced Billing id of the price point - body (`Update Currency Prices Request`) #### Response Type - Component Currency Prices Response #### Response Properties - response (`Component Currency Prices Response`): OK ### listAllComponentPricePoints This method allows to retrieve a list of Components Price Points belonging to a Site. #### Code Sample ```Http 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' ``` #### Request Parameters - include (`List Components Price Points Include`): Allows including additional data in the response. Use in query: `include=currency_prices`. - page (`Number`): 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`. - per_page (`Number`): 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`. - direction (`Sorting Direction`): Controls the order in which results are returned. Use in query `direction=asc`. - filter (`List Price Points Filter`): Filter to use for List PricePoints operations #### Response Type - List Components Price Points Response #### Response Properties - response (`List Components Price Points Response`): OK ## Customers ### createCustomer You may create a new Customer at any time, or you may create a Customer at the same time you create a Subscription. The only validation restriction is that you may 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 may choose to leave `reference` blank, and store Advanced Billing’s unique ID for the customer, which is in the `id` attribute. Full documentation on how to locate, create and edit Customers in the Advanced Billing UI can be located [here](https://maxio.zendesk.com/hc/en-us/articles/24252190590093-Customer-Details). ## Required Country Format Advanced Billing requires that you use the ISO Standard Country codes when formatting country attribute of the customer. Countries should be formatted as 2 characters. For more information, see the following wikipedia article on [ISO_3166-1.](http://en.wikipedia.org/wiki/ISO_3166-1#Current_codes) ## Required State Format Advanced Billing requires that you use the ISO Standard State codes when formatting state attribute of the customer. + US States (2 characters): [ISO_3166-2](https://en.wikipedia.org/wiki/ISO_3166-2:US) + States Outside the US (2-3 characters): To find the correct state codes outside of 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 country you wish to populate. ## Locale Advanced Billing allows you to attribute a language/region to your customer to deliver invoices in any required language. For more: [Customer Locale](https://maxio.zendesk.com/hc/en-us/articles/24286672013709-Customer-Locale) #### Code Sample ```Http 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" } }' ``` #### Request Parameters - body (`Create Customer Request`) #### Response Type - Customer Response #### Response Properties - response (`Customer Response`): OK ### listCustomers This request will by default list all customers associated with your Site. ## 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). #### Code Sample ```Http 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' ``` #### Request Parameters - direction (`Sorting Direction`): Direction to sort customers by time of creation - page (`Number`): 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`. - per_page (`Number`): 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`. - date_field (`Basic Date Field`): The type of filter you would like to apply to your search. Use in query: `date_field=created_at`. - start_date (`String`): 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`): 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`): 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`): 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`): A search query by which to filter customers (can be an email, an ID, a reference, organization) #### Response Type - array #### Response Properties - response (`array`): OK ### readCustomer Retrieves the Customer properties by Advanced Billing-generated Customer ID. #### Code Sample ```Http curl -X GET \ --url 'https://subdomain.chargify.com/customers/112.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - id (`Number`): The Advanced Billing id of the customer #### Response Type - Customer Response #### Response Properties - response (`Customer Response`): OK ### updateCustomer This method allows to update the Customer. #### Code Sample ```Http 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" } }' ``` #### Request Parameters - id (`Number`): The Advanced Billing id of the customer - body (`Update Customer Request`) #### Response Type - Customer Response #### Response Properties - response (`Customer Response`): OK ### deleteCustomer This method allows you to delete the Customer. #### Code Sample ```Http curl -X DELETE \ --url 'https://subdomain.chargify.com/customers/112.json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - id (`Number`): The Advanced Billing id of the customer #### Response Type - Void #### Response Properties - response (`Void`): No Content ### readCustomerByReference Use this method to return the customer object if you have the unique **Reference ID (Your App)** value handy. It will return a single match. #### Code Sample ```Http curl -X GET -G \ --url 'https://subdomain.chargify.com/customers/lookup.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' \ -d 'reference=reference4' ``` #### Request Parameters - reference (`String`): Customer reference #### Response Type - Customer Response #### Response Properties - response (`Customer Response`): OK ### listCustomerSubscriptions This method lists all subscriptions that belong to a customer. #### Code Sample ```Http curl -X GET \ --url 'https://subdomain.chargify.com/customers/150/subscriptions.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - customer_id (`Number`): The Chargify id of the customer #### Response Type - array #### Response Properties - response (`array`): OK ## Custom Fields ### createMetafields 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]($e/Custom%20Fields/updateMetafield), [Create Metadata]($e/Custom%20Fields/createMetadata), or [Update Metadata]($e/Custom%20Fields/updateMetadata) 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. #### Code Sample ```Http 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" } } }' ``` #### Request Parameters - resource_type (`Resource Type`): The resource type to which the metafields belong. - body (`Create Metafields Request`) #### Response Type - array #### Response Properties - response (`array`): OK ### listMetafields Lists the metafields and their associated details for a Site and resource type. You can filter the request to a specific metafield. #### Code Sample ```Http 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' ``` #### Request Parameters - resource_type (`Resource Type`): The resource type to which the metafields belong. - name (`String`): Filter by the name of the metafield. - page (`Number`): 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`. - per_page (`Number`): 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`. - direction (`Sorting Direction`): Controls the order in which results are returned. Use in query `direction=asc`. #### Response Type - List Metafields Response #### Response Properties - response (`List Metafields Response`): OK ### updateMetafield 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. #### Code Sample ```Http curl -X PUT \ --url 'https://subdomain.chargify.com/subscriptions/metafields.json' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - resource_type (`Resource Type`): The resource type to which the metafields belong. - body (`Update Metafields Request`) #### Response Type - array #### Response Properties - response (`array`): OK ### deleteMetafield Deletes a metafield from your Site. Removes the metafield and associated metadata from all Subscriptions or Customers resources on the Site. #### Code Sample ```Http curl -X DELETE -G \ --url 'https://subdomain.chargify.com/subscriptions/metafields.json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - resource_type (`Resource Type`): The resource type to which the metafields belong. - name (`String`): The name of the metafield to be deleted #### Response Type - Void #### Response Properties - response (`Void`): OK ### createMetadata 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]($e/Custom%20Fields/updateMetafield) 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. #### Code Sample ```Http 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" } ] }' ``` #### Request Parameters - resource_type (`Resource Type`): The resource type to which the metafields belong. - resource_id (`Number`): The Advanced Billing id of the customer or the subscription for which the metadata applies - body (`Create Metadata Request`) #### Response Type - array #### Response Properties - response (`array`): OK ### listMetadata Lists metadata and metafields for a specific customer or subscription. #### Code Sample ```Http 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' ``` #### Request Parameters - resource_type (`Resource Type`): The resource type to which the metafields belong. - resource_id (`Number`): The Advanced Billing id of the customer or the subscription for which the metadata applies - page (`Number`): 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`. - per_page (`Number`): 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`. #### Response Type - Paginated Metadata #### Response Properties - response (`Paginated Metadata`): OK ### updateMetadata 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 Subscription and another 100 for Customer. #### Code Sample ```Http curl -X PUT \ --url 'https://subdomain.chargify.com/subscriptions/60/metadata.json' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - resource_type (`Resource Type`): The resource type to which the metafields belong. - resource_id (`Number`): The Advanced Billing id of the customer or the subscription for which the metadata applies - body (`Update Metadata Request`) #### Response Type - array #### Response Properties - response (`array`): OK ### deleteMetadata Deletes one or more metafields (and associated metadata) from the specified subscription or customer. #### Code Sample ```Http curl -X DELETE -G \ --url 'https://subdomain.chargify.com/subscriptions/60/metadata.json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - resource_type (`Resource Type`): The resource type to which the metafields belong. - resource_id (`Number`): The Advanced Billing id of the customer or the subscription for which the metadata applies - name (`String`): Name of field to be removed. - names (`array`): Names of fields to be removed. Use in query: `names[]=field1&names[]=my-field&names[]=another-field`. #### Response Type - Void #### Response Properties - response (`Void`): OK ### listMetadataForResourceType Lists metadata for a specified array of subscriptions or customers. #### Code Sample ```Http 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' ``` #### Request Parameters - resource_type (`Resource Type`): The resource type to which the metafields belong. - page (`Number`): 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`. - per_page (`Number`): 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`. - date_field (`Basic Date Field`): The type of filter you would like to apply to your search. - start_date (`Date`): 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`): 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`): 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`): 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`): Allow to fetch deleted metadata. - resource_ids (`array`): Allow to fetch metadata for multiple records based on provided ids. Use in query: `resource_ids[]=122&resource_ids[]=123&resource_ids[]=124`. - direction (`Sorting Direction`): Controls the order in which results are returned. Use in query `direction=asc`. #### Response Type - Paginated Metadata #### Response Properties - response (`Paginated Metadata`): OK ## Events ### listEvents ## Events Intro Advanced Billing 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 Advanced Billing UI, "Events" are referred to as "Site Activity". Full documentation on how to record view Events / Site Activty in the Advanced Billing UI can be located [here](https://maxio.zendesk.com/hc/en-us/articles/24250671733517-Site-Activity). ## List Events for a Site This method will retrieve a list of events for a site. Use query string filters to narrow down results. You may use the `key` filter as part of your query string to narrow down results. ### 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. You can check supported keys [here]($m/Event%20Key). ## 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]($m/Event). ### Example Here’s an example event for the `subscription_product_change` event: ``` { "event": { "id": 351, "key": "subscription_product_change", "message": "Product changed on Marky Mark'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 Marky Mark'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" } } ``` #### Code Sample ```Http 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' ``` #### Request Parameters - page (`Number`): 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`. - per_page (`Number`): 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`. - since_id (`Long`): Returns events with an id greater than or equal to the one specified - max_id (`Long`): Returns events with an id less than or equal to the one specified - direction (`Direction`): The sort direction of the returned events. - filter (`array`): You can pass multiple event keys after comma. Use in query `filter=signup_success,payment_success`. - date_field (`List Events Date Field`): The type of filter you would like to apply to your search. - start_date (`String`): 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`): 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`): 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`): 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 - array #### Response Properties - response (`array`): OK ### listSubscriptionEvents The following request will return a list of events for a subscription. ## Event Key The event type is identified by the key property. You can check supported keys [here]($m/Event%20Key). ## 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]($m/Event). #### Code Sample ```Http 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' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - page (`Number`): 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`. - per_page (`Number`): 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`. - since_id (`Long`): Returns events with an id greater than or equal to the one specified - max_id (`Long`): Returns events with an id less than or equal to the one specified - direction (`Direction`): The sort direction of the returned events. - filter (`array`): You can pass multiple event keys after comma. Use in query `filter=signup_success,payment_success`. #### Response Type - array #### Response Properties - response (`array`): OK ### readEventsCount Get a count of all the events for a given site by using this method. #### Code Sample ```Http 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' ``` #### Request Parameters - page (`Number`): 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`. - per_page (`Number`): 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`. - since_id (`Long`): Returns events with an id greater than or equal to the one specified - max_id (`Long`): Returns events with an id less than or equal to the one specified - direction (`Direction`): The sort direction of the returned events. - filter (`array`): You can pass multiple event keys after comma. Use in query `filter=signup_success,payment_success`. #### Response Type - Count Response #### Response Properties - response (`Count Response`): OK ## Events-Based Billing: Segments ### createSegment This endpoint creates a new Segment for a Component with 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. #### Code Sample ```Http 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 } ] } }' ``` #### Request Parameters - component_id (`String`): ID or Handle for the Component - price_point_id (`String`): ID or Handle for the Price Point belonging to the Component - body (`Create Segment Request`) #### Response Type - Segment Response #### Response Properties - response (`Segment Response`): Created ### listSegmentsForPricePoint This endpoint allows you to fetch Segments created for a given Price Point. They will be returned in the 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. #### Code Sample ```Http 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' ``` #### Request Parameters - component_id (`String`): ID or Handle for the Component - price_point_id (`String`): ID or Handle for the Price Point belonging to the Component - page (`Number`): 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`. - per_page (`Number`): 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`. - filter (`List Segments Filter`): Filter to use for List Segments for a Price Point operation #### Response Type - List Segments Response #### Response Properties - response (`List Segments Response`): OK ### updateSegment This endpoint updates a single Segment for a Component with a segmented Metric. It allows you to update the pricing for the segment. You may specify component and/or price point by using either the numeric ID or the `handle:gold` syntax. #### Code Sample ```Http 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' ``` #### Request Parameters - component_id (`String`): ID or Handle of the Component - price_point_id (`String`): ID or Handle of the Price Point belonging to the Component - id (`Decimal`): The ID of the Segment - body (`Update Segment Request`) #### Response Type - Segment Response #### Response Properties - response (`Segment Response`): OK ### deleteSegment This endpoint allows you to delete a Segment with specified ID. You may specify component and/or price point by using either the numeric ID or the `handle:gold` syntax. #### Code Sample ```Http curl -X DELETE \ --url 'https://subdomain.chargify.com/components/component_id8/price_points/price_point_id8/segments/60.json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - component_id (`String`): ID or Handle of the Component - price_point_id (`String`): ID or Handle of the Price Point belonging to the Component - id (`Decimal`): The ID of the Segment #### Response Type - Void #### Response Properties - response (`Void`): No Content ### bulkCreateSegments This endpoint allows you to create 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. #### Code Sample ```Http 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' ``` #### Request Parameters - component_id (`String`): ID or Handle for the Component - price_point_id (`String`): ID or Handle for the Price Point belonging to the Component - body (`Bulk Create Segments`) #### Response Type - List Segments Response #### Response Properties - response (`List Segments Response`): Created ### bulkUpdateSegments This endpoint allows you to update 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. #### Code Sample ```Http 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' ``` #### Request Parameters - component_id (`String`): ID or Handle for the Component - price_point_id (`String`): ID or Handle for the Price Point belonging to the Component - body (`Bulk Update Segments`) #### Response Type - List Segments Response #### Response Properties - response (`List Segments Response`): OK ## Insights ### readSiteStats The Stats API is a very basic view of some 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 ``` #### Code Sample ```Http curl -X GET \ --url 'https://subdomain.chargify.com/stats.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Response Type - Site Summary #### Response Properties - response (`Site Summary`): OK ### readMrr This endpoint returns your site's current MRR, including plan and usage breakouts. #### Code Sample ```Http curl -X GET -G \ --url 'https://subdomain.chargify.com/mrr.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - at_time (`DateTime`): submit a timestamp in ISO8601 format to request MRR for a historic time - subscription_id (`Number`): submit the id of a subscription in order to limit results #### Response Type - MRR Response #### Response Properties - response (`MRR Response`): OK ### listMrrMovements This endpoint returns 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 #### Code Sample ```Http 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' ``` #### Request Parameters - subscription_id (`Number`): optionally filter results by subscription - page (`Number`): 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`. - per_page (`Number`): 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`. - direction (`Sorting Direction`): Controls the order in which results are returned. Use in query `direction=asc`. #### Response Type - List MRR Response #### Response Properties - response (`List MRR Response`): OK ### listMrrPerSubscription This endpoint returns your site's current MRR, including plan and usage breakouts split per subscription. #### Code Sample ```Http 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' ``` #### Request Parameters - filter (`List Mrr Filter`): Filter to use for List MRR per subscription operation - at_time (`String`): 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`): 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`. - per_page (`Number`): 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`. - direction (`Direction`): 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 - Subscription MRR Response #### Response Properties - response (`Subscription MRR Response`): OK ## Invoices ### refundInvoice Refund 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. A $50.00 refund on a $100.00 consolidated invoice with one $60.00 and one $40.00 segment, the refunded amount will be applied as 50% of each ($30.00 and $20.00 respectively). #### Code Sample ```Http 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 } }' ``` #### Request Parameters - uid (`String`): The unique identifier for the invoice, this does not refer to the public facing invoice number. - body (`Refund Invoice Request`) #### Response Type - Invoice #### Response Properties - response (`Invoice`): OK ### listInvoices 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`. #### Code Sample ```Http 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' ``` #### Request Parameters - start_date (`String`): 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`): 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`): The current status of the invoice. Allowed Values: draft, open, paid, pending, voided - subscription_id (`Number`): The subscription's ID. - subscription_group_uid (`String`): 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`): The consolidation level of the invoice. Allowed Values: none, parent, child or comma-separated lists of thereof, e.g. none,parent. - page (`Number`): 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`. - per_page (`Number`): 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`. - direction (`Direction`): The sort direction of the returned invoices. - line_items (`Boolean`): Include line items data - discounts (`Boolean`): Include discounts data - taxes (`Boolean`): Include taxes data - credits (`Boolean`): Include credits data - payments (`Boolean`): Include payments data - custom_fields (`Boolean`): Include custom fields data - refunds (`Boolean`): Include refunds data - date_field (`Invoice Date Field`): The type of filter you would like to apply to your search. Use in query `date_field=issue_date`. - start_datetime (`String`): 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`): 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`): Allows fetching invoices with matching customer id based on provided values. Use in query `customer_ids=1,2,3`. - number (`array`): Allows fetching invoices with matching invoice number based on provided values. Use in query `number=1234,1235`. - product_ids (`array`): Allows fetching invoices with matching line items product ids based on provided values. Use in query `product_ids=23,34`. - sort (`Invoice Sort Field`): Allows specification of the order of the returned list. Use in query `sort=total_amount`. #### Response Type - List Invoices Response #### Response Properties - response (`List Invoices Response`): OK ### readInvoice Use this endpoint to retrieve 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. ``` #### Code Sample ```Http curl -X GET \ --url 'https://subdomain.chargify.com/invoices/uid0.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - uid (`String`): The unique identifier for the invoice, this does not refer to the public facing invoice number. #### Response Type - Invoice #### Response Properties - response (`Invoice`): OK ### listInvoiceEvents This endpoint returns a list of invoice events. 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. #### Code Sample ```Http 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' ``` #### Request Parameters - since_date (`String`): 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`): 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`): 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`. - per_page (`Number`): 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. - invoice_uid (`String`): Providing an invoice_uid allows for scoping of the invoice events to a single invoice or credit note. - with_change_invoice_status (`String`): Use this parameter if you want to fetch also invoice events with change_invoice_status type. - event_types (`array`): 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 - List Invoice Events Response #### Response Properties - response (`List Invoice Events Response`): OK ### recordPaymentForInvoice 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 Bulk Payment endpoint. #### Code Sample ```Http 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" } }' ``` #### Request Parameters - uid (`String`): The unique identifier for the invoice, this does not refer to the public facing invoice number. - body (`Create Invoice Payment Request`) #### Response Type - Invoice #### Response Properties - response (`Invoice`): OK ### recordPaymentForMultipleInvoices This API call should be used when you want to record an external payment against multiple invoices. In order apply a payment to multiple invoices, at minimum, specify the `amount` and `applications` (i.e., `invoice_uid` and `amount`) details. ``` { "payment": { "memo": "to pay the bills", "details": "check number 8675309", "method": "check", "amount": "250.00", "applications": [ { "invoice_uid": "inv_8gk5bwkct3gqt", "amount": "100.00" }, { "invoice_uid": "inv_7bc6bwkct3lyt", "amount": "150.00" } ] } } ``` Note that the invoice payment amounts must be greater than 0. Total amount must be greater or equal to invoices payment amount sum. #### Code Sample ```Http 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" } ] } }' ``` #### Request Parameters - body (`Create Multi Invoice Payment Request`) #### Response Type - Multi Invoice Payment Response #### Response Properties - response (`Multi Invoice Payment Response`): OK ### listCreditNotes 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`. #### Code Sample ```Http curl -X GET -G \ --url 'https://subdomain.chargify.com/credit_notes.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' \ -d 'page=1' \ -d 'per_page=50' \ -d 'line_items=false' \ -d 'discounts=false' \ -d 'taxes=false' \ -d 'refunds=false' \ -d 'applications=false' ``` #### Request Parameters - subscription_id (`Number`): The subscription's Advanced Billing id - page (`Number`): 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`. - per_page (`Number`): 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`. - line_items (`Boolean`): Include line items data - discounts (`Boolean`): Include discounts data - taxes (`Boolean`): Include taxes data - refunds (`Boolean`): Include refunds data - applications (`Boolean`): Include applications data #### Response Type - List Credit Notes Response #### Response Properties - response (`List Credit Notes Response`): OK ### readCreditNote Use this endpoint to retrieve the details for a credit note. #### Code Sample ```Http curl -X GET \ --url 'https://subdomain.chargify.com/credit_notes/uid0.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - uid (`String`): The unique identifier of the credit note #### Response Type - Credit Note #### Response Properties - response (`Credit Note`): OK ### recordPaymentForSubscription Record 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. #### Code Sample ```Http 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" } }' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - body (`Record Payment Request`) #### Response Type - Record Payment Response #### Response Properties - response (`Record Payment Response`): OK ### reopenInvoice This endpoint allows you to reopen 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. #### Code Sample ```Http curl -X POST \ --url 'https://subdomain.chargify.com/invoices/uid0/reopen.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - uid (`String`): The unique identifier for the invoice, this does not refer to the public facing invoice number. #### Response Type - Invoice #### Response Properties - response (`Invoice`): OK ### voidInvoice This endpoint allows you to void 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. #### Code Sample ```Http 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" } }' ``` #### Request Parameters - uid (`String`): The unique identifier for the invoice, this does not refer to the public facing invoice number. - body (`Void Invoice Request`) #### Response Type - Invoice #### Response Properties - response (`Invoice`): OK ### listConsolidatedInvoiceSegments Invoice segments returned on the index will only include totals, not detailed breakdowns for `line_items`, `discounts`, `taxes`, `credits`, `payments`, or `custom_fields`. #### Code Sample ```Http 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' ``` #### Request Parameters - invoice_uid (`String`): The unique identifier of the consolidated invoice - page (`Number`): 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`. - per_page (`Number`): 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`. - direction (`Direction`): Sort direction of the returned segments. #### Response Type - Consolidated Invoice #### Response Properties - response (`Consolidated Invoice`): OK ### createInvoice This endpoint will allow you to create 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 items types When defining line item, You can choose one of 3 types for one line item: #### Custom item Like in basic behavior example above, 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 supportted 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. `issue_date` parameter can be send to alter that. Only dates in the past can be send. `issue_date` should be send in `YYYY-MM-DD` format. #### 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_instrucions` parameter. #### Status By default, invoices will be created with open status. Possible alternative is `draft`. #### Code Sample ```Http 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" } ] } }' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - body (`Create Invoice Request`) #### Response Type - Invoice Response #### Response Properties - response (`Invoice Response`): OK ### sendInvoice This endpoint allows for invoices to be programmatically delivered 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. 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. #### Code Sample ```Http 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" ] }' ``` #### Request Parameters - uid (`String`): The unique identifier for the invoice, this does not refer to the public facing invoice number. - body (`Send Invoice Request`) #### Response Type - Void #### Response Properties - response (`Void`): No Content ### previewCustomerInformationChanges Customer information may change after an invoice is issued which may lead to a mismatch between customer information that are present on an open invoice and actual customer information. This endpoint allows to preview these differences, if any. The endpoint doesn't accept a request body. Customer information differences are calculated on the application side. #### Code Sample ```Http curl -X POST \ --url 'https://subdomain.chargify.com/invoices/uid0/customer_information/preview.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - uid (`String`): The unique identifier for the invoice, this does not refer to the public facing invoice number. #### Response Type - Customer Changes Preview Response #### Response Properties - response (`Customer Changes Preview Response`): OK ### updateCustomerInformation This endpoint 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 before. The endpoint doesn't accept a request body. Customer information differences are calculated on the application side. #### Code Sample ```Http curl -X PUT \ --url 'https://subdomain.chargify.com/invoices/uid0/customer_information.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - uid (`String`): The unique identifier for the invoice, this does not refer to the public facing invoice number. #### Response Type - Invoice #### Response Properties - response (`Invoice`): OK ### issueInvoice This endpoint allows you to issue an invoice that is in "pending" 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 subscription will be automatically applied. Additionally, if setting is on, an email will be sent for issued invoice. For Automatic subscriptions, prepayments and service credits will apply to the invoice and 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). #### Code Sample ```Http 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" }' ``` #### Request Parameters - uid (`String`): The unique identifier for the invoice, this does not refer to the public facing invoice number. - body (`Issue Invoice Request`) #### Response Type - Invoice #### Response Properties - response (`Invoice`): OK ## Offers ### createOffer Create an offer within your Advanced Billing site by sending a POST request. ## Documentation 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. Full documentation on how to use offers in the Advanced Billing UI can be located [here](https://maxio.zendesk.com/hc/en-us/articles/24261295098637-Offers-Overview). ## 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. #### Code Sample ```Http 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" ] } }' ``` #### Request Parameters - body (`Create Offer Request`) #### Response Type - Offer Response #### Response Properties - response (`Offer Response`): Created ### listOffers This endpoint will list offers for a site. #### Code Sample ```Http 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' ``` #### Request Parameters - page (`Number`): 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`. - per_page (`Number`): 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`. - include_archived (`Boolean`): Include archived products. Use in query: `include_archived=true`. #### Response Type - List Offers Response #### Response Properties - response (`List Offers Response`): OK ### readOffer This method allows you to list a specific offer's attributes. This is different than list all offers for a site, as it requires an `offer_id`. #### Code Sample ```Http curl -X GET \ --url 'https://subdomain.chargify.com/offers/130.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - offer_id (`Number`): The Chargify id of the offer #### Response Type - Offer Response #### Response Properties - response (`Offer Response`): OK ### archiveOffer Archive an existing offer. Please provide an `offer_id` in order to archive the correct item. #### Code Sample ```Http curl -X PUT \ --url 'https://subdomain.chargify.com/offers/130/archive.json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - offer_id (`Number`): The Chargify id of the offer #### Response Type - Void #### Response Properties - response (`Void`): OK ### unarchiveOffer Unarchive a previously archived offer. Please provide an `offer_id` in order to un-archive the correct item. #### Code Sample ```Http curl -X PUT \ --url 'https://subdomain.chargify.com/offers/130/unarchive.json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - offer_id (`Number`): The Chargify id of the offer #### Response Type - Void #### Response Properties - response (`Void`): OK ## Payment Profiles ### createPaymentProfile 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 [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) + [Chargify.js](https://docs.maxio.com/hc/en-us/articles/38163190843789-Chargify-js-Overview) + [Chargify.js with GoCardless - minimal example](https://docs.maxio.com/hc/en-us/articles/38206331271693-Examples#h_01K0PJ15QQZKCER8CFK40MR6XJ) + [Chargify.js with GoCardless - full example](https://docs.maxio.com/hc/en-us/articles/38206331271693-Examples#h_01K0PJ15QR09JVHWW0MCA7HVJV) + [Chargify.js with Stripe Direct Debit - minimal example](https://docs.maxio.com/hc/en-us/articles/38206331271693-Examples#h_01K0PJ15QQFKKN8Z7B7DZ9AJS5) + [Chargify.js with Stripe Direct Debit - full example](https://docs.maxio.com/hc/en-us/articles/38206331271693-Examples#h_01K0PJ15QRECQQ4ECS3ZA55GY7) + [Chargify.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) + [Chargify.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 Authentication during payment profile creation. When a payment requires 3D Secure Authentication to adhear to Strong Customer Authentication (SCA) during payment profile creation, the request enters a [post-authentication flow](https://maxio.zendesk.com/hc/en-us/articles/24176278996493-Testing-Implementing-3D-Secure#psd2-flows-pre-authentication-and-post-authentication). In this case, a 422 Unprocessable Entity status is returned with the following response: ```json { "jsonapi": { "version": "1.0" }, "errors": [ { "title": "This card requires 3DSecure verification.", "detail": "This card requires 3D secure authentication. Redirect the customer to the URL from the action_link attribute to authenticate. Attach callback_url param to this URL if you want to be notified about the result of 3D Secure authentication. Attach redirect_url param to this URL if you want to redirect a customer back to your page after 3D Secure authentication. Example: https://checkout-test.chargifypay.test/3d-secure/checkout/pay_uerzhsxd5uhkbodx5jhvkg6yeu?one_time_token_id=93&callback_url=http://localhost:4000&redirect_url=https://yourpage.com will do a POST request to https://localhost:4000 after credit card is authenticated and will redirect a customer to https://yourpage.com after 3DS authentication.", "links": { "action_link": "https://checkout-test.chargifypay.test/3d-secure/checkout/pay_uerzhsxd5uhkbodx5jhvkg6yeu?one_time_token_id=93" } } ] } ``` To let the customer go through 3D Secure Authentication, they need to be redirected to the URL specified in `action_link`. Optionally, you can specify the `callback_url` parameter in the `action_link` URL to receive notification about the result of 3D Secure Authentication. The `callback_url` will return the following information: - whether the authentication was successful (`success`) - the payment profile ID (`payment_profile_id`) You can also specify a `redirect_url` parameter in the `action_link` URL to redirect the customer back to your site. You cannot use action_link in an iframe inside a custom application. You must redirect the customer directly to the `action_link` and use the `redirect_url` or `callback_url` to be notified of the result. The final URL that you send a customer to complete 3D Secure may resemble the following, where the first half is the `action_link` and the second half contains a `redirect_url` and `callback_url`: `https://checkout-test.chargifypay.test/3d-secure/checkout/pay_uerzhsxd5uhkbodx5jhvkg6yeu?one_time_token_id=93&callback_url=http://localhost:4000&redirect_url=https://yourpage.com` ### Example Redirect Flow Here's an example flow to redirect customers to different pages depending on whether SCA was performed successfully: 1. Create a payment profile via the API; it requires 3DS. 2. You receive an `action_link` in the response. 3. Use this `action_link` to, for example, connect with your internal resources or generate a `session_id`. 4. Include one of those attributes inside the `callback_url` and `redirect_url` to be aware which “session” this applies to. 5. Redirect the customer to the `action_link` with `callback_url` and `redirect_url` applied 6. After the customer completes 3DS authentication, we notify you of the result via the applied `callback_url`. 7. After that, we redirect the customer to the `redirect_url`; at this point the result of authentication is known. 8. Optionally, you can use the applied "msg" param in the `redirect_url` to determine if the redirect was successful. #### Code Sample ```Http 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" } }' ``` #### Request Parameters - body (`Create Payment Profile Request`): 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 - Payment Profile Response #### Response Properties - response (`Payment Profile Response`): OK ### listPaymentProfiles This method will return all of the active `payment_profiles` for a Site, or for one Customer within a site. If no payment profiles are found, this endpoint will return an empty array, not a 404. #### Code Sample ```Http 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' ``` #### Request Parameters - page (`Number`): 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`. - per_page (`Number`): 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`. - customer_id (`Number`): The ID of the customer for which you wish to list payment profiles #### Response Type - array #### Response Properties - response (`array`): OK ### readPaymentProfile Using the GET method you can retrieve 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 } } ``` #### Code Sample ```Http curl -X GET \ --url 'https://subdomain.chargify.com/payment_profiles/198.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - payment_profile_id (`Number`): The Chargify id of the payment profile #### Response Type - Payment Profile Response #### Response Properties - response (`Payment Profile Response`): OK ### updatePaymentProfile ## 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. #### Code Sample ```Http 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" } }' ``` #### Request Parameters - payment_profile_id (`Number`): The Chargify id of the payment profile - body (`Update Payment Profile Request`) #### Response Type - Payment Profile Response #### Response Properties - response (`Payment Profile Response`): OK ### deleteUnusedPaymentProfile Deletes an unused payment profile. If the payment profile is in use by one or more subscriptions or groups, a 422 and error message will be returned. #### Code Sample ```Http curl -X DELETE \ --url 'https://subdomain.chargify.com/payment_profiles/198.json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - payment_profile_id (`Number`): The Chargify id of the payment profile #### Response Type - Void #### Response Properties - response (`Void`): No Content ### deleteSubscriptionsPaymentProfile This will delete a payment profile belonging to the customer on the subscription. + If the customer has multiple subscriptions, the payment profile will be removed from all of them. + If you delete the default payment profile for a subscription, you will 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). #### Code Sample ```Http curl -X DELETE \ --url 'https://subdomain.chargify.com/subscriptions/222/payment_profiles/198.json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - payment_profile_id (`Number`): The Chargify id of the payment profile #### Response Type - Void #### Response Properties - response (`Void`): No Content ### verifyBankAccount Submit the two small deposit amounts the customer received in their bank account in order to verify the bank account. (Stripe only) #### Code Sample ```Http 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 } }' ``` #### Request Parameters - bank_account_id (`Number`): Identifier of the bank account in the system. - body (`Bank Account Verification Request`) #### Response Type - Bank Account Response #### Response Properties - response (`Bank Account Response`): OK ### deleteSubscriptionGroupPaymentProfile This will delete 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. #### Code Sample ```Http curl -X DELETE \ --url 'https://subdomain.chargify.com/subscription_groups/uid0/payment_profiles/198.json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - uid (`String`): The uid of the subscription group - payment_profile_id (`Number`): The Chargify id of the payment profile #### Response Type - Void #### Response Properties - response (`Void`): No Content ### changeSubscriptionDefaultPaymentProfile This will change the default payment profile on the subscription to the existing payment profile with the id specified. 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. #### Code Sample ```Http curl -X POST \ --url 'https://subdomain.chargify.com/subscriptions/222/payment_profiles/198/change_payment_profile.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - payment_profile_id (`Number`): The Chargify id of the payment profile #### Response Type - Payment Profile Response #### Response Properties - response (`Payment Profile Response`): Created ### changeSubscriptionGroupDefaultPaymentProfile This will change the default payment profile on the subscription group to the existing payment profile with the id specified. 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. #### Code Sample ```Http 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' ``` #### Request Parameters - uid (`String`): The uid of the subscription group - payment_profile_id (`Number`): The Chargify id of the payment profile #### Response Type - Payment Profile Response #### Response Properties - response (`Payment Profile Response`): Created ### readOneTimeToken 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). #### Code Sample ```Http curl -X GET \ --url 'https://subdomain.chargify.com/one_time_tokens/chargify_token8.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - chargify_token (`String`): Advanced Billing Token #### Response Type - Get One Time Token Request #### Response Properties - response (`Get One Time Token Request`): OK ### sendRequestUpdatePaymentEmail You can send 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. #### Code Sample ```Http curl -X POST \ --url 'https://subdomain.chargify.com/subscriptions/222/request_payment_profiles_update.json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription #### Response Type - Void #### Response Properties - response (`Void`): Created ## Product Families ### listProductsForProductFamily Retrieves a list of Products belonging to a Product Family. #### Code Sample ```Http 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' ``` #### Request Parameters - product_family_id (`String`): Either the product family's id or its handle prefixed with `handle:` - page (`Number`): 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`. - per_page (`Number`): 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`. - date_field (`Basic Date Field`): The type of filter you would like to apply to your search. Use in query: `date_field=created_at`. - filter (`List Products Filter`): Filter to use for List Products operations - start_date (`Date`): 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`): 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`): 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`): 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`): Include archived products - include (`List Products Include`): Allows including additional data in the response. Use in query `include=prepaid_product_price_point`. #### Response Type - array #### Response Properties - response (`array`): OK ### createProductFamily Creates a Product Family within your Advanced Billing 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). #### Code Sample ```Http 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" } }' ``` #### Request Parameters - body (`Create Product Family Request`) #### Response Type - Product Family Response #### Response Properties - response (`Product Family Response`): Created ### listProductFamilies Retrieve a list of Product Families for a site. #### Code Sample ```Http curl -X GET -G \ --url 'https://subdomain.chargify.com/product_families.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' \ -d 'date_field=updated_at' ``` #### Request Parameters - date_field (`Basic Date Field`): The type of filter you would like to apply to your search. Use in query: `date_field=created_at`. - start_date (`Date`): 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`): 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`): 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`): 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 - array #### Response Properties - response (`array`): OK ### readProductFamily 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. #### Code Sample ```Http curl -X GET \ --url 'https://subdomain.chargify.com/product_families/112.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - id (`Number`): The Advanced Billing id of the product family #### Response Type - Product Family Response #### Response Properties - response (`Product Family Response`): OK ## Products ### createProduct Creates a product in your Advanced Billing site. See the following product docuemation for more information: + [Products Documentation](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) #### Code Sample ```Http 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" } }' ``` #### Request Parameters - product_family_id (`String`): Either the product family's id or its handle prefixed with `handle:` - body (`Create or Update Product Request`) #### Response Type - Product Response #### Response Properties - response (`Product Response`): Created ### readProduct Reads the current details of a product. #### Code Sample ```Http curl -X GET \ --url 'https://subdomain.chargify.com/products/202.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - product_id (`Number`): The Advanced Billing id of the product #### Response Type - Product Response #### Response Properties - response (`Product Response`): OK ### updateProduct 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. #### Code Sample ```Http curl -X PUT \ --url 'https://subdomain.chargify.com/products/202.json' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - product_id (`Number`): The Advanced Billing id of the product - body (`Create or Update Product Request`) #### Response Type - Product Response #### Response Properties - response (`Product Response`): OK ### archiveProduct Archives the product. All current subscribers will be unffected; 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. #### Code Sample ```Http curl -X DELETE \ --url 'https://subdomain.chargify.com/products/202.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - product_id (`Number`): The Advanced Billing id of the product #### Response Type - Product Response #### Response Properties - response (`Product Response`): OK ### readProductByHandle Retrieves a Product object by its `api_handle`. #### Code Sample ```Http curl -X GET \ --url 'https://subdomain.chargify.com/products/handle/api_handle6.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - api_handle (`String`): The handle of the product #### Response Type - Product Response #### Response Properties - response (`Product Response`): OK ### listProducts This method allows to retrieve a list of Products belonging to a Site. #### Code Sample ```Http 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' ``` #### Request Parameters - date_field (`Basic Date Field`): The type of filter you would like to apply to your search. Use in query: `date_field=created_at`. - filter (`List Products Filter`): Filter to use for List Products operations - end_date (`Date`): 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`): 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`): 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`): 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`): 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`. - per_page (`Number`): 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`. - include_archived (`Boolean`): Include archived products. Use in query: `include_archived=true`. - include (`List Products Include`): Allows including additional data in the response. Use in query `include=prepaid_product_price_point`. #### Response Type - array #### Response Properties - response (`array`): OK ## Product: Price Points ### createProductPricePoint 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. #### Code Sample ```Http 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" } }' ``` #### Request Parameters - product_id (`Number | String`): The id or handle of the product. When using the handle, it must be prefixed with `handle:` - body (`Create Product Price Point Request`) #### Response Type - Product Price Point Response #### Response Properties - response (`Product Price Point Response`): Created ### listProductPricePoints Retrieves a list of product price points. #### Code Sample ```Http 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')' ``` #### Request Parameters - product_id (`Number | String`): The id or handle of the product. When using the handle, it must be prefixed with `handle:` - page (`Number`): 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`. - per_page (`Number`): 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. - currency_prices (`Boolean`): When fetching a product's price points, if you have defined multiple currencies at the site level, you can optionally pass the ?currency_prices=true query param 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`): Use in query: `filter[type]=catalog,default`. - archived (`Boolean`): Set to include archived price points in the response. #### Response Type - List Product Price Points Response #### Response Properties - response (`List Product Price Points Response`): OK ### updateProductPricePoint Updates a product price point. Note: Custom product price points cannot be updated. #### Code Sample ```Http 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 } }' ``` #### Request Parameters - product_id (`Number | String`): 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`): 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`) #### Response Type - Product Price Point Response #### Response Properties - response (`Product Price Point Response`): OK ### readProductPricePoint Use this endpoint to retrieve details for a specific product price point. You can achieve this by using either the product price point ID or handle. #### Code Sample ```Http curl -X GET -G \ --url 'https://subdomain.chargify.com/products/124/price_points/188.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - product_id (`Number | String`): 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`): 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`): When fetching a product's price points, if you have defined multiple currencies at the site level, you can optionally pass the ?currency_prices=true query param 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 - Product Price Point Response #### Response Properties - response (`Product Price Point Response`): OK ### archiveProductPricePoint Archives a product price point. #### Code Sample ```Http curl -X DELETE \ --url 'https://subdomain.chargify.com/products/124/price_points/188.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - product_id (`Number | String`): 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`): 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 - Product Price Point Response #### Response Properties - response (`Product Price Point Response`): OK ### unarchiveProductPricePoint Use this endpoint to unarchive an archived product price point. #### Code Sample ```Http curl -X PATCH \ --url 'https://subdomain.chargify.com/products/202/price_points/10/unarchive.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - product_id (`Number`): The Advanced Billing id of the product to which the price point belongs - price_point_id (`Number`): The Advanced Billing id of the product price point #### Response Type - Product Price Point Response #### Response Properties - response (`Product Price Point Response`): OK ### promoteProductPricePointToDefault 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. #### Code Sample ```Http curl -X PATCH \ --url 'https://subdomain.chargify.com/products/202/price_points/10/default.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - product_id (`Number`): The Advanced Billing id of the product to which the price point belongs - price_point_id (`Number`): The Advanced Billing id of the product price point #### Response Type - Product Response #### Response Properties - response (`Product Response`): OK ### bulkCreateProductPricePoints Creates multiple product price points in one request. #### Code Sample ```Http 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" } ] }' ``` #### Request Parameters - product_id (`Number`): The Advanced Billing id of the product to which the price points belong - body (`Bulk Create Product Price Points Request`) #### Response Type - Bulk Create Product Price Points Response #### Response Properties - response (`Bulk Create Product Price Points Response`): Created ### createProductCurrencyPrices 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. #### Code Sample ```Http 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" } ] }' ``` #### Request Parameters - product_price_point_id (`Number`): The Advanced Billing id of the product price point - body (`Create Product Currency Prices Request`) #### Response Type - Currency Prices Response #### Response Properties - response (`Currency Prices Response`): OK ### updateProductCurrencyPrices 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. #### Code Sample ```Http 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 } ] }' ``` #### Request Parameters - product_price_point_id (`Number`): The Advanced Billing id of the product price point - body (`Update Currency Prices Request`) #### Response Type - Currency Prices Response #### Response Properties - response (`Currency Prices Response`): OK ### listAllProductPricePoints This method allows retrieval of a list of Products Price Points belonging to a Site. #### Code Sample ```Http 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' ``` #### Request Parameters - direction (`Sorting Direction`): Controls the order in which results are returned. Use in query `direction=asc`. - filter (`List Price Points Filter`): Filter to use for List PricePoints operations - include (`List Products Price Points Include`): Allows including additional data in the response. Use in query: `include=currency_prices`. - page (`Number`): 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`. - per_page (`Number`): 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`. #### Response Type - List Product Price Points Response #### Response Properties - response (`List Product Price Points Response`): OK ## Proforma Invoices ### createConsolidatedProformaInvoice This endpoint will trigger the creation of a consolidated proforma invoice asynchronously. It will return a 201 with no message, or a 422 with any errors. To find and view the new consolidated proforma invoice, you may poll the subscription group listing for proforma invoices; only one consolidated proforma invoice may 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. #### Code Sample ```Http curl -X POST \ --url 'https://subdomain.chargify.com/subscription_groups/uid0/proforma_invoices.json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - uid (`String`): The uid of the subscription group #### Response Type - Void #### Response Properties - response (`Void`): Created ### listSubscriptionGroupProformaInvoices Only proforma invoices with a `consolidation_level` of parent are returned. 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. #### Code Sample ```Http 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' ``` #### Request Parameters - uid (`String`): The uid of the subscription group - line_items (`Boolean`): Include line items data - discounts (`Boolean`): Include discounts data - taxes (`Boolean`): Include taxes data - credits (`Boolean`): Include credits data - payments (`Boolean`): Include payments data - custom_fields (`Boolean`): Include custom fields data #### Response Type - List Proforma Invoices Response #### Response Properties - response (`List Proforma Invoices Response`): OK ### readProformaInvoice Use this endpoint to read the details of an existing proforma invoice. ## Restrictions Proforma invoices are only available on Relationship Invoicing sites. #### Code Sample ```Http curl -X GET \ --url 'https://subdomain.chargify.com/proforma_invoices/proforma_invoice_uid4.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - proforma_invoice_uid (`String`): The uid of the proforma invoice #### Response Type - Proforma Invoice #### Response Properties - response (`Proforma Invoice`): OK ### createProformaInvoice This endpoint will create a proforma invoice and return 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. #### Code Sample ```Http curl -X POST \ --url 'https://subdomain.chargify.com/subscriptions/222/proforma_invoices.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription #### Response Type - Proforma Invoice #### Response Properties - response (`Proforma Invoice`): OK ### listProformaInvoices By default, proforma invoices returned on the index will 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`. #### Code Sample ```Http 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' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - start_date (`String`): The beginning date range for the invoice's Due Date, in the YYYY-MM-DD format. - end_date (`String`): The ending date range for the invoice's Due Date, in the YYYY-MM-DD format. - status (`Proforma Invoice Status`): The current status of the invoice. Allowed Values: draft, open, paid, pending, voided - page (`Number`): 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`. - per_page (`Number`): 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`. - direction (`Direction`): The sort direction of the returned invoices. - line_items (`Boolean`): Include line items data - discounts (`Boolean`): Include discounts data - taxes (`Boolean`): Include taxes data - credits (`Boolean`): Include credits data - payments (`Boolean`): Include payments data - custom_fields (`Boolean`): Include custom fields data #### Response Type - List Proforma Invoices Response #### Response Properties - response (`List Proforma Invoices Response`): OK ### voidProformaInvoice This endpoint will void 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. #### Code Sample ```Http 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' ``` #### Request Parameters - proforma_invoice_uid (`String`): The uid of the proforma invoice - body (`Void Invoice Request`) #### Response Type - Proforma Invoice #### Response Properties - response (`Proforma Invoice`): OK ### previewProformaInvoice Return a preview of 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. #### Code Sample ```Http curl -X POST \ --url 'https://subdomain.chargify.com/subscriptions/222/proforma_invoices/preview.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription #### Response Type - Proforma Invoice #### Response Properties - response (`Proforma Invoice`): OK ### createSignupProformaInvoice This endpoint is only available for Relationship Invoicing sites. It cannot be used to create consolidated proforma invoices or preview prepaid subscriptions. Create a proforma invoice to preview costs before a subscription's signup. 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. #### Code Sample ```Http 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" } } }' ``` #### Request Parameters - body (`Create Subscription Request`) #### Response Type - Proforma Invoice #### Response Properties - response (`Proforma Invoice`): Created ### previewSignupProformaInvoice This endpoint is only available for Relationship Invoicing sites. It cannot be used to create consolidated proforma invoice previews or preview prepaid subscriptions. Create a signup preview in the format of a proforma invoice to preview costs before a subscription's signup. You have the option of optionally 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. #### Code Sample ```Http 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" } } }' ``` #### Request Parameters - include (`Create Signup Proforma Preview Include`): Choose to include a proforma invoice preview for the first renewal. Use in query `include=next_proforma_invoice`. - body (`Create Subscription Request`) #### Response Type - Signup Proforma Preview Response #### Response Properties - response (`Signup Proforma Preview Response`): Created ## Reason Codes ### createReasonCode # Reason Codes Intro ReasonCodes 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. ## Reason Code Documentation Full documentation on how Reason Codes operate within Advanced Billing can be located under the following links. [Churn Reason Codes](https://maxio.zendesk.com/hc/en-us/articles/24286647554701-Churn-Reason-Codes) ## Create Reason Code This method gives a merchant the option to create a reason codes for a given Site. #### Code Sample ```Http 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 } }' ``` #### Request Parameters - body (`Create Reason Code Request`) #### Response Type - Reason Code Response #### Response Properties - response (`Reason Code Response`): OK ### listReasonCodes This method gives a merchant the option to retrieve a list of all of the current churn codes for a given site. #### Code Sample ```Http 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' ``` #### Request Parameters - page (`Number`): 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`. - per_page (`Number`): 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`. #### Response Type - array #### Response Properties - response (`array`): OK ### readReasonCode This method gives a merchant the option to retrieve a list of a particular code for a given Site by providing the unique numerical ID of the code. #### Code Sample ```Http curl -X GET \ --url 'https://subdomain.chargify.com/reason_codes/32.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - reason_code_id (`Number`): The Advanced Billing id of the reason code #### Response Type - Reason Code Response #### Response Properties - response (`Reason Code Response`): OK ### updateReasonCode This method gives a merchant the option to update an existing reason code for a given site. #### Code Sample ```Http curl -X PUT \ --url 'https://subdomain.chargify.com/reason_codes/32.json' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - reason_code_id (`Number`): The Advanced Billing id of the reason code - body (`Update Reason Code Request`) #### Response Type - Reason Code Response #### Response Properties - response (`Reason Code Response`): OK ### deleteReasonCode This method gives a merchant the option to delete one reason code from the Churn Reason Codes. This code will be immediately removed. This action is not reversible. #### Code Sample ```Http curl -X DELETE \ --url 'https://subdomain.chargify.com/reason_codes/32.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - reason_code_id (`Number`): The Advanced Billing id of the reason code #### Response Type - Ok Response #### Response Properties - response (`Ok Response`): OK ## Referral Codes ### validateReferralCode Use this method to determine if the referral code is valid and applicable within your Site. This method is useful for validating referral codes that are entered by a customer. ## Referrals Documentation Full documentation on how to use the referrals feature in the Advanced Billing UI can be located [here](https://maxio.zendesk.com/hc/en-us/sections/24286965611405-Referrals). ## Server Response If the referral code is valid the status code will be `200` and the referral code will be returned. If the referral code is invalid, a `404` response will be returned. #### Code Sample ```Http curl -X GET -G \ --url 'https://subdomain.chargify.com/referral_codes/validate.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' \ -d 'code=code8' ``` #### Request Parameters - code (`String`): The referral code you are trying to validate #### Response Type - Referral Validation Response #### Response Properties - response (`Referral Validation Response`): OK ## Sales Commissions ### listSalesCommissionSettings Endpoint returns 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` #### Code Sample ```Http 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' ``` #### Request Parameters - seller_id (`String`): The Chargify id of your seller account - Authorization (`String`): For authorization use user API key. See details [here](https://developers.chargify.com/docs/developer-docs/ZG9jOjMyNzk5NTg0-2020-04-20-new-api-authentication). - live_mode (`Boolean`): This parameter indicates if records should be fetched from live mode sites. Default value is true. - page (`Number`): 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`. - per_page (`Number`): This parameter indicates how many records to fetch in each request. Default value is 100. #### Response Type - array #### Response Properties - response (`array`): OK ### listSalesReps Endpoint returns sales rep list 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` #### Code Sample ```Http 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' ``` #### Request Parameters - seller_id (`String`): The Chargify id of your seller account - Authorization (`String`): For authorization use user API key. See details [here](https://developers.chargify.com/docs/developer-docs/ZG9jOjMyNzk5NTg0-2020-04-20-new-api-authentication). - live_mode (`Boolean`): This parameter indicates if records should be fetched from live mode sites. Default value is true. - page (`Number`): 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`. - per_page (`Number`): This parameter indicates how many records to fetch in each request. Default value is 100. #### Response Type - array #### Response Properties - response (`array`): OK ### readSalesRep Endpoint returns sales rep and attached subscriptions 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` #### Code Sample ```Http 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' ``` #### Request Parameters - seller_id (`String`): The Chargify id of your seller account - sales_rep_id (`String`): The Advanced Billing id of sales rep. - Authorization (`String`): For authorization use user API key. See details [here](https://developers.chargify.com/docs/developer-docs/ZG9jOjMyNzk5NTg0-2020-04-20-new-api-authentication). - live_mode (`Boolean`): This parameter indicates if records should be fetched from live mode sites. Default value is true. - page (`Number`): 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`. - per_page (`Number`): This parameter indicates how many records to fetch in each request. Default value is 100. #### Response Type - Sale Rep #### Response Properties - response (`Sale Rep`): OK ## Sites ### readSite This endpoint allows you to fetch some site data. Full documentation on Sites in the Advanced Billing UI can be located [here](https://maxio.zendesk.com/hc/en-us/sections/24250550707085-Sites). Specifically, the [Clearing Site Data](https://maxio.zendesk.com/hc/en-us/articles/24250617028365-Clearing-Site-Data) section is extremely relevant to this endpoint documentation. #### Relationship invoicing enabled If site has RI enabled then you will see more settings like: "customer_hierarchy_enabled": true, "whopays_enabled": true, "whopays_default_payer": "self" You can read more about these settings here: [Who Pays & Customer Hierarchy](https://maxio.zendesk.com/hc/en-us/articles/24252185211533-Customer-Hierarchies-WhoPays) #### Code Sample ```Http curl -X GET \ --url 'https://subdomain.chargify.com/site.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Response Type - Site Response #### Response Properties - response (`Site Response`): OK ### clearSite 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.** #### Code Sample ```Http curl -X POST -G \ --url 'https://subdomain.chargify.com/sites/clear_data.json' \ -u 'BasicAuthUserName:BasicAuthPassword' \ -d 'cleanup_scope=all' ``` #### Request Parameters - cleanup_scope (`Cleanup Scope`): `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`. #### Response Type - Void #### Response Properties - response (`Void`): OK ### listChargifyJsPublicKeys This endpoint returns public keys used for Chargify.js. #### Code Sample ```Http 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' ``` #### Request Parameters - page (`Number`): 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`. - per_page (`Number`): 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`. #### Response Type - List Public Keys Response #### Response Properties - response (`List Public Keys Response`): OK ## Subscriptions ### createSubscription Creates a Subscription for a customer and product Specify the product with `product_id` or `product_handle`. To set a specific product pricepPoint, 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. 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]($e/Payment%20Profiles/createPaymentProfile) endpoint for details on payment parameters. Do not use real card information for testing. See the Sites articles that cover [testing your site setup](https://docs.maxio.com/hc/en-us/articles/24250712113165-Testing-Overview#testing-overview-0-0) for more details on testing in your sandbox. Note that collecting and sending raw card details in production requires [PCI compliance](https://docs.maxio.com/hc/en-us/articles/24183956938381-PCI-Compliance#pci-compliance-0-0) on your end. If your business is not PCI compliant, use [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 [Subscription Signups](page:introduction/basic-concepts/subscription-signup) article for more information on working with subscriptions in Advanced Billing. #### Code Sample ```Http 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" } }' ``` #### Request Parameters - body (`Create Subscription Request`) #### Response Type - Subscription Response #### Response Properties - response (`Subscription Response`): Created ### listSubscriptions This method will return an array of subscriptions from a Site. Pay close attention to query string filters and pagination in order to control responses from the server. ## 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. #### Code Sample ```Http 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 'start_date=2022-07-01' \ -d 'end_date=2022-08-01' \ -d 'start_datetime=2022-07-01+09%3A00%3A05' \ -d 'end_datetime=2022-08-01+10%3A00%3A05' \ -d 'sort=signup_date' \ -d 'include[]=self_service_page_token' ``` #### Request Parameters - page (`Number`): 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`. - per_page (`Number`): 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`. - state (`Subscription State Filter`): The current state of the subscription - product (`Number`): The product id of the subscription. (Note that the product handle cannot be used.) - product_price_point_id (`Number`): The ID of the product price point. If supplied, product is required - coupon (`Number`): 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`): The coupon code currently applied to the subscription - date_field (`Subscription Date Field`): 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`): 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`): 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`): 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`): 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`): The value of the metadata field specified in the parameter. Use in query `metadata[my-field]=value&metadata[other-field]=another_value`. - direction (`Sorting Direction`): Controls the order in which results are returned. Use in query `direction=asc`. - sort (`Subscription Sort`): The attribute by which to sort - include (`array`): Allows including additional data in the response. Use in query: `include[]=self_service_page_token`. #### Response Type - array #### Response Properties - response (`array`): OK ### updateSubscription 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 subscrption. ### 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 he 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 original `snap_day`. The `snap_day`will will reset to 'null on the next billing cycle. This is because a product change is instantanous and only affects the product associated with a subscription. #### Code Sample ```Http 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" } }' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - body (`Update Subscription Request`) #### Response Type - Subscription Response #### Response Properties - response (`Subscription Response`): OK ### readSubscription Use this endpoint to find subscription details. ## 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. #### Code Sample ```Http 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' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - include (`array`): Allows including additional data in the response. Use in query: `include[]=coupons&include[]=self_service_page_token`. #### Response Type - Subscription Response #### Response Properties - response (`Subscription Response`): OK ### overrideSubscription This API endpoint allows you to set certain subscription fields that are usually managed for you 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. #### Code Sample ```Http 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" } }' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - body (`Override Subscription Request`): Only these fields are available to be set. #### Response Type - Void #### Response Properties - response (`Void`): No Content ### findSubscription Use this endpoint to find a subscription by its reference. #### Code Sample ```Http curl -X GET -G \ --url 'https://subdomain.chargify.com/subscriptions/lookup.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - reference (`String`): Subscription reference #### Response Type - Subscription Response #### Response Properties - response (`Subscription Response`): OK ### purgeSubscription For sites in test mode, you may purge individual subscriptions. 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` #### Code Sample ```Http 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' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - ack (`Number`): id of the customer. - cascade (`array`): Options are "customer" or "payment_profile". Use in query: `cascade[]=customer&cascade[]=payment_profile`. #### Response Type - Subscription Response #### Response Properties - response (`Subscription Response`): OK ### updatePrepaidSubscriptionConfiguration Use this endpoint to update a subscription's prepaid configuration. #### Code Sample ```Http 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 } }' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - body (`Upsert Prepaid Configuration Request`) #### Response Type - Prepaid Configuration Response #### Response Properties - response (`Prepaid Configuration Response`): OK ### previewSubscription The Chargify API allows you to preview 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. A subscription will not be created by utilizing this endpoint; it is meant to serve as a prediction. For more information, see our documentation [here](https://maxio.zendesk.com/hc/en-us/articles/24252493695757-Subscriber-Interface-Overview). ## Taxable Subscriptions This endpoint will preview taxes applicable to a purchase. In order 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 in order to calculate tax For more information about creating taxable previews, see our documentation guide on how to create [taxable subscriptions.](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 in Advanced Billing. The billing address and the credit card information are stored together within the payment profile object. Also, you may not send a billing address to Advanced Billing 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 may leave off the billing information. #### Code Sample ```Http 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" } }' ``` #### Request Parameters - body (`Create Subscription Request`) #### Response Type - Subscription Preview Response #### Response Properties - response (`Subscription Preview Response`): OK ### applyCouponsToSubscription 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. #### Code Sample ```Http 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" ] }' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - code (`String`): A code for the coupon that would be applied to a subscription - body (`Add Coupons Request`) #### Response Type - Subscription Response #### Response Properties - response (`Subscription Response`): OK ### removeCouponFromSubscription Use this endpoint to remove a coupon from an existing subscription. For more information on the expected behaviour of removing a coupon from a subscription, See our documentation [here.](https://maxio.zendesk.com/hc/en-us/articles/24261259337101-Coupons-and-Subscriptions#removing-a-coupon) #### Code Sample ```Http curl -X DELETE -G \ --url 'https://subdomain.chargify.com/subscriptions/222/remove_coupon.json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - coupon_code (`String`): The coupon code #### Response Type - String #### Response Properties - response (`String`): OK ### activateSubscription Advanced Billing offers the ability to activate awaiting signup and trialing subscriptions. This feature is only available on the Relationship Invoicing architecture. Subscriptions in a group may not be activated immediately. For details on how the activation works, and how to activate subscriptions through the application, see [activation](#). The `revert_on_failure` parameter controls the behavior upon activation failure. - If set to `true` and something goes wrong i.e. payment fails, then Advanced Billing will not change the subscription's state. The subscription’s billing period will also remain the same. - If set to `false` and something goes wrong i.e. payment fails, then Advanced Billing will continue through with the activation and enter an end of life state. For trialing subscriptions, that will either be 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 will always be canceled. The default activation failure behavior can be configured per activation attempt, or you may 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 You can read more about the behavior of trialing subscriptions [here](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 will remain as Trialing, we will void the invoice from activation and return any prepayments and credits applied to the invoice back to the subscription. #### Code Sample ```Http curl -X PUT \ --url 'https://subdomain.chargify.com/subscriptions/222/activate.json' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - body (`Activate Subscription Request`) #### Response Type - Subscription Response #### Response Properties - response (`Subscription Response`): OK ## Subscription Components ### readSubscriptionComponent This request will list information regarding a specific component owned by a subscription. #### Code Sample ```Http curl -X GET \ --url 'https://subdomain.chargify.com/subscriptions/222/components/222.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - component_id (`Number`): The Advanced Billing id of the component. Alternatively, the component's handle prefixed by `handle:` #### Response Type - Subscription Component Response #### Response Properties - response (`Subscription Component Response`): OK ### listSubscriptionComponents This request will list 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. #### Code Sample ```Http 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' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - date_field (`Subscription List Date Field`): The type of filter you'd like to apply to your search. Use in query `date_field=updated_at`. - direction (`Sorting Direction`): Controls the order in which results are returned. Use in query `direction=asc`. - filter (`List Subscription Components Filter`): Filter to use for List Subscription Components operation - end_date (`String`): 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`): 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`): Allows fetching components allocation only if price point id is present. Use in query `price_point_ids=not_null`. - product_family_ids (`array`): 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`): The attribute by which to sort. Use in query `sort=updated_at`. - start_date (`String`): 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`): 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`): Allows including additional data in the response. Use in query `include=subscription,historic_usages`. - in_use (`Boolean`): 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 - array #### Response Properties - response (`array`): OK ### bulkUpdateSubscriptionComponentsPricePoints 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. #### Code Sample ```Http 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" } ] }' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - body (`Bulk Components Price Point Assignment`) #### Response Type - Bulk Components Price Point Assignment #### Response Properties - response (`Bulk Components Price Point Assignment`): OK ### bulkResetSubscriptionComponentsPricePoints 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. #### Code Sample ```Http curl -X POST \ --url 'https://subdomain.chargify.com/subscriptions/222/price_points/reset.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription #### Response Type - Subscription Response #### Response Properties - response (`Subscription Response`): Created ### allocateComponent This endpoint creates a new allocation, setting the current allocated quantity for the Component and recording a memo. **Notice**: Allocations can only be updated for Quantity, On/Off, and Prepaid Components. ## Allocations Documentation Full documentation on how to record Allocations in the Advanced Billing UI can be located [here](https://maxio.zendesk.com/hc/en-us/articles/24251883961485-Component-Allocations-Overview). It is focused on how allocations operate within the Advanced Billing UI.It goes into greater detail on how the user interface will react when recording allocations. This documentation also goes into greater detail on how proration is taken into consideration when applying component allocations. ## Proration Schemes Changing the allocated quantity of a component mid-period can result in either a Charge or Credit being applied to the subscription. When creating an allocation via the API, you can pass the `upgrade_charge`, `downgrade_credit`, and `accrue_charge` to be applied. **Notice:** These proration and accural fields will be ignored for Prepaid Components since this component type always generate charges immediately without proration. For background information on prorated components and upgrade/downgrade schemes, see [Setting Component Allocations.](https://maxio.zendesk.com/hc/en-us/articles/24251906165133-Component-Allocations-Proration). See the tables below for valid values. | upgrade_charge | Definition                                                        | |----------------|-------------------------------------------------------------------| | `full`         | A charge is added for the full price of the component.            | | `prorated`     | A charge is added for the prorated price of the component change. | | `none`         | No charge is added.                                               | | downgrade_credit | Definition                                        | |------------------|---------------------------------------------------| | `full`           | A full price credit is added for the amount owed. | | `prorated`       | A prorated credit is added for the amount owed.   | | `none`           | No charge is added.                               | | accrue_charge | Definition                                                                                               | |---------------|------------------------------------------------------------------------------------------------------------| | `true`        | Attempt to charge the customer at next renewal. | | `false`       | Attempt to charge the customer right away. If it fails, the charge will be accrued until the next renewal. | ### 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.** #### Code Sample ```Http 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": 5.0, "memo": "Recoding component purchase of Acme Support" } }' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - component_id (`Number`): The Advanced Billing id of the component - body (`Create Allocation Request`) #### Response Type - Allocation Response #### Response Properties - response (`Allocation Response`): OK ### listAllocations This endpoint returns 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. ## Querying data via Advanced Billing gem You can also query the current quantity via the [official Advanced Billing Gem.](http://github.com/chargify/chargify_api_ares) ```# First way component = Chargify::Subscription::Component.find(1, :params => {:subscription_id => 7}) puts component.allocated_quantity # => 23 # Second way component = Chargify::Subscription.find(7).component(1) puts component.allocated_quantity # => 23 ``` #### Code Sample ```Http 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' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - component_id (`Number`): The Advanced Billing id of the component - page (`Number`): 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`. #### Response Type - array #### Response Properties - response (`array`): OK ### allocateComponents Creates multiple allocations, setting the current allocated quantity for each of the components and recording a memo. 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. Be aware of the Order of Resolutions explained below in determining the proration scheme. A `component_id` is required for each allocation. This endpoint only responds to JSON. It is not available for XML. #### Code Sample ```Http 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" } ] }' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - body (`Allocate Components`) #### Response Type - array #### Response Properties - response (`array`): OK ### previewAllocations Advanced Billing offers the ability to preview 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. #### Code Sample ```Http 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" }' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - body (`Preview Allocations Request`) #### Response Type - Allocation Preview Response #### Response Properties - response (`Allocation Preview Response`): OK ### updatePrepaidUsageAllocationExpirationDate When the expiration interval options are selected on a prepaid usage component price point, all allocations will be created with an expiration date. 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. #### Code Sample ```Http 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" } }' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - component_id (`Number`): The Advanced Billing id of the component - allocation_id (`Number`): The Advanced Billing id of the allocation - body (`Update Allocation Expiration Date`) #### Response Type - Void #### Response Properties - response (`Void`): OK ### deletePrepaidUsageAllocation 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. #### Code Sample ```Http 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" }' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - component_id (`Number`): The Advanced Billing id of the component - allocation_id (`Number`): The Advanced Billing id of the allocation - body (`Credit Scheme Request`) #### Response Type - Void #### Response Properties - response (`Void`): OK ### createUsage 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 documention articles for more information: - [Create and Manage Components](https://maxio.zendesk.com/hc/en-us/articles/24261149711501-Create-Edit-and-Archive-Components). A - [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]($e/Subscription%20Components/readSubscriptionComponent) 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`. #### Code Sample ```Http 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" } }' ``` #### Request Parameters - subscription_id_or_reference (`Number | String`): 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`): Either the Advanced Billing id for the component or the component's handle prefixed by `handle:` - body (`Create Usage Request`) #### Response Type - Usage Response #### Response Properties - response (`Usage Response`): OK ### listUsages This request will return a list of the 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. #### Code Sample ```Http 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' ``` #### Request Parameters - subscription_id_or_reference (`Number | String`): 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`): Either the Advanced Billing id for the component or the component's handle prefixed by `handle:` - since_id (`Long`): Returns usages with an id greater than or equal to the one specified - max_id (`Long`): Returns usages with an id less than or equal to the one specified - since_date (`Date`): Returns usages with a created_at date greater than or equal to midnight (12:00 AM) on the date specified. - until_date (`Date`): Returns usages with a created_at date less than or equal to midnight (12:00 AM) on the date specified. - page (`Number`): 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`. - per_page (`Number`): 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`. #### Response Type - array #### Response Properties - response (`array`): OK ### activateEventBasedComponent In order to bill your subscribers on your Events data under the Events-Based Billing feature, the components must be activated for the subscriber. Learn more about the role of activation in the [Events-Based Billing docs](https://maxio.zendesk.com/hc/en-us/articles/24260323329805-Events-Based-Billing-Overview). Use this endpoint to activate an event-based component for a single subscription. Activating an event-based component causes Advanced Billing to bill 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.* #### Code Sample ```Http 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" } ] } }' ``` #### Request Parameters - subscription_id (`Number`): The Advanced Billing id of the subscription - component_id (`Number`): The Advanced Billing id of the component - body (`Activate Event-Based Component`) #### Response Type - Void #### Response Properties - response (`Void`): OK ### deactivateEventBasedComponent Use this endpoint to deactivate an event-based component for a single subscription. Deactivating the event-based component causes Advanced Billing to ignore related events at subscription renewal. #### Code Sample ```Http curl -X POST \ --url 'https://subdomain.chargify.com/event_based_billing/subscriptions/222/components/222/deactivate.json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - subscription_id (`Number`): The Advanced Billing id of the subscription - component_id (`Number`): The Advanced Billing id of the component #### Response Type - Void #### Response Properties - response (`Void`): OK ### recordEvent ## Documentation 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. Learn more about the feature in general in the [Events-Based Billing help docs](https://maxio.zendesk.com/hc/en-us/articles/24260323329805-Events-Based-Billing-Overview). ## Record Event Use this endpoint to record a single event. *Note: this endpoint differs from the standard Chargify API endpoints in that the URL subdomain will be `events` and your site subdomain will be included in the URL path. For example:* ``` https://events.chargify.com/my-site-subdomain/events/my-stream-api-handle ``` #### Code Sample ```Http 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" } } }' ``` #### Request Parameters - api_handle (`String`): Identifies the Stream for which the event should be published. - store_uid (`String`): If you've attached your own Keen project as an Advanced Billing event data-store, use this parameter to indicate the data-store. - body (`EBB Event`) #### Response Type - Void #### Response Properties - response (`Void`): Created ### bulkRecordEvents Use this endpoint to record a collection of events. *Note: this endpoint differs from the standard Chargify API endpoints in that the subdomain will be `events` and your site subdomain will be included in the URL path.* A maximum of 1000 events can be published in a single request. A 422 will be returned if this limit is exceeded. #### Code Sample ```Http 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" } } } ]' ``` #### Request Parameters - api_handle (`String`): Identifies the Stream for which the events should be published. - store_uid (`String`): If you've attached your own Keen project as an Advanced Billing event data-store, use this parameter to indicate the data-store. - body (`array`) #### Response Type - Void #### Response Properties - response (`Void`): Created ### listSubscriptionComponentsForSite This request will list components applied to each subscription. #### Code Sample ```Http 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' ``` #### Request Parameters - page (`Number`): 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`. - per_page (`Number`): 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`. - sort (`List Subscription Components Sort`): The attribute by which to sort. Use in query: `sort=updated_at`. - direction (`Sorting Direction`): Controls the order in which results are returned. Use in query `direction=asc`. - filter (`List Subscription Components for Site Filter`): Filter to use for List Subscription Components For Site operation - date_field (`Subscription List Date Field`): The type of filter you'd like to apply to your search. Use in query: `date_field=updated_at`. - start_date (`String`): 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`): 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`): 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`): 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`): Allows fetching components allocation with matching subscription id based on provided ids. Use in query `subscription_ids=1,2,3`. - price_point_ids (`Include Not Null`): Allows fetching components allocation only if price point id is present. Use in query `price_point_ids=not_null`. - product_family_ids (`array`): 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`): Allows including additional data in the response. Use in query `include=subscription,historic_usages`. #### Response Type - List Subscription Components Response #### Response Properties - response (`List Subscription Components Response`): OK ## Subscription Groups ### signupWithSubscriptionGroup Create multiple subscriptions at once under the same customer and consolidate 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 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 Chargify.js. #### Code Sample ```Http 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 } ] } }' ``` #### Request Parameters - body (`Subscription Group Signup Request`) #### Response Type - Subscription Group Signup Response #### Response Properties - response (`Subscription Group Signup Response`): Created ### createSubscriptionGroup Creates a subscription group with given members. #### Code Sample ```Http 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 ] } }' ``` #### Request Parameters - body (`Create Subscription Group Request`) #### Response Type - Subscription Group Response #### Response Properties - response (`Subscription Group Response`): OK ### listSubscriptionGroups Returns an array of 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. #### Code Sample ```Http 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' ``` #### Request Parameters - page (`Number`): 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`. - per_page (`Number`): 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`. - include (`array`): 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 - List Subscription Groups Response #### Response Properties - response (`List Subscription Groups Response`): OK ### readSubscriptionGroup Use this endpoint to find 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. #### Code Sample ```Http 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' ``` #### Request Parameters - uid (`String`): The uid of the subscription group - include (`array`): Allows including additional data in the response. Use in query: `include[]=current_billing_amount_in_cents`. #### Response Type - Full Subscription Group Response #### Response Properties - response (`Full Subscription Group Response`): OK ### updateSubscriptionGroupMembers Use this endpoint to update 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 subscription group. To clean up members, just leave the array empty. #### Code Sample ```Http 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 ] } }' ``` #### Request Parameters - uid (`String`): The uid of the subscription group - body (`Update Subscription Group Request`) #### Response Type - Subscription Group Response #### Response Properties - response (`Subscription Group Response`): OK ### deleteSubscriptionGroup Use this endpoint to delete subscription group. Only groups without members can be deleted #### Code Sample ```Http curl -X DELETE \ --url 'https://subdomain.chargify.com/subscription_groups/uid0.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - uid (`String`): The uid of the subscription group #### Response Type - Delete Subscription Group Response #### Response Properties - response (`Delete Subscription Group Response`): OK ### findSubscriptionGroup Use this endpoint to find subscription group associated with subscription. If the subscription is not in a group endpoint will return 404 code. #### Code Sample ```Http 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' ``` #### Request Parameters - subscription_id (`String`): The Advanced Billing id of the subscription associated with the subscription group #### Response Type - Full Subscription Group Response #### Response Properties - response (`Full Subscription Group Response`): OK ### addSubscriptionToGroup 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) #### Code Sample ```Http 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 } } }' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - body (`Add Subscription to a Group`) #### Response Type - Subscription Group Response #### Response Properties - response (`Subscription Group Response`): OK ### removeSubscriptionFromGroup 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 existing subscription from subscription group. #### Code Sample ```Http curl -X DELETE \ --url 'https://subdomain.chargify.com/subscriptions/222/group.json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription #### Response Type - Void #### Response Properties - response (`Void`): No Content ## Subscription Group Invoice Account ### createSubscriptionGroupPrepayment A prepayment can be added for a subscription group identified by the group's `uid`. This endpoint requires a `amount`, `details`, `method`, and `memo`. On success, the prepayment will be added to the group's prepayment balance. #### Code Sample ```Http 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' ``` #### Request Parameters - uid (`String`): The uid of the subscription group - body (`Subscription Group Prepayment Request`) #### Response Type - Subscription Group Prepayment Response #### Response Properties - response (`Subscription Group Prepayment Response`): OK ### listPrepaymentsForSubscriptionGroup This request will list a subscription group's prepayments. #### Code Sample ```Http 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' ``` #### Request Parameters - uid (`String`): The uid of the subscription group - page (`Number`): 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`. - per_page (`Number`): 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`. - filter (`List Prepayments Filter`): Filter to use for List Prepayments operations #### Response Type - List Subscription Group Prepayment Response #### Response Properties - response (`List Subscription Group Prepayment Response`): OK ### issueSubscriptionGroupServiceCredit Credit can be issued for a subscription group identified by the group's `uid`. 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. #### Code Sample ```Http 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" } }' ``` #### Request Parameters - uid (`String`): The uid of the subscription group - body (`Issue Service Credit Request`) #### Response Type - Service Credit Response #### Response Properties - response (`Service Credit Response`): OK ### deductSubscriptionGroupServiceCredit Credit can be deducted for a subscription group identified by the group's `uid`. Credit will be deducted from the group in the amount specified in the request body. #### Code Sample ```Http 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" } }' ``` #### Request Parameters - uid (`String`): The uid of the subscription group - body (`Deduct Service Credit Request`) #### Response Type - Service Credit #### Response Properties - response (`Service Credit`): Created ## Subscription Group Status ### cancelSubscriptionsInGroup 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. #### Code Sample ```Http 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 }' ``` #### Request Parameters - uid (`String`): The uid of the subscription group - body (`Cancel Grouped Subscriptions Request`) #### Response Type - Void #### Response Properties - response (`Void`): OK ### initiateDelayedCancellationForGroup This endpoint will schedule 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. #### Code Sample ```Http curl -X POST \ --url 'https://subdomain.chargify.com/subscription_groups/uid0/delayed_cancel.json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - uid (`String`): The uid of the subscription group #### Response Type - Void #### Response Properties - response (`Void`): OK ### cancelDelayedCancellationForGroup 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. #### Code Sample ```Http curl -X DELETE \ --url 'https://subdomain.chargify.com/subscription_groups/uid0/delayed_cancel.json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - uid (`String`): The uid of the subscription group #### Response Type - Void #### Response Properties - response (`Void`): OK ### reactivateSubscriptionGroup This endpoint will attempt to reactivate or resume 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. #### Code Sample ```Http 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 }' ``` #### Request Parameters - uid (`String`): The uid of the subscription group - body (`Reactivate Subscription Group Request`) #### Response Type - Reactivate Subscription Group Response #### Response Properties - response (`Reactivate Subscription Group Response`): OK ## Subscription Invoice Account ### readAccountBalances 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. #### Code Sample ```Http curl -X GET \ --url 'https://subdomain.chargify.com/subscriptions/222/account_balances.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription #### Response Type - Account Balances #### Response Properties - response (`Account Balances`): OK ### createPrepayment ## Create Prepayment 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. #### Code Sample ```Http 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" } }' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - body (`Create Prepayment Request`) #### Response Type - Create Prepayment Response #### Response Properties - response (`Create Prepayment Response`): Created ### listPrepayments This request will list a subscription's prepayments. #### Code Sample ```Http 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' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - page (`Number`): 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`. - per_page (`Number`): 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`. - filter (`List Prepayments Filter`): Filter to use for List Prepayments operations #### Response Type - Prepayments Response #### Response Properties - response (`Prepayments Response`): OK ### issueServiceCredit Credit will be added to the subscription in the amount specified in the request body. The credit is subsequently applied to the next generated invoice. #### Code Sample ```Http 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" } }' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - body (`Issue Service Credit Request`) #### Response Type - Service Credit #### Response Properties - response (`Service Credit`): Created ### deductServiceCredit Credit will be removed from the subscription in the amount specified in the request body. The credit amount being deducted must be equal to or less than the current credit balance. #### Code Sample ```Http 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" } }' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - body (`Deduct Service Credit Request`) #### Response Type - Void #### Response Properties - response (`Void`): OK ### listServiceCredits This request will list a subscription's service credits. #### Code Sample ```Http 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' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - page (`Number`): 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`. - per_page (`Number`): 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`. - direction (`Sorting Direction`): Controls the order in which results are returned. Use in query `direction=asc`. #### Response Type - List Service Credits Response #### Response Properties - response (`List Service Credits Response`): OK ### refundPrepayment This endpoint will refund, completely or partially, a particular prepayment applied to a subscription. 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`. #### Code Sample ```Http 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' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - prepayment_id (`Long`): id of prepayment - body (`Refund Prepayment Request`) #### Response Type - Prepayment Response #### Response Properties - response (`Prepayment Response`): Created ## Subscription Notes ### createSubscriptionNote Use the following method to create a note for a subscription. ## How to Use Subscription Notes 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 instead. Full documentation on how to use Notes in the Advanced Billing UI can be located [here](https://maxio.zendesk.com/hc/en-us/articles/24251712214413-Subscription-Summary-Overview). #### Code Sample ```Http 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 } }' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - body (`Update Subscription Note Request`) #### Response Type - Subscription Note Response #### Response Properties - response (`Subscription Note Response`): OK ### listSubscriptionNotes Use this method to retrieve a list of Notes associated with a Subscription. The response will be an array of Notes. #### Code Sample ```Http 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' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - page (`Number`): 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`. - per_page (`Number`): 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`. #### Response Type - array #### Response Properties - response (`array`): OK ### readSubscriptionNote Once you have obtained the ID of the note you wish to read, use this method to show a particular note attached to a subscription. #### Code Sample ```Http curl -X GET \ --url 'https://subdomain.chargify.com/subscriptions/222/notes/66.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - note_id (`Number`): The Advanced Billing id of the note #### Response Type - Subscription Note Response #### Response Properties - response (`Subscription Note Response`): OK ### updateSubscriptionNote Use the following method to update a note for a Subscription. #### Code Sample ```Http 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 } }' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - note_id (`Number`): The Advanced Billing id of the note - body (`Update Subscription Note Request`) #### Response Type - Subscription Note Response #### Response Properties - response (`Subscription Note Response`): OK ### deleteSubscriptionNote Use the following method to delete a note for a Subscription. #### Code Sample ```Http curl -X DELETE \ --url 'https://subdomain.chargify.com/subscriptions/222/notes/66.json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - note_id (`Number`): The Advanced Billing id of the note #### Response Type - Void #### Response Properties - response (`Void`): OK ## Subscription Products ### migrateSubscriptionProduct In order to create a migration, you must pass the `product_id` or `product_handle` in the object when you send a POST request. You may 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 will be moved to the products default price point. The response will be the updated subscription. ## Valid Subscriptions Subscriptions should be in the `active` or `trialing` state in order 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.) ## Migrations Documentation Full documentation on how to record Migrations in the Advanced Billing UI can be located [here](https://maxio.zendesk.com/hc/en-us/articles/24181589372429-Data-Migration-to-Advanced-Billing). ## Failed Migrations Importaint 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. ## Migration 3D Secure - Stripe When a payment requires 3D Secure Authentication to adhear to Strong Customer Authentication (SCA) when the subscription is migrated to a new product, the request enters a [post-authentication flow](https://maxio.zendesk.com/hc/en-us/articles/24176278996493-Testing-Implementing-3D-Secure#psd2-flows-pre-authentication-and-post-authentication). The server returns `422 Unprocessable Entity` in this case with the following response: ```json { "errors": [ "Your card was declined. This transaction requires 3D secure authentication." ], "gateway_payment_id": "pi_1F0aGoJ2UDb3Q4av7zU3sHPh", "description": "This card requires 3D secure authentication. Redirect the customer to the URL from the action_link attribute to authenticate. Attach callback_url param to this URL if you want to be notified about the result of 3D Secure authentication. Attach redirect_url param to this URL if you want to redirect a customer back to your page after 3D Secure authentication. Example: https://mysite.chargify.com/3d-secure/pi_1FCm4RKDeye4C0XfbqquXRYm?one_time_token_id=128&callback_url=https://localhost:4000&redirect_url=https://yourpage.com will do a POST request to https://localhost:4000 after payment is authenticated and will redirect a customer to https://yourpage.com after 3DS authentication.", "action_link": "http://acme.chargify.com/3d-secure/pi_1F0aGoJ2UDb3Q4av7zU3sHPh?one_time_token_id=242" } ``` To let the customer go through 3D Secure Authentication, they need to be redirected to the URL specified in `action_link`. Optionally, you can specify `callback_url` parameter in the `action_link` URL if you’d like to be notified about the result of 3D Secure Authentication. The `callback_url` will return the following information: - whether the authentication was successful (`success`) - the gateway ID for the payment (`gateway_payment_id`) - the subscription ID (`subscription_id`) Lastly, you can also specify a `redirect_url` within the `action_link` URL if you’d like to redirect a customer back to your site. It is not possible to use `action_link` in an iframe inside a custom application. You have to redirect the customer directly to the `action_link`, then, to be notified about the result, use `redirect_url` or `callback_url`. The final URL that you send a customer to to complete 3D Secure may resemble the following, where the first half is the `action_link` and the second half contains a `redirect_url` and `callback_url`: `https://mysite.chargify.com/3d-secure/pi_1FCm4RKDeye4C0XfbqquXRYm?one_time_token_id=128&callback_url=https://localhost:4000&redirect_url=https://yourpage.com` ### Example Redirect Flow You may wish to redirect customers to different pages depending on whether SCA was performed successfully. Here's an example flow to use as a reference: 1. Create a migration via API; it requires 3DS 2. You receive a `gateway_payment_id` in the `action_link` along other params in the response. 3. Use this `gateway_payment_id` to, for example, connect with your internal resources or generate a session_id 4. Include 1 of those attributes inside the `callback_url` and `redirect_url` to be aware which “session” this applies to 5. Redirect the customer to the `action_link` with `callback_url` and `redirect_url` applied 6. After the customer finishes 3DS authentication, we let you know the result by making a request to applied `callback_url`. 7. After that, we redirect the customer to the `redirect_url`; at this point the result of authentication is known 8. Optionally, you can use the applied "msg" param in the `redirect_url` to determine whether it was successful or not. #### Code Sample ```Http 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 } }' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - body (`Subscription Product Migration Request`) #### Response Type - Subscription Response #### Response Properties - response (`Subscription Response`): OK ### previewSubscriptionProductMigration ## 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 (eg: `"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. #### Code Sample ```Http 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 } }' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - body (`Subscription Migration Preview Request`) #### Response Type - Subscription Migration Preview Response #### Response Properties - response (`Subscription Migration Preview Response`): OK ## Subscription Status ### retrySubscription Advanced Billing offers the ability to retry collecting the balance due on a past due Subscription without waiting for the next scheduled attempt. ## Successful Reactivation The response will be `200 OK` with the updated Subscription. ## Failed Reactivation The response will be `422 "Unprocessable Entity`. #### Code Sample ```Http curl -X PUT \ --url 'https://subdomain.chargify.com/subscriptions/222/retry.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription #### Response Type - Subscription Response #### Response Properties - response (`Subscription Response`): OK ### cancelSubscription The DELETE action causes the cancellation of the Subscription. This means, the method sets the Subscription state to "canceled". #### Code Sample ```Http curl -X DELETE \ --url 'https://subdomain.chargify.com/subscriptions/222.json' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - body (`Cancellation Request`) #### Response Type - Subscription Response #### Response Properties - response (`Subscription Response`): OK ### resumeSubscription Resume 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. #### Code Sample ```Http curl -X POST -G \ --url 'https://subdomain.chargify.com/subscriptions/222/resume.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - calendar_billing['resumption_charge'] (`Resumption Charge`): (For calendar billing subscriptions only) The way that the resumed subscription's charge should be handled #### Response Type - Subscription Response #### Response Properties - response (`Subscription Response`): OK ### pauseSubscription This will place the subscription in the on_hold state and it will not renew. ## Limitations You may not place a subscription on hold if the `next_billing_at` date is within 24 hours. #### Code Sample ```Http 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" } }' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - body (`Pause Request`) #### Response Type - Subscription Response #### Response Properties - response (`Subscription Response`): OK ### updateAutomaticSubscriptionResumption Once a subscription has been paused / put on hold, you can update the date which was specified to automatically resume the subscription. To update a subscription's resume date, use this method to change or update the `automatically_resume_at` date. ### Remove the resume date Alternately, you can change the `automatically_resume_at` to `null` if you would like the subscription to not have a resume date. #### Code Sample ```Http 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" } }' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - body (`Pause Request`) #### Response Type - Subscription Response #### Response Properties - response (`Subscription Response`): OK ### reactivateSubscription Advanced Billing offers the ability to reactivate 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. | 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 #### Code Sample ```Http 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 }' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - body (`Reactivate Subscription Request`) #### Response Type - Subscription Response #### Response Properties - response (`Subscription Response`): OK ### initiateDelayedCancellation Advanced Billing offers the ability to cancel a subscription at the end of the current billing period. This period is set by its current product. Requesting to cancel the subscription at the end of the period sets the `cancel_at_end_of_period` flag to true. Note that you cannot set `cancel_at_end_of_period` at subscription creation, or if the subscription is past due. #### Code Sample ```Http 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' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - body (`Cancellation Request`) #### Response Type - Delayed Cancellation Response #### Response Properties - response (`Delayed Cancellation Response`): OK ### cancelDelayedCancellation Removing the delayed cancellation on a subscription will ensure that it doesn't get canceled at the end of the period that it is in. 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. #### Code Sample ```Http curl -X DELETE \ --url 'https://subdomain.chargify.com/subscriptions/222/delayed_cancel.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription #### Response Type - Delayed Cancellation Response #### Response Properties - response (`Delayed Cancellation Response`): OK ### cancelDunning If a subscription is currently in dunning, the subscription will be set to active and the active Dunner will be resolved. #### Code Sample ```Http curl -X POST \ --url 'https://subdomain.chargify.com/subscriptions/222/cancel_dunning.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription #### Response Type - Subscription Response #### Response Properties - response (`Subscription Response`): OK ### previewRenewal The Chargify API allows you to preview a renewal by posting to the renewals endpoint. 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 our documentation [here](https://maxio.zendesk.com/hc/en-us/articles/24252493695757-Subscriber-Interface-Overview). ## Optional Component Fields This endpoint is particularly useful due to the fact that it will return the computed billing amount for the base product and the components which are in use by a subscriber. By default, the preview will include 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. We do not predict end-of-period values for components, so metered or events-based usage may be less than it will eventually be at the end of the period. Optionally, **you may 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. ## Subscription Side Effects You can request a `POST` to obtain this data from the endpoint without any side effects. Plain and simple, this will preview data, not log any changes against a subscription. #### Code Sample ```Http 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" } ] }' ``` #### Request Parameters - subscription_id (`Number`): The Chargify id of the subscription - body (`Renewal Preview Request`) #### Response Type - Renewal Preview Response #### Response Properties - response (`Renewal Preview Response`): OK ## Webhooks ### listWebhooks Allows you to view a list of webhooks. You can pass query parameters if you want to filter webhooks. See the [Webhooks](page:introduction/webhooks/webhooks) documentation for more information. #### Code Sample ```Http curl -X GET -G \ --url 'https://subdomain.chargify.com/webhooks.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' \ -d 'page=1' \ -d 'per_page=50' ``` #### Request Parameters - status (`Webhook Status`): Webhooks with matching status would be returned. - since_date (`String`): Format YYYY-MM-DD. Returns Webhooks with the created_at date greater than or equal to the one specified. - until_date (`String`): Format YYYY-MM-DD. Returns Webhooks with the created_at date less than or equal to the one specified. - page (`Number`): 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`. - per_page (`Number`): 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`. - order (`Webhook Order`): The order in which the Webhooks are returned. - subscription (`Number`): The Advanced Billing id of a subscription you'd like to filter for #### Response Type - array #### Response Properties - response (`array`): OK ### enableWebhooks Allows you to enable webhooks for your site #### Code Sample ```Http curl -X PUT \ --url 'https://subdomain.chargify.com/webhooks/settings.json' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' \ --data-raw '{ "webhooks_enabled": true }' ``` #### Request Parameters - body (`Enable Webhooks Request`) #### Response Type - Enable Webhooks Response #### Response Properties - response (`Enable Webhooks Response`): OK ### replayWebhooks Replays webhooks. Posting to this endpoint does not immediately resend the webhooks. They are added to a queue and sent as soon as possible, depending on available system resources. You can submit an array of up to 1000 webhook IDs in the replay request. #### Code Sample ```Http curl -X POST \ --url 'https://subdomain.chargify.com/webhooks/replay.json' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' \ --data-raw '{ "ids": [ 123456789, 123456788 ] }' ``` #### Request Parameters - body (`Replay Webhooks Request`) #### Response Type - Replay Webhooks Response #### Response Properties - response (`Replay Webhooks Response`): OK ### createEndpoint Creates an endpoint and assigns a list of webhooks subscriptions (events) to it. See the [Webhooks Reference](page:introduction/webhooks/webhooks-reference#events) page for available events. #### Code Sample ```Http curl -X POST \ --url 'https://subdomain.chargify.com/endpoints.json' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' \ --data-raw '{ "endpoint": { "url": "https://your.site/webhooks", "webhook_subscriptions": [ "payment_success", "payment_failure" ] } }' ``` #### Request Parameters - body (`Create or Update Endpoint Request`) #### Response Type - Endpoint Response #### Response Properties - response (`Endpoint Response`): OK ### listEndpoints Returns created endpoints for a site. #### Code Sample ```Http curl -X GET \ --url 'https://subdomain.chargify.com/endpoints.json' \ -H 'Accept: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' ``` #### Response Type - array #### Response Properties - response (`array`): OK ### updateEndpoint Updates an Endpoint. You can change the `url` of your endpoint or the list of `webhook_subscriptions` to which you are subscribed. See the [Webhooks Reference](page:introduction/webhooks/webhooks-reference#events) page for available events. Always send a complete list of events to which you want to subscribe. Sending a PUT request for an existing endpoint with an empty list of `webhook_subscriptions` will unsubscribe all events. If you want unsubscribe from a specific event, send a list of `webhook_subscriptions` without the specific event key. #### Code Sample ```Http curl -X PUT \ --url 'https://subdomain.chargify.com/endpoints/42.json' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -u 'BasicAuthUserName:BasicAuthPassword' \ --data-raw '{ "endpoint": { "url": "https://your.site/webhooks/1/json.", "webhook_subscriptions": [ "payment_failure", "payment_success", "refund_failure" ] } }' ``` #### Request Parameters - endpoint_id (`Number`): The Advanced Billing id for the endpoint that should be updated - body (`Create or Update Endpoint Request`) #### Response Type - Endpoint Response #### Response Properties - response (`Endpoint Response`): OK # Models ## Payment Method Apple Pay ### Properties - type (`Invoice Event Payment Method`) ## Payment Method Bank Account ### Properties - masked_account_number (`String`) - masked_routing_number (`String`) - type (`Invoice Event Payment Method`) ## Payment Method Credit Card ### Properties - card_brand (`String`) - card_expiration (`String`) - last_four (`String`) - masked_card_number (`String`) - type (`Invoice Event Payment Method`) ## Payment Method External ### Properties - details (`String`) - kind (`String`) - memo (`String`) - type (`Invoice Event Payment Method`) ## Payment Method Paypal ### Properties - email (`String`) - type (`Invoice Event Payment Method`) ## Apply Credit Note Event ### Properties - id (`Long`) - timestamp (`DateTime`) - invoice (`Invoice`) - event_type (`Invoice Event Type`) - event_data (`Apply Credit Note Event Data`): Example schema for an `apply_credit_note` event ## Apply Debit Note Event ### Properties - id (`Long`) - timestamp (`DateTime`) - invoice (`Invoice`) - event_type (`Invoice Event Type`) - event_data (`Apply Debit Note Event Data`): Example schema for an `apply_debit_note` event ## Apply Payment Event ### Properties - id (`Long`) - timestamp (`DateTime`) - invoice (`Invoice`) - event_type (`Invoice Event Type`) - event_data (`Apply Payment Event Data`): Example schema for an `apply_payment` event ## Backport Invoice Event ### Properties - id (`Long`) - timestamp (`DateTime`) - invoice (`Invoice`) - event_type (`Invoice Event Type`) - event_data (`Invoice`): Example schema for an `backport_invoice` event ## Change Chargeback Status Event ### Properties - id (`Long`) - timestamp (`DateTime`) - invoice (`Invoice`) - event_type (`Invoice Event Type`) - event_data (`Change Chargeback Status Event Data`): Example schema for an `change_chargeback_status` event ## Change Invoice Collection Method Event ### Properties - id (`Long`) - timestamp (`DateTime`) - invoice (`Invoice`) - event_type (`Invoice Event Type`) - event_data (`Change Invoice Collection Method Event Data`): Example schema for an `change_invoice_collection_method` event ## Change Invoice Status Event ### Properties - id (`Long`) - timestamp (`DateTime`) - invoice (`Invoice`) - event_type (`Invoice Event Type`) - event_data (`Change Invoice Status Event Data`): Example schema for an `change_invoice_status` event ## Create Credit Note Event ### Properties - id (`Long`) - timestamp (`DateTime`) - invoice (`Invoice`) - event_type (`Invoice Event Type`) - event_data (`Credit Note`): Example schema for an `create_credit_note` event ## Create Debit Note Event ### Properties - id (`Long`) - timestamp (`DateTime`) - invoice (`Invoice`) - event_type (`Invoice Event Type`) - event_data (`Debit Note`): Example schema for an `create_debit_note` event ## Failed Payment Event ### Properties - id (`Long`) - timestamp (`DateTime`) - invoice (`Invoice`) - event_type (`Invoice Event Type`) - event_data (`Failed Payment Event Data`): Example schema for an `failed_payment` event ## Issue Invoice Event ### Properties - id (`Long`) - timestamp (`DateTime`) - invoice (`Invoice`) - event_type (`Invoice Event Type`) - event_data (`Issue Invoice Event Data`): Example schema for an `issue_invoice` event ## Refund Invoice Event ### Properties - id (`Long`) - timestamp (`DateTime`) - invoice (`Invoice`) - event_type (`Invoice Event Type`) - event_data (`Refund Invoice Event Data`): Example schema for an `refund_invoice` event ## Remove Payment Event ### Properties - id (`Long`) - timestamp (`DateTime`) - invoice (`Invoice`) - event_type (`Invoice Event Type`) - event_data (`Remove Payment Event Data`): Example schema for an `remove_payment` event ## Void Invoice Event ### Properties - id (`Long`) - timestamp (`DateTime`) - invoice (`Invoice`) - event_type (`Invoice Event Type`) - event_data (`Void Invoice Event Data`): Example schema for an `void_invoice` event ## Void Remainder Event ### Properties - id (`Long`) - timestamp (`DateTime`) - invoice (`Invoice`) - event_type (`Invoice Event Type`) - event_data (`Void Remainder Event Data`): Example schema for an `void_remainder` event ## List Invoice Events Response ### Properties - events (`array`) - page (`Number`) - per_page (`Number`) - total_pages (`Number`) ## ApplePay Payment Profile ### Properties - id (`Number`): The Chargify-assigned ID of the Apple Pay payment profile. - first_name (`String`): The first name of the Apple Pay account holder - last_name (`String`): The last name of the Apple Pay account holder - customer_id (`Number`): The Chargify-assigned id for the customer record to which the Apple Pay account belongs - current_vault (`Apple Pay Vault`): The vault that stores the payment profile with the provided vault_token. - vault_token (`String`): The “token” provided by your vault storage for an already stored payment profile - billing_address (`String`): The current billing street address for the Apple Pay account - billing_city (`String`): The current billing address city for the Apple Pay account - billing_state (`String`): The current billing address state for the Apple Pay account - billing_zip (`String`): The current billing address zip code for the Apple Pay account - billing_country (`String`): The current billing address country for the Apple Pay account - customer_vault_token (`String`) - billing_address_2 (`String`): The current billing street address, second line, for the Apple Pay account - payment_type (`Payment Type`) - site_gateway_setting_id (`Number`) - gateway_handle (`String`) - created_at (`DateTime`): A timestamp indicating when this payment profile was created - updated_at (`DateTime`): A timestamp indicating when this payment profile was last updated ## Bank Account Payment Profile ### Properties - id (`Number`): The Chargify-assigned ID of the stored bank account. 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`): The first name of the bank account holder - last_name (`String`): The last name of the bank account holder - customer_id (`Number`): The Chargify-assigned id for the customer record to which the bank account belongs - current_vault (`Bank Account Vault`): The vault that stores the payment profile with the provided vault_token. Use `bogus` for testing. - vault_token (`String`): The “token” provided by your vault storage for an already stored payment profile - billing_address (`String`): The current billing street address for the bank account - billing_city (`String`): The current billing address city for the bank account - billing_state (`String`): The current billing address state for the bank account - billing_zip (`String`): The current billing address zip code for the bank account - billing_country (`String`): The current billing address country for the bank account - customer_vault_token (`String`): (only for Authorize.Net CIM storage): the customerProfileId for the owner of the customerPaymentProfileId provided as the vault_token. - billing_address_2 (`String`): The current billing street address, second line, for the bank account - bank_name (`String`): The bank where the account resides - masked_bank_routing_number (`String`): A string representation of the stored bank routing number with all but the last 4 digits marked with X’s (i.e. ‘XXXXXXX1111’). payment_type will be bank_account - masked_bank_account_number (`String`): A string representation of the stored bank account number with all but the last 4 digits marked with X’s (i.e. ‘XXXXXXX1111’) - bank_account_type (`Bank Account Type`): Defaults to checking - bank_account_holder_type (`Bank Account Holder Type`): Defaults to personal - payment_type (`Payment Type`) - verified (`Boolean`): denotes whether a bank account has been verified by providing the amounts of two small deposits made into the account - site_gateway_setting_id (`Number`) - gateway_handle (`String`) - created_at (`DateTime`): A timestamp indicating when this payment profile was created - updated_at (`DateTime`): A timestamp indicating when this payment profile was last updated ## Credit Card Payment Profile ### Properties - id (`Number`): 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`): The first name of the card holder. - last_name (`String`): The last name of the card holder. - masked_card_number (`String`): A string representation of the credit card number with all but the last 4 digits masked with X’s (i.e. ‘XXXX-XXXX-XXXX-1234’). - card_type (`Card Type`): The type of card used. - expiration_month (`Number`): An integer representing the expiration month of the card(1 – 12). - expiration_year (`Number`): An integer representing the 4-digit expiration year of the card(i.e. ‘2012’). - customer_id (`Number`): The Chargify-assigned id for the customer record to which the card belongs. - current_vault (`Credit Card Vault`): The vault that stores the payment profile with the provided `vault_token`. Use `bogus` for testing. - vault_token (`String`): The “token” provided by your vault storage for an already stored payment profile. - billing_address (`String`): The current billing street address for the card. - billing_city (`String`): The current billing address city for the card. - billing_state (`String`): The current billing address state for the card. - billing_zip (`String`): The current billing address zip code for the card. - billing_country (`String`): The current billing address country for the card. - customer_vault_token (`String`): (only for Authorize.Net CIM storage): the customerProfileId for the owner of the customerPaymentProfileId provided as the vault_token. - billing_address_2 (`String`): The current billing street address, second line, for the card. - payment_type (`Payment Type`) - disabled (`Boolean`) - chargify_token (`String`): Token received after sending billing information using chargify.js. This token will only be received if passed as a sole attribute of credit_card_attributes (i.e. tok_9g6hw85pnpt6knmskpwp4ttt) - site_gateway_setting_id (`Number`) - gateway_handle (`String`): An identifier of connected gateway. - created_at (`DateTime`): A timestamp indicating when this payment profile was created - updated_at (`DateTime`): A timestamp indicating when this payment profile was last updated ## Paypal Payment Profile ### Properties - id (`Number`): The Chargify-assigned ID of the stored PayPal payment profile. - first_name (`String`): The first name of the PayPal account holder - last_name (`String`): The last name of the PayPal account holder - customer_id (`Number`): The Chargify-assigned id for the customer record to which the PayPal account belongs - current_vault (`Pay Pal Vault`): The vault that stores the payment profile with the provided vault_token. - vault_token (`String`): The “token” provided by your vault storage for an already stored payment profile - billing_address (`String`): The current billing street address for the PayPal account - billing_city (`String`): The current billing address city for the PayPal account - billing_state (`String`): The current billing address state for the PayPal account - billing_zip (`String`): The current billing address zip code for the PayPal account - billing_country (`String`): The current billing address country for the PayPal account - customer_vault_token (`String`) - billing_address_2 (`String`): The current billing street address, second line, for the PayPal account - payment_type (`Payment Type`) - site_gateway_setting_id (`Number`) - gateway_handle (`String`) - paypal_email (`String`) - created_at (`DateTime`): A timestamp indicating when this payment profile was created - updated_at (`DateTime`): A timestamp indicating when this payment profile was last updated ## Account Balance ### Properties - balance_in_cents (`Long`): The balance in cents. - automatic_balance_in_cents (`Long`): The automatic balance in cents. - remittance_balance_in_cents (`Long`): The remittance balance in cents. ## Account Balances ### Properties - open_invoices (`Account Balance`): The balance, in cents, of the sum of the subscription's open, payable invoices. - pending_invoices (`Account Balance`): The balance, in cents, of the sum of the subscription's pending, payable invoices. - pending_discounts (`Account Balance`): The balance, in cents, of the subscription's Pending Discount account. - service_credits (`Account Balance`): The balance, in cents, of the subscription's Service Credit account. - prepayments (`Account Balance`): The balance, in cents, of the subscription's Prepayment account. ## ACH Agreement (Optional) If passed, the proof of the authorized ACH agreement terms will be persisted. ### Properties - agreement_terms (`String`): (Required when providing ACH agreement params) The ACH authorization agreement terms. - authorizer_first_name (`String`): (Required when providing ACH agreement params) The first name of the person authorizing the ACH agreement. - authorizer_last_name (`String`): (Required when providing ACH agreement params) The last name of the person authorizing the ACH agreement. - ip_address (`String`): (Required when providing ACH agreement params) The IP address of the person authorizing the ACH agreement. ## Activate Event-Based Component ### Properties - price_point_id (`Number`): The Chargify id of the price point - billing_schedule (`Billing Schedule`): This attribute is particularly useful when you need to align billing events for different components on distinct schedules within a subscription. This only works for site with Multifrequency enabled. - custom_price (`Component Custom Price`): Create or update custom pricing unique to the subscription. Used in place of `price_point_id`. ## Activate Subscription Request ### Properties - revert_on_failure (`Boolean`): 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 value set in the site settings (default: `true`) ## Add Coupons Request ### Properties - codes (`array`) ## Add Subscription to a Group ### Properties - group (`Group Settings`) ## Address Change ### Properties - before (`Invoice Address`) - after (`Invoice Address`) ## Agreement Acceptance Required when creating a subscription with Maxio Payments. ### Properties - ip_address (`String`): Required when providing agreement acceptance params. - terms_url (`String`): Required when creating a subscription with Maxio Payments. Either terms_url or provacy_policy_url required when providing agreement_acceptance params. - privacy_policy_url (`String`) - return_refund_policy_url (`String`) - delivery_policy_url (`String`) - secure_checkout_policy_url (`String`) ## All Vaults The vault that stores the payment profile with the provided `vault_token`. Use `bogus` for testing. ### Properties - adyen - authorizenet - beanstream - blue_snap - bogus - braintree1 - braintree_blue - checkout - cybersource - elavon - eway - eway_rapid - eway_rapid_std - firstdata - forte - gocardless - litle - maxio_payments - maxp - moduslink - moneris - nmi - orbital - payment_express - paymill - paypal - paypal_complete - pin - square - stripe - stripe_connect - trust_commerce - unipaas - wirecard ## Allocate Components ### Properties - proration_upgrade_scheme (`String`) - proration_downgrade_scheme (`String`) - allocations (`array`) - accrue_charge (`Boolean`) - upgrade_charge (`Credit Type`): The type of credit to be created when upgrading/downgrading. Defaults to the component and then site setting if one is not provided. Available values: `full`, `prorated`, `none`. - downgrade_credit (`Credit Type`): The type of credit to be created when upgrading/downgrading. Defaults to the component and then site setting if one is not provided. Available values: `full`, `prorated`, `none`. - payment_collection_method (`Collection Method`): (Optional) If not passed, the allocation(s) will use the payment collection method on the subscription - initiate_dunning (`Boolean`): 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. ## Allocation ### Properties - allocation_id (`Number`): The allocation unique id - component_id (`Number`): The integer component ID for the allocation. This references a component that you have created in your Product setup - component_handle (`String`): The handle of the component. This references a component that you have created in your Product setup - subscription_id (`Number`): The integer subscription ID for the allocation. This references a unique subscription in your Site - quantity (`Number | String`): The allocated quantity set in to effect by the allocation. String for components supporting fractional quantities - previous_quantity (`Number | String`): The allocated quantity that was in effect before this allocation was created. String for components supporting fractional quantities - memo (`String`): The memo passed when the allocation was created - timestamp (`DateTime`): The time that the allocation was recorded, in format and UTC timezone, i.e. 2012-11-20T22:00:37Z - created_at (`DateTime`): Timestamp indicating when this allocation was created - proration_upgrade_scheme (`String`): The scheme used if the proration was an upgrade. This is only present when the allocation was created mid-period. - proration_downgrade_scheme (`String`): The scheme used if the proration was a downgrade. This is only present when the allocation was created mid-period. - price_point_id (`Number`) - price_point_name (`String`) - price_point_handle (`String`) - interval (`Number`): The numerical interval. i.e. 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`): 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`) - accrue_charge (`Boolean`): 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`): 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`): The type of credit to be created when upgrading/downgrading. Defaults to the component and then site setting if one is not provided. Available values: `full`, `prorated`, `none`. - downgrade_credit (`Credit Type`): The type of credit to be created when upgrading/downgrading. Defaults to the component and then site setting if one is not provided. Available values: `full`, `prorated`, `none`. - payment (`Payment for Allocation`) - expires_at (`DateTime`) - used_quantity (`Long`) - charge_id (`Long`) ## Allocation Expiration Date ### Properties - expires_at (`DateTime`) ## Allocation Preview ### Properties - start_date (`DateTime`) - end_date (`DateTime`) - subtotal_in_cents (`Long`) - total_tax_in_cents (`Long`) - total_discount_in_cents (`Long`) - total_in_cents (`Long`) - direction (`Allocation Preview Direction`) - proration_scheme (`String`) - line_items (`array`) - accrue_charge (`Boolean`) - allocations (`array`) - period_type (`String`) - existing_balance_in_cents (`Long`): An integer representing the amount of the subscription's current balance ## Allocation Preview Direction ### Properties - upgrade - downgrade ## Allocation Preview Item ### Properties - component_id (`Number`) - subscription_id (`Number`) - quantity (`Number | String`) - previous_quantity (`Number | String`) - memo (`String`) - timestamp (`String`) - proration_upgrade_scheme (`String`) - proration_downgrade_scheme (`String`) - accrue_charge (`Boolean`) - upgrade_charge (`Credit Type`): The type of credit to be created when upgrading/downgrading. Defaults to the component and then site setting if one is not provided. Available values: `full`, `prorated`, `none`. - downgrade_credit (`Credit Type`): The type of credit to be created when upgrading/downgrading. Defaults to the component and then site setting if one is not provided. Available values: `full`, `prorated`, `none`. - price_point_id (`Number`) - interval (`Number`): The numerical interval. i.e. 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`): 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`) - price_point_handle (`String`) - price_point_name (`String`) - component_handle (`String`) ## Allocation Preview Line Item ### Properties - transaction_type (`Line Item Transaction Type`): A handle for the line item transaction type - kind (`Allocation Preview Line Item Kind`): A handle for the line item kind for allocation preview - amount_in_cents (`Long`) - memo (`String`) - discount_amount_in_cents (`Long`) - taxable_amount_in_cents (`Long`) - component_id (`Number`) - component_handle (`String`) - direction (`Allocation Preview Direction`): Visible when using Fine-grained Component Control ## Allocation Preview Line Item Kind A handle for the line item kind for allocation preview ### Properties - quantity_based_component - on_off_component - coupon - tax ## Allocation Preview Response ### Properties - allocation_preview (`Allocation Preview`) ## Allocation Response ### Properties - allocation (`Allocation`) ## Allocation Settings ### Properties - upgrade_charge (`Credit Type`): The type of credit to be created when upgrading/downgrading. Defaults to the component and then site setting if one is not provided. Available values: `full`, `prorated`, `none`. - downgrade_credit (`Credit Type`): The type of credit to be created when upgrading/downgrading. Defaults to the component and then site setting if one is not provided. Available values: `full`, `prorated`, `none`. - accrue_charge (`String`): Either "true" or "false". ## Apple Pay Vault The vault that stores the payment profile with the provided vault_token. ### Properties - braintree_blue ## Applied Credit Note Data ### Properties - uid (`String`): The UID of the credit note - number (`String`): The number of the credit note ## Apply Credit Note Event Data Example schema for an `apply_credit_note` event ### Properties - uid (`String`): 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`): A unique, identifying string that appears on the credit note and in places it is referenced. - credit_note_uid (`String`): Unique identifier for the credit note. It is generated automatically by Chargify and has the prefix "cn_" followed by alphanumeric characters. - original_amount (`String`): The full, original amount of the credit note. - applied_amount (`String`): The amount of the credit note applied to invoice. - transaction_time (`DateTime`): The time the credit note was applied, in ISO 8601 format, i.e. "2019-06-07T17:20:06Z" - memo (`String`): The credit note memo. - role (`String`): The role of the credit note (e.g. 'general') - consolidated_invoice (`Boolean`): Shows whether it was applied to consolidated invoice or not - applied_credit_notes (`array`): List of credit notes applied to children invoices (if consolidated invoice) ## Apply Debit Note Event Data Example schema for an `apply_debit_note` event ### Properties - debit_note_number (`String`): A unique, identifying string that appears on the debit note and in places it is referenced. - debit_note_uid (`String`): Unique identifier for the debit note. It is generated automatically by Chargify and has the prefix "db_" followed by alphanumeric characters. - original_amount (`String`): The full, original amount of the debit note. - applied_amount (`String`): The amount of the debit note applied to invoice. - memo (`String`): The debit note memo. - transaction_time (`DateTime`): The time the debit note was applied, in ISO 8601 format, i.e. "2019-06-07T17:20:06Z" ## Apply Payment Event Data Example schema for an `apply_payment` event ### Properties - consolidation_level (`Invoice Consolidation Level`) - memo (`String`): The payment memo - original_amount (`String`): 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`): 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`): 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`): A nested data structure detailing the method of payment - transaction_id (`Number`): The Chargify id of the original payment - parent_invoice_number (`Number`) - remaining_prepayment_amount (`String`) - prepayment (`Boolean`) - external (`Boolean`) ## Attribute Error ### Properties - attribute (`array`) ## Auto Invite ### Properties - No - Yes ## Auto Resume ### Properties - automatically_resume_at (`DateTime`) ## Bank Account Attributes ### Properties - chargify_token (`String`) - bank_name (`String`): (Required when creating a subscription with ACH or GoCardless) The name of the bank where the customer’s account resides - bank_routing_number (`String`): (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`): (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`): Defaults to checking - bank_branch_code (`String`): (Optional when creating a subscription with GoCardless) Branch code. Alternatively, an IBAN can be provided - bank_iban (`String`): (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`): Defaults to personal - payment_type (`Payment Type`) - current_vault (`Bank Account Vault`): The vault that stores the payment profile with the provided vault_token. Use `bogus` for testing. - vault_token (`String`) - customer_vault_token (`String`): (only for Authorize.Net CIM storage or Square) The customerProfileId for the owner of the customerPaymentProfileId provided as the vault_token ## Bank Account Holder Type Defaults to personal ### Properties - personal - business ## Bank Account Response ### Properties - payment_profile (`Bank Account Payment Profile`) ## Bank Account Type Defaults to checking ### Properties - checking - savings ## Bank Account Vault The vault that stores the payment profile with the provided vault_token. Use `bogus` for testing. ### Properties - authorizenet - blue_snap - bogus - forte - gocardless - maxio_payments - maxp - stripe_connect ## Bank Account Verification ### Properties - deposit_1_in_cents (`Long`) - deposit_2_in_cents (`Long`) ## Bank Account Verification Request ### Properties - bank_account_verification (`Bank Account Verification`) ## Base Refund Error ### Properties - base (`array`) ## Base String Error The error is base if it is not directly associated with a single attribute. ### Properties - base (`array`) ## Basic Date Field Allows to filter by `created_at` or `updated_at`. ### Properties - updated_at - created_at ## Batch Job Response ### Properties - batchjob (`Batch-Job`) ## Batch-Job ### Properties - id (`Number`) - finished_at (`DateTime`) - row_count (`Number`) - created_at (`DateTime`) - completed (`String`) ## Billing Manifest ### Properties - line_items (`array`) - total_in_cents (`Long`) - total_discount_in_cents (`Long`) - total_tax_in_cents (`Long`) - subtotal_in_cents (`Long`) - start_date (`DateTime`) - end_date (`DateTime`) - period_type (`String`) - existing_balance_in_cents (`Long`) ## Billing Manifest Item ### Properties - transaction_type (`Line Item Transaction Type`): A handle for the line item transaction type - kind (`Billing Manifest Line Item Kind`): A handle for the billing manifest line item kind - amount_in_cents (`Long`) - memo (`String`) - discount_amount_in_cents (`Long`) - taxable_amount_in_cents (`Long`) - component_id (`Number`) - component_handle (`String`) - component_name (`String`) - product_id (`Number`) - product_handle (`String`) - product_name (`String`) - period_range_start (`String`) - period_range_end (`String`) ## Billing Manifest Line Item Kind A handle for the billing manifest line item kind ### Properties - baseline - initial - trial - coupon - component - tax ## Billing Schedule This attribute is particularly useful when you need to align billing events for different components on distinct schedules within a subscription. This only works for site with Multifrequency enabled. ### Properties - initial_billing_at (`Date`): The initial_billing_at attribute in Maxio allows you to specify a custom starting date for billing cycles associated with components that have their own billing frequency set. Only ISO8601 format is supported. ## Breakouts ### Properties - plan_amount_in_cents (`Long`) - plan_amount_formatted (`String`) - usage_amount_in_cents (`Long`) - usage_amount_formatted (`String`) ## Bulk Components Price Point Assignment ### Properties - components (`array`) ## Bulk Create Product Price Points Request ### Properties - price_points (`array`) ## Bulk Create Product Price Points Response ### Properties - price_points (`array`) ## Bulk Create Segments ### Properties - segments (`array`) ## Bulk Update Segments ### Properties - segments (`array`) ## Bulk Update Segments Item ### Properties - id (`Number`): The ID of the segment you want to update. - pricing_scheme (`Pricing Scheme`): The identifier for the pricing scheme. See [Product Components](https://help.chargify.com/products/product-components.html) for an overview of pricing schemes. - prices (`array`) ## Calendar Billing (Optional). Cannot be used when also specifying next_billing_at ### Properties - snap_day (`Number | Snap Day`): A day of month that subscription will be processed on. Can be 1 up to 28 or 'end'. - calendar_billing_first_charge (`First Charge Type`) ## Cancel Grouped Subscriptions Request ### Properties - charge_unbilled_usage (`Boolean`) ## Cancellation Method The process used to cancel the subscription, if the subscription has been canceled. It is nil if the subscription's state is not canceled. ### Properties - merchant_ui - merchant_api - dunning - billing_portal - unknown - imported ## Cancellation Options ### Properties - cancellation_message (`String`): For your internal use. An indication as to why the subscription is being canceled. - reason_code (`String`): The reason code associated with the cancellation. See the list of reason codes associated with your site. ## Cancellation Request ### Properties - subscription (`Cancellation Options`) ## Card Type The type of card used. ### Properties - visa - master - elo - cabal - alelo - discover - american_express - naranja - diners_club - jcb - dankort - maestro - maestro_no_luhn - forbrugsforeningen - sodexo - alia - vr - unionpay - carnet - cartes_bancaires - olimpica - creditel - confiable - synchrony - routex - mada - bp_plus - passcard - edenred - anda - tarjetad - hipercard - bogus - switch - solo - laser ## Change Chargeback Status Event Data Example schema for an `change_chargeback_status` event ### Properties - chargeback_status (`Chargeback Status`) ## Change Invoice Collection Method Event Data Example schema for an `change_invoice_collection_method` event ### Properties - from_collection_method (`String`): The previous collection method of the invoice. - to_collection_method (`String`): The new collection method of the invoice. ## Change Invoice Status Event Data Example schema for an `change_invoice_status` event ### Properties - gateway_trans_id (`String`): Identifier for the transaction within the payment gateway. - amount (`String`): The monetary value associated with the linked payment, expressed in dollars. - from_status (`Invoice Status`): The status of the invoice before any changes occurred. See [Invoice Statuses](https://maxio.zendesk.com/hc/en-us/articles/24252287829645-Advanced-Billing-Invoices-Overview#invoice-statuses) for more. - to_status (`Invoice Status`): The updated status of the invoice after changes have been made. See [Invoice Statuses](https://maxio.zendesk.com/hc/en-us/articles/24252287829645-Advanced-Billing-Invoices-Overview#invoice-statuses) for more. - consolidation_level (`Invoice Consolidation Level`) ## Chargeback Status The current chargeback status. ### Properties - open - lost - won - closed ## Chargify EBB ### Properties - timestamp (`DateTime`): This timestamp determines what billing period the event will be billed in. If your request payload does not include it, Chargify will add `chargify.timestamp` to the event payload and set the value to `now`. - id (`String`): A unique ID set by Chargify. This field is reserved. If `chargify.id` is present in the request payload, it will be overwritten. - created_at (`DateTime`): An ISO-8601 timestamp, set by Chargify at the time each event is recorded. This field is reserved. If `chargify.created_at` is present in the request payload, it will be overwritten. - uniqueness_token (`String`): User-defined string scoped per-stream. Duplicate events within a stream will be silently ignored. Tokens expire after 31 days. - subscription_id (`Number`): Id of Maxio Advanced Billing Subscription which is connected to this event. Provide `subscription_id` if you configured `chargify.subscription_id` as Subscription Identifier in your Event Stream. - subscription_reference (`String`): Reference of Maxio Advanced Billing Subscription which is connected to this event. Provide `subscription_reference` if you configured `chargify.subscription_reference` as Subscription Identifier in your Event Stream. ## Cleanup scope 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. ### Properties - all - customers ## Collection Method The type of payment collection to be used in the subscription. For legacy Statements Architecture valid options are - `invoice`, `automatic`. For current Relationship Invoicing Architecture valid options are - `remittance`, `automatic`, `prepaid`. ### Properties - automatic - remittance - prepaid - invoice ## Component ### Properties - id (`Number`): The unique ID assigned to the component by Chargify. This ID can be used to fetch the component from the API. - name (`String`): The name of the Component, suitable for display on statements. i.e. Text Messages. - handle (`String`): The component API handle - pricing_scheme (`Pricing Scheme`) - unit_name (`String`): The name of the unit that the component’s usage is measured in. i.e. message - unit_price (`String`): The amount the customer will be charged per unit. This field is only populated for ‘per_unit’ pricing schemes, otherwise it may be null. - product_family_id (`Number`): The id of the Product Family to which the Component belongs - product_family_name (`String`): The name of the Product Family to which the Component belongs - product_family_handle (`String`): The handle of the Product Family to which the Component belongs - price_per_unit_in_cents (`Long`): deprecated - use unit_price instead - kind (`Component Kind`): A handle for the component type - archived (`Boolean`): Boolean flag describing whether a component is archived or not. - description (`String`): The description of the component. - default_price_point_id (`Number`) - overage_prices (`array`): Applicable only to prepaid usage components. An array of overage price brackets. - prices (`array`): An array of price brackets. If the component uses the ‘per_unit’ pricing scheme, this array will be empty. - price_point_count (`Number`): Count for the number of price points associated with the component - price_points_url (`String`): URL that points to the location to read the existing price points via GET request - default_price_point_name (`String`) - taxable (`Boolean`): Boolean flag describing whether a component is taxable or not. - tax_code (`String`): A string representing the tax code related to the component type. This is especially important when using AvaTax to tax based on locale. This attribute has a max length of 25 characters. - recurring (`Boolean`) - upgrade_charge (`Credit Type`): The type of credit to be created when upgrading/downgrading. Defaults to the component and then site setting if one is not provided. Available values: `full`, `prorated`, `none`. - downgrade_credit (`Credit Type`): The type of credit to be created when upgrading/downgrading. Defaults to the component and then site setting if one is not provided. Available values: `full`, `prorated`, `none`. - created_at (`DateTime`): Timestamp indicating when this component was created - updated_at (`DateTime`): Timestamp indicating when this component was updated - archived_at (`DateTime`): Timestamp indicating when this component was archived - hide_date_range_on_invoice (`Boolean`): (Only available on Relationship Invoicing sites) Boolean flag describing if the service date range should show for the component on generated invoices. - allow_fractional_quantities (`Boolean`) - item_category (`Item Category`): One of the following: Business Software, Consumer Software, Digital Services, Physical Goods, Other - use_site_exchange_rate (`Boolean`) - accounting_code (`String`): E.g. Internal ID or SKU Number - event_based_billing_metric_id (`Number`): (Only for Event Based Components) This is an ID of a metric attached to the component. This metric is used to bill upon collected events. - interval (`Number`): The numerical interval. i.e. an interval of ‘30’ coupled with an interval_unit of day would mean this component's default price point would renew every 30 days. This property is only available for sites with Multifrequency enabled. - interval_unit (`Interval Unit`): A string representing the interval unit for this component's default price point, either month or day. This property is only available for sites with Multifrequency enabled. ## Component Allocation Change ### Properties - previous_allocation (`Number`) - new_allocation (`Number`) - component_id (`Number`) - component_handle (`String`) - memo (`String`) - allocation_id (`Number`) - allocated_quantity (`Number | String`) ## Component Allocation Error ### Properties - errors (`array`) ## Component Allocation Error Item ### Properties - component_id (`Number`) - message (`String`) - kind (`String`) - on (`String`) ## Component Allocation Error1 ### Properties - errors (`array`) ## Component Cost Data ### Properties - component_code_id (`Number`) - price_point_id (`Number`) - product_id (`Number`) - quantity (`String`) - amount (`String`) - pricing_scheme (`Pricing Scheme`): The identifier for the pricing scheme. See [Product Components](https://help.chargify.com/products/product-components.html) for an overview of pricing schemes. - tiers (`array`) ## Component Cost Data Rate Tier ### Properties - starting_quantity (`Number`) - ending_quantity (`Number`) - quantity (`String`) - unit_price (`String`) - amount (`String`) ## Component Currency Price ### Properties - id (`Number`) - currency (`String`) - price (`String`) - formatted_price (`String`) - price_id (`Number`) - price_point_id (`Number`) ## Component Currency Prices Response ### Properties - currency_prices (`array`) ## Component Custom Price Create or update custom pricing unique to the subscription. Used in place of `price_point_id`. ### Properties - tax_included (`Boolean`): Whether or not the price point includes tax - pricing_scheme (`Pricing Scheme`): Omit for On/Off components - interval (`Number`): The numerical interval. i.e. 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`): 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. - prices (`array`): On/off components only need one price bracket starting at 1 - renew_prepaid_allocation (`Boolean`): Applicable only to prepaid usage components. Controls whether the allocated quantity renews each period. - rollover_prepaid_remainder (`Boolean`): Applicable only to prepaid usage components. Controls whether remaining units roll over to the next period. - expiration_interval (`Number`): Applicable only when rollover is enabled. Number of `expiration_interval_unit`s after which rollover amounts expire. - expiration_interval_unit (`Expiration Interval Unit`): Applicable only when rollover is enabled. Interval unit for rollover expiration (month or day). ## Component Kind A handle for the component type ### Properties - metered_component - quantity_based_component - on_off_component - prepaid_usage_component - event_based_component ## Component Price ### Properties - id (`Number`) - component_id (`Number`) - starting_quantity (`Number`) - ending_quantity (`Number`) - unit_price (`String`) - price_point_id (`Number`) - formatted_unit_price (`String`) - segment_id (`Number`) ## Component Price Point ### Properties - id (`Number`) - type (`Price Point Type`): Price point type. We expose the following types: 1. **default**: a price point that is marked as a default price for a certain product. 2. **custom**: a custom price point. 3. **catalog**: a price point that is **not** marked as a default price for a certain product and is **not** a custom one. - default (`Boolean`): Note: Refer to type attribute instead - name (`String`) - pricing_scheme (`Pricing Scheme`): The identifier for the pricing scheme. See [Product Components](https://help.chargify.com/products/product-components.html) for an overview of pricing schemes. - component_id (`Number`) - handle (`String`) - archived_at (`DateTime`) - created_at (`DateTime`) - updated_at (`DateTime`) - prices (`array`) - use_site_exchange_rate (`Boolean`): Whether to use the site level exchange rate or define your own prices for each currency if you have multiple currencies defined on the site. Defaults to true during creation. - subscription_id (`Number`): (only used for Custom Pricing - ie. when the price point's type is `custom`) The id of the subscription that the custom price point is for. - tax_included (`Boolean`) - interval (`Number`): The numerical interval. i.e. 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`): 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. - currency_prices (`array`): An array of currency pricing data is available when multiple currencies are defined for the site. It varies based on the use_site_exchange_rate setting for the price point. This parameter is present only in the response of read endpoints, after including the appropriate query parameter. - overage_prices (`array`): Applicable only to prepaid usage components. An array of overage price brackets. - overage_pricing_scheme (`Pricing Scheme`): Applicable only to prepaid usage components. Pricing scheme for overage pricing. - renew_prepaid_allocation (`Boolean`): Applicable only to prepaid usage components. Boolean which controls whether or not the allocated quantity should be renewed at the beginning of each period. - rollover_prepaid_remainder (`Boolean`): Applicable only to prepaid usage components. Boolean which controls whether or not remaining units should be rolled over to the next period. - expiration_interval (`Number`): Applicable only to prepaid usage components where rollover_prepaid_remainder is true. The number of `expiration_interval_unit`s after which rollover amounts should expire. - expiration_interval_unit (`Expiration Interval Unit`): Applicable only to prepaid usage components where rollover_prepaid_remainder is true. A string representing the expiration interval unit for this component, either month or day. ## Component Price Point Assignment ### Properties - component_id (`Number`) - price_point (`String | Number`) ## Component Price Point Item ### Properties - name (`String`) - handle (`String`) - pricing_scheme (`Pricing Scheme`): The identifier for the pricing scheme. See [Product Components](https://help.chargify.com/products/product-components.html) for an overview of pricing schemes. - interval (`Number`): The numerical interval. i.e. 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`): 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. - prices (`array`) ## Component Price Point Response ### Properties - price_point (`Component Price Point`) ## Component Price Points response ### Properties - price_points (`array`) - meta (`List Public Keys Meta`) ## Component PricePoint Error ### Properties - errors (`array`) ## Component PricePoint Error Item ### Properties - component_id (`Number`) - message (`String`) - price_point (`Number`) ## Component PricePoint Error1 ### Properties - errors (`array`) ## Component Response ### Properties - component (`Component`) ## Compounding Strategy Applicable only to stackable coupons. For `compound`, Percentage-based discounts will be calculated against the remaining price, after prior discounts have been calculated. For `full-price`, Percentage-based discounts will always be calculated against the original item price, before other discounts are applied. ### Properties - compound - fullprice ## Consolidated Invoice ### Properties - invoices (`array`) ## Count Response ### Properties - count (`Number`) ## Coupon ### Properties - id (`Number`) - name (`String`) - code (`String`) - description (`String`) - amount (`Decimal`) - amount_in_cents (`Long`) - product_family_id (`Number`) - product_family_name (`String`) - start_date (`DateTime`) - end_date (`DateTime`): After the given time, this coupon code will be invalid for new signups. Recurring discounts started before this date will continue to recur even after this date. - percentage (`String`) - recurring (`Boolean`) - recurring_scheme (`Recurring Scheme`) - duration_period_count (`Number`) - duration_interval (`Number`) - duration_interval_unit (`String`) - duration_interval_span (`String`) - allow_negative_balance (`Boolean`): If set to true, discount is not limited (credits will carry forward to next billing). - archived_at (`DateTime`) - conversion_limit (`String`) - stackable (`Boolean`): A stackable coupon can be combined with other coupons on a Subscription. - compounding_strategy (`Compounding Strategy`): Applicable only to stackable coupons. For `compound`, Percentage-based discounts will be calculated against the remaining price, after prior discounts have been calculated. For `full-price`, Percentage-based discounts will always be calculated against the original item price, before other discounts are applied. - use_site_exchange_rate (`Boolean`) - created_at (`DateTime`) - updated_at (`DateTime`) - discount_type (`Discount Type`) - exclude_mid_period_allocations (`Boolean`) - apply_on_cancel_at_end_of_period (`Boolean`) - apply_on_subscription_expiration (`Boolean`) - coupon_restrictions (`array`) - currency_prices (`array`): Returned in read, find, and list endpoints if the query parameter is provided. ## Coupon Currency ### Properties - id (`Number`) - currency (`String`) - price (`Decimal`) - coupon_id (`Number`) ## Coupon Currency Request ### Properties - currency_prices (`array`) ## Coupon Currency Response ### Properties - currency_prices (`array`) ## Coupon Payload ### Properties - name (`String`): Required when creating a new coupon. This name is not displayed to customers and is limited to 255 characters. - code (`String`): Required when creating a new coupon. The code is limited to 255 characters. May contain uppercase alphanumeric characters and these special characters (which allow for email addresses to be used): “%”, “@”, “+”, “-”, “_”, and “.” - description (`String`): Required when creating a new coupon. A description of the coupon that can be displayed to customers in transactions and on statements. The description is limited to 255 characters. - percentage (`String | Decimal`): Required when creating a new percentage coupon. Can't be used together with amount_in_cents. Percentage discount - amount_in_cents (`Long`): Required when creating a new flat amount coupon. Can't be used together with percentage. Flat USD discount - allow_negative_balance (`Boolean`): If set to true, discount is not limited (credits will carry forward to next billing). Can't be used together with restrictions. - recurring (`Boolean`) - end_date (`Date`): After the end of the given day, this coupon code will be invalid for new signups. Recurring discounts started before this date will continue to recur even after this date. - product_family_id (`String`) - stackable (`Boolean`): A stackable coupon can be combined with other coupons on a Subscription. - compounding_strategy (`Compounding Strategy`): Applicable only to stackable coupons. For `compound`, Percentage-based discounts will be calculated against the remaining price, after prior discounts have been calculated. For `full-price`, Percentage-based discounts will always be calculated against the original item price, before other discounts are applied. - exclude_mid_period_allocations (`Boolean`) - apply_on_cancel_at_end_of_period (`Boolean`) - apply_on_subscription_expiration (`Boolean`) ## Coupon Request ### Properties - coupon (`Coupon Payload`) - restricted_products (`map`): An object where the keys are product IDs or handles (prefixed with 'handle:'), and the values are booleans indicating if the coupon should be applicable to the product - restricted_components (`map`): An object where the keys are component IDs or handles (prefixed with 'handle:'), and the values are booleans indicating if the coupon should be applicable to the component ## Coupon Response ### Properties - coupon (`Coupon`) ## Coupon Restriction ### Properties - id (`Number`) - item_type (`Restriction Type`) - item_id (`Number`) - name (`String`) - handle (`String`) ## Coupon Subcodes ### Properties - codes (`array`) ## Coupon Subcodes Response ### Properties - created_codes (`array`) - duplicate_codes (`array`) - invalid_codes (`array`) ## Coupon Usage ### Properties - id (`Number`): The Chargify id of the product - name (`String`): Name of the product - signups (`Number`): Number of times the coupon has been applied - savings (`Number`): Dollar amount of customer savings as a result of the coupon. - savings_in_cents (`Long`): Dollar amount of customer savings as a result of the coupon. - revenue (`Number`): Total revenue of the all subscriptions that have received a discount from this coupon. - revenue_in_cents (`Long`): Total revenue of the all subscriptions that have received a discount from this coupon. ## Create Allocation ### Properties - quantity (`Decimal`): The allocated quantity to which to set the line-items allocated quantity. By default, this is an integer. If decimal allocations are enabled for the component, it will be a decimal number. For On/Off components, use 1for on and 0 for off. - component_id (`Number`): (required for the multiple allocations endpoint) The id associated with the component for which the allocation is being made - memo (`String`): A memo to record along with the allocation - proration_downgrade_scheme (`String`): The scheme used if the proration is a downgrade. Defaults to the site setting if one is not provided. - proration_upgrade_scheme (`String`): The scheme used if the proration is an upgrade. Defaults to the site setting if one is not provided. - accrue_charge (`Boolean`): 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. Defaults to the site setting if one is not provided. - downgrade_credit (`Credit Type`): The type of credit to be created when upgrading/downgrading. Defaults to the component and then site setting if one is not provided. Available values: `full`, `prorated`, `none`. - upgrade_charge (`Credit Type`): The type of credit to be created when upgrading/downgrading. Defaults to the component and then site setting if one is not provided. Available values: `full`, `prorated`, `none`. - initiate_dunning (`Boolean`): If set to true, if the immediate component payment fails, initiate dunning for the subscription. Otherwise, leave the charges on the subscription to pay for at renewal. Defaults to false. - price_point_id (`String | Number`): Price point that the allocation should be charged at. Accepts either the price point's id (integer) or handle (string). When not specified, the default price point will be used. - billing_schedule (`Billing Schedule`): This attribute is particularly useful when you need to align billing events for different components on distinct schedules within a subscription. This only works for site with Multifrequency enabled. ## Create Allocation Request ### Properties - allocation (`Create Allocation`) ## Create Component Price Point ### Properties - name (`String`) - handle (`String`) - pricing_scheme (`Pricing Scheme`): The identifier for the pricing scheme. See [Product Components](https://help.chargify.com/products/product-components.html) for an overview of pricing schemes. - prices (`array`) - use_site_exchange_rate (`Boolean`): Whether to use the site level exchange rate or define your own prices for each currency if you have multiple currencies defined on the site. Setting not supported when creating price points in bulk. - tax_included (`Boolean`): Whether or not the price point includes tax. Setting not supported when creating price points in bulk. - interval (`Number`): The numerical interval. i.e. an interval of ‘30’ coupled with an interval_unit of day would mean this price point would renew every 30 days. This property is only available for sites with Multifrequency enabled. - interval_unit (`Interval Unit`): A string representing the interval unit for this price point, either month or day. This property is only available for sites with Multifrequency enabled. ## Create Component Price Point Request ### Properties - price_point (`Create Component Price Point | Create Prepaid Usage Component Price Point`) ## Create Component Price Points Request ### Properties - price_points (`array`) ## Create Currency Price ### Properties - currency (`String`): ISO code for a currency defined on the site level - price (`Decimal`): Price for the price level in this currency - price_id (`Number`): ID of the price that this corresponds with ## Create Currency Prices Request ### Properties - currency_prices (`array`) ## Create Customer ### Properties - first_name (`String`) - last_name (`String`) - email (`String`) - cc_emails (`String`) - organization (`String`) - reference (`String`) - address (`String`) - address_2 (`String`) - city (`String`) - state (`String`) - zip (`String`) - country (`String`) - phone (`String`) - locale (`String`): Set a specific language on a customer record. - vat_number (`String`) - tax_exempt (`Boolean`) - tax_exempt_reason (`String`) - parent_id (`Number`): The parent ID in Chargify if applicable. Parent is another Customer object. - salesforce_id (`String`): The Salesforce ID of the customer ## Create Customer Request ### Properties - customer (`Create Customer`) ## Create EBB Component ### Properties - event_based_component (`EBB Component`) ## Create Invoice ### Properties - line_items (`array`) - issue_date (`Date`) - net_terms (`Number`): 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. - payment_instructions (`String`) - memo (`String`): A custom memo can be sent to override the site's default. - seller_address (`Create Invoice Address`): Overrides the defaults for the site - billing_address (`Create Invoice Address`): Overrides the default for the customer - shipping_address (`Create Invoice Address`): Overrides the default for the customer - coupons (`array`) - status (`Create Invoice Status`) ## Create Invoice Address Overrides the default address. ### Properties - first_name (`String`) - last_name (`String`) - phone (`String`) - address (`String`) - address_2 (`String`) - city (`String`) - state (`String`) - zip (`String`) - country (`String`) ## Create Invoice Coupon ### Properties - code (`String`) - subcode (`String`) - percentage (`String | Decimal`) - amount (`String | Decimal`) - description (`String`) - product_family_id (`String | Number`) - compounding_strategy (`Compounding Strategy`): Applicable only to stackable coupons. For `compound`, Percentage-based discounts will be calculated against the remaining price, after prior discounts have been calculated. For `full-price`, Percentage-based discounts will always be calculated against the original item price, before other discounts are applied. ## Create Invoice Item ### Properties - title (`String`) - quantity (`Decimal | String`): The quantity can contain up to 8 decimal places. i.e. 1.00 or 0.0012 or 0.00000065. If you submit a value with more than 8 decimal places, we will round it down to the 8th decimal place. - unit_price (`Decimal | String`): The unit_price can contain up to 8 decimal places. i.e. 1.00 or 0.0012 or 0.00000065. If you submit a value with more than 8 decimal places, we will round it down to the 8th decimal place. - taxable (`Boolean`): Set to true to automatically calculate taxes. Site must be configured to use and calculate taxes. If using AvaTax, a tax_code parameter must also be sent. - tax_code (`String`): A string representing the tax code related to the product type. This is especially important when using AvaTax to tax based on locale. This attribute has a max length of 25 characters. - period_range_start (`String`): YYYY-MM-DD - period_range_end (`String`): YYYY-MM-DD - product_id (`String | Number`): Product handle or product id. - component_id (`String | Number`): Component handle or component id. - price_point_id (`String | Number`): Price point handle or id. For component. - product_price_point_id (`String | Number`) - description (`String`) ## Create Invoice Payment ### Properties - amount (`String | Decimal`): A string of the dollar amount to be refunded (eg. "10.50" => $10.50) - memo (`String`): A description to be attached to the payment. Applicable only to `external` payments. - method (`Invoice Payment Method Type`): The type of payment method used. Defaults to other. - details (`String`): Additional information related to the payment method (eg. Check #). Applicable only to `external` payments. - payment_profile_id (`Number`): The ID of the payment profile to be used for the payment. - received_on (`Date`): Date reflecting when the payment was received from a customer. Must be in the past. Applicable only to `external` payments. ## Create Invoice Payment Application ### Properties - invoice_uid (`String`): Unique identifier for the invoice. It has the prefix "inv_" followed by alphanumeric characters. - amount (`String`): Dollar amount of the invoice payment (eg. "10.50" => $10.50). ## Create Invoice Payment Request ### Properties - payment (`Create Invoice Payment`) - type (`Invoice Payment Type`): The type of payment to be applied to an Invoice. Defaults to external. ## Create Invoice Request ### Properties - invoice (`Create Invoice`) ## Create Invoice Status ### Properties - draft - open ## Create Metadata ### Properties - name (`String`) - value (`String`) ## Create Metadata Request ### Properties - metadata (`array`) ## Create Metafield ### Properties - name (`String`) - scope (`Metafield Scope`): Warning: When updating a metafield's scope attribute, all scope attributes must be passed. Partially complete scope attributes will override the existing settings. - input_type (`Metafield Input`): Indicates the type of metafield. A text metafield allows any string value. Dropdown and radio metafields have a set of values that can be selected. Defaults to 'text'. - enum (`array`): Only applicable when input_type is radio or dropdown. Empty strings will not be submitted. ## Create Metafields Request ### Properties - metafields (`Create Metafield | array`) ## Create Metered Component ### Properties - metered_component (`Metered Component`) ## Create Multi Invoice Payment ### Properties - memo (`String`): A description to be attached to the payment. - details (`String`): Additional information related to the payment method (eg. Check #). - method (`Invoice Payment Method Type`): The type of payment method used. Defaults to other. - amount (`String | Decimal`): Dollar amount of the sum of the invoices payment (eg. "10.50" => $10.50). - received_on (`String`): Date reflecting when the payment was received from a customer. Must be in the past. - applications (`array`) ## Create Multi Invoice Payment Request ### Properties - payment (`Create Multi Invoice Payment`) ## Create Offer ### Properties - name (`String`) - handle (`String`) - description (`String`) - product_id (`Number`) - product_price_point_id (`Number`) - components (`array`) - coupons (`array`) ## Create Offer Component ### Properties - component_id (`Number`) - price_point_id (`Number`) - starting_quantity (`Number`) ## Create Offer Request ### Properties - offer (`Create Offer`) ## Create On/Off Component ### Properties - on_off_component (`On Off Component`) ## Create or Update Endpoint Used to Create or Update Endpoint ### Properties - url (`String`) - webhook_subscriptions (`array`) ## Create or Update Endpoint Request Used to Create or Update Endpoint ### Properties - endpoint (`Create or Update Endpoint`): Used to Create or Update Endpoint ## Create or Update Product ### Properties - name (`String`): The product name - handle (`String`): The product API handle - description (`String`): The product description - accounting_code (`String`): E.g. Internal ID or SKU Number - require_credit_card (`Boolean`): Deprecated value that can be ignored unless you have legacy hosted pages. For Public Signup Page users, read this attribute from under the signup page. - price_in_cents (`Long`): The product price, in integer cents - interval (`Number`): The numerical interval. i.e. an interval of ‘30’ coupled with an interval_unit of day would mean this product would renew every 30 days - interval_unit (`Interval Unit`): A string representing the interval unit for this product, either month or day - trial_price_in_cents (`Long`): The product trial price, in integer cents - trial_interval (`Number`): The numerical trial interval. i.e. an interval of ‘30’ coupled with a trial_interval_unit of day would mean this product trial would last 30 days. - trial_interval_unit (`Interval Unit`): A string representing the trial interval unit for this product, either month or day - trial_type (`Trial Type`): Indicates how a trial is handled when the trail period ends and there is no credit card on file. For `no_obligation`, the subscription transitions to a Trial Ended state. Maxio will not send any emails or statements. For `payment_expected`, the subscription transitions to a Past Due state. Maxio will send normal dunning emails and statements according to your other settings. - expiration_interval (`Number`): The numerical expiration interval. i.e. an expiration_interval of ‘30’ coupled with an expiration_interval_unit of day would mean this product would expire after 30 days. - expiration_interval_unit (`Expiration Interval Unit`): A string representing the expiration interval unit for this product, either month, day or never - auto_create_signup_page (`Boolean`) - tax_code (`String`): A string representing the tax code related to the product type. This is especially important when using AvaTax to tax based on locale. This attribute has a max length of 25 characters. ## Create or Update Product Request ### Properties - product (`Create or Update Product`) ## Create or Update Segment Price ### Properties - starting_quantity (`Number`) - ending_quantity (`Number`) - unit_price (`String | Decimal`): The price can contain up to 8 decimal places. i.e. 1.00 or 0.0012 or 0.00000065 ## Create Payment ### Properties - amount (`String`) - memo (`String`) - payment_details (`String`) - payment_method (`Invoice Payment Method Type`): The type of payment method used. Defaults to other. ## Create Payment Profile ### Properties - chargify_token (`String`): Token received after sending billing information using chargify.js. - id (`Number`) - payment_type (`Payment Type`) - first_name (`String`): First name on card or bank account. If omitted, the first_name from customer attributes will be used. - last_name (`String`): Last name on card or bank account. If omitted, the last_name from customer attributes will be used. - masked_card_number (`String`) - full_number (`String`): The full credit card number - card_type (`Card Type`): The type of card used. - expiration_month (`Number | String`): (Optional when performing an Import via vault_token, required otherwise) The 1- or 2-digit credit card expiration month, as an integer or string, i.e. 5 - expiration_year (`Number | String`): (Optional when performing a Import via vault_token, required otherwise) The 4-digit credit card expiration year, as an integer or string, i.e. 2012 - billing_address (`String`): The credit card or bank account billing street address (i.e. 123 Main St.). This value is merely passed through to the payment gateway. - billing_address_2 (`String`): Second line of the customer’s billing address i.e. Apt. 100 - billing_city (`String`): The credit card or bank account billing address city (i.e. “Boston”). This value is merely passed through to the payment gateway. - billing_state (`String`): The credit card or bank account billing address state (i.e. MA). This value is merely passed through to the payment gateway. This must conform to the [ISO_3166-1](https://en.wikipedia.org/wiki/ISO_3166-1#Current_codes) in order to be valid for tax locale purposes. - billing_country (`String`): The credit card or bank account billing address country, required in [ISO_3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format (i.e. “US”). This value is merely passed through to the payment gateway. Some gateways require country codes in a specific format. Check your gateway’s documentation. If creating an ACH subscription, only US is supported at this time. - billing_zip (`String`): The credit card or bank account billing address zip code (i.e. 12345). This value is merely passed through to the payment gateway. - current_vault (`All Vaults`): The vault that stores the payment profile with the provided `vault_token`. Use `bogus` for testing. - vault_token (`String`): The “token” provided by your vault storage for an already stored payment profile - customer_vault_token (`String`): (only for Authorize.Net CIM storage or Square) The customerProfileId for the owner of the customerPaymentProfileId provided as the vault_token - customer_id (`Number`): (Required when creating a new payment profile) The Chargify customer id. - paypal_email (`String`): used by merchants that implemented BraintreeBlue javaScript libraries on their own. We recommend using Chargify.js instead. - payment_method_nonce (`String`): used by merchants that implemented BraintreeBlue javaScript libraries on their own. We recommend using Chargify.js instead. - gateway_handle (`String`): This attribute is only available if MultiGateway feature is enabled for your Site. This feature is in the Private Beta currently. gateway_handle is used to directly select a gateway where a payment profile will be stored in. Every connected gateway must have a unique gateway handle specified. Read [Multigateway description](https://chargify.zendesk.com/hc/en-us/articles/4407761759643#connecting-with-multiple-gateways) to learn more about new concepts that MultiGateway introduces and the default behavior when this attribute is not passed. - cvv (`String`): The 3- or 4-digit Card Verification Value. This value is merely passed through to the payment gateway. - bank_name (`String`): (Required when creating with ACH or GoCardless, optional with Stripe Direct Debit). The name of the bank where the customerʼs account resides - bank_iban (`String`): (Optional when creating with GoCardless, required with Stripe Direct Debit). International Bank Account Number. Alternatively, local bank details can be provided - bank_routing_number (`String`): (Required when creating 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`): (Required when creating with ACH, GoCardless, Stripe BECS or BACS Direct Debit, and bank_iban is blank) The customerʼs bank account number - bank_branch_code (`String`): (Optional when creating with GoCardless, required with Stripe BECS or BACS Direct Debit) Branch/Sort code. Alternatively, an IBAN can be provided - bank_account_type (`Bank Account Type`): Defaults to checking - bank_account_holder_type (`Bank Account Holder Type`): Defaults to personal - last_four (`String`): (Optional) Used for creating subscription with payment profile imported using vault_token, for proper display in Advanced Billing UI ## Create Payment Profile Request ### Properties - payment_profile (`Create Payment Profile`) ## Create Prepaid Component ### Properties - prepaid_usage_component (`Prepaid Usage Component`) ## Create Prepaid Usage Component Price Point ### Properties - name (`String`) - handle (`String`) - pricing_scheme (`Pricing Scheme`): The identifier for the pricing scheme. See [Product Components](https://help.chargify.com/products/product-components.html) for an overview of pricing schemes. - prices (`array`) - overage_pricing (`Overage Pricing`) - use_site_exchange_rate (`Boolean`): Whether to use the site level exchange rate or define your own prices for each currency if you have multiple currencies defined on the site. - rollover_prepaid_remainder (`Boolean`): (only for prepaid usage components) Boolean which controls whether or not remaining units should be rolled over to the next period - renew_prepaid_allocation (`Boolean`): (only for prepaid usage components) Boolean which controls whether or not the allocated quantity should be renewed at the beginning of each period - expiration_interval (`Decimal`): (only for prepaid usage components where rollover_prepaid_remainder is true) The number of `expiration_interval_unit`s after which rollover amounts should expire - expiration_interval_unit (`Expiration Interval Unit`): (only for prepaid usage components where rollover_prepaid_remainder is true) A string representing the expiration interval unit for this component, either month or day ## Create Prepayment ### Properties - amount (`Decimal`) - details (`String`) - memo (`String`) - method (`Create Prepayment 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. - payment_profile_id (`Number`) ## Create Prepayment 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. ### Properties - check - cash - money_order - ach - paypal_account - credit_card - credit_card_on_file - other ## Create Prepayment Request ### Properties - prepayment (`Create Prepayment`) ## Create Prepayment Response ### Properties - prepayment (`Created Prepayment`) ## Create Product Currency Price ### Properties - currency (`String`): ISO code for one of the site level currencies. - price (`Number`): Price for the given role. - role (`Currency Price Role`): Role for the price. ## Create Product Currency Prices Request ### Properties - currency_prices (`array`) ## Create Product Family ### Properties - name (`String`) - handle (`String`) - description (`String`) ## Create Product Family Request ### Properties - product_family (`Create Product Family`) ## Create Product Price Point ### Properties - name (`String`): The product price point name - handle (`String`): The product price point API handle - price_in_cents (`Long`): The product price point price, in integer cents - interval (`Number`): The numerical interval. i.e. an interval of ‘30’ coupled with an interval_unit of day would mean this product price point would renew every 30 days - interval_unit (`Interval Unit`): A string representing the interval unit for this product price point, either month or day - trial_price_in_cents (`Long`): The product price point trial price, in integer cents - trial_interval (`Number`): The numerical trial interval. i.e. an interval of ‘30’ coupled with a trial_interval_unit of day would mean this product price point trial would last 30 days. - trial_interval_unit (`Interval Unit`): A string representing the trial interval unit for this product price point, either month or day - trial_type (`Trial Type`): Indicates how a trial is handled when the trail period ends and there is no credit card on file. For `no_obligation`, the subscription transitions to a Trial Ended state. Maxio will not send any emails or statements. For `payment_expected`, the subscription transitions to a Past Due state. Maxio will send normal dunning emails and statements according to your other settings. - initial_charge_in_cents (`Long`): The product price point initial charge, in integer cents - initial_charge_after_trial (`Boolean`) - expiration_interval (`Number`): The numerical expiration interval. i.e. an expiration_interval of ‘30’ coupled with an expiration_interval_unit of day would mean this product price point would expire after 30 days. - expiration_interval_unit (`Expiration Interval Unit`): A string representing the expiration interval unit for this product price point, either month, day or never - use_site_exchange_rate (`Boolean`): Whether or not to use the site's exchange rate or define your own pricing when your site has multiple currencies defined. ## Create Product Price Point Request ### Properties - price_point (`Create Product Price Point`) ## Create Quantity Based Component ### Properties - quantity_based_component (`Quantity Based Component`) ## Create Reason Code ### Properties - code (`String`): The unique identifier for the ReasonCode - description (`String`): The friendly summary of what the code signifies - position (`Number`): The order that code appears in lists ## Create Reason Code Request ### Properties - reason_code (`Create Reason Code`) ## Create Segment ### Properties - segment_property_1_value (`String | Decimal | Number | Boolean`): A value that will occur in your events that you want to bill upon. The type of the value depends on the property type in the related event based billing metric. - segment_property_2_value (`String | Decimal | Number | Boolean`): A value that will occur in your events that you want to bill upon. The type of the value depends on the property type in the related event based billing metric. - segment_property_3_value (`String | Decimal | Number | Boolean`): A value that will occur in your events that you want to bill upon. The type of the value depends on the property type in the related event based billing metric. - segment_property_4_value (`String | Decimal | Number | Boolean`): A value that will occur in your events that you want to bill upon. The type of the value depends on the property type in the related event based billing metric. - pricing_scheme (`Pricing Scheme`): The identifier for the pricing scheme. See [Product Components](https://help.chargify.com/products/product-components.html) for an overview of pricing schemes. - prices (`array`) ## Create Segment Request ### Properties - segment (`Create Segment`) ## Create Signup Proforma Preview Include ### Properties - next_proforma_invoice ## Create Subscription ### Properties - product_handle (`String`): The API Handle of the product for which you are creating a subscription. Required, unless a `product_id` is given instead. - product_id (`Number`): The Product ID of the product for which you are creating a subscription. The product ID is not currently published, so we recommend using the API Handle instead. - product_price_point_handle (`String`): The user-friendly API handle of a product's particular price point. - product_price_point_id (`Number`): The ID of the particular price point on the product. - custom_price (`Subscription Custom Price`): (Optional) Used in place of `product_price_point_id` to define a custom price point unique to the subscription - coupon_code (`String`): (deprecated) The coupon code of the single coupon currently applied to the subscription. See coupon_codes instead as subscriptions can now have more than one coupon. - coupon_codes (`array`): An array for all the coupons attached to the subscription. - payment_collection_method (`Collection Method`): The type of payment collection to be used in the subscription. For legacy Statements Architecture valid options are - `invoice`, `automatic`. For current Relationship Invoicing Architecture valid options are - `remittance`, `automatic`, `prepaid`. - receives_invoice_emails (`String`): (Optional) Default: True - Whether or not this subscription is set to receive emails related to this subscription. - net_terms (`String`): (Optional) Default: null The number of days after renewal (on invoice billing) that a subscription is due. A value between 0 (due immediately) and 180. - customer_id (`Number`): The ID of an existing customer within Chargify. Required, unless a `customer_reference` or a set of `customer_attributes` is given. - next_billing_at (`DateTime`): (Optional) Set this attribute to a future date/time to sync imported subscriptions to your existing renewal schedule. See the notes on “Date/Time Format” in our [subscription import documentation](https://maxio.zendesk.com/hc/en-us/articles/24251489107213-Advanced-Billing-Subscription-Imports#date-format). If you provide a next_billing_at timestamp that is in the future, no trial or initial charges will be applied when you create the subscription. In fact, no payment will be captured at all. The first payment will be captured, according to the prices defined by the product, near the time specified by next_billing_at. If you do not provide a value for next_billing_at, any trial and/or initial charges will be assessed and charged at the time of subscription creation. If the card cannot be successfully charged, the subscription will not be created. See further notes in the section on Importing Subscriptions. - initial_billing_at (`DateTime`): (Optional) Set this attribute to a future date/time to create a subscription in the Awaiting Signup state, rather than Active or Trialing. You can omit the initial_billing_at date to activate the subscription immediately. In the Awaiting Signup state, a subscription behaves like any other. It can be canceled, allocated to, or have its billing date changed. etc. When the initial_billing_at date hits, the subscription will transition to the expected state. If the product has a trial, the subscription will enter a trial, otherwise it will go active. Setup fees will be respected either before or after the trial, as configured on the price point. If the payment is due at the initial_billing_at and it fails the subscription will be immediately canceled. See the [subscription import](https://maxio.zendesk.com/hc/en-us/articles/24251489107213-Advanced-Billing-Subscription-Imports#date-format) documentation for more information about Date/Time Formats. - defer_signup (`Boolean`): (Optional) Set this attribute to true to create the subscription in the Awaiting Signup Date state. Use this when you want to create a subscription that has an unknown first billing date. When the first billing date is known, update a subscription and set the `initial_billing_at` date. The subscription moves to the Awaiting Signup state with a scheduled initial billing date. You can omit the initial_billing_at date to activate the subscription immediately. See [Subscription States](https://maxio-chargify.zendesk.com/hc/en-us/articles/5404222005773-Subscription-States) for more information. - stored_credential_transaction_id (`Number`): For European sites subject to PSD2 and using 3D Secure, this can be used to reference a previous transaction for the customer. This will ensure the card will be charged successfully at renewal. - sales_rep_id (`Number`) - payment_profile_id (`Number`): The Payment Profile ID of an existing card or bank account, which belongs to an existing customer to use for payment for this subscription. If the card, bank account, or customer does not exist already, or if you want to use a new (unstored) card or bank account for the subscription, use `payment_profile_attributes` instead to create a new payment profile along with the subscription. (This value is available on an existing subscription via the API as `credit_card` > id or `bank_account` > id) - reference (`String`): The reference value (provided by your app) for the subscription itself. - customer_attributes (`Customer Attributes`) - payment_profile_attributes (`Payment Profile Attributes`): alias to credit_card_attributes - credit_card_attributes (`Payment Profile Attributes`): Credit Card data to create a new Subscription. Interchangeable with `payment_profile_attributes` property. - bank_account_attributes (`Bank Account Attributes`) - components (`array`): (Optional) An array of component ids and quantities to be added to the subscription. See [Components](https://maxio.zendesk.com/hc/en-us/articles/24261141522189-Components-Overview) for more information. - calendar_billing (`Calendar Billing`): (Optional). Cannot be used when also specifying next_billing_at - metafields (`map`): (Optional) A set of key/value pairs representing custom fields and their values. Metafields will be created “on-the-fly” in your site for a given key, if they have not been created yet. - customer_reference (`String`): The reference value (provided by your app) of an existing customer within Chargify. Required, unless a `customer_id` or a set of `customer_attributes` is given. - group (`Group Settings`) - ref (`String`): A valid referral code. (optional, see [Referrals](https://maxio.zendesk.com/hc/en-us/articles/24286981223693-Referrals-Reference#how-to-obtain-referral-codes) for more details). If supplied, must be valid, or else subscription creation will fail. - cancellation_message (`String`): (Optional) Can be used when canceling a subscription (via the HTTP DELETE method) to make a note about the reason for cancellation. - cancellation_method (`String`): (Optional) Can be used when canceling a subscription (via the HTTP DELETE method) to make a note about how the subscription was canceled. - currency (`String`): (Optional) If Multi-Currency is enabled and the currency is configured in Chargify, pass it at signup to create a subscription on a non-default currency. Note that you cannot update the currency of an existing subscription. - expires_at (`DateTime`): Timestamp giving the expiration date of this subscription (if any). You may manually change the expiration date at any point during a subscription period. - expiration_tracks_next_billing_change (`String`): (Optional, default false) When set to true, and when next_billing_at is present, if the subscription expires, the expires_at will be shifted by the same amount of time as the difference between the old and new “next billing” dates. - agreement_terms (`String`): (Optional) The ACH authorization agreement terms. If enabled, an email will be sent to the customer with a copy of the terms. - authorizer_first_name (`String`): (Optional) The first name of the person authorizing the ACH agreement. - authorizer_last_name (`String`): (Optional) The last name of the person authorizing the ACH agreement. - calendar_billing_first_charge (`String`): (Optional) One of “prorated” (the default – the prorated product price will be charged immediately), “immediate” (the full product price will be charged immediately), or “delayed” (the full product price will be charged with the first scheduled renewal). - reason_code (`String`): (Optional) Can be used when canceling a subscription (via the HTTP DELETE method) to indicate why a subscription was canceled. - product_change_delayed (`Boolean`): (Optional) used only for Delayed Product Change When set to true, indicates that a changed value for product_handle should schedule the product change to the next subscription renewal. - offer_id (`String | Number`): Use in place of passing product and component information to set up the subscription with an existing offer. May be either the Chargify id of the offer or its handle prefixed with `handle:`.er - prepaid_configuration (`Upsert Prepaid Configuration`) - previous_billing_at (`DateTime`): Providing a previous_billing_at that is in the past will set the current_period_starts_at when the subscription is created. It will also set activated_at if not explicitly passed during the subscription import. Can only be used if next_billing_at is also passed. Using this option will allow you to set the period start for the subscription so mid period component allocations have the correct prorated amount. - import_mrr (`Boolean`): Setting this attribute to true will cause the subscription's MRR to be added to your MRR analytics immediately. For this value to be honored, a next_billing_at must be present and set to a future date. This key/value will not be returned in the subscription response body. - canceled_at (`DateTime`) - activated_at (`DateTime`) - agreement_acceptance (`Agreement Acceptance`): Required when creating a subscription with Maxio Payments. - ach_agreement (`ACH Agreement`): (Optional) If passed, the proof of the authorized ACH agreement terms will be persisted. - dunning_communication_delay_enabled (`Boolean`): Enable Communication Delay feature, making sure no communication (email or SMS) is sent to the Customer between 9PM and 8AM in time zone set by the `dunning_communication_delay_time_zone` attribute. - dunning_communication_delay_time_zone (`String`): Time zone for the Dunning Communication Delay feature. - skip_billing_manifest_taxes (`Boolean`): Valid only for the Subscription Preview endpoint. When set to `true` it skips calculating taxes for the current and next billing manifests. ## Create Subscription Component ### Properties - component_id (`Number | String`) - enabled (`Boolean`): Used for on/off components only. - unit_balance (`Number`): Used for metered and events based components. - allocated_quantity (`Number | String`): Used for quantity based components. - quantity (`Number`): Deprecated. Use `allocated_quantity` instead. - price_point_id (`Number | String`) - custom_price (`Component Custom Price`): Create or update custom pricing unique to the subscription. Used in place of `price_point_id`. ## Create Subscription Group ### Properties - subscription_id (`Number`) - member_ids (`array`) ## Create Subscription Group Request ### Properties - subscription_group (`Create Subscription Group`) ## Create Subscription Request ### Properties - subscription (`Create Subscription`) ## Create Usage ### Properties - quantity (`Decimal`): integer by default or decimal number if fractional quantities are enabled for the component - price_point_id (`String`) - memo (`String`) - billing_schedule (`Billing Schedule`): This attribute is particularly useful when you need to align billing events for different components on distinct schedules within a subscription. This only works for site with Multifrequency enabled. - custom_price (`Component Custom Price`): Create or update custom pricing unique to the subscription. Used in place of `price_point_id`. ## Create Usage Request ### Properties - usage (`Create Usage`) ## Created Prepayment ### Properties - id (`Long`) - subscription_id (`Number`) - amount_in_cents (`Long`) - memo (`String`) - created_at (`DateTime`) - starting_balance_in_cents (`Long`) - ending_balance_in_cents (`Long`) ## Credit Account Balance Changed ### Properties - reason (`String`) - service_credit_account_balance_in_cents (`Long`) - service_credit_balance_change_in_cents (`Long`) - currency_code (`String`) - at_time (`DateTime`) ## Credit Card Attributes ### Properties - full_number (`String`) - expiration_month (`String`) - expiration_year (`String`) ## Credit Card Vault The vault that stores the payment profile with the provided `vault_token`. Use `bogus` for testing. ### Properties - adyen - authorizenet - beanstream - blue_snap - bogus - braintree1 - braintree_blue - checkout - cybersource - elavon - eway - eway_rapid - eway_rapid_std - firstdata - forte - litle - maxio_payments - maxp - moduslink - moneris - nmi - orbital - payment_express - paymill - paypal - paypal_complete - pin - square - stripe - stripe_connect - trust_commerce - unipaas - wirecard ## Credit Note ### Properties - uid (`String`): Unique identifier for the credit note. It is generated automatically by Chargify and has the prefix "cn_" followed by alphanumeric characters. - site_id (`Number`): ID of the site to which the credit note belongs. - customer_id (`Number`): ID of the customer to which the credit note belongs. - subscription_id (`Number`): ID of the subscription that generated the credit note. - number (`String`): A unique, identifying string that appears on the credit note and in places it is referenced. While the UID is long and not appropriate to show to customers, the number is usually shorter and consumable by the customer and the merchant alike. - sequence_number (`Number`): A monotonically increasing number assigned to credit notes as they are created. This number is unique within a site and can be used to sort and order credit notes. - issue_date (`Date`): Date the credit note was issued to the customer. This is the date that the credit was made available for application, and may come before it is fully applied. The format is `"YYYY-MM-DD"`. - applied_date (`Date`): Credit notes are applied to invoices to offset invoiced amounts - they reduce the amount due. This field is the date the credit note became fully applied to invoices. If the credit note has been partially applied, this field will not have a value until it has been fully applied. The format is `"YYYY-MM-DD"`. - status (`Credit Note Status`): Current status of the credit note. - currency (`String`): The ISO 4217 currency code (3 character string) representing the currency of the credit note amount fields. - memo (`String`): The memo printed on credit note, which is a description of the reason for the credit. - seller (`Invoice Seller`): Information about the seller (merchant) listed on the masthead of the credit note. - customer (`Invoice Customer`): Information about the customer who is owner or recipient the credited subscription. - billing_address (`Invoice Address`): The billing address of the credit subscription. - shipping_address (`Invoice Address`): The shipping address of the credited subscription. - subtotal_amount (`String`): Subtotal of the credit note, which is the sum of all line items before discounts or taxes. Note that this is a positive amount representing the credit back to the customer. - discount_amount (`String`): Total discount applied to the credit note. Note that this is a positive amount representing the discount amount being credited back to the customer (i.e. a credit on an earlier discount). For example, if the original purchase was $1.00 and the original discount was $0.10, a credit of $0.50 of the original purchase (half) would have a discount credit of $0.05 (also half). - tax_amount (`String`): Total tax of the credit note. Note that this is a positive amount representing a previously taxex amount being credited back to the customer (i.e. a credit of an earlier tax). For example, if the original purchase was $1.00 and the original tax was $0.10, a credit of $0.50 of the original purchase (half) would also have a tax credit of $0.05 (also half). - total_amount (`String`): The credit note total, which is `subtotal_amount - discount_amount + tax_amount`.' - applied_amount (`String`): The amount of the credit note that has already been applied to invoices. - remaining_amount (`String`): The amount of the credit note remaining to be applied to invoices, which is `total_amount - applied_amount`. - line_items (`array`): Line items on the credit note. - discounts (`array`) - taxes (`array`) - applications (`array`) - refunds (`array`) - origin_invoices (`array`): An array of origin invoices for the credit note. Learn more about [Origin Invoice from our docs](https://maxio.zendesk.com/hc/en-us/articles/24252261284749-Credit-Notes-Proration#origin-invoices) ## Credit Note Application ### Properties - uid (`String`) - transaction_time (`DateTime`) - invoice_uid (`String`) - memo (`String`) - applied_amount (`String`) ## Credit Note Line Item ### Properties - uid (`String`): Unique identifier for the line item. Useful when cross-referencing the line against individual discounts in the `discounts` or `taxes` lists. - title (`String`): A short descriptor for the credit given by this line. - description (`String`): Detailed description for the credit given by this line. May include proration details in plain text. Note: this string may contain line breaks that are hints for the best display format on the credit note. - quantity (`String`): The quantity or count of units credited by the line item. This is a decimal number represented as a string. (See "About Decimal Numbers".) - unit_price (`String`): The price per unit for the line item. When tiered pricing was used (i.e. not every unit was actually priced at the same price) this will be the blended average cost per unit and the `tiered_unit_price` field will be set to `true`. - subtotal_amount (`String`): The line subtotal, generally calculated as `quantity * unit_price`. This is the canonical amount of record for the line - when rounding differences are in play, `subtotal_amount` takes precedence over the value derived from `quantity * unit_price` (which may not have the proper precision to exactly equal this amount). - discount_amount (`String`): The approximate discount of just this line. The value is approximated in cases where rounding errors make it difficult to apportion exactly a total discount among many lines. Several lines may have been summed prior to applying the discount to arrive at `discount_amount` for the invoice - backing that out to the discount on a single line may introduce rounding or precision errors. - tax_amount (`String`): The approximate tax of just this line. The value is approximated in cases where rounding errors make it difficult to apportion exactly a total tax among many lines. Several lines may have been summed prior to applying the tax rate to arrive at `tax_amount` for the invoice - backing that out to the tax on a single line may introduce rounding or precision errors. - total_amount (`String`): The non-canonical total amount for the line. `subtotal_amount` is the canonical amount for a line. The invoice `total_amount` is derived from the sum of the line `subtotal_amount`s and discounts or taxes applied thereafter. Therefore, due to rounding or precision errors, the sum of line `total_amount`s may not equal the invoice `total_amount`. - tiered_unit_price (`Boolean`): When `true`, indicates that the actual pricing scheme for the line was tiered, so the `unit_price` shown is the blended average for all units. - period_range_start (`Date`): Start date for the period credited by this line. The format is `"YYYY-MM-DD"`. - period_range_end (`Date`): End date for the period credited by this line. The format is `"YYYY-MM-DD"`. - product_id (`Number`): The ID of the product being credited. This may be set even for component credits, so true product-only (non-component) credits will also have a nil `component_id`. - product_version (`Number`): The version of the product being credited. - component_id (`Number`): The ID of the component being credited. Will be `nil` for non-component credits. - price_point_id (`Number`): The price point ID of the component being credited. Will be `nil` for non-component credits. - billing_schedule_item_id (`Number`) - custom_item (`Boolean`) ## Credit Note Status Current status of the credit note. ### Properties - open - applied ## Credit Scheme ### Properties - none - credit - refund ## Credit Scheme Request ### Properties - credit_scheme (`Credit Scheme`) ## Credit Type The type of credit to be created when upgrading/downgrading. Defaults to the component and then site setting if one is not provided. Available values: `full`, `prorated`, `none`. ### Properties - full - prorated - none ## Currency Price ### Properties - id (`Number`) - currency (`String`) - price (`Decimal`) - formatted_price (`String`) - price_id (`Number`) - price_point_id (`Number`) - product_price_point_id (`Number`) - role (`Currency Price Role`): Role for the price. ## Currency Price Role Role for the price. ### Properties - baseline - trial - initial ## Currency Prices Response ### Properties - currency_prices (`array`) ## Custom Field Owner ### Properties - Customer - Subscription ## Custom Field Value Change ### Properties - event_type (`String`) - metafield_name (`String`) - metafield_id (`Number`) - old_value (`String`) - new_value (`String`) - resource_type (`String`) - resource_id (`Number`) ## Customer ### Properties - first_name (`String`): The first name of the customer - last_name (`String`): The last name of the customer - email (`String`): The email address of the customer - cc_emails (`String`): A comma-separated list of emails that should be cc’d on all customer communications (i.e. “joe@example.com, sue@example.com”) - organization (`String`): The organization of the customer. If no value, `null` or empty string is provided, `organization` will be populated with the customer's first and last name, separated with a space. - reference (`String`): The unique identifier used within your own application for this customer - id (`Number`): The customer ID in Chargify - created_at (`DateTime`): The timestamp in which the customer object was created in Chargify - updated_at (`DateTime`): The timestamp in which the customer object was last edited - address (`String`): The customer’s shipping street address (i.e. “123 Main St.”) - address_2 (`String`): Second line of the customer’s shipping address i.e. “Apt. 100” - city (`String`): The customer’s shipping address city (i.e. “Boston”) - state (`String`): The customer’s shipping address state (i.e. “MA”) - state_name (`String`): The customer's full name of state - zip (`String`): The customer’s shipping address zip code (i.e. “12345”) - country (`String`): The customer shipping address country - country_name (`String`): The customer's full name of country - phone (`String`): The phone number of the customer - verified (`Boolean`): Is the customer verified to use ACH as a payment method. - portal_customer_created_at (`DateTime`): The timestamp of when the Billing Portal entry was created at for the customer - portal_invite_last_sent_at (`DateTime`): The timestamp of when the Billing Portal invite was last sent at - portal_invite_last_accepted_at (`DateTime`): The timestamp of when the Billing Portal invite was last accepted - tax_exempt (`Boolean`): The tax exempt status for the customer. Acceptable values are true or 1 for true and false or 0 for false. - vat_number (`String`): The VAT business identification number for the customer. This number is used to determine VAT tax opt out rules. It is not validated when added or updated on a customer record. Instead, it is validated via VIES before calculating taxes. Only valid business identification numbers will allow for VAT opt out. - parent_id (`Number`): The parent ID in Chargify if applicable. Parent is another Customer object. - locale (`String`): The locale for the customer to identify language-region - default_subscription_group_uid (`String`) - salesforce_id (`String`): The Salesforce ID for the customer - tax_exempt_reason (`String`): The Tax Exemption Reason Code for the customer - default_auto_renewal_profile_id (`Number`): The default auto-renewal profile ID for the customer ## Customer Attributes ### Properties - first_name (`String`): The first name of the customer. Required when creating a customer via attributes. - last_name (`String`): The last name of the customer. Required when creating a customer via attributes. - email (`String`): The email address of the customer. Required when creating a customer via attributes. - cc_emails (`String`): A list of emails that should be cc’d on all customer communications. Optional. - organization (`String`): The organization/company of the customer. Optional. - reference (`String`): A customer “reference”, or unique identifier from your app, stored in Chargify. Can be used so that you may reference your customer’s within Chargify using the same unique value you use in your application. Optional. - address (`String`): (Optional) The customer’s shipping street address (i.e. “123 Main St.”). - address_2 (`String`): (Optional) Second line of the customer’s shipping address i.e. “Apt. 100” - city (`String`): (Optional) The customer’s shipping address city (i.e. “Boston”). - state (`String`): (Optional) The customer’s shipping address state (i.e. “MA”). This must conform to the [ISO_3166-1](https://en.wikipedia.org/wiki/ISO_3166-1#Current_codes) in order to be valid for tax locale purposes. - zip (`String`): (Optional) The customer’s shipping address zip code (i.e. “12345”). - country (`String`): (Optional) The customer shipping address country, required in [ISO_3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format (i.e. “US”). - phone (`String`): (Optional) The phone number of the customer. - verified (`Boolean`) - tax_exempt (`Boolean`): (Optional) The tax_exempt status of the customer. Acceptable values are true or 1 for true and false or 0 for false. - vat_number (`String`): (Optional) Supplying the VAT number allows EU customer’s to opt-out of the Value Added Tax assuming the merchant address and customer billing address are not within the same EU country. It’s important to omit the country code from the VAT number upon entry. Otherwise, taxes will be assessed upon the purchase. - metafields (`map`): (Optional) A set of key/value pairs representing custom fields and their values. Metafields will be created “on-the-fly” in your site for a given key, if they have not been created yet. - parent_id (`Number`): The parent ID in Chargify if applicable. Parent is another Customer object. - salesforce_id (`String`): (Optional) The Salesforce ID of the customer. - default_auto_renewal_profile_id (`Number`): (Optional) The default auto-renewal profile ID for the customer ## Customer Change ### Properties - payer (`Customer Payer Change`) - shipping_address (`Address Change`) - billing_address (`Address Change`) - custom_fields (`Customer Custom Fields Change`) ## Customer Changes Preview Response ### Properties - changes (`Customer Change`) ## Customer Custom Fields Change ### Properties - before (`array`) - after (`array`) ## Customer Error ### Properties - customer (`String`) ## Customer Error Response ### Properties - errors (`Customer Error | array`) ## Customer Error Response1 ### Properties - errors (`Customer Error | array`) ## Customer Payer Change ### Properties - before (`Invoice Payer Change`) - after (`Invoice Payer Change`) ## Customer Response ### Properties - customer (`Customer`) ## Debit Note ### Properties - uid (`String`): Unique identifier for the debit note. It is generated automatically by Chargify and has the prefix "db_" followed by alphanumeric characters. - site_id (`Number`): ID of the site to which the debit note belongs. - customer_id (`Number`): ID of the customer to which the debit note belongs. - subscription_id (`Number`): ID of the subscription that generated the debit note. - number (`Number`): A unique, identifier that appears on the debit note and in places it is referenced. - sequence_number (`Number`): A monotonically increasing number assigned to debit notes as they are created. - origin_credit_note_uid (`String`): Unique identifier for the connected credit note. It is generated automatically by Chargify and has the prefix "cn_" followed by alphanumeric characters. While the UID is long and not appropriate to show to customers, the number is usually shorter and consumable by the customer and the merchant alike. - origin_credit_note_number (`String`): A unique, identifying string of the connected credit note. - issue_date (`Date`): Date the document was issued to the customer. This is the date that the document was made available for payment. The format is "YYYY-MM-DD". - applied_date (`Date`): Debit notes are applied to invoices to offset invoiced amounts - they adjust the amount due. This field is the date the debit note document became fully applied to the invoice. The format is "YYYY-MM-DD". - due_date (`Date`): Date the document is due for payment. The format is "YYYY-MM-DD". - status (`Debit Note Status`): Current status of the debit note. - memo (`String`): The memo printed on debit note, which is a description of the reason for the debit. - role (`Debit Note Role`): The role of the debit note. - currency (`String`): The ISO 4217 currency code (3 character string) representing the currency of the credit note amount fields. - seller (`Invoice Seller`): Information about the seller (merchant) listed on the masthead of the debit note. - customer (`Invoice Customer`): Information about the customer who is owner or recipient the debited subscription. - billing_address (`Invoice Address`): The billing address of the debited subscription. - shipping_address (`Invoice Address`): The shipping address of the debited subscription. - line_items (`array`): Line items on the debit note. - discounts (`array`) - taxes (`array`) - refunds (`array`) ## Debit Note Role The role of the debit note. ### Properties - chargeback - refund ## Debit Note Status Current status of the debit note. ### Properties - open - applied - banished - paid ## Deduct Service Credit ### Properties - amount (`String | Decimal`) - memo (`String`) ## Deduct Service Credit Request ### Properties - deduction (`Deduct Service Credit`) ## Delayed Cancellation Response ### Properties - message (`String`) ## Delete Subscription Group Response ### Properties - uid (`String`) - deleted (`Boolean`) ## direction ### Properties - asc - desc ## Discount Type ### Properties - amount - percent ## Dunner Data ### Properties - state (`String`) - subscription_id (`Number`) - revenue_at_risk_in_cents (`Long`) - created_at (`DateTime`) - attempts (`Number`) - last_attempted_at (`DateTime`) ## Dunning Step Data ### Properties - day_threshold (`Number`) - action (`String`) - email_body (`String`) - email_subject (`String`) - send_email (`Boolean`) - send_bcc_email (`Boolean`) - send_sms (`Boolean`) - sms_body (`String`) ## Dunning Step Reached ### Properties - dunner (`Dunner Data`) - current_step (`Dunning Step Data`) - next_step (`Dunning Step Data`) ## EBB Component ### Properties - name (`String`): A name for this component that is suitable for showing customers and displaying on billing statements, ie. "Minutes". - unit_name (`String`): The name of the unit of measurement for the component. It should be singular since it will be automatically pluralized when necessary. i.e. “message”, which may then be shown as “5 messages” on a subscription’s component line-item - description (`String`): A description for the component that will be displayed to the user on the hosted signup page. - handle (`String`): A unique identifier for your use that can be used to retrieve this component is subsequent requests. Must start with a letter or number and may only contain lowercase letters, numbers, or the characters '.', ':', '-', or '_'. - taxable (`Boolean`): Boolean flag describing whether a component is taxable or not. - pricing_scheme (`Pricing Scheme`): The identifier for the pricing scheme. See [Product Components](https://help.chargify.com/products/product-components.html) for an overview of pricing schemes. - prices (`array`): (Not required for ‘per_unit’ pricing schemes) One or more price brackets. See [Price Bracket Rules](https://maxio.zendesk.com/hc/en-us/articles/24261149166733-Component-Pricing-Schemes#price-bracket-rules) for an overview of how price brackets work for different pricing schemes. - price_points (`array`) - unit_price (`String | Decimal`): The amount the customer will be charged per unit when the pricing scheme is “per_unit”. The price can contain up to 8 decimal places. i.e. 1.00 or 0.0012 or 0.00000065 - tax_code (`String`): A string representing the tax code related to the component type. This is especially important when using AvaTax to tax based on locale. This attribute has a max length of 25 characters. - hide_date_range_on_invoice (`Boolean`): (Only available on Relationship Invoicing sites) Boolean flag describing if the service date range should show for the component on generated invoices. - event_based_billing_metric_id (`Number`): The ID of an event based billing metric that will be attached to this component. - interval (`Number`): The numerical interval. i.e. an interval of ‘30’ coupled with an interval_unit of day would mean this component's default price point would renew every 30 days. This property is only available for sites with Multifrequency enabled. - interval_unit (`Interval Unit`): A string representing the interval unit for this component's default price point, either month or day. This property is only available for sites with Multifrequency enabled. ## EBB Event ### Properties - chargify (`Chargify EBB`) ## Enable Webhooks Request ### Properties - webhooks_enabled (`Boolean`) ## Enable Webhooks Response ### Properties - webhooks_enabled (`Boolean`) ## Endpoint ### Properties - id (`Number`) - url (`String`) - site_id (`Number`) - status (`String`) - webhook_subscriptions (`array`) ## Endpoint Response ### Properties - endpoint (`Endpoint`) ## Error Array Map Response ### Properties - errors (`map`) ## Error Array Map Response1 ### Properties - errors (`map`) ## Error List Response Error which contains list of messages. ### Properties - errors (`array`) ## Error List Response1 Error which contains list of messages. ### Properties - errors (`array`) ## Error String Map Response ### Properties - errors (`map`) ## Error String Map Response1 ### Properties - errors (`map`) ## Errors ### Properties - per_page (`array`) - price_point (`array`) ## Event ### Properties - id (`Long`) - key (`Event Key`) - message (`String`) - subscription_id (`Number`) - customer_id (`Number`) - created_at (`DateTime`) - event_specific_data (`Subscription Product Change | Subscription State Change | Payment Related Events | Refund Success | Component Allocation Change | Metered Usage | Prepaid Usage | Dunning Step Reached | Invoice Issued | Pending Cancellation Change | Prepaid Subscription Balance Changed | Proforma Invoice Issued | Subscription Group Signup Event Data | Credit Account Balance Changed | Prepayment Account Balance Changed | Payment Collection Method Changed | Item Price Point Changed | Custom Field Value Change`): The schema varies based on the event key. The key-to-event data mapping is as follows: * `subscription_product_change` - SubscriptionProductChange * `subscription_state_change` - SubscriptionStateChange * `signup_success`, `delayed_signup_creation_success`, `payment_success`, `payment_failure`, `renewal_success`, `renewal_failure`, `chargeback_lost`, `chargeback_accepted`, `chargeback_closed` - PaymentRelatedEvents * `refund_success` - RefundSuccess * `component_allocation_change` - ComponentAllocationChange * `metered_usage` - MeteredUsage * `prepaid_usage` - PrepaidUsage * `dunning_step_reached` - DunningStepReached * `invoice_issued` - InvoiceIssued * `pending_cancellation_change` - PendingCancellationChange * `prepaid_subscription_balance_changed` - PrepaidSubscriptionBalanceChanged * `subscription_group_signup_success` and `subscription_group_signup_failure` - SubscriptionGroupSignupEventData * `proforma_invoice_issued` - ProformaInvoiceIssued * `subscription_prepayment_account_balance_changed` - PrepaymentAccountBalanceChanged * `payment_collection_method_changed` - PaymentCollectionMethodChanged * `subscription_service_credit_account_balance_changed` - CreditAccountBalanceChanged * `item_price_point_changed` - ItemPricePointChanged * `custom_field_value_change` - CustomFieldValueChange * The rest, that is `delayed_signup_creation_failure`, `billing_date_change`, `expiration_date_change`, `expiring_card`, `customer_update`, `customer_create`, `customer_delete`, `upgrade_downgrade_success`, `upgrade_downgrade_failure`, `statement_closed`, `statement_settled`, `subscription_card_update`, `subscription_group_card_update`, `subscription_bank_account_update`, `refund_failure`, `upcoming_renewal_notice`, `trial_end_notice`, `direct_debit_payment_paid_out`, `direct_debit_payment_rejected`, `direct_debit_payment_pending`, `pending_payment_created`, `pending_payment_failed`, `pending_payment_completed`, don't have event_specific_data defined, `renewal_success_recreated`, `renewal_failure_recreated`, `payment_success_recreated`, `payment_failure_recreated`, `subscription_deletion`, `subscription_group_bank_account_update`, `subscription_paypal_account_update`, `subscription_group_paypal_account_update`, `subscription_customer_change`, `account_transaction_changed`, `go_cardless_payment_paid_out`, `go_cardless_payment_rejected`, `go_cardless_payment_pending`, `stripe_direct_debit_payment_paid_out`, `stripe_direct_debit_payment_rejected`, `stripe_direct_debit_payment_pending`, `maxio_payments_direct_debit_payment_paid_out`, `maxio_payments_direct_debit_payment_rejected`, `maxio_payments_direct_debit_payment_pending`, `invoice_in_collections_canceled`, `subscription_added_to_group`, `subscription_removed_from_group`, `chargeback_opened`, `chargeback_lost`, `chargeback_accepted`, `chargeback_closed`, `chargeback_won`, `payment_collection_method_changed`, `component_billing_date_changed`, `subscription_term_renewal_scheduled`, `subscription_term_renewal_pending`, `subscription_term_renewal_activated`, `subscription_term_renewal_removed` they map to `null` instead. ## Event Based Billing List Segments Errors ### Properties - errors (`Errors`) ## Event Based Billing List Segments Errors1 ### Properties - errors (`Errors`) ## Event Based Billing Segment ### Properties - errors (`Event Based Billing Segment Error`) ## Event Based Billing Segment Error ### Properties - segments (`map`): The key of the object would be a number (an index in the request array) where the error occurred. In the value object, the key represents the field and the value is an array with error messages. In most cases, this object would contain just one key. ## Event Based Billing Segment Errors ### Properties - errors (`map`): The key of the object would be a number (an index in the request array) where the error occurred. In the value object, the key represents the field and the value is an array with error messages. In most cases, this object would contain just one key. ## Event Based Billing Segment Errors1 ### Properties - errors (`map`): The key of the object would be a number (an index in the request array) where the error occurred. In the value object, the key represents the field and the value is an array with error messages. In most cases, this object would contain just one key. ## Event Based Billing Segment1 ### Properties - errors (`Event Based Billing Segment Error`) ## Event Key ### Properties - payment_success - payment_failure - signup_success - signup_failure - delayed_signup_creation_success - delayed_signup_creation_failure - billing_date_change - expiration_date_change - renewal_success - renewal_failure - subscription_state_change - subscription_product_change - pending_cancellation_change - expiring_card - customer_update - customer_create - customer_delete - component_allocation_change - metered_usage - prepaid_usage - upgrade_downgrade_success - upgrade_downgrade_failure - statement_closed - statement_settled - subscription_card_update - subscription_group_card_update - subscription_bank_account_update - refund_success - refund_failure - upcoming_renewal_notice - trial_end_notice - dunning_step_reached - invoice_issued - prepaid_subscription_balance_changed - subscription_group_signup_success - subscription_group_signup_failure - direct_debit_payment_paid_out - direct_debit_payment_rejected - direct_debit_payment_pending - pending_payment_created - pending_payment_failed - pending_payment_completed - proforma_invoice_issued - subscription_prepayment_account_balance_changed - subscription_service_credit_account_balance_changed - custom_field_value_change - item_price_point_changed - renewal_success_recreated - renewal_failure_recreated - payment_success_recreated - payment_failure_recreated - subscription_deletion - subscription_group_bank_account_update - subscription_paypal_account_update - subscription_group_paypal_account_update - subscription_customer_change - account_transaction_changed - go_cardless_payment_paid_out - go_cardless_payment_rejected - go_cardless_payment_pending - stripe_direct_debit_payment_paid_out - stripe_direct_debit_payment_rejected - stripe_direct_debit_payment_pending - maxio_payments_direct_debit_payment_paid_out - maxio_payments_direct_debit_payment_rejected - maxio_payments_direct_debit_payment_pending - invoice_in_collections_canceled - subscription_added_to_group - subscription_removed_from_group - chargeback_opened - chargeback_lost - chargeback_accepted - chargeback_closed - chargeback_won - payment_collection_method_changed - component_billing_date_changed - subscription_term_renewal_scheduled - subscription_term_renewal_pending - subscription_term_renewal_activated - subscription_term_renewal_removed ## Event Response ### Properties - event (`Event`) ## Expiration Interval Unit ### Properties - day - month - never ## Failed Payment Action Action taken when payment for an invoice fails: - `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). ### Properties - leave_open_invoice - rollback_to_pending - initiate_dunning ## Failed Payment Event Data Example schema for an `failed_payment` event ### Properties - amount_in_cents (`Number`): The monetary value of the payment, expressed in cents. - applied_amount (`Number`): The monetary value of the payment, expressed in dollars. - memo (`String`): The memo passed when the payment was created. - payment_method (`Invoice Payment Method Type`) - transaction_id (`Number`): The transaction ID of the failed payment. ## First Charge Type ### Properties - prorated - immediate - delayed ## Full Subscription Group Response ### Properties - uid (`String`) - scheme (`Number`) - customer_id (`Number`) - payment_profile_id (`Number`) - subscription_ids (`array`) - primary_subscription_id (`Number`) - next_assessment_at (`DateTime`) - state (`Subscription State`): The state of a subscription. * **Live States** * `active` - A normal, active subscription. It is not in a trial and is paid and up to date. * `assessing` - An internal (transient) state that indicates a subscription is in the middle of periodic assessment. Do not base any access decisions in your app on this state, as it may not always be exposed. * `pending` - An internal (transient) state that indicates a subscription is in the creation process. Do not base any access decisions in your app on this state, as it may not always be exposed. * `trialing` - A subscription in trialing state has a valid trial subscription. This type of subscription may transition to active once payment is received when the trial has ended. Otherwise, it may go to a Problem or End of Life state. * `paused` - An internal state that indicates that your account with Advanced Billing is in arrears. * **Problem States** * `past_due` - Indicates that the most recent payment has failed, and payment is past due for this subscription. If you have enabled our automated dunning, this subscription will be in the dunning process (additional status and callbacks from the dunning process will be available in the future). If you are handling dunning and payment updates yourself, you will want to use this state to initiate a payment update from your customers. * `soft_failure` - Indicates that normal assessment/processing of the subscription has failed for a reason that cannot be fixed by the Customer. For example, a Soft Fail may result from a timeout at the gateway or incorrect credentials on your part. The subscriptions should be retried automatically. An interface is being built for you to review problems resulting from these events to take manual action when needed. * `unpaid` - Indicates an unpaid subscription. A subscription is marked unpaid if the retry period expires and you have configured your [Dunning](https://maxio.zendesk.com/hc/en-us/articles/24287076583565-Dunning-Overview) settings to have a Final Action of `mark the subscription unpaid`. * **End of Life States** * `canceled` - Indicates a canceled subscription. This may happen at your request (via the API or the web interface) or due to the expiration of the [Dunning](https://maxio.zendesk.com/hc/en-us/articles/24287076583565-Dunning-Overview) process without payment. See the [Reactivation](https://maxio.zendesk.com/hc/en-us/articles/24252109503629-Reactivating-and-Resuming) documentation for info on how to restart a canceled subscription. While a subscription is canceled, its period will not advance, it will not accrue any new charges, and Advanced Billing will not attempt to collect the overdue balance. * `expired` - Indicates a subscription that has expired due to running its normal life cycle. Some products may be configured to have an expiration period. An expired subscription then is one that stayed active until it fulfilled its full period. * `failed_to_create` - Indicates that signup has failed. (You may see this state in a signup_failure webhook.) * `on_hold` - Indicates that a subscription’s billing has been temporarily stopped. While it is expected that the subscription will resume and return to active status, this is still treated as an “End of Life” state because the customer is not paying for services during this time. * `suspended` - Indicates that a prepaid subscription has used up all their prepayment balance. If a prepayment is applied, it will return to an active state. * `trial_ended` - A subscription in a trial_ended state is a subscription that completed a no-obligation trial and did not have a card on file at the expiration of the trial period. See [Product Pricing – No Obligation Trials](https://maxio.zendesk.com/hc/en-us/articles/24261076617869-Product-Editing) for more details. See [Subscription States](https://maxio.zendesk.com/hc/en-us/articles/24252119027853-Subscription-States) for more info about subscription states and state transitions. - cancel_at_end_of_period (`Boolean`) - current_billing_amount_in_cents (`Long`) - customer (`Subscription Group Customer`) - account_balances (`Subscription Group Balances`) ## Get One Time Token Payment Profile ### Properties - id (`String`) - first_name (`String`) - last_name (`String`) - masked_card_number (`String`) - card_type (`Card Type`): The type of card used. - expiration_month (`Decimal`) - expiration_year (`Decimal`) - customer_id (`String`) - current_vault (`Credit Card Vault`): The vault that stores the payment profile with the provided `vault_token`. Use `bogus` for testing. - vault_token (`String`) - billing_address (`String`) - billing_address_2 (`String`) - billing_city (`String`) - billing_country (`String`) - billing_state (`String`) - billing_zip (`String`) - payment_type (`String`) - disabled (`Boolean`) - site_gateway_setting_id (`Number`) - customer_vault_token (`String`) - gateway_handle (`String`) ## Get One Time Token Request ### Properties - payment_profile (`Get One Time Token Payment Profile`) ## Group Billing Optional attributes related to billing date and accrual. Note: Only applicable for new subscriptions. ### Properties - accrue (`Boolean`): A flag indicating whether or not to accrue charges on the new subscription. - align_date (`Boolean`): A flag indicating whether or not to align the billing date of the new subscription with the billing date of the primary subscription of the hierarchy's default subscription group. Required to be true if prorate is also true. - prorate (`Boolean`): A flag indicating whether or not to prorate billing of the new subscription for the current period. A value of true is ignored unless align_date is also true. ## Group Settings ### Properties - target (`Group Target`): Attributes of the target customer who will be the responsible payer of the created subscription. Required. - billing (`Group Billing`): Optional attributes related to billing date and accrual. Note: Only applicable for new subscriptions. ## Group Target Attributes of the target customer who will be the responsible payer of the created subscription. Required. ### Properties - type (`Group Target Type`): The type of object indicated by the id attribute. - id (`Number`): The id of the target customer or subscription to group the existing subscription with. Ignored and should not be included if type is "self" , "parent", or "eldest" ## Group Target Type The type of object indicated by the id attribute. ### Properties - customer - subscription - self - parent - eldest ## Group Type ### Properties - single_customer - multiple_customers ## Historic Usage Optional for Event Based Components. If the `include=historic_usages` query param is provided, the last ten billing periods will be returned. ### Properties - total_usage_quantity (`Decimal`): Total usage of a component for billing period - billing_period_starts_at (`DateTime`): Start date of billing period - billing_period_ends_at (`DateTime`): End date of billing period ## Include Not Null Passed as a parameter to list methods to return only non null values. ### Properties - not_null ## Include Null Or Not Null Allows to filter by `not_null` or `null`. ### Properties - not_null - null ## Include Option ### Properties - Exclude - Include ## Interval Unit ### Properties - day - month ## Invoice ### Properties - id (`Long`) - uid (`String`): Unique identifier for the invoice. It is generated automatically by Chargify and has the prefix "inv_" followed by alphanumeric characters. - site_id (`Number`): ID of the site to which the invoice belongs. - customer_id (`Number`): ID of the customer to which the invoice belongs. - subscription_id (`Number`): ID of the subscription that generated the invoice. - number (`String`): A unique, identifying string that appears on the invoice and in places the invoice is referenced. While the UID is long and not appropriate to show to customers, the number is usually shorter and consumable by the customer and the merchant alike. - sequence_number (`Number`): A monotonically increasing number assigned to invoices as they are created. This number is unique within a site and can be used to sort and order invoices. - transaction_time (`DateTime`) - created_at (`DateTime`) - updated_at (`DateTime`) - issue_date (`Date`): Date the invoice was issued to the customer. This is the date that the invoice was made available for payment. The format is `"YYYY-MM-DD"`. - due_date (`Date`): Date the invoice is due. The format is `"YYYY-MM-DD"`. - paid_date (`Date`): Date the invoice became fully paid. If partial payments are applied to the invoice, this date will not be present until payment has been made in full. The format is `"YYYY-MM-DD"`. - status (`Invoice Status`): The current status of the invoice. See [Invoice Statuses](https://maxio.zendesk.com/hc/en-us/articles/24252287829645-Advanced-Billing-Invoices-Overview#invoice-statuses) for more. - role (`Invoice Role`) - parent_invoice_id (`Number`) - collection_method (`Collection Method`): The type of payment collection to be used in the subscription. For legacy Statements Architecture valid options are - `invoice`, `automatic`. For current Relationship Invoicing Architecture valid options are - `remittance`, `automatic`, `prepaid`. - payment_instructions (`String`): A message that is printed on the invoice when it is marked for remittance collection. It is intended to describe to the customer how they may make payment, and is configured by the merchant. - currency (`String`): The ISO 4217 currency code (3 character string) representing the currency of invoice transaction. - consolidation_level (`Invoice Consolidation Level`): Consolidation level of the invoice, which is applicable to invoice consolidation. It will hold one of the following values: * "none": A normal invoice with no consolidation. * "child": An invoice segment which has been combined into a consolidated invoice. * "parent": A consolidated invoice, whose contents are composed of invoice segments. "Parent" invoices do not have lines of their own, but they have subtotals and totals which aggregate the member invoice segments. See also the [invoice consolidation documentation](https://maxio.zendesk.com/hc/en-us/articles/24252269909389-Invoice-Consolidation). - parent_invoice_uid (`String`): For invoices with `consolidation_level` of `child`, this specifies the UID of the parent (consolidated) invoice. - subscription_group_id (`Number`) - parent_invoice_number (`Number`): For invoices with `consolidation_level` of `child`, this specifies the number of the parent (consolidated) invoice. - group_primary_subscription_id (`Number`): For invoices with `consolidation_level` of `parent`, this specifies the ID of the subscription which was the primary subscription of the subscription group that generated the invoice. - product_name (`String`): The name of the product subscribed when the invoice was generated. - product_family_name (`String`): The name of the product family subscribed when the invoice was generated. - seller (`Invoice Seller`): Information about the seller (merchant) listed on the masthead of the invoice. - customer (`Invoice Customer`): Information about the customer who is owner or recipient the invoiced subscription. - payer (`Invoice Payer`) - recipient_emails (`array`) - net_terms (`Number`) - memo (`String`): The memo printed on invoices of any collection type. This message is in control of the merchant. - billing_address (`Invoice Address`): The invoice billing address. - shipping_address (`Invoice Address`): The invoice shipping address. - subtotal_amount (`String`): Subtotal of the invoice, which is the sum of all line items before discounts or taxes. - discount_amount (`String`): Total discount applied to the invoice. - tax_amount (`String`): Total tax on the invoice. - total_amount (`String`): The invoice total, which is `subtotal_amount - discount_amount + tax_amount`.' - credit_amount (`String`): The amount of credit (from credit notes) applied to this invoice. Credits offset the amount due from the customer. - debit_amount (`String`) - refund_amount (`String`) - paid_amount (`String`): The amount paid on the invoice by the customer. - due_amount (`String`): Amount due on the invoice, which is `total_amount - credit_amount - paid_amount`. - line_items (`array`): Line items on the invoice. - discounts (`array`) - taxes (`array`) - credits (`array`) - debits (`array`) - refunds (`array`) - payments (`array`) - custom_fields (`array`) - display_settings (`Invoice Display Settings`) - avatax_details (`Invoice Avatax Details`) - public_url (`String`): The public URL of the invoice - previous_balance_data (`Invoice Previous Balance`) - public_url_expires_on (`Date`): The format is `"YYYY-MM-DD"`. ## Invoice Address ### Properties - street (`String`) - line2 (`String`) - city (`String`) - state (`String`) - zip (`String`) - country (`String`) ## Invoice Avatax Details ### Properties - id (`Long`) - status (`String`) - document_code (`String`) - commit_date (`DateTime`) - modify_date (`DateTime`) ## Invoice Balance Item ### Properties - uid (`String`) - number (`String`) - outstanding_amount (`String`) ## Invoice Consolidation Level Consolidation level of the invoice, which is applicable to invoice consolidation. It will hold one of the following values: * "none": A normal invoice with no consolidation. * "child": An invoice segment which has been combined into a consolidated invoice. * "parent": A consolidated invoice, whose contents are composed of invoice segments. "Parent" invoices do not have lines of their own, but they have subtotals and totals which aggregate the member invoice segments. See also the [invoice consolidation documentation](https://maxio.zendesk.com/hc/en-us/articles/24252269909389-Invoice-Consolidation). ### Properties - none - child - parent ## Invoice Credit ### Properties - uid (`String`) - credit_note_number (`String`) - credit_note_uid (`String`) - transaction_time (`DateTime`) - memo (`String`) - original_amount (`String`) - applied_amount (`String`) ## Invoice Custom Field ### Properties - owner_id (`Number`) - owner_type (`Custom Field Owner`) - name (`String`) - value (`String`) - metadatum_id (`Number`) ## Invoice Customer Information about the customer who is owner or recipient the invoiced subscription. ### Properties - chargify_id (`Number`) - first_name (`String`) - last_name (`String`) - organization (`String`) - email (`String`) - vat_number (`String`) - reference (`String`) ## Invoice Date Field ### Properties - created_at - due_date - issue_date - updated_at - paid_date ## Invoice Debit ### Properties - uid (`String`) - debit_note_number (`String`) - debit_note_uid (`String`) - role (`Debit Note Role`): The role of the debit note. - transaction_time (`DateTime`) - memo (`String`) - original_amount (`String`) - applied_amount (`String`) ## Invoice Discount ### Properties - uid (`String`) - title (`String`) - description (`String`) - code (`String`) - source_type (`Invoice Discount Source Type`) - source_id (`Number`) - discount_type (`Invoice Discount Type`) - percentage (`String`) - eligible_amount (`String`) - discount_amount (`String`) - transaction_id (`Number`) - line_item_breakouts (`array`) ## Invoice Discount Breakout ### Properties - uid (`String`) - eligible_amount (`String`) - discount_amount (`String`) ## Invoice Discount Source Type ### Properties - Coupon - Referral - Enum_Ad Hoc Coupon ## Invoice Discount Type ### Properties - percentage - flat_amount - rollover ## Invoice Display Settings ### Properties - hide_zero_subtotal_lines (`Boolean`) - include_discounts_on_lines (`Boolean`) ## Invoice Event Payment Method ### Properties - apple_pay - bank_account - credit_card - external - paypal_account ## Invoice Event Type Invoice Event Type ### Properties - issue_invoice - apply_credit_note - create_credit_note - apply_payment - apply_debit_note - create_debit_note - refund_invoice - void_invoice - void_remainder - backport_invoice - change_invoice_status - change_invoice_collection_method - remove_payment - failed_payment - change_chargeback_status ## Invoice Issued ### Properties - uid (`String`) - number (`String`) - role (`String`) - due_date (`Date`) - issue_date (`String`): Invoice issue date. Can be an empty string if value is missing. - paid_date (`String`): Paid date. Can be an empty string if value is missing. - due_amount (`String`) - paid_amount (`String`) - tax_amount (`String`) - refund_amount (`String`) - total_amount (`String`) - status_amount (`String`) - product_name (`String`) - consolidation_level (`String`) - line_items (`array`) ## Invoice Line Item ### Properties - uid (`String`): Unique identifier for the line item. Useful when cross-referencing the line against individual discounts in the `discounts` or `taxes` lists. - title (`String`): A short descriptor for the charge or item represented by this line. - description (`String`): Detailed description for the charge or item represented by this line. May include proration details in plain text. Note: this string may contain line breaks that are hints for the best display format on the invoice. - quantity (`String`): The quantity or count of units billed by the line item. This is a decimal number represented as a string. (See "About Decimal Numbers".) - unit_price (`String`): The price per unit for the line item. When tiered pricing was used (i.e. not every unit was actually priced at the same price) this will be the blended average cost per unit and the `tiered_unit_price` field will be set to `true`. - subtotal_amount (`String`): The line subtotal, generally calculated as `quantity * unit_price`. This is the canonical amount of record for the line - when rounding differences are in play, `subtotal_amount` takes precedence over the value derived from `quantity * unit_price` (which may not have the proper precision to exactly equal this amount). - discount_amount (`String`): The approximate discount applied to just this line. The value is approximated in cases where rounding errors make it difficult to apportion exactly a total discount among many lines. Several lines may have been summed prior to applying the discount to arrive at `discount_amount` for the invoice - backing that out to the discount on a single line may introduce rounding or precision errors. - tax_amount (`String`): The approximate tax applied to just this line. The value is approximated in cases where rounding errors make it difficult to apportion exactly a total tax among many lines. Several lines may have been summed prior to applying the tax rate to arrive at `tax_amount` for the invoice - backing that out to the tax on a single line may introduce rounding or precision errors. - total_amount (`String`): The non-canonical total amount for the line. `subtotal_amount` is the canonical amount for a line. The invoice `total_amount` is derived from the sum of the line `subtotal_amount`s and discounts or taxes applied thereafter. Therefore, due to rounding or precision errors, the sum of line `total_amount`s may not equal the invoice `total_amount`. - tiered_unit_price (`Boolean`): When `true`, indicates that the actual pricing scheme for the line was tiered, so the `unit_price` shown is the blended average for all units. - period_range_start (`Date`): Start date for the period covered by this line. The format is `"YYYY-MM-DD"`. * For periodic charges paid in advance, this date will match the billing date, and the end date will be in the future. * For periodic charges paid in arrears (e.g. metered charges), this date will be the date of the previous billing, and the end date will be the current billing date. * For non-periodic charges, this date and the end date will match. - period_range_end (`Date`): End date for the period covered by this line. The format is `"YYYY-MM-DD"`. * For periodic charges paid in advance, this date will match the next (future) billing date. * For periodic charges paid in arrears (e.g. metered charges), this date will be the date of the current billing date. * For non-periodic charges, this date and the start date will match. - transaction_id (`Number`) - product_id (`Number`): The ID of the product subscribed when the charge was made. This may be set even for component charges, so true product-only (non-component) charges will also have a nil `component_id`. - product_version (`Number`): The version of the product subscribed when the charge was made. - component_id (`Number`): The ID of the component being billed. Will be `nil` for non-component charges. - price_point_id (`Number`): The price point ID of the component being billed. Will be `nil` for non-component charges. - billing_schedule_item_id (`Number`) - hide (`Boolean`) - component_cost_data (`Invoice Line Item Component Cost Data`) - product_price_point_id (`Number`): The price point ID of the line item's product - custom_item (`Boolean`) - kind (`String`) ## Invoice Line Item Component Cost Data ### Properties - rates (`array`) ## Invoice Line Item Event Data ### Properties - uid (`String`) - title (`String`) - description (`String`) - quantity (`Number`) - quantity_delta (`Number`) - unit_price (`String`) - period_range_start (`String`) - period_range_end (`String`) - amount (`String`) - line_references (`String`) - pricing_details_index (`Number`) - pricing_details (`array`) - tax_code (`String`) - tax_amount (`String`) - product_id (`Number`) - product_price_point_id (`Number`) - price_point_id (`Number`) - component_id (`Number`) - billing_schedule_item_id (`Number`) - custom_item (`Boolean`) ## Invoice Line Item Pricing Detail ### Properties - label (`String`) - amount (`String`) ## Invoice Payer ### Properties - chargify_id (`Number`) - first_name (`String`) - last_name (`String`) - organization (`String`) - email (`String`) - vat_number (`String`) ## Invoice Payer Change ### Properties - first_name (`String`) - last_name (`String`) - organization (`String`) - email (`String`) ## Invoice Payment ### Properties - transaction_time (`DateTime`) - memo (`String`) - original_amount (`String`) - applied_amount (`String`) - payment_method (`Invoice Payment Method`) - transaction_id (`Number`) - prepayment (`Boolean`) - gateway_handle (`String`) - gateway_used (`String`) - gateway_transaction_id (`String`): The transaction ID for the payment as returned from the payment gateway - received_on (`Date`): Date reflecting when the payment was received from a customer. Must be in the past. Applicable only to `external` payments. - uid (`String`) ## Invoice Payment Application ### Properties - invoice_uid (`String`): Unique identifier for the paid invoice. It has the prefix "inv_" followed by alphanumeric characters. - application_uid (`String`): Unique identifier for the payment. It has the prefix "pmt_" followed by alphanumeric characters. - applied_amount (`String`): Dollar amount of the paid invoice. ## Invoice Payment Method ### Properties - details (`String`) - kind (`String`) - memo (`String`) - type (`String`) - card_brand (`String`) - card_expiration (`String`) - last_four (`String`) - masked_card_number (`String`) ## Invoice Payment Method Type The type of payment method used. Defaults to other. ### Properties - credit_card - check - cash - money_order - ach - other ## Invoice Payment Type The type of payment to be applied to an Invoice. Defaults to external. ### Properties - external - prepayment - service_credit - payment ## Invoice PrePayment ### Properties - subscription_id (`Number`): The subscription id for the prepayment account - amount_in_cents (`Long`): The amount in cents of the prepayment that was created as a result of this payment. - ending_balance_in_cents (`Long`): The total balance of the prepayment account for this subscription including any prior prepayments ## Invoice Previous Balance ### Properties - captured_at (`DateTime`) - invoices (`array`) ## Invoice Refund ### Properties - transaction_id (`Number`) - payment_id (`Number`) - memo (`String`) - original_amount (`String`) - applied_amount (`String`) - gateway_transaction_id (`String`): The transaction ID for the refund as returned from the payment gateway - gateway_used (`String`) - gateway_handle (`String`) - ach_late_reject (`Boolean`) ## Invoice Response ### Properties - invoice (`Invoice`) ## Invoice Role ### Properties - unset - signup - renewal - usage - reactivation - proration - migration - adhoc - backport - backportbalancereconciliation ## Invoice Seller Information about the seller (merchant) listed on the masthead of the invoice. ### Properties - name (`String`) - address (`Invoice Address`) - phone (`String`) - logo_url (`String`) ## Invoice Sort Field ### Properties - status - total_amount - due_amount - created_at - updated_at - issue_date - due_date - number ## Invoice Status The current status of the invoice. See [Invoice Statuses](https://maxio.zendesk.com/hc/en-us/articles/24252287829645-Advanced-Billing-Invoices-Overview#invoice-statuses) for more. ### Properties - draft - open - paid - pending - voided - canceled - processing ## Invoice Tax ### Properties - uid (`String`) - title (`String`) - description (`String`) - source_type (`Proforma Invoice Tax Source Type`) - source_id (`Number`) - percentage (`String`) - taxable_amount (`String`) - tax_amount (`String`) - transaction_id (`Number`) - line_item_breakouts (`array`) - tax_component_breakouts (`array`) - eu_vat (`Boolean`) - type (`String`) - tax_exempt_amount (`String`) ## Invoice Tax Breakout ### Properties - uid (`String`) - taxable_amount (`String`) - tax_amount (`String`) - tax_exempt_amount (`String`) ## Invoice Tax Component Breakout ### Properties - tax_rule_id (`Number`) - percentage (`String`) - country_code (`String`) - subdivision_code (`String`) - tax_amount (`String`) - taxable_amount (`String`) - tax_exempt_amount (`String`) - non_taxable_amount (`String`) - tax_name (`String`) - tax_type (`String`) - rate_type (`String`) - tax_authority_type (`Number`) - state_assigned_no (`String`) - tax_sub_type (`String`) ## Issue Advance Invoice Request ### Properties - force (`Boolean`) ## Issue Invoice Event Data Example schema for an `issue_invoice` event ### Properties - consolidation_level (`Invoice Consolidation Level`): Consolidation level of the invoice, which is applicable to invoice consolidation. It will hold one of the following values: * "none": A normal invoice with no consolidation. * "child": An invoice segment which has been combined into a consolidated invoice. * "parent": A consolidated invoice, whose contents are composed of invoice segments. "Parent" invoices do not have lines of their own, but they have subtotals and totals which aggregate the member invoice segments. See also the [invoice consolidation documentation](https://maxio.zendesk.com/hc/en-us/articles/24252269909389-Invoice-Consolidation). - from_status (`Invoice Status`): The status of the invoice before event occurrence. See [Invoice Statuses](https://maxio.zendesk.com/hc/en-us/articles/24252287829645-Advanced-Billing-Invoices-Overview#invoice-statuses) for more. - to_status (`Invoice Status`): The status of the invoice after event occurrence. See [Invoice Statuses](https://maxio.zendesk.com/hc/en-us/articles/24252287829645-Advanced-Billing-Invoices-Overview#invoice-statuses) for more. - due_amount (`String`): Amount due on the invoice, which is `total_amount - credit_amount - paid_amount`. - total_amount (`String`): The invoice total, which is `subtotal_amount - discount_amount + tax_amount`.' ## Issue Invoice Request ### Properties - on_failed_payment (`Failed Payment Action`): Action taken when payment for an invoice fails: - `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). ## Issue Service Credit ### Properties - amount (`Decimal | String`) - memo (`String`) ## Issue Service Credit Request ### Properties - service_credit (`Issue Service Credit`) ## Item Category One of the following: Business Software, Consumer Software, Digital Services, Physical Goods, Other ### Properties - Enum_Business Software - Enum_Consumer Software - Enum_Digital Services - Enum_Physical Goods - Other ## Item Price Point Changed ### Properties - item_id (`Number`) - item_type (`String`) - item_handle (`String`) - item_name (`String`) - previous_price_point (`Item Price Point Data`) - current_price_point (`Item Price Point Data`) ## Item Price Point Data ### Properties - id (`Number`) - handle (`String`) - name (`String`) ## Line Item Kind A handle for the line item kind ### Properties - baseline - initial - trial - quantity_based_component - prepaid_usage_component - on_off_component - metered_component - event_based_component - coupon - tax ## Line Item Transaction Type A handle for the line item transaction type ### Properties - charge - credit - adjustment - payment - refund - info_transaction - payment_authorization ## List Components Filter ### Properties - ids (`array`): Allows fetching components with matching id based on provided value. Use in query `filter[ids]=1,2,3`. - use_site_exchange_rate (`Boolean`): Allows fetching components with matching use_site_exchange_rate based on provided value (refers to default price point). Use in query `filter[use_site_exchange_rate]=true`. ## List Components Price Points Include ### Properties - currency_prices ## List Components Price Points Response ### Properties - price_points (`array`) ## List Coupons Filter ### Properties - date_field (`Basic Date Field`): The type of filter you would like to apply to your search. Use in query `filter[date_field]=created_at`. - start_date (`Date`): The start date (format YYYY-MM-DD) with which to filter the date_field. Returns coupons with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified. Use in query `filter[start_date]=2011-12-17`. - end_date (`Date`): The end date (format YYYY-MM-DD) with which to filter the date_field. Returns coupons with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified. Use in query `filter[end_date]=2011-12-15`. - start_datetime (`DateTime`): The start date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns coupons 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 `filter[start_datetime]=2011-12-19T10:15:30+01:00`. - end_datetime (`DateTime`): The end date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns coupons 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 `filter[end_datetime]=2011-12-1T10:15:30+01:00`. - ids (`array`): Allows fetching coupons with matching id based on provided values. Use in query `filter[ids]=1,2,3`. - codes (`array`): Allows fetching coupons with matching codes based on provided values. Use in query `filter[codes]=free,free_trial`. - use_site_exchange_rate (`Boolean`): If true, restricts the list to coupons whose pricing is recalculated from the site’s current exchange rates, so their currency_prices array contains on-the-fly conversions rather than stored price records. If false, restricts the list to coupons that have manually defined amounts for each currency, ensuring the response includes the saved currency_prices entries instead of exchange-rate-derived values. Use in query `filter[use_site_exchange_rate]=true`. - include_archived (`Boolean`): Controls returning archived coupons. ## List Credit Notes Response ### Properties - credit_notes (`array`) ## List Events Date Field ### Properties - created_at ## List Invoices Response ### Properties - invoices (`array`) ## List Metafields Response ### Properties - total_count (`Number`) - current_page (`Number`) - total_pages (`Number`) - per_page (`Number`) - metafields (`array`) ## List Mrr Filter ### Properties - subscription_ids (`array`): Submit ids in order to limit results. Use in query: `filter[subscription_ids]=1,2,3`. ## List MRR Response ### Properties - mrr (`List MRR Response Result`) ## List MRR Response Result ### Properties - page (`Number`) - per_page (`Number`) - total_pages (`Number`) - total_entries (`Number`) - currency (`String`) - currency_symbol (`String`) - movements (`array`) ## List Offers Response ### Properties - offers (`array`) ## List Prepayment Date Field ### Properties - created_at - application_at ## List Prepayments Filter ### Properties - date_field (`List Prepayment Date Field`): The type of filter you would like to apply to your search. `created_at` - Time when prepayment was created. `application_at` - Time when prepayment was applied to invoice. Use in query `filter[date_field]=created_at`. - start_date (`Date`): The start date (format YYYY-MM-DD) with which to filter the date_field. Returns prepayments with a timestamp at or after midnight (12:00:00 AM) in your site's time zone on the date specified. Use in query: `filter[start_date]=2011-12-15`. - end_date (`Date`): The end date (format YYYY-MM-DD) with which to filter the date_field. Returns prepayments with a timestamp up to and including 11:59:59PM in your site's time zone on the date specified. Use in query: `filter[end_date]=2011-12-15`. ## List PricePoints Filter ### Properties - date_field (`Basic Date Field`): The type of filter you would like to apply to your search. Use in query: `filter[date_field]=created_at`. - start_date (`Date`): The start date (format YYYY-MM-DD) with which to filter the date_field. Returns price points with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified. - end_date (`Date`): The end date (format YYYY-MM-DD) with which to filter the date_field. Returns price points with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified. - start_datetime (`DateTime`): The start date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns price points 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`): The end date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns price points 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. - type (`array`): Allows fetching price points with matching type. Use in query: `filter[type]=custom,catalog`. - ids (`array`): Allows fetching price points with matching id based on provided values. Use in query: `filter[ids]=1,2,3`. - archived_at (`Include Null or Not Null`): Allows fetching price points only if archived_at is present or not. Use in query: `filter[archived_at]=not_null`. ## List Product Price Points Response ### Properties - price_points (`array`) ## List Products Filter ### Properties - ids (`array`): Allows fetching products with matching id based on provided values. Use in query `filter[ids]=1,2,3`. - prepaid_product_price_point (`Prepaid Product Price Point Filter`): Allows fetching products only if a prepaid product price point is present or not. To use this filter you also have to include the following param in the request `include=prepaid_product_price_point`. Use in query `filter[prepaid_product_price_point][product_price_point_id]=not_null`. - use_site_exchange_rate (`Boolean`): Allows fetching products with matching use_site_exchange_rate based on provided value (refers to default price point). Use in query `filter[use_site_exchange_rate]=true`. ## List Products Include ### Properties - prepaid_product_price_point ## List Products Price Points Include ### Properties - currency_prices ## List Proforma Invoices Meta ### Properties - total_count (`Number`) - current_page (`Number`) - total_pages (`Number`) - status_code (`Number`) ## List Proforma Invoices Response ### Properties - proforma_invoices (`array`) - meta (`List Proforma Invoices Meta`) ## List Public Keys Meta ### Properties - total_count (`Number`) - current_page (`Number`) - total_pages (`Number`) - per_page (`Number`) ## List Public Keys Response ### Properties - chargify_js_keys (`array`) - meta (`List Public Keys Meta`) ## List Sale Rep Item ### Properties - id (`Number`) - full_name (`String`) - subscriptions_count (`Number`) - mrr_data (`map`) - test_mode (`Boolean`) ## List Segments Filter ### Properties - segment_property_1_value (`String`): The value passed here would be used to filter segments. Pass a value related to `segment_property_1` on attached Metric. If empty string is passed, this filter would be rejected. Use in query `filter[segment_property_1_value]=EU`. - segment_property_2_value (`String`): The value passed here would be used to filter segments. Pass a value related to `segment_property_2` on attached Metric. If empty string is passed, this filter would be rejected. - segment_property_3_value (`String`): The value passed here would be used to filter segments. Pass a value related to `segment_property_3` on attached Metric. If empty string is passed, this filter would be rejected. - segment_property_4_value (`String`): The value passed here would be used to filter segments. Pass a value related to `segment_property_4` on attached Metric. If empty string is passed, this filter would be rejected. ## List Segments Response ### Properties - segments (`array`) ## List Service Credits Response ### Properties - service_credits (`array`) ## List Subcription Group Prepayment Item ### Properties - id (`Number`) - subscription_group_uid (`String`) - amount_in_cents (`Long`) - remaining_amount_in_cents (`Long`) - details (`String`) - external (`Boolean`) - memo (`String`) - payment_type (`Prepayment Method`) - created_at (`DateTime`) ## List Subscription Components Filter ### Properties - currencies (`array`): Allows fetching components allocation with matching currency based on provided values. Use in query `filter[currencies]=EUR,USD`. - use_site_exchange_rate (`Boolean`): Allows fetching components allocation with matching use_site_exchange_rate based on provided value. Use in query `filter[use_site_exchange_rate]=true`. ## List Subscription Components For Site Filter ### Properties - currencies (`array`): Allows fetching components allocation with matching currency based on provided values. Use in query `filter[currencies]=USD,EUR`. - use_site_exchange_rate (`Boolean`): Allows fetching components allocation with matching use_site_exchange_rate based on provided value. Use in query `filter[use_site_exchange_rate]=true`. - subscription (`Subscription Filter`): Nested filter used for List Subscription Components For Site Filter ## List Subscription Components Include ### Properties - subscription - historic_usages ## List Subscription Components Response ### Properties - subscriptions_components (`array`) ## List Subscription Components Sort ### Properties - id - updated_at ## List Subscription Group Prepayment ### Properties - prepayment (`List Subcription Group Prepayment Item`) ## List Subscription Group Prepayment Response ### Properties - prepayments (`array`) ## List Subscription Groups Item ### Properties - uid (`String`) - scheme (`Number`) - customer_id (`Number`) - payment_profile_id (`Number`) - subscription_ids (`array`) - primary_subscription_id (`Number`) - next_assessment_at (`DateTime`) - state (`String`) - cancel_at_end_of_period (`Boolean`) - account_balances (`Subscription Group Balances`) - group_type (`Group Type`) ## List Subscription Groups Meta ### Properties - current_page (`Number`) - total_count (`Number`) ## List Subscription Groups Response ### Properties - subscription_groups (`array`) - meta (`List Subscription Groups Meta`) ## Metadata ### Properties - id (`Number`) - value (`String`) - resource_id (`Number`) - name (`String`) - deleted_at (`DateTime`) - metafield_id (`Number`) ## Metafield ### Properties - id (`Number`) - name (`String`) - scope (`Metafield Scope`): Warning: When updating a metafield's scope attribute, all scope attributes must be passed. Partially complete scope attributes will override the existing settings. - data_count (`Number`): The amount of subscriptions this metafield has been applied to in Advanced Billing. - input_type (`Metafield Input`): Indicates the type of metafield. A text metafield allows any string value. Dropdown and radio metafields have a set of values that can be selected. Defaults to 'text'. - enum (`String | array`) ## Metafield Input Indicates the type of metafield. A text metafield allows any string value. Dropdown and radio metafields have a set of values that can be selected. Defaults to 'text'. ### Properties - balance_tracker - text - radio - dropdown ## Metafield Scope Warning: When updating a metafield's scope attribute, all scope attributes must be passed. Partially complete scope attributes will override the existing settings. ### Properties - csv (`Include Option`): Include (1) or exclude (0) metafields from the csv export. - invoices (`Include Option`): Include (1) or exclude (0) metafields from invoices. - statements (`Include Option`): Include (1) or exclude (0) metafields from statements. - portal (`Include Option`): Include (1) or exclude (0) metafields from the portal. - public_show (`Include Option`): Include (1) or exclude (0) metafields used in [Embeddable Components](page:development-tools/embeddable-components/overview) from being viewable by your ecosystem. - public_edit (`Include Option`): Include (1) or exclude (0) metafields used in [Embeddable Components](page:development-tools/embeddable-components/overview) from being editable by your ecosystem. - hosted (`array`) ## Metered Component ### Properties - name (`String`): A name for this component that is suitable for showing customers and displaying on billing statements, ie. "Minutes". - unit_name (`String`): The name of the unit of measurement for the component. It should be singular since it will be automatically pluralized when necessary. i.e. “message”, which may then be shown as “5 messages” on a subscription’s component line-item - description (`String`): A description for the component that will be displayed to the user on the hosted signup page. - handle (`String`): A unique identifier for your use that can be used to retrieve this component is subsequent requests. Must start with a letter or number and may only contain lowercase letters, numbers, or the characters '.', ':', '-', or '_'. - taxable (`Boolean`): Boolean flag describing whether a component is taxable or not. - pricing_scheme (`Pricing Scheme`): The identifier for the pricing scheme. See [Product Components](https://help.chargify.com/products/product-components.html) for an overview of pricing schemes. - prices (`array`): (Not required for ‘per_unit’ pricing schemes) One or more price brackets. See [Price Bracket Rules](https://maxio.zendesk.com/hc/en-us/articles/24261149166733-Component-Pricing-Schemes#price-bracket-rules) for an overview of how price brackets work for different pricing schemes. - price_points (`array`) - unit_price (`String | Decimal`): The amount the customer will be charged per unit when the pricing scheme is “per_unit”. For On/Off Components, this is the amount that the customer will be charged when they turn the component on for the subscription. The price can contain up to 8 decimal places. i.e. 1.00 or 0.0012 or 0.00000065 - tax_code (`String`): A string representing the tax code related to the component type. This is especially important when using AvaTax to tax based on locale. This attribute has a max length of 25 characters. - hide_date_range_on_invoice (`Boolean`): (Only available on Relationship Invoicing sites) Boolean flag describing if the service date range should show for the component on generated invoices. - display_on_hosted_page (`Boolean`) - allow_fractional_quantities (`Boolean`) - public_signup_page_ids (`array`) - interval (`Number`): The numerical interval. i.e. an interval of ‘30’ coupled with an interval_unit of day would mean this component's default price point would renew every 30 days. This property is only available for sites with Multifrequency enabled. - interval_unit (`Interval Unit`): A string representing the interval unit for this component's default price point, either month or day. This property is only available for sites with Multifrequency enabled. ## Metered Usage ### Properties - previous_unit_balance (`String`) - new_unit_balance (`Number`) - usage_quantity (`Number`) - component_id (`Number`) - component_handle (`String`) - memo (`String`) ## Movement ### Properties - timestamp (`DateTime`) - amount_in_cents (`Long`) - amount_formatted (`String`) - description (`String`) - category (`String`) - breakouts (`Breakouts`) - line_items (`array`) - subscription_id (`Number`) - subscriber_name (`String`) ## Movement Line Item ### Properties - product_id (`Number`) - component_id (`Number`): For Product (or "baseline") line items, this field will have a value of `0`. - price_point_id (`Number`) - name (`String`) - mrr (`Number`) - mrr_movements (`array`) - quantity (`Number`) - prev_quantity (`Number`) - recurring (`Boolean`): When `true`, the line item's MRR value will contribute to the `plan` breakout. When `false`, the line item contributes to the `usage` breakout. ## MRR ### Properties - amount_in_cents (`Long`) - amount_formatted (`String`) - currency (`String`) - currency_symbol (`String`) - breakouts (`Breakouts`) - at_time (`DateTime`): ISO8601 timestamp ## MRR Movement ### Properties - amount (`Number`) - category (`String`) - subscriber_delta (`Number`) - lead_delta (`Number`) ## MRR response ### Properties - mrr (`MRR`) ## Multi Invoice Payment ### Properties - transaction_id (`Number`): The numeric ID of the transaction. - total_amount (`String`): Dollar amount of the sum of the paid invoices. - currency_code (`String`): The ISO 4217 currency code (3 character string) representing the currency of invoice transaction. - applications (`array`) ## Multi Invoice Payment Response ### Properties - payment (`Multi Invoice Payment`) ## Nested Subscription Group ### Properties - uid (`String`): The UID for the group - scheme (`Number`): Whether the group is configured to rely on a primary subscription for billing. At this time, it will always be 1. - primary_subscription_id (`Number`): The subscription ID of the primary within the group. Applicable to scheme 1. - primary (`Boolean`): A boolean indicating whether the subscription is the primary in the group. Applicable to scheme 1. ## Net Terms ### Properties - default_net_terms (`Number`) - automatic_net_terms (`Number`) - remittance_net_terms (`Number`) - net_terms_on_remittance_signups_enabled (`Boolean`) - custom_net_terms_enabled (`Boolean`) ## Offer ### Properties - id (`Number`) - site_id (`Number`) - product_family_id (`Number`) - product_id (`Number`) - product_price_point_id (`Number`) - product_revisable_number (`Number`) - name (`String`) - handle (`String`) - description (`String`) - created_at (`DateTime`) - updated_at (`DateTime`) - archived_at (`DateTime`) - offer_items (`array`) - offer_discounts (`array`) - product_family_name (`String`) - product_name (`String`) - product_price_point_name (`String`) - product_price_in_cents (`Long`) - offer_signup_pages (`array`) ## Offer Discount ### Properties - coupon_code (`String`) - coupon_id (`Number`) - coupon_name (`String`) ## Offer Item ### Properties - component_id (`Number`) - price_point_id (`Number`) - starting_quantity (`String`) - editable (`Boolean`) - component_unit_price (`String`) - component_name (`String`) - price_point_name (`String`) - currency_prices (`array`) - interval (`Number`): The numerical interval. i.e. 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`): 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. ## Offer Response ### Properties - offer (`Offer`) ## Offer Signup Page ### Properties - id (`Number`) - nickname (`String`) - enabled (`Boolean`) - return_url (`String`) - return_params (`String`) - url (`String`) ## Ok Response ### Properties - ok (`String`) ## On/Off Component ### Properties - name (`String`): A name for this component that is suitable for showing customers and displaying on billing statements, ie. "Minutes". - description (`String`): A description for the component that will be displayed to the user on the hosted signup page. - handle (`String`): A unique identifier for your use that can be used to retrieve this component is subsequent requests. Must start with a letter or number and may only contain lowercase letters, numbers, or the characters '.', ':', '-', or '_'. - taxable (`Boolean`): Boolean flag describing whether a component is taxable or not. - upgrade_charge (`Credit Type`): The type of credit to be created when upgrading/downgrading. Defaults to the component and then site setting if one is not provided. Available values: `full`, `prorated`, `none`. - downgrade_credit (`Credit Type`): The type of credit to be created when upgrading/downgrading. Defaults to the component and then site setting if one is not provided. Available values: `full`, `prorated`, `none`. - price_points (`array`) - unit_price (`String | Decimal`): This is the amount that the customer will be charged when they turn the component on for the subscription. The price can contain up to 8 decimal places. i.e. 1.00 or 0.0012 or 0.00000065 - tax_code (`String`): A string representing the tax code related to the component type. This is especially important when using AvaTax to tax based on locale. This attribute has a max length of 25 characters. - hide_date_range_on_invoice (`Boolean`): (Only available on Relationship Invoicing sites) Boolean flag describing if the service date range should show for the component on generated invoices. - display_on_hosted_page (`Boolean`) - allow_fractional_quantities (`Boolean`) - public_signup_page_ids (`array`) - interval (`Number`): The numerical interval. i.e. an interval of ‘30’ coupled with an interval_unit of day would mean this component's default price point would renew every 30 days. This property is only available for sites with Multifrequency enabled. - interval_unit (`Interval Unit`): A string representing the interval unit for this component's default price point, either month or day. This property is only available for sites with Multifrequency enabled. ## Organization Address ### Properties - street (`String`) - line2 (`String`) - city (`String`) - state (`String`) - zip (`String`) - country (`String`) - name (`String`) - phone (`String`) ## Origin Invoice ### Properties - uid (`String`): The UID of the invoice serving as an origin invoice. - number (`String`): The number of the invoice serving as an origin invoice. ## Overage Pricing ### Properties - pricing_scheme (`Pricing Scheme`): The identifier for the pricing scheme. See [Product Components](https://help.chargify.com/products/product-components.html) for an overview of pricing schemes. - prices (`array`) ## Override Subscription ### Properties - activated_at (`DateTime`): Can be used to record an external signup date. Chargify uses this field to record when a subscription first goes active (either at signup or at trial end). Only ISO8601 format is supported. - canceled_at (`DateTime`): Can be used to record an external cancellation date. Chargify sets this field automatically when a subscription is canceled, whether by request or via dunning. Only ISO8601 format is supported. - cancellation_message (`String`): Can be used to record a reason for the original cancellation. - expires_at (`DateTime`): Can be used to record an external expiration date. Chargify sets this field automatically when a subscription expires (ceases billing) after a prescribed amount of time. Only ISO8601 format is supported. This field is not supported when Multi-frequency is enabled for the Site. To change the Term End of a Subscription, use the Update Subscription endpoint. - current_period_starts_at (`DateTime`): Can only be used when a subscription is unbilled, which happens when a future initial billing date is passed at subscription creation. The value passed must be before the current date and time. Allows you to set when the period started so mid period component allocations have the correct proration. Only ISO8601 format is supported. ## Override Subscription Request ### Properties - subscription (`Override Subscription`) ## Paginated Metadata ### Properties - total_count (`Number`) - current_page (`Number`) - total_pages (`Number`) - per_page (`Number`) - metadata (`array`) ## Paid Invoice ### Properties - invoice_id (`String`): The uid of the paid invoice - status (`Invoice Status`): The current status of the invoice. See [Invoice Statuses](https://maxio.zendesk.com/hc/en-us/articles/24252287829645-Advanced-Billing-Invoices-Overview#invoice-statuses) for more. - due_amount (`String`): The remaining due amount on the invoice - paid_amount (`String`): The total amount paid on this invoice (including any prior payments) ## Pause Request Allows to pause a Subscription ### Properties - hold (`Auto Resume`) ## Payer Attributes ### Properties - first_name (`String`) - last_name (`String`) - email (`String`) - cc_emails (`String`) - organization (`String`) - reference (`String`) - address (`String`) - address_2 (`String`) - city (`String`) - state (`String`) - zip (`String`) - country (`String`) - phone (`String`) - locale (`String`) - vat_number (`String`) - tax_exempt (`Boolean`) - tax_exempt_reason (`String`) - metafields (`map`): (Optional) A set of key/value pairs representing custom fields and their values. Metafields will be created “on-the-fly” in your site for a given key, if they have not been created yet. ## Payer Error ### Properties - last_name (`array`) - first_name (`array`) - email (`array`) ## Payment Collection Method Changed ### Properties - previous_value (`String`) - current_value (`String`) ## Payment for Allocation Information for captured payment, if applicable ### Properties - id (`Number`) - amount_in_cents (`Long`) - success (`Boolean`) - memo (`String`) ## Payment Profile Attributes alias to credit_card_attributes ### Properties - chargify_token (`String`): (Optional) Token received after sending billing information using chargify.js. This token must be passed as a sole attribute of `payment_profile_attributes` (i.e. tok_9g6hw85pnpt6knmskpwp4ttt) - id (`Number`) - payment_type (`Payment Type`) - first_name (`String`): (Optional) First name on card or bank account. If omitted, the first_name from customer attributes will be used. - last_name (`String`): (Optional) Last name on card or bank account. If omitted, the last_name from customer attributes will be used. - masked_card_number (`String`) - full_number (`String`): The full credit card number (string representation, i.e. 5424000000000015) - card_type (`Card Type`): (Optional, used only for Subscription Import) If you know the card type (i.e. Visa, MC, etc) you may supply it here so that we may display the card type in the UI. - expiration_month (`Number | String`): (Optional when performing a Subscription Import via vault_token, required otherwise) The 1- or 2-digit credit card expiration month, as an integer or string, i.e. 5 - expiration_year (`Number | String`): (Optional when performing a Subscription Import via vault_token, required otherwise) The 4-digit credit card expiration year, as an integer or string, i.e. 2012 - billing_address (`String`): (Optional, may be required by your product configuration or gateway settings) The credit card or bank account billing street address (i.e. 123 Main St.). This value is merely passed through to the payment gateway. - billing_address_2 (`String`): (Optional) Second line of the customer’s billing address i.e. Apt. 100 - billing_city (`String`): (Optional, may be required by your product configuration or gateway settings) The credit card or bank account billing address city (i.e. “Boston”). This value is merely passed through to the payment gateway. - billing_state (`String`): (Optional, may be required by your product configuration or gateway settings) The credit card or bank account billing address state (i.e. MA). This value is merely passed through to the payment gateway. This must conform to the [ISO_3166-1](https://en.wikipedia.org/wiki/ISO_3166-1#Current_codes) in order to be valid for tax locale purposes. - billing_country (`String`): (Optional, may be required by your product configuration or gateway settings) The credit card or bank account billing address country, required in [ISO_3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format (i.e. “US”). This value is merely passed through to the payment gateway. Some gateways require country codes in a specific format. Check your gateway’s documentation. If creating an ACH subscription, only US is supported at this time. - billing_zip (`String`): (Optional, may be required by your product configuration or gateway settings) The credit card or bank account billing address zip code (i.e. 12345). This value is merely passed through to the payment gateway. - current_vault (`All Vaults`): (Optional, used only for Subscription Import) The vault that stores the payment profile with the provided vault_token. - vault_token (`String`): (Optional, used only for Subscription Import) The “token” provided by your vault storage for an already stored payment profile - customer_vault_token (`String`): (Optional, used only for Subscription Import) (only for Authorize.Net CIM storage or Square) The customerProfileId for the owner of the customerPaymentProfileId provided as the vault_token - customer_id (`Number`) - paypal_email (`String`) - payment_method_nonce (`String`): (Required for Square unless importing with vault_token and customer_vault_token) The nonce generated by the Square Javascript library (SqPaymentForm) - gateway_handle (`String`): (Optional) This attribute is only available if MultiGateway feature is enabled for your Site. This feature is in the Private Beta currently. gateway_handle is used to directly select a gateway where a payment profile will be stored in. Every connected gateway must have a unique gateway handle specified. Read [Multigateway description](https://chargify.zendesk.com/hc/en-us/articles/4407761759643#connecting-with-multiple-gateways) to learn more about new concepts that MultiGateway introduces and the default behavior when this attribute is not passed. - cvv (`String`): (Optional, may be required by your gateway settings) The 3- or 4-digit Card Verification Value. This value is merely passed through to the payment gateway. - last_four (`String`): (Optional, used only for Subscription Import) If you have the last 4 digits of the credit card number, you may supply them here so that we may create a masked card number (i.e. XXXX-XXXX-XXXX-1234) for display in the UI. Last 4 digits are required for refunds in Auth.Net. ## Payment Profile Response ### Properties - payment_profile (`Apple Pay Payment Profile | Bank Account Payment Profile | Credit Card Payment Profile | Paypal Payment Profile`) ## Payment Related Events ### Properties - product_id (`Number`) - account_transaction_id (`Number`) ## Payment Type ### Properties - credit_card - bank_account - paypal_account - apple_pay ## PayPal Vault The vault that stores the payment profile with the provided vault_token. ### Properties - braintree_blue - paypal - moduslink - paypal_complete ## Pending Cancellation Change ### Properties - cancellation_state (`String`) - cancels_at (`DateTime`) ## Portal Management Link ### Properties - url (`String`) - fetch_count (`Number`) - created_at (`DateTime`) - new_link_available_at (`DateTime`) - expires_at (`DateTime`) - last_invite_sent_at (`DateTime`) ## Prepaid Configuration ### Properties - id (`Number`) - initial_funding_amount_in_cents (`Long`) - replenish_to_amount_in_cents (`Long`) - auto_replenish (`Boolean`) - replenish_threshold_amount_in_cents (`Long`) ## Prepaid Configuration Response ### Properties - prepaid_configuration (`Prepaid Configuration`) ## Prepaid Product Price Point Filter ### Properties - product_price_point_id (`String`): Passed as a parameter to list methods to return only non null values. ## Prepaid Subscription Balance Changed ### Properties - reason (`String`) - current_account_balance_in_cents (`Long`) - prepayment_account_balance_in_cents (`Long`) - current_usage_amount_in_cents (`Long`) ## Prepaid Usage ### Properties - previous_unit_balance (`String`) - previous_overage_unit_balance (`String`) - new_unit_balance (`Number`) - new_overage_unit_balance (`Number`) - usage_quantity (`Number`) - overage_usage_quantity (`Number`) - component_id (`Number`) - component_handle (`String`) - memo (`String`) - allocation_details (`array`) ## Prepaid Usage Allocation Detail ### Properties - allocation_id (`Number`) - charge_id (`Number`) - usage_quantity (`Number`) ## Prepaid Usage Component ### Properties - name (`String`): A name for this component that is suitable for showing customers and displaying on billing statements, ie. "Minutes". - unit_name (`String`): The name of the unit of measurement for the component. It should be singular since it will be automatically pluralized when necessary. i.e. “message”, which may then be shown as “5 messages” on a subscription’s component line-item - description (`String`): A description for the component that will be displayed to the user on the hosted signup page. - handle (`String`): A unique identifier for your use that can be used to retrieve this component is subsequent requests. Must start with a letter or number and may only contain lowercase letters, numbers, or the characters '.', ':', '-', or '_'. - taxable (`Boolean`): Boolean flag describing whether a component is taxable or not. - pricing_scheme (`Pricing Scheme`): The identifier for the pricing scheme. See [Product Components](https://help.chargify.com/products/product-components.html) for an overview of pricing schemes. - prices (`array`): (Not required for ‘per_unit’ pricing schemes) One or more price brackets. See [Price Bracket Rules](https://maxio.zendesk.com/hc/en-us/articles/24261149166733-Component-Pricing-Schemes#price-bracket-rules) for an overview of how price brackets work for different pricing schemes. - upgrade_charge (`Credit Type`): The type of credit to be created when upgrading/downgrading. Defaults to the component and then site setting if one is not provided. Available values: `full`, `prorated`, `none`. - downgrade_credit (`Credit Type`): The type of credit to be created when upgrading/downgrading. Defaults to the component and then site setting if one is not provided. Available values: `full`, `prorated`, `none`. - price_points (`array`) - unit_price (`String | Decimal`): The amount the customer will be charged per unit when the pricing scheme is “per_unit”. For On/Off Components, this is the amount that the customer will be charged when they turn the component on for the subscription. The price can contain up to 8 decimal places. i.e. 1.00 or 0.0012 or 0.00000065 - tax_code (`String`): A string representing the tax code related to the component type. This is especially important when using AvaTax to tax based on locale. This attribute has a max length of 25 characters. - hide_date_range_on_invoice (`Boolean`): (Only available on Relationship Invoicing sites) Boolean flag describing if the service date range should show for the component on generated invoices. - overage_pricing (`Overage Pricing`) - rollover_prepaid_remainder (`Boolean`): Boolean which controls whether or not remaining units should be rolled over to the next period - renew_prepaid_allocation (`Boolean`): Boolean which controls whether or not the allocated quantity should be renewed at the beginning of each period - expiration_interval (`Decimal`): (only for prepaid usage components where rollover_prepaid_remainder is true) The number of `expiration_interval_unit`s after which rollover amounts should expire - expiration_interval_unit (`Expiration Interval Unit`) - display_on_hosted_page (`Boolean`) - allow_fractional_quantities (`Boolean`) - public_signup_page_ids (`array`) ## Prepayment ### Properties - id (`Number`) - subscription_id (`Number`) - amount_in_cents (`Long`) - remaining_amount_in_cents (`Long`) - refunded_amount_in_cents (`Long`) - details (`String`) - external (`Boolean`) - memo (`String`) - payment_type (`Prepayment Method`): The payment type of the prepayment. - created_at (`DateTime`) ## Prepayment Account Balance Changed ### Properties - reason (`String`) - prepayment_account_balance_in_cents (`Long`) - prepayment_balance_change_in_cents (`Long`) - currency_code (`String`) ## Prepayment Aggregated Error ### Properties - amount_in_cents (`array`) - base (`array`) - external (`array`) ## Prepayment Method ### Properties - check - cash - money_order - ach - paypal_account - credit_card - other ## Prepayment Response ### Properties - prepayment (`Prepayment`) ## Prepayments Response ### Properties - prepayments (`array`) ## Preview Allocations Request ### Properties - allocations (`array`) - effective_proration_date (`Date`): To calculate proration amounts for a future time. Only within a current subscription period. Only ISO8601 format is supported. - upgrade_charge (`Credit Type`): The type of credit to be created when upgrading/downgrading. Defaults to the component and then site setting if one is not provided. Available values: `full`, `prorated`, `none`. - downgrade_credit (`Credit Type`): The type of credit to be created when upgrading/downgrading. Defaults to the component and then site setting if one is not provided. Available values: `full`, `prorated`, `none`. ## Price ### Properties - starting_quantity (`Number | String`) - ending_quantity (`Number | String`) - unit_price (`Decimal | String`): The price can contain up to 8 decimal places. i.e. 1.00 or 0.0012 or 0.00000065 ## Price Point Type Price point type. We expose the following types: 1. **default**: a price point that is marked as a default price for a certain product. 2. **custom**: a custom price point. 3. **catalog**: a price point that is **not** marked as a default price for a certain product and is **not** a custom one. ### Properties - catalog - default - custom ## Pricing Scheme The identifier for the pricing scheme. See [Product Components](https://help.chargify.com/products/product-components.html) for an overview of pricing schemes. ### Properties - stairstep - volume - per_unit - tiered ## Product ### Properties - id (`Number`) - name (`String`): The product name - handle (`String`): The product API handle - description (`String`): The product description - accounting_code (`String`): E.g. Internal ID or SKU Number - request_credit_card (`Boolean`): Deprecated value that can be ignored unless you have legacy hosted pages. For Public Signup Page users, read this attribute from under the signup page. - expiration_interval (`Number`): A numerical interval for the length a subscription to this product will run before it expires. See the description of interval for a description of how this value is coupled with an interval unit to calculate the full interval - expiration_interval_unit (`Expiration Interval Unit`): A string representing the expiration interval unit for this product, either month, day or never - created_at (`DateTime`): Timestamp indicating when this product was created - updated_at (`DateTime`): Timestamp indicating when this product was last updated - price_in_cents (`Long`): The product price, in integer cents - interval (`Number`): The numerical interval. i.e. an interval of ‘30’ coupled with an interval_unit of day would mean this product would renew every 30 days - interval_unit (`Interval Unit`): A string representing the interval unit for this product, either month or day - initial_charge_in_cents (`Long`): The up front charge you have specified. - trial_price_in_cents (`Long`): The price of the trial period for a subscription to this product, in integer cents. - trial_interval (`Number`): A numerical interval for the length of the trial period of a subscription to this product. See the description of interval for a description of how this value is coupled with an interval unit to calculate the full interval - trial_interval_unit (`Interval Unit`): A string representing the trial interval unit for this product, either month or day - archived_at (`DateTime`): Timestamp indicating when this product was archived - require_credit_card (`Boolean`): Boolean that controls whether a payment profile is required to be entered for customers wishing to sign up on this product. - return_params (`String`) - taxable (`Boolean`) - update_return_url (`String`): The url to which a customer will be returned after a successful account update - initial_charge_after_trial (`Boolean`) - version_number (`Number`): The version of the product - update_return_params (`String`): The parameters will append to the url after a successful account update. See [help documentation](https://help.chargify.com/products/product-editing.html#return-parameters-after-account-update) - product_family (`Product Family`) - public_signup_pages (`array`) - product_price_point_name (`String`) - request_billing_address (`Boolean`): A boolean indicating whether to request a billing address on any Self-Service Pages that are used by subscribers of this product. - require_billing_address (`Boolean`): A boolean indicating whether a billing address is required to add a payment profile, especially at signup. - require_shipping_address (`Boolean`): A boolean indicating whether a shipping address is required for the customer, especially at signup. - tax_code (`String`): A string representing the tax code related to the product type. This is especially important when using AvaTax to tax based on locale. This attribute has a max length of 25 characters. - default_product_price_point_id (`Number`) - use_site_exchange_rate (`Boolean`) - item_category (`String`): One of the following: Business Software, Consumer Software, Digital Services, Physical Goods, Other - product_price_point_id (`Number`) - product_price_point_handle (`String`) ## Product Family ### Properties - id (`Number`) - name (`String`) - handle (`String`) - accounting_code (`String`) - description (`String`) - created_at (`DateTime`) - updated_at (`DateTime`) ## Product Family Response ### Properties - product_family (`Product Family`) ## Product Price Point ### Properties - id (`Number`) - name (`String`): The product price point name - handle (`String`): The product price point API handle - price_in_cents (`Long`): The product price point price, in integer cents - interval (`Number`): The numerical interval. i.e. an interval of ‘30’ coupled with an interval_unit of day would mean this product price point would renew every 30 days - interval_unit (`Interval Unit`): A string representing the interval unit for this product price point, either month or day - trial_price_in_cents (`Long`): The product price point trial price, in integer cents - trial_interval (`Number`): The numerical trial interval. i.e. an interval of ‘30’ coupled with a trial_interval_unit of day would mean this product price point trial would last 30 days - trial_interval_unit (`Interval Unit`): A string representing the trial interval unit for this product price point, either month or day - trial_type (`Trial Type`): Indicates how a trial is handled when the trail period ends and there is no credit card on file. For `no_obligation`, the subscription transitions to a Trial Ended state. Maxio will not send any emails or statements. For `payment_expected`, the subscription transitions to a Past Due state. Maxio will send normal dunning emails and statements according to your other settings. - introductory_offer (`Boolean`): reserved for future use - initial_charge_in_cents (`Long`): The product price point initial charge, in integer cents - initial_charge_after_trial (`Boolean`) - expiration_interval (`Number`): The numerical expiration interval. i.e. an expiration_interval of ‘30’ coupled with an expiration_interval_unit of day would mean this product price point would expire after 30 days - expiration_interval_unit (`Expiration Interval Unit`): A string representing the expiration interval unit for this product price point, either month, day or never - product_id (`Number`): The product id this price point belongs to - archived_at (`DateTime`): Timestamp indicating when this price point was archived - created_at (`DateTime`): Timestamp indicating when this price point was created - updated_at (`DateTime`): Timestamp indicating when this price point was last updated - use_site_exchange_rate (`Boolean`): Whether or not to use the site's exchange rate or define your own pricing when your site has multiple currencies defined. - type (`Price Point Type`): The type of price point - tax_included (`Boolean`): Whether or not the price point includes tax - subscription_id (`Number`): The subscription id this price point belongs to - currency_prices (`array`): An array of currency pricing data is available when multiple currencies are defined for the site. It varies based on the use_site_exchange_rate setting for the price point. This parameter is present only in the response of read endpoints, after including the appropriate query parameter. ## Product Price Point Error Response ### Properties - errors (`Product Price Point Errors`) ## Product Price Point Error Response1 ### Properties - errors (`Product Price Point Errors`) ## Product Price Point Errors ### Properties - price_point (`String`) - interval (`array`) - interval_unit (`array`) - name (`array`) - price (`array`) - price_in_cents (`array`) ## Product Price Point Response ### Properties - price_point (`Product Price Point`) ## Product Response ### Properties - product (`Product`) ## Proforma Bad Request Error Response ### Properties - errors (`Proforma Error`) ## Proforma Bad Request Error Response1 ### Properties - errors (`Proforma Error`) ## Proforma Error ### Properties - subscription (`Base String Error`): The error is base if it is not directly associated with a single attribute. ## Proforma Invoice ### Properties - uid (`String`) - site_id (`Number`) - customer_id (`Number`) - subscription_id (`Number`) - number (`Number`) - sequence_number (`Number`) - created_at (`DateTime`) - delivery_date (`Date`) - status (`Proforma Invoice Status`) - collection_method (`Collection Method`): The type of payment collection to be used in the subscription. For legacy Statements Architecture valid options are - `invoice`, `automatic`. For current Relationship Invoicing Architecture valid options are - `remittance`, `automatic`, `prepaid`. - payment_instructions (`String`) - currency (`String`) - consolidation_level (`Invoice Consolidation Level`): Consolidation level of the invoice, which is applicable to invoice consolidation. It will hold one of the following values: * "none": A normal invoice with no consolidation. * "child": An invoice segment which has been combined into a consolidated invoice. * "parent": A consolidated invoice, whose contents are composed of invoice segments. "Parent" invoices do not have lines of their own, but they have subtotals and totals which aggregate the member invoice segments. See also the [invoice consolidation documentation](https://maxio.zendesk.com/hc/en-us/articles/24252269909389-Invoice-Consolidation). - product_name (`String`) - product_family_name (`String`) - role (`Proforma Invoice Role`): 'proforma' value is deprecated in favor of proforma_adhoc and proforma_automatic - seller (`Invoice Seller`): Information about the seller (merchant) listed on the masthead of the invoice. - customer (`Invoice Customer`): Information about the customer who is owner or recipient the invoiced subscription. - memo (`String`) - billing_address (`Invoice Address`) - shipping_address (`Invoice Address`) - subtotal_amount (`String`) - discount_amount (`String`) - tax_amount (`String`) - total_amount (`String`) - credit_amount (`String`) - paid_amount (`String`) - refund_amount (`String`) - due_amount (`String`) - line_items (`array`) - discounts (`array`) - taxes (`array`) - credits (`array`) - payments (`array`) - custom_fields (`array`) - public_url (`String`) ## Proforma Invoice Credit ### Properties - uid (`String`) - memo (`String`) - original_amount (`String`) - applied_amount (`String`) ## Proforma Invoice Discount ### Properties - uid (`String`) - title (`String`) - code (`String`) - source_type (`Proforma Invoice Discount Source Type`) - discount_type (`Invoice Discount Type`) - eligible_amount (`String`) - discount_amount (`String`) - line_item_breakouts (`array`) ## Proforma Invoice Discount Source Type ### Properties - Coupon - Referral ## Proforma Invoice Issued ### Properties - uid (`String`) - number (`String`) - role (`String`) - delivery_date (`Date`) - created_at (`DateTime`) - due_amount (`String`) - paid_amount (`String`) - tax_amount (`String`) - total_amount (`String`) - product_name (`String`) - line_items (`array`) ## Proforma Invoice Payment ### Properties - memo (`String`) - original_amount (`String`) - applied_amount (`String`) - prepayment (`Boolean`) ## Proforma Invoice Role 'proforma' value is deprecated in favor of proforma_adhoc and proforma_automatic ### Properties - unset - proforma - proforma_adhoc - proforma_automatic ## Proforma Invoice Status ### Properties - draft - voided - archived ## Proforma Invoice Tax ### Properties - uid (`String`) - title (`String`) - source_type (`Proforma Invoice Tax Source Type`) - percentage (`String`) - taxable_amount (`String`) - tax_amount (`String`) - line_item_breakouts (`array`) ## Proforma Invoice Tax Source Type ### Properties - Tax - Avalara ## Proration ### Properties - preserve_period (`Boolean`): The alternative to sending preserve_period as a direct attribute to migration ## Public Key ### Properties - public_key (`String`) - requires_security_token (`Boolean`) - created_at (`DateTime`) ## Public Signup Page ### Properties - id (`Number`): The id of the signup page (public_signup_pages only) - return_url (`String`): The url to which a customer will be returned after a successful signup (public_signup_pages only) - return_params (`String`): The params to be appended to the return_url (public_signup_pages only) - url (`String`): The url where the signup page can be viewed (public_signup_pages only) ## Quantity Based Component ### Properties - name (`String`): A name for this component that is suitable for showing customers and displaying on billing statements, ie. "Minutes". - unit_name (`String`): The name of the unit of measurement for the component. It should be singular since it will be automatically pluralized when necessary. i.e. “message”, which may then be shown as “5 messages” on a subscription’s component line-item - description (`String`): A description for the component that will be displayed to the user on the hosted signup page. - handle (`String`): A unique identifier for your use that can be used to retrieve this component is subsequent requests. Must start with a letter or number and may only contain lowercase letters, numbers, or the characters '.', ':', '-', or '_'. - taxable (`Boolean`): Boolean flag describing whether a component is taxable or not. - pricing_scheme (`Pricing Scheme`): The identifier for the pricing scheme. See [Product Components](https://help.chargify.com/products/product-components.html) for an overview of pricing schemes. - prices (`array`): (Not required for ‘per_unit’ pricing schemes) One or more price brackets. See [Price Bracket Rules](https://maxio.zendesk.com/hc/en-us/articles/24261149166733-Component-Pricing-Schemes#price-bracket-rules) for an overview of how price brackets work for different pricing schemes. - upgrade_charge (`Credit Type`): The type of credit to be created when upgrading/downgrading. Defaults to the component and then site setting if one is not provided. Available values: `full`, `prorated`, `none`. - downgrade_credit (`Credit Type`): The type of credit to be created when upgrading/downgrading. Defaults to the component and then site setting if one is not provided. Available values: `full`, `prorated`, `none`. - price_points (`array`) - unit_price (`String | Decimal`): The amount the customer will be charged per unit when the pricing scheme is “per_unit”. For On/Off Components, this is the amount that the customer will be charged when they turn the component on for the subscription. The price can contain up to 8 decimal places. i.e. 1.00 or 0.0012 or 0.00000065 - tax_code (`String`): A string representing the tax code related to the component type. This is especially important when using AvaTax to tax based on locale. This attribute has a max length of 25 characters. - hide_date_range_on_invoice (`Boolean`): (Only available on Relationship Invoicing sites) Boolean flag describing if the service date range should show for the component on generated invoices. - recurring (`Boolean`) - display_on_hosted_page (`Boolean`) - allow_fractional_quantities (`Boolean`) - public_signup_page_ids (`array`) - interval (`Number`): The numerical interval. i.e. an interval of ‘30’ coupled with an interval_unit of day would mean this component's default price point would renew every 30 days. This property is only available for sites with Multifrequency enabled. - interval_unit (`Interval Unit`): A string representing the interval unit for this component's default price point, either month or day. This property is only available for sites with Multifrequency enabled. ## Reactivate Subscription Group Request ### Properties - resume (`Boolean`) - resume_members (`Boolean`) ## Reactivate Subscription Group Response ### Properties - uid (`String`) - scheme (`Number`) - customer_id (`Number`) - payment_profile_id (`Number`) - subscription_ids (`array`) - primary_subscription_id (`Number`) - next_assessment_at (`DateTime`) - state (`String`) - cancel_at_end_of_period (`Boolean`) ## Reactivate Subscription Request ### Properties - calendar_billing (`Reactivation Billing`): These values are only applicable to subscriptions using calendar billing - include_trial (`Boolean`): If `true` is sent, the reactivated Subscription will include a trial if one is available. If `false` is sent, the trial period will be ignored. - preserve_balance (`Boolean`): If `true` is passed, the existing subscription balance will NOT be cleared/reset before adding the additional reactivation charges. - coupon_code (`String`): The coupon code to be applied during reactivation. - use_credits_and_prepayments (`Boolean`): If true is sent, Chargify will use service credits and prepayments upon reactivation. If false is sent, the service credits and prepayments will be ignored. - resume (`Boolean | Resume Options`): If `true`, Chargify will attempt to resume the subscription's billing period. if not resumable, the subscription will be reactivated with a new billing period. If `false`: Chargify will only attempt to reactivate the subscription. ## Reactivation Billing These values are only applicable to subscriptions using calendar billing ### Properties - reactivation_charge (`Reactivation Charge`): You may choose how to handle the reactivation charge for that subscription: 1) `prorated` A prorated charge for the product price will be attempted for to complete the period 2) `immediate` A full-price charge for the product price will be attempted immediately 3) `delayed` A full-price charge for the product price will be attempted at the next renewal ## Reactivation Charge You may choose how to handle the reactivation charge for that subscription: 1) `prorated` A prorated charge for the product price will be attempted for to complete the period 2) `immediate` A full-price charge for the product price will be attempted immediately 3) `delayed` A full-price charge for the product price will be attempted at the next renewal ### Properties - prorated - immediate - delayed ## Reason Code ### Properties - id (`Number`) - site_id (`Number`) - code (`String`) - description (`String`) - position (`Number`) - created_at (`DateTime`) - updated_at (`DateTime`) ## Reason Code Response ### Properties - reason_code (`Reason Code`) ## Record Payment Request ### Properties - payment (`Create Payment`) ## Record Payment Response ### Properties - paid_invoices (`array`) - prepayment (`Invoice Pre Payment`) ## Recurring Scheme ### Properties - do_not_recur - recur_indefinitely - recur_with_duration ## Referral Code ### Properties - id (`Number`) - site_id (`Number`) - subscription_id (`Number`) - code (`String`) ## Referral Validation Response ### Properties - referral_code (`Referral Code`) ## Refund Consolidated Invoice Refund consolidated invoice ### Properties - memo (`String`): A description for the refund - payment_id (`Number`): The ID of the payment to be refunded - segment_uids (`array | String`): An array of segment uids to refund or the string 'all' to indicate that all segments should be refunded - external (`Boolean`): Flag that marks refund as external (no money is returned to the customer). Defaults to `false`. - apply_credit (`Boolean`): If set to true, creates credit and applies it to an invoice. Defaults to `false`. - amount (`String`): The amount of payment to be refunded in decimal format. Example: "10.50". This will default to the full amount of the payment if not provided. ## Refund Invoice Refund an invoice or a segment of a consolidated invoice. ### Properties - amount (`String`): The amount to be refunded in decimal format as a string. Example: "10.50". Must not exceed the remaining refundable balance of the payment. - memo (`String`): A description that will be attached to the refund - payment_id (`Number`): The ID of the payment to be refunded - external (`Boolean`): Flag that marks refund as external (no money is returned to the customer). Defaults to `false`. - apply_credit (`Boolean`): If set to true, creates credit and applies it to an invoice. Defaults to `false`. - void_invoice (`Boolean`): If `apply_credit` set to false and refunding full amount, if `void_invoice` set to true, invoice will be voided after refund. Defaults to `false`. ## Refund Invoice Event Data Example schema for an `refund_invoice` event ### Properties - apply_credit (`Boolean`): If true, credit was created and applied it to the invoice. - consolidation_level (`Invoice Consolidation Level`): Consolidation level of the invoice, which is applicable to invoice consolidation. It will hold one of the following values: * "none": A normal invoice with no consolidation. * "child": An invoice segment which has been combined into a consolidated invoice. * "parent": A consolidated invoice, whose contents are composed of invoice segments. "Parent" invoices do not have lines of their own, but they have subtotals and totals which aggregate the member invoice segments. See also the [invoice consolidation documentation](https://maxio.zendesk.com/hc/en-us/articles/24252269909389-Invoice-Consolidation). - credit_note_attributes (`Credit Note`) - memo (`String`): The refund memo. - original_amount (`String`): The full, original amount of the refund. - payment_id (`Number`): The ID of the payment transaction to be refunded. - refund_amount (`String`): The amount of the refund. - refund_id (`Number`): The ID of the refund transaction. - transaction_time (`DateTime`): The time the refund was applied, in ISO 8601 format, i.e. "2019-06-07T17:20:06Z" ## Refund Invoice Request ### Properties - refund (`Refund Invoice | Refund Consolidated Invoice`) ## Refund Prepayment ### Properties - amount_in_cents (`Long`): `amount` is not required if you pass `amount_in_cents`. - amount (`String | Decimal`): `amount_in_cents` is not required if you pass `amount`. - memo (`String`) - external (`Boolean`): Specify the type of refund you wish to initiate. When the prepayment is external, the `external` flag is optional. But if the prepayment was made through a payment profile, the `external` flag is required. ## Refund Prepayment Aggregated Error ### Properties - refund (`Prepayment Aggregated Error`) ## Refund Prepayment Aggregated Errors Response Errors returned on creating a refund prepayment, grouped by field, as arrays of strings. ### Properties - errors (`Refund Prepayment Aggregated Error`) ## Refund Prepayment Base Errors Response Errors returned on creating a refund prepayment when bad request ### Properties - errors (`Refund Prepayment Base Refund Error`) ## Refund Prepayment Base Errors Response1 Errors returned on creating a refund prepayment when bad request ### Properties - errors (`Refund Prepayment Base Refund Error`) ## Refund Prepayment Base Refund Error ### Properties - refund (`Base Refund Error`) ## Refund Prepayment Request ### Properties - refund (`Refund Prepayment`) ## Refund Success ### Properties - refund_id (`Number`) - gateway_transaction_id (`Number`) - product_id (`Number`) ## Remove Payment Event Data Example schema for an `remove_payment` event ### Properties - transaction_id (`Number`): Transaction ID of the original payment that was removed - memo (`String`): Memo of the original payment - original_amount (`String`): Full amount of the original payment - applied_amount (`String`): Applied amount of the original payment - transaction_time (`DateTime`): Transaction time of the original payment, 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`): A nested data structure detailing the method of payment - prepayment (`Boolean`): The flag that shows whether the original payment was a prepayment or not ## Renewal Preview ### Properties - next_assessment_at (`DateTime`): The timestamp for the subscription’s next renewal - subtotal_in_cents (`Long`): An integer representing the amount of the total pre-tax, pre-discount charges that will be assessed at the next renewal - total_tax_in_cents (`Long`): An integer representing the total tax charges that will be assessed at the next renewal - total_discount_in_cents (`Long`): An integer representing the amount of the coupon discounts that will be applied to the next renewal - total_in_cents (`Long`): An integer representing the total amount owed, less any discounts, that will be assessed at the next renewal - existing_balance_in_cents (`Long`): An integer representing the amount of the subscription’s current balance - total_amount_due_in_cents (`Long`): An integer representing the existing_balance_in_cents plus the total_in_cents - uncalculated_taxes (`Boolean`): A boolean indicating whether or not additional taxes will be calculated at the time of renewal. This will be true if you are using Avalara and the address of the subscription is in one of your defined taxable regions. - line_items (`array`): An array of objects representing the individual transactions that will be created at the next renewal ## Renewal Preview Component ### Properties - component_id (`String | Number`): Either the component's Chargify id or its handle prefixed with `handle:` - quantity (`Number`): The quantity for which you wish to preview billing. This is useful if you want to preview a predicted, higher usage value than is currently present on the subscription. This quantity represents: - Whether or not an on/off component is enabled - use 0 for disabled or 1 for enabled - The desired allocated_quantity for a quantity-based component - The desired unit_balance for a metered component - The desired metric quantity for an events-based component - price_point_id (`String | Number`): Either the component price point's Chargify id or its handle prefixed with `handle:` ## Renewal Preview Line Item ### Properties - transaction_type (`Line Item Transaction Type`): A handle for the line item transaction type - kind (`Line Item Kind`): A handle for the line item kind - amount_in_cents (`Long`) - memo (`String`) - discount_amount_in_cents (`Long`) - taxable_amount_in_cents (`Long`) - product_id (`Number`) - product_name (`String`) - component_id (`Number`) - component_handle (`String`) - component_name (`String`) - product_handle (`String`) - period_range_start (`String`) - period_range_end (`String`) ## Renewal Preview Request ### Properties - components (`array`): An optional array of component definitions to preview. Providing any component definitions here will override the actual components on the subscription (and their quantities), and the billing preview will contain only these components (in addition to any product base fees). ## Renewal Preview Response ### Properties - renewal_preview (`Renewal Preview`) ## Replay Webhooks Request ### Properties - ids (`array`) ## Replay Webhooks Response ### Properties - status (`String`) ## Resent Invitation ### Properties - last_sent_at (`String`) - last_accepted_at (`String`) - send_invite_link_text (`String`) - uninvited_count (`Number`) - last_invite_sent_at (`DateTime`) - last_invite_accepted_at (`DateTime`) ## Resource Type ### Properties - subscriptions - customers ## Restriction Type ### Properties - Component - Product ## Resume Options ### Properties - require_resume (`Boolean`): Chargify will only attempt to resume the subscription's billing period. If not resumable, the subscription will be left in its current state. - forgive_balance (`Boolean`): Indicates whether or not Chargify should clear the subscription's existing balance before attempting to resume the subscription. If subscription cannot be resumed, the balance will remain as it was before the attempt to resume was made. ## Resumption Charge (For calendar billing subscriptions only) The way that the resumed subscription's charge should be handled ### Properties - prorated - immediate - delayed ## Revoked Invitation ### Properties - last_sent_at (`String`) - last_accepted_at (`String`) - uninvited_count (`Number`) ## Sale Rep ### Properties - id (`Number`) - full_name (`String`) - subscriptions_count (`Number`) - test_mode (`Boolean`) - subscriptions (`array`) ## Sale Rep Item Mrr ### Properties - mrr (`String`) - usage (`String`) - recurring (`String`) ## Sale Rep Settings ### Properties - customer_name (`String`) - subscription_id (`Number`) - site_link (`String`) - site_name (`String`) - subscription_mrr (`String`) - sales_rep_id (`Number`) - sales_rep_name (`String`) ## Sale Rep Subscription ### Properties - id (`Number`) - site_name (`String`) - subscription_url (`String`) - customer_name (`String`) - created_at (`String`) - mrr (`String`) - usage (`String`) - recurring (`String`) - last_payment (`String`) - churn_date (`String`) ## Segment ### Properties - id (`Number`) - component_id (`Number`) - price_point_id (`Number`) - event_based_billing_metric_id (`Number`) - pricing_scheme (`Pricing Scheme`): The identifier for the pricing scheme. See [Product Components](https://help.chargify.com/products/product-components.html) for an overview of pricing schemes. - segment_property_1_value (`String | Decimal | Number | Boolean`) - segment_property_2_value (`String | Decimal | Number | Boolean`) - segment_property_3_value (`String | Decimal | Number | Boolean`) - segment_property_4_value (`String | Decimal | Number | Boolean`) - created_at (`DateTime`) - updated_at (`DateTime`) - prices (`array`) ## Segment Price ### Properties - id (`Number`) - component_id (`Number`) - starting_quantity (`Number`) - ending_quantity (`Number`) - unit_price (`String`) - price_point_id (`Number`) - formatted_unit_price (`String`) - segment_id (`Number`) ## Segment Response ### Properties - segment (`Segment`) ## Send Invoice Request ### Properties - recipient_emails (`array`) - cc_recipient_emails (`array`) - bcc_recipient_emails (`array`) ## Service Credit ### Properties - id (`Number`) - amount_in_cents (`Long`): The amount in cents of the entry - ending_balance_in_cents (`Long`): The new balance for the credit account - entry_type (`Service Credit Type`): The type of entry - memo (`String`): The memo attached to the entry ## Service Credit Response ### Properties - service_credit (`Service Credit`) ## Service Credit Type The type of entry ### Properties - Credit - Debit ## Service Credit1 ### Properties - id (`Number`) - amount_in_cents (`Long`): The amount in cents of the entry - ending_balance_in_cents (`Long`): The new balance for the credit account - entry_type (`Service Credit Type`): The type of entry - memo (`String`): The memo attached to the entry - invoice_uid (`String`): The invoice uid associated with the entry. Only present for debit entries - remaining_balance_in_cents (`Long`): The remaining balance for the entry - created_at (`DateTime`): The date and time the entry was created ## Signup Proforma Preview ### Properties - current_proforma_invoice (`Proforma Invoice`) - next_proforma_invoice (`Proforma Invoice`) ## Signup Proforma Preview Response ### Properties - proforma_invoice_preview (`Signup Proforma Preview`) ## Single Error Response ### Properties - error (`String`) ## Single Error Response1 ### Properties - error (`String`) ## Single String Error Response ### Properties - errors (`String`) ## Single String Error Response1 ### Properties - errors (`String`) ## Site ### Properties - id (`Number`) - name (`String`) - subdomain (`String`) - currency (`String`) - seller_id (`Number`) - non_primary_currencies (`array`) - relationship_invoicing_enabled (`Boolean`) - schedule_subscription_cancellation_enabled (`Boolean`) - customer_hierarchy_enabled (`Boolean`) - whopays_enabled (`Boolean`) - whopays_default_payer (`String`) - allocation_settings (`Allocation Settings`) - default_payment_collection_method (`String`) - organization_address (`Organization Address`) - tax_configuration (`Tax Configuration`) - net_terms (`Net Terms`) - test (`Boolean`) ## Site Response ### Properties - site (`Site`) ## Site Statistics ### Properties - total_subscriptions (`Number`) - subscriptions_today (`Number`) - total_revenue (`String`) - revenue_today (`String`) - revenue_this_month (`String`) - revenue_this_year (`String`) - total_canceled_subscriptions (`Number`) - total_active_subscriptions (`Number`) - total_past_due_subscriptions (`Number`) - total_unpaid_subscriptions (`Number`) - total_dunning_subscriptions (`Number`) ## Site Summary ### Properties - seller_name (`String`) - site_name (`String`) - site_id (`Number`) - site_currency (`String`) - stats (`Site Statistics`) ## SnapDay ### Properties - end ## Sorting direction Used for sorting results. ### Properties - asc - desc ## Subscription ### Properties - id (`Number`): The subscription unique id within Chargify. - state (`Subscription State`): The state of a subscription. * **Live States** * `active` - A normal, active subscription. It is not in a trial and is paid and up to date. * `assessing` - An internal (transient) state that indicates a subscription is in the middle of periodic assessment. Do not base any access decisions in your app on this state, as it may not always be exposed. * `pending` - An internal (transient) state that indicates a subscription is in the creation process. Do not base any access decisions in your app on this state, as it may not always be exposed. * `trialing` - A subscription in trialing state has a valid trial subscription. This type of subscription may transition to active once payment is received when the trial has ended. Otherwise, it may go to a Problem or End of Life state. * `paused` - An internal state that indicates that your account with Advanced Billing is in arrears. * **Problem States** * `past_due` - Indicates that the most recent payment has failed, and payment is past due for this subscription. If you have enabled our automated dunning, this subscription will be in the dunning process (additional status and callbacks from the dunning process will be available in the future). If you are handling dunning and payment updates yourself, you will want to use this state to initiate a payment update from your customers. * `soft_failure` - Indicates that normal assessment/processing of the subscription has failed for a reason that cannot be fixed by the Customer. For example, a Soft Fail may result from a timeout at the gateway or incorrect credentials on your part. The subscriptions should be retried automatically. An interface is being built for you to review problems resulting from these events to take manual action when needed. * `unpaid` - Indicates an unpaid subscription. A subscription is marked unpaid if the retry period expires and you have configured your [Dunning](https://maxio.zendesk.com/hc/en-us/articles/24287076583565-Dunning-Overview) settings to have a Final Action of `mark the subscription unpaid`. * **End of Life States** * `canceled` - Indicates a canceled subscription. This may happen at your request (via the API or the web interface) or due to the expiration of the [Dunning](https://maxio.zendesk.com/hc/en-us/articles/24287076583565-Dunning-Overview) process without payment. See the [Reactivation](https://maxio.zendesk.com/hc/en-us/articles/24252109503629-Reactivating-and-Resuming) documentation for info on how to restart a canceled subscription. While a subscription is canceled, its period will not advance, it will not accrue any new charges, and Advanced Billing will not attempt to collect the overdue balance. * `expired` - Indicates a subscription that has expired due to running its normal life cycle. Some products may be configured to have an expiration period. An expired subscription then is one that stayed active until it fulfilled its full period. * `failed_to_create` - Indicates that signup has failed. (You may see this state in a signup_failure webhook.) * `on_hold` - Indicates that a subscription’s billing has been temporarily stopped. While it is expected that the subscription will resume and return to active status, this is still treated as an “End of Life” state because the customer is not paying for services during this time. * `suspended` - Indicates that a prepaid subscription has used up all their prepayment balance. If a prepayment is applied, it will return to an active state. * `trial_ended` - A subscription in a trial_ended state is a subscription that completed a no-obligation trial and did not have a card on file at the expiration of the trial period. See [Product Pricing – No Obligation Trials](https://maxio.zendesk.com/hc/en-us/articles/24261076617869-Product-Editing) for more details. See [Subscription States](https://maxio.zendesk.com/hc/en-us/articles/24252119027853-Subscription-States) for more info about subscription states and state transitions. - balance_in_cents (`Long`): Gives the current outstanding subscription balance in the number of cents. - total_revenue_in_cents (`Long`): Gives the total revenue from the subscription in the number of cents. - product_price_in_cents (`Long`): (Added Nov 5 2013) The recurring amount of the product (and version),currently subscribed. NOTE: this may differ from the current price of,the product, if you’ve changed the price of the product but haven’t,moved this subscription to a newer version. - product_version_number (`Number`): The version of the product for the subscription. Note that this is a deprecated field kept for backwards-compatibility. - current_period_ends_at (`DateTime`): Timestamp relating to the end of the current (recurring) period (i.e.,when the next regularly scheduled attempted charge will occur) - next_assessment_at (`DateTime`): Timestamp that indicates when capture of payment will be tried or,retried. This value will usually track the current_period_ends_at, but,will diverge if a renewal payment fails and must be retried. In that,case, the current_period_ends_at will advance to the end of the next,period (time doesn’t stop because a payment was missed) but the,next_assessment_at will be scheduled for the auto-retry time (i.e. 24,hours in the future, in some cases) - trial_started_at (`DateTime`): Timestamp for when the trial period (if any) began - trial_ended_at (`DateTime`): Timestamp for when the trial period (if any) ended - activated_at (`DateTime`): Timestamp for when the subscription began (i.e. when it came out of trial, or when it began in the case of no trial) - expires_at (`DateTime`): Timestamp giving the expiration date of this subscription (if any) - created_at (`DateTime`): The creation date for this subscription - updated_at (`DateTime`): The date of last update for this subscription - cancellation_message (`String`): Seller-provided reason for, or note about, the cancellation. - cancellation_method (`Cancellation Method`): The process used to cancel the subscription, if the subscription has been canceled. It is nil if the subscription's state is not canceled. - cancel_at_end_of_period (`Boolean`): Whether or not the subscription will (or has) canceled at the end of the period. - canceled_at (`DateTime`): The timestamp of the most recent cancellation - current_period_started_at (`DateTime`): Timestamp relating to the start of the current (recurring) period - previous_state (`Subscription State`): Only valid for webhook payloads The previous state for webhooks that have indicated a change in state. For normal API calls, this will always be the same as the state (current state) - signup_payment_id (`Number`): The ID of the transaction that generated the revenue - signup_revenue (`String`): The revenue, formatted as a string of decimal separated dollars and,cents, from the subscription signup ($50.00 would be formatted as,50.00) - delayed_cancel_at (`DateTime`): Timestamp for when the subscription is currently set to cancel. - coupon_code (`String`): (deprecated) The coupon code of the single coupon currently applied to the subscription. See coupon_codes instead as subscriptions can now have more than one coupon. - snap_day (`Number | Snap Day`): The day of the month that the subscription will charge according to calendar billing rules, if used. - payment_collection_method (`Collection Method`): The type of payment collection to be used in the subscription. For legacy Statements Architecture valid options are - `invoice`, `automatic`. For current Relationship Invoicing Architecture valid options are - `remittance`, `automatic`, `prepaid`. - customer (`Customer`) - product (`Product`) - credit_card (`Credit Card Payment Profile`) - group (`Nested Subscription Group`) - bank_account (`Bank Account Payment Profile`) - payment_type (`String`): The payment profile type for the active profile on file. - referral_code (`String`): The subscription's unique code that can be given to referrals. - next_product_id (`Number`): If a delayed product change is scheduled, the ID of the product that the subscription will be changed to at the next renewal. - next_product_handle (`String`): If a delayed product change is scheduled, the handle of the product that the subscription will be changed to at the next renewal. - coupon_use_count (`Number`): (deprecated) How many times the subscription's single coupon has been used. This field has no replacement for multiple coupons. - coupon_uses_allowed (`Number`): (deprecated) How many times the subscription's single coupon may be used. This field has no replacement for multiple coupons. - reason_code (`String`): If the subscription is canceled, this is their churn code. - automatically_resume_at (`DateTime`): The date the subscription is scheduled to automatically resume from the on_hold state. - coupon_codes (`array`): An array for all the coupons attached to the subscription. - offer_id (`Number`): The ID of the offer associated with the subscription. - payer_id (`Number`): On Relationship Invoicing, the ID of the individual paying for the subscription. Defaults to the Customer ID unless the 'Customer Hierarchies & WhoPays' feature is enabled. - current_billing_amount_in_cents (`Long`): The balance in cents plus the estimated renewal amount in cents. Returned ONLY for the readSubscription operation as it's a compute intensive operation. - product_price_point_id (`Number`): The product price point currently subscribed to. - product_price_point_type (`Price Point Type`): Price point type. We expose the following types: 1. **default**: a price point that is marked as a default price for a certain product. 2. **custom**: a custom price point. 3. **catalog**: a price point that is **not** marked as a default price for a certain product and is **not** a custom one. - next_product_price_point_id (`Number`): If a delayed product change is scheduled, the ID of the product price point that the subscription will be changed to at the next renewal. - net_terms (`Number`): On Relationship Invoicing, the number of days before a renewal invoice is due. - stored_credential_transaction_id (`Number`): For European sites subject to PSD2 and using 3D Secure, this can be used to reference a previous transaction for the customer. This will ensure the card will be charged successfully at renewal. - reference (`String`): The reference value (provided by your app) for the subscription itelf. - on_hold_at (`DateTime`): The timestamp of the most recent on hold action. - prepaid_dunning (`Boolean`): Boolean representing whether the subscription is prepaid and currently in dunning. Only returned for Relationship Invoicing sites with the feature enabled - coupons (`array`): Additional coupon data. To use this data you also have to include the following param in the request`include[]=coupons`. Only in Read Subscription Endpoint. - dunning_communication_delay_enabled (`Boolean`): Enable Communication Delay feature, making sure no communication (email or SMS) is sent to the Customer between 9PM and 8AM in time zone set by the `dunning_communication_delay_time_zone` attribute. - dunning_communication_delay_time_zone (`String`): Time zone for the Dunning Communication Delay feature. - receives_invoice_emails (`Boolean`) - locale (`String`) - currency (`String`) - scheduled_cancellation_at (`DateTime`) - credit_balance_in_cents (`Long`) - prepayment_balance_in_cents (`Long`) - prepaid_configuration (`Prepaid Configuration`) - self_service_page_token (`String`): Returned only for list/read Subscription operation when `include[]=self_service_page_token` parameter is provided. ## Subscription Add Coupon Error ### Properties - codes (`array`) - coupon_code (`array`) - coupon_codes (`array`) - subscription (`array`) ## Subscription Add Coupon Error1 ### Properties - codes (`array`) - coupon_code (`array`) - coupon_codes (`array`) - subscription (`array`) ## Subscription Component ### Properties - id (`Number`) - name (`String`) - kind (`Component Kind`): A handle for the component type - unit_name (`String`) - enabled (`Boolean`): (for on/off components) indicates if the component is enabled for the subscription - unit_balance (`Number`) - currency (`String`) - allocated_quantity (`Number | String`): For Quantity-based components: The current allocation for the component on the given subscription. For On/Off components: Use 1 for on. Use 0 for off. - pricing_scheme (`Pricing Scheme`) - component_id (`Number`) - component_handle (`String`) - subscription_id (`Number`) - recurring (`Boolean`) - upgrade_charge (`Credit Type`): The type of credit to be created when upgrading/downgrading. Defaults to the component and then site setting if one is not provided. Available values: `full`, `prorated`, `none`. - downgrade_credit (`Credit Type`): The type of credit to be created when upgrading/downgrading. Defaults to the component and then site setting if one is not provided. Available values: `full`, `prorated`, `none`. - archived_at (`DateTime`) - price_point_id (`Number`) - price_point_handle (`String`) - price_point_type (`Price Point Type`) - price_point_name (`String`) - product_family_id (`Number`) - product_family_handle (`String`) - created_at (`DateTime`) - updated_at (`DateTime`) - use_site_exchange_rate (`Boolean`) - description (`String`) - allow_fractional_quantities (`Boolean`) - subscription (`Subscription Component Subscription`): An optional object, will be returned if provided `include=subscription` query param. - historic_usages (`array`) - display_on_hosted_page (`Boolean`) - interval (`Number`): The numerical interval. i.e. 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`): 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. ## Subscription Component Allocation Error ### Properties - errors (`array`) ## Subscription Component Allocation Error Item ### Properties - kind (`String`) - message (`String`) ## Subscription Component Allocation Error1 ### Properties - errors (`array`) ## Subscription Component Response ### Properties - component (`Subscription Component`) ## Subscription Component Subscription An optional object, will be returned if provided `include=subscription` query param. ### Properties - state (`Subscription State`): The state of a subscription. * **Live States** * `active` - A normal, active subscription. It is not in a trial and is paid and up to date. * `assessing` - An internal (transient) state that indicates a subscription is in the middle of periodic assessment. Do not base any access decisions in your app on this state, as it may not always be exposed. * `pending` - An internal (transient) state that indicates a subscription is in the creation process. Do not base any access decisions in your app on this state, as it may not always be exposed. * `trialing` - A subscription in trialing state has a valid trial subscription. This type of subscription may transition to active once payment is received when the trial has ended. Otherwise, it may go to a Problem or End of Life state. * `paused` - An internal state that indicates that your account with Advanced Billing is in arrears. * **Problem States** * `past_due` - Indicates that the most recent payment has failed, and payment is past due for this subscription. If you have enabled our automated dunning, this subscription will be in the dunning process (additional status and callbacks from the dunning process will be available in the future). If you are handling dunning and payment updates yourself, you will want to use this state to initiate a payment update from your customers. * `soft_failure` - Indicates that normal assessment/processing of the subscription has failed for a reason that cannot be fixed by the Customer. For example, a Soft Fail may result from a timeout at the gateway or incorrect credentials on your part. The subscriptions should be retried automatically. An interface is being built for you to review problems resulting from these events to take manual action when needed. * `unpaid` - Indicates an unpaid subscription. A subscription is marked unpaid if the retry period expires and you have configured your [Dunning](https://maxio.zendesk.com/hc/en-us/articles/24287076583565-Dunning-Overview) settings to have a Final Action of `mark the subscription unpaid`. * **End of Life States** * `canceled` - Indicates a canceled subscription. This may happen at your request (via the API or the web interface) or due to the expiration of the [Dunning](https://maxio.zendesk.com/hc/en-us/articles/24287076583565-Dunning-Overview) process without payment. See the [Reactivation](https://maxio.zendesk.com/hc/en-us/articles/24252109503629-Reactivating-and-Resuming) documentation for info on how to restart a canceled subscription. While a subscription is canceled, its period will not advance, it will not accrue any new charges, and Advanced Billing will not attempt to collect the overdue balance. * `expired` - Indicates a subscription that has expired due to running its normal life cycle. Some products may be configured to have an expiration period. An expired subscription then is one that stayed active until it fulfilled its full period. * `failed_to_create` - Indicates that signup has failed. (You may see this state in a signup_failure webhook.) * `on_hold` - Indicates that a subscription’s billing has been temporarily stopped. While it is expected that the subscription will resume and return to active status, this is still treated as an “End of Life” state because the customer is not paying for services during this time. * `suspended` - Indicates that a prepaid subscription has used up all their prepayment balance. If a prepayment is applied, it will return to an active state. * `trial_ended` - A subscription in a trial_ended state is a subscription that completed a no-obligation trial and did not have a card on file at the expiration of the trial period. See [Product Pricing – No Obligation Trials](https://maxio.zendesk.com/hc/en-us/articles/24261076617869-Product-Editing) for more details. See [Subscription States](https://maxio.zendesk.com/hc/en-us/articles/24252119027853-Subscription-States) for more info about subscription states and state transitions. - updated_at (`DateTime`) ## Subscription Custom Price (Optional) Used in place of `product_price_point_id` to define a custom price point unique to the subscription ### Properties - name (`String`): (Optional) - handle (`String`): (Optional) - price_in_cents (`String | Long`): Required if using `custom_price` attribute. - interval (`String | Number`): Required if using `custom_price` attribute. - interval_unit (`Interval Unit`): Required if using `custom_price` attribute. - trial_price_in_cents (`String | Long`): (Optional) - trial_interval (`String | Number`): (Optional) - trial_interval_unit (`Interval Unit`): (Optional) - trial_type (`Trial Type`): Indicates how a trial is handled when the trail period ends and there is no credit card on file. For `no_obligation`, the subscription transitions to a Trial Ended state. Maxio will not send any emails or statements. For `payment_expected`, the subscription transitions to a Past Due state. Maxio will send normal dunning emails and statements according to your other settings. - initial_charge_in_cents (`String | Long`): (Optional) - initial_charge_after_trial (`Boolean`): (Optional) - expiration_interval (`String | Number`): (Optional) - expiration_interval_unit (`Expiration Interval Unit`): (Optional) - tax_included (`Boolean`): (Optional) ## Subscription Date Field ### Properties - current_period_ends_at - current_period_starts_at - created_at - activated_at - canceled_at - expires_at - trial_started_at - trial_ended_at - updated_at ## Subscription Filter Nested filter used for List Subscription Components For Site Filter ### Properties - states (`array`): Allows fetching components allocations that belong to the subscription with matching states based on provided values. To use this filter you also have to include the following param in the request `include=subscription`. Use in query `filter[subscription][states]=active,canceled&include=subscription`. - date_field (`Subscription List Date Field`): The type of filter you'd like to apply to your search. To use this filter you also have to include the following param in the request `include=subscription`. - start_date (`Date`): The start date (format YYYY-MM-DD) with which to filter the date_field. Returns components that belong to the subscription with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified. To use this filter you also have to include the following param in the request `include=subscription`. - end_date (`Date`): The end date (format YYYY-MM-DD) with which to filter the date_field. Returns components that belong to the subscription with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified. To use this filter you also have to include the following param in the request `include=subscription`. - start_datetime (`DateTime`): The start date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns components that belong to the subscription 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. To use this filter you also have to include the following param in the request `include=subscription`. - end_datetime (`DateTime`): The end date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns components that belong to the subscription 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. To use this filter you also have to include the following param in the request `include=subscription`. ## Subscription Group ### Properties - customer_id (`Number`) - payment_profile (`Subscription Group Payment Profile`) - payment_collection_method (`Collection Method`): The type of payment collection to be used in the subscription. For legacy Statements Architecture valid options are - `invoice`, `automatic`. For current Relationship Invoicing Architecture valid options are - `remittance`, `automatic`, `prepaid`. - subscription_ids (`array`) - created_at (`DateTime`) ## Subscription Group Balances ### Properties - prepayments (`Account Balance`) - service_credits (`Account Balance`) - open_invoices (`Account Balance`) - pending_discounts (`Account Balance`) ## Subscription Group Bank Account ### Properties - bank_name (`String`): (Required when creating a subscription with ACH or GoCardless) The name of the bank where the customer’s account resides - bank_account_number (`String`): (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_routing_number (`String`): (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_iban (`String`): (Optional when creating a subscription with GoCardless). International Bank Account Number. Alternatively, local bank details can be provided - bank_branch_code (`String`): (Optional when creating a subscription with GoCardless) Branch code. Alternatively, an IBAN can be provided - bank_account_type (`Bank Account Type`): Defaults to checking - bank_account_holder_type (`Bank Account Holder Type`): Defaults to personal - payment_type (`Payment Type`) - billing_address (`String`) - billing_city (`String`) - billing_state (`String`) - billing_zip (`String`) - billing_country (`String`) - chargify_token (`String`) - current_vault (`Bank Account Vault`): The vault that stores the payment profile with the provided vault_token. Use `bogus` for testing. - gateway_handle (`String`) ## Subscription Group Component Custom Price Used in place of `price_point_id` to define a custom price point unique to the subscription. You still need to provide `component_id`. ### Properties - pricing_scheme (`Pricing Scheme`): The identifier for the pricing scheme. See [Product Components](https://help.chargify.com/products/product-components.html) for an overview of pricing schemes. - prices (`array`) - overage_pricing (`array`) ## Subscription Group Create Error Response ### Properties - errors (`Subscription Group Members Array Error | Subscription Group Single Error | String`) ## Subscription Group Create Error Response1 ### Properties - errors (`Subscription Group Members Array Error | Subscription Group Single Error | String`) ## Subscription Group Credit Card ### Properties - chargify_token (`String`) - vault_token (`String`) - current_vault (`Credit Card Vault`): The vault that stores the payment profile with the provided `vault_token`. Use `bogus` for testing. - gateway_handle (`String`) - first_name (`String`) - last_name (`String`) - billing_address (`String`) - billing_address_2 (`String`) - billing_city (`String`) - billing_state (`String`) - billing_zip (`String`) - billing_country (`String`) - full_number (`String | Number`) - expiration_month (`String | Number`) - expiration_year (`String | Number`) - last_four (`String`) - card_type (`Card Type`): The type of card used. - customer_vault_token (`String`) - cvv (`String`) - payment_type (`String`) ## Subscription Group Customer ### Properties - first_name (`String`) - last_name (`String`) - organization (`String`) - email (`String`) - reference (`String`) ## Subscription Group Include ### Properties - current_billing_amount_in_cents ## Subscription Group Item ### Properties - id (`Number`) - reference (`String`) - product_id (`Number`) - product_handle (`String`) - product_price_point_id (`Number`) - product_price_point_handle (`String`) - currency (`String`) - coupon_code (`String`) - total_revenue_in_cents (`Long`) - balance_in_cents (`Long`) ## Subscription Group Members Array Error ### Properties - members (`array`) ## Subscription Group Payment Profile ### Properties - id (`Number`) - first_name (`String`) - last_name (`String`) - masked_card_number (`String`) ## Subscription Group Prepayment ### Properties - amount (`Number`) - details (`String`) - memo (`String`) - method (`Subscription Group Prepayment Method`) ## Subscription Group Prepayment Method ### Properties - check - cash - money_order - ach - paypal_account - other ## Subscription Group Prepayment Request ### Properties - prepayment (`Subscription Group Prepayment`) ## Subscription Group Prepayment Response ### Properties - id (`Number`) - amount_in_cents (`Long`): The amount in cents of the entry. - ending_balance_in_cents (`Long`): The ending balance in cents of the account. - entry_type (`Service Credit Type`): The type of entry - memo (`String`): A memo attached to the entry. ## Subscription Group Response ### Properties - subscription_group (`Subscription Group`) ## Subscription Group Signup ### Properties - payment_profile_id (`Number`) - payer_id (`Number`) - payer_reference (`String`) - payment_collection_method (`Collection Method`): The type of payment collection to be used in the subscription. For legacy Statements Architecture valid options are - `invoice`, `automatic`. For current Relationship Invoicing Architecture valid options are - `remittance`, `automatic`, `prepaid`. - payer_attributes (`Payer Attributes`) - credit_card_attributes (`Subscription Group Credit Card`) - bank_account_attributes (`Subscription Group Bank Account`) - subscriptions (`array`) ## Subscription Group Signup Component ### Properties - component_id (`String | Number`): Required if passing any component to `components` attribute. - allocated_quantity (`String | Number`) - unit_balance (`String | Number`) - price_point_id (`String | Number`) - custom_price (`Subscription Group Component Custom Price`): Used in place of `price_point_id` to define a custom price point unique to the subscription. You still need to provide `component_id`. ## Subscription Group Signup Error ### Properties - subscriptions (`map`): Object that as key have subscription position in request subscriptions array and as value subscription errors object. - payer_reference (`String`) - payer (`Payer Error`) - subscription_group (`array`) - payment_profile_id (`String`) - payer_id (`String`) ## Subscription Group Signup Error Response ### Properties - errors (`Subscription Group Signup Error`) ## Subscription Group Signup Error Response1 ### Properties - errors (`Subscription Group Signup Error`) ## Subscription Group Signup Event Data ### Properties - subscription_group (`Subscription Group Signup Failure Data`) - customer (`Customer`) ## Subscription Group Signup Failure Data ### Properties - payer_id (`Number`) - payer_reference (`String`) - payment_profile_id (`Number`) - payment_collection_method (`String`) - payer_attributes (`Payer Attributes`) - credit_card_attributes (`Subscription Group Credit Card`) - bank_account_attributes (`Subscription Group Bank Account`) - subscriptions (`array`) ## Subscription Group Signup Item ### Properties - product_handle (`String`): The API Handle of the product for which you are creating a subscription. Required, unless a `product_id` is given instead. - product_id (`Number`): The Product ID of the product for which you are creating a subscription. You can pass either `product_id` or `product_handle`. - product_price_point_id (`Number`): The ID of the particular price point on the product. - product_price_point_handle (`String`): The user-friendly API handle of a product's particular price point. - offer_id (`Number`): Use in place of passing product and component information to set up the subscription with an existing offer. May be either the Chargify ID of the offer or its handle prefixed with `handle:` - reference (`String`): The reference value (provided by your app) for the subscription itelf. - primary (`Boolean`): One of the subscriptions must be marked as primary in the group. - currency (`String`): (Optional) If Multi-Currency is enabled and the currency is configured in Chargify, pass it at signup to create a subscription on a non-default currency. Note that you cannot update the currency of an existing subscription. - coupon_codes (`array`): An array for all the coupons attached to the subscription. - components (`array`) - custom_price (`Subscription Custom Price`): (Optional) Used in place of `product_price_point_id` to define a custom price point unique to the subscription - calendar_billing (`Calendar Billing`): (Optional). Cannot be used when also specifying next_billing_at - metafields (`map`): (Optional) A set of key/value pairs representing custom fields and their values. Metafields will be created “on-the-fly” in your site for a given key, if they have not been created yet. ## Subscription Group Signup Request ### Properties - subscription_group (`Subscription Group Signup`) ## Subscription Group Signup Response ### Properties - uid (`String`) - scheme (`Number`) - customer_id (`Number`) - payment_profile_id (`Number`) - subscription_ids (`array`) - primary_subscription_id (`Number`) - next_assessment_at (`DateTime`) - state (`Subscription State`): The state of a subscription. * **Live States** * `active` - A normal, active subscription. It is not in a trial and is paid and up to date. * `assessing` - An internal (transient) state that indicates a subscription is in the middle of periodic assessment. Do not base any access decisions in your app on this state, as it may not always be exposed. * `pending` - An internal (transient) state that indicates a subscription is in the creation process. Do not base any access decisions in your app on this state, as it may not always be exposed. * `trialing` - A subscription in trialing state has a valid trial subscription. This type of subscription may transition to active once payment is received when the trial has ended. Otherwise, it may go to a Problem or End of Life state. * `paused` - An internal state that indicates that your account with Advanced Billing is in arrears. * **Problem States** * `past_due` - Indicates that the most recent payment has failed, and payment is past due for this subscription. If you have enabled our automated dunning, this subscription will be in the dunning process (additional status and callbacks from the dunning process will be available in the future). If you are handling dunning and payment updates yourself, you will want to use this state to initiate a payment update from your customers. * `soft_failure` - Indicates that normal assessment/processing of the subscription has failed for a reason that cannot be fixed by the Customer. For example, a Soft Fail may result from a timeout at the gateway or incorrect credentials on your part. The subscriptions should be retried automatically. An interface is being built for you to review problems resulting from these events to take manual action when needed. * `unpaid` - Indicates an unpaid subscription. A subscription is marked unpaid if the retry period expires and you have configured your [Dunning](https://maxio.zendesk.com/hc/en-us/articles/24287076583565-Dunning-Overview) settings to have a Final Action of `mark the subscription unpaid`. * **End of Life States** * `canceled` - Indicates a canceled subscription. This may happen at your request (via the API or the web interface) or due to the expiration of the [Dunning](https://maxio.zendesk.com/hc/en-us/articles/24287076583565-Dunning-Overview) process without payment. See the [Reactivation](https://maxio.zendesk.com/hc/en-us/articles/24252109503629-Reactivating-and-Resuming) documentation for info on how to restart a canceled subscription. While a subscription is canceled, its period will not advance, it will not accrue any new charges, and Advanced Billing will not attempt to collect the overdue balance. * `expired` - Indicates a subscription that has expired due to running its normal life cycle. Some products may be configured to have an expiration period. An expired subscription then is one that stayed active until it fulfilled its full period. * `failed_to_create` - Indicates that signup has failed. (You may see this state in a signup_failure webhook.) * `on_hold` - Indicates that a subscription’s billing has been temporarily stopped. While it is expected that the subscription will resume and return to active status, this is still treated as an “End of Life” state because the customer is not paying for services during this time. * `suspended` - Indicates that a prepaid subscription has used up all their prepayment balance. If a prepayment is applied, it will return to an active state. * `trial_ended` - A subscription in a trial_ended state is a subscription that completed a no-obligation trial and did not have a card on file at the expiration of the trial period. See [Product Pricing – No Obligation Trials](https://maxio.zendesk.com/hc/en-us/articles/24261076617869-Product-Editing) for more details. See [Subscription States](https://maxio.zendesk.com/hc/en-us/articles/24252119027853-Subscription-States) for more info about subscription states and state transitions. - cancel_at_end_of_period (`Boolean`) - subscriptions (`array`) - payment_collection_method (`Collection Method`): The type of payment collection to be used in the subscription. For legacy Statements Architecture valid options are - `invoice`, `automatic`. For current Relationship Invoicing Architecture valid options are - `remittance`, `automatic`, `prepaid`. ## Subscription Group Single Error ### Properties - subscription_group (`String`) ## Subscription Group Subscription Error Object which contains subscription errors. ### Properties - product (`array`) - product_price_point_id (`array`) - payment_profile (`array`) - payment_profile.chargify_token (`array`) - base (`array`) - payment_profile.expiration_month (`array`) - payment_profile.expiration_year (`array`) - payment_profile.full_number (`array`) ## Subscription Group Update Error ### Properties - members (`array`) ## Subscription Group Update Error Response ### Properties - errors (`Subscription Group Update Error`) ## Subscription Group Update Error Response1 ### Properties - errors (`Subscription Group Update Error`) ## Subscription Groups List Include ### Properties - account_balances ## Subscription Include ### Properties - coupons - self_service_page_token ## Subscription Included Coupon ### Properties - code (`String`) - use_count (`Number`) - uses_allowed (`Number`) - expires_at (`String`) - recurring (`Boolean`) - amount_in_cents (`Long`) - percentage (`String`) ## Subscription List Date Field ### Properties - updated_at ## Subscription List Include ### Properties - self_service_page_token ## Subscription Migration Preview ### Properties - prorated_adjustment_in_cents (`Long`): The amount of the prorated adjustment that would be issued for the current subscription. - charge_in_cents (`Long`): The amount of the charge that would be created for the new product. - payment_due_in_cents (`Long`): The amount of the payment due in the case of an upgrade. - credit_applied_in_cents (`Long`): Represents a credit in cents that is applied to your subscription as part of a migration process for a specific product, which reduces the amount owed for the subscription. ## Subscription Migration Preview Options ### Properties - product_id (`Number`): The ID of the target Product. Either a product_id or product_handle must be present. A Subscription can be migrated to another product for both the current Product Family and another Product Family. Note: Going to another Product Family, components will not be migrated as well. - product_price_point_id (`Number`): The ID of the specified product's price point. This can be passed to migrate to a non-default price point. - include_trial (`Boolean`): Whether to include the trial period configured for the product price point when starting a new billing period. Note that if preserve_period is set, then include_trial will be ignored. - include_initial_charge (`Boolean`): If `true` is sent initial charges will be assessed. - include_coupons (`Boolean`): If `true` is sent, any coupons associated with the subscription will be applied to the migration. If `false` is sent, coupons will not be applied. Note: When migrating to a new product family, the coupon cannot migrate. - preserve_period (`Boolean`): If `false` is sent, the subscription's billing period will be reset to today and the full price of the new product will be charged. If `true` is sent, the billing period will not change and a prorated charge will be issued for the new product. - product_handle (`String`): The handle of the target Product. Either a product_id or product_handle must be present. A Subscription can be migrated to another product for both the current Product Family and another Product Family. Note: Going to another Product Family, components will not be migrated as well. - product_price_point_handle (`String`): The ID or handle of the specified product's price point. This can be passed to migrate to a non-default price point. - proration (`Proration`) - proration_date (`DateTime`): The date that the proration is calculated from for the preview ## Subscription Migration Preview Request ### Properties - migration (`Subscription Migration Preview Options`) ## Subscription Migration Preview Response ### Properties - migration (`Subscription Migration Preview`) ## Subscription MRR ### Properties - subscription_id (`Number`) - mrr_amount_in_cents (`Long`) - breakouts (`Subscription MRR Breakout`) ## Subscription MRR Breakout ### Properties - plan_amount_in_cents (`Long`) - usage_amount_in_cents (`Long`) ## Subscription MRR Response ### Properties - subscriptions_mrr (`array`) ## Subscription Note ### Properties - id (`Number`) - body (`String`) - subscription_id (`Number`) - created_at (`DateTime`) - updated_at (`DateTime`) - sticky (`Boolean`) ## Subscription Note Response ### Properties - note (`Subscription Note`) ## Subscription Preview ### Properties - current_billing_manifest (`Billing Manifest`) - next_billing_manifest (`Billing Manifest`) ## Subscription Preview Response ### Properties - subscription_preview (`Subscription Preview`) ## Subscription Product Change ### Properties - previous_product_id (`Number`) - new_product_id (`Number`) ## Subscription Product Migration ### Properties - product_id (`Number`): The ID of the target Product. Either a product_id or product_handle must be present. A Subscription can be migrated to another product for both the current Product Family and another Product Family. Note: Going to another Product Family, components will not be migrated as well. - product_price_point_id (`Number`): The ID of the specified product's price point. This can be passed to migrate to a non-default price point. - include_trial (`Boolean`): Whether to include the trial period configured for the product price point when starting a new billing period. Note that if preserve_period is set, then include_trial will be ignored. - include_initial_charge (`Boolean`): If `true` is sent initial charges will be assessed. - include_coupons (`Boolean`): If `true` is sent, any coupons associated with the subscription will be applied to the migration. If `false` is sent, coupons will not be applied. Note: When migrating to a new product family, the coupon cannot migrate. - preserve_period (`Boolean`): If `false` is sent, the subscription's billing period will be reset to today and the full price of the new product will be charged. If `true` is sent, the billing period will not change and a prorated charge will be issued for the new product. - product_handle (`String`): The handle of the target Product. Either a product_id or product_handle must be present. A Subscription can be migrated to another product for both the current Product Family and another Product Family. Note: Going to another Product Family, components will not be migrated as well. - product_price_point_handle (`String`): The ID or handle of the specified product's price point. This can be passed to migrate to a non-default price point. - proration (`Proration`) ## Subscription Product Migration Request ### Properties - migration (`Subscription Product Migration`) ## Subscription Purge Type ### Properties - customer - payment_profile ## Subscription Remove Coupon Errors ### Properties - subscription (`array`) ## Subscription Remove Coupon Errors1 ### Properties - subscription (`array`) ## Subscription Response ### Properties - subscription (`Subscription`) ## Subscription Response_Error ### Properties - subscription (`Subscription`) ## Subscription Sort ### Properties - signup_date - period_start - period_end - next_assessment - updated_at - created_at ## Subscription State The state of a subscription. * **Live States** * `active` - A normal, active subscription. It is not in a trial and is paid and up to date. * `assessing` - An internal (transient) state that indicates a subscription is in the middle of periodic assessment. Do not base any access decisions in your app on this state, as it may not always be exposed. * `pending` - An internal (transient) state that indicates a subscription is in the creation process. Do not base any access decisions in your app on this state, as it may not always be exposed. * `trialing` - A subscription in trialing state has a valid trial subscription. This type of subscription may transition to active once payment is received when the trial has ended. Otherwise, it may go to a Problem or End of Life state. * `paused` - An internal state that indicates that your account with Advanced Billing is in arrears. * **Problem States** * `past_due` - Indicates that the most recent payment has failed, and payment is past due for this subscription. If you have enabled our automated dunning, this subscription will be in the dunning process (additional status and callbacks from the dunning process will be available in the future). If you are handling dunning and payment updates yourself, you will want to use this state to initiate a payment update from your customers. * `soft_failure` - Indicates that normal assessment/processing of the subscription has failed for a reason that cannot be fixed by the Customer. For example, a Soft Fail may result from a timeout at the gateway or incorrect credentials on your part. The subscriptions should be retried automatically. An interface is being built for you to review problems resulting from these events to take manual action when needed. * `unpaid` - Indicates an unpaid subscription. A subscription is marked unpaid if the retry period expires and you have configured your [Dunning](https://maxio.zendesk.com/hc/en-us/articles/24287076583565-Dunning-Overview) settings to have a Final Action of `mark the subscription unpaid`. * **End of Life States** * `canceled` - Indicates a canceled subscription. This may happen at your request (via the API or the web interface) or due to the expiration of the [Dunning](https://maxio.zendesk.com/hc/en-us/articles/24287076583565-Dunning-Overview) process without payment. See the [Reactivation](https://maxio.zendesk.com/hc/en-us/articles/24252109503629-Reactivating-and-Resuming) documentation for info on how to restart a canceled subscription. While a subscription is canceled, its period will not advance, it will not accrue any new charges, and Advanced Billing will not attempt to collect the overdue balance. * `expired` - Indicates a subscription that has expired due to running its normal life cycle. Some products may be configured to have an expiration period. An expired subscription then is one that stayed active until it fulfilled its full period. * `failed_to_create` - Indicates that signup has failed. (You may see this state in a signup_failure webhook.) * `on_hold` - Indicates that a subscription’s billing has been temporarily stopped. While it is expected that the subscription will resume and return to active status, this is still treated as an “End of Life” state because the customer is not paying for services during this time. * `suspended` - Indicates that a prepaid subscription has used up all their prepayment balance. If a prepayment is applied, it will return to an active state. * `trial_ended` - A subscription in a trial_ended state is a subscription that completed a no-obligation trial and did not have a card on file at the expiration of the trial period. See [Product Pricing – No Obligation Trials](https://maxio.zendesk.com/hc/en-us/articles/24261076617869-Product-Editing) for more details. See [Subscription States](https://maxio.zendesk.com/hc/en-us/articles/24252119027853-Subscription-States) for more info about subscription states and state transitions. ### Properties - pending - failed_to_create - trialing - assessing - active - soft_failure - past_due - suspended - canceled - expired - paused - unpaid - trial_ended - on_hold - awaiting_signup ## Subscription State Change ### Properties - previous_subscription_state (`String`) - new_subscription_state (`String`) ## Subscription State Filter Allowed values for filtering by the current state of the subscription. ### Properties - active - canceled - expired - expired_cards - on_hold - past_due - pending_cancellation - pending_renewal - suspended - trial_ended - trialing - unpaid ## Subscriptions Mrr Error Response ### Properties - errors (`Attribute Error`) ## Subscriptions Mrr Error Response1 ### Properties - errors (`Attribute Error`) ## Tax Configuration ### Properties - kind (`Tax Configuration Kind`) - destination_address (`Tax Destination Address`) - fully_configured (`Boolean`): Returns `true` when Chargify has been properly configured to charge tax using the specified tax system. More details about taxes: https://maxio.zendesk.com/hc/en-us/articles/24287012608909-Taxes-Overview ## Tax Configuration Kind ### Properties - custom - Enum_managed avalara - Enum_linked avalara - Enum_digital river ## Tax Destination Address ### Properties - shipping_then_billing - billing_then_shipping - shipping_only - billing_only ## Too Many Management Link Requests ### Properties - error (`String`) - new_link_available_at (`DateTime`) ## Too Many Management Link Requests Error ### Properties - errors (`Too Many Management Link Requests`) ## Too Many Management Link Requests Error1 ### Properties - errors (`Too Many Management Link Requests`) ## Trial Type Indicates how a trial is handled when the trail period ends and there is no credit card on file. For `no_obligation`, the subscription transitions to a Trial Ended state. Maxio will not send any emails or statements. For `payment_expected`, the subscription transitions to a Past Due state. Maxio will send normal dunning emails and statements according to your other settings. ### Properties - no_obligation - payment_expected ## Update Allocation Expiration Date ### Properties - allocation (`Allocation Expiration Date`) ## Update Component ### Properties - handle (`String`) - name (`String`): The name of the Component, suitable for display on statements. i.e. Text Messages. - description (`String`): The description of the component. - accounting_code (`String`) - taxable (`Boolean`): Boolean flag describing whether a component is taxable or not. - tax_code (`String`): A string representing the tax code related to the component type. This is especially important when using AvaTax to tax based on locale. This attribute has a max length of 25 characters. - item_category (`Item Category`): One of the following: Business Software, Consumer Software, Digital Services, Physical Goods, Other - display_on_hosted_page (`Boolean`) - upgrade_charge (`Credit Type`): The type of credit to be created when upgrading/downgrading. Defaults to the component and then site setting if one is not provided. Available values: `full`, `prorated`, `none`. ## Update Component Price Point ### Properties - name (`String`) - handle (`String`) - pricing_scheme (`Pricing Scheme`): The identifier for the pricing scheme. See [Product Components](https://help.chargify.com/products/product-components.html) for an overview of pricing schemes. - use_site_exchange_rate (`Boolean`): Whether to use the site level exchange rate or define your own prices for each currency if you have multiple currencies defined on the site. - tax_included (`Boolean`): Whether or not the price point includes tax - interval (`Number`): The numerical interval. i.e. 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`): 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. - prices (`array`) ## Update Component Price Point Request ### Properties - price_point (`Update Component Price Point`) ## Update Component Request ### Properties - component (`Update Component`) ## Update Coupon Currency ### Properties - currency (`String`): ISO code for the site defined currency. - price (`Number`): Price for the given currency. ## Update Currency Price ### Properties - id (`Number`): ID of the currency price record being updated - price (`Decimal`): New price for the given currency ## Update Currency Prices Request ### Properties - currency_prices (`array`) ## Update Customer ### Properties - first_name (`String`) - last_name (`String`) - email (`String`) - cc_emails (`String`) - organization (`String`) - reference (`String`) - address (`String`) - address_2 (`String`) - city (`String`) - state (`String`) - zip (`String`) - country (`String`) - phone (`String`) - locale (`String`): Set a specific language on a customer record. - vat_number (`String`) - tax_exempt (`Boolean`) - tax_exempt_reason (`String`) - parent_id (`Number`) - verified (`Boolean`): Is the customer verified to use ACH as a payment method. Available only on Authorize.Net gateway - salesforce_id (`String`): The Salesforce ID of the customer ## Update Customer Request ### Properties - customer (`Update Customer`) ## Update Metadata ### Properties - current_name (`String`) - name (`String`) - value (`String`) ## Update Metadata Request ### Properties - metadata (`Update Metadata`) ## Update Metafield ### Properties - current_name (`String`) - name (`String`) - scope (`Metafield Scope`): Warning: When updating a metafield's scope attribute, all scope attributes must be passed. Partially complete scope attributes will override the existing settings. - input_type (`Metafield Input`): Indicates the type of metafield. A text metafield allows any string value. Dropdown and radio metafields have a set of values that can be selected. Defaults to 'text'. - enum (`array`): Only applicable when input_type is radio or dropdown. ## Update Metafields Request ### Properties - metafields (`Update Metafield | array`) ## Update Payment Profile ### Properties - first_name (`String`): The first name of the card holder. - last_name (`String`): The last name of the card holder. - full_number (`String`): The full credit card number - card_type (`Card Type`): The type of card used. - expiration_month (`String`): (Optional when performing an Import via vault_token, required otherwise) The 1- or 2-digit credit card expiration month, as an integer or string, i.e. 5 - expiration_year (`String`): (Optional when performing a Import via vault_token, required otherwise) The 4-digit credit card expiration year, as an integer or string, i.e. 2012 - current_vault (`All Vaults`): The vault that stores the payment profile with the provided `vault_token`. Use `bogus` for testing. - billing_address (`String`): The credit card or bank account billing street address (i.e. 123 Main St.). This value is merely passed through to the payment gateway. - billing_city (`String`): The credit card or bank account billing address city (i.e. “Boston”). This value is merely passed through to the payment gateway. - billing_state (`String`): The credit card or bank account billing address state (i.e. MA). This value is merely passed through to the payment gateway. This must conform to the [ISO_3166-1](https://en.wikipedia.org/wiki/ISO_3166-1#Current_codes) in order to be valid for tax locale purposes. - billing_zip (`String`): The credit card or bank account billing address zip code (i.e. 12345). This value is merely passed through to the payment gateway. - billing_country (`String`): The credit card or bank account billing address country, required in [ISO_3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format (i.e. “US”). This value is merely passed through to the payment gateway. Some gateways require country codes in a specific format. Check your gateway’s documentation. If creating an ACH subscription, only US is supported at this time. - billing_address_2 (`String`): Second line of the customer’s billing address i.e. Apt. 100 ## Update Payment Profile Request ### Properties - payment_profile (`Update Payment Profile`) ## Update Price ### Properties - id (`Number`) - ending_quantity (`Number | String`) - unit_price (`Decimal | String`): The price can contain up to 8 decimal places. i.e. 1.00 or 0.0012 or 0.00000065 - _destroy (`Boolean`) - starting_quantity (`Number | String`) ## Update Product Price Point ### Properties - handle (`String`) - price_in_cents (`Long`) ## Update Product Price Point Request ### Properties - price_point (`Update Product Price Point`) ## Update Reason Code ### Properties - code (`String`): The unique identifier for the ReasonCode - description (`String`): The friendly summary of what the code signifies - position (`Number`): The order that code appears in lists ## Update Reason Code Request ### Properties - reason_code (`Update Reason Code`) ## Update Segment ### Properties - pricing_scheme (`Pricing Scheme`): The identifier for the pricing scheme. See [Product Components](https://help.chargify.com/products/product-components.html) for an overview of pricing schemes. - prices (`array`) ## Update Segment Request ### Properties - segment (`Update Segment`) ## Update Subscription ### Properties - credit_card_attributes (`Credit Card Attributes`) - product_handle (`String`): Set to the handle of a different product to change the subscription's product - product_id (`Number`): Set to the id of a different product to change the subscription's product - product_change_delayed (`Boolean`) - next_product_id (`String`): Set to an empty string to cancel a delayed product change. - next_product_price_point_id (`String`) - snap_day (`Number | Snap Day`): Use for subscriptions with product eligible for calendar billing only. Value can be 1-28 or 'end'. - initial_billing_at (`DateTime`): (Optional) Set this attribute to a future date/time to update a subscription in the Awaiting Signup Date state, to Awaiting Signup. In the Awaiting Signup state, a subscription behaves like any other. It can be canceled, allocated to, or have its billing date changed. etc. When the `initial_billing_at` date hits, the subscription will transition to the expected state. If the product has a trial, the subscription will enter a trial, otherwise it will go active. Setup fees will be respected either before or after the trial, as configured on the price point. If the payment is due at the initial_billing_at and it fails the subscription will be immediately canceled. You can omit the initial_billing_at date to activate the subscription immediately. See the [subscription import](https://maxio.zendesk.com/hc/en-us/articles/24251489107213-Advanced-Billing-Subscription-Imports#date-format) documentation for more information about Date/Time formats. - defer_signup (`Boolean`): (Optional) Set this attribute to true to move the subscription from Awaiting Signup, to Awaiting Signup Date. Use this when you want to update a subscription that has an unknown initial billing date. When the first billing date is known, update a subscription to set the `initial_billing_at` date. The subscription moves to the awaiting signup with a scheduled initial billing date. You can omit the initial_billing_at date to activate the subscription immediately. See [Subscription States](https://maxio-chargify.zendesk.com/hc/en-us/articles/5404222005773-Subscription-States) for more information. - next_billing_at (`DateTime`) - expires_at (`DateTime`): Timestamp giving the expiration date of this subscription (if any). You may manually change the expiration date at any point during a subscription period. - payment_collection_method (`String`) - receives_invoice_emails (`Boolean`) - net_terms (`String | Number`) - stored_credential_transaction_id (`Number`) - reference (`String`) - custom_price (`Subscription Custom Price`): (Optional) Used in place of `product_price_point_id` to define a custom price point unique to the subscription - components (`array`): (Optional) An array of component ids and custom prices to be added to the subscription. - dunning_communication_delay_enabled (`Boolean`): Enable Communication Delay feature, making sure no communication (email or SMS) is sent to the Customer between 9PM and 8AM in time zone set by the `dunning_communication_delay_time_zone` attribute. - dunning_communication_delay_time_zone (`String`): Time zone for the Dunning Communication Delay feature. - product_price_point_id (`Number`): Set to change the current product's price point. - product_price_point_handle (`String`): Set to change the current product's price point. ## Update Subscription Component ### Properties - component_id (`Number`) - custom_price (`Component Custom Price`): Create or update custom pricing unique to the subscription. Used in place of `price_point_id`. ## Update Subscription Group ### Properties - member_ids (`array`) ## Update Subscription Group Request ### Properties - subscription_group (`Update Subscription Group`) ## Update Subscription Note Updatable fields for Subscription Note ### Properties - body (`String`) - sticky (`Boolean`) ## Update Subscription Note Request Updatable fields for Subscription Note ### Properties - note (`Update Subscription Note`): Updatable fields for Subscription Note ## Update Subscription Request ### Properties - subscription (`Update Subscription`) ## Upsert Prepaid Configuration ### Properties - initial_funding_amount_in_cents (`Long`) - replenish_to_amount_in_cents (`Long`) - auto_replenish (`Boolean`) - replenish_threshold_amount_in_cents (`Long`) ## Upsert Prepaid Configuration Request ### Properties - prepaid_configuration (`Upsert Prepaid Configuration`) ## Usage ### Properties - id (`Long`) - memo (`String`) - created_at (`DateTime`) - price_point_id (`Number`) - quantity (`Number | String`) - overage_quantity (`Number`) - component_id (`Number`) - component_handle (`String`) - subscription_id (`Number`) ## Usage Response ### Properties - usage (`Usage`) ## Void Invoice ### Properties - reason (`String`) ## Void Invoice Event Data Example schema for an `void_invoice` event ### Properties - credit_note_attributes (`Credit Note`) - memo (`String`): The memo provided during invoice voiding. - applied_amount (`String`): The amount of the void. - transaction_time (`DateTime`): The time the refund was applied, in ISO 8601 format, i.e. "2019-06-07T17:20:06Z" - is_advance_invoice (`Boolean`): If true, the invoice is an advance invoice. - reason (`String`): The reason for the void. ## Void Invoice Request ### Properties - void (`Void Invoice`) ## Void Remainder Event Data Example schema for an `void_remainder` event ### Properties - credit_note_attributes (`Credit Note`) - memo (`String`): The memo provided during invoice remainder voiding. - applied_amount (`String`): The amount of the void. - transaction_time (`DateTime`): The time the refund was applied, in ISO 8601 format, i.e. "2019-06-07T17:20:06Z" ## Webhook ### Properties - event (`String`): A string describing which event type produced the given webhook - id (`Long`): The unique identifier for the webhooks (unique across all of Chargify). This is not changed on a retry/replay of the same webhook, so it may be used to avoid duplicate action for the same event. - created_at (`DateTime`): Timestamp indicating when the webhook was created - last_error (`String`): Text describing the status code and/or error from the last failed attempt to send the Webhook. When a webhook is retried and accepted, this field will be cleared. - last_error_at (`DateTime`): Timestamp indicating when the last non-acceptance occurred. If a webhook is later resent and accepted, this field will be cleared. - accepted_at (`DateTime`): Timestamp indicating when the webhook was accepted by the merchant endpoint. When a webhook is explicitly replayed by the merchant, this value will be cleared until it is accepted again. - last_sent_at (`DateTime`): Timestamp indicating when the most recent attempt was made to send the webhook - last_sent_url (`String`): The url that the endpoint was last sent to. - successful (`Boolean`): A boolean flag describing whether the webhook was accepted by the webhook endpoint for the most recent attempt. (Acceptance is defined by receiving a “200 OK” HTTP response within a reasonable timeframe, i.e. 15 seconds) - body (`String`): The data sent within the webhook post - signature (`String`): The calculated webhook signature - signature_hmac_sha_256 (`String`): The calculated HMAC-SHA-256 webhook signature ## Webhook Order ### Properties - newest_first - oldest_first ## Webhook Response ### Properties - webhook (`Webhook`) ## Webhook Status ### Properties - successful - failed - pending - paused ## Webhook Subscription ### Properties - billing_date_change - component_allocation_change - customer_create - customer_update - dunning_step_reached - expiring_card - expiration_date_change - invoice_issued - metered_usage - payment_failure - payment_success - direct_debit_payment_pending - direct_debit_payment_paid_out - direct_debit_payment_rejected - prepaid_subscription_balance_changed - prepaid_usage - refund_failure - refund_success - renewal_failure - renewal_success - signup_failure - signup_success - statement_closed - statement_settled - subscription_card_update - subscription_group_card_update - subscription_product_change - subscription_state_change - trial_end_notice - upcoming_renewal_notice - upgrade_downgrade_failure - upgrade_downgrade_success - pending_cancellation_change - subscription_prepayment_account_balance_changed - subscription_service_credit_account_balance_changed ## UpdateComponentPricePointComponentId This is a container for OneOf cases. ### Cases #### `Number` Initialization Code: ```Http 0 ``` #### `String` Initialization Code: ```Http "String0" ``` ## UpdateComponentPricePointPricePointId This is a container for OneOf cases. ### Cases #### `Number` Initialization Code: ```Http 0 ``` #### `String` Initialization Code: ```Http "String0" ``` ## ReadComponentPricePointComponentId This is a container for OneOf cases. ### Cases #### `Number` Initialization Code: ```Http 0 ``` #### `String` Initialization Code: ```Http "String0" ``` ## ReadComponentPricePointPricePointId This is a container for OneOf cases. ### Cases #### `Number` Initialization Code: ```Http 0 ``` #### `String` Initialization Code: ```Http "String0" ``` ## ArchiveComponentPricePointComponentId This is a container for OneOf cases. ### Cases #### `Number` Initialization Code: ```Http 0 ``` #### `String` Initialization Code: ```Http "String0" ``` ## ArchiveComponentPricePointPricePointId This is a container for OneOf cases. ### Cases #### `Number` Initialization Code: ```Http 0 ``` #### `String` Initialization Code: ```Http "String0" ``` ## CreateProductPricePointProductId This is a container for OneOf cases. ### Cases #### `Number` Initialization Code: ```Http 0 ``` #### `String` Initialization Code: ```Http "String0" ``` ## ListProductPricePointsProductId This is a container for OneOf cases. ### Cases #### `Number` Initialization Code: ```Http 0 ``` #### `String` Initialization Code: ```Http "String0" ``` ## UpdateProductPricePointProductId This is a container for OneOf cases. ### Cases #### `Number` Initialization Code: ```Http 0 ``` #### `String` Initialization Code: ```Http "String0" ``` ## UpdateProductPricePointPricePointId This is a container for OneOf cases. ### Cases #### `Number` Initialization Code: ```Http 0 ``` #### `String` Initialization Code: ```Http "String0" ``` ## ReadProductPricePointProductId This is a container for OneOf cases. ### Cases #### `Number` Initialization Code: ```Http 0 ``` #### `String` Initialization Code: ```Http "String0" ``` ## ReadProductPricePointPricePointId This is a container for OneOf cases. ### Cases #### `Number` Initialization Code: ```Http 0 ``` #### `String` Initialization Code: ```Http "String0" ``` ## ArchiveProductPricePointProductId This is a container for OneOf cases. ### Cases #### `Number` Initialization Code: ```Http 0 ``` #### `String` Initialization Code: ```Http "String0" ``` ## ArchiveProductPricePointPricePointId This is a container for OneOf cases. ### Cases #### `Number` Initialization Code: ```Http 0 ``` #### `String` Initialization Code: ```Http "String0" ``` ## CreateUsageSubscriptionIdOrReference This is a container for OneOf cases. ### Cases #### `Number` Initialization Code: ```Http 0 ``` #### `String` Initialization Code: ```Http "String0" ``` ## CreateUsageComponentId This is a container for OneOf cases. ### Cases #### `Number` Initialization Code: ```Http 0 ``` #### `String` Initialization Code: ```Http "String0" ``` ## ListUsagesSubscriptionIdOrReference This is a container for OneOf cases. ### Cases #### `Number` Initialization Code: ```Http 0 ``` #### `String` Initialization Code: ```Http "String0" ``` ## ListUsagesComponentId This is a container for OneOf cases. ### Cases #### `Number` Initialization Code: ```Http 0 ``` #### `String` Initialization Code: ```Http "String0" ``` ## Invoice-Event ### Cases #### `Apply Credit Note Event` Initialization Code: ```Http { "id": 214, "timestamp": "2016-03-13T12:52:32.123Z", "invoice": { "issue_date": "2024-01-01", "due_date": "2024-01-01", "paid_date": "2024-01-01", "public_url_expires_on": "2024-01-21" }, "event_type": "apply_credit_note", "event_data": { "uid": "uid6", "credit_note_number": "credit_note_number0", "credit_note_uid": "credit_note_uid0", "original_amount": "original_amount0", "applied_amount": "applied_amount2" } } ``` #### `Apply Debit Note Event` Initialization Code: ```Http { "id": 164, "timestamp": "2016-03-13T12:52:32.123Z", "invoice": { "issue_date": "2024-01-01", "due_date": "2024-01-01", "paid_date": "2024-01-01", "public_url_expires_on": "2024-01-21" }, "event_type": "apply_debit_note", "event_data": { "debit_note_number": "debit_note_number6", "debit_note_uid": "debit_note_uid2", "original_amount": "original_amount0", "applied_amount": "applied_amount2" } } ``` #### `Apply Payment Event` Initialization Code: ```Http { "id": 234, "timestamp": "2016-03-13T12:52:32.123Z", "invoice": { "issue_date": "2024-01-01", "due_date": "2024-01-01", "paid_date": "2024-01-01", "public_url_expires_on": "2024-01-21" }, "event_type": "apply_payment", "event_data": { "consolidation_level": "child", "memo": "memo0", "original_amount": "original_amount0", "applied_amount": "applied_amount2", "transaction_time": "2016-03-13T12:52:32.123Z", "payment_method": { "type": "apple_pay" } } } ``` #### `Backport Invoice Event` Initialization Code: ```Http { "id": 78, "timestamp": "2016-03-13T12:52:32.123Z", "invoice": { "issue_date": "2024-01-01", "due_date": "2024-01-01", "paid_date": "2024-01-01", "public_url_expires_on": "2024-01-21" }, "event_type": "backport_invoice", "event_data": { "issue_date": "2024-01-01", "due_date": "2024-01-01", "paid_date": "2024-01-01", "public_url_expires_on": "2024-01-21" } } ``` #### `Change Chargeback Status Event` Initialization Code: ```Http { "id": 214, "timestamp": "2016-03-13T12:52:32.123Z", "invoice": { "issue_date": "2024-01-01", "due_date": "2024-01-01", "paid_date": "2024-01-01", "public_url_expires_on": "2024-01-21" }, "event_type": "change_chargeback_status", "event_data": { "chargeback_status": "won" } } ``` #### `Change Invoice Collection Method Event` Initialization Code: ```Http { "id": 246, "timestamp": "2016-03-13T12:52:32.123Z", "invoice": { "issue_date": "2024-01-01", "due_date": "2024-01-01", "paid_date": "2024-01-01", "public_url_expires_on": "2024-01-21" }, "event_type": "change_invoice_collection_method", "event_data": { "from_collection_method": "from_collection_method4", "to_collection_method": "to_collection_method8" } } ``` #### `Change Invoice Status Event` Initialization Code: ```Http { "id": 92, "timestamp": "2016-03-13T12:52:32.123Z", "invoice": { "issue_date": "2024-01-01", "due_date": "2024-01-01", "paid_date": "2024-01-01", "public_url_expires_on": "2024-01-21" }, "event_type": "change_invoice_status", "event_data": { "from_status": "open", "to_status": "pending" } } ``` #### `Create Credit Note Event` Initialization Code: ```Http { "id": 28, "timestamp": "2016-03-13T12:52:32.123Z", "invoice": { "issue_date": "2024-01-01", "due_date": "2024-01-01", "paid_date": "2024-01-01", "public_url_expires_on": "2024-01-21" }, "event_type": "create_credit_note", "event_data": {} } ``` #### `Create Debit Note Event` Initialization Code: ```Http { "id": 98, "timestamp": "2016-03-13T12:52:32.123Z", "invoice": { "issue_date": "2024-01-01", "due_date": "2024-01-01", "paid_date": "2024-01-01", "public_url_expires_on": "2024-01-21" }, "event_type": "create_debit_note", "event_data": {} } ``` #### `Failed Payment Event` Initialization Code: ```Http { "id": 120, "timestamp": "2016-03-13T12:52:32.123Z", "invoice": { "issue_date": "2024-01-01", "due_date": "2024-01-01", "paid_date": "2024-01-01", "public_url_expires_on": "2024-01-21" }, "event_type": "failed_payment", "event_data": { "amount_in_cents": 220, "applied_amount": 194, "payment_method": "cash", "transaction_id": 78 } } ``` #### `Issue Invoice Event` Initialization Code: ```Http { "id": 130, "timestamp": "2016-03-13T12:52:32.123Z", "invoice": { "issue_date": "2024-01-01", "due_date": "2024-01-01", "paid_date": "2024-01-01", "public_url_expires_on": "2024-01-21" }, "event_type": "issue_invoice", "event_data": { "consolidation_level": "child", "from_status": "open", "to_status": "pending", "due_amount": "due_amount8", "total_amount": "total_amount2" } } ``` #### `Refund Invoice Event` Initialization Code: ```Http { "id": 54, "timestamp": "2016-03-13T12:52:32.123Z", "invoice": { "issue_date": "2024-01-01", "due_date": "2024-01-01", "paid_date": "2024-01-01", "public_url_expires_on": "2024-01-21" }, "event_type": "refund_invoice", "event_data": { "apply_credit": false, "credit_note_attributes": {}, "payment_id": 204, "refund_amount": "refund_amount8", "refund_id": 248, "transaction_time": "2016-03-13T12:52:32.123Z" } } ``` #### `Remove Payment Event` Initialization Code: ```Http { "id": 236, "timestamp": "2016-03-13T12:52:32.123Z", "invoice": { "issue_date": "2024-01-01", "due_date": "2024-01-01", "paid_date": "2024-01-01", "public_url_expires_on": "2024-01-21" }, "event_type": "remove_payment", "event_data": { "transaction_id": 78, "memo": "memo0", "applied_amount": "applied_amount2", "transaction_time": "2016-03-13T12:52:32.123Z", "payment_method": { "type": "apple_pay" }, "prepayment": false } } ``` #### `Void Invoice Event` Initialization Code: ```Http { "id": 16, "timestamp": "2016-03-13T12:52:32.123Z", "invoice": { "issue_date": "2024-01-01", "due_date": "2024-01-01", "paid_date": "2024-01-01", "public_url_expires_on": "2024-01-21" }, "event_type": "void_invoice", "event_data": { "credit_note_attributes": {}, "memo": "memo0", "applied_amount": "applied_amount2", "transaction_time": "2016-03-13T12:52:32.123Z", "is_advance_invoice": false, "reason": "reason2" } } ``` #### `Void Remainder Event` Initialization Code: ```Http { "id": 128, "timestamp": "2016-03-13T12:52:32.123Z", "invoice": { "issue_date": "2024-01-01", "due_date": "2024-01-01", "paid_date": "2024-01-01", "public_url_expires_on": "2024-01-21" }, "event_type": "void_remainder", "event_data": { "credit_note_attributes": {}, "memo": "memo0", "applied_amount": "applied_amount2", "transaction_time": "2016-03-13T12:52:32.123Z" } } ``` ## AllocationQuantity This is a container for OneOf cases. ### Cases #### `Number` Initialization Code: ```Http 0 ``` #### `String` Initialization Code: ```Http "String0" ``` ## AllocationPreviousQuantity This is a container for OneOf cases. ### Cases #### `Number` Initialization Code: ```Http 0 ``` #### `String` Initialization Code: ```Http "String0" ``` ## AllocationPreviewItemQuantity This is a container for OneOf cases. ### Cases #### `Number` Initialization Code: ```Http 0 ``` #### `String` Initialization Code: ```Http "String0" ``` ## AllocationPreviewItemPreviousQuantity This is a container for OneOf cases. ### Cases #### `Number` Initialization Code: ```Http 0 ``` #### `String` Initialization Code: ```Http "String0" ``` ## Invoice-Event-Payment A nested data structure detailing the method of payment ### Cases #### `Payment Method Apple Pay` Initialization Code: ```Http { "type": "apple_pay" } ``` #### `Payment Method Bank Account` Initialization Code: ```Http { "masked_account_number": "masked_account_number2", "masked_routing_number": "masked_routing_number2", "type": "bank_account" } ``` #### `Payment Method Credit Card` Initialization Code: ```Http { "card_brand": "card_brand4", "masked_card_number": "masked_card_number0", "type": "credit_card" } ``` #### `Payment Method External` Initialization Code: ```Http { "details": "details4", "kind": "kind2", "memo": "memo8", "type": "external" } ``` #### `Payment Method Paypal` Initialization Code: ```Http { "email": "email2", "type": "paypal_account" } ``` ## CalendarBillingSnapDay This is a container for OneOf cases. ### Cases #### `Number` Initialization Code: ```Http 1 ``` #### `SnapDay` Initialization Code: ```Http "end" ``` ## ComponentAllocationChangeAllocatedQuantity This is a container for OneOf cases. ### Cases #### `Number` Initialization Code: ```Http 0 ``` #### `String` Initialization Code: ```Http "String0" ``` ## ComponentPricePointAssignmentPricePoint This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Number` Initialization Code: ```Http 0 ``` ## CouponPayloadPercentage This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Precision` Initialization Code: ```Http 0.0 ``` ## CreateAllocationPricePointId This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Number` Initialization Code: ```Http 0 ``` ## CreateComponentPricePointRequestPricePoint This is a container for AnyOf cases. ### Cases #### `Create Component Price Point` Initialization Code: ```Http { "name": "name0", "pricing_scheme": "per_unit", "prices": [ { "starting_quantity": 242, "unit_price": 23.26 } ], "use_site_exchange_rate": true } ``` #### `Create Prepaid Usage Component Price Point` Initialization Code: ```Http { "name": "name0", "pricing_scheme": "per_unit", "prices": [ { "starting_quantity": 242, "unit_price": 23.26 } ], "overage_pricing": { "pricing_scheme": "stairstep" }, "use_site_exchange_rate": true } ``` ## CreateComponentPricePointsRequestPricePoints This is a container for AnyOf cases. ### Cases #### `Create Component Price Point` Initialization Code: ```Http { "name": "name0", "pricing_scheme": "per_unit", "prices": [ { "starting_quantity": 242, "unit_price": 23.26 } ], "use_site_exchange_rate": true } ``` #### `Create Prepaid Usage Component Price Point` Initialization Code: ```Http { "name": "name0", "pricing_scheme": "per_unit", "prices": [ { "starting_quantity": 242, "unit_price": 23.26 } ], "overage_pricing": { "pricing_scheme": "stairstep" }, "use_site_exchange_rate": true } ``` ## CreateInvoiceCouponPercentage This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Precision` Initialization Code: ```Http 0.0 ``` ## CreateInvoiceCouponAmount This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Precision` Initialization Code: ```Http 0.0 ``` ## CreateInvoiceCouponProductFamilyId This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Number` Initialization Code: ```Http 0 ``` ## CreateInvoiceItemQuantity This is a container for OneOf cases. ### Cases #### `Precision` Initialization Code: ```Http 0.0 ``` #### `String` Initialization Code: ```Http "String0" ``` ## CreateInvoiceItemUnitPrice This is a container for OneOf cases. ### Cases #### `Precision` Initialization Code: ```Http 0.0 ``` #### `String` Initialization Code: ```Http "String0" ``` ## CreateInvoiceItemProductId This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Number` Initialization Code: ```Http 0 ``` ## CreateInvoiceItemComponentId This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Number` Initialization Code: ```Http 0 ``` ## CreateInvoiceItemPricePointId This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Number` Initialization Code: ```Http 0 ``` ## CreateInvoiceItemProductPricePointId This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Number` Initialization Code: ```Http 0 ``` ## CreateInvoicePaymentAmount This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Precision` Initialization Code: ```Http 0.0 ``` ## CreateMetafieldsRequestMetafields This is a container for OneOf cases. ### Cases #### `Create Metafield` Initialization Code: ```Http { "name": "my_field", "scope": { "csv": "0", "invoices": "0", "statements": "0", "portal": "0", "public_show": "0", "public_edit": "0" }, "input_type": "text", "enum": [ "string" ] } ``` #### `Create Metafield` Initialization Code: ```Http [ {} ] ``` ## CreateMultiInvoicePaymentAmount This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Precision` Initialization Code: ```Http 0.0 ``` ## CreateOrUpdateSegmentPriceUnitPrice This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Precision` Initialization Code: ```Http 0.0 ``` ## CreatePaymentProfileExpirationMonth This is a container for OneOf cases. ### Cases #### `Number` Initialization Code: ```Http 0 ``` #### `String` Initialization Code: ```Http "String0" ``` ## CreatePaymentProfileExpirationYear This is a container for OneOf cases. ### Cases #### `Number` Initialization Code: ```Http 0 ``` #### `String` Initialization Code: ```Http "String0" ``` ## CreateSegmentSegmentProperty1Value This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Precision` Initialization Code: ```Http 0.0 ``` #### `Number` Initialization Code: ```Http 0 ``` #### `Boolean` Initialization Code: ```Http false ``` ## CreateSegmentSegmentProperty2Value This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Precision` Initialization Code: ```Http 0.0 ``` #### `Number` Initialization Code: ```Http 0 ``` #### `Boolean` Initialization Code: ```Http false ``` ## CreateSegmentSegmentProperty3Value This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Precision` Initialization Code: ```Http 0.0 ``` #### `Number` Initialization Code: ```Http 0 ``` #### `Boolean` Initialization Code: ```Http false ``` ## CreateSegmentSegmentProperty4Value This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Precision` Initialization Code: ```Http 0.0 ``` #### `Number` Initialization Code: ```Http 0 ``` #### `Boolean` Initialization Code: ```Http false ``` ## CreateSubscriptionOfferId This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Number` Initialization Code: ```Http 0 ``` ## CreateSubscriptionComponentComponentId This is a container for OneOf cases. ### Cases #### `Number` Initialization Code: ```Http 0 ``` #### `String` Initialization Code: ```Http "String0" ``` ## CreateSubscriptionComponentAllocatedQuantity This is a container for OneOf cases. ### Cases #### `Number` Initialization Code: ```Http 0 ``` #### `String` Initialization Code: ```Http "String0" ``` ## CreateSubscriptionComponentPricePointId This is a container for OneOf cases. ### Cases #### `Number` Initialization Code: ```Http 0 ``` #### `String` Initialization Code: ```Http "String0" ``` ## CustomerErrorResponseErrors This is a container for OneOf cases. ### Cases #### `Customer Error` Initialization Code: ```Http {} ``` #### `String` Initialization Code: ```Http [ "String1" ] ``` ## CustomerErrorResponse1Errors This is a container for OneOf cases. ### Cases #### `Customer Error` Initialization Code: ```Http {} ``` #### `String` Initialization Code: ```Http [ "String1" ] ``` ## DeductServiceCreditAmount This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Precision` Initialization Code: ```Http 0.0 ``` ## EBBComponentUnitPrice This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Precision` Initialization Code: ```Http 0.0 ``` ## EventEventSpecificData This is a container for OneOf cases. ### Cases #### `Subscription Product Change` Initialization Code: ```Http { "previous_product_id": 126, "new_product_id": 12 } ``` #### `Subscription State Change` Initialization Code: ```Http { "previous_subscription_state": "previous_subscription_state2", "new_subscription_state": "new_subscription_state6" } ``` #### `Payment Related Events` Initialization Code: ```Http { "product_id": 42, "account_transaction_id": 58 } ``` #### `Refund Success` Initialization Code: ```Http { "refund_id": 12, "gateway_transaction_id": 182, "product_id": 168 } ``` #### `Component Allocation Change` Initialization Code: ```Http { "previous_allocation": 94, "new_allocation": 102, "component_id": 88, "component_handle": "component_handle8", "memo": "memo2", "allocation_id": 158 } ``` #### `Metered Usage` Initialization Code: ```Http { "previous_unit_balance": "previous_unit_balance6", "new_unit_balance": 80, "usage_quantity": 42, "component_id": 4, "component_handle": "component_handle8", "memo": "memo2" } ``` #### `Prepaid Usage` Initialization Code: ```Http { "previous_unit_balance": "previous_unit_balance0", "previous_overage_unit_balance": "previous_overage_unit_balance4", "new_unit_balance": 252, "new_overage_unit_balance": 224, "usage_quantity": 214, "overage_usage_quantity": 106, "component_id": 176, "component_handle": "component_handle4", "memo": "memo8", "allocation_details": [ {} ] } ``` #### `Dunning Step Reached` Initialization Code: ```Http { "dunner": { "state": "state8", "subscription_id": 194, "revenue_at_risk_in_cents": 98, "created_at": "2016-03-13T12:52:32.123Z", "attempts": 42, "last_attempted_at": "2016-03-13T12:52:32.123Z" }, "current_step": { "day_threshold": 198, "action": "action4", "send_email": false, "send_bcc_email": false, "send_sms": false }, "next_step": { "day_threshold": 30, "action": "action4", "send_email": false, "send_bcc_email": false, "send_sms": false } } ``` #### `Invoice Issued` Initialization Code: ```Http { "uid": "uid4", "number": "number8", "role": "role2", "due_date": "2016-03-13", "issue_date": "issue_date0", "paid_date": "paid_date6", "due_amount": "due_amount6", "paid_amount": "paid_amount4", "tax_amount": "tax_amount2", "refund_amount": "refund_amount0", "total_amount": "total_amount0", "status_amount": "status_amount4", "product_name": "product_name0", "consolidation_level": "consolidation_level4", "line_items": [ {} ] } ``` #### `Pending Cancellation Change` Initialization Code: ```Http { "cancellation_state": "cancellation_state8", "cancels_at": "2016-03-13T12:52:32.123Z" } ``` #### `Prepaid Subscription Balance Changed` Initialization Code: ```Http { "reason": "reason8", "current_account_balance_in_cents": 250, "prepayment_account_balance_in_cents": 44, "current_usage_amount_in_cents": 242 } ``` #### `Proforma Invoice Issued` Initialization Code: ```Http { "uid": "uid0", "number": "number2", "role": "role6", "delivery_date": "2016-03-13", "created_at": "2016-03-13T12:52:32.123Z", "due_amount": "due_amount2", "paid_amount": "paid_amount8", "tax_amount": "tax_amount6", "total_amount": "total_amount6", "product_name": "product_name6", "line_items": [ {} ] } ``` #### `Subscription Group Signup Event Data` Initialization Code: ```Http { "subscription_group": {}, "customer": {} } ``` #### `Credit Account Balance Changed` Initialization Code: ```Http { "reason": "reason8", "service_credit_account_balance_in_cents": 10, "service_credit_balance_change_in_cents": 116, "currency_code": "currency_code8", "at_time": "2016-03-13T12:52:32.123Z" } ``` #### `Prepayment Account Balance Changed` Initialization Code: ```Http { "reason": "reason4", "prepayment_account_balance_in_cents": 182, "prepayment_balance_change_in_cents": 206, "currency_code": "currency_code4" } ``` #### `Payment Collection Method Changed` Initialization Code: ```Http { "previous_value": "previous_value4", "current_value": "current_value2" } ``` #### `Item Price Point Changed` Initialization Code: ```Http { "item_id": 66, "item_type": "item_type6", "item_handle": "item_handle4", "item_name": "item_name8", "previous_price_point": {}, "current_price_point": {} } ``` #### `Custom Field Value Change` Initialization Code: ```Http { "event_type": "event_type2", "metafield_name": "metafield_name6", "metafield_id": 78, "old_value": "old_value2", "new_value": "new_value8", "resource_type": "resource_type2", "resource_id": 74 } ``` ## IssueServiceCreditAmount This is a container for OneOf cases. ### Cases #### `Precision` Initialization Code: ```Http 0.0 ``` #### `String` Initialization Code: ```Http "String0" ``` ## MetafieldEnum This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `String` Initialization Code: ```Http [ "String1" ] ``` ## MeteredComponentUnitPrice This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Precision` Initialization Code: ```Http 0.0 ``` ## OnOffComponentUnitPrice This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Precision` Initialization Code: ```Http 0.0 ``` ## PaymentProfileAttributesExpirationMonth This is a container for OneOf cases. ### Cases #### `Number` Initialization Code: ```Http 0 ``` #### `String` Initialization Code: ```Http "String0" ``` ## PaymentProfileAttributesExpirationYear This is a container for OneOf cases. ### Cases #### `Number` Initialization Code: ```Http 0 ``` #### `String` Initialization Code: ```Http "String0" ``` ## Payment-Profile ### Cases #### `ApplePay Payment Profile` Initialization Code: ```Http { "payment_type": "apple_pay" } ``` #### `Bank Account Payment Profile` Initialization Code: ```Http { "masked_bank_account_number": "masked_bank_account_number8", "payment_type": "bank_account", "verified": false } ``` #### `Credit Card Payment Profile` Initialization Code: ```Http { "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": "customer_vault_token2", "billing_address_2": "", "payment_type": "credit_card", "site_gateway_setting_id": 1, "gateway_handle": "gateway_handle8" } ``` #### `Paypal Payment Profile` Initialization Code: ```Http { "payment_type": "paypal_account" } ``` ## PrepaidUsageComponentUnitPrice This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Precision` Initialization Code: ```Http 0.0 ``` ## PriceStartingQuantity This is a container for OneOf cases. ### Cases #### `Number` Initialization Code: ```Http 0 ``` #### `String` Initialization Code: ```Http "String0" ``` ## PriceEndingQuantity This is a container for OneOf cases. ### Cases #### `Number` Initialization Code: ```Http 0 ``` #### `String` Initialization Code: ```Http "String0" ``` ## PriceUnitPrice This is a container for OneOf cases. ### Cases #### `Precision` Initialization Code: ```Http 0.0 ``` #### `String` Initialization Code: ```Http "String0" ``` ## QuantityBasedComponentUnitPrice This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Precision` Initialization Code: ```Http 0.0 ``` ## ReactivateSubscriptionRequestResume This is a container for OneOf cases. ### Cases #### `Boolean` Initialization Code: ```Http false ``` #### `Resume Options` Initialization Code: ```Http {} ``` ## RefundConsolidatedInvoiceSegmentUids This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http [ "String1" ] ``` #### `String` Initialization Code: ```Http "String0" ``` ## RefundInvoiceRequestRefund This is a container for AnyOf cases. ### Cases #### `Refund Invoice` Initialization Code: ```Http { "amount": "amount8", "memo": "memo0", "payment_id": 0 } ``` #### `Refund Consolidated Invoice` Initialization Code: ```Http { "memo": "memo0", "payment_id": 46, "segment_uids": [ "String0", "String1" ] } ``` ## RefundPrepaymentAmount This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Precision` Initialization Code: ```Http 0.0 ``` ## RenewalPreviewComponentComponentId This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Number` Initialization Code: ```Http 0 ``` ## RenewalPreviewComponentPricePointId This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Number` Initialization Code: ```Http 0 ``` ## SegmentSegmentProperty1Value This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Precision` Initialization Code: ```Http 0.0 ``` #### `Number` Initialization Code: ```Http 0 ``` #### `Boolean` Initialization Code: ```Http false ``` ## SegmentSegmentProperty2Value This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Precision` Initialization Code: ```Http 0.0 ``` #### `Number` Initialization Code: ```Http 0 ``` #### `Boolean` Initialization Code: ```Http false ``` ## SegmentSegmentProperty3Value This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Precision` Initialization Code: ```Http 0.0 ``` #### `Number` Initialization Code: ```Http 0 ``` #### `Boolean` Initialization Code: ```Http false ``` ## SegmentSegmentProperty4Value This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Precision` Initialization Code: ```Http 0.0 ``` #### `Number` Initialization Code: ```Http 0 ``` #### `Boolean` Initialization Code: ```Http false ``` ## SubscriptionSnapDay This is a container for OneOf cases. ### Cases #### `Number` Initialization Code: ```Http 1 ``` #### `SnapDay` Initialization Code: ```Http "end" ``` ## SubscriptionComponentAllocatedQuantity This is a container for OneOf cases. ### Cases #### `Number` Initialization Code: ```Http 0 ``` #### `String` Initialization Code: ```Http "String0" ``` ## SubscriptionCustomPricePriceInCents This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Long` Initialization Code: ```Http 0 ``` ## SubscriptionCustomPriceInterval This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Number` Initialization Code: ```Http 0 ``` ## SubscriptionCustomPriceTrialPriceInCents This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Long` Initialization Code: ```Http 0 ``` ## SubscriptionCustomPriceTrialInterval This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Number` Initialization Code: ```Http 0 ``` ## SubscriptionCustomPriceInitialChargeInCents This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Long` Initialization Code: ```Http 0 ``` ## SubscriptionCustomPriceExpirationInterval This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Number` Initialization Code: ```Http 0 ``` ## SubscriptionGroupCreateErrorResponseErrors This is a container for OneOf cases. ### Cases #### `Subscription Group Members Array Error` Initialization Code: ```Http { "members": [ "members6" ] } ``` #### `Subscription Group Single Error` Initialization Code: ```Http { "subscription_group": "subscription_group2" } ``` #### `String` Initialization Code: ```Http "String0" ``` ## SubscriptionGroupCreateErrorResponse1Errors This is a container for OneOf cases. ### Cases #### `Subscription Group Members Array Error` Initialization Code: ```Http { "members": [ "members6" ] } ``` #### `Subscription Group Single Error` Initialization Code: ```Http { "subscription_group": "subscription_group2" } ``` #### `String` Initialization Code: ```Http "String0" ``` ## SubscriptionGroupCreditCardFullNumber This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Number` Initialization Code: ```Http 0 ``` ## SubscriptionGroupCreditCardExpirationMonth This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Number` Initialization Code: ```Http 0 ``` ## SubscriptionGroupCreditCardExpirationYear This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Number` Initialization Code: ```Http 0 ``` ## SubscriptionGroupSignupComponentComponentId This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Number` Initialization Code: ```Http 0 ``` ## SubscriptionGroupSignupComponentAllocatedQuantity This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Number` Initialization Code: ```Http 0 ``` ## SubscriptionGroupSignupComponentUnitBalance This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Number` Initialization Code: ```Http 0 ``` ## SubscriptionGroupSignupComponentPricePointId This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Number` Initialization Code: ```Http 0 ``` ## UpdateMetafieldsRequestMetafields This is a container for OneOf cases. ### Cases #### `Update Metafield` Initialization Code: ```Http {} ``` #### `Update Metafield` Initialization Code: ```Http [ {} ] ``` ## UpdatePriceEndingQuantity This is a container for OneOf cases. ### Cases #### `Number` Initialization Code: ```Http 0 ``` #### `String` Initialization Code: ```Http "String0" ``` ## UpdatePriceUnitPrice This is a container for OneOf cases. ### Cases #### `Precision` Initialization Code: ```Http 0.0 ``` #### `String` Initialization Code: ```Http "String0" ``` ## UpdatePriceStartingQuantity This is a container for OneOf cases. ### Cases #### `Number` Initialization Code: ```Http 0 ``` #### `String` Initialization Code: ```Http "String0" ``` ## UpdateSubscriptionSnapDay This is a container for OneOf cases. ### Cases #### `Number` Initialization Code: ```Http 1 ``` #### `SnapDay` Initialization Code: ```Http "end" ``` ## UpdateSubscriptionNetTerms This is a container for OneOf cases. ### Cases #### `String` Initialization Code: ```Http "String0" ``` #### `Number` Initialization Code: ```Http 0 ``` ## UsageQuantity This is a container for OneOf cases. ### Cases #### `Number` Initialization Code: ```Http 0 ``` #### `String` Initialization Code: ```Http "String0" ```