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).
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 |
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.
Resource | Endpoints | Webhook topics | Supported include values |
Supported included_objects values |
---|---|---|---|---|
Addresses |
GET /addresses GET /addresses/:id |
address/created address/updated |
customer discount payment_methods (beta)subscriptions |
customer metafields |
Charges |
GET /charges GET /charges/:id |
charge/created charge/failed charge/max_retries_reached charge/paid charge/refunded charge/uncaptured charge/upcoming charge/updated |
metafields |
metafields |
Customers |
GET /customers GET /customers/:id |
customer/activated customer/created customer/deactivated customer/payment_method_updated customer/updated |
addresses metafields payment_methods (beta)subscriptions |
addresses metafields |
Orders |
GET /orders GET /orders/:id |
order/cancelled order/created order/deleted order/processed order/upcoming order/updated |
customer metafields |
customer metafields |
Products |
GET /products GET /products/:id |
product/created product/deleted product/updated |
collections metafields |
collections metafields |
Subscriptions |
GET /subscriptions GET /subscriptions/:id |
subscription/activated subscription/cancelled subscription/created subscription/deleted subscription/skipped subscription/updated subscription/unskipped subscription/paused |
address metafields |
metafields |
Page Based Pagination
By default API calls will return 50 results. By using the limit
parameter that can be increased to 250 results.
When there are more results than can fit on a page you may loop through the results by using the page
parameter.
To request a page, include page
as a parameter in the url.
E.g. https://api.rechargeapps.com/subscriptions?limit=250&page=1
The example to the right shows a loop through all Subscription
by page.
With minor changes this example can be used for looping through any object type: Customers, Addresses etc.
Page based pagination deep into large data sets is not recommended due to performance degradation. To paginate deeper into a data set, we recommend exploring cursor pagination instead.
# request the first page (page=1)
curl -i -H 'X-Recharge-Access-Token: your_api_token'
-X GET https://api.rechargeapps.com/subscriptions?limit=250&page=1
# request next page of results (page=2)
curl -i -H 'X-Recharge-Access-Token: your_api_token'
-X GET https://api.rechargeapps.com/subscriptions?limit=250&page=2
id: 123
id: 456
# ... continues through 250 records
page: 1 result_size: 250
id: 567
id: 678
# ... continues through 250 records
page: 2 result_size: 250
id: 567
id: 678
# ... continues through only 10 records, no further pages needed
page: 3 result_size: 10
Cursor Pagination
By default API calls will return 50 results. By using the limit
parameter that can be increased to 250 results. When there are more results than the current limit
a cursor may be used to request additional results.
Cursor based pagination is the preferred method for looping through all records in a given data set, as it is more performant than specifying a page number along with number of results. This method also provides more assurance that you will receive all of the records in a given set.
Cursor based pagination works by providing a reference to a specific item in a list of sequential data which will represent the cursor, such as a numeric id. You can then specify whether you would like to query records starting before or starting after that item.
For convenience, the API provides a Link
header in all responses for which there are further pages. This header contains both a next_cursor
and previous_cursor
link, which is just a URL with an encoded page_info
parameter that contains any filters from your first call, as well as markers to let the API know where it left off and where to begin for the next call.
Please note that the only compatible filter allowed to be used with cursors is limit
.
Supported endpoints for Link |
---|
GET /addresses |
GET /async_batches |
GET /async_batches/:id/tasks |
GET /charges |
GET /customers |
GET /discounts |
GET /orders |
GET /products |
GET /subscriptions |
/charges
requests which supply either the updated_at_min
or created_at_min
filter will not currently return a Link
header.Requests which contain a filter for ids,
shopify_product_ids
will not return a Link
header.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 charge_date-asc charge_date-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 created_at-asc created_at-desc shipped_date-asc shipped_date-desc shipping_date-asc shipping_date-desc updated_at-asc updated_at-desc |
Product |
Default: id-desc Options: id-asc id-desc created_at-asc created_at-desc updated_at-asc updated_at-desc title-asc title-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
Addresses represents one of the many shipping locations a customer may have. Subscriptions are tied to a given address. Each customer can have multiple address objects (many to one aka n:1) in the relationship.
The address object
Addresses represents one of the many shipping locations a customer may have. Subscriptions are tied to a given address. Each customer can have multiple address objects (many to one aka n:1) in the relationship.
Attributes
- idinteger
Unique numeric identifier for the
Address
. - address1string
The street associated with the
Address
. - address2string
Any additional information associated with the shipping address.
The note that that will be passed to the
note
field ofOrders
made within theAddress
.cart_note
is not currently honored when sent to the Shopify contract api (SCI).- citystring
The city associated with the shipping address.
- companystring
The company associated with the shipping address.
- countrystring
The country associated with the shipping address.
- country_codestring
The 2-letter country code.
- customer_idinteger
Unique numeric identifier for the
Customer
associated with theAddress
. - discount_idinteger
Unique numeric identifier of
Discount
that is applied on theAddress
. - first_namestring
The customer’s first name associated with the address.
- last_namestring
The customer’s last name associated with the address.
Extra information that is added to the order.
note_attributes
is not currently honored when sent to the Shopify contract api (SCI).Show object attributes- phonestring
The phone number associated with the address.
Presentment currency is the currency used to display prices to the associated on a storefront and at checkout.
Only set if the currency is different from the store-level currency. Else, will default to store-level currency.
- provincestring
The state or province associated with the address.
- shipping_lines_overridearray
Used when shipping rates need to be overridden. If this parameter has value
null
, rates will be fetched when a relatedCharge
is created or regeneratedShow object attributes - zipstring
The zip or postal code associated with the address.
Error related attributes
More Attributes
- cart_attributesarray
Additional information added to an initial order.
Important: This field will be deprecated. Please use
note_attributes
instead. - created_atdatetime
The date and time when the address was created.
- original_shipping_lines
Shipping line details.
Important: This field will be deprecated. Please use
shipping_lines_override
instead. - updated_atdatetime
The date and time when the
Address
was last updated.
{
"address": {
"id": 21317826,
"address1": "1776 Washington Street",
"address2": "",
"cart_note": null,
"city": "Los Angeles",
"company": "Recharge",
"country": "United States",
"country_code": "US",
"created_at": "2018-11-14T09:00:01",
"customer_id": 18819267,
"discount_id": null,
"first_name": "John",
"last_name": "Doe",
"note_attributes": [
{
"name": "custom name",
"value": "custom value"
}
],
"original_shipping_lines": [
{
"code": "Standard Shipping",
"price": "0.00",
"title": "Standard Shipping"
}
],
"phone": "5551234567",
"presentment_currency": null,
"province": "California",
"shipping_lines_override": null,
"updated_at": "2018-11-14T09:00:01",
"zip": "90404"
}
}
Create an address
Create a new address for a customer.
Body Parameters
- address1string* Required
The street associated with the
Address
. Minimum length is 1 character. If country is “United States” then validate with UPS external service. - address2string
Any additional information associated with the shipping address.
- cart_notestring
The note that that will be passed to the
note
field ofOrders
made within theAddress
.cart_note
is not currently honored when sent to the Shopify contract api (SCI). - citystring* Required
The city associated with the shipping address. Minimum length is 1 character. If country is “United States” then validate with UPS external service.
- companystring
The company associated with the shipping address.
- countrystring* Required
The country associated with the shipping address. Minimal length is 1 character. Check if the store supports shipping to this country. This is set by the merchant in their Shipping Settings page.
- first_namestring* Required
The customer’s first name associated with the address. Minimum length is 1 character.
- last_namestring* Required
The customer’s last name associated with the address. Minimum length is 1 character.
- note_attributesarray
Extra information that is added to the order.
note_attributes
is not currently honored when sent to the Shopify contract api (SCI).Show object attributes - phonestring* Required
The phone number associated with the address. Must be included in the request schema but can be an empty string.
- presentment_currencystring
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.
- provincestring* Required
The state or province associated with the address. Check if country requires a province
COUNTRIES_REQUIRING_PROVINCE
. If country isUnited States
then validate with UPS external service. - shipping_lines_overridearray
Used when shipping rates need to be overridden. If this parameter has value
null
, rates will be fetched when a relatedCharge
is created or regeneratedShow object attributes - zipstring* 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 isUnited States
then validate against regexUNITED_STATES_ZIP_REGEX
and validate with UPS external service. If country isUnited Kingdom
then validate against regexUNITED_KINGDOM_ZIP_REGEX
.
More Parameters
- cart_attributesarray
Additional information added to an initial order.
Important note: This field will be deprecated. Please use
note_attributes
instead. - original_shipping_lines
Shipping line details.
Important note: This field will be deprecated. Please use
shipping_lines_override
instead.
Responses
- 200
successful response
Show response object
curl 'https://api.rechargeapps.com/customers/3411137/addresses' \
-H 'Content-Type: application/json' \
-H 'X-Recharge-Access-Token: your_api_token' \
-d '{
"address1": "1776 Washington Street",
"address2": "",
"city": "Los Angeles",
"company": "Recharge",
"country": "United States",
"first_name": "John",
"last_name": "Doe",
"note_attributes": [
{
"name": "custom name",
"value": "custom value"
}
],
"phone": "5551234567",
"presentment_currency": "USD",
"province": "California",
"shipping_lines_override": [
{
"code": "Standard Shipping",
"price": "0.00",
"title": "Standard Shipping"
}
],
"zip": "90404"
}'
{
"address": {
"id": 21317826,
"address1": "1776 Washington Street",
"address2": "",
"cart_note": null,
"city": "Los Angeles",
"company": "Recharge",
"country": "United States",
"country_code": "US",
"created_at": "2018-11-14T09:00:01",
"customer_id": 18819267,
"discount_id": null,
"first_name": "John",
"last_name": "Doe",
"note_attributes": [
{
"name": "custom name",
"value": "custom value"
}
],
"shipping_lines_override": [
{
"code": "Standard Shipping",
"price": "0.00",
"title": "Standard Shipping"
}
],
"phone": "5551234567",
"presentment_currency": "USD",
"province": "California",
"updated_at": "2018-11-14T09:00:01",
"zip": "90404"
}
}
Retrieve an address
Retrieves address for customer based on specified address id.
Responses
- 200
successful response
Show response object
curl 'https://api.rechargeapps.com/addresses/21317826' \
-H 'X-Recharge-Access-Token: your_api_token'
{
"address": {
"id": 21317826,
"address1": "6419 Ocean Front Walk",
"address2": "Apt 1",
"cart_note": null,
"city": "Los Angeles",
"company": "",
"country": "United States",
"country_code": "US",
"created_at": "2020-06-16T12:45:35",
"customer_id": 43845860,
"discount_id": null,
"first_name": "Nikola",
"last_name": "Tesla",
"note_attributes": [
{
"name": "custom name",
"value": "custom value"
}
],
"original_shipping_lines": [
{
"code": "Standard Shipping",
"price": "0.00",
"title": "Standard Shipping"
}
],
"phone": "1-800-800-8000",
"presentment_currency": null,
"province": "California",
"shipping_lines_override": null,
"updated_at": "2020-07-10T11:12:58",
"zip": "90293"
}
}
Update an address
Updates an existing address to match the specified parameters.
When updating the country
property you will have to update the zip
property as well, otherwise you will receive an error.
Body Parameters
- address1string
The street associated with the
Address
. Minimum length is 1 character. If country is “United States” then validate with UPS external service. - address2string
Any additional information associated with the shipping address.
The note that that will be passed to the
note
field ofOrders
made within theAddress
.cart_note
is not currently honored when sent to the Shopify contract api (SCI).- citystring
The city associated with the shipping address. Minimum length is 1 character. If country is “United States” then validate with UPS external service.
- companystring
The company associated with the shipping address.
- countrystring
The country associated with the shipping address. Minimal length is 1 character. Check if the store supports shipping to this country. This is set by the merchant in their Shipping Settings page.
- first_namestring
The customer’s first name associated with the address. Minimum length is 1 character.
- last_namestring
The customer’s last name associated with the address. Minimum length is 1 character.
Extra information that is added to the order.
note_attributes
is not currently honored when sent to the Shopify contract api (SCI).Show object attributes- phonestring
The phone number associated with the address. Must be included in the request schema but can be an empty string.
- provincestring
The state or province associated with the address. Check if country requires a province
COUNTRIES_REQUIRING_PROVINCE
. If country isUnited States
then validate with UPS external service. Used when shipping rates need to be overridden. If this parameter has value
null
, rates will be fetched when a relatedCharge
is created or regeneratedShow object attributes- zipstring
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 isUnited States
then validate against regexUNITED_STATES_ZIP_REGEX
and validate with UPS external service. If country isUnited Kingdom
then validate against regexUNITED_KINGDOM_ZIP_REGEX
.
More Parameters
- cart_attributesarray
Additional information added to an initial order.
Important note: This field will be deprecated. Please use
note_attributes
instead. - original_shipping_lines
Shipping line details.
Important note: This field will be deprecated. Please use
shipping_lines_override
instead.
Responses
- 200
successful response
Show response object
curl -X PUT 'https://api.rechargeapps.com/addresses/21317826' \
-H 'Content-Type: application/json' \
-H 'X-Recharge-Access-Token: your_api_token' \
-d '{"address1": "3020 Nebraska Avenue"}'
{
"address": {
"id": 21317826,
"address1": "3020 Nebraska Avenue",
"address2": "",
"cart_note": null,
"city": "Los Angeles",
"company": "Recharge",
"country": "United States",
"country_code": "US",
"created_at": "2018-11-14T09:00:01",
"customer_id": 18819267,
"discount_id": null,
"first_name": "John",
"last_name": "Doe",
"note_attributes": [
{
"name": "custom name",
"value": "custom value"
}
],
"original_shipping_lines": [
{
"code": "Standard Shipping",
"price": "0.00",
"title": "Standard Shipping"
}
],
"phone": "5551234567",
"presentment_currency": null,
"province": "California",
"shipping_lines_override": null,
"updated_at": "2018-11-14T09:00:01",
"zip": "90404"
}
}
Delete an address
It is possible to delete certain addresses from the store using API. However, there are some rules for deleting them. Note: Only Addresses with no active subscriptions can be deleted.
Responses
- 200
successful response
Show response object
curl -X DELETE 'https://api.rechargeapps.com/addresses/21317826' \
-H 'X-Recharge-Access-Token: your_api_token'
{}
List addresses
Returns all addresses from the store, or addresses for the user given in the parameter.
HTTPS request examples
GET /addresses
GET /customers/:id/addresses
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
Query Parameters
- created_at_maxstring
Returns addresses created before the given time.
- created_at_minstring
Returns addresses created after the given time.
- customer_idinteger
Unique numeric identifier for the customer associated with the address.
- discount_codestring
Returns addresses that have the provided discount_code.
- discount_idstring
Returns addresses that have the provided discount_id.
- idsstring
Filter addresses by id. If passing multiple values, must be comma separated. Non-integer values will result in a 422 error
- limitstring
Default: 50
Max: 250
The amount of results. Default is 50 while the maximum is 250.
- pagestring
Default: 1
The page to show. Default is 1.
- updated_at_maxstring
Returns addresses updated before the given date.
- updated_at_minstring
Returns addresses updated after the given time.
More Parameters
Responses
- 200
successful response
Show response object
curl 'https://api.rechargeapps.com/addresses' \
-H 'X-Recharge-Access-Token: your_api_token' \
-d limit=3 -G
{
"addresses": [
{
"id": 48563471,
"address1": "6419 Ocean Front Walk",
"address2": "Apt 1",
"cart_note": null,
"city": "Los Angeles",
"company": "",
"country": "United States",
"country_code": "US",
"created_at": "2020-06-16T12:45:35",
"customer_id": 43845860,
"discount_id": null,
"first_name": "Nikola",
"last_name": "Tesla",
"note_attributes": [
{
"name": "custom name",
"value": "custom value"
}
],
"original_shipping_lines": [],
"phone": "1-800-800-8000",
"presentment_currency": null,
"province": "California",
"shipping_lines_override": null,
"updated_at": "2020-07-10T11:12:58",
"zip": "90293"
}
]
}
Count addresses
Retrieve the count of addresses.
HTTPS request examples
GET /addresses/count
GET /addresses/count?discount_code=10PERCENTOFF
GET /addresses/count?discount_id=123123123
GET /addresses/count?created_at_min=2019-11-11
GET /addresses/count?created_at_max=2019-11-11
GET /addresses/count?updated_at_min=2019-11-11
GET /addresses/count?updated_at_max=2019-11-11
GET /addresses/count?created_at_min=2019-11-10&updated_at_max=2019-11-11
Notes: you can combine multiple parameters with &
Query Parameters
- created_at_maxstring
Returns addresses created before the given time.
- created_at_minstring
Returns addresses created after the given time.
- discount_codestring
Returns addresses that have the provided discount_code.
- discount_idstring
Returns addresses that have the provided discount_id.
- updated_at_maxstring
Returns addresses updated before the given date.
- updated_at_minstring
Returns addresses updated after the given time.
More Parameters
Responses
- 200
successful response
Show response object
curl 'https://api.rechargeapps.com/addresses/count' \
-H 'X-Recharge-Access-Token: your_api_token'
{
"count": 6000
}
Validate an address
USA only
It is important to validate an address before attempting to create charges for it, as at that point the user may no longer be available to edit incorrect values.
Address validation works only for USA addresses.
Body Parameters
- address1string* Required
The street associated with the address.
- citystring* Required
The city associated with the address.
- statestring* Required
The state associated with the address.
- zipcodestring* Required
The zip or postal code associated with the address.
More Parameters
Responses
- 200
successful response
Show response object
curl 'https://api.rechargeapps.com/addresses/validate' \
-H 'Content-Type: application/json' \
-H 'X-Recharge-Access-Token: your_api_token' \
-d '{
"address1": "1776 Washington Street",
"city": "santa monica",
"state": "California",
"zipcode": "90404"
}'
{
"city": "santa monica",
"errors": {},
"state": "CA",
"state_name": "California",
"zipcode": "90404"
}
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). Order
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).
The charge object
A Charge
is the representation of the financial transaction linked to a purchase (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 for pay as you go subscriptions and several for pre-paid).
A Charge
can have many parent subscriptions. All subscriptions on a given Address
with the same next_charge_date
date will be merged into one Charge
and that charge will contain one line_item
per Subscription
.
Attributes
- idinteger
The unique numeric identifier for the charge.
- address_idinteger
The customer shipping address the charge is tied to.
- analytics_dataobject
An object containing analytics data associated with the charge.
Show object attributes - billing_addressobject
All the billing information related to the charge.
Show object attributes - client_detailsobject
Details of the access method used by the purchaser.
Show object attributes - created_atdatetime
When the
Charge
was created. - customer_hashstring
The
hash
of theCustomer
associated with the charge. - customer_idstring
The
id
of theCustomer
associated with the charge. - discount_codesobject
An array of discounts associated with the charge.
Show object attributes - emailstring
The email address of the customer.
- first_namestring
The first name of the customer.
- last_namestring
The last name of the customer.
- line_itemsarray
A list of
line_item
objects, each one containing information about an item in the charge. Oneline_item
per subscription.Show object attributes - notestring
Shows the next order in sequence.
- note_attributesarray
note attributes.
Show object attributes - processor_namestring
The payment processor used on the charge.
- processed_atdatetime
The date and time when the transaction was processed.
- scheduled_atdatetime
When the charge processing will next be attempted.
If a charge failed to process,
scheduled_at
remains the initial scheduled date of the processing not the date of the next attempt. - shipments_countinteger
The number of successfully processed child orders on the charge.
- shipping_addressobject
The shipping address of the shipping address.
Show object attributes - shipping_linesarray
An array of shipping lines associated with the charge.
Show object attributes - shopify_order_idinteger
The unique numeric identifier within Shopify for the charge
- statusstring
Possible values: SUCCESS, ERROR, QUEUED, SKIPPED, REFUNDED, PARTIALLY_REFUNDED
The status of the charge.
- subtotal_pricestring
The item price without taxes and shipping.
- tagsarray
Array of strings used to distinguish specific charges.
- tax_linesarray
Array of strings used to distinguish specific charges.
Show object attributes - total_discountsstring
The sum of the discounts applied to the
Charge
. - total_line_items_pricestring
The sum of all the prices of all the items in the charge.
- total_pricestring
The sum of all the prices of all the items in the charge, taxes and discounts included (must be positive).
- total_refundsstring
The sum of all refunds that were made on specific charge.
- total_weightstring
The sum of all refunds that were made on specific charge.
- transaction_idstring
The unique alphanumeric identifier of the transaction.
- typestring
Possible values: CHECKOUT, RECURRING
The type of the charge.
- updated_atdatetime
The date and time when the
Charge
was last updated.
Error related attributes
- errorstring
Error reason as sentence text (typically returned direct from the payment processor). e.g.
"Customer needs to update credit card"
- error_typestring
Structured reason why the charge failed such as
CUSTOMER_NEEDS_TO_UPDATE_CARD
- last_charge_attempt_datedatetime
The date when a charge was last attempted.
- number_times_triedinteger
Shows how many times an attempt to charge was placed.
- retry_datedate
The date when the next attempt will be placed.
- shopify_variant_id_not_foundinteger
Indicates if Recharge was able to find the
shopify_variant_id
from the charge.
More Attributes
- has_uncommited_changes
Specifies whether the charge is scheduled for a regeneration (if the subscription related to the charge was updated in the last 5 seconds using “commit_update”:false).
- sub_total
The item price without taxes and discounts. Use subtotal_price instead.
{
"charge": {
"id": 100714428,
"address_id": 21317826,
"analytics_data": {
"utm_params": [
{
"utm_campaign": "spring_sale",
"utm_content": "differentiate-content",
"utm_data_source": "shopify_cookie",
"utm_medium": "email",
"utm_source": "newsletter",
"utm_term": "test-term",
"utm_time_stamp": "2019-12-16T23:57:28.752Z"
}
]
},
"billing_address": {
"address1": "3030 Nebraska Avenue",
"address2": null,
"city": "Los Angeles",
"company": null,
"country": "United States",
"first_name": "Mike",
"last_name": "Flynn",
"phone": "3103843698",
"province": "California",
"zip": "90404"
},
"client_details": {
"browser_ip": null,
"user_agent": null
},
"created_at": "2018-11-14T09:45:44",
"customer_hash": "18819267b1f9095be98f13a8",
"customer_id": 18819267,
"discount_codes": [],
"email": "example_mail@gmail.com",
"first_name": "Mike",
"has_uncommited_changes": false,
"last_name": "Flynn",
"line_items": [
{
"grams": 4536,
"images": {
"large": "https://cdn.shopify.com/s/files/1/0175/0695/9460/products/Sumatra_Coffee_large.png",
"medium": "https://cdn.shopify.com/s/files/1/0175/0695/9460/products/Sumatra_Coffee__medium.png",
"original": "https://cdn.shopify.com/s/files/1/0175/0695/9460/products/Sumatra_Coffee_.png",
"small": "https://cdn.shopify.com/s/files/1/0175/0695/9460/products/Sumatra_Coffee__small.png"
},
"original_price": "12.00",
"price": "12.00",
"properties": [
{
"name": "grind",
"value": "drip"
}
],
"quantity": 1,
"shopify_product_id": "1255183683",
"shopify_variant_id": "3844924611",
"sku": "MILK-1",
"subscription_id": 27363808,
"title": "Sumatra Coffee",
"variant_title": "Milk - a / b"
}
],
"note": "next order #1",
"note_attributes": [
{
"name": "custom name",
"value": "custom value"
}
],
"processor_name": "stripe",
"scheduled_at": "2018-12-12T00:00:00",
"shipments_count": null,
"shipping_address": {
"address1": "3030 Nebraska Avenue",
"address2": "",
"city": "Los Angeles",
"company": "Recharge",
"country": "United States",
"first_name": "Mike",
"last_name": "Flynn",
"phone": "3103843698",
"province": "California",
"zip": "90404"
},
"shipping_lines": [
{
"code": "Standard Shipping",
"price": "0.00",
"title": "Standard Shipping"
}
],
"shopify_order_id": 12345,
"status": "QUEUED",
"sub_total": 12,
"subtotal_price": "12:00",
"tags": "Subscription",
"tax_lines": [
{
"price": "0.950",
"rate": 0.0725,
"title": "CA State Tax"
},
{
"price": "0.335",
"rate": 0.0225,
"title": "Los Angeles County Tax"
}
],
"total_discounts": "0.0",
"total_line_items_price": "12.00",
"total_price": "12.00",
"total_refunds": null,
"total_tax": 0,
"total_weight": 4536,
"transaction_id": "cch_1Du2QpJ2iqHvZRd18RyqoPvc",
"type": "RECURRING",
"updated_at": "2018-11-14T09:45:44"
}
}
Retrieve a charge
Retrieve a charge using the Recharge charge id.
Responses
- 200
successful response
Show response object
curl 'https://api.rechargeapps.com/charges/100714428' \
-H 'X-Recharge-Access-Token: your_api_token'
{
"charge": {
"id": 100714428,
"address_id": 21317826,
"analytics_data": {
"utm_params": [
{
"utm_campaign": "spring_sale",
"utm_content": "differentiate-content",
"utm_data_source": "shopify_cookie",
"utm_medium": "email",
"utm_source": "newsletter",
"utm_term": "test-term",
"utm_time_stamp": "2019-12-16T23:57:28.752Z"
}
]
},
"billing_address": {
"address1": "3030 Nebraska Avenue",
"address2": null,
"city": "Los Angeles",
"company": null,
"country": "United States",
"first_name": "Mike",
"last_name": "Flynn",
"phone": "3103843698",
"province": "California",
"zip": "90404"
},
"client_details": {
"browser_ip": null,
"user_agent": null
},
"created_at": "2018-11-14T09:45:44",
"customer_hash": "18819267b1f9095be98f13a8",
"customer_id": 18819267,
"discount_codes": [],
"email": "example_mail@gmail.com",
"first_name": "Mike",
"has_uncommited_changes": false,
"last_name": "Flynn",
"line_items": [
{
"grams": 4536,
"images": {
"large": "https://cdn.shopify.com/s/files/1/0175/0695/9460/products/Sumatra_Coffee_large.png",
"medium": "https://cdn.shopify.com/s/files/1/0175/0695/9460/products/Sumatra_Coffee__medium.png",
"original": "https://cdn.shopify.com/s/files/1/0175/0695/9460/products/Sumatra_Coffee_.png",
"small": "https://cdn.shopify.com/s/files/1/0175/0695/9460/products/Sumatra_Coffee__small.png"
},
"original_price": "12.00",
"price": "12.00",
"properties": [
{
"name": "grind",
"value": "drip"
}
],
"quantity": 1,
"shopify_product_id": "1255183683",
"shopify_variant_id": "3844924611",
"sku": "MILK-1",
"subscription_id": 27363808,
"title": "Sumatra Coffee",
"variant_title": "Milk - a / b"
}
],
"note": "next order #1",
"note_attributes": [
{
"name": "custom name",
"value": "custom value"
}
],
"processor_name": "stripe",
"scheduled_at": "2018-12-12T00:00:00",
"shipments_count": null,
"shipping_address": {
"address1": "3030 Nebraska Avenue",
"address2": "",
"city": "Los Angeles",
"company": "Recharge",
"country": "United States",
"first_name": "Mike",
"last_name": "Flynn",
"phone": "3103843698",
"province": "California",
"zip": "90404"
},
"shipping_lines": [
{
"code": "Standard Shipping",
"price": "0.00",
"title": "Standard Shipping"
}
],
"shopify_order_id": 12345,
"status": "QUEUED",
"sub_total": 12,
"subtotal_price": "12:00",
"tags": "Subscription",
"tax_lines": [
{
"price": "0.950",
"rate": 0.0725,
"title": "CA State Tax"
},
{
"price": "0.335",
"rate": 0.0225,
"title": "Los Angeles County Tax"
}
],
"total_discounts": "0.0",
"total_line_items_price": "12.00",
"total_price": "12.00",
"total_refunds": null,
"total_tax": 0,
"total_weight": 4536,
"transaction_id": "cch_1Du2QpJ2iqHvZRd18RyqoPvc",
"type": "RECURRING",
"updated_at": "2018-11-14T09:45:44"
}
}
List charges
Returns a list of charges.
HTTPS request examples
GET /charges?address_id=21317826
GET /charges?customer_id=18819267
GET /charges?date_min=2021-05-18&date_max=2021-06-18
GET /charges?discount_code=10PERCENTOFF
GET /charges?discount_id=753963
GET /charges?ids=1123551,262667345,12341535
GET /charges?shopify_order_id=7895652
GET /charges?sort_by=id-desc
GET /charges?status=queued
GET /charges?status=queued,refunded,partially_refunded
GET /charges?subscription_id=753489514
Reminder: returned charges are sorted ascending by id value by default.
Query Parameters
- address_idstring
Filter charges by address.
- created_at_maxstring
Show charges created before the given date.
- created_at_minstring
Show charges created after the given date.
- customer_idstring
Filter charges by customer.
- datestring
Show charges scheduled on the given date.
- date_maxstring
Show charges scheduled before the given date.
- date_minstring
Show charges scheduled after the given date.
- discount_codestring
List charges that contain the given
discount_code
. - discount_idstring
List charges that contain the given
discount_id
. - idsstring
Filter charges by
id
. If passing multiple values, must be comma separated.Non-integer values will result in a
422
error. - limitstring
Default: 50
Max: 250
The amount of results.
- pagestring
Default: 1
The page to show.
The maximum value of this attribute is 100. If you need data past this point use cursor pagination.
- shopify_order_idstring
Filter charges by
shopify_order_id
. - statusstring
Possible values: SUCCESS, QUEUED, ERROR, REFUNDED, PARTIALLY_REFUNDED, SKIPPED
Filter charges by status
- subscription_idstring
Filter charges by
subscription_id
. - updated_at_maxstring
Show charges updated before the given date.
- updated_at_minstring
Show charges updated after the given date.
More Parameters
Responses
- 200
successful response
Show response object
curl 'https://api.rechargeapps.com/charges' \
-H 'X-Recharge-Access-Token: your_api_token' \
-d limit=3 -G
{
"charges": [
{
"id": 100714428,
"address_id": 21317826,
"analytics_data": {
"utm_params": [
{
"utm_campaign": "spring_sale",
"utm_content": "differentiate-content",
"utm_data_source": "shopify_cookie",
"utm_medium": "email",
"utm_source": "newsletter",
"utm_term": "test-term",
"utm_time_stamp": "2019-12-16T23:57:28.752Z"
}
]
},
"billing_address": {
"address1": "3030 Nebraska Avenue",
"address2": null,
"city": "Los Angeles",
"company": null,
"country": "United States",
"first_name": "Mike",
"last_name": "Flynn",
"phone": "3103843698",
"province": "California",
"zip": "90404"
},
"client_details": {
"browser_ip": null,
"user_agent": null
},
"created_at": "2018-11-14T09:45:44",
"customer_hash": "18819267b1f9095be98f13a8",
"customer_id": 18819267,
"discount_codes": [],
"email": "example_mail@gmail.com",
"first_name": "Mike",
"has_uncommited_changes": false,
"last_name": "Flynn",
"line_items": [
{
"grams": 4536,
"images": {
"large": "https://cdn.shopify.com/s/files/1/0175/0695/9460/products/Sumatra_Coffee_large.png",
"medium": "https://cdn.shopify.com/s/files/1/0175/0695/9460/products/Sumatra_Coffee__medium.png",
"original": "https://cdn.shopify.com/s/files/1/0175/0695/9460/products/Sumatra_Coffee_.png",
"small": "https://cdn.shopify.com/s/files/1/0175/0695/9460/products/Sumatra_Coffee__small.png"
},
"original_price": "12.00",
"price": "12.00",
"properties": [
{
"name": "grind",
"value": "drip"
}
],
"quantity": 1,
"shopify_product_id": "1255183683",
"shopify_variant_id": "3844924611",
"sku": "MILK-1",
"subscription_id": 27363808,
"title": "Sumatra Coffee",
"variant_title": "Milk - a / b"
}
],
"note": " next order #1 - Subscription Recurring Order",
"note_attributes": null,
"processor_name": "stripe",
"scheduled_at": "2018-12-19T00:00:00",
"shipments_count": null,
"shipping_address": {
"address1": "3030 Nebraska Avenue",
"address2": "",
"city": "Los Angeles",
"company": "Recharge",
"country": "United States",
"first_name": "Mike",
"last_name": "Flynn",
"phone": "3103843698",
"province": "California",
"zip": "90404"
},
"shipping_lines": [
{
"code": "Standard Shipping",
"price": "0.00",
"title": "Standard Shipping"
}
],
"shopify_order_id": null,
"status": "QUEUED",
"sub_total": null,
"subtotal_price": "12: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"
}
],
"total_discounts": "0.0",
"total_line_items_price": "12.00",
"total_price": "12.00",
"total_refunds": null,
"total_tax": 0,
"total_weight": 4536,
"transaction_id": "cch_1Du2QpJ2iqHvZRd18RyqoPvc",
"type": "RECURRING",
"updated_at": "2018-11-14T10:08:14"
}
]
}
Count charges
Retrieve a count of charges.
HTTPS request examples
GET /charges/count
GET /charges/count?address_id=10175825
GET /charges/count?customer_id=10101
GET /charges/count?date_min=2019-11-10&date_max=2019-11-11
GET /charges/count?discount_code=10PERCENTOFF
GET /charges/count?discount_id=18493516
GET /charges/count?shopify_order_id=281223307
GET /charges/count?status=queued
GET /charges/count?status=queued,refunded,partially_refunded
GET /charges/count?subscription_id=14562
Reminder: returned charges are sorted ascending by id value.
Query Parameters
- address_idstring
Filter charges by address.
- customer_idstring
Filter charges by customer.
- datestring
Show charges scheduled on the given date.
- date_maxstring
Show charges scheduled before the given date.
- date_minstring
Show charges scheduled after the given date.
- discount_idstring
List charges that contain the given discount_id.
- shopify_order_idinteger
Filter charges by shopify_order_id.
- statusstring
Filter charges by status. Available status: SUCCESS, QUEUED, ERROR, REFUNDED, PARTIALLY_REFUNDED, SKIPPED.
- subscription_idstring
Filter charges by subscription_id.
More Parameters
Responses
- 200
successful response
Show response object
curl 'https://api.rechargeapps.com/charges/count' \
-H 'X-Recharge-Access-Token: your_api_token'
{
"count": 38667
}
Change next charge date
Modify the next_charge_date of the subscription.
If there are two queued Charges
with the same address_id
, and you update their scheduled_at
attribute to match, they will be merged into one Charge
.
Body Parameters
- next_charge_datestring* Required
Next charge date in ISO 8601 format.
More Parameters
Responses
- 200
successful response
Show response object
curl 'https://api.rechargeapps.com/charges/100714428/change_next_charge_date' \
-H 'Content-Type: application/json' \
-H 'X-Recharge-Access-Token: your_api_token' \
-d '{"next_charge_date": "2021-12-19"}'
{
"charge": {
"id": 100714428,
"address_id": 21317826,
"analytics_data": {
"utm_params": [
{
"utm_campaign": "spring_sale",
"utm_content": "differentiate-content",
"utm_data_source": "shopify_cookie",
"utm_medium": "email",
"utm_source": "newsletter",
"utm_term": "test-term",
"utm_time_stamp": "2019-12-16T23:57:28.752Z"
}
]
},
"billing_address": {
"address1": "3030 Nebraska Avenue",
"address2": null,
"city": "Los Angeles",
"company": null,
"country": "United States",
"first_name": "Mike",
"last_name": "Flynn",
"phone": "3103843698",
"province": "California",
"zip": "90404"
},
"client_details": {
"browser_ip": null,
"user_agent": null
},
"created_at": "2018-11-14T09:45:44",
"customer_hash": "18819267b1f9095be98f13a8",
"customer_id": 18819267,
"discount_codes": [],
"email": "example_mail@gmail.com",
"first_name": "Mike",
"has_uncommited_changes": false,
"last_name": "Flynn",
"line_items": [
{
"grams": 4536,
"images": {
"large": "https://cdn.shopify.com/s/files/1/0175/0695/9460/products/Sumatra_Coffee_large.png",
"medium": "https://cdn.shopify.com/s/files/1/0175/0695/9460/products/Sumatra_Coffee__medium.png",
"original": "https://cdn.shopify.com/s/files/1/0175/0695/9460/products/Sumatra_Coffee_.png",
"small": "https://cdn.shopify.com/s/files/1/0175/0695/9460/products/Sumatra_Coffee__small.png"
},
"original_price": "12.00",
"price": "12.00",
"properties": [
{
"name": "grind",
"value": "drip"
}
],
"quantity": 1,
"shopify_product_id": "1255183683",
"shopify_variant_id": "3844924611",
"sku": "MILK-1",
"subscription_id": 27363808,
"title": "Sumatra Coffee",
"variant_title": "Milk - a / b"
}
],
"note": " next order #1 - Subscription Recurring Order",
"note_attributes": null,
"processor_name": "stripe",
"scheduled_at": "2021-12-19T00:00:00",
"shipments_count": null,
"shipping_address": {
"address1": "3030 Nebraska Avenue",
"address2": "",
"city": "Los Angeles",
"company": "Recharge",
"country": "United States",
"first_name": "Mike",
"last_name": "Flynn",
"phone": "3103843698",
"province": "California",
"zip": "90404"
},
"shipping_lines": [
{
"code": "Standard Shipping",
"price": "0.00",
"title": "Standard Shipping"
}
],
"shopify_order_id": null,
"status": "QUEUED",
"sub_total": null,
"subtotal_price": "12.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"
}
],
"total_discounts": "0.0",
"total_line_items_price": "12.00",
"total_price": "12.00",
"total_refunds": null,
"total_tax": 0,
"total_weight": 4536,
"transaction_id": "cch_1Du2QpJ2iqHvZRd18RyqoPvc",
"type": "RECURRING",
"updated_at": "2018-11-14T09:59:28"
}
}
Skip a charge
Skip the charge and generate the next Charge
in the schedule.
When a Charge
contains multiple line_items
and you only want to skip the charge for a subset of items, you can specify the specific subscription_id
OR subscriptions_ids
.
Responses
- 200
successful response
Show response object
curl 'https://api.rechargeapps.com/charges/100714428/skip' \
-H 'Content-Type: application/json' \
-H 'X-Recharge-Access-Token: your_api_token' \
-d '{"subscription_ids": ["27363808"]}'
{
"charge": {
"id": 100714428,
"address_id": 21317826,
"analytics_data": {
"utm_params": [
{
"utm_campaign": "spring_sale",
"utm_content": "differentiate-content",
"utm_data_source": "shopify_cookie",
"utm_medium": "email",
"utm_source": "newsletter",
"utm_term": "test-term",
"utm_time_stamp": "2019-12-16T23:57:28.752Z"
}
]
},
"billing_address": {
"address1": "3030 Nebraska Avenue",
"address2": null,
"city": "Los Angeles",
"company": null,
"country": "United States",
"first_name": "Mike",
"last_name": "Flynn",
"phone": "3103843698",
"province": "California",
"zip": "90404"
},
"client_details": {
"browser_ip": null,
"user_agent": null
},
"created_at": "2018-11-14T09:45:44",
"customer_hash": "18819267b1f9095be98f13a8",
"customer_id": 18819267,
"discount_codes": [],
"email": "example_mail@gmail.com",
"first_name": "Mike",
"has_uncommited_changes": false,
"last_name": "Flynn",
"line_items": [
{
"grams": 4536,
"images": {
"large": "https://cdn.shopify.com/s/files/1/0175/0695/9460/products/Sumatra_Coffee_large.png",
"medium": "https://cdn.shopify.com/s/files/1/0175/0695/9460/products/Sumatra_Coffee__medium.png",
"original": "https://cdn.shopify.com/s/files/1/0175/0695/9460/products/Sumatra_Coffee_.png",
"small": "https://cdn.shopify.com/s/files/1/0175/0695/9460/products/Sumatra_Coffee__small.png"
},
"original_price": "12.00",
"price": "12.00",
"properties": [
{
"name": "grind",
"value": "drip"
}
],
"quantity": 1,
"shopify_product_id": "1255183683",
"shopify_variant_id": "3844924611",
"sku": "MILK-1",
"subscription_id": 27363808,
"title": "Sumatra Coffee",
"variant_title": "Milk - a / b"
}
],
"note": " next order #1 - Subscription Recurring Order",
"note_attributes": null,
"processor_name": "stripe",
"scheduled_at": "2021-12-19T00:00:00",
"shipments_count": null,
"shipping_address": {
"address1": "3030 Nebraska Avenue",
"address2": "",
"city": "Los Angeles",
"company": "Recharge",
"country": "United States",
"first_name": "Mike",
"last_name": "Flynn",
"phone": "3103843698",
"province": "California",
"zip": "90404"
},
"shipping_lines": [
{
"code": "Standard Shipping",
"price": "0.00",
"title": "Standard Shipping"
}
],
"shopify_order_id": null,
"status": "QUEUED",
"sub_total": null,
"subtotal_price": "12.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"
}
],
"total_discounts": "0.0",
"total_line_items_price": "12.00",
"total_price": "12.00",
"total_refunds": null,
"total_tax": 0,
"total_weight": 4536,
"transaction_id": "cch_1Du2QpJ2iqHvZRd18RyqoPvc",
"type": "RECURRING",
"updated_at": "2018-11-14T09:59:28"
}
}
Unskip a charge
Unskip the charge.
When a Charge
contains multiple line_items
and you only want to unskip the charge for a subset of items, you can specify the specific subscription_id
OR subscriptions_ids
.
Responses
- 200
successful response
Show response object - 422
Unprocessable
Show response object
curl 'https://api.rechargeapps.com/charges/100714428/unskip' \
-H 'Content-Type: application/json' \
-H 'X-Recharge-Access-Token: your_api_token' \
-d '{"subscription_ids": ["27363808"]}'
{
"charge": {
"id": 100714428,
"address_id": 21317826,
"analytics_data": {
"utm_params": [
{
"utm_campaign": "spring_sale",
"utm_content": "differentiate-content",
"utm_data_source": "shopify_cookie",
"utm_medium": "email",
"utm_source": "newsletter",
"utm_term": "test-term",
"utm_time_stamp": "2019-12-16T23:57:28.752Z"
}
]
},
"billing_address": {
"address1": "3030 Nebraska Avenue",
"address2": null,
"city": "Los Angeles",
"company": null,
"country": "United States",
"first_name": "Mike",
"last_name": "Flynn",
"phone": "3103843698",
"province": "California",
"zip": "90404"
},
"client_details": {
"browser_ip": null,
"user_agent": null
},
"created_at": "2018-11-14T09:45:44",
"customer_hash": "18819267b1f9095be98f13a8",
"customer_id": 18819267,
"discount_codes": [],
"email": "example_mail@gmail.com",
"first_name": "Mike",
"has_uncommited_changes": false,
"last_name": "Flynn",
"line_items": [
{
"grams": 4536,
"images": {
"large": "https://cdn.shopify.com/s/files/1/0175/0695/9460/products/Sumatra_Coffee_large.png",
"medium": "https://cdn.shopify.com/s/files/1/0175/0695/9460/products/Sumatra_Coffee__medium.png",
"original": "https://cdn.shopify.com/s/files/1/0175/0695/9460/products/Sumatra_Coffee_.png",
"small": "https://cdn.shopify.com/s/files/1/0175/0695/9460/products/Sumatra_Coffee__small.png"
},
"original_price": "12.00",
"price": "12.00",
"properties": [
{
"name": "grind",
"value": "drip"
}
],
"quantity": 1,
"shopify_product_id": "1255183683",
"shopify_variant_id": "3844924611",
"sku": "MILK-1",
"subscription_id": 27363808,
"title": "Sumatra Coffee",
"variant_title": "Milk - a / b"
}
],
"note": " next order #1 - Subscription Recurring Order",
"note_attributes": null,
"processor_name": "stripe",
"scheduled_at": "2021-12-19T00:00:00",
"shipments_count": null,
"shipping_address": {
"address1": "3030 Nebraska Avenue",
"address2": "",
"city": "Los Angeles",
"company": "Recharge",
"country": "United States",
"first_name": "Mike",
"last_name": "Flynn",
"phone": "3103843698",
"province": "California",
"zip": "90404"
},
"shipping_lines": [
{
"code": "Standard Shipping",
"price": "0.00",
"title": "Standard Shipping"
}
],
"shopify_order_id": null,
"status": "QUEUED",
"sub_total": null,
"subtotal_price": "12.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"
}
],
"total_discounts": "0.0",
"total_line_items_price": "12.00",
"total_price": "12.00",
"total_refunds": null,
"total_tax": 0,
"total_weight": 4536,
"transaction_id": "cch_1Du2QpJ2iqHvZRd18RyqoPvc",
"type": "RECURRING",
"updated_at": "2018-11-14T09:59:28"
}
}
Refund a charge
Applies a refund to a Charge
.
After the refund, the Charge
will have status
parameter REFUNDED
or PARTIALLY_REFUNDED
.
Body Parameters
- amountstring* Required
Amount of money that will be refunded. It can be fully or partially refunded.
- full_refundboolean
If this parameter is set to
true
, the charge will be totally refunded.
More Parameters
Responses
- 200
successful response
Show response object
curl 'https://api.rechargeapps.com/charges/100714428/refund' \
-H 'Content-Type: application/json' \
-H 'X-Recharge-Access-Token: your_api_token' \
-d '{"amount": 11.00}'
{
"charge": {
"id": 100714428,
"address_id": 21317826,
"analytics_data": {
"utm_params": [
{
"utm_campaign": "spring_sale",
"utm_content": "differentiate-content",
"utm_data_source": "shopify_cookie",
"utm_medium": "email",
"utm_source": "newsletter",
"utm_term": "test-term",
"utm_time_stamp": "2019-12-16T23:57:28.752Z"
}
]
},
"billing_address": {
"address1": "3030 Nebraska Avenue",
"address2": null,
"city": "Los Angeles",
"company": null,
"country": "United States",
"first_name": "Mike",
"last_name": "Flynn",
"phone": "3103843698",
"province": "California",
"zip": "90404"
},
"client_details": {
"browser_ip": null,
"user_agent": null
},
"created_at": "2018-11-14T09:45:44",
"customer_hash": "18819267b1f9095be98f13a8",
"customer_id": 18819267,
"discount_codes": [],
"email": "example_mail@gmail.com",
"first_name": "Mike",
"has_uncommited_changes": false,
"last_name": "Flynn",
"line_items": [
{
"grams": 4536,
"images": {
"large": "https://cdn.shopify.com/s/files/1/0175/0695/9460/products/Sumatra_Coffee_large.png",
"medium": "https://cdn.shopify.com/s/files/1/0175/0695/9460/products/Sumatra_Coffee__medium.png",
"original": "https://cdn.shopify.com/s/files/1/0175/0695/9460/products/Sumatra_Coffee_.png",
"small": "https://cdn.shopify.com/s/files/1/0175/0695/9460/products/Sumatra_Coffee__small.png"
},
"original_price": "12.00",
"price": "12.00",
"properties": [
{
"name": "grind",
"value": "drip"
}
],
"quantity": 1,
"shopify_product_id": "1255183683",
"shopify_variant_id": "3844924611",
"sku": "MILK-1",
"subscription_id": 27363808,
"title": "Sumatra Coffee",
"variant_title": "Milk - a / b"
}
],
"note": " next order #1 - Subscription Recurring Order",
"note_attributes": null,
"processor_name": "stripe",
"scheduled_at": "2021-12-19T00:00:00",
"shipments_count": null,
"shipping_address": {
"address1": "3030 Nebraska Avenue",
"address2": "",
"city": "Los Angeles",
"company": "Recharge",
"country": "United States",
"first_name": "Mike",
"last_name": "Flynn",
"phone": "3103843698",
"province": "California",
"zip": "90404"
},
"shipping_lines": [
{
"code": "Standard Shipping",
"price": "0.00",
"title": "Standard Shipping"
}
],
"shopify_order_id": null,
"status": "QUEUED",
"sub_total": null,
"subtotal_price": "12.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"
}
],
"total_discounts": "0.0",
"total_line_items_price": "12.00",
"total_price": "12.00",
"total_refunds": null,
"total_tax": 0,
"total_weight": 4536,
"transaction_id": "cch_1Du2QpJ2iqHvZRd18RyqoPvc",
"type": "RECURRING",
"updated_at": "2018-11-14T09:59:28"
}
}
Process a charge
Pro plan
The charge processing route can be used to process Charges
that are in a queued
or error
status.
Related guides: Charges FAQ
The /charges/{id}/process
endpoint is available to Recharge Pro merchants on a request basis. If you’re interested in leveraging the Recharge charge processing API, reach out to your account manager or our Support team.
Learn more about Recharge Pro.
Responses
- 200
successful response
Show response object
curl 'https://api.rechargeapps.com/charges/100714428/process' \
-H 'Content-Type: application/json' \
-H 'X-Recharge-Access-Token: your_api_token' \
-d '{}'
{
"charge": {
"id": 100714428,
"address_id": 21317826,
"analytics_data": {
"utm_params": [
{
"utm_campaign": "spring_sale",
"utm_content": "differentiate-content",
"utm_data_source": "shopify_cookie",
"utm_medium": "email",
"utm_source": "newsletter",
"utm_term": "test-term",
"utm_time_stamp": "2019-12-16T23:57:28.752Z"
}
]
},
"billing_address": {
"address1": "3030 Nebraska Avenue",
"address2": null,
"city": "Los Angeles",
"company": null,
"country": "United States",
"first_name": "Mike",
"last_name": "Flynn",
"phone": "3103843698",
"province": "California",
"zip": "90404"
},
"client_details": {
"browser_ip": null,
"user_agent": null
},
"created_at": "2018-11-14T09:45:44",
"customer_hash": "18819267b1f9095be98f13a8",
"customer_id": 18819267,
"discount_codes": [],
"email": "example_mail@gmail.com",
"first_name": "Mike",
"has_uncommited_changes": false,
"last_name": "Flynn",
"line_items": [
{
"grams": 4536,
"images": {
"large": "https://cdn.shopify.com/s/files/1/0175/0695/9460/products/Sumatra_Coffee_large.png",
"medium": "https://cdn.shopify.com/s/files/1/0175/0695/9460/products/Sumatra_Coffee__medium.png",
"original": "https://cdn.shopify.com/s/files/1/0175/0695/9460/products/Sumatra_Coffee_.png",
"small": "https://cdn.shopify.com/s/files/1/0175/0695/9460/products/Sumatra_Coffee__small.png"
},
"original_price": "12.00",
"price": "12.00",
"properties": [
{
"name": "grind",
"value": "drip"
}
],
"quantity": 1,
"shopify_product_id": "1255183683",
"shopify_variant_id": "3844924611",
"sku": "MILK-1",
"subscription_id": 27363808,
"title": "Sumatra Coffee",
"variant_title": "Milk - a / b"
}
],
"note": " next order #1 - Subscription Recurring Order",
"note_attributes": null,
"processor_name": "stripe",
"scheduled_at": "2021-12-19T00:00:00",
"shipments_count": null,
"shipping_address": {
"address1": "3030 Nebraska Avenue",
"address2": "",
"city": "Los Angeles",
"company": "Recharge",
"country": "United States",
"first_name": "Mike",
"last_name": "Flynn",
"phone": "3103843698",
"province": "California",
"zip": "90404"
},
"shipping_lines": [
{
"code": "Standard Shipping",
"price": "0.00",
"title": "Standard Shipping"
}
],
"shopify_order_id": null,
"status": "QUEUED",
"sub_total": null,
"subtotal_price": "12.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"
}
],
"total_discounts": "0.0",
"total_line_items_price": "12.00",
"total_price": "12.00",
"total_refunds": null,
"total_tax": 0,
"total_weight": 4536,
"transaction_id": "cch_1Du2QpJ2iqHvZRd18RyqoPvc",
"type": "RECURRING",
"updated_at": "2018-11-14T09:59:28"
}
}
Capture a charge
Pro plan
Beta
If you are leveraging the authorize/capture workflow with Recharge, the charge/capture_payment endpoint is how to capture the funds of a previously authorized Charge
.
Capture Window
You can only capture payment on charges that have been authorized within the last 7 days. This is a limitation of payment providers/financial institutions and Recharge cannot configure or override this limit. Any charges that are attempted to be captured beyond that 7 day window may respond in an error indicating the charge cannot be captured.
As a result, Recharge provides a
charge/uncaptured
webhook. If subscribed, this webhook will notify you of any charges that are not captured 6 days after authorization. Please refer to the webhooks section for more information.
The capture_payment endpoint is available to Recharge Pro merchants in the Recharge Closed Beta group. If you’re interested in leveraging the Recharge charge capture_payment
endpoint, reach out to your account manager or our Support team.
Learn more about Recharge Pro.
Responses
- 200
Charge captured successfully
Show response object - 400
Bad Request
Show response object - 404
Not Found
Show response object - 422
Unprocessable
Show response object
curl 'https://api.rechargeapps.com/charges/100714428/capture_payment' \
-H 'Content-Type: application/json' \
-H 'X-Recharge-Access-Token: your_api_token' \
-d '{}'
{
"charge": {
"id": 100714428,
"address_id": 21317826,
"analytics_data": {
"utm_params": [
{
"utm_campaign": "spring_sale",
"utm_content": "differentiate-content",
"utm_data_source": "shopify_cookie",
"utm_medium": "email",
"utm_source": "newsletter",
"utm_term": "test-term",
"utm_time_stamp": "2019-12-16T23:57:28.752Z"
}
]
},
"billing_address": {
"address1": "3030 Nebraska Avenue",
"address2": null,
"city": "Los Angeles",
"company": null,
"country": "United States",
"first_name": "Mike",
"last_name": "Flynn",
"phone": "3103843698",
"province": "California",
"zip": "90404"
},
"client_details": {
"browser_ip": null,
"user_agent": null
},
"created_at": "2018-11-14T09:45:44",
"customer_hash": "18819267b1f9095be98f13a8",
"customer_id": 18819267,
"discount_codes": [],
"email": "example_mail@gmail.com",
"first_name": "Mike",
"has_uncommited_changes": false,
"last_name": "Flynn",
"line_items": [
{
"grams": 4536,
"images": {
"large": "https://cdn.shopify.com/s/files/1/0175/0695/9460/products/Sumatra_Coffee_large.png",
"medium": "https://cdn.shopify.com/s/files/1/0175/0695/9460/products/Sumatra_Coffee__medium.png",
"original": "https://cdn.shopify.com/s/files/1/0175/0695/9460/products/Sumatra_Coffee_.png",
"small": "https://cdn.shopify.com/s/files/1/0175/0695/9460/products/Sumatra_Coffee__small.png"
},
"original_price": "12.00",
"price": "12.00",
"properties": [
{
"name": "grind",
"value": "drip"
}
],
"quantity": 1,
"shopify_product_id": "1255183683",
"shopify_variant_id": "3844924611",
"sku": "MILK-1",
"subscription_id": 27363808,
"title": "Sumatra Coffee",
"variant_title": "Milk - a / b"
}
],
"note": "next order #2",
"note_attributes": null,
"processor_name": "stripe",
"scheduled_at": "2018-12-19T00:00:00",
"shipments_count": null,
"shipping_address": {
"address1": "3030 Nebraska Avenue",
"address2": "",
"city": "Los Angeles",
"company": "Recharge",
"country": "United States",
"first_name": "Mike",
"last_name": "Flynn",
"phone": "3103843698",
"province": "California",
"zip": "90404"
},
"shipping_lines": [
{
"code": "Standard Shipping",
"price": "0.00",
"title": "Standard Shipping"
}
],
"shopify_order_id": null,
"status": "SUCCESS",
"sub_total": null,
"subtotal_price": "12: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"
}
],
"total_discounts": "0.0",
"total_line_items_price": "12.00",
"total_price": "12.00",
"total_refunds": "12.00",
"total_tax": 0,
"total_weight": 4536,
"transaction_id": "ch_1Du2QpJ2iqHvZRd18RyqoPvc",
"type": "RECURRING",
"updated_at": "2018-11-14T10:08:14"
}
}
Checkouts
The checkout resource allows to create unique checkout experiences.
We currently support Stripe, Apple Pay, Google Pay, and Braintree as payment processor.
Related guides: Mobile payments
Important - The Checkout
endpoints are only available for BigCommerce and Custom. Checkouts on Shopify must go through Shopify.
The checkout object
The checkout resource allows to create unique checkout experiences.
We currently support Stripe, Apple Pay, Google Pay, Braintree, Authorize as payment processor.
The Checkout
endpoints are only available for BigCommerce and Custom implementations. Checkouts on Shopify must go through Shopify.
If you are using test stripe keys, you can use tok_visa
as your token.
Attributes
- analytics_dataobject
Analytics data containing amongst other things the
utm_params
Show object attributes - applied_discountobject
Details of the discount code applied to the checkout.
Show object attributes - billing_addressobject
Billing address for the checkout.
Show object attributes - buyer_accepts_marketingboolean
Serves as the audit trail for a buyer email marketing’s communication opt-in
- charge_idinteger
The
id
associated to theCharge
generated as a by-product of aCheckout
being processed.This value will remain
null
as long as theCheckout
has not been completed. - completed_attimestamp
The timestamp at which the
Checkout
was processed.This value will remain
null
as long as theCheckout
has not been completed. - created_attimestamp
The timestamp at which the
Checkout
was created. - currencystring
The presentment currency of the
Checkout
.This will also be the currency of the resulting Address and Subscriptions created by the checkout processing.
- discount_codestring
Discount code to be used on the checkout, e.g. “DISCOUNT20”.
- emailstring
Email address for the customer.
- external_checkout_idstring
Field which will hold the value of the corresponding external checkout or cart if the checkout was branched from another platform.
- external_checkout_sourcestring
Possible values: big_commerce, headless, shopify
Source of the creation of the checkout.
- external_customer_idstring
Customer identifier in the source platform issuing the checkout.
This field is useful for mapping to your customer id in your central CRM, ERP or any other commerce platform where you maintain your customer’s profiles.
- line_itemsarray
The details of the different items being purchased by the user.
Show object attributes - notestring
Note used to store free text notes.
- note_attributesarray
Structured note attributes.
Show object attributes - payment_processorstring
Name of the payment processor selected for the checkout.
Will remain
null
until payment details have been filled in. - payment_processor_customer_idstring
Identifier for the customer on the payment processor platform.
Will remain
null
until the checkout has been processed. - payment_processor_transaction_idstring
Identifier for the transaction on the payment processor platform.
Will remain
null
until the checkout has been processed. - phonestring
Customer phone number.
- requires_shippingboolean
Signals if the
Order
resulting from the processing of the checkout will need to be shipped aka packed and delivered.This relies on whether any of the
line_items
requires_shipping
. - shipping_addressobject
Shipping address for the checkout.
Show object attributes - shipping_address_validationsobject
Results of the shipping address validation.
only available once the shipping address has been filled in.
Show object attributes - shipping_linearray
Shipping lines.
Show object attributes - shipping_ratestring
The name of the shipping rate applied.
- tax_linesarray
Tax details.
Show object attributes - taxes_includedboolean
Whether taxes are included in the price of the line_items
- tokenstring
Unique identifier of the checkout. Used by the update and processing and update endpoints.
- total_pricestring
Total amount for the full checkout transaction
- total_taxstring
Total amount of tax for the full checkout transaction
- updated_attimestamp
The timestamp at which the
Checkout
was last updated.
Error related attributes
More Attributes
{
"checkout": {
"analytics_data": {
"utm_params": [
{
"utm_campaign": "spring_sale",
"utm_content": "textlink",
"utm_data_source": "shopify_cookie",
"utm_medium": "cpc",
"utm_source": "google",
"utm_term": "mleko",
"utm_timestamp": "2020-03-05T00:00:00"
}
]
},
"applied_discount": {
"amount": "7.50",
"applicable": true,
"non_applicable_reason": "",
"value": "7.50",
"value_type": "fixed_amount"
},
"billing_address": null,
"buyer_accepts_marketing": false,
"charge_id": null,
"completed_at": null,
"created_at": "2020-07-10T09:21:46+00:00",
"currency": "USD",
"discount_code": "POPUS_25",
"email": "somerandomemail@test.com",
"external_checkout_id": "<cart_token>",
"external_checkout_source": "ecommerce_platform",
"line_items": [
{
"charge_interval_frequency": 5,
"cutoff_day_of_month": null,
"cutoff_day_of_week": null,
"expire_after_specific_number_of_charges": null,
"first_recurring_charge_delay": null,
"fulfillment_service": "manual",
"grams": 1000,
"image": "//cdn.example.com/s/files/1/0279/8387/2103/products/kazan_small.jpg?v=1586451337",
"line_price": "30.00",
"order_day_of_month": null,
"order_day_of_week": null,
"order_interval_frequency": 5,
"order_interval_unit": "day",
"order_interval_unit_type": "day",
"original_price": "5.00",
"price": "5.00",
"product_id": 4546063663207,
"product_type": "Milk",
"properties": null,
"quantity": 6,
"recurring_price": "5.00",
"requires_shipping": true,
"sku": "kRaViCah-1",
"tax_code": null,
"taxable": false,
"title": "Powder Milk",
"type": "SUBSCRIPTION",
"variant_id": 32165284380775,
"variant_title": "1 / Powder",
"vendor": "Imlek"
}
],
"note": null,
"note_attributes": null,
"payment_processor": null,
"payment_processor_customer_id": null,
"payment_processor_transaction_id": null,
"phone": null,
"requires_shipping": true,
"shipping_address": {
"address1": "6419 Ocean Front Walk",
"address2": "Apt 2",
"city": "Los Angeles",
"company": "",
"country": "United States",
"first_name": "Novak",
"last_name": "Djokovic",
"phone": "1-800-800-8000",
"province": "California",
"zip": "90293"
},
"shipping_address_validations": {
"country_is_supported": true,
"ups": true
},
"shipping_line": null,
"shipping_rate": null,
"subtotal_price": "22.50",
"tax_lines": [
{
"price": "0.950",
"rate": 0.0725,
"title": "CA State Tax"
},
{
"price": "0.335",
"rate": 0.0225,
"title": "Los Angeles County Tax"
}
],
"taxes_included": false,
"token": "b706eecfd66c45329d3886a02d7515d6",
"total_price": "22.50",
"total_tax": "0.00",
"updated_at": "2020-07-10T09:21:46+00:00"
}
}
Create a checkout
Endpoint to create a checkout object and start populating it.
Related guides: Checkout integrations
The Checkout
endpoints are only available for BigCommerce and Custom. Checkouts on Shopify must go through Shopify.
The token
field received on checkout POST
response is the unique identifier for the Checkout
. Use it to make updates to the Checkout
.
Body Parameters
- analytics_dataobject
Analytics data containing amongst other things the
utm_params
.analytics_data
will be added toSubscription
,Customer
andCharge
objects created as a result of the successful processing of theCheckout
.Show object attributes - billing_addressobject
Billing address for the checkout.
Show object attributes - buyer_accepts_marketingboolean
Serves as the audit trail for a buyer email marketing’s communication opt-in
- currencystring
The presentment currency of the
Checkout
.Only currencies set up in the store setting
store_presentment_currencies
are accepted. This will also be the currency of the resulting Address and Subscriptions created by the checkout processing. - discount_codestring
Discount code to be used on the checkout, e.g. “DISCOUNT20”.
- emailstring
Email address for the customer.
will be required before being able to process a
Checkout
. - external_checkout_idstring
Cart token from ecommerce platform.
- external_checkout_sourcestring
Possible values: big_commerce, headless, shopify
Ecommerce platform hosting the cart.
- external_checkout_customer_idstring
Ecommerce platform hosting the cart.
- line_itemsarray* Required
The details of the different items being purchased by the user.
will be required before being able to process a
Checkout
.Show object attributes - notestring
Note used to store free text notes.
- note_attributesarray
Structured note attributes.
Show object attributes - phonestring
Customer phone number.
- shipping_addressobject
Shipping address for the checkout.
will be required before being able to process a
Checkout
.Show object attributes
More Parameters
Responses
- 200
Success
Show response object - 422
Unprocessable
Show response object
curl 'https://api.rechargeapps.com/checkouts' \
-H 'Content-Type: application/json' \
-H 'X-Recharge-Access-Token: your_api_token' \
-d '{
"analytics_data": {
"utm_params": [{
"utm_campaign": "spring_sale",
"utm_content": "textlink",
"utm_data_source": "website_cookie",
"utm_medium": "cpc",
"utm_source": "google",
"utm_term": "mleko",
"utm_timestamp": "2020-03-05"
}]
},
"discount_code": "POPUS_25",
"email":"somerandomemail@test.com",
"external_checkout_id": "<cart_token>",
"external_checkout_source": "custom",
"line_items": [
{
"charge_interval_frequency": 5,
"cutoff_day_of_month": None,
"cutoff_day_of_week": None,
"expire_after_specific_number_of_charges": None,
"fulfillment_service": "manual",
"order_day_of_month": None,
"order_day_of_week": None,
"order_interval_frequency": 5,
"order_interval_unit": "day",
"product_id": 4546063663207,
"quantity": 6,
"requires_shipping": True,
"taxable": True,
"variant_id": 32165284380775
}
],
"shipping_address": {
"address1": "6419 Ocean Front Walk",
"address2": "Apt 2",
"city": "Los Angeles",
"company": "",
"country": "United States",
"first_name": "Novak",
"last_name": "Djokovic",
"phone": "1-800-800-8000",
"province": "California",
"zip": "90293"
}
}'
{
"checkout": {
"analytics_data": {
"utm_params": [
{
"utm_campaign": "spring_sale",
"utm_content": "textlink",
"utm_data_source": "website_cookie",
"utm_medium": "cpc",
"utm_source": "google",
"utm_term": "mleko",
"utm_timestamp": "2020-03-05T00:00:00"
}
]
},
"applied_discount": {
"amount": "7.50",
"applicable": true,
"non_applicable_reason": "",
"value": "7.50",
"value_type": "fixed_amount"
},
"billing_address": {
"address1": "6419 Ocean Front Walk",
"address2": "Apt 2",
"city": "Los Angeles",
"company": "",
"country": "United States",
"first_name": "Novak",
"last_name": "Djokovic",
"phone": "1-800-800-8000",
"province": "California",
"zip": "90293"
},
"buyer_accepts_marketing": false,
"charge_id": null,
"completed_at": null,
"created_at": "2020-07-10T09:21:46.259352+00:00",
"currency": "USD",
"discount_code": "POPUS_25",
"email": "somerandomemail@test.com",
"external_checkout_id": "<cart_token>",
"external_checkout_source": "custom",
"external_customer_id": "someone",
"line_items": [
{
"charge_interval_frequency": 5,
"cutoff_day_of_month": null,
"cutoff_day_of_week": null,
"expire_after_specific_number_of_charges": null,
"first_recurring_charge_delay": null,
"fulfillment_service": "manual",
"grams": 1000,
"handle": null,
"image": "//cdn.example.com/s/files/1/0279/8387/2103/products/kazan_small.jpg?v=1586451337",
"line_price": "30.00",
"order_day_of_month": null,
"order_day_of_week": null,
"order_interval_frequency": 5,
"order_interval_unit": "day",
"order_interval_unit_type": "day",
"original_price": "5.00",
"price": "5.00",
"product_id": 4546063663207,
"product_type": "Milk",
"properties": null,
"quantity": 6,
"recurring_price": "5.00",
"requires_shipping": true,
"sku": "kRaViCah-1",
"tax_code": null,
"taxable": false,
"title": "Powder Milk",
"type": "SUBSCRIPTION",
"variant_id": 32165284380775,
"variant_title": "1 / Powder",
"vendor": "Imlek"
}
],
"note": null,
"note_attributes": null,
"payment_processor": null,
"payment_processor_customer_id": null,
"payment_processor_transaction_id": null,
"phone": null,
"requires_shipping": true,
"shipping_address": {
"address1": "6419 Ocean Front Walk",
"address2": "Apt 2",
"city": "Los Angeles",
"company": "",
"country": "United States",
"first_name": "Novak",
"last_name": "Djokovic",
"phone": "1-800-800-8000",
"province": "California",
"zip": "90293"
},
"shipping_address_validations": {
"country_is_supported": true,
"ups": true
},
"shipping_line": null,
"shipping_rate": null,
"subtotal_price": "22.50",
"tax_lines": [
{
"price": "0.950",
"rate": 0.0725,
"title": "CA State Tax"
},
{
"price": "0.335",
"rate": 0.0225,
"title": "Los Angeles County Tax"
}
],
"taxes_included": false,
"token": "b706eecfd66c45329d3886a02d7515d6",
"total_price": "22.50",
"total_tax": "1.28",
"updated_at": "2020-07-10T09:21:46.284703+00:00"
}
}
Retrieve a checkout
Retrieve a checkout
The Checkout
endpoints are only available for BigCommerce and Custom. Checkouts on Shopify must go through Shopify.
Responses
- 200
Success
Show response object
curl 'https://api.rechargeapps.com/checkouts/6a7c36a1213a4d7fb746e6588fa55005' \
-H 'X-Recharge-Access-Token: your_api_token'
{
"checkout": {
"analytics_data": {
"utm_params": [
{
"utm_campaign": "spring_sale",
"utm_content": "textlink",
"utm_data_source": "website_cookie",
"utm_medium": "cpc",
"utm_source": "google",
"utm_term": "mleko",
"utm_timestamp": "2020-03-05T00:00:00"
}
]
},
"applied_discount": {
"amount": "7.50",
"applicable": true,
"non_applicable_reason": "",
"value": "7.50",
"value_type": "fixed_amount"
},
"billing_address": null,
"buyer_accepts_marketing": false,
"charge_id": null,
"completed_at": null,
"created_at": "2020-07-10T09:21:46.259352+00:00",
"currency": "USD",
"discount_code": "POPUS_25",
"email": "somerandomemail@test.com",
"external_checkout_id": "<cart_token>",
"external_checkout_source": "headless",
"line_items": [
{
"charge_interval_frequency": 5,
"cutoff_day_of_month": null,
"cutoff_day_of_week": null,
"expire_after_specific_number_of_charges": null,
"first_recurring_charge_delay": null,
"fulfillment_service": "manual",
"grams": 1000,
"image": "//cdn.example.com/s/files/1/0279/8387/2103/products/kazan_small.jpg?v=1586451337",
"line_price": "30.00",
"order_day_of_month": null,
"order_day_of_week": null,
"order_interval_frequency": 5,
"order_interval_unit": "day",
"order_interval_unit_type": "day",
"original_price": "5.00",
"price": "5.00",
"product_id": 4546063663207,
"product_type": "Milk",
"properties": null,
"quantity": 6,
"recurring_price": "5.00",
"requires_shipping": true,
"sku": "kRaViCah-1",
"tax_code": null,
"taxable": false,
"title": "Powder Milk",
"type": "SUBSCRIPTION",
"variant_id": 32165284380775,
"variant_title": "1 / Powder",
"vendor": "Imlek"
}
],
"note": null,
"note_attributes": null,
"payment_processor": null,
"payment_processor_customer_id": null,
"payment_processor_transaction_id": null,
"phone": null,
"requires_shipping": true,
"shipping_address": {
"address1": "6419 Ocean Front Walk",
"address2": "Apt 2",
"city": "Los Angeles",
"company": "",
"country": "United States",
"first_name": "Novak",
"last_name": "Djokovic",
"phone": "1-800-800-8000",
"province": "California",
"zip": "90293"
},
"shipping_address_validations": {
"country_is_supported": true,
"ups": true
},
"shipping_line": null,
"shipping_rate": null,
"subtotal_price": "22.50",
"tax_lines": [
{
"price": "0.950",
"rate": 0.0725,
"title": "CA State Tax"
},
{
"price": "0.335",
"rate": 0.0225,
"title": "Los Angeles County Tax"
}
],
"taxes_included": false,
"token": "b706eecfd66c45329d3886a02d7515d6",
"total_price": "22.50",
"total_tax": "0.00",
"updated_at": "2020-07-10T09:21:46.284703+00:00"
}
}
Update a checkout
You can modify an existing checkout to match the specified parameters.
Related guides: Checkout integrations
The Checkout
endpoints are only available for BigCommerce and Custom. Checkouts on Shopify must go through Shopify.
If you are using test stripe keys, you can use tok_visa
as your token.
Body Parameters
- analytics_dataobject
Analytics data containing amongst other things the
utm_params
.analytics_data
will be added toSubscription
,Customer
andCharge
objects created as a result of the successful processing of theCheckout
.Show object attributes - billing_addressobject
Billing address for the checkout.
Show object attributes - buyer_accepts_marketingboolean
Does the buyer accept marketing, newsletters etc.
- currencystring
The presentment currency of the
Checkout
.Only currencies set up in the store setting
store_presentment_currencies
are accepted. This will also be the currency of the resulting Address and Subscriptions created by the checkout processing. - discount_codestring
Discount code to be used on the checkout, e.g. “DISCOUNT20”.
- emailstring
Email address for the customer.
- external_checkout_idstring
Cart token from ecommerce platform.
- external_checkout_sourcestring
Possible values: big_commerce, headless, shopify
Ecommerce platform hosting the cart.
- external_checkout_customer_idstring
Ecommerce platform hosting the cart.
- line_itemsarray
quantity
,product_id
andvariant_id
are required parameters in line_items.Show object attributes - notestring
Note attribute used to store custom notes.
- note_attributesarray
Each array entry must contain a dictionary with “name” and “value” keys.
Show object attributes - partial_shippingboolean
When set to true, shipping address validations are reduced to only require country and zip when creating/updating a checkout. The full shipping address including address line 1 must be added to the checkout before processing associated charges. This is helpful for mobile payments.
Related guides: Mobile payments - phonestring
Customer phone number.
- shipping_addressobject
Shipping address for the checkout.
When using mobile payment options, insufficient shipping address data is available until payment intent, which causes validation errors when updating the checkout object.
Related guides: Checkout mobile paymentShow object attributes
More Parameters
Responses
- 200
Success
Show response object
curl -X PUT 'https://api.rechargeapps.com/checkouts/98ac7af0c9d447019379c6ccdb24d069' \
-H 'Content-Type: application/json' \
-H 'X-Recharge-Access-Token: your_api_token' \
-d '{
"line_items": [
{
"product_id": 4546063663207,
"quantity": 6,
"variant_id": 3844924611
}
]
}'
{
"checkout": {
"analytics_data": {
"utm_params": [
{
"utm_campaign": "spring_sale",
"utm_content": "textlink",
"utm_data_source": "website_cookie",
"utm_medium": "cpc",
"utm_source": "google",
"utm_term": "mleko",
"utm_timestamp": "2020-03-05T00:00:00"
}
]
},
"applied_discount": {
"amount": "7.50",
"applicable": true,
"non_applicable_reason": "",
"value": "7.50",
"value_type": "fixed_amount"
},
"billing_address": null,
"buyer_accepts_marketing": false,
"charge_id": null,
"completed_at": null,
"created_at": "2020-07-10T09:21:46.259352+00:00",
"currency": "USD",
"discount_code": "POPUS_25",
"email": "somerandomemail@test.com",
"external_checkout_id": "<cart_token>",
"external_checkout_source": "headless",
"line_items": [
{
"charge_interval_frequency": 5,
"cutoff_day_of_month": null,
"cutoff_day_of_week": null,
"expire_after_specific_number_of_charges": null,
"first_recurring_charge_delay": null,
"fulfillment_service": "manual",
"grams": 1000,
"image": "//cdn.example.com/s/files/1/0279/8387/2103/products/kazan_small.jpg?v=1586451337",
"line_price": "30.00",
"order_day_of_month": null,
"order_day_of_week": null,
"order_interval_frequency": 5,
"order_interval_unit": "day",
"order_interval_unit_type": "day",
"original_price": "5.00",
"price": "5.00",
"product_id": 4546063663207,
"product_type": "Milk",
"properties": null,
"quantity": 6,
"recurring_price": "5.00",
"requires_shipping": true,
"sku": "kRaViCah-1",
"tax_code": null,
"taxable": false,
"title": "Powder Milk",
"type": "SUBSCRIPTION",
"variant_id": 32165284380775,
"variant_title": "1 / Powder",
"vendor": "Imlek"
}
],
"note": null,
"note_attributes": null,
"payment_processor": null,
"payment_processor_customer_id": null,
"payment_processor_transaction_id": null,
"phone": null,
"requires_shipping": true,
"shipping_address": {
"address1": "6419 Ocean Front Walk",
"address2": "Apt 2",
"city": "Los Angeles",
"company": "",
"country": "United States",
"first_name": "Novak",
"last_name": "Djokovic",
"phone": "1-800-800-8000",
"province": "California",
"zip": "90293"
},
"shipping_address_validations": {
"country_is_supported": true,
"ups": true
},
"shipping_line": null,
"shipping_rate": null,
"subtotal_price": "22.50",
"tax_lines": [
{
"price": "0.950",
"rate": 0.0725,
"title": "CA State Tax"
},
{
"price": "0.335",
"rate": 0.0225,
"title": "Los Angeles County Tax"
}
],
"taxes_included": false,
"token": "b706eecfd66c45329d3886a02d7515d6",
"total_price": "22.50",
"total_tax": "0.00",
"updated_at": "2020-07-10T09:21:46.284703+00:00"
}
}
Retrieve shipping rates
Retrieve all shipping rates for a specific checkout.
The Checkout
endpoints are only available for BigCommerce and Custom. Checkouts on Shopify must go through Shopify.
Responses
- 200
success
Show response object
curl 'https://api.rechargeapps.com/checkouts/6a7c36a1213a4d7fb746e6588fa55005/shipping_rates' \
-H 'X-Recharge-Access-Token: your_api_token'
{
"shipping_rates": [
{
"checkout": {
"subtotal_price": "22.50",
"total_price": "42.40",
"total_tax": "0.00"
},
"code": "Standard",
"delivery_range": null,
"description": null,
"handle": "shopify-Standard-19.90",
"name": "Standard",
"phone_required": false,
"price": "19.90",
"tax_lines": [],
"title": "Standard"
}
]
}
Process a checkout
You can process and charge checkout using our API.
The Checkout
endpoints are only available for BigCommerce and Custom. Checkouts on Shopify must go through Shopify.
The Checkout API supports Stripe, Apple Pay, Google Pay, and Braintree as payment processor.
If you are using test stripe keys, you can use tok_visa
as your token. For checkouts using Mobile Payments, see Mobile Payments with Checkout API
Body Parameters
- payment_processorstring* Required
Possible values: stripe, braintree, mollie, authorize
The name of payment processor.
- payment_tokenstring* Required
Payment token that will be used in transaction.
For
stripe
this field needs to be populated with a payment method.
Forbraintree
this field needs to be populated with a payment nonce.
Formollie
this field needs to be populated with a mandate. - payment_typestring
Possible values: CREDIT_CARD, PAYPAL, APPLE_PAY, GOOGLE_PAY
It identifies the payment type.
More Parameters
Responses
- 200
Success
Show response object - 422
Unprocessable
Show response object
curl 'https://api.rechargeapps.com/checkouts/5a5c19ea31c44641855017f1276db959/charge' \
-H 'Content-Type: application/json' \
-H 'X-Recharge-Access-Token: your_api_token' \
-d '{
"payment_processor": "stripe",
"payment_token": "<payment_token>",
"payment_type": "CREDIT_CARD"
}'
{
"checkout_charge": {
"authorization_token": null,
"charge_id": 258065996,
"free": false,
"payment_processor": "stripe",
"payment_processor_customer_id": "cus_HcbgqiS49fABBg62E",
"payment_processor_transaction_id": "ch_1H3McXJ2zdqHvZaRd191xV2idRt",
"payment_token": "tok_visa",
"payment_type": "CREDIT_CARD",
"status": "successful"
}
}
Customers
The Customer object holds account and billing information. Email is unique on the customer; no two customers for a store can have the same email. Address is the child of the customer object. There can be many child addresses on a customer, but only one parent customer per address.
The customer object
The following fields are deprecated: stripe_customer_token
, paypal_customer_token
, authorizedotnet_profile_id
, authorizedotnet_payment_profile_id
. To add payment methods to a customer use 2021-11 /payment_methods
instead
Attributes
- idinteger
Unique numeric identifier for the customer.
- accepts_marketingboolean
Indicates whether the
Customer
gives consent for marketing communications. - billing_address1string
The customer’s billing address.
- billing_address2string
An additional field for the customer’s billing address.
- billing_citystring
The customer’s billing city.
- billing_companystring
The customer’s billing company.
- billing_countrystring
The customer’s billing country.
- billing_first_namestring
The customer’s billing first name. Required when creating a customer.
- billing_last_namestring
The customer’s billing last name. Required when creating a customer.
- billing_phonestring
The customer’s billing phone number.
- billing_provincestring
The customer’s billing province or state name.
- billing_zipstring
The customer’s billing zip or postal code.
- created_atdatetime
The date and time when the customer was created.
- emailstring
The email address of the customer.
- first_charge_processed_atstring
Date when first charge was processed for the customer.
- first_namestring
The customer’s first name.
- has_card_error_in_dunningboolean
Does have a credit card in dunning, can be
true
andfalse
. - has_valid_payment_methodboolean
Is the payment method valid or not, can be
true
andfalse
. - hashstring
The unique string identifier used in a customers portal link.
- last_namestring
The customer’s last name.
- number_active_subscriptionsinteger
The number of active subscriptions for the customer.
- number_subscriptionsinteger
The number of subscriptions for the customer.
- phonestring
The customer’s phone number.
- processor_typestring
What the merchant processor customer is stored on.
- reason_payment_method_not_validstring
Why payment method is not valid.
- shopify_customer_idstring
Shopify’s unique identifier for the customer.
- statusstring
Customer’s status, can be
ACTIVE
andINACTIVE
. - updated_atdatetime
The date and time when the customer was last updated.
Error related attributes
More Attributes
{
"id": 18819267,
"accepts_marketing": true,
"analytics_data": {
"utm_params": []
},
"billing_address1": "3030 Nebraska Avenue",
"billing_address2": null,
"billing_city": "Los Angeles",
"billing_company": null,
"billing_country": "United States",
"billing_phone": "3103843698",
"billing_province": "California",
"billing_zip": "90404",
"created_at": "2018-11-14T08:40:38",
"email": "example_mail@gmail.com",
"first_charge_processed_at": null,
"first_name": "Jacob",
"has_card_error_in_dunning": false,
"has_valid_payment_method": false,
"hash": "18819267b1f9095be98f13a8",
"last_name": "Bronowski",
"number_active_subscriptions": 0,
"number_subscriptions": 0,
"phone": "+16175551212",
"processor_type": null,
"reason_payment_method_not_valid": null,
"shopify_customer_id": null,
"status": "INACTIVE",
"stripe_customer_token": "cus_I9bJ...",
"updated_at": "2018-11-14T08:40:38"
}
Create a customer in Recharge.
If you plan to add payment information, it must be the tokenized customer representation. We do not accept card data directly. Please make sure it starts with ‘cus’ and not with a 'tok’, as the 'cus’ is prefix for customer token, and 'tok’ is prefix for payment token.
Creating a customer in Recharge will not create the customer on any other platform at this time.
Write_Payments permission is only required when creating customers with payment token information, or updating payment token information on a customer.
Body Parameters
- accepts_marketingboolean
Indicates whether the
Customer
gives consent for marketing communications. - authorizedotnet_payment_profile_idinteger*Deprecated
Authorize.net customer payment profile id. Required when
authorizedotnet_profile_id
is provided. - authorizedotnet_profile_idinteger*Deprecated
Authorize.net customer profile id. If both
authorizedotnet_profile_id
andauthorizedotnet_payment_profile_id
is provided the authorize.net payment profile will be tokenized and associated with the created customer. The tokenized value is returned as customer’s authorizedotnet_customer_token field. - billing_address1string* Required
The customer’s billing address 1.
- billing_address2string
An additional field for the customer’s billing address.
- billing_citystring* Required
The customer’s billing city.
- billing_companystring
The customer’s billing company.
- billing_countrystring* Required
The customer’s billing country.
- billing_first_namestring* Required
The customer’s billing first name.
- billing_last_namestring* Required
The customer’s billing last name.
- billing_phonestring
The customer’s billing phone number.
- billing_provincestring* Required
The customer’s billing province or state name.
- billing_zipstring* Required
The customer’s billing zip or postal code.
- emailstring* Required
The customer’s email address.
- first_namestring* Required
The customer’s first name.
- last_namestring* Required
The customer’s last name.
- paypal_customer_tokenstring*Deprecated
The payment processor customer payment token.
- phonestring
The customer’s phone number.
- processor_typestring
What the merchant processor customer is stored on.
- shopify_customer_idstring
The shopify customer id.
_The provided “shopify_customer_id” must match the provided “email” in the Shopify database for the customer. - stripe_customer_tokenstring*Deprecated
The customer token, you will need to tokenize customers first on the payment processors end, and after you get the customer token, you can create the Recharge customer with it.
More Parameters
Responses
- 200
Success
Show response object
curl 'https://api.rechargeapps.com/customers' \
-H 'Content-Type: application/json' \
-H 'X-Recharge-Access-Token: your_api_token' \
-d '{
"billing_address1": "3030 Nebraska Avenue",
"billing_city": "Los Angeles",
"billing_country": "United States",
"billing_first_name": "Mike",
"billing_last_name": "Flynn",
"billing_phone": "3103843698",
"billing_province": "California",
"billing_zip": "90404",
"email": "example_mail@gmail.com",
"first_name": "Mike",
"last_name": "Flynn",
"stripe_customer_token": "Customer_payment_token"
}'
{
"customer": {
"id": 18819267,
"accepts_marketing": true,
"analytics_data": {
"utm_params": []
},
"billing_address1": "3030 Nebraska Avenue",
"billing_address2": null,
"billing_city": "Los Angeles",
"billing_company": null,
"billing_country": "United States",
"billing_phone": "3103843698",
"billing_province": "California",
"billing_zip": "90404",
"created_at": "2018-11-14T08:40:38",
"email": "example_mail@gmail.com",
"first_charge_processed_at": null,
"first_name": "Mike",
"hash": "18819267b1f9095be98f13a8",
"has_card_error_in_dunning": false,
"has_valid_payment_method": false,
"last_name": "Flynn",
"number_active_subscriptions": 0,
"number_subscriptions": 0,
"phone": "+16175551212",
"processor_type": null,
"reason_payment_method_not_valid": null,
"shopify_customer_id": null,
"status": "INACTIVE",
"stripe_customer_token": "cus_I9bJ...",
"updated_at": "2018-11-14T08:40:38"
}
}
Retrieve a customer
Retrieve one customer using the Recharge customer id.
Responses
- 200
Success
Show response object
curl 'https://api.rechargeapps.com/customers/18819267' \
-H 'X-Recharge-Access-Token: your_api_token
{
"customer": {
"id": 18819267,
"accepts_marketing": true,
"analytics_data": {
"utm_params": []
},
"billing_address1": "3030 Nebraska Avenue",
"billing_address2": null,
"billing_city": "Los Angeles",
"billing_company": null,
"billing_country": "United States",
"billing_phone": "3103843698",
"billing_province": "California",
"billing_zip": "90404",
"created_at": "2018-11-14T08:40:38",
"email": "example_mail@gmail.com",
"first_charge_processed_at": null,
"first_name": "Mike",
"hash": "18819267b1f9095be98f13a8",
"has_card_error_in_dunning": false,
"has_valid_payment_method": false,
"last_name": "Flynn",
"number_active_subscriptions": 0,
"number_subscriptions": 0,
"phone": "+16175551212",
"processor_type": null,
"reason_payment_method_not_valid": null,
"shopify_customer_id": null,
"status": "INACTIVE",
"stripe_customer_token": "cus_I9bJ...",
"updated_at": "2018-11-14T08:40:38"
}
}
Update a customer
Modify an existing customer to match the specified parameters.
Note: For US citizens parameter billing_zip
is required when updating customer’s billing_country
parameter
Body Parameters
- accepts_marketingboolean
Indicates whether the
Customer
gives consent for marketing communications. - emailstring
Email address of the customer.
- billing_address1string
Customer’s billing address 1.
- billing_address2string
An additional field for the customer’s billing address.
- billing_citystring
Customer’s billing city.
- billing_companystring
An additional field for the customer’s company.
- billing_countrystring
Customer’s billing country.
- billing_first_namestring
Customer’s billing first name.
- billing_last_namestring
Customer’s billing last name.
- billing_phonestring
Customers billing phone number.
- billing_provincestring
Customer’s billing province or state name.
- billing_zipstring
Customer’s billing zip or postal code.
- first_namestring
Customer’s first name.
- last_namestring
Customer’s last name.
- phonestring
The customer’s phone number.
- shopify_customer_idinteger
Shopify’s customer id.
More Parameters
Responses
- 200
Success
Show response object
curl -X PUT https://api.rechargeapps.com/customers/18819267
-H 'Content-Type: application/json'
-H 'X-Recharge-Access-Token: your_api_token'
-d '{"billing_address1": "3030 Nebraska Avenue"}'
{
"customer": {
"id": 18819267,
"accepts_marketing": true,
"analytics_data": {
"utm_params": []
},
"billing_address1": "3030 Nebraska Avenue",
"billing_address2": null,
"billing_city": "Los Angeles",
"billing_company": null,
"billing_country": "United States",
"billing_phone": "3103843698",
"billing_province": "California"