API v2 Release Notes

Our release notes outline changes between various API versions to help our merchants better integrate with our API service.

2.29 Release Notes

Request and Response changes:

• Changed POST v2/coupons request:
  • Added optional <applies_to_all_items>boolean and <item_codes> array fields
• Changed POST v2/coupons response:
  • Added <applies_to_all_items> boolean and <item_codes> array fields
• Changed GET v2/coupons response:
  • Same changes as POST v2/coupons response
• Changed GET v2/coupons/{coupon_code} response:
  • Same changes as POST v2/coupons response
• Changed PUT v2/coupons/{coupon_code} response:
  • Same changes as POST v2/coupons response
• Changed PUT v2/coupons/{coupon_code}/restore response:
  • Same changes as POST v2/coupons response
• Changed PUT v2/coupons/{coupon_code}/unique_coupon_codes response:
  • Same changes as POST v2/coupons response

v2.27 Release Notes

Request and Response changes:

• Changed POST v2/items request:
  • With an Avalara for Communications integration active on the site
    • Added required <avalara_transaction_type> and <avalara_service_type> integer fields
• Changed POST v2/items response:
  • With an Avalara for Communications integration active on the site
    • Added <avalara_transaction_type> and <avalara_service_type> integer elements
• Changed PUT v2/items/{item_id} request:
  • Same changes as POST v2/items request.
• Changed PUT v2/items/{item_id} response:
  • Same changes as POST v2/items response.
• Changed GET v2/items response:
  • Same changes as POST v2/items response.
• Changed GET v2/items/{item_id} response:
  • Same changes as POST v2/items response.
• Changed POST v2/plans request:
  • Added optional <allow_any_item_on_subscriptions> field. Requires the add_items_on_subs feature flag be enabled on the site.
  • <allow_any_item_on_subscriptions> will default to false
  • With an Avalara for Communications integration active on the site
    • Added required <avalara_transaction_type> and <avalara_service_type> integer elements
• Changed POST v2/plans response:
  • With the add_items_on_subs feature flag enabled on the site
    • Added <allow_any_item_on_subscriptions>
  • With an Avalara for Communications integration active on the site
    • Added <avalara_transaction_type> and <avalara_service_type> integer elements
• Changed GET v2/plans response:
  • For each plan, follows the same changes as POST v2/plans response.
• Changed GET v2/plans/{plan_id} response:
  • Same changes as POST v2/plans response.
• Changed PUT v2/plans/{plan_id} request:
  • Same changes as POST v2/plans request.
• Changed PUT v2/plans/{plan_id} response:
  • Same changes as POST v2/plans response.
• Changed POST v2/plans/{plan_id}/add_ons request:
  • With an Avalara for Communications integration active on the site
    • Added required <avalara_transaction_type> and <avalara_service_type> integer elements
• Changed POST v2/plans/{plan_id}/add_ons response:
  • With an Avalara for Communications integration active on the site
    • Added <avalara_transaction_type> and <avalara_service_type> integer elements
• Changed PUT v2/plans/{plan_id}/add_ons/{add_on_id} request:
  • Same changes as POST v2/plans/{plan_id}/add_ons request.
• Changed PUT v2/plans/{plan_id}/add_ons/{add_on_id} response:
  • Same changes as POST v2/plans/{plan_id}/add_ons response.
• Changed GET v2/plans/{plan_id}/add_ons response:
  • Same changes as POST v2/plans/{plan_id}/add_ons response.
• Changed GET v2/plans/{plan_id}/add_ons/{add_on_id} response:
  • Same changes as POST v2/plans/{plan_id}/add_ons response.
• Changed GET v2/subscriptions response:
  • With the add_items_on_subs feature flag enabled on the site, <subscription_add_on>s have:
    • Added <add_on_source>
• Changed POST v2/subscriptions request:
  • With the add_items_on_subs feature flag enabled on the site, <subscription_add_on>s have:
    • Added optional <add_on_source> field.
    • <add_on_source> will default to plan_add_on but can also be set to item if a subscription’s plan has the <allow_any_item_on_subscriptions> field set to true.
    • <add_on_code> will mimic the existing behavior when <add_on_source> is set to plan_add_on
    • If <add_on_source> is set to item then <add_on_code> will need to be an item_code for an item in your item catalog
• Changed POST v2/subscriptions response:
  • Same changes as GET v2/subscriptions response.
• Changed POST v2/subscriptions/preview request:
  • Same changes as POST v2/subscriptions request
• Changed POST v2/subscriptions/preview response:
  • Same changes as GET v2/subscriptions response.
• Changed PUT v2/subscriptions/{subscription_uuid} request:
  • Same changes as POST v2/subscriptions request
• Changed PUT v2/subscriptions/{subscription_uuid} response:
  • Same changes as GET v2/subscriptions response.
• Changed PUT v2/subscriptions/{subscription_uuid}/preview request:
  • Same changes as POST v2/subscriptions request
• Changed PUT v2/subscriptions/{subscription_uuid}/preview response:
  • Same changes as GET v2/subscriptions response.
• Changed GET v2/subscriptions/{subscription_uuid} response:
  • Same changes as GET v2/subscriptions response.
• Changed POST v2/purchases/create request:
  • With the add_items_on_subs feature flag enabled on the site:
    • Added optional <add_on_source> field to <subscription_add_ons>.
    • <add_on_source> will default to plan_add_on but can also be set to item if a subscription’s plan has the <allow_any_item_on_subscriptions> field set to true.
    • <add_on_code> will mimic the existing behavior when <add_on_source> is set to plan_add_on.
  • With an Avalara for Communications integration active on the site
    • Added required <avalara_transaction_type> and <avalara_service_type> integer elements for the <adjustment> array elements
• Changed POST v2/purchases/preview request:
  • Same changes as POST v2/purchases/create.
