@maxio-com/advanced-billing-sdk
Version:
Ultimate billing and pricing flexibility for B2B SaaS. Maxio integrates directly into your product, so you can seamlessly manage your product catalog, bill customers, and collect payments.
960 lines • 73.4 kB
JavaScript
/**
* AdvancedBilling
*
* This file was automatically generated for Maxio by APIMATIC v3.0 ( https://www.apimatic.io ).
*/
import { commaPrefix, unindexedPrefix, } from '../core';
import { activateSubscriptionRequestSchema, } from '../models/activateSubscriptionRequest';
import { addCouponsRequestSchema, } from '../models/addCouponsRequest';
import { createSubscriptionRequestSchema, } from '../models/createSubscriptionRequest';
import { overrideSubscriptionRequestSchema, } from '../models/overrideSubscriptionRequest';
import { prepaidConfigurationResponseSchema, } from '../models/prepaidConfigurationResponse';
import { sortingDirectionSchema, } from '../models/sortingDirection';
import { subscriptionDateFieldSchema, } from '../models/subscriptionDateField';
import { subscriptionIncludeSchema, } from '../models/subscriptionInclude';
import { subscriptionListIncludeSchema, } from '../models/subscriptionListInclude';
import { subscriptionPreviewResponseSchema, } from '../models/subscriptionPreviewResponse';
import { subscriptionPurgeTypeSchema, } from '../models/subscriptionPurgeType';
import { subscriptionResponseSchema, } from '../models/subscriptionResponse';
import { subscriptionSortSchema, } from '../models/subscriptionSort';
import { subscriptionStateFilterSchema, } from '../models/subscriptionStateFilter';
import { updateSubscriptionRequestSchema, } from '../models/updateSubscriptionRequest';
import { upsertPrepaidConfigurationRequestSchema, } from '../models/upsertPrepaidConfigurationRequest';
import { array, dict, number, optional, string } from '../schema';
import { BaseController } from './baseController';
import { ApiError } from '@apimatic/core';
import { ErrorArrayMapResponseError } from '../errors/errorArrayMapResponseError';
import { ErrorListResponseError } from '../errors/errorListResponseError';
import { SingleErrorResponseError } from '../errors/singleErrorResponseError';
import { SubscriptionAddCouponError } from '../errors/subscriptionAddCouponError';
import { SubscriptionRemoveCouponErrorsError } from '../errors/subscriptionRemoveCouponErrorsError';
import { SubscriptionResponseError } from '../errors/subscriptionResponseError';
export class SubscriptionsController extends BaseController {
/**
* Full documentation on how subscriptions operate within Advanced Billing can be located under the
* following topics:
*
* + [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)
*
* When creating a subscription, you must specify a product and a customer. Credit card details may be
* required, depending on the options for the Product being subscribed ([see Product Options](https:
* //maxio.zendesk.com/hc/en-us/articles/24261076617869-Product-Editing)).
*
* The product may be specified by `product_id` or by `product_handle` (API Handle). In similar fashion,
* to pass a particular product price point, you may either use `product_price_point_handle` or
* `product_price_point_id`.
*
* An existing customer may be specified by a `customer_id` (ID within Advanced Billing) or a
* `customer_reference` (unique value within your app that you have shared with Advanced Billing via
* the reference attribute on a customer). You may also pass in an existing payment profile for that
* customer with `payment_profile_id`. A new customer may be created by providing `customer_attributes`.
*
* Credit card details may be required, depending on the options for the product being subscribed. The
* product can be specified by `product_id` or by `product_handle` (API Handle).
*
* If you are creating a subscription with a payment profile, the attribute to send will be
* `credit_card_attributes` or `bank_account_attributes` for ACH and Direct Debit. That said, when you
* read the subscription after creation, we return the profile details under `credit_card` or
* `bank_account`.
*
* ## Bulk creation of subscriptions
*
* Bulk creation of subscriptions is currently not supported. For scenarios where multiple
* subscriptions must be added, particularly when assigning to the same subscription group, it is
* essential to switch to a single-threaded approach.
*
* To avoid data conflicts or inaccuracies, incorporate a sleep interval between requests.
*
* While this single-threaded approach may impact performance, it ensures data consistency and accuracy
* in cases where concurrent creation attempts could otherwise lead to issues with subscription
* alignment and integrity.
*
* ## Taxable Subscriptions
*
* If your intent is to charge your subscribers tax via [Avalara Taxes](https://maxio.zendesk.com/hc/en-
* us/articles/24287043035661-Avalara-VAT-Tax) or [Custom Taxes](https://maxio.zendesk.com/hc/en-
* us/articles/24287044212749-Custom-Taxes), there are a few considerations to be made regarding
* collecting subscription data.
* For subscribers to be eligible to be taxed, the following information for the `customer` object or
* `payment_profile` object must by 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 adddress 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.
*
* ## Subscription Request Examples
*
* The subscription 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.
*
* The second section, "Passing Payment Information", will focus on passing payment information into
* Advanced Billing. Please be aware that <b>collecting and sending Advanced Billing raw card details
* requires PCI compliance on your end</b>; these examples are provided as guidance. If your business
* is not PCI compliant, we recommend using Chargify.js to collect credit cards or bank accounts.
*
* # Subscription Customization
*
* ## With Components
*
* Different components require slightly different data. For example, quantity-based and on/off
* components accept `allocated_quantity`, while metered components accept `unit_balance`.
*
* When creating a subscription with a component, a `price_point_id` can be passed in along with the
* `component_id` to specify which price point to use. If not passed in, the default price point will
* be used.
*
* Note: if an invalid `price_point_id` is used, the subscription will still proceed but will use the
* component's default price point.
*
* Components and their price points may be added by ID or by handle. See the example request body
* labeled "Components By Handle (Quantity-Based)"; the format will be the same for other component
* types.
*
* ## With Coupon(s)
*
* Pass an array of `coupon_codes`. See the example request body "With Coupon".
*
* ## With Manual Invoice Collection
*
* The `invoice` collection method works only on legacy Statement Architecture.
*
* On Relationship Invoicing Architecture use the `remittance` collection method.
*
* ## Prepaid Subscription
*
* A prepaid subscription can be created with the usual subscription creation parameters, specifying
* `prepaid` as the `payment_collection_method` and including a nested `prepaid_configuration`.
*
* After a prepaid subscription has been created, additional funds can be manually added to the
* prepayment account through the [Create Prepayment Endpoint](https://developers.chargify.com/docs/api-
* docs/7ec482de77ba7-create-prepayment).
*
* Prepaid subscriptions do not work on legacy Statement Architecture.
*
* ## With Metafields
*
* Metafields can either attach to subscriptions or customers. Metafields are popuplated with the
* supplied metadata to the resource specified.
*
* If the metafield doesn't exist yet, it will be created on-the-fly.
*
* ## With Custom Pricing
*
* Custom pricing is pricing specific to the subscription in question.
* Create a subscription with custom pricing by passing pricing information instead of a price point.
* For a custom priced product, pass the custom_price object in place of `product_price_point_id`. For
* a custom priced component, pass the `custom_price` object within the component object.
* Custom prices and price points can exist in harmony on a subscription.
*
* # Passing Payment Information
*
* ## Subscription with Chargify.js token
*
* The `chargify_token` can be obtained using [Chargify.js](https://developers.chargify.
* com/docs/developer-docs/ZG9jOjE0NjAzNDI0-overview). The token represents payment profile attributes
* that were provided by the customer in their browser and stored at the payment gateway.
*
* The `payment_type` attribute may either be `credit_card` or `bank_account`, depending on the type of
* payment method being added. If a bank account is being passed, the payment attributes should be
* changed to `bank_account_attributes`.
*
* ```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"
* }
* }
* }
* ```
*
* ## Subscription with vault token
*
* If you already have a customer and card stored in your payment gateway, you may create a
* subscription with a `vault_token`. Providing the last_four, card type and expiration date will
* allow the card to be displayed properly in the Advanced Billing UI.
*
* ```json
* {
* "subscription": {
* "product_handle": "pro-plan",
* "customer_attributes": {
* "first_name": "Joe",
* "last_name": "Smith",
* "email": "j.smith@example.com"
* },
* "credit_card_attributes": {
* first_name: "Joe,
* last_name: "Smith",
* card_type: "visa",
* expiration_month: "05",
* expiration_year: "2025",
* last_four: "1234",
* vault_token: "12345abc",
* current_vault: "braintree_blue"
* }
* }
* ```
*
* ## Subscription with ACH as Payment Profile
*
* ```json
* {
* "subscription": {
* "product_handle": "gold-product",
* "customer_attributes": {
* "first_name": "Joe",
* "last_name": "Blow",
* "email": "joe@example.com",
* "zip": "02120",
* "state": "MA",
* "reference": "XYZ",
* "phone": "(617) 111 - 0000",
* "organization": "Acme",
* "country": "US",
* "city": "Boston",
* "address_2": null,
* "address": "123 Mass Ave."
* },
* "bank_account_attributes": {
* "bank_name": "Best Bank",
* "bank_routing_number": "021000089",
* "bank_account_number": "111111111111",
* "bank_account_type": "checking",
* "bank_account_holder_type": "business",
* "payment_type": "bank_account"
* }
* }
* }
* ```
*
* ## Subscription with PayPal payment profile
*
* ### With the nonce from Braintree JS
*
* ```json
* { "subscription": {
* "product_handle":"test-product-b",
* "customer_attributes": {
* "first_name":"Amelia",
* "last_name":"Johnson",
* "email":"amelia@example.com",
* "organization":"My Awesome Company"
* },
* "payment_profile_attributes":{
* "paypal_email": "amelia@example.com",
* "current_vault": "braintree_blue",
* "payment_method_nonce":"abc123",
* "payment_type":"paypal_account"
* }
* }
* ```
*
*
* ### With the Braintree Customer ID as the vault token:
*
* ```json
* { "subscription": {
* "product_handle":"test-product-b",
* "customer_attributes": {
* "first_name":"Amelia",
* "last_name":"Johnson",
* "email":"amelia@example.com",
* "organization":"My Awesome Company"
* },
* "payment_profile_attributes":{
* "paypal_email": "amelia@example.com",
* "current_vault": "braintree_blue",
* "vault_token":"58271347",
* "payment_type":"paypal_account"
* }
* }
* ```
*
* ## Subscription using GoCardless Bank Number
*
* These examples creates a customer, bank account and mandate in GoCardless.
*
* For more information on GoCardless, please view the following two resources:
*
* + [Payment Profiles via API for GoCardless](https://developers.chargify.com/docs/api-
* docs/1f10a4f170405-create-payment-profile#gocardless)
* + [Full documentation on GoCardless](https://maxio.zendesk.com/hc/en-us/articles/24176159136909-
* GoCardless)
*
* + [Using Chargify.js with GoCardless - minimal example](https://developers.chargify.
* com/docs/developer-docs/ZG9jOjE0NjAzNDIy-examples#minimal-example-with-direct-debit-gocardless-
* gateway)
*
* + [Using Chargify.js with GoCardless - full example](https://developers.chargify.com/docs/developer-
* docs/ZG9jOjE0NjAzNDIy-examples#full-example-with-direct-debit-gocardless-gateway)
*
* ```json
* {
* "subscription": {
* "product_handle": "gold-product",
* "customer_attributes": {
* "first_name": "Jane",
* "last_name": "Doe",
* "email": "jd@chargify.test"
* },
* "bank_account_attributes": {
* "bank_name": "Royal Bank of France",
* "bank_account_number": "0000000",
* "bank_routing_number": "0003",
* "bank_branch_code": "00006",
* "payment_type": "bank_account",
* "billing_address": "20 Place de la Gare",
* "billing_city": "Colombes",
* "billing_state": "Île-de-France",
* "billing_zip": "92700",
* "billing_country": "FR"
* }
* }
* }
* ```
*
* ## Subscription using GoCardless IBAN Number
*
* ```json
* {
* "subscription": {
* "product_handle": "gold-product",
* "customer_attributes": {
* "first_name": "Jane",
* "last_name": "Doe",
* "email": "jd@chargify.test"
* },
* "bank_account_attributes": {
* "bank_name": "French Bank",
* "bank_iban": "FR1420041010050500013M02606",
* "payment_type": "bank_account",
* "billing_address": "20 Place de la Gare",
* "billing_city": "Colombes",
* "billing_state": "Île-de-France",
* "billing_zip": "92700",
* "billing_country": "FR"
* }
* }
* }
* ```
*
* ## Subscription using Stripe SEPA Direct Debit
*
* For more information on Stripe Direct Debit, please view the following two resources:
*
* + [Payment Profiles via API for Stripe SEPA Direct Debit](https://developers.chargify.com/docs/api-
* docs/1f10a4f170405-create-payment-profile#sepa-direct-debit)
* + [Full documentation on Stripe Direct Debit](https://maxio.zendesk.com/hc/en-
* us/articles/24176170430093-Stripe-SEPA-and-BECS-Direct-Debit)
*
* + [Using Chargify.js with Stripe SEPA or BECS Direct Debit - minimal example](https://developers.
* chargify.com/docs/developer-docs/ZG9jOjE0NjAzNDIy-examples#minimal-example-with-sepa-or-becs-direct-
* debit-stripe-gateway)
*
* + [Using Chargify.js with Stripe SEPA Direct Debit - full example](https://developers.chargify.
* com/docs/developer-docs/ZG9jOjE0NjAzNDIy-examples#full-example-with-sepa-direct-debit-stripe-
* gateway)
*
*
* ```json
* {
* "subscription": {
* "product_handle": "gold-product",
* "customer_attributes": {
* "first_name": "Jane",
* "last_name": "Doe",
* "email": "jd@chargify.test"
* },
* "bank_account_attributes": {
* "bank_name": "Test Bank",
* "bank_iban": "DE89370400440532013000",
* "payment_type": "bank_account"
* }
* }
* }
* ```
*
* ## Subscription using Stripe BECS Direct Debit
*
* For more information on Stripe Direct Debit, please view the following two resources:
*
* + [Payment Profiles via API for Stripe BECS Direct
* Debit]($e/Payment%20Profiles/createPaymentProfile)
* + [Full documentation on Stripe Direct Debit](https://maxio.zendesk.com/hc/en-
* us/articles/24176170430093-Stripe-SEPA-and-BECS-Direct-Debit)
*
* + [Using Chargify.js with Stripe SEPA, BECS or BACS Direct Debit - minimal example](page:development-
* tools/chargify-js/examples#minimal-example-with-sepa-becs-or-bacs-direct-debit-stripe-gateway)
*
* + [Using Chargify.js with Stripe BECS Direct Debit - full example](page:development-tools/chargify-
* js/examples#full-example-with-becs-direct-debit-stripe-gateway)
*
*
* ```json
* {
* "subscription": {
* "product_handle": "gold-product",
* "customer_attributes": {
* "first_name": "Jane",
* "last_name": "Doe",
* "email": "jd@chargify.test"
* },
* "bank_account_attributes": {
* "bank_name": "Test Bank",
* "bank_branch_code": "000000",
* "bank_account_number": "000123456",
* "payment_type": "bank_account"
* }
* }
* }
* ```
*
* ## Subscription using Stripe BACS Direct Debit
*
* For more information on Stripe Direct Debit, please view the following two resources:
*
* + [Payment Profiles via API for Stripe BACS Direct
* Debit]($e/Payment%20Profiles/createPaymentProfile)
* + [Full documentation on Stripe Direct Debit](https://maxio.zendesk.com/hc/en-
* us/articles/24176170430093-Stripe-SEPA-and-BECS-Direct-Debit)
*
* + [Using Chargify.js with Stripe SEPA, BECS or BACS Direct Debit - minimal example](page:development-
* tools/chargify-js/examples#minimal-example-with-sepa-becs-or-bacs-direct-debit-stripe-gateway)
*
* + [Using Chargify.js with Stripe BACS Direct Debit - full example](page:development-tools/chargify-
* js/examples#full-example-with-bacs-direct-debit-stripe-gateway)
*
* ```json
* {
* "subscription": {
* "product_handle": "gold-product",
* "customer_attributes": {
* "first_name": "Jane",
* "last_name": "Doe",
* "email": "jd@chargify.test"
* },
* "bank_account_attributes": {
* "bank_name": "Test Bank",
* "bank_branch_code": "108800",
* "bank_account_number": "00012345",
* "payment_type": "bank_account",
* "billing_address": "123 Main St.",
* "billing_city": "London",
* "billing_state": "LND",
* "billing_zip": "W1A 1AA",
* "billing_country": "GB"
* }
* }
* }
* ```
*
* ## 3D Secure - Stripe
*
* It may happen that a payment needs 3D Secure Authentication when the subscription is created; this
* is referred to in our help docs as 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`
*
* ## 3D Secure - Checkout
*
* It may happen that a payment needs 3D Secure Authentication when the subscription is created; this
* is referred to in our help docs as 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": "pay_6gjofv7dlyrkpizlolsuspvtiu",
* "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/pay_6gjofv7dlyrkpizlolsuspvtiu?
* one_time_token_id=123&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://mysite.chargify.com/3d-secure/pay_6gjofv7dlyrkpizlolsuspvtiu?
* one_time_token_id=123"
* }
* ```
*
* 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` parameter 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 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/pay_6gjofv7dlyrkpizlolsuspvtiu?
* one_time_token_id=123&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 their SCA was performed
* successfully. Here's an example flow to use as a reference:
*
* 1. Create a subscription 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
*
* ## Subscriptions Import
*
* Subscriptions can be “imported” via the API to handle the following scenarios:
*
* + You already have existing subscriptions with specific start and renewal dates that you would like
* to import to Advanced Billing
* + You already have credit cards stored in your provider’s vault and you would like to create
* subscriptions using those tokens
*
* Before importing, you should have already set up your products to match your offerings. Then, you
* can create Subscriptions via the API just like you normally would, but using a few special
* attributes.
*
* Full documentation on how import Subscriptions using the **import tool** in the Advanced Billing UI
* can be located [here](https://maxio.zendesk.com/hc/en-us/articles/24251489107213-Imports).
*
* ### Important Notices and Disclaimers regarding Imports
*
* Before performing a bulk import of subscriptions via the API, we suggest reading the [Subscriptions
* Import](https://maxio.zendesk.com/hc/en-us/articles/24251489107213-Imports) instructions to
* understand the repurcussions of a large import.
*
* ### Subscription Input Attributes
*
* The following _additional_ attributes to the subscription input attributes make imports possible:
* `next_billing_at`, `previous_billing_at`, and `import_mrr`.
*
* ### Current Vault
*
* If you are using a Legacy gateway such as "eWAY Rapid (Legacy)" or "Stripe (Legacy)" then please
* contact Support for further instructions on subscription imports.
*
* ### Braintree Blue (Braintree v2) Imports
*
* Braintree Blue is Braintree’s newer (version 2) API. For this gateway, please provide the
* `vault_token` parameter with the value from Braintree’s “Customer ID” rather than the “Payment
* Profile Token”. At this time we do not use `current_vault_token` with the Braintree Blue gateway,
* and we only support a single payment profile per Braintree Customer.
*
* When importing PayPal type payment profiles, please set `payment_type` to `paypal_account`.
*
* ### Stripe ACH Imports
*
* If the bank account has already been verified, currently you will need to create the customer,
* create the payment profile in Advanced Billing - setting verified=true, then create a subscription
* using the customer_id and payment_profile_id.
*
* ### Webhooks During Import
*
* If no `next_billing_at` is provided, webhooks will be fired as normal. If you do set a future
* `next_billing_at`, only a subset of the webhooks are fired when the subscription is created. Keep
* reading for more information as to what webhooks will be fired under which scenarios.
*
* #### Successful creation with Billing Date
*
* Scenario: If `next_billing_at` provided
*
* + `signup_success`
* + `billing_date_change`
*
* #### Successful creation without Billing Date
*
* Scenario: If no `next_billing_at` provided
*
* + `signup_success`
* + `payment_success`
*
* #### Unsuccessful creation
*
* Scenario: If card can’t be charged, and no `next_billing_at` provided
*
* + signup_failure
*
* #### Webhooks fired when next_billing_at is reached:
*
* + `renewal_success or renewal_failure`
* + `payment_success or payment_failure`
*
* ### Date and Time Formats
*
* We will attempt to parse any string you send as the value of next_billing_at in to a date or time.
* For best results, use a known format like described in “Date and Time Specification” of RFC 2822 or
* ISO 8601 .
*
* The following are all equivalent and will work as input to `next_billing_at`:
*
* ```
* Aug 06 2030 11:34:00 -0400
* Aug 06 2030 11:34 -0400
* 2030-08-06T11:34:00-04:00
* 8/6/2030 11:34:00 EDT
* 8/6/2030 8:34:00 PDT
* 2030-08-06T15:34:00Z
* ```
* You may also pass just a date, in which case we will assume the time to be noon
*
* ```
* 2010-08-06
* ```
*
* ## Subscription Hierarchies & WhoPays
*
* When subscription groups were first added to our Relationship Invoicing architecture, to group
* together invoices for related subscriptions and allow for complex customer hierarchies and WhoPays
* scenarios, they were designed to consist of a primary and a collection of group members. The primary
* would control many aspects of the group, such as when the consolidated invoice is generated. As of
* today, groups still function this way.
*
* In the future, the concept of a "primary" will be removed in order to offer more flexibility into
* group management and reduce confusion concerning what actions must be done on a primary level,
* rather than a member level.
*
* We have introduced a two scheme system as a bridge between these two group organizations. Scheme 1,
* which is relevant to all subscription groups today, marks the group as being "ruled" by a primary.
*
* When reading a subscription via API, they will return a top-level attribute called `group`, which
* will denote which scheme is being used. At this time, the `scheme` attribute will always be 1.
*
* ### Subscription in a Customer Hierarchy
*
* 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) features, it is
* possible to create subscriptions within a customer hierarchy. This can be achieved 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.
*
* When the `target` parameter specifies a customer that is already part of a hierarchy, the new
* subscription will become a member of the customer hierarchy as well. If the target customer is not
* part of a hierarchy, a new customer hierarchy will be created and both the target customer and the
* new subscription will become part of the hierarchy with the specified target customer set as the
* responsible payer for the hierarchy's subscriptions.
*
* 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. This will be true whether the customer is being created new, is already part
* of a hierarchy, or already exists outside a hierarchy. A valid payment method must also be
* specified in the subscription parameters.
*
* Note that when creating subscriptions in a customer hierarchy, if the customer hierarchy does not
* already have a payment method, passing valid credit card attributes in the subscription parameters
* will also result in the payment method being established as the default payment method for the
* customer hierarchy irrespective of the responsible payer.
*
* The optional `billing` parameters specify how some aspects of the billing for the new subscription
* should be handled. Rather than capturing payment immediately, the `accrue` parameter can be
* included so that the new subscription charges accrue until the next assessment date. Regarding the
* date, the `align_date` parameter can be included so that the billing date of the new subscription
* matches up with the default subscription group in the customer hierarchy. When choosing to align
* the dates, the `prorate` parameter can also be specified so that the new subscription charges are
* prorated based on the billing period of the default subscription group in the customer hierarchy
* also.
*
* ### 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) it may be desireable to create a
* subscription as part of a [subscription group](https://maxio.zendesk.com/hc/en-
* us/articles/24252172565005-Subscription-Groups-Overview) in order to rely on [invoice
* consolidation](https://maxio.zendesk.com/hc/en-us/articles/24252269909389-Invoice-Consolidation).
* This can be achieved 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 will
* become a member of the group as well. If the target subscription is not part of a group, a new
* group will be created and both the target and the new subscription will become part of the group
* with the target as the group's primary subscription.
*
* The optional `billing` parameters specify how some aspects of the billing for the new subscription
* should be handled. Rather than capturing payment immediately, the `accrue` parameter can be
* included so that the new subscription charges accrue until the next assessment date. Regarding the
* date, the `align_date` parameter can be included so that the billing date of the new subscription
* matches up with the target subscription. When choosing to align the dates, the `prorate` parameter
* can also be specified so that the new subscription charges are prorated based on the billing period
* of the target subscription also.
*
* ## Providing Agreement Acceptance Params
*
* It is possible to provide a proof of customer's acceptance of terms and policies.
* We will be storing this proof in case it might be required (i.e. chargeback).
* Currently, we already keep it for subscriptions created via Public Signup Pages.
* In order to create a subscription with the proof of agreement acceptance, you must provide
* additional parameters `agreement acceptance` with `ip_address` and at least one url to the policy
* that was accepted: `terms_url` or `privacy_policy_url`. Additional urls that can be provided:
* `return_refund_policy_url`, `delivery_policy_url` and
* `secure_checkout_policy_url`.
*
* ```json
* "subscription": {
* "product_handle": "gold-product",
* "customer_attributes": {
* "first_name": "Jane",
* "last_name": "Doe",
* "email": "jd@chargify.test"
* },
* "agreement_acceptance": {
* "ip_address": "1.2.3.4",
* "terms_url": "https://terms.url",
* "privacy_policy_url": "https://privacy_policy.url",
* "return_refund_policy_url": "https://return_refund_policy.url",
* "delivery_policy_url": "https://delivery_policy.url",
* "secure_checkout_policy_url": "https://secure_checkout_policy.url"
* }
* }
* }
* ```
*
* **For Maxio Payments subscriptions, the agreement acceptance params are required, with at least
* terms_url provided.**
*
* ## Providing ACH Agreement params
*
* It is also possible to provide a proof that a customer authorized ACH agreement terms.
* The proof will be stored and the email will be sent to the customer with a copy of the terms (if
* enabled).
* In order to create a subscription with the proof of authorized ACH agreement terms, you must provide
* the additional parameter `ach_agreement` with the following nested parameters: `agreement_terms`,
* `authorizer_first_name`, `authorizer_last_name` and `ip_address`.
* Each of them is required.
*
* ```json
* "subscription": {
* "product_handle": "gold-product",
* "customer_attributes": {
* "first_name": "Jane",
* "last_name": "Doe",
* "email": "jd@chargify.test"
* },
* "bank_account_attributes": {
* "bank_name": "Test Bank",
* "bank_routing_number": "021000089",
* "bank_account_number": "111111111111",
* "bank_account_type": "checking",
* "bank_account_holder_type": "business",
* "payment_type": "bank_account"
* },
* "ach_agreement": {
* "agreement_terms": "ACH agreement terms",
* "authorizer_first_name": "Jane",
* "authorizer_last_name": "Doe",
* "ip_address": "1.2.3.4"
* }
* }
* ```
*
* @param body
* @return Response from the API call
*/
async createSubscription(body, requestOptions) {
const req = this.createRequest('POST', '/subscriptions.json');
const mapped = req.prepareArgs({
body: [body, optional(createSubscriptionRequestSchema)],
});
req.header('Content-Type', 'application/json');
req.json(mapped.body);
req.throwOn(422, ErrorListResponseError, true, "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'.");
req.authenticate([{ basicAuth: true }]);
return req.callAsJson(subscriptionResponseSchema, requestOptions);
}
/**
* 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.
*
* @param page 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`.
* @param perPage 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`.
* @param state The current state of the subscription
* @param product The product id of the subscription. (Note that the
* product handle cannot be used.)
* @param productPricePointId The ID of the product price point. If supplied,
* product is required
* @param coupon 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.)
* @param couponCode The coupon code currently applied to the subscription
* @param dateField 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
* @param startDate 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`.
* @param endDate 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`.
* @param startDatetime 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`.
* @param endDatetime 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`.
* @param metadata The value of the metadata field specified in the
* parameter. Use in query `metadata[my-
* field]=value&metadata[other-field]=another_value`.
* @param direction Controls the order in which results are returned. Use
* in query `direction=asc`.
* @param sort The attribute by which to sort
* @param include Allows including additional data in the response. Use
* in query: `include[]=self_service_page_token`.
* @return Response from the API call
*/
async listSubscriptions({ page, perPage, state, product, productPricePointId, coupon, couponCode, dateField, startDate, endDate, startDatetime, endDatetime, metadata, direction, sort, include, }, requestOptions) {
const req = this.createRequest('GET', '/subscriptions.json');
const mapped = req.prepareArgs({
page: [page, optional(number())],
perPage: [perPage, optional(number())],
state: [state, optional(subscriptionStateFilterSchema)],
product: [product, optional(number())],
productPricePointId: [productPricePointId, optional(number())],
coupon: [coupon, optional(number())],
couponCode: [couponCode, optional(string())],
dateField: [dateField, optional(subscriptionDateFieldSchema)],
startDate: [startDate, optional(string())],
endDate: [endDate, optional(string())],
startDatetime: [startDatetime, optional(string())],
endDatetime: [endDatetime, optional(string())],
metadata: [metadata, optional(dict(string()))],
direction: [direction, optional(sortingDirectionSchema)],
sort: [sort, optional(subscriptionSortSchema)],
include: [include, optional(array(subscriptionListIncludeSchema))],
});
req.query('page', mapped.page, unindexedPrefix);
req.query('per_page', mapped.perPage, unindexedPrefix);
req.query('state', mapped.state, unindexedPrefix);
req.query('product', mapped.product, unindexedPrefix);
r