API Reference

The Recharge API is primarily a REST API with some RPC endpoints to support common operations. It has predictable, resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and methods.

Related guides: Generate API tokens, Using the API



API and Platforms compatibility

Recharge offers hosted solutions and integrates with various ecommerce platforms to process recurring transactions with the setup of your choice. In order to be compatible with those platforms some of our API resources and endpoints may be limited in use to a subset of platforms. When that is the case we will flag with the help of tags the checkout/platform association for which that feature is compatible.
When there is no restriction of compatibility no tags will appear.
Below is a legend of the tags you may come across:


Tag Checkout solution Ecommerce platform
BigCommerce Recharge hosted BigCommerce
Custom Recharge hosted or API-first Custom
RCS Recharge hosted Shopify
SCI Shopify hosted Shopify

You may also come across other tags specifying regional restrictions (e.g. USA Only) or new releases (e.g. Alpha, Beta).



Intro image
Base URL
https://api.rechargeapps.com

Authentication

Recharge uses API keys to authenticate requests.

Each request to the API should contain an API token in the following header:

X-Recharge-Access-Token:store_api_token

Replace store_api_token with your API key.

All requests must be made over HTTPS.


API Token Scopes

Scopes can be set up from the API token edit page in Recharge to control the level of access of an API token.

The API currently supports the scopes below:

Write Read
read_accounts
write_batches read_batches
write_customers read_customers
write_discounts read_discounts
read_events
write_notifications
write_orders read_orders
write_payment_methods read_payment_methods
write_products read_products
write_subscriptions read_subscriptions
read_store
read_credit_accounts
read_credit_adjustments
GET /
curl -i -H 'X-Recharge-Access-Token: your_api_token'
-X GET

Versioning

All requests will use your account API settings, unless you send a X-Recharge-Version header to specify the version.
You can use the same token to make calls to all versions. When no version is specified it will default to the default version on your store.

Existing API Versions Release notes
2021-11 2021-11 release notes
2021-01

Responses

Recharge uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided ( e.g. a required parameter was omitted, a charge failed, etc ), and codes in the 5xx range indicate an error with Recharge’s servers.

200 - OK: Everything worked as expected.
201 - OK: The request was successful, created a new resource, and resource created is in the body.
202 - OK: The request has been accepted and is in processing.
204 - OK: The server has successfully fulfilled the request and there is no content to send in the response body.
400 - Bad Request: The request was unacceptable, often due to a missing required parameter.
401 - Unauthorized: No valid API key was provided.
402 - Request Failed: The parameters were valid but the request failed.
403 - The request was authenticated but not authorized for the requested resource (permission scope error).
404 - Not Found: The requested resource doesn’t exist.
405 - Method Not Allowed: The method is not allowed for this URI.
406 - The request was unacceptable, or requesting a data source which is not allowed although permissions permit the request.
409 - Conflict: You will get this error when you try to send two requests to edit an address or any of its child objects at the same time, in order to avoid out of date information being returned.
415 - The request body was not a JSON object.
422 - The request was understood but cannot be processed due to invalid or missing supplemental information.
426 - The request was made using an invalid API version.
429 - The request has been rate limited.
500 - Internal server error.
501 - The resource requested has not been implemented in the current version but may be implemented in the future.
503 - A 3rd party service on which the request depends has timed out.

Extending responses

Our API endpoints and webhooks allow developers to extend responses with additional data in order to optimize calls, allowing for simpler and more efficient implementations.

The API supports including additional objects when using a GET request to retrieve a list or a GET request to retrieve a record by a specific id. This is achieved by using an include query parameter in the request URL. The include value contains the object or objects you want to include in the response of your request. On routes where multiple includes are available, you are able to pass multiple values separated by a comma (include=customer,metafields). The below table defines available include values for commonly used resources of the API.

Webhooks support included_objects on the topics listed below. Webhook included_objects accepts an array of supported values ("included_objects": [ "customer", "metafields"]). Specifying included_objects will return an enriched payload, containing the original resource and the associated included objects.

When including charge_activities in API calls or webhooks, note that only the last 90 days of activities will be included in the response.

Resource Endpoints Webhook topics Supported include values Supported included_objects values
Addresses GET /addresses
GET /addresses/{id}		 address/created
address/updated		 charge_activities
customer
discount
payment_methods
subscriptions		 customer
payment_methods
Charges GET /charges
GET /charges/{id}		 charge/created
charge/failed
charge/max_retries_reached
charge/paid
charge/refunded
charge/uncaptured
charge/upcoming
charge/updated
charge/deleted		 charge_activities (beta)
customer
metafields
payment_methods		 customer
metafields
payment_methods
Customers GET /customers
GET /customers/{id}		 customer/activated
customer/created
customer/deactivated
customer/payment_method_updated
customer/updated
customer/deleted		 addresses
metafields
payment_methods
subscriptions		 addresses
metafields
payment_methods
Orders GET /orders
GET /orders/{id}		 order/cancelled
order/created
order/deleted
order/processed
order/payment_captured
order/upcoming
order/updated
order/success		 customer
metafields		 customer
metafields
Payment Methods GET /payment_methods
GET /payment_methods/{id}		 addresses addresses
Subscriptions GET /subscriptions
GET /subscriptions/{id}		 subscription/activated
subscription/cancelled
subscription/created
subscription/deleted
subscription/skipped
subscription/updated
subscription/unskipped
subscription/paused		 address
charge_activities
customer
metafields
bundle_product
bundle_selections		 customer
metafields

Cursor Pagination

By default, calls for a list of objects will return 50 results. Using the limit parameter, that can be increased to 250 results per response.

When there are more results than the current limit a cursor may be used to request additional results.

The next_cursor and previous_cursor attributes are are included in all list responses.

To request the next set of results, find the next_cursor in the list response and include it in the url with the cursor parameter e.g. GET https://api.rechargeapps.com/subscriptions?limit=250&cursor=<next_cursor>

To request the previous set of results, find the previous_cursor in the list response and include it in the url with the cursor parameter e.g. GET https://api.rechargeapps.com/subscriptions?limit=250&cursor=<previous_cursor>