• Changed POST v2/accounts/{account_id}/adjustments request:
  • With an Avalara for Communications integration active on the site
    • Added required <avalara_transaction_type> and <avalara_service_type> integer elements
• Changed POST v2/transactions request:
  • Same changes as POST v2/accounts/{account_id}/adjustments.
• Changed POST v2/accounts/{account_id}/adjustments response:
  • With an Avalara for Communications integration active on the site
    • Added <avalara_transaction_type> and <avalara_service_type> integer elements
• Changed GET v2/accounts/{account_id}/adjustments response:
  • Same changes as POST v2/accounts/{account_id}/adjustments response.
• Changed GET v2/accounts/{account_id}/adjustments/{adjustment_id} response:
  • Same changes as POST v2/accounts/{account_id}/adjustments response.
  • If the invoice has tax from Avalara for Communications
    • Added the following fields to the <tax_detail> array element
      • <level>, string enum, the level the tax applies at. Can be state, federal, county, city or unincorporated
      • <billable>, boolean, tax is billable?
• Changed GET v2/invoices/{invoice_id}/adjustments response:
  • Same changes as POST v2/accounts/{account_id}/adjustments response.
• Changed GET v2/invoices/{invoice_id}/adjustments/{adjustment_id} response:
  • Same changes as POST v2/accounts/{account_id}/adjustments response.
  • Same changes as GET v2/accounts/{account_id}/adjustments/{adjustment_id} response.
• Changed GET v2/invoices response:
  • If the invoice has tax from Avalara for Communications
    • Added the <tax_details> array with the following <tax_detail> array elements properties:
      • <name>, string, is the tax name
      • <type>, string, is the tax type/category
      • <tax_rate>, float, is the tax rate
      • <tax_in_cents>, integer, is the total amount charged for this tax type
      • <level>, string enum, the level the tax applies at. Can be state, federal, county, city or unincorporated
• Changed GET v2/accounts/{account_id}/invoices response:
  • Same changes as GET v2/invoices response.
• Changed GET v2/invoices/{invoice_id} response:
  • Same changes as GET v2/invoices response.
• Changed POST v2/accounts/{account_id}/invoices/preview response:
  • Same changes as GET v2/invoices response.
• Changed POST v2/accounts/{account_id}/invoices response:
  • Same changes as GET v2/invoices response.

v2.26 Release Notes

Request and Response changes:

• Changed POST v2/plans/{plan_id}/add_ons request:
  • Added optional <tier_type> field and <tiers> array. Requires the subscription_terms feature flag be enabled on the site.
  • <tier_type> will default to flat but can also be set to tiered, volume, or stairstep
  • <tiers> must be populated by one or more <tier> fields. <tiers> cannot be present if <tier_type> is flat.
    • <unit_amount_in_cents> is required within a <tier>.
    • <ending_quantity> is optional within a <tier> and will default to 999999999, the maximum, if no value is given. The minimum is 1.
      • There must be a <tier> with the default ending_quantity, 999999999.
      • When the provided <tier>s are ordered by the <ending_quantity>, the first <tier> has an implicit starting quantity of 1, and each subsequent tier begins after the <ending_quantity> of the previous <tier>.
  • <unit_amount_in_cents> will not be accepted as a parameter on an Add On with tiers.
• Changed POST v2/plans/{plan_id}/add_ons response:
  • With the subscription_terms feature flag enabled on the site
    • Added <tier_type>
    • Added <tiers> when <tier_type> is not flat which will contain at least one <tier>.
    • The following fields are returned in a <tier> object:
      • <ending_quantity>
      • <unit_amount_in_cents>
    • unit_amount_in_cents> will not be returned on an <add_on> with <tiers>.
• Changed PUT v2/plans/{plan_id}/add_ons/{add_on_code} request:
  • With the subscription_terms feature flag enabled on the site:
    • <tier_type> is optional but cannot change from when the Add On was created.
    • <tiers> is optional and overrides existing tiers when present. Follows the same rules as POST v2/plans/{plan_id}/add_ons request.
    • unit_amount_in_cents> will not be returned on an <add_on> with <tiers>.
• Changed PUT v2/plans/{plan_id}/add_ons/{add_on_code} response:
  • Same changes as POST v2/plans/{plan_id}/add_ons response.
• Changed GET v2/plans/{plan_id}/add_ons response:
  • For each add_on, follows the same changes as POST v2/plans/{plan_id}/add_ons response.
• Changed GET v2/plans/{plan_id}/add_ons/{add_on_code} response:
  • Same changes as POST v2/plans/{plan_id}/add_ons response.
• Changed GET v2/subscriptions response:
  • With the subscription_terms feature flag enabled on the site, <subscription_add_on>s have:
    • Added <tier_type>.
    • Added <tiers> when <tier_type> is not flat which will contain at least one <tier>.
    • The following fields are returned in a <tier> object:
      • <ending_quantity>
      • <unit_amount_in_cents>
• Changed POST v2/subscriptions request:
  • Added the following to <subscription_add_on>:
    • Added optional <tiers> array. Requires the subscription_terms feature flag be enabled on the site.
    • <tiers> should be populated by one or more <tier> fields.
    • <unit_amount_in_cents> is required within a <tier>.
    • <ending_quantity> is optional within a <tier> and has a minimum value of 1. Will default to 999999999 if no value is given.
• Changed POST v2/subscriptions response:
  • Same changes as GET v2/subscriptions response.
• Changed POST v2/subscriptions/preview request:
  • Same changes as POST v2/subscriptions request
• Changed POST v2/subscriptions/preview response:
  • Same changes as GET v2/subscriptions response.
• Changed PUT v2/subscriptions/{subscription_uuid} request:
  • Same changes as POST v2/subscriptions request
• Changed PUT v2/subscriptions/{subscription_uuid} response:
  • Same changes as GET v2/subscriptions response.
• Changed PUT v2/subscriptions/{subscription_uuid}/preview request:
  • Same changes as POST v2/subscriptions request
