Changelog
API ReferenceTheme Engine ReferenceRecharge Help CenterContact Us
Back to All

2021-11 API new version - release notes

almost 2 years ago by Diane Albouy

Our values

This new version of the API is the opportunity for us to formalise the values that guide us in building our API and our solutions at large. We are making those values public and will be maintaining them to reflect our ever growing investment and dedication to building resilient and consistent interfaces for our users.

Resources

We are actively investing in maintaining a documentation that can reflect the capabilities of our tooling.

Some resources to keep in mind:


What’s new in 2021-11

The 2021-11 version of the Recharge API includes improvements to most resources and endpoints. Here are 6 notable changes to keep in mind.

1. Global standards

Version 2021-11 includes many new global standards across all resources. This helps provide a consistent and intuitive experience for developers. Find out more in Recharge API Standards.

2. Products and Plans

  • We have rearchitected our Products resource and added a new Plans resource. We wanted to ensure that you continue to maintain your product catalog in a single system:
    • To that end, for merchants that use Shopify or BigCommerce as their PIM/OMS, Recharge automatically fetches the product catalog from those systems. This is how it has always worked and will continue to work with the new API version as well. There are no changes in behavior or functionality there.
    • However, we did rearchitect our Products resource to enable merchants that don’t use Shopify or BigCommerce to build an integration between Recharge and their PIM. This new resource, available exclusively to merchants doing a custom integration with their PIM system, enables merchants to send information regarding the Products they sell to Recharge.
  • The new Plan resource decouples the concept of “what you sell” from “how you sell it”. You can create and configure subscription, prepaid, and onetime purchase options for Products in Recharge using Plans. You can now create multiple Plans for a Product.
  • You probably already caught this, but the big difference between 2021-01 and 2021-11 is that Products in 2021-01 are now Plans in 2021-11.

3. Store


The Store resource replaces the Shop resource from 2021-01. It contains Recharge settings and other store-specific information.


4. Payment Methods


The new Payment Methods resource includes payment method information associated with customers. Each customer can have multiple payment methods.

  • You can associate a Payment method to an Address. Recharge will use this Payment method to process charges.
  • Note that we are actively rolling out support for this resource across all stores.
    • At this point, all new Shopify stores created after August 3, 2021 have access to the `Payment Method` resource.
    • Additionally, as we continue to roll out support across stores and platforms, it’s possible that your store already has access. However, if you notice a `You do not have sufficient permissions (scopes) for this object` error while trying to access this resource that means we haven’t rolled out Payment Methods on your store yet. If you would like immediate access to this resource, please reach out to Recharge Support.

5. Improved Pagination

  • List responses now contain in-body attributes indicating the cursor value for the next and previous pages of results.
  • This enables the implementation of more consistent and performant pagination without the need for parsing cursor headers or storing current page counts.

6. Token Information Resource

  • The Recharge API adds the ability to view the name and permission scopes of an API token without the need for UI.
  • Callers can see the contact information associated with their API token.

📘

Please see the detailed changelog for more information.


What else is coming in 2021-11

Here’s a non-exhaustive list of upcoming functionality in the works for version 2021-11.

  • The Collections resource will be available soon to enable the grouping and organizing of your products into collections in Recharge.
  • An improved Address Validation service is coming soon.
  • The Bulk Purchase Items resource will enable merchants to create, update, or delete many purchase items of various types (such as subscriptions and onetimes) in a single request. This resource will replace the subscriptions-bulk resource from version 2021-01.
  • The Async Batch resource will be available soon to enable processing large volumes of operations asynchronously.
  • The Accounts resource will allow callers to view accounts with access to their merchant admin portal, along with the permissions associated with each account.

Upgrading to the 2021-11 version


Since the 2021-11 version implements several new global standards, it is inherently a breaking change from the 2021-01 version.


The table below provides a high-level overview of the differences between the two versions. While you can use this as a guide, we highly encourage you to review the detailed changelog above before upgrading your i
implementation to the new version.