Retrieving total number of records

Starting with the 2021-11 version of the API, you will not be able to retrieve a count of total records for a given GET request. If you are building a UI page that allows end users to paginate through result sets (such as paginating through a list of orders or subscriptions), we recommend that your pagination implementation allow users to go to the next and previous page of results (as opposed to allowing users to jump to specific page in the results). This aligns well with the previous_cursor and the next_cursor fields included in all list responses.

Example Request
URL="https://api.rechargeapps.com/charges?limit=5"

response=$(curl -s -w "%{http_code}"\ 
    -H 'X-Recharge-Access-Token: your_api_token' \ 
    -H 'X-Recharge-Version: 2021-11' \    -X GET $URL)

content=$(sed '$ d' <<< "$response") # get all but the last line which contains the status code

# Display results
echo $content | jq "."

# parse next url
echo "Next URL"
next_cursor=$(jq ".next_cursor" <<< "${content}")

# Notice next_cursor value is passed as page_info query param
echo "$URL&page_info=$next_cursor"

Sorting

The API supports sorting of results when using a GET request to retrieve a list. Sorting is achieved using a sort_by query parameter in the request URL. The sort_by value contains the parameter and sort direction for your results (ascending or descending), and available sort_by values vary between resources. The below table defines available sort_by options for commonly used resources.


Resource Supported sort_by_values
Address Default: id-desc
Options: id-asc id-desc updated_at-asc updated_at-desc
Async Batch Default: id-desc
Options: id-asc id-desc created_at-asc created_at-desc
Charge Default: id-asc
Options: id-asc id-desc created_at-asc created_at-desc updated_at-asc updated_at-desc scheduled_at-asc scheduled_at-desc
Customer Default: id-desc
Options: id-asc id-desc created_at-asc created_at-desc updated_at-asc updated_at-desc
Discount Default: id-desc
Options: id-asc id-desc created_at-asc created_at-desc updated_at-asc updated_at-desc
Metafield Default: id-desc
Options:id-asc id-desc updated_at-asc updated_at-desc
Onetime Default: id-desc
Options: id-asc id-desc created_at-asc created_at-desc updated_at-asc updated_at-desc
Order Default: id-desc
Options: id-asc id-desc updated_at-asc updated_at-desc processed_at-asc processed_at-desc scheduled_at-asc scheduled_at-desc
Plan Default: id-desc
Options:id-asc id-desc updated_at-asc updated_at-desc
Subscription Default: id-desc
Options: id-asc id-desc created_at-asc created_at-desc updated_at-asc updated_at-desc
Webhook Default: id-desc
Options: id-asc id-desc

Addresses

An Addresses record represents a shipping address. Each customer can have multiple addresses. Subscriptions are a child object of an address.

Endpoints
POST
/addresses
GET
/addresses/{id}
PUT
/addresses/{id}
DELETE
/addresses/{id}
GET
/addresses
POST
/addresses/merge
POST
/addresses/{id}/charges/skip

The address object

An Addresses record represents a shipping address. Each customer can have multiple addresses. Subscriptions are a child object of an address.

Attributes
  • id
    integer

    Unique numeric identifier for the Address.

  • payment_method_id
    integer

    Unique numeric identifier for the Payment Method associated to the Address.

  • address1
    string

    The street associated with the Address.

  • address2
    string

    Any additional information associated with the Address.

  • city
    string

    The city associated with the address.

  • company
    string

    The company associated with the address.

  • country_code
    string

    2-letter country code.

  • customer_id
    integer

    Unique numeric identifier for the customer associated with the address.

  • discounts
    array

    A list of discounts applied on the address. These discounts will apply to future recurring charges associated with this address.

    Show object attributes
  • first_name
    string

    The customer’s first name associated with the address.

  • last_name
    string

    The customer’s last name associated with the address.

  • order_attributes
    array

    BigCommerce

    Custom

    RCS

    Replaces cart_attributes. Extra information that is added to the order.

    Show object attributes
  • order_note
    string

    Notes to be added to all orders associated with the address.

  • phone
    string

    The phone number associated with the address.

  • presentment_currency
    string

    SCI

    The currency on the subscription contract in Shopify.

    Only set if the currency is different from the store-level currency. Else, will default to store-level currency.

  • province
    string

    The state or province associated with the address.

  • shipping_lines_conserved
    array

    Shipping rates that have previously been overridden via shipping_lines_override but are currently inactive.

    Show object attributes
  • shipping_lines_override
    array

    Used when shipping rates need to be overridden.

    If this parameter has value null, rates will be fetched when Charge is created or regenerated

    Show object attributes
  • zip
    string

    The zip or postal code associated with the address.

  • created_at
    datetime

    The date and time when the address was created.

  • updated_at
    datetime

    The date and time when the address was last updated.

The address object
{
  "address": {
    "id": 21317826,
    "payment_method_id": 17874235,
    "address1": "1776 Washington Street",
    "address2": "",
    "city": "Los Angeles",
    "company": "Recharge",
    "country_code": "US",
    "created_at": "2018-11-14T09:00:01+00:00",
    "customer_id": 18819267,
    "discounts": [
      {
        "id": 12345,
        "code": "TESTCODE10",
        "value": 10,
        "value_type": "fixed_amount"
      }
    ],
    "first_name": "John",
    "last_name": "Doe",
    "order_attributes": [
      {
        "name": "custom name",
        "value": "custom value"
      }
    ],
    "order_note": "My recurring order note.",
    "phone": "5551234567",
    "presentment_currency": "USD",
    "shipping_lines_conserved": [],
    "shipping_lines_override": [
      {
        "code": "Standard Shipping",
        "price": "0.00",
        "title": "Standard Shipping"
      }
    ],
    "updated_at": "2018-11-14T09:00:01+00:00",
    "zip": "90404"
  }
}

Create an address

Create a new address for a customer.