• Changed PUT v2/subscriptions/{subscription_uuid}/preview response:
  • Same changes as GET v2/subscriptions response.
• Changed GET v2/subscriptions/{subscription_uuid} response:
  • Same changes as GET v2/subscriptions response.
• Changed POST v2/purchases request:
  • Added the following to <subscription_add_on>:
    • Added optional <tiers> array. Requires the subscription_terms feature flag be enabled on the site.
    • <tiers> should be populated by one or more <tier> fields.
    • <unit_amount_in_cents> is required within a <tier>.
    • <ending_quantity> is optional within a <tier> and has a minimum value of 1. Will default to 999999999 if no value is given.
• Changed POST v2/purchases/preview request:
  • Same changes as POST v2/purchases request
• Changed GET v2/subscriptions/{subscription_id}/add_ons/{add_on_code}/usage response:
  • Added <tier_type>.
  • Added <tiers> when <tier_type> is not flat which will contain at least one <tier>.
  • The following fields are returned in a <tier> object:
    • <ending_quantity>
    • <unit_amount_in_cents>
• Changed GET v2/subscriptions/{subscription_id}/add_ons/{add_on_code}/usage/{usage_id} response:
  • Same changes as GET v2/subscriptions/{subscription_id}/add_ons/{add_on_code}/usage response
• Changed POST v2/subscriptions/{subscription_id}/add_ons/{add_on_code}/usage response:
  • Same changes as GET v2/subscriptions/{subscription_id}/add_ons/{add_on_code}/usage response
• Changed PUT v2/subscriptions/{subscription_id}/add_ons/{add_on_code}/usage/{usage_id} response:
  • Same changes as GET v2/subscriptions/{subscription_id}/add_ons/{add_on_code}/usage response
• Changed DELETE v2/subscriptions/{subscription_id}/add_ons/{add_on_code}/usage/{usage_id} response:
  • Same changes as GET v2/subscriptions/{subscription_id}/add_ons/{add_on_code}/usage response

v2.25 Release Notes

Request and Response changes:

• Added PUT /v2/subscriptions/:uuid/convert_trial
  • description: Immediately convert a subscription’s trial, putting the subscription into a fully active state. Produces an invoice and attempts collection on the invoice for auto collecting subscriptions.
• Changed POST v2/plans/{plan_id}/add_ons request:
• Added optional <item_code> field. Requires the catalog_item_addons feature flag be enabled on the site. item_code must be unique within the Add On. <item_code>must be a valid and active Item.
• The following fields must be absent when <item_code> is present: <add_on_code>, <name>, <add_on_type>, <accounting_code>, <revenue_schedule_type>, <tax_code>, <measured_unit_id>, <usage_type>, <usage_percentage> <unit_amount_in_cents> is now optional if <item_code> is present and the item has default pricing.
• Changed POST v2/plans/{plan_id}/add_ons response:
• For an Add On created using an Item:
  • Added <item> resource link.
  • Added <external_sku>.
  • Added <item_state>.
• Changed GET v2/plans/{plan_id}/add_ons/{add_on_code} response:
  • For an Add On created using an Item:
    • Added <item> resource link.
    • Added <external_sku>.
    • Added <item_state>.
• Changed PUT v2/plans/{plan_id}/add_ons/{add_on_code} request:
  • The following fields must be absent when the Add On has an associated Item: <add_on_code>, <name>, <add_on_type>, <accounting_code>, <revenue_schedule_type>, <tax_code>, <measured_unit_id>, <usage_type>, <usage_percentage>
• Changed PUT v2/plans/{plan_id}/add_ons/{add_on_code} response:
  • For an Add On created using an Item:
    • Added <item> resource link.
    • Added <external_sku>.
    • Added <item_state>.
• Changed POST v2/subscriptions response:
  • For an Subscription created using an Item-backed Add On:
    • Added <item> resource link.
    • Added <external_sku>.
• Changed POST v2/subscriptions/preview response:
  • For a pending Subscription using an Item-backed Add On:
    • Added <item> resource link.
    • Added <external_sku>.
• Changed PUT v2/subscriptions response:
  • For a Subscription updated with an Item-backed Add On:
    • Added <item> resource link.
    • Added <external_sku>.
• Changed GET v2/subscriptions response:
  • For Subscriptions with an Item-backed Add On:
    • Added <item> resource link.
    • Added <external_sku>.
• Changed GET v2/subscriptions/{subscription_uuid} response:
  • For a Subscription with an Item-backed Add On:
    • Added <item> resource link.
    • Added <external_sku>.

v2.24 Release Notes

Item Catalog changes:

• Added GET /v2/items
  • description: A list of a site’s items. Requires the catalog feature be enabled on the site.
• Added GET /v2/items/:code
  • description: An item’s details. Requires the catalog feature be enabled on the site.
• Added POST /v2/items
  • description: Create an item. Requires the catalog feature be enabled on the site.
• Added PUT /v2/items/:item_code
  • description: Update an existing item. Requires the catalog feature be enabled on the site.
• Added DELETE /v2/items/:item_code
  • description: Deactivate an existing active item. Requires the catalog feature be enabled on the site.
• Added PUT /v2/items/:item_code/reactivate
  • description: Reactivate an existing inactive item. Requires the catalog feature be enabled on the site.
• Changed Adjustment request format:
  • Added optional <item_code> field.
    • description: Associates the adjustment with an item and sets related attributes on the adjustment from the default values on the item. <description>, <product_code>, <accounting_code>, <tax_exempt> and <tax_code> are not accepted when <item_code> is present.
• Changed Adjustment response format:
  • Added <item_code> field.
    • description: The item_code for the item associated with the adjustment, if there is one.
  • Added <item> link.
    • description: If there is an item associated with the adjustment, a link to the resource will be included in the response.