Resource / endpoint / attribute / feature2021-012021-11
GET /token_informationNot availableAvailable
Datetime fieldsAlways in ESTAlways in UTC using ISO-8601
Boolean valuesA mix of True, true, 1 and False, false, 0Always true or false. Stringified values are not supported
Null valuesVarying behavior across endpointsConsistent behavior across all resources and endpoints
Unrecognized or unsupported query parametersError responseSilently ignored
Date filtersInclusive or exclusive depending on the resourceAlways inclusive
Default sort on list endpointsVarying behavior across resourcesid-desc
Attribute namesVarying naming conventions across resourcesConsistent naming convention across resources
Amount fields regarding currency, such as product pricesRepresented by strings or numbersAlways represented by strings
External IDsRepresented by numbersAlways represented by strings
Page-based paginationSupportedNot supported
Cursor-based paginationNext and previous links included in the response headers. Users must parse header to extract cursor valueNext and previous cursors included in the response body as distinct key-value pairs
Count endpointsSupportedNot supported
GET /customers/:id/payment_sourcesSupportedUse GET /payment_methods instead
Setting payment methods on the customer objectSupportedUse POST or PUT /payment_methods instead
POST /orders/:id/change_dateSupportedUse PUT /orders instead
PUT /orders/:id/update_shopify_variant/:remote_variant_idSupportedUse PUT /orders instead
/productsAvailable across all platforms. Allows you to configure the product’s subscription options.Allows you to tell Recharge what you intend to sell. Only available for merchants doing a custom integration with a Product Information Management (PIM) system that isn’t Shopify or BigCommerce. If you are looking for the replacement of /products from 2021-01, use /plans in 2021-11
/plansNot supportedA new resource that effectively replaces /products from 2021-01
Delaying a charge regenerationcommit_update defaults to truecommit_update defaults to false
/shopSupportedUse /store instead
ResourceChange
WebhooksYou can now indicate the version of the payload you would like us to send you for webhooks by including the version attribute in your webhook registration.

Detailed Changelog

Globally implemented changes (key points in bold):

Requests

  • A JSON object container is only required on requests where body attributes are necessary. For example, POST /charge/:id/process does not require a body.
  • Boolean values are represented as true or false, where previously representation varied between True, true, 1 and False, false, 0.
  • Null values by data type:
    • Number: null may or may not be a valid input. Attribute nullability is reflected in the Recharge API Reference.
    • Boolean: null may or not be a valid input. Attribute nullability is reflected in the Recharge API Reference. When boolean values are set to null, false is the default value.
    • Date and Date-time strings: null may or may not be a valid input. Attribute nullability is reflected in the Recharge API Reference. Date and date-time values must conform to ISO 8601 standard.
    • String: when a string attribute has a null value, it will be returned as null, not an empty string.
    • Object: null will be interpreted as {}, an empty object.
    • Array: null will be interpreted as [], an empty array.
  • Missing optional keys:
    • POST: the values for missing keys will be treated as their null equivalent unless another default value is reflected in Recharge API Reference, as reflected above.
    • PUT: missing keys will be ignored.
  • Request Parameters:
    • Request parameters should always be query parameters passed in the URL.
    • Unrecognized or unsupported query parameters will be silently ignored. No error message will result from unsupported URL parameters.
    • All date filters are inclusive.

Responses


Response Headers

  • The x-recharge-version identifies the version of the Recharge API used to process the request.