Scopes: write_customers
Body Parameters
  • customer_id
    integer
    * Required

    Unique numeric identifier for the customer associated with the address.

  • address1
    string
    * Required

    The street associated with the Address. Minimum length is 1 character.

  • address2
    string

    Any additional information associated with the shipping address.

  • city
    string
    * Required

    The city associated with the shipping address.

  • company
    string

    The company associated with the shipping address.

  • country_code
    string
    * Required

    2-letter country code.

    Check if the store supports shipping to this country. This is set by the merchant in their Shipping Settings page.

  • discounts
    array

    List of discounts applied on the Address.

    Show object attributes
  • first_name
    string
    * Required

    The customer’s first name associated with the address. Minimum length is 1 character.

  • last_name
    string
    * Required

    The customer’s last name associated with the address. Minimum length is 1 character.

  • order_attributes
    array

    BigCommerce

    Custom

    RCS

    Extra information that is added to the order.

    Show object attributes
  • order_note
    string

    Notes to be added to all orders associated with the address.

  • payment_method_id
    integer

    Payment method id for the Payment_method to be associated to this address.

  • phone
    string
    * Required

    The phone number associated with the address. Must be included in the request schema but can be an empty string.

  • presentment_currency
    string

    The currency that charges on this address will be processed in. If no presentment_currency is passed, it will be set to your default store currency.

  • province
    string
    * Required

    The state or province associated with the address. Check if country requires a province COUNTRIES_REQUIRING_PROVINCE.

  • shipping_lines_override
    array

    Used when shipping rates need to be overridden. If this parameter has value null, rates will be fetched when a related Charge is created or regenerated

    Show object attributes
  • zip
    string
    * Required

    The zip or postal code associated with the address.

    Check if the country requires a zip code COUNTRIES_NOT_REQUIRING_ZIP. If not included in the list then a zip code with the minimum length of 1 character is required. If the country is United States validate against regex UNITED_STATES_ZIP_REGEX. If country is United Kingdom then validate against regex UNITED_KINGDOM_ZIP_REGEX.

Responses
  • 201

    OK: The request was successful, created a new resource, and resource created is in the body.

    Show response object
POST
/addresses 
curl https://api.rechargeapps.com/addresses \ 
 -H 'X-Recharge-Version: 2021-11' \ 
 -H 'Content-Type: application/json' \ 
 -H 'X-Recharge-Access-Token: your_api_token' \ 
 -d '{
  "customer_id": 22152215,
  "address1": "1776 Washington Street",
  "address2": "",
  "city": "Los Angeles",
  "company": "Recharge",
  "country_code": "US",
  "first_name": "John",
  "last_name": "Doe",
  "order_attributes": [
    {
      "name": "custom name",
      "value": "custom value"
    }
  ],
  "phone": "5551234567",
 "presentment_currency": "USD",
  "province": "California",
  "zip": "90404"
}'
Response 
{
  "address": {
    "id": 42171447,
    "address1": "1030 Barnum Ave",
    "address2": "Suite 101",
    "city": "Stratford",
    "company": "Fake Company",
    "country_code": "US",
    "created_at": "2022-10-12T20:16:09+00:00",
    "customer_id": 37657002,
    "discounts": [],
    "first_name": "Fake First",
    "last_name": "Fake Last",
    "order_attributes": [
      {
        "name": "custom name",
        "value": "custom value"
      }
    ],
    "order_note": "My recurring order note",
    "phone": "999-999-9999",
    "presentment_currency": "USD",
    "province": "Connecticut",
    "shipping_lines_conserved": [],
    "shipping_lines_override": [],
    "updated_at": "2022-10-12T20:16:09+00:00",
    "zip": "06614"
  }
}

Retrieve an address

Retrieves address for customer based on specified address id.

Scopes: read_customers
Responses
  • 200

    successful response

    Show response object
GET
/addresses/{id} 
curl 'https://api.rechargeapps.com/addresses/21317826' \ 
 -H 'X-Recharge-Version: 2021-11' \ 
 -H 'X-Recharge-Access-Token: your_api_token'
Response 
{
  "address": {
    "id": 42171447,
    "payment_method_id": 17874235,
    "address1": "1030 Barnum Ave",
    "address2": "Suite 101",
    "city": "Stratford",
    "company": "Fake Company",
    "country_code": "US",
    "created_at": "2022-10-12T20:16:09+00:00",
    "customer_id": 37657002,
    "discounts": [],
    "first_name": "Fake First",
    "last_name": "Fake Last",
    "order_attributes": [
      {
        "name": "custom name",
        "value": "custom value"
      }
    ],
    "order_note": "My recurring order note",
    "phone": "999-999-9999",
    "presentment_currency": "USD",
    "province": "Connecticut",
    "shipping_lines_conserved": [],
    "shipping_lines_override": [],
    "updated_at": "2022-10-12T20:16:09+00:00",
    "zip": "06614"
  }
}

Update an address

Updates an existing address to match the specified parameters.

Example: remove discounts from an address

To remove all discounts from an address, set the discounts parameter to an empty array: {"discounts": []}

Note: When updating the country property you will have to update the zip property as well, otherwise you will receive an error.

Scopes: write_customers
Body Parameters
  • address1
    string

    The street associated with the Address. Minimum length is 1 character.

  • address2
    string

    Any additional information associated with the shipping address.

  • city
    string

    The city associated with the shipping address. Minimum length is 1 character.

  • company
    string

    The company associated with the shipping address.

  • country_code
    string

    2-letter country code.

    Check if the store supports shipping to this country. This is set by the merchant in their Shipping Settings page.

  • discounts
    array

    A list of discounts applied on the address. These discounts will apply to future recurring charges associated with this address.

    Show object attributes
  • first_name
    string

    The customer’s first name associated with the address. Minimum length is 1 character.

  • last_name
    string

    The customer’s last name associated with the address. Minimum length is 1 character.

  • order_attributes
    array

    BigCommerce

    Custom

    RCS

    Extra information that is added to the order.

    Show object attributes
  • order_note
    string

    Notes to be added to all orders associated with the address.

  • payment_method_id
    integer

    Payment method id for the Payment_method to be associated to this address.

  • phone
    string

    The phone number associated with the address. Must be included in the request schema but can be an empty string.

  • province
    string

    The state or province associated with the address. Check if country requires a province COUNTRIES_REQUIRING_PROVINCE.

  • shipping_lines_override
    array

    BigCommerce

    Custom

    RCS

    SCI

    Used when shipping rates need to be overridden. If this parameter has value null, rates will be fetched when a related Charge is created or regenerated.

    Show object attributes
  • zip
    string

    The zip or postal code associated with the address. Check if the country requires a zip code COUNTRIES_NOT_REQUIRING_ZIP. If not included in the list then a zip code with the minimum length of 1 character is required. If the country is United States then validate against regex UNITED_STATES_ZIP_REGEX. If country is United Kingdom then validate against regex UNITED_KINGDOM_ZIP_REGEX.