• Changed Purchases request format for <adjustment> field:
  • Added optional <item_code> field.
    • description: Associates the adjustment with an item and sets related attributes on the adjustment from the default values on the item. <description>, <product_code>, <accounting_code>, <tax_exempt> and <tax_code> are not accepted when <item_code> is present.
• Changed Purchases response format for <adjustment> field:
  • Added <item_code> field.
    • description: The item_code for the item associated with the adjustment, if there is one.
  • Added <item> link.
    • description: If there is an item associated with the adjustment, a link to the resource will be included in the response.

Request and Response changes:

• Changed Adjustment response format
  • Removed <taxable> tag.
• Changed subscription cancel request format
  • Added optional timeframe url parameter
    • description: The timeframe parameter accepts bill_date and term_end, with the former resulting in expiration of the subscription at the next billing event (at current_period_ends_at) regardless of the remaining length of the term. The latter results in the expiration of the subscription at the end of the subscription term (at current_term_ends_at).

v2.22 Release Notes

Request and Response changes:

• Changed Billing Info request format:
  • Added optional <transaction_type> tag.
    • description: Indicates type of resulting transaction
    • type: string(enum), accepted_values: “moto”
• Changed Account request format:
  • Added optional <transaction_type> tag.
    • description: Indicates type of resulting transaction
    • type: string(enum), accepted_values: “moto”
• Changed Subscription request format:
  • Added optional <transaction_type> tag.
    • description: Indicates type of resulting transaction
    • type: string(enum), accepted_values: “moto”
• Changed Subscription Change request format:
  • Added optional <transaction_type> tag.
    • description: Indicates type of resulting transaction
    • type: string(enum), accepted_values: “moto”
• Changed Purchase request format:
  • Added optional <transaction_type> tag.
    • description: Indicates type of resulting transaction
    • type: string(enum), accepted_values: “moto”
• Changed Invoice collect request format:
  • Added optional <transaction_type> tag.
    • description: Indicates type of resulting transaction
    • type: string(enum), accepted_values: “moto”

v2.21 Release Notes

• Changed <billing_info> request format:
  • Added <three_d_secure_action_result_token_id> tag. Used to indicate the three_d_secure_action_result_token returned by RJS for 3DS2.
• Changed transaction error response format:
  • Added <three_d_secure_action_token_id> tag. Used to indicate the three_d_secure_action_token that will be used to authenticate a transaction in order to resubmit the transaction.
• Changed token_invalid error response:
  • Response code is now 422

v2.20 Release Notes

• Changed Subscription request/response format
  • Added <shipping_amount_in_cents> tag to subscription xml. Optional field allows merchants to specify the shipping amount for a subscription.
  • Added <shipping_method_code> tag to subscription xml. Optional code allows merchant to track the shipping method used. Required if shipping_amount_in_cents is > 0.
• Changed Purchase request format:
  • Added optional <shipping_fees><shipping_fee> tags to charge shipping on one-time purchases. Accepts the following child tags:
  • <shipping_method_code> – Required, specifies shipping method used.
  • <shipping_amount_in_cents> - Required, specifies amount charged for shipping.
  • <shipping_address> - Optional, contains shipping address tags. You cannot provide both <shipping_address> and <shipping_address_id>.
  • <shipping_address_id> - Optional, id of existing shipping address. You cannot provide both <shipping_address> and <shipping_address_id>.
• Added GET /v2/shipping_methods
  • A list of a site’s shipping methods.
• Added GET /v2/shipping_methods/:code
  • A shipping method’s details.

v2.19 Release Notes

• Changed Account create request format:
  • Added <parent_account_code> field. Allows associating a new account to an existing account as its child.
• Changed Account update request format:
  • Added <parent_account_code> field. Allows associating an existing account to another existing account as its child. Sending an empty <parent_account_code> tag removes an associated parent account from an existing account.
• Changed Account response format:
  • Added <parent_account> field. Provides href of parent account show, if parent account exists.
  • Added <parent_account_code> field. Displays an account’s parent’s account_code.
  • Added <child_accounts> tag. Provides href of new endpoint accounts/:account_id/child_accounts for index of child accounts associated to the account being rendered, if one or more child accounts exists.
• Changed Invoice response format:
  • Added <parent_account> field. Provides href of parent account show, if parent account exists.
• Changed Subscription create request format:
  • Added <parent_account_code> field to account tag. Allows associating a new account to an existing account as its child. Sending an empty <parent_account_code> tag will remove an associated parent account from an existing account.
• Changed Subscription response format:
  • Added <parent_account> field. Provides href of parent account show, if parent account exists.
• Changed Purchases create request format:
  • Added <parent_account_code> field to account tag. Allows associating a new account to an existing account as its child. Sending an empty <parent_account_code> tag will remove an associated parent account from an existing account.
• Added GET /v2/accounts/:account_code/child_accounts. A list of an account’s child accounts.

v2.18 Release Notes

• Added <amazon_region> to billing info xml
  • Allow assignment of an amazon region to billing infos with amazon billing agreements. Must be one of the following: eu, us, or uk

v2.17 Release Notes

• Changed Account request/response:
  • Added <exemption_certificate> field. Allows merchants using the Vertex tax provider to associate an exemption certificate with the account to be included in any tax calculation requests for the account.
• Changed PUT /v2/subscriptions/:uuid/notes:
  • Added <gateway_code> tag to subscription xml. Allows subscription’s gateway_code to be immediately updated.
• Changed PUT /v2/invoices/:uuid:
  • Added <gateway_code> tag to invoice xml. Allows invoice’s gateway_code to be immediately updated.
• Changed POST v2/purchases request:
  • Allow starts_at to specify a future date when a subscription should start. Previous versions only allowed subscriptions to start immediately via this endpoint.

v2.16 Release Notes

Request and Response changes:

• Changed POST v2/purchases request:
  • Allow po_number when collection method is automatic and manual invoicing is enabled.