Response Bodies

  • All list responses are ordered by id-desc if no sort_by param is passed to override sorting.
  • All list responses will default to 50 records if no limit parameter is passed to override the maximum. A maximum of 250 records may be returned in a single response.
  • Ordering of attributes:
    • The primary id of any object is the first attribute in the response.
    • All foreign keys relating an object to other Recharge resources will appear first after the primary key, in alphabetized order.
    • All remaining attributes of an object will appear in alphabetical order, following the standard English alphabet, where underscores are treated as spaces.
    • All foreign keys relating an object to other Recharge resources will appear first after the primary key, in alphabetized order.
  • Attribute naming:
    • All attribute keys are lowercase snake-case, for example, order_id
    • All attribute keys referencing external values take the following format: external_{object name}_{attribute name}. For example, external_order_number.
    • All attribute keys referencing a recharge object id take the following format: {object_name}_id. For example, customer_id.
    • Nested object id keys are not prepended with the object name unless not representative of the parent attribute.
    • Attributes referencing a timestamp take on the following format: {verb}_at. For example, charged_at or updated_at
    • Attributes referencing a date value take the following format: {subject}_date. For example, charge_date
  • Attribute Formatting:
    • All boolean values are returned as true or false. Boolean attributes do not support stringified values.
    • Any value for a varchar key will be returned in all lowercase characters but may support mixed-case when writing.
    • All amount values are formatted as strings and include the common number of decimal places to a store’s configured currency (except in the case of dollar values for taxes, where rounding may occur).
    • All external_id values are formatted as strings.
    • For any price that is a child of a tax_lines object, the value is displayed to 3 decimal places to support complex rounding.
    • Any value of rate inside tax_lines is displayed to 4 decimal places to reflect tax rates accurately. For example, a 12.5% tax rate is reflected as 0.1250.
    • In the event an attribute referring to an external value may contain multiple external platforms, the format supports a flexible list of values, where the ecommerce child is treated as the primary external value.
    • If an array or list attribute contains no results, it will be returned as [] or {} instead of null
    • Any datetime value will be reflected in UTC using ISO 8601 standard format.
  • Pagination
    • The page parameter is not supported in 2021-11, and functionality has been replaced with cursor-based pagination
    • List responses contain top-level ‘next’ and ‘previous’ keys, indicating the cursor value for the next and previous pages of results.
    • Count endpoints are not implemented in 2021-11
  • Status Codes:
    • We abide by a list of standard error codes. More details in API Standards.

Other changes


  • The customer payment sources endpoint has been deprecated in 2021-11, and is replaced by Payment Methods. The Payment Methods resource allows for associating multiple payment methods with a Customer, assigning one payment method as the primary on every Address. Note that we are actively rolling out support for this resource across all stores.
    • At this point, all new Shopify stores created after August 3, 2021 have access to the Payment Method resource.
    • Additionally, as we continue to roll out support across stores and platforms, it’s possible that your store already has access. However, if you notice a You do not have sufficient permissions (scopes) for this object error while trying to access this resource that means we haven’t rolled out Payment Methods on your store yet. If you would like immediate access to this resource, please reach out to Recharge Support.
  • Change an order date endpoint in the Orders API in 2021-01 is not promoted to 2021-11. If you want to change an order date, use the ‘Update an order’ endpoint instead.
  • note_attributes in the Address and Order objects has been renamed to order_attributes, but the functionality is consistent across versions. Additionally, cart_attributes has been replaced by order_attributes.
  • The new Products resource enables merchants that don’t use Shopify or BigCommerce to build an integration between Recharge and their PIM. This new resource, available exclusively to merchants doing a custom integration with their PIM system, enables merchants to send information regarding what products they sell to Recharge.
  • The new Plans resource replaces the Products resource from 2021-01. A 'plan' decouples the concept of “what you sell” from “how you sell it”. Using plans you can create and configure subscription, prepaid, and onetime purchase options for products in Recharge. You can now create multiple Plans for a Product.
  • Delay a charge regen functionality in the Subscriptions resource in 2021-01 will default differently in 2021-11. Each subscription update triggers a charge regeneration which can be time-consuming if multiple updates are being performed in sequence. In `2021-11`, delaying a charge regen is the default behavior. If you do not wish to delay, you can leverage a query parameter to immediately commit the update, and regenerate the associated charge synchronously within your request. (?commit=true)
  • The Store resource replaces the Shop resource from 2021-01.
  • Webhook registrations now allow you to send an api_version attribute, indicating the version of the object payload you would like in the webhooks.
  • Many duplicative attributes have been removed from resources across the API. For example, email no longer appears on the Subscriptions object. These attributes can now be fetched alongside subscriptions by leveraging our new Extended Responses (?include=customer).
  • Customer.status has been deprecated in 2021-11.
  • All payment information has been removed from the customer resource in 2021-11. To view payment details alongside a customer record, use Extended Responses.
  • In instances where a purchase item may be a subscription or onetime, subscription_id has been renamed to purchase_item_id.
  • Discounts.usage_limit has been renamed to automatic_redemptions_per_customer for functional clarity.
  • Webhooks:
    • product/created, product/updated, and product/deleted webhooks have been deprecated.
    • plan/created, plan/updated, plan/deleted webhooks have been added.
    • store/updated, webhook has been added.

Need Help? Contact Us