Responses
  • 200

    successful response

    Show response object
PUT
/addresses/{id} 
curl -X PUT 'https://api.rechargeapps.com/addresses/38700614' \ 
 -H 'X-Recharge-Version: 2021-11' \ 
 -H 'Content-Type: application/json' \ 
 -H 'X-Recharge-Access-Token: your_api_token' \ 
 -d '{"address1": "1776 Washington Street"}'
Response 
{
  "address": {
    "id": 42171447,
    "payment_method_id": 17874235,
    "address1": "1030 Barnum Ave",
    "address2": "Suite 101",
    "city": "Stratford",
    "company": "Fake Company",
    "country_code": "US",
    "created_at": "2022-10-12T20:16:09+00:00",
    "customer_id": 37657002,
    "discounts": [],
    "first_name": "Fake First",
    "last_name": "Fake Last",
    "order_attributes": [
      {
        "name": "custom name",
        "value": "custom value"
      }
    ],
    "order_note": "My recurring order note",
    "phone": "999-999-9999",
    "presentment_currency": "USD",
    "province": "Connecticut",
    "shipping_lines_conserved": [],
    "shipping_lines_override": [],
    "updated_at": "2022-10-12T20:16:09+00:00",
    "zip": "06614"
  }
}

Delete an address

It is possible to delete certain addresses from the store using API.

Only Addresses with no active Subscriptions can be deleted.

Scopes: write_customers
Responses
  • 204

    Content Deleted: The server has successfully fulfilled the request and deleted the desired object and there is no content to send in the response body.

    Show response object
DELETE
/addresses/{id} 
curl -X DELETE 'https://api.rechargeapps.com/addresses/38700614'\ 
 -H 'X-Recharge-Version: 2021-11' \ 
 -H 'X-Recharge-Access-Token: your_api_token'
Response 
{}

List addresses

Returns all addresses from the store, or addresses for the user given in the parameter.

HTTP examples


GET /addresses

GET /addresses?customer_id=<customer_id>

GET /addresses?discount_id=<discount_id>

GET /addresses?discount_code=<discount_code>

You can combine created_at_min and created_at_max to return all addresses created in the given timespan. This also applies to updated_at_min and updated_at_max parameters.

Scopes: read_customers
Query Parameters
  • created_at_max
    datetime

    Returns addresses created before the given time.

  • created_at_min
    datetime

    Returns addresses created after the given time.

  • customer_id
    integer

    Unique identifier of the customer.

  • discount_code
    string

    Returns addresses that have the provided discount_code.

  • discount_id
    string

    Returns addresses that have the provided discount_id.

  • ids
    string

    Filter addresses by id. If passing multiple values, must be comma separated. Non-integer values will result in a 422 error

  • limit
    string

    Default: 50

    Max: 250

    The amount of results. Default is 50 while the maximum is 250.

  • page
    string

    Default: 1

    The page to show. Default is 1.

  • updated_at_max
    string

    Returns addresses updated before the given date.

  • updated_at_min
    string

    Returns addresses updated after the given time.

  • is_active
    boolean

    Returns active addresses.

Responses
  • 200

    successful response

    Show response object
GET
/addresses 
curl 'https://api.rechargeapps.com/addresses' \ 
 -H 'X-Recharge-Version: 2021-11' \ 
 -H 'X-Recharge-Access-Token: your_api_token' \ 
 -d limit=3 -G
Response 
{
  "addresses": [
    {
      "id": 42171447,
      "payment_method_id": 17874235,
      "address1": "1030 Barnum Ave",
      "address2": "Suite 101",
      "city": "Stratford",
      "company": "Fake Company",
      "country_code": "US",
      "created_at": "2022-10-12T20:16:09+00:00",
      "customer_id": 37657002,
      "discounts": [
        {
          "id": 123456
        }
      ],
      "first_name": "Fake First",
      "last_name": "Fake Last",
      "order_attributes": [
        {
          "name": "custom name",
          "value": "custom value"
        }
      ],
      "order_note": "My recurring order note",
      "phone": "999-999-9999",
      "presentment_currency": "USD",
      "province": "Connecticut",
      "shipping_lines_conserved": [],
      "shipping_lines_override": [
        {
          "code": "Standard Shipping",
          "price": "0.00",
          "title": "Standard Shipping"
        }
      ],
      "updated_at": "2022-10-12T20:16:09+00:00",
      "zip": "06614"
    }
  ]
}

Merge addresses

Merges up to 10 source addresses into 1 target address.

If one of the Addresses being merged has a different presentment currency, the entire merge will fail and throw an error.

Scopes: write_customers
Body Parameters
  • delete_source_addresses
    boolean

    Indicates whether source addresses should be deleted.

  • next_charge_date
    string

    Specifies the next charge date of the associated subscriptions on the target address.

  • target_address
    object
    * Required

    The address all of the subscriptions should be moved to.

    Show object attributes
  • source_addresses
    array
    * Required

    The list of addresses that the subscriptions should move from.

Responses
  • 200

    successful response

    Show response object
POST
/addresses/merge 
curl -X POST 'https://api.rechargeapps.com/addresses/merge' \ 
 -H 'X-Recharge-Version: 2021-11' \ 
 -H 'Content-Type: application/json' \ 
 -H 'X-Recharge-Access-Token: your_api_token' \ 
 -d '{"target_address": {"id": 42171447}, "source_addresses": [{"id": 42171446}, {"id": 42171445}]}'