• Changed PUT /v2/accounts/:account_code/billing_info request:
  • Added support for updating billing info with a gateway code and token. Previous versions only allowed creating a new billing info, not updating existing billing info.
• Changed PUT /v2/accounts/:account_code/billing_info response:
  • Added <gateway_code> and (masked) <gateway_token> to response when updating a billing info with gateway code and token, so it maps to the request that was sent.

v2.15 Release Notes

Request and Response changes:

• Changed Account response:
  • Added <notes> href tag so client libraries have the link for listing account notes.
• Changed POST v2/accounts/:account_code/billing_info request
  • Added <card_type> String
• Changed POST v2/subscriptions request when including billing info
  • Added <card_type> String

v2.14 Release Notes

Request and Response changes:

• Changed Subscription create request format:
  • Added <next_bill_date> Datetime.
    • description: <first_renewal_date> is now deprecated. Use <next_bill_date> instead.
• Added PUT /v2/invoices/:invoice_number
  • description: If the Edit Invoice feature flag is enabled, several fields on invoices are editable. This includes customer_notes, and terms_and_conditions. vat_reverse_charge_notes can be edited only if the invoice already had reverse charge notes. po_number is editable except for credit invoices. name_on_account, first_name, last_name, company, and phone are editable on address. address1, address2, city, state, zip and country on address are also editable, if the invoice doesn’t have tax applied, and site doesn’t have taxes enabled. net_terms is editable, only for manual invoices in pending or past due states. Only the invoice and address fields (as listed above) in the request will be updated; fields not present in the request will not be updated, and their values will not change.
• Changed Invoice response
  • description: name_on_account, first_name, last_name, company will be returned within address.
• Changed PUT /v2/subscriptions/:uuid/notes
  • Added <custom_fields type="array"> so that the programmer can update custom fields without clearing pending subscription changes or reactivating the subscription.

v2.13 Release Notes

Request and Response changes:

• Changed Plan POST request/response
  • Added <auto_renew> Boolean default: true
• Changed Plan PUT request/response
  • Added <auto_renew> Boolean default: true
• Changed Subscription POST request/response
  • Added <auto_renew> Boolean default: true
  • Added <renewal_billing_cycles> Integer default: nil
• Changed Subscription response
  • Added <current_term_started_at> Datetime default: nil
  • Added <current_term_ends_at> Datetime default: nil
• Changed Shipping Address request/response XML:
  • Accept new attributes first_name and last_name for shipping addresses
  • Return new attributes first_name and last_name in address xml for addresses created using new attributes
• Changed Purchases POST response
  • Return new attributes name, first_name and last_name in line item address xml
• Changed Account, Subscription, and Purchase request/response
  • Added optional <custom_fields> list to account and subscription xml entities
    • path: <account><custom_fields><custom_field><name></name><value></value></custom_field></custom_fields></account>
    • path: <subscription><custom_fields><custom_field><name></name><value></value></custom_field></custom_fields></subscription>
    • path: <subscription><account><custom_fields><custom_field><name></name><value></value></custom_field></custom_fields></subscription>
    • path: <purchase><subscriptions><subscription><custom_fields><custom_field><name></name><value></value></custom_field></custom_fields></subscription></subscriptions></purchase>
    • path: <purchase><account><custom_fields><custom_field><name></name><value></value></custom_field></custom_fields></account></purchase>
    • description: Allows fetch, create, update, and delete of Custom Fields on Accounts and Subscriptions. Custom Field must be configured through the Admin UI before accessing them through the API. To create or update a custom field, add the name & new value to the <custom_fields></custom_fields> list. The field will be created if it does not exist yet. To delete a custom field, add the name & an empty value to the list: <custom_field><name>[name_of_existing_field]</name><value></value></custom_field> Existing values which are not present in the request will not be modified.
• Change Subscription PUT request/response
  • Added <auto_renew> and <renewal_billing_cycles>
• Change Plans PUT request/response
  • Modifying <plan_interval_unit> will result in an error: Plan interval unit cannot be edited once a plan is created.
  • Modifying <plan_interval_length> will result in an error: Plan interval length cannot be edited once a plan is created.

v2.12 Release Notes

Route changes:

• Added GET /v2/invoices/:invoice_number/transactions

Request and Response changes:

• Changed Account response
  • Added <all_transactions> href to list an invoices transactions if there are > 500 transactions on the invoice
• Changed Gift Card response
  • Added <redemption_invoice>
    • description: When a gift card is redemeed with the Credit Memos enabled, a credit invoice is created. A link to that credit invoice is returned in <redemption_invoice>
  • Renamed <invoice> to <purchase_invoice>

v2.11 Release Notes

Request and Response changes:

• Changed Account POST request/response
  • Added <preferred_locale>
• Changed Account PUT request/response
  • Added <preferred_locale>
• Changes POST /v2/purchases/ and POST /v2/purchases/preview requests
  • Added <shipping_address_id>
    • path: <purchase><shipping_address_id></shipping_address_id></purchase>
    • description: Adds support for referencing an existing account shipping addresses id for the purchase. This will apply to all subscriptions in the purchase unless those subscriptions have their own shipping addresses designated.
  • Added <shipping_address>
    • path: <account><shipping_address></shipping_address></account>
    • description: Adds support for creating new account shipping addresses. The last shipping_address tag will get applied to all the subscriptions and/or adjustments on the purchase unless those subscriptions and/or adjustments have their own shipping addresses designated.
  • Added <shipping_address_id>
    • path: <subscriptions><subscription><shipping_address_id></shipping_address_id></subscription></subscriptions>
    • description: Adds support for referencing an existing account shipping addresses id on the subscription
  • Added <shipping_address>
    • path: <subscriptions><subscription><shipping_address></shipping_address></subscription></subscriptions>
    • description: Adds support for creating new subscription shipping addresses
  • Added <shipping_address_id>
    • path: <adjustments><adjustment><shipping_address_id></shipping_address_id></subscription></adjustments>
    • description: Adds support for referencing an existing account shipping addresses id on an adjustment
  • Added <shipping_address>
    • path: <adjustments><adjustment><shipping_address></shipping_address></subscription></adjustments>
    • description: Adds support for creating new adjustment shipping addresses
