2021-11 API new version - release notes
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
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
Products
and Plans
- We have rearchitected our
Products
resource and added a newPlans
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 theProducts
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 forProducts
in Recharge usingPlans
. You can now create multiplePlans
for aProduct
. - You probably already caught this, but the big difference between
2021-01
and2021-11
is thatProducts
in2021-01
are nowPlans
in2021-11
.
3. Store
Store
The Store
resource replaces the Shop
resource from 2021-01
. It contains Recharge settings and other store-specific information.
4. Payment Methods
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 anAddress
. Recharge will use thisPayment 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 / feature | 2021-01 | 2021-11 |
---|---|---|
GET /token_information | Not available | Available |
Datetime fields | Always in EST | Always in UTC using ISO-8601 |
Boolean values | A mix of True , true , 1 and False , false , 0 | Always true or false . Stringified values are not supported |
Null values | Varying behavior across endpoints | Consistent behavior across all resources and endpoints |
Unrecognized or unsupported query parameters | Error response | Silently ignored |
Date filters | Inclusive or exclusive depending on the resource | Always inclusive |
Default sort on list endpoints | Varying behavior across resources | id-desc |
Attribute names | Varying naming conventions across resources | Consistent naming convention across resources |
Amount fields regarding currency, such as product prices | Represented by strings or numbers | Always represented by strings |
External IDs | Represented by numbers | Always represented by strings |
Page-based pagination | Supported | Not supported |
Cursor-based pagination | Next and previous links included in the response headers. Users must parse header to extract cursor value | Next and previous cursors included in the response body as distinct key-value pairs |
Count endpoints | Supported | Not supported |
GET /customers/:id/payment_sources | Supported | Use GET /payment_methods instead |
Setting payment methods on the customer object | Supported | Use POST or PUT /payment_methods instead |
POST /orders/:id/change_date | Supported | Use PUT /orders instead |
PUT /orders/:id/update_shopify_variant/:remote_variant_id | Supported | Use PUT /orders instead |
/products | Available 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 |
/plans | Not supported | A new resource that effectively replaces /products from 2021-01 |
Delaying a charge regeneration | commit_update defaults to true | commit_update defaults to false |
/shop | Supported | Use /store instead |
Resource | Change |
---|---|
Webhooks | You 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
andFalse
,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 tonull
,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 asnull
, not an empty string. - Object:
null
will be interpreted as{}
, an empty object. - Array:
null
will be interpreted as[]
, an empty array.
- Number:
- 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
orupdated_at
- Attributes referencing a date value take the following format:
{subject}_date
. For example,charge_date
- All attribute keys are lowercase snake-case, for example,
- 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 ofnull
- 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
- The page parameter is not supported in
- 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 byPayment Methods
. ThePayment Methods
resource allows for associating multiple payment methods with aCustomer
, assigning one payment method as the primary on everyAddress
. 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.
- At this point, all new Shopify stores created after August 3, 2021 have access to the
Change an order date
endpoint in the Orders API in2021-01
is not promoted to2021-11
. If you want to change an order date, use the ‘Update an order’ endpoint instead.note_attributes
in theAddress
andOrder
objects has been renamed toorder_attributes
, but the functionality is consistent across versions. Additionally,cart_attributes
has been replaced byorder_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 theProducts
resource from2021-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 multiplePlans
for aProduct
. Delay a charge regen
functionality in theSubscriptions
resource in2021-01
will default differently in2021-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 theShop
resource from2021-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 in2021-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 topurchase_item_id
. Discounts.usage_limit
has been renamed toautomatic_redemptions_per_customer
for functional clarity.- Webhooks:
product/created
,product/updated
, andproduct/deleted
webhooks have been deprecated.plan/created
,plan/updated
,plan/deleted
webhooks have been added.store/updated
, webhook has been added.