Response 
{
  "address": {
    "id": 42171447,
    "payment_method_id": 17874235,
    "address1": "1030 Barnum Ave",
    "address2": "Suite 101",
    "city": "Stratford",
    "company": "Fake Company",
    "country_code": "US",
    "created_at": "2022-10-12T20:16:09+00:00",
    "customer_id": 37657002,
    "discounts": [],
    "first_name": "Fake First",
    "last_name": "Fake Last",
    "order_attributes": [
      {
        "name": "custom name",
        "value": "custom value"
      }
    ],
    "order_note": "My recurring order note",
    "phone": "999-999-9999",
    "presentment_currency": "USD",
    "province": "Connecticut",
    "shipping_lines_conserved": [],
    "shipping_lines_override": [],
    "updated_at": "2022-10-12T20:16:09+00:00",
    "zip": "06614"
  }
}

Skip future charge

Skip a Charge in the future for one or multiple Subscriptions associated with the Address.

If the Charge does not exist on the date, it will be created with a SKIPPED status.

Scopes: write_orders
Body Parameters
  • date
    datetime
    * Required

    The date in the future of the Charge to be skipped.

    This date must be within the delivery schedules of the Customer.

  • subscription_ids
    array
    * Required

    A list containing the Subscription IDs to be skipped.

Responses
  • 200

    successful response

    Show response object
  • 404

    the Address with id does not exist

    Show response object
  • 422

    invalid data passed to the endpoint

    Show response object
POST
/addresses/{id}/charges/skip 
curl 'https://api.rechargeapps.com/addresses/91977136/charges/skip' \ 
 -H 'X-Recharge-Version: 2021-11' \ 
 -H 'Content-Type: application/json' \ 
 -H 'X-Recharge-Access-Token: your_api_token' \ 
 -d '{"date": "2022-09-15", "purchase_item_ids": [27363808, 27363809]}'
Response 
{
  "charge": {
    "id": 377749210,
    "address_id": 42171447,
    "analytics_data": {
      "utm_params": [
        {
          "utm_source": "facebook",
          "utm_medium": "cpc"
        }
      ]
    },
    "billing_address": {
      "address1": "601 SW Washing St.",
      "address2": "Suite 101",
      "city": "Portland",
      "company": "Acme Corp",
      "country_code": "US",
      "first_name": "Jane",
      "last_name": "Doe",
      "phone": "888-888-8888",
      "province": "Oregon",
      "zip": "97205"
    },
    "client_details": {
      "browser_ip": "192.168.0.1",
      "user_agent": "safari webkit"
    },
    "created_at": "2021-11-09T19:22:13+00:00",
    "currency": "USD",
    "customer": {
      "id": 37657002,
      "email": "test@test.com",
      "external_customer_id": {
        "ecommerce": "2879413682227"
      },
      "hash": "7e706455cbd13e40"
    },
    "discounts": [
      {
        "id": 12345,
        "code": "TESTCODE10",
        "value": 10,
        "value_type": "fixed_amount"
      }
    ],
    "error": null,
    "error_type": null,
    "external_order_id": {
      "ecommerce": "2541635698739"
    },
    "external_transaction_id": {
      "payment_processor": "ch_1HzWElJ2zqHvZRd1TWKFFqDR"
    },
    "has_uncommitted_changes": false,
    "line_items": [
      {
        "purchase_item_id": 63898947,
        "external_product_id": {
          "ecommerce": "4381728735283"
        },
        "external_variant_id": {
          "ecommerce": "999999999999"
        },
        "grams": 454,
        "handle": "shirt-package",
        "images": {
          "large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg",
          "medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg",
          "original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg",
          "small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg"
        },
        "original_price": "10.00",
        "properties": [
          {
            "name": "Color",
            "value": "Blue"
          }
        ],
        "purchase_item_type": "subscription",
        "quantity": 1,
        "sku": "TOM0001",
        "tax_due": "1.30",
        "tax_lines": [
          {
            "price": "0.9931",
            "rate": "0.0725",
            "title": "CA State Tax",
            "unit_price": "0.3310"
          },
          {
            "price": "0.3082",
            "rate": "0.0225",
            "title": "LA County Tax",
            "unit_price": "0.1027"
          }
        ],
        "taxable": true,
        "taxable_amount": "10.00",
        "title": "Shirt package",
        "total_price": "11.30",
        "unit_price": "10.00",
        "unit_price_includes_tax": false,
        "variant_title": "Blue T-shirt"
      }
    ],
    "note": "next order in sequence 3",
    "order_attributes": [
      {
        "name": "Checkout-Method",
        "value": "delivery"
      }
    ],
    "orders_count": 1,
    "payment_processor": "stripe",
    "processed_at": null,
    "retry_date": null,
    "scheduled_at": "2021-12-09",
    "shipping_address": {
      "address1": "1030 Barnum Ave",
      "address2": "Suite 101",
      "city": "Stratford",
      "company": "Fake Company",
      "country_code": "US",
      "first_name": "Fake First",
      "last_name": "Fake Last",
      "phone": "999-999-9999",
      "province": "Connecticut",
      "zip": "06614"
    },
    "shipping_lines": [
      {
        "code": "Standard",
        "price": "4.90",
        "source": "shopify",
        "taxable": true,
        "tax_lines": [
          {
            "price": "0.355",
            "rate": 0.0725,
            "title": "CA State Tax"
          },
          {
            "price": "0.110",
            "rate": 0.0225,
            "title": "Los Angeles  County Tax"
          }
        ],
        "title": "Standard"
      }
    ],
    "status": "skipped",
    "subtotal_price": "10.00",
    "tags": "Subscription, Subscription Recurring Order",
    "tax_lines": [
      {
        "price": "0.950",
        "rate": 0.0725,
        "title": "CA State Tax"
      },
      {
        "price": "0.335",
        "rate": 0.0225,
        "title": "Los Angeles  County Tax"
      }
    ],
    "taxable": true,
    "total_discounts": "10.0",
    "total_line_items_price": "10.00",
    "total_price": "11.29",
    "total_refunds": "0.00",
    "total_tax": "1.29",
    "total_weight_grams": 454,
    "type": "recurring",
    "updated_at": "2021-11-09T23:59:32+00:00"
  }
}