• Changed GET /v2/adjustments/:adjustment_id
  • Added <shipping_address></shipping_address>
    • path: <adjustment><shipping_address></shipping_address></adjustment>
    • description: Adds shipping address info for an adjustment
• Changed GET /v2/invoices
  • Added <shipping_address>
    • path: <line_items><adjustment><shipping_address></shipping_address></adjustment></line_items>
    • description: Adds shipping address info for adjustments under invoices
• Changed GET /v2/invoices/:invoice_number
  • Added <shipping_address>
    • path: <line_items><adjustment><shipping_address></shipping_address></adjustment></line_items>
    • description: Adds shipping address info for adjustments under an invoice
• Added PUT /v2/subscriptions/:uuid/pause
  • description: Sets a subscription’s paused_at and remaining_pause_cycles attributes to facilitate the scheduling of a pause starting at the next billing cycle
• Added PUT /v2/subscriptions/:uuid/resume
  • description: Immediately resumes a paused subscription, applying any pending changes and producing an invoice
• Changed Subscription response
  • Added <state> value:
    • paused
• Changed Account request/response
  • Added <has_paused_subscription> element

v2.10 Release Notes

Route changes:

• Added GET /v2/credit_payments
• Added GET /v2/credit_payments/:uuid
• Added GET /v2/adjustments/:adjustment_id/credit_adjustments
• Added GET /v2/accounts/:account_code/credit_payments
• Added GET /v2/invoices/:invoice_number/original_invoices
• Added GET /v2/invoices/:invoice_number/credit_invoices
• Added PUT /v2/invoices/:invoice_number/void
  • description: Reduces a credit invoice’s balance to zero. The credit invoice’s state is set to voided (if it has a full balance) or closed (if it has a partial balance)
• Added POST /v2/accounts/:account_code/billing_info/verify_cvv
  • description: Verify a given CVV against an account’s billing info

Request and Response Changes:

• Changed POST /v2/invoices/:invoice_number/refund request
  • Added <credit_customer_notes> element if site has Credit Memos
    • description: Adds notes to refund credit invoice
  • Added <external_refund> element if site has Credit Memos
    • description: Allowed values are true or false and designates that the refund transactions created are manual
  • Added <payment_method> element if site has Credit Memos
    • description: Allowed if <external_refund> is true and creates the manual transactions with this payment method
  • Added <description> element if site has Credit Memos
    • description: Allowed if <external_refund> is true and sets this value as the transaction_note on the manual transactions created
  • Added <refunded_at> element if site has Credit Memos
    • description: Allowed if <external_refund> is true and sets this value as the collected_at on the manual transactions created
  • Replaced <refund_apply_order> with <refund_method>
    • description: Allowed values are credit_first or transaction_first without Credit Memos and additional accepted values of all_credit and all_transaction with Credit Memos
• Changes POST /v2/purchases/ request
  • Added <invoice_collection> element if site has Credit Memos
    • description: A list of invoices created by the invoicing service: charge_invoice and credit_invoices array
  • Added <credit_customer_notes> element if site has Credit Memos
    • description: Adds notes to custom credit invoice if generated
• Changed Subscription creation and preview POST request
  • Added <credit_customer_notes> element if site has Credit Memos
• Changed Subscription preview and preview_update POST request
  • Added <invoice_collection> element if site has Credit Memos
    • description: A list of invoices created by the invoicing service: charge_invoice and credit_invoices array
• Changed Invoice creation and preview POST request
  • Added <credit_customer_notes> element if site has Credit Memos
  • Added <type> element if site has Credit Memos
  • Added <origin> element if site has Credit Memos
  • Renamed <subtotal_in_cents> to <subtotal_before_discount_in_cents>
  • Renamed <subtotal_after_discount_in_cents> to <subtotal_in_cents>
  • Added <discount_in_cents>
  • Added <balance_in_cents> if site has Credit Memos
  • Added <due_on> element if site has Credit Memos
  • Added <type> element if site has Credit Memos
  • Added <origin> element if site has Credit Memos
  • Added <credit_invoices> reference link when site has Credit Memos and the invoice is a Charge Invoice
  • Added <original_invoices> reference link when site has Credit Memos and the invoice is a Credit Invoice
  • Added <invoice_collection> element if site has Credit Memos
    • description: A list of invoices created by the invoicing service: charge_invoice and credit_invoices array
• Changed GET /v2/invoices/:invoice_number
  • Added void action for voidable credit invoices, <a name="void" href="<domain>/v2/invoices/:invoice_number/void" method="put"/>
  • Added credit_payments
    • path: <credit_payments type="array"><credit_payment /></credit_payments>
    • description: A list of credit payments applied to the invoice
  • Changed <state> values
    • collected has changed to paid
    • open has changed to pending
• Changed Adjustments POST request/response
  • Added <credit_reason_code>
• Changed Adjustments GET response
  • Added reference to new credit_adjustments endpoint for adjustments of type charge
• Changed GET /v2/transactions
  • Added <reference>
    • path: <transactions><transaction><fraud_info><reference></reference></fraud_info></transaction></transactions>
    • description: Adds Kount reference ID for fraud details under transactions
• Changed GET /v2/transactions/:transaction_uuid
  • Added <reference>
    • path: <transaction><fraud_info><reference></reference></fraud_info></transaction>
    • description: Adds Kount reference ID for fraud details under a transaction

v2.9 Release Notes

Route changes:

• Added POST /v2/purchases/authorize

Request and Response Changes:

• Changed GET /v2/adjustments/:adjustment_id
  • Changed <subscription>
    • path: <subscription href=""></subscription>
    • description: tag is only returned if adjustment is originating from a subscription plan charge, setup fee, add on, trial or proration credit. It is no longer returned for other adjustments
  • Added <proration_rate>
    • path: <proration_rate type="float">0.500</proration_rate>
    • description: The proration rate is only present on prorated adjustments. It represents how much the adjustment was prorated to account for a mid cycle subscription change.
• Changed <invoice> and <transaction> responses
  • Removed deprecated singular <subscription> links. Now only plural <subscriptions> links are returned.
• Changed GET /v2/subscriptions and GET /v2/account/:account_code/subscriptions to accept a started_with_gift parameter. It can generate some slower queries so we’re going to leave it out of the public docs.

v2.8 Release Notes

Route changes:

• Added GET /v2/invoices/:invoice_number/subscriptions
• Added GET /v2/transactions/:transaction_id/subscriptions

Request and Response Changes:

• Changed POST /v2/accounts request:
  • Validates address.country, billing_info.country, and shipping_address.country for 2 letter ISO 3166 country code.
• Changed PUT /v2/accounts/:account_code request:
  • Validates address.country, billing_info.country, and shipping_address.country for 2 letter ISO 3166 country code.
• Changed POST /v2/subscriptions request:
  • Validates account.address.country, account.billing_info.country, account.shipping_addresses.shipping_address.country, and shipping_address.country for 2 letter ISO 3166 country code.
• Changed PUT /v2/subscriptions/:subscription_uuid request:
  • Validates shipping_address.country for 2 letter ISO 3166 country code.
• Changed PUT /v2/accounts/:account_code/billing_info request:
  • Validates country for 2 letter ISO 3166 country code.
• Changed POST /v2/accounts/:account_code/shipping_addresses/ request:
  • Validates country for 2 letter ISO 3166 country code.
• Changed PUT /v2/accounts/:account_code/shipping_addresses/:shipping_address_id request:
  • Validates country for 2 letter ISO 3166 country code.
• Changed POST /v2/gift_cards request:
  • Validates gifter_account.address.country, gifter_account.billing_info.address.country, gifter_account.shipping_addresses.country for 2 letter ISO 3166 country code.
• Added support for multiple subscriptions in POST /v2/purchases
• Added custom note support for POST /v2/purchases
  • Added <terms_and_conditions> element
  • Added <customer_notes> element
  • Added <vat_reverse_charge_notes> element
• Changed POST /v2/purchases request:
  • <currency> tag no longer allowed under <adjustment>. <currency> is an invoice level tag and is not permitted under an adjustment.
• Changed POST /v2/subscriptions and PUT /v2/subscriptions/:uuid request / GET /v2/subscriptions/:uuid response:
  • Added boolean <imported_trial> element
    • path: <subscription><imported_trial>true|false</imported_trial></subscription>
    • description: A boolean value that indicates if the subscription is to be treated as an import for data analysis or a real trial. This value can only be changed on a trial subscription and is persisted for its lifetime.
• Changed GET /v2/invoices/:invoice_number
  • Added <subscriptions>
    • path: <subscriptions href=""</subscriptions>
    • description: new subscriptions tag contains a link to new endpoint for subscriptions on an invoice (GET /v2/invoices/:invoice_number/subscriptions)
• Changed GET /v2/transactions/:transaction_id
  • Added <subscriptions>
    • path: <subscriptions href=""</subscriptions>
    • description: new subscriptions tag contains a link to new endpoint for subscriptions associated with a transaction (GET /v2/transactions/:transaction_id/subscriptions)

v2.7 Release Notes

Request and Response Changes:

• Changed POST /v2/purchases request:
  • Added coupon_codes
    • path: <coupon_codes type="array"><coupon_code>COUPON1234</coupon_code></coupon_codes>
    • description: A list of coupon codes to apply to this purchase.
  • Added subscriptions
    • path: <subscriptions type="array"><subscription/></subscriptions>
    • description: A list of Subscriptions to invoice in this purchase (currently only one subscription is allowed).
  • Added gift_card
    • path: <gift_card><redemption_code>ABCD1234</redemption_code></gift_card>
    • description: A gift card with a redemption code to apply to this purchase.

v2.6 Release Notes

Route changes:

Request and Response Changes:

• Changed Plan request/response:
  • Added <trial_requires_billing_info> element.
• Changed Subscription response:
  • Added <no_billing_info_reason> element.
• Added POST /v2/purchases
• Added POST /v2/purchases/preview
• Changed Subscription behavior
  • For POST /v2/subscriptions Sending NULL for total_billing_cycles attribute will now override plan total_billing_cycles setting and will make subscription renew forever. Omitting the attribute will cause the setting to default to the value of plan total_billing_cycles

v2.5 Release Notes

Route changes:

• Added PUT /v2/invoices/:invoice_number/collect

Request and Response Changes:

• Changed Subscription response:
  • Added <started_with_gift> element.
  • Added <converted_at> element.
• Changed Billing Info response:
  • Added <updated_at> element.
• Changed Coupon response:
  • Added <id> element.
• Changed Invoice response:
  • Added <subtotal_after_discount_in_cents> element.
  • Added <attempt_next_collection_at> element.
  • Added <recovery_reason> element.
  • Added <all_line_items> link when invoice response only shows first 500 line items.
• Changed Transaction response:
  • Added <gateway_type> element.
  • Added <origin> element.
  • Added <description> element.
  • Added <message> element.
  • Added <approval_code> element.
  • Added <collected_at> element.
• Changed Account response:
  • Added <has_live_subscription> element.
  • Added <has_active_subscription> element.
  • Added <has_future_subscription> element.
  • Added <has_canceled_subscription> element.
  • Added <has_past_due_invoice> element.
• Added GET /v2/invoices/:invoice_number/adjustments
• Changed Adjustment POST request:
  • Added <product_code> element.