Bundle Selections

Pro plan

SCI

RCS

A bundle selection represents the contents within a Bundle linked to an individual Subscription. It can represent the selection for upcoming orders or past orders. A BundleSelection is associated with a corresponding Subscription and a BundleVariant (the BundleVariant is used to validate contents in the selection). When a new order for the associated Subscription occurs, it will extract the current contents of the BundleSelection for the Bundle item in the order.

Endpoints
GET
/bundle_selections
GET
/bundle_selections/{id}
POST
/bundle_selections
PUT
/bundle_selections/{id}
DELETE
/bundle_selections/{id}
Expand

Charges

A charge is the representation of a financial transaction linked to the purchase of an item (past or future). It can be a transaction that was processed already or the representation of an upcoming transaction. A Charge is linked to its corresponding Orders (one Order for pay as you go subscriptions and several for pre-paid). Orders are created once the corresponding Charge is successful. After successful payment, the first Order will be immediately submitted to the external platform if applicable (e.g. Shopify, BigCommerce).

Endpoints
GET
/charges/{id}
GET
/charges
POST
/charges/{id}/apply_discount
POST
/charges/{id}/remove_discount
POST
/charges/{id}/skip
POST
/charges/{id}/unskip
POST
/charges/{id}/refund
POST
/charges/{id}/process
POST
/charges/{id}/capture_payment
Expand

Checkouts

Pro plan

BigCommerce

Custom

Checkouts allow you to create, update, and process a Checkout programmatically. Shipping cost and sales tax determination are automatic functions of the Recharge Checkout resource.

Related guides: Recharge checkout integrations, How to use the Checkout resource

Important - The Checkout endpoints are only available for BigCommerce and Custom. Checkouts on Shopify must go through Shopify.

Endpoints
POST
/checkouts
GET
/checkouts/{token}
POST
/checkouts
PUT
/checkouts/{token}
GET
/checkouts/{token}/shipping_rates
POST
/checkouts/{token}/charge
Expand

Collections

Collections allow to create and manage a logical list of Products called a Collection. A Collection contains an ordered list of Products and can be used for selective display of Products on chosen interfaces or for business logic automation (e.g. Discounts definition…).

Endpoints
POST
/collections
GET
/collections/{id}
PUT
/collections/{id}
DELETE
/collections/{id}
GET
/collections
GET
/collection_products
POST
/collections/{id}/collection_products-bulk
DELETE
/collections/{id}/collection_products-bulk
Expand

Credits

Retain

The Credit Account object represents a set of positive and negative credit adjustments that when summed equal an available balance. Credit accounts may not have negative balances. A credit account may be associated with a customer, via the customer_id attribute. A customer may be associated with many credit accounts.

A credit adjustment represents a financial adjustment to the balance of a Credit Account. An adjustment of type ‘credit’ results in an increase in the available balance of a credit account, where an adjustment of type ‘debit’ results in a decrease.

Access to the Credits endpoints are only available for merchants using Retain.

Endpoints
GET
/credit_accounts
GET
/credit_accounts/{id}
GET
/credit_adjustments
GET
/credit_adjustments/{id}
GET
/credit_accounts/{id}/credit_adjustments
Expand

Customers

The Customer object holds account information. Email is unique on the Customer; no two customers for a store can have the same email. Address is a child of the Customer object. There can be many child Addresses on a customer, but only one parent Customer per Address.

Endpoints
POST
/customers
GET
/customers/{id}
PUT
/customers/{id}
DELETE
/customers/{id}
GET
/customers
GET
/customers/{id}/delivery_schedule
GET
/customers/{id}/credit_summary
Expand

Discounts

Discounts can be applied to a Checkout, or can be applied directly to an Address. Depending on configuration they allow for single use, or recurring discounts. More details on how to add or remove discounts from an Address can be found at Update an address.

Often discounts can be used in combination with webhooks, such that when a specific event occurs, it can apply a discount dependent on custom business logic.

There are various options that can be utilized for discounts such as minimum price, single use, recurring for a set number of charges, or ongoing. You can also set the date from which time the discount will become applicable and when it can no longer be applied to a new subscription.

Endpoints
POST
/discounts
GET
/discounts/{id}
PUT
/discounts/{id}
DELETE
/discounts/{id}
GET
/discounts
Expand

Metafields

Metafields allow users to add additional information to other resources. They can be used for adding custom fields to objects, and are useful for storing specialized information.

Endpoints
POST
/metafields
GET
/metafields/{id}
PUT
/metafields/{id}
DELETE
/metafields/{id}
GET
/metafields
Expand

Notifications

The Customer Notifications resource is used to dispatch email notifications to customers within Recharge. The endpoint uses your configured Recharge email templates, and will dispatch an email to the address associated with the indicated customer_id. Some email templates require variable values, which are sent through the Customer Notifications resource via the template_vars attribute. See below examples for all available template types.

Endpoints
POST
/customers/{id}/notifications
Expand

Onetimes

Onetimes represent non-recurring line items on a QUEUED Charge.

Endpoints
POST
/onetimes
GET
/onetimes/{id}
PUT
/onetimes/{id}
DELETE
/onetimes/{id}
GET
/onetimes
Expand

Orders

An order is created after a Charge is successfully processed. The Order contains all the same json data as the Charge. In case of a prepaid order creation, the order will be queued for a particular date and submitted on that date to the external platform.

Endpoints
GET
/orders/{id}
POST
/orders/{id}/clone
POST
/orders/{id}/delay
PUT
/orders/{id}
DELETE
/orders/{id}
GET
/orders
Expand

Payment methods

The Payment Method object holds payment and billing information. A Customer may be associated with many Payment Methods, and an Addresses record must be associated with at least one Payment_method.


Important - If you see the following error when accessing Payment Methods endpoints: “You do not have sufficient permissions (scopes) for this object”, the token you are using has not been configured with correct access permissions. Update the token to have “Read access” or “Read and Write access” depending on your use case.

Endpoints
POST
/payment_methods
GET
/payment_methods/{id}
PUT
/payment_methods/{id}
DELETE
/payment_methods/{id}
GET
/payment_methods
Expand

Plans

The Plans resource is used to create and configure the transactional options for the Product (subscription, prepaid, and onetime purchase options) in Recharge.

Endpoints
POST
/plans
PUT
/plans/{id}
DELETE
/plans/{id}
GET
/plans
POST
/products/{external_product_id}/plans-bulk
PUT
/products/{external_product_id}/plans-bulk
DELETE
/products/{external_product_id}/plans-bulk
Expand

Products

Custom

Representation of the Products from your catalog in Recharge.

Endpoints
POST
/products
GET
/products/{external_product_id}
PUT
/products/{external_product_id}
DELETE
/products/{external_product_id}
GET
/products
Expand

Retention Strategies

Retention Strategies are customer retention workflows that are used to win back customers who are in the process of canceling their subscription. The workflow is determined by the cancellation reason selected by the customer.

Endpoints
POST
/retention_strategies
GET
/retention_strategies/{id}
PUT
/retention_strategies/{id}
DELETE
/retention_strategies/{id}
GET
/retention_strategies
Expand

Store

The store endpoint includes ReCharge settings and other store specific information.

Endpoints
GET
/store
Expand

Subscriptions

Subscriptions are individual items a customer receives on a recurring basis.

A Subscription is a Product added to an Address.

Endpoints
POST
/subscriptions
GET
/subscriptions/{id}
PUT
/subscriptions/{id}
DELETE
/subscriptions/{id}
GET
/subscriptions
POST
/subscriptions/{id}/set_next_charge_date
POST
/subscriptions/{id}/change_address
POST
/subscriptions/{id}/cancel
POST
/subscriptions/{id}/activate
POST
/subscriptions/skip_gift
Expand

Webhook endpoints

Webhooks are a mechanism for reacting to specific events that are triggered in the Recharge system.
For example, a checkout completion, a customer activation or subscription cancellation. Webhooks will deliver you the data of the specific event in real-time. This data can be used to custom code logic behind automated subscription management, dashboards creation, discounts applying…

When a webhook is triggered, the payload will be identical to the payload you would receive from another API endpoint.

For example, a webhook on subscription/created will be identical to the payload for retrieving a subscription by ID from the Recharge API.

There are a lot of things that can be done via Webhooks: It can be used to collect all kinds of data from our API and then create a custom Dashboard to show how much and when your customers are buying in real time, or use all this data to do Analytics of some kind in order to create a better customer experience. Webhooks can be used as a “Trigger” on your backend to update subscription products.

If you have some kind of a Subscription where you want to change the Product that the customer gets every month, you can do it by waiting for an order/created webhook on your backend, and when it fires you can make an API call to change the Product of that subscription or the next shipping date, etc.

Retries / Idempotency


Due to webhook retries, it’s possible that your application receives the same webhook more than once. Ensure idempotency of the webhook call by detecting such duplicates within your application.


Respond to a webhook



Your webhook acknowledges that it received data by sending a 200 OK response. Any response outside of the 200 range will let Recharge know that you didn’t receive your webhook. Recharge has implemented a 5 second time-out period. We wait 5 seconds, if our system doesn’t get a response in that period we consider that request as failed. Our system will try 20 times to send the same webhook over the next 2 days, if the request fails every time our system will delete this webhook. At this moment our system is logging those deleted webhooks.

Endpoints
POST
/webhooks
GET
/webhooks/{id}
PUT
/webhooks/{id}
DELETE
/webhooks/{id}
GET
/webhooks
POST
/webhooks/{id}/test
Expand

Webhooks explained

Here you will find what specific action triggers a given webhook.


Address webhooks

To use these webhooks your API Token must have read permissions for Customers enabled ( read_customer ).


Topic Explanation
address/created This will trigger when you create an address via API, or when you go through the checkout with a particular address for the first time with the same customer.
address/updated This will trigger when you update an address via API, or when you update the address via UI. It will also trigger whenever a subscription has been activated or cancelled.

Bundle webhooks

To use these webhooks your API Token must have read permissions for Subscriptions enabled ( read_subscriptions ).


Topic Explanation
bundle_selection/created This will trigger when a new selection is created for a Bundle subscription.
bundle_selection/updated This will trigger when a Bundle Selection is succesfully updated.
bundle_selection/deleted This will trigger when a Bundle Selection is deleted.

Charge webhooks

To use these webhooks your API Token must have read permissions for Orders enabled ( read_orders ).


Topic Explanation
charge/created This will trigger when a charge is created.
charge/failed This will trigger every time we try to process a charge and it fails due to various reasons (insufficient funds, invalid CC info, expired CC, etc.) on both API and UI.
charge/max_retries_reached This will trigger after we attempt to process a charge 8 times, and it failed every time due to various CC issues. This can be triggered on both UI (manually retry a charge 8 times and fail) and API.
charge/paid This will trigger when a charge is successfully processed, both manually via UI and automatic recurring charge. This will not trigger on the checkout itself.
charge/refunded This will trigger when a charge is successfully refunded, either partially or in full. It will fire if a charge has been refunded both manually via UI and through an API request.
charge/upcoming This will trigger X days before the upcoming charge is scheduled. The default is 3 days but your store specific setting can be verified on the Notification Settings page in the description of the Upcoming charge customer notification.
charge/updated This will trigger when applying a discount, a change to charge that recalculates shipping rates as well as if next_charge_date is updated on charge endpoint charges/<charge_id>/change_next_charge_date.
charge/deleted This will trigger when a subscription is cancelled and upcoming charges are deleted.

Checkout webhooks

To use these webhooks your API Token must have read permissions for Orders enabled ( read-orders ).


Topic Explanation
checkout/created This will trigger when a checkout is successfully created.
checkout/completed Will be deprecated.
checkout/processed This will trigger when a checkout is successfully processed.
checkout/updated This will trigger when a checkout is successfully updated.

Customer webhooks

To use these webhooks your API Token must have read permissions for Customers enabled ( read_customers ).