• Changed Transactions POST request:
  • Added <product_code> element.
• Changed Invoice Preview POST request:
  • Added optional <currency> element. This change affects all versions of the API.
• Changed Invoice POST request:
  • Added optional <currency> element. This change affects all versions of the API.

v2.4 Release Notes

This release adds three new features:

• Gift cards
• Shipping addresses
• Marketing/CRM data

Route changes:

• Added POST /v2/gift_cards
• Added POST /v2/gift_cards/preview
• Added POST /v2/gift_cards/:redemption_code/redeem
• Added GET /v2/gift_cards
• Added GET /v2/gift_cards/:id
• Added GET /v2/accounts/:account_code/acquisition
• Added GET /v2/accounts/:account_code/shipping_addresses
• Added GET /v2/accounts/:account_code/shipping_addresses/:shipping_address_id
• Added GET /v2/accounts/:account_code/shipping_addresses/:shipping_address_id/subscriptions
• Added POST /v2/accounts/:account_code/shipping_addresses
• Added PUT /v2/accounts/:account_code/shipping_addresses/:shipping_address_id
• Added DELETE /v2/accounts/:account_code/shipping_addresses/:shipping_address_id
• Removed GET /v2/accounts/:account_code/subscription
• Removed POST /v2/accounts/:account_code/subscription
• Removed PUT /v2/accounts/:account_code/subscription
• Removed DELETE /v2/accounts/:account_code/subscription
• Added GET /v2/export_dates
• Added GET /v2/export_dates/:date/export_files
• Added GET /v2/export_dates/:date/export_files/:file

Request and Response Changes:

• Changed Account POST request:
  • Added <shipping_addresses> element.
• Changed Account response:
  • Added <account_acquisition> link element.
  • Added <shipping_addresses> link element.
• Changed Subscription request:
  • Added <shipping_address> element.
  • Added <shipping_address_id> element.
• Changed Subscription response:
  • Added <shipping_address> link element.
• Changed Transaction and BillingInfo responses:
  • Added <risk_rules_triggered> element to <fraud_info>
• Added Account Acquisition request and response.
• Changed Invoice response:
  • Added <shipping_address> element.
• Changed Address response:
  • Added <name> element.
• Added ExportDates, ExportDate, ExportFiles, ExportsFile responses.
• Changed Subscription Create and Preview POST requests:
  • Create route: POST /v2/subscriptions
  • Preview route: POST /v2/subscriptions/preview
  • Added optional <gift_card> block element for redeeming gift card as part of new subscription signup.

v2.3 Release Notes

This release added:

• Revenue schedules to several objects to enable Revenue Recognition.
• Sorting and date filtering to listing endpoints, see Pagination for details.
• The ability to check an account’s balance, see Lookup Account Balance for details.

Detailed listing of changes to requests and responses:

• Changed Account response:
  • Added <account_balance> link element.
• Changed Adjustment response:
  • Added <revenue_schedule_type> element.
• Changed Plan response:
  • Added <revenue_schedule_type> element.
  • Added <setup_fee_revenue_schedule_type> element.
• Changed Plan Add-On response:
  • Added <revenue_schedule_type> element.
• Changed Subscription response:
  • Added <revenue_schedule_type> element.
• Changed Subscription Add-On response:
  • Added <revenue_schedule_type> element.
• Changed Transaction response:
  • Added <original_transaction> link element.
• Added pagination options:
  • Added sort option: accepts created_at/updated_at, defaults to created_at.
  • Added order option: accepts desc/asc, defaults to desc.
  • Added begin_time/end_time options: accepts an ISO 8601 date or date and time.

A complete list of changes for all versions is available on the API Release Notes page.

v2.2 Release Notes

This release focused on supporting our new Usage-Based Billing feature.

Added endpoints for managing Measured Units:

• List Measured Units
• Create Measured Unit
• Lookup Measured Unit
• Update Measured Unit
• Delete Measured Unit

Added endpoints for managing Usage-Based Billing:

• List a Subscription Add-On’s Usage
• Log Usage
• Lookup Usage Record
• Update Usage Record
• Delete Usage Record

Detailed listing of changes to requests and responses:

• Changed Account response:
  • Added <updated_at> element.
• Changed Add-On response:
  • Added <measured_unit> link element.
  • Added <add_on_type> element.
  • Added <usage_type> element.
  • Added <usage_percentage> element.
  • Added <updated_at> element.
• Changed Adjustment response:
  • Added <updated_at> element.
• Changed Coupon response:
  • Added <updated_at> element.
• Changed Invoice response:
  • Added <updated_at> element.
• Changed Plan response:
  • Added <updated_at> element.
• Changed Redemption response:
  • Added <updated_at> element.
• Changed Subscription response:
  • Added the following to <subscription_add_on>:
    • <add_on_type> element.
    • <measured_unit> link element.
    • <usage> link element.
    • <unit_amount_in_cents> element.
  • Added <updated_at> element.
• Changed Transaction response:
  • Added <updated_at> element.

v2.1 Release Notes

This release is focused on adding better Coupon integration.

Added endpoints managing coupon redemptions:

• Lookup a Coupon Redemption on an Account
• Lookup a Coupon Redemption on an Invoice
• Lookup a Coupon Redemption on a Subscription
• Remove a Coupon Redemption from an Account

Added endpoint for creating bulk coupons:

• Generate Unique Codes

Detailed listing of changes to requests and responses:

• Changed Account, Invoice, and Subscription responses:
  • Added <redemptions> link element.
  • Removed <redemption> link, use <redemptions> instead.
• Changed Coupon response:
  • Added <bulk_coupon> link to unique coupon codes.
  • Added <redemption> link to unique coupon codes.
  • Added <unique_coupon_codes> link to bulk coupons.
• Changed Redemption response, added <subscription> link element.

v2.0 Release Notes

Initial release of 2.0.