Topic Explanation
customer/activated This will trigger when you activate* a customer
* activating means that you have added a subscription to a customer who didn’t have an active subscription previously.
customer/created This will trigger when you create a customer via API or go through the checkout with a particular email address for a first time customer.
customer/deactivated This will trigger when the last subscription a customer had expires, so he no longer has ANY active subscriptions (which means there are no QUEUED charges/orders for this customer).
customer/payment_method_updated This will trigger only* when you update the payment_token from the UI
* We are working on triggering this when you do the update from the API as well.
customer/updated This will trigger when you update a customer via both API and UI.
customer/deleted This will trigger when you delete a customer via both API and UI.

Onetime webhooks

To use these webhooks your API Token must have read permissions for Subscriptions enabled ( read_subscriptions ).


Topic Explanation
onetime/created This will trigger when you create a one time product via API.
onetime/deleted This will trigger when you delete a one time product via API.
onetime/updated This will trigger when you update a one time product via API.

Order webhooks

To use these webhooks your API Token must have read permissions for Orders enabled ( read_orders ).


Topic Explanation
order/created This will trigger when an order is created (when a charge is successfully processed)
* In case of prepaid Orders there will be multiple order/created webhooks fired, one for every queued order created at once.
order/deleted This will trigger when an order is deleted.
order/processed This will trigger when the order is processed (when an order goes from status queued to status success). This will not trigger on checkout.
order/upcoming This will trigger X days before a QUEUED (prepaid) order is scheduled to be processed. The default is 3 days.
order/updated This will trigger when an order is updated.

Plan webhooks

To use these webhooks your API Token must have read permissions for Products enabled ( read_products ).


Topic Explanation
plan/created This will trigger when a plan is created by one of the following methods: via API, via Merchant portal or when using the 2021-01 Products endpoint.
plan/deleted This will trigger when a plan is deleted by one of the following methods: via API, via Merchant portal or when using the 2021-01 Products endpoint.
plan/updated This will trigger when a plan is updated by one of the following methods: via API, via Merchant portal or when using the 2021-01 Products endpoint…

Subscription webhooks

To use these webhooks your API Token must have read permissions for Subscriptions enabled ( read_subscriptions ).


Topic Explanation
subscription/activated This will trigger when you activate a subscription via API or UI.
subscription/cancelled This will trigger when you cancel a subscription via API or UI. An involuntary subscription cancelled due to max retries reached will only trigger the charge/max_retries_reached webhook and not the subscription/cancelled webhook.
subscription/created This will trigger when you create a subscription via API or when you go through the checkout on UI.
subscription/deleted This will trigger when you delete a subscription via API or UI.
subscription/skipped This will trigger when you skip a subscription within a charge, meaning that you only skip a particular subscription (the subscription_id you send in the body) in that charge if there are multiple subscriptions related to that charge.
subscription/unskipped This will trigger when you unskip a subscription within a charge, meaning you only unskip a particular subscription (the subscription_id you send in the body) in that charge if there are multiple subscriptions related to that charge.
subscription/updated This will trigger when you update a subscription via API (PUT method) or when you update the subscription via UI. This will also trigger when you update next charge date on Customer Portal, or when you change it using subscription endpoint subscriptions/ <subscription_id>set_next_charge_date.
subscription/swapped This will trigger when you swap a subscription product for a given address to a different product or product variation API or UI.
subscription/paused This will trigger when a customer pauses a subscription from within the customer portal.

Other webhooks

To use these webhooks your API Token must have read permissions for Store enabled ( read_store ).


Topic Explanation
app/uninstalled This will trigger when you uninstall OAuth app on your store.
recharge/uninstalled This will trigger when Recharge is uninstalled.
store/updated This will trigger when and update has been made to the store.

Webhook validation

Webhooks created through the API can be verified by calculating a digital signature. Each Webhook request includes an X-Recharge-Hmac-Sha256 header which is generated using the API Client Secret, along with the data sent in the request.

API Client Secret is not the same as your API token and it can be found at:
Recharge Dashboard—>Integrations—>API Tokens—>Click on your token
Edit API Token page will appear and there you will find API Client Secret

The request_body must be in JSON string format. Validation will fail even if one space is lost in process of JSON string generation.

Then use code similar to the example by adapting it to the programming language that you are using for your project.

Related guides: Example code for validating webhooks

Example Request:

Async batch Endpoints

The Async batches API can be used for processing large volumes of operations asynchronously, in order to reduce aggregate processing time and network traffic when interacting with many unique objects. For example, a user can leverage async_batches to create 1000 discounts with only 3 API requests.

As shown in the diagram below, the necessary steps to create and process a batch are:

1. Create an async_batch with the desired batch_type

2. Add tasks (individual operations) to your batch. You can add up to 1,000 tasks with each request, up to 10,000 tasks per batch.

3. Submit the batch for processing. Until a batch is submitted for processing, no tasks are attempted.

4. You may retrieve the batch to view progress details while it processes, or register for the async_batch/processed webhook to receive immediate notification of batch completion.

5. Page through the tasks in the batch to view results of each completed or failed task.

Related guides: Examples of Async batches

Endpoints
POST
/async_batches
GET
/async_batches/{id}
GET
/async_batches
POST
/async_batches/{batch_id}/process
Expand

Async batch Tasks

Most commonly, the response from listing tasks on an async_batch id will be identical to the body of a singular request to standard Recharge API endpoints. However, in some instances there are variations from the standard list task response body. See below for examples corresponding to each batch_type.

Related guides: Examples of async batches

Endpoints
POST
/async_batches/{batch_id}/tasks
GET
/async_batches/{batch_id}/tasks
Expand

Token information

This resource allows a caller to inspect basic information regarding the token in use. It will only return a single object related to the calling token ( ie - a call with api_token.id=1 will only return information regarding api_token.id=1.

Endpoints
GET
/token_information
Expand

Accounts

This resource allows a caller to inspect basic information regarding the staff accounts in the store.

Endpoints
GET
/accounts/{id}
GET
/accounts
Expand

Events

This resource allows a caller to inspect recent events in the store.

Endpoints
GET
/events
Expand