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.
When including charge_activities
in API calls or webhooks, note that only the last 90 days of activities will be included in the response.
Resource | Endpoints | Webhook topics | Supported include values |
Supported included_objects values |
---|---|---|---|---|
Addresses |
GET /addresses GET /addresses/{id} |
address/created address/updated |
charge_activities customer discount payment_methods subscriptions |
customer payment_methods |
Charges |
GET /charges GET /charges/{id} |
charge/created charge/failed charge/max_retries_reached charge/paid charge/refunded charge/uncaptured charge/upcoming charge/updated charge/deleted |
charge_activities (beta)customer metafields payment_methods |
customer metafields payment_methods |
Customers |
GET /customers GET /customers/{id} |
customer/activated customer/created customer/deactivated customer/payment_method_updated customer/updated customer/deleted |
addresses metafields payment_methods subscriptions |
addresses metafields payment_methods |
Orders |
GET /orders GET /orders/{id} |
order/cancelled order/created order/deleted order/processed order/payment_captured order/upcoming order/updated order/success |
customer metafields |
customer metafields |
Payment Methods |
GET /payment_methods GET /payment_methods/{id} |
addresses |
addresses |
|
Subscriptions |
GET /subscriptions GET /subscriptions/{id} |
subscription/activated subscription/cancelled subscription/created subscription/deleted subscription/skipped subscription/updated subscription/unskipped subscription/paused |
address charge_activities customer metafields bundle_product bundle_selections |
customer metafields |
Cursor Pagination
By default, calls for a list of objects will return 50 results. Using the limit
parameter, that can be increased to 250 results per response.
When there are more results than the current limit
a cursor may be used to request additional results.
The next_cursor
and previous_cursor
attributes are are included in all list responses.
To request the next set of results, find the next_cursor
in the list response and include it in the url with the cursor parameter e.g. GET https://api.rechargeapps.com/subscriptions?limit=250&cursor=<next_cursor>
To request the previous set of results, find the previous_cursor
in the list response and include it in the url with the cursor parameter e.g. GET https://api.rechargeapps.com/subscriptions?limit=250&cursor=<previous_cursor>
Retrieving total number of records
Starting with the 2021-11
version of the API, you will not be able to retrieve a count of total records for a given GET
request. If you are building a UI page that allows end users to paginate through result sets (such as paginating through a list of orders or subscriptions), we recommend that your pagination implementation allow users to go to the next and previous page of results (as opposed to allowing users to jump to specific page in the results). This aligns well with the previous_cursor
and the next_cursor
fields included in all list responses.
URL="https://api.rechargeapps.com/charges?limit=5"
response=$(curl -s -w "%{http_code}"\
-H 'X-Recharge-Access-Token: your_api_token' \
-H 'X-Recharge-Version: 2021-11' \ -X GET $URL)
content=$(sed '$ d' <<< "$response") # get all but the last line which contains the status code
# Display results
echo $content | jq "."
# parse next url
echo "Next URL"
next_cursor=$(jq ".next_cursor" <<< "${content}")
# Notice next_cursor value is passed as page_info query param
echo "$URL&page_info=$next_cursor"
Sorting
The API supports sorting of results when using a GET
request to retrieve a list. Sorting is achieved using a sort_by
query parameter in the request URL. The sort_by
value contains the parameter and sort direction for your results (ascending or descending), and available sort_by values vary between resources. The below table defines available sort_by
options for commonly used resources.
Resource | Supported sort_by_values |
---|---|
Address |
Default: id-desc Options: id-asc id-desc updated_at-asc updated_at-desc |
Async Batch |
Default: id-desc Options: id-asc id-desc created_at-asc created_at-desc |
Charge |
Default: id-asc Options: id-asc id-desc created_at-asc created_at-desc updated_at-asc updated_at-desc scheduled_at-asc scheduled_at-desc |
Customer |
Default: id-desc Options: id-asc id-desc created_at-asc created_at-desc updated_at-asc updated_at-desc |
Discount |
Default: id-desc Options: id-asc id-desc created_at-asc created_at-desc updated_at-asc updated_at-desc |
Metafield |
Default: id-desc Options: id-asc id-desc updated_at-asc updated_at-desc |
Onetime |
Default: id-desc Options: id-asc id-desc created_at-asc created_at-desc updated_at-asc updated_at-desc |
Order |
Default: id-desc Options: id-asc id-desc updated_at-asc updated_at-desc processed_at-asc processed_at-desc scheduled_at-asc scheduled_at-desc |
Plan |
Default: id-desc Options: id-asc id-desc updated_at-asc updated_at-desc |
Subscription |
Default: id-desc Options: id-asc id-desc created_at-asc created_at-desc updated_at-asc updated_at-desc |
Webhook |
Default: id-desc Options: id-asc id-desc |
Addresses
An Addresses record represents a shipping address. Each customer can have multiple addresses. Subscriptions are a child object of an address.
The address object
An Addresses record represents a shipping address. Each customer can have multiple addresses. Subscriptions are a child object of an address.
Attributes
- idinteger
Unique numeric identifier for the
Address
. - payment_method_idinteger
Unique numeric identifier for the
Payment Method
associated to theAddress
. - address1string
The street associated with the
Address
. - address2string
Any additional information associated with the
Address
. - citystring
The city associated with the address.
- companystring
The company associated with the address.
- country_codestring
2-letter country code.
- customer_idinteger
Unique numeric identifier for the customer associated with the address.
- discountsarray
A list of discounts applied on the address. These discounts will apply to future recurring charges associated with this address.
Show object attributes - first_namestring
The customer’s first name associated with the address.
- last_namestring
The customer’s last name associated with the address.
Replaces cart_attributes. Extra information that is added to the order.
Show object attributes- order_notestring
Notes to be added to all orders associated with the address.
- phonestring
The phone number associated with the address.
The currency on the subscription contract in Shopify.
Only set if the currency is different from the store-level currency. Else, will default to store-level currency.
- provincestring
The state or province associated with the address.
- shipping_lines_conservedarray
Shipping rates that have previously been overridden via
shipping_lines_override
but are currently inactive.Show object attributes - shipping_lines_overridearray
Used when shipping rates need to be overridden.
If this parameter has value
null
, rates will be fetched whenCharge
is created or regeneratedShow object attributes - zipstring
The zip or postal code associated with the address.
- created_atdatetime
The date and time when the address was created.
- updated_atdatetime
The date and time when the address was last updated.
Error related attributes
More Attributes
{
"address": {
"id": 21317826,
"payment_method_id": 17874235,
"address1": "1776 Washington Street",
"address2": "",
"city": "Los Angeles",
"company": "Recharge",
"country_code": "US",
"created_at": "2018-11-14T09:00:01+00:00",
"customer_id": 18819267,
"discounts": [
{
"id": 12345,
"code": "TESTCODE10",
"value": 10,
"value_type": "fixed_amount"
}
],
"first_name": "John",
"last_name": "Doe",
"order_attributes": [
{
"name": "custom name",
"value": "custom value"
}
],
"order_note": "My recurring order note.",
"phone": "5551234567",
"presentment_currency": "USD",
"shipping_lines_conserved": [],
"shipping_lines_override": [
{
"code": "Standard Shipping",
"price": "0.00",
"title": "Standard Shipping"
}
],
"updated_at": "2018-11-14T09:00:01+00:00",
"zip": "90404"
}
}
Create an address
Create a new address for a customer.
Body Parameters
- customer_idinteger* Required
Unique numeric identifier for the customer associated with the address.
- address1string* Required
The street associated with the
Address
. Minimum length is 1 character. - address2string
Any additional information associated with the shipping address.
- citystring* Required
The city associated with the shipping address.
- companystring
The company associated with the shipping address.
- country_codestring* Required
2-letter country code.
Check if the store supports shipping to this country. This is set by the merchant in their Shipping Settings page.
- discountsarray
List of discounts applied on the
Address
.Show object attributes - 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.
Extra information that is added to the order.
Show object attributes- order_notestring
Notes to be added to all orders associated with the address.
- payment_method_idinteger
Payment method id for the
Payment_method
to be associated to this address. - 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
. - 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 azip
codeCOUNTRIES_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
validate against regexUNITED_STATES_ZIP_REGEX
. If country isUnited Kingdom
then validate against regexUNITED_KINGDOM_ZIP_REGEX
.
More Parameters
Responses
- 201
OK: The request was successful, created a new resource, and resource created is in the body.
Show response object
curl https://api.rechargeapps.com/addresses \
-H 'X-Recharge-Version: 2021-11' \
-H 'Content-Type: application/json' \
-H 'X-Recharge-Access-Token: your_api_token' \
-d '{
"customer_id": 22152215,
"address1": "1776 Washington Street",
"address2": "",
"city": "Los Angeles",
"company": "Recharge",
"country_code": "US",
"first_name": "John",
"last_name": "Doe",
"order_attributes": [
{
"name": "custom name",
"value": "custom value"
}
],
"phone": "5551234567",
"presentment_currency": "USD",
"province": "California",
"zip": "90404"
}'
{
"address": {
"id": 42171447,
"address1": "1030 Barnum Ave",
"address2": "Suite 101",
"city": "Stratford",
"company": "Fake Company",
"country_code": "US",
"created_at": "2022-10-12T20:16:09+00:00",
"customer_id": 37657002,
"discounts": [],
"first_name": "Fake First",
"last_name": "Fake Last",
"order_attributes": [
{
"name": "custom name",
"value": "custom value"
}
],
"order_note": "My recurring order note",
"phone": "999-999-9999",
"presentment_currency": "USD",
"province": "Connecticut",
"shipping_lines_conserved": [],
"shipping_lines_override": [],
"updated_at": "2022-10-12T20:16:09+00:00",
"zip": "06614"
}
}
Retrieve an address
Retrieves address for customer based on specified address id.
Responses
- 200
successful response
Show response object
curl 'https://api.rechargeapps.com/addresses/21317826' \
-H 'X-Recharge-Version: 2021-11' \
-H 'X-Recharge-Access-Token: your_api_token'
{
"address": {
"id": 42171447,
"payment_method_id": 17874235,
"address1": "1030 Barnum Ave",
"address2": "Suite 101",
"city": "Stratford",
"company": "Fake Company",
"country_code": "US",
"created_at": "2022-10-12T20:16:09+00:00",
"customer_id": 37657002,
"discounts": [],
"first_name": "Fake First",
"last_name": "Fake Last",
"order_attributes": [
{
"name": "custom name",
"value": "custom value"
}
],
"order_note": "My recurring order note",
"phone": "999-999-9999",
"presentment_currency": "USD",
"province": "Connecticut",
"shipping_lines_conserved": [],
"shipping_lines_override": [],
"updated_at": "2022-10-12T20:16:09+00:00",
"zip": "06614"
}
}
Update an address
Updates an existing address to match the specified parameters.
Example: remove discounts from an address
To remove all discounts from an address, set thediscounts
parameter to an empty array: {"discounts": []}
Note: When updating the country
property you will have to update the zip
property as well, otherwise you will receive an error.
Body Parameters
- address1string
The street associated with the
Address
. Minimum length is 1 character. - address2string
Any additional information associated with the shipping address.
- citystring
The city associated with the shipping address. Minimum length is 1 character.
- companystring
The company associated with the shipping address.
- country_codestring
2-letter country code.
Check if the
store
supports shipping to this country. This is set by the merchant in their Shipping Settings page. - discountsarray
A list of discounts applied on the address. These discounts will apply to future recurring charges associated with this address.
Show object attributes - 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.
Show object attributes- order_notestring
Notes to be added to all orders associated with the address.
- payment_method_idinteger
Payment method id for the
Payment_method
to be associated to this address. - 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
. Used when shipping rates need to be overridden. If this parameter has value
null
, rates will be fetched when a relatedCharge
is created or regenerated.Show 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
. If country isUnited Kingdom
then validate against regexUNITED_KINGDOM_ZIP_REGEX
.
More Parameters
Responses
- 200
successful response
Show response object
curl -X PUT 'https://api.rechargeapps.com/addresses/38700614' \
-H 'X-Recharge-Version: 2021-11' \
-H 'Content-Type: application/json' \
-H 'X-Recharge-Access-Token: your_api_token' \
-d '{"address1": "1776 Washington Street"}'
{
"address": {
"id": 42171447,
"payment_method_id": 17874235,
"address1": "1030 Barnum Ave",
"address2": "Suite 101",
"city": "Stratford",
"company": "Fake Company",
"country_code": "US",
"created_at": "2022-10-12T20:16:09+00:00",
"customer_id": 37657002,
"discounts": [],
"first_name": "Fake First",
"last_name": "Fake Last",
"order_attributes": [
{
"name": "custom name",
"value": "custom value"
}
],
"order_note": "My recurring order note",
"phone": "999-999-9999",
"presentment_currency": "USD",
"province": "Connecticut",
"shipping_lines_conserved": [],
"shipping_lines_override": [],
"updated_at": "2022-10-12T20:16:09+00:00",
"zip": "06614"
}
}
Delete an address
It is possible to delete certain addresses from the store using API.
Only Addresses
with no active Subscriptions
can be deleted.
Responses
- 204
Content Deleted: The server has successfully fulfilled the request and deleted the desired object and there is no content to send in the response body.
Show response object
curl -X DELETE 'https://api.rechargeapps.com/addresses/38700614'\
-H 'X-Recharge-Version: 2021-11' \
-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.
HTTP examples
GET /addresses
GET /addresses?customer_id=<customer_id>
GET /addresses?discount_id=<discount_id>
GET /addresses?discount_code=<discount_code>
You can combine created_at_min
and created_at_max
to return all addresses created in the given timespan. This also applies to updated_at_min
and updated_at_max
parameters.
Query Parameters
- created_at_maxdatetime
Returns addresses created before the given time.
- created_at_mindatetime
Returns addresses created after the given time.
- customer_idinteger
Unique identifier of the customer.
- 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.
- is_activeboolean
Returns active addresses.
More Parameters
Responses
- 200
successful response
Show response object
curl 'https://api.rechargeapps.com/addresses' \
-H 'X-Recharge-Version: 2021-11' \
-H 'X-Recharge-Access-Token: your_api_token' \
-d limit=3 -G
{
"addresses": [
{
"id": 42171447,
"payment_method_id": 17874235,
"address1": "1030 Barnum Ave",
"address2": "Suite 101",
"city": "Stratford",
"company": "Fake Company",
"country_code": "US",
"created_at": "2022-10-12T20:16:09+00:00",
"customer_id": 37657002,
"discounts": [
{
"id": 123456
}
],
"first_name": "Fake First",
"last_name": "Fake Last",
"order_attributes": [
{
"name": "custom name",
"value": "custom value"
}
],
"order_note": "My recurring order note",
"phone": "999-999-9999",
"presentment_currency": "USD",
"province": "Connecticut",
"shipping_lines_conserved": [],
"shipping_lines_override": [
{
"code": "Standard Shipping",
"price": "0.00",
"title": "Standard Shipping"
}
],
"updated_at": "2022-10-12T20:16:09+00:00",
"zip": "06614"
}
]
}
Merge addresses
Merges up to 10 source addresses into 1 target address.
If one of the Addresses
being merged has a different presentment currency, the entire merge will fail and throw an error.
Body Parameters
- delete_source_addressesboolean
Indicates whether source addresses should be deleted.
- next_charge_datestring
Specifies the next charge date of the associated subscriptions on the target address.
- target_addressobject* Required
The address all of the subscriptions should be moved to.
Show object attributes - source_addressesarray* Required
The list of addresses that the subscriptions should move from.
More Parameters
Responses
- 200
successful response
Show response object
curl -X POST 'https://api.rechargeapps.com/addresses/merge' \
-H 'X-Recharge-Version: 2021-11' \
-H 'Content-Type: application/json' \
-H 'X-Recharge-Access-Token: your_api_token' \
-d '{"target_address": {"id": 42171447}, "source_addresses": [{"id": 42171446}, {"id": 42171445}]}'
{
"address": {
"id": 42171447,
"payment_method_id": 17874235,
"address1": "1030 Barnum Ave",
"address2": "Suite 101",
"city": "Stratford",
"company": "Fake Company",
"country_code": "US",
"created_at": "2022-10-12T20:16:09+00:00",
"customer_id": 37657002,
"discounts": [],
"first_name": "Fake First",
"last_name": "Fake Last",
"order_attributes": [
{
"name": "custom name",
"value": "custom value"
}
],
"order_note": "My recurring order note",
"phone": "999-999-9999",
"presentment_currency": "USD",
"province": "Connecticut",
"shipping_lines_conserved": [],
"shipping_lines_override": [],
"updated_at": "2022-10-12T20:16:09+00:00",
"zip": "06614"
}
}
Skip future charge
Skip a Charge
in the future for one or multiple Subscriptions
associated with the Address
.
If the Charge
does not exist on the date, it will be created with a SKIPPED
status.
Body Parameters
- datedatetime* Required
The date in the future of the
Charge
to be skipped.This date must be within the delivery schedules of the
Customer
. - subscription_idsarray* Required
A list containing the
Subscription
IDs to be skipped.
More Parameters
Responses
- 200
successful response
Show response object - 404
the
Address
withid
does not existShow response object - 422
invalid data passed to the endpoint
Show response object
curl 'https://api.rechargeapps.com/addresses/91977136/charges/skip' \
-H 'X-Recharge-Version: 2021-11' \
-H 'Content-Type: application/json' \
-H 'X-Recharge-Access-Token: your_api_token' \
-d '{"date": "2022-09-15", "purchase_item_ids": [27363808, 27363809]}'
{
"charge": {
"id": 377749210,
"address_id": 42171447,
"analytics_data": {
"utm_params": [
{
"utm_source": "facebook",
"utm_medium": "cpc"
}
]
},
"billing_address": {
"address1": "601 SW Washing St.",
"address2": "Suite 101",
"city": "Portland",
"company": "Acme Corp",
"country_code": "US",
"first_name": "Jane",
"last_name": "Doe",
"phone": "888-888-8888",
"province": "Oregon",
"zip": "97205"
},
"client_details": {
"browser_ip": "192.168.0.1",
"user_agent": "safari webkit"
},
"created_at": "2021-11-09T19:22:13+00:00",
"currency": "USD",
"customer": {
"id": 37657002,
"email": "test@test.com",
"external_customer_id": {
"ecommerce": "2879413682227"
},
"hash": "7e706455cbd13e40"
},
"discounts": [
{
"id": 12345,
"code": "TESTCODE10",
"value": 10,
"value_type": "fixed_amount"
}
],
"error": null,
"error_type": null,
"external_order_id": {
"ecommerce": "2541635698739"
},
"external_transaction_id": {
"payment_processor": "ch_1HzWElJ2zqHvZRd1TWKFFqDR"
},
"has_uncommitted_changes": false,
"line_items": [
{
"purchase_item_id": 63898947,
"external_product_id": {
"ecommerce": "4381728735283"
},
"external_variant_id": {
"ecommerce": "999999999999"
},
"grams": 454,
"handle": "shirt-package",
"images": {
"large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg",
"medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg",
"original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg",
"small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg"
},
"original_price": "10.00",
"properties": [
{
"name": "Color",
"value": "Blue"
}
],
"purchase_item_type": "subscription",
"quantity": 1,
"sku": "TOM0001",
"tax_due": "1.30",
"tax_lines": [
{
"price": "0.9931",
"rate": "0.0725",
"title": "CA State Tax",
"unit_price": "0.3310"
},
{
"price": "0.3082",
"rate": "0.0225",
"title": "LA County Tax",
"unit_price": "0.1027"
}
],
"taxable": true,
"taxable_amount": "10.00",
"title": "Shirt package",
"total_price": "11.30",
"unit_price": "10.00",
"unit_price_includes_tax": false,
"variant_title": "Blue T-shirt"
}
],
"note": "next order in sequence 3",
"order_attributes": [
{
"name": "Checkout-Method",
"value": "delivery"
}
],
"orders_count": 1,
"payment_processor": "stripe",
"processed_at": null,
"retry_date": null,
"scheduled_at": "2021-12-09",
"shipping_address": {
"address1": "1030 Barnum Ave",
"address2": "Suite 101",
"city": "Stratford",
"company": "Fake Company",
"country_code": "US",
"first_name": "Fake First",
"last_name": "Fake Last",
"phone": "999-999-9999",
"province": "Connecticut",
"zip": "06614"
},
"shipping_lines": [
{
"code": "Standard",
"price": "4.90",
"source": "shopify",
"taxable": true,
"tax_lines": [
{
"price": "0.355",
"rate": 0.0725,
"title": "CA State Tax"
},
{
"price": "0.110",
"rate": 0.0225,
"title": "Los Angeles County Tax"
}
],
"title": "Standard"
}
],
"status": "skipped",
"subtotal_price": "10.00",
"tags": "Subscription, Subscription Recurring Order",
"tax_lines": [
{
"price": "0.950",
"rate": 0.0725,
"title": "CA State Tax"
},
{
"price": "0.335",
"rate": 0.0225,
"title": "Los Angeles County Tax"
}
],
"taxable": true,
"total_discounts": "10.0",
"total_line_items_price": "10.00",
"total_price": "11.29",
"total_refunds": "0.00",
"total_tax": "1.29",
"total_weight_grams": 454,
"type": "recurring",
"updated_at": "2021-11-09T23:59:32+00:00"
}
}
A bundle selection represents the contents within a Bundle linked to an individual Subscription. It can represent the selection for upcoming orders or past orders. A BundleSelection
is associated with a corresponding Subscription
and a BundleVariant
(the BundleVariant
is used to validate contents in the selection). When a new order for the associated Subscription
occurs, it will extract the current contents of the BundleSelection
for the Bundle item in the order.
A bundle selection represents the contents within a Bundle linked to an individual Subscription. It can represent the selection for upcoming orders or past orders. A BundleSelection
is associated with a corresponding Subscription
and a BundleVariant
(the BundleVariant
is used to validate contents in the selection).
Attributes
- idinteger
The unique numeric identifier for the
BundleSelection
. - bundle_variant_idinteger
The ID of the
BundleVariant
associated with theBundleSelection
. - purchase_item_idinteger
The ID of the
PurchaseItem
associated with theBundleSelection
. - created_atdatetime
The date and time when the contents were selected.
- external_product_idstring
The product id as it appears in the external e-commerce platform. The
external_product_id
of theProduct
record in Recharge, linking theBundleSelection
to aProduct
associated with a Bundle. - external_variant_idstring
The variant id as it appears in the external e-commerce platform. The
external_variant_id
of theProduct
record in Recharge, linking theBundleSelection
to aProduct
associated with a Bundle. - itemsarray
A list of
item
objects, each containing information about a distinct product selected as part of the Bundle.Show object attributes - updated_atdatetime
The date and time at which the
BundleSelection
was most recently updated.
Error related attributes
More Attributes
{
"bundle_selection": {
"id": 100714428,
"bundle_variant": 382417,
"purchase_item_id": 199820883,
"created_at": "2022-08-26T18:31:28+00:00",
"external_product_id": "7121697210548",
"external_variant_id": "41450875650228",
"items": [
{
"id": 541,
"collection_id": "287569608884",
"collection_source": "shopify",
"created_at": "2022-08-26T18:31:28+00:00",
"external_product_id": "7121693671604",
"external_variant_id": "41450853105844",
"quantity": 3,
"updated_at": "2022-08-26T18:52:41+00:00"
}
],
"updated_at": "2022-08-26T18:31:28+00:00"
}
}
Returns a list of BundleSelections
.
HTTP request examples
GET /bundle_selections?purchase_item_ids=:purchase_item_id_1,:purchase_item_id_2
GET /bundle_selections?bundle_variant_ids=:bundle_variant_id_1,:bundle_variant_id_2
GET /bundle_selections?limit=1
GET /bundle_selections?limit=1&page=2
GET /bundle_selections?sort_by=updated_at-desc
BundleSelections
are sorted descending by ID value by default.BundleSelections
endpoints are available for Recharge Pro merchants. If you’re interested in leveraging the Recharge bundle_selections
endpoints, reach out to your account manager or our Support team.
Learn more about Recharge Pro.
Query Parameters
- purchase_item_idsstring
Filter
BundleSelections
bySubscription
orOnetime
ID.If passing multiple values, must be comma separated. Non-integer values will result in a
422
error. - bundle_variant_idsstring
Filter
BundleSelections
byBundleVariants
.If passing multiple values, must be comma separated. Non-integer values will result in a
422
error. - item_external_variant_idsstring
Filter
BundleSelections
by contents. If the Variant ID exists as a content of theBundleSelection
it will appear as a result.If passing multiple values, must be comma separated. Non-integer values will result in a
422
error. - item_external_product_idsstring
Filter
BundleSelections
by contents. If the Product ID exists as a content of theBundleSelection
it will appear as a result.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.
- sort_bystring
Sort listed
BundleSelections
in a specific order.
Available sort options:id-asc
,id-desc
,updated_at-asc
,updated_at-desc
. - active_purchase_itemsboolean
Bundle selections are not directly linked to Subscriptions. By default, the endpoint returns Bundle Selections, even those associated with cancelled subscriptions, unless the Bundle Selection has been deleted.
To exclude cancelled subscriptions from your results, includeactive_purchase_items=true
in your query.
More Parameters
Responses
- 200
successful response
Show response object
curl 'https://api.rechargeapps.com/bundle_selections' \
-H 'X-Recharge-Version: 2021-11' \
-H 'X-Recharge-Access-Token: your_api_token' \
-d limit=3 -G
{
"next_cursor": null,
"previous_cursor": null,
"bundle_selections": [
{
"id": 100714428,
"bundle_variant": 382417,
"purchase_item_id": 199820883,
"created_at": "2022-08-26T18:31:28+00:00",
"external_product_id": "7121697210548",
"external_variant_id": "41450875650228",
"items": [
{
"id": 541,
"collection_id": "287569608884",
"collection_source": "shopify",
"created_at": "2022-08-26T18:31:28+00:00",
"external_product_id": "7121693671604",
"external_variant_id": "41450853105844",
"quantity": 3,
"updated_at": "2022-08-26T18:52:41+00:00"
}
],
"updated_at": "2022-08-26T18:31:28+00:00"
}
]
}
Retrieve a BundleSelection
using the bundle_selection_id
.
BundleSelections
endpoints are available for Recharge Pro merchants. If you’re interested in leveraging the Recharge bundle_selections
endpoints, reach out to your account manager or our Support team.
Learn more about Recharge Pro.
Responses
- 200
successful response
Show response object - 404
the
BundleSelection
withbundle_selection_id
does not existShow response object
curl 'https://api.rechargeapps.com/bundle_selections/100714428' \
-H 'X-Recharge-Version: 2021-11' \
-H 'X-Recharge-Access-Token: your_api_token'
{
"bundle_selection": {
"id": 100714428,
"bundle_variant": 382417,
"purchase_item_id": 199820883,
"created_at": "2022-08-26T18:31:28+00:00",
"external_product_id": "7121697210548",
"external_variant_id": "41450875650228",
"items": [
{
"id": 541,
"collection_id": "287569608884",
"collection_source": "shopify",
"created_at": "2022-08-26T18:31:28+00:00",
"external_product_id": "7121693671604",
"external_variant_id": "41450853105844",
"quantity": 3,
"updated_at": "2022-08-26T18:52:41+00:00"
}
],
"updated_at": "2022-08-26T18:31:28+00:00"
}
}
Create a BundleSelection
.
BundleSelections
endpoints are available for Recharge Pro merchants. If you’re interested in leveraging the Recharge bundle_selections
endpoints, reach out to your account manager or our Support team.
Learn more about Recharge Pro.
Body Parameters
- purchase_item_idinteger* Required
The ID of the
PurchaseItem
associated with theBundleSelection
. - plan_idinteger
A Recharge Plan ID. If provided in a dynamically-priced Bundle, the unit price of each product variant will be inferred from the plan associated with the ID; otherwise, it will be inferred from the plan with the greatest discount for each product in the selection. This is not used in fixed-priced Bundles.
- itemsarray* Required
A list of
item
objects, each containing information about a distinct product selected as part of the Bundle.Show object attributes
More Parameters
Responses
- 200
successful response
Show response object - 422
missing required field or invalid items passed
Show response object
curl 'https://api.rechargeapps.com/bundle_selections' \
-H 'X-Recharge-Version: 2021-11' \
-H 'Content-Type: application/json' \
-H 'X-Recharge-Access-Token: your_api_token' \
-d '{
"purchase_item_id": 199820883,
"items": [
{
"collection_id": "287569608884",
"collection_source": "shopify",
"external_product_id": "7121693671604",
"external_variant_id": "41450853105844",
"quantity": 3
}
]
}'
{
"bundle_selection": {
"id": 100714428,
"bundle_variant": 382417,
"purchase_item_id": 199820883,
"created_at": "2022-08-26T18:31:28+00:00",
"external_product_id": "7121697210548",
"external_variant_id": "41450875650228",
"items": [
{
"id": 541,
"collection_id": "287569608884",
"collection_source": "shopify",
"created_at": "2022-08-26T18:31:28+00:00",
"external_product_id": "7121693671604",
"external_variant_id": "41450853105844",
"quantity": 3,
"updated_at": "2022-08-26T18:52:41+00:00"
}
],
"updated_at": "2022-08-26T18:31:28+00:00"
}
}
Modify an existing BundleSelection
to match the specified parameters.
BundleSelections
endpoints are available for Recharge Pro merchants. If you’re interested in leveraging the Recharge bundle_selections
endpoints, reach out to your account manager or our Support team.
Learn more about Recharge Pro.
Body Parameters
- purchase_item_idinteger
The ID of the
PurchaseItem
associated with theBundleSelection
. - plan_idinteger
A Recharge Plan ID. If provided in a dynamically-priced Bundle, the unit price of each product variant will be inferred from the plan associated with the ID; otherwise, it will be inferred from the plan with the greatest discount for each product in the selection. This is not used in fixed-priced Bundles.
- itemsarray
A list of
item
objects, each containing information about a distinct product selected as part of the Bundle.
More Parameters
Responses
- 200
successful response
Show response object - 404
the
BundleSelection
withbundle_selection_id
does not existShow response object - 422
invalid items passed
Show response object
curl -X PUT 'https://api.rechargeapps.com/bundle_selections/100714428' \
-H 'X-Recharge-Version: 2021-11' \
-H 'Content-Type: application/json' \
-H 'X-Recharge-Access-Token: your_api_token' \
-d '{
"purchase_item_id": 199820883,
"items": [
{
"collection_id": "287569608884",
"collection_source": "shopify",
"external_product_id": "7121693671604",
"external_variant_id": "41450853105844",
"quantity": 3
}
]
}'
{
"bundle_selection": {
"id": 100714428,
"bundle_variant": 382417,
"purchase_item_id": 199820883,
"created_at": "2022-08-26T18:31:28+00:00",
"external_product_id": "7121697210548",
"external_variant_id": "41450875650228",
"items": [
{
"id": 541,
"collection_id": "287569608884",
"collection_source": "shopify",
"created_at": "2022-08-26T18:31:28+00:00",
"external_product_id": "7121693671604",
"external_variant_id": "41450853105844",
"quantity": 3,
"updated_at": "2022-08-26T18:52:41+00:00"
}
],
"updated_at": "2022-08-26T18:31:28+00:00"
}
}
Delete a BundleSelection
BundleSelections
endpoints are available for Recharge Pro merchants. If you’re interested in leveraging the Recharge bundle_selections
endpoints, reach out to your account manager or our Support team.
Learn more about Recharge Pro.
Responses
- 204
the
BundleSelection
has been removed and there is no content to send back in the response body.Show response object - 404
the
BundleSelection
withid
does not existShow response object
curl -X DELETE 'https://api.rechargeapps.com/bundle_selections/100714428' \
-H 'X-Recharge-Version: 2021-11' \
-H 'X-Recharge-Access-Token: your_api_token'
{}
Charges
A charge is the representation of a financial transaction linked to the purchase of an item (past or future). It can be a transaction that was processed already or the representation of an upcoming transaction. A Charge
is linked to its corresponding Orders
(one Order
for pay as you go subscriptions and several for pre-paid). Orders
are created once the corresponding Charge
is successful. After successful payment, the first Order
will be immediately submitted to the external platform if applicable (e.g. Shopify, BigCommerce).
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 ID of the shipping
Address
tied to theCharge
. - 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
The date and time when the transaction was created.
- currencystring
The code of the currency for this
Charge
, such asUSD
.Related guides: Supported currencies
- customerobject
An object containing
Customer
information associated with thisCharge
.Show object attributes - discountsarray
An array of
Discounts
associated with theCharge
.Show object attributes - external_order_idobject
An object containing the associated external order ID.
Show object attributes - external_transaction_idobject
An object containing the associated external transaction ID.
Show object attributes - line_itemsarray
A list of
line_item
objects, each containing information about a distinct purchase item.Show object attributes - notestring
Notes associated with the
Charge
. - order_attributesarray
An array of name-value pairs of order attributes on the
Charge
.Show object attributes - orders_countinteger
The number of
Orders
generated from thisCharge
(>1 for prepaidSubscriptions
). - payment_processorstring
The payment processor used for this
Charge
. - processed_atdatetime
The date and time when the transaction was processed.
- scheduled_atdate
The date time of when the
Charge
is/was scheduled to process. - shipping_addressobject
The shipping
Address
of theCharge
.Show object attributes - shipping_linesarray
An array of shipping lines associated with the
Charge
.Show object attributes - statusstring
Possible values: success, error, queued, skipped, refunded, partially_refunded, pending_manual_payment, pending
The status of the
Charge
. - subtotal_pricestring
The combined price of all
line_items
without taxes and shipping. - tagsstring
A comma-separated list of tags on the
Charge
. - tax_linesarray
An array of tax lines that apply to the
Charge
.Show object attributes - taxableboolean
A boolean indicator of the taxability of the
Charge
. - taxes_includedboolean
Whether taxes are included in the order subtotal.
- total_discountsstring
The sum of the
Discounts
applied to theCharge
. - total_line_items_pricestring
The total price of all line items of 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 applied to the
Charge
. - total_taxstring
The total tax due associated with the
Charge
. - total_weight_gramsinteger
The total weight of the
Charge
’s line items in grams. - typestring
Possible values: checkout, recurring
An indicator of the
Charge
’s type, either checkout or recurring. - updated_atdatetime
The date time at which the
Charge
was most recently updated.
Error related attributes
- errorstring
Error reason as sentence text (typically returned direct from the payment processor). e.g.
"error": "Customer needs to update credit card"
- error_typestring
Structured reason why the charge failed such as
CUSTOMER_NEEDS_TO_UPDATE_CARD
. - charge_attemptsinteger
Shows how many times an attempt to charge was placed.
- external_variant_id_not_foundboolean
Indicates if Recharge was able to find the
external_variant_id
from theCharge
. - retry_datedate
The date when the next attempt will be placed.
More Attributes
- has_uncommited_changesboolean
Specifies whether the
Charge
is scheduled for a regeneration (if theSubscription
related to the charge was updated in the last 5 seconds usingcommit=false
).
{
"charge": {
"id": 100714428,
"address_id": 21317826,
"analytics_data": {
"utm_params": [
{
"utm_campaign": "spring_sale",
"utm_content": "differentiate-content",
"utm_data_source": "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_code": "US",
"first_name": "Mike",
"last_name": "Flynn",
"phone": "3103843698",
"province": "California",
"zip": "90404"
},
"client_details": {
"browser_ip": "192.168.0.1",
"user_agent": "safari webkit"
},
"created_at": "2018-11-14T09:45:44+00:00",
"currency": "USD",
"customer": {
"id": 12345,
"email": "test@test.com",
"external_customer_id": {
"ecommerce": "2879413682227"
},
"hash": "7e706455cbd13e40"
},
"discounts": [
{
"id": 12345,
"code": "10DOLLAROFF",
"value": 10,
"value_type": "fixed_amount"
}
],
"error": null,
"error_type": null,
"external_order_id": {
"ecommerce": "2541635698739"
},
"external_transaction_id": {
"payment_processor": "ch_XXXXXXXXXXXXXXX"
},
"has_uncommitted_changes": false,
"line_items": [
{
"purchase_item_id": 63898947,
"external_product_id": {
"ecommerce": "4381728735283"
},
"external_variant_id": {
"ecommerce": "99999999999"
},
"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",
"properties": [
{
"name": "grind",
"value": "drip"
}
],
"purchase_item_type": "subscription",
"quantity": 1,
"sku": "MILK-1",
"tax_due": "1.14",
"tax_lines": [
{
"price": "0.870",
"rate": 0.0725,
"title": "CA State Tax"
},
{
"price": "0.270",
"rate": 0.0225,
"title": "Los Angeles County Tax"
}
],
"taxable": true,
"taxable_amount": "12.00",
"title": "Sumatra Coffee",
"total_price": "13.14",
"unit_price": "12.00",
"variant_title": "Milk - a / b"
}
],
"note": "next order #1",
"order_attributes": [
{
"name": "custom name",
"value": "custom value"
}
],
"processor_name": "stripe",
"scheduled_at": "2018-12-12",
"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"
}
],
"status": "queued",
"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"
}
],
"taxes_included": true,
"total_discounts": "0.00",
"total_line_items_price": "12.00",
"total_price": "13.14",
"total_refunds": null,
"total_tax": "1.14",
"total_weight_grams": 4536,
"type": "recurring",
"updated_at": "2018-11-14T09:45:44+00:00"
}
}
Retrieve a charge
Retrieve a Charge
using the charge_id
.
Responses
- 200
successful response
Show response object
curl 'https://api.rechargeapps.com/charges/377749210' \
-H 'X-Recharge-Version: 2021-11' \
-H 'X-Recharge-Access-Token: your_api_token'
{
"charge": {
"id": 377749210,
"address_id": 42171447,
"analytics_data": {
"utm_params": [
{
"utm_source": "facebook",
"utm_medium": "cpc"
}
]
},
"billing_address": {
"address1": "601 SW Washing St.",
"address2": "Suite 101",
"city": "Portland",
"company": "Acme Corp",
"country_code": "US",
"first_name": "Jane",
"last_name": "Doe",
"phone": "888-888-8888",
"province": "Oregon",
"zip": "97205"
},
"client_details": {
"browser_ip": "192.168.0.1",
"user_agent": "safari webkit"
},
"created_at": "2021-11-09T19:22:13+00:00",
"currency": "USD",
"customer": {
"id": 37657002,
"email": "test@test.com",
"external_customer_id": {
"ecommerce": "2879413682227"
},
"hash": "7e706455cbd13e40"
},
"discounts": [
{
"id": 12345,
"code": "TESTCODE10",
"value": 10,
"value_type": "fixed_amount"
}
],
"error": null,
"error_type": null,
"external_order_id": {
"ecommerce": "2541635698739"
},
"external_transaction_id": {
"payment_processor": "ch_1HzWElJ2zqHvZRd1TWKFFqDR"
},
"has_uncommitted_changes": false,
"line_items": [
{
"purchase_item_id": 63898947,
"external_product_id": {
"ecommerce": "4381728735283"
},
"external_variant_id": {
"ecommerce": "999999999999"
},
"grams": 454,
"handle": "shirt-package",
"images": {
"large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg",
"medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg",
"original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg",
"small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg"
},
"original_price": "10.00",
"properties": [
{
"name": "Color",
"value": "Blue"
}
],
"purchase_item_type": "subscription",
"quantity": 1,
"sku": "TOM0001",
"tax_due": "1.30",
"tax_lines": [
{
"price": "0.9931",
"rate": "0.0725",
"title": "CA State Tax",
"unit_price": "0.3310"
},
{
"price": "0.3082",
"rate": "0.0225",
"title": "LA County Tax",
"unit_price": "0.1027"
}
],
"taxable": true,
"taxable_amount": "10.00",
"title": "Shirt package",
"total_price": "11.30",
"unit_price": "10.00",
"unit_price_includes_tax": false,
"variant_title": "Blue T-shirt"
}
],
"note": "next order in sequence 3",
"order_attributes": [
{
"name": "Checkout-Method",
"value": "delivery"
}
],
"orders_count": 1,
"payment_processor": "stripe",
"processed_at": "2021-11-09T23:59:31+00:00",
"retry_date": "2021-01-01",
"scheduled_at": "2021-12-09",
"shipping_address": {
"address1": "1030 Barnum Ave",
"address2": "Suite 101",
"city": "Stratford",
"company": "Fake Company",
"country_code": "US",
"first_name": "Fake First",
"last_name": "Fake Last",
"phone": "999-999-9999",
"province": "Connecticut",
"zip": "06614"
},
"shipping_lines": [
{
"code": "Standard",
"price": "4.90",
"source": "shopify",
"taxable": true,
"tax_lines": [
{
"price": "0.355",
"rate": 0.0725,
"title": "CA State Tax"
},
{
"price": "0.110",
"rate": 0.0225,
"title": "Los Angeles County Tax"
}
],
"title": "Standard"
}
],
"status": "success",
"subtotal_price": "10.00",
"tags": "Subscription, Subscription Recurring Order",
"tax_lines": [
{
"price": "0.950",
"rate": 0.0725,
"title": "CA State Tax"
},
{
"price": "0.335",
"rate": 0.0225,
"title": "Los Angeles County Tax"
}
],
"taxable": true,
"taxes_included": true,
"total_discounts": "10.0",
"total_line_items_price": "10.00",
"total_price": "11.29",
"total_refunds": "0.00",
"total_tax": "1.29",
"total_weight_grams": 454,
"type": "recurring",
"updated_at": "2021-11-09T23:59:32+00:00"
}
}
List charges
Returns a list of Charges
.
HTTP request examples
GET /charges?address_id=:address_id
GET /charges?created_at_min=2016-05-18&created_at_max=2016-06-18
GET /charges?customer_id=:customer_id
GET /charges?discount_code=10PERCENTOFF
GET /charges?discount_id=:discount_id
GET /charges?external_order_id=:external_order_id
GET /charges?ids=1123551,262667345,12341535
GET /charges?purchase_item_id=:purchase_item_id
GET /charges?scheduled_at=2016-06-18
GET /charges?scheduled_at_min=2016-05-18&scheduled_at_max=2016-06-18
GET /charges?sort_by=id-desc
GET /charges?status=queued
GET /charges?status=queued,refunded,partially_refunded
GET /charges?updated_at_min=2016-05-18&updated_at_max=2016-06-18
GET /charges?processed_at_min=2022-01-18&processed_at_max=2022-02-18
Returned Charges
are sorted ascending by ID value by default.
Query Parameters
- address_idstring
Filter
Charges
byAddress
. - created_at_maxstring
Show
Charges
created before the given date. - created_at_minstring
Show
Charges
created after the given date. - customer_idstring
Filter
Charges
byCustomer
. - discount_codestring
List
Charges
that contain the givendiscount_code
. - discount_idstring
List
Charges
that contain the givendiscount_id
. - external_order_idstring
Filter
Charges
by the associated order ID in the external e-commerce platform. - 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.
- purchase_item_idstring
Filter
Charges
by aSubscription
orOnetime
ID. - purchase_item_idsstring
Filter
Charges
by a comma-separated list ofSubscription
orOnetime
IDs. - scheduled_atstring
Filter
Charges
by specific scheduled charge date. - scheduled_at_maxstring
Show
Charges
scheduled to be processed before the given date. - scheduled_at_minstring
Show
Charges
scheduled to be processed after the given date. - sort_bystring
Sort listed
Charges
in a specific order.
Available sort options:id-asc
,id-desc
,updated_at-asc
,updated_at-desc
,scheduled_at-asc
,scheduled_at-desc
. - statusstring
Filter charges by status.
Available status:success
,queued
,error
,refunded
,partially_refunded
,skipped
,pending_manual_payment
,pending
. - updated_at_maxstring
Show charges updated before the given date.
- updated_at_minstring
Show charges updated after the given date.
- processed_at_minstring
Show charges processed after, and including, the given date.
- processed_at_maxstring
Show charges processed before, and including, the given date.
More Parameters
Responses
- 200
successful response
Show response object
curl 'https://api.rechargeapps.com/charges' \
-H 'X-Recharge-Version: 2021-11' \
-H 'X-Recharge-Access-Token: your_api_token' \
-d limit=3 -G
{
"next": "next_cursor",
"previous": "previous_cursor",
"charges": [
{
"id": 377749210,
"address_id": 42171447,
"analytics_data": {
"utm_params": [
{
"utm_source": "facebook",
"utm_medium": "cpc"
}
]
},
"billing_address": {
"address1": "601 SW Washing St.",
"address2": "Suite 101",
"city": "Portland",
"company": "Acme Corp",
"country_code": "US",
"first_name": "Jane",
"last_name": "Doe",
"phone": "888-888-8888",
"province": "Oregon",
"zip": "97205"
},
"client_details": {
"browser_ip": "192.168.0.1",
"user_agent": "safari webkit"
},
"created_at": "2021-11-09T19:22:13+00:00",
"currency": "USD",
"customer": {
"id": 37657002,
"email": "test@test.com",
"external_customer_id": {
"ecommerce": "2879413682227"
},
"hash": "7e706455cbd13e40"
},
"discounts": [
{
"id": 12345,
"code": "TESTCODE10",
"value": 10,
"value_type": "fixed_amount"
}
],
"error": null,
"error_type": null,
"external_order_id": {
"ecommerce": "2541635698739"
},
"external_transaction_id": {
"payment_processor": "ch_1HzWElJ2zqHvZRd1TWKFFqDR"
},
"has_uncommitted_changes": false,
"line_items": [
{
"purchase_item_id": 63898947,
"external_product_id": {
"ecommerce": "4381728735283"
},
"external_variant_id": {
"ecommerce": "999999999999"
},
"grams": 454,
"handle": "shirt-package",
"images": {
"large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg",
"medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg",
"original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg",
"small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg"
},
"original_price": "10.00",
"properties": [
{
"name": "Color",
"value": "Blue"
}
],
"purchase_item_type": "subscription",
"quantity": 1,
"sku": "TOM0001",
"tax_due": "1.30",
"tax_lines": [
{
"price": "0.9931",
"rate": "0.0725",
"title": "CA State Tax",
"unit_price": "0.3310"
},
{
"price": "0.3082",
"rate": "0.0225",
"title": "LA County Tax",
"unit_price": "0.1027"
}
],
"taxable": true,
"taxable_amount": "10.00",
"title": "Shirt package",
"total_price": "11.30",
"unit_price": "10.00",
"unit_price_includes_tax": false,
"variant_title": "Blue T-shirt"
}
],
"note": "next order in sequence 3",
"order_attributes": [
{
"name": "Checkout-Method",
"value": "delivery"
}
],
"orders_count": 1,
"payment_processor": "stripe",
"processed_at": "2021-11-09T23:59:31+00:00",
"retry_date": "2021-01-01",
"scheduled_at": "2021-12-09",
"shipping_address": {
"address1": "1030 Barnum Ave",
"address2": "Suite 101",
"city": "Stratford",
"company": "Fake Company",
"country_code": "US",
"first_name": "Fake First",
"last_name": "Fake Last",
"phone": "999-999-9999",
"province": "Connecticut",
"zip": "06614"
},
"shipping_lines": [
{
"code": "Standard",
"price": "4.90",
"source": "shopify",
"taxable": true,
"tax_lines": [
{
"price": "0.355",
"rate": 0.0725,
"title": "CA State Tax"
},
{
"price": "0.110",
"rate": 0.0225,
"title": "Los Angeles County Tax"
}
],
"title": "Standard"
}
],
"status": "success",
"subtotal_price": "10.00",
"tags": "Subscription, Subscription Recurring Order",
"tax_lines": [
{
"price": "0.950",
"rate": 0.0725,
"title": "CA State Tax"
},
{
"price": "0.335",
"rate": 0.0225,
"title": "Los Angeles County Tax"
}
],
"taxable": true,
"taxes_included": true,
"total_discounts": "10.0",
"total_line_items_price": "10.00",
"total_price": "11.29",
"total_refunds": "0.00",
"total_tax": "1.29",
"total_weight_grams": 454,
"type": "recurring",
"updated_at": "2021-11-09T23:59:32+00:00"
}
]
}
Apply a discount
Endpoint for adding Discount
to an existing queued Charge
.
You cannot add a Discount
to an existing queued Charge
if the Charge
or the associated Address
already has one.
You can provide either discount_id
or discount_code
. If both parameters are passed, the value for discount_id
will take precedence.
If a Charge
has a Discount
and it gets updated, or a regeneration occurs, the Discount
will be lost. Regeneration is a process that refreshes the Charge
JSON with new data in the case of the Subscription
or Address
being updated.
Body Parameters
- discount_codestring
Code of the
Discount
you want to apply to aCharge
. - discount_idinteger
ID of the
Discount
you want to apply to aCharge
.
More Parameters
Responses
- 200
successful response
Show response object
curl 'https://api.rechargeapps.com/charges/105805051/apply_discount' \
-H 'Content-Type: application/json' \
-H 'X-Recharge-Version: 2021-11' \
-H 'X-Recharge-Access-Token: your_api_token' \
-d '{"discount_code": "test"}'
{
"charge": {
"id": 377749210,
"address_id": 42171447,
"analytics_data": {
"utm_params": [
{
"utm_source": "facebook",
"utm_medium": "cpc"
}
]
},
"billing_address": {
"address1": "601 SW Washing St.",
"address2": "Suite 101",
"city": "Portland",
"company": "Acme Corp",
"country_code": "US",
"first_name": "Jane",
"last_name": "Doe",
"phone": "888-888-8888",
"province": "Oregon",
"zip": "97205"
},
"client_details": {
"browser_ip": "192.168.0.1",
"user_agent": "safari webkit"
},
"created_at": "2021-11-09T19:22:13+00:00",
"currency": "USD",
"customer": {
"id": 37657002,
"email": "test@test.com",
"external_customer_id": {
"ecommerce": "2879413682227"
},
"hash": "7e706455cbd13e40"
},
"discounts": [
{
"id": 12345,
"code": "TESTCODE10",
"value": 10,
"value_type": "fixed_amount"
}
],
"error": null,
"error_type": null,
"external_order_id": {
"ecommerce": "2541635698739"
},
"external_transaction_id": {
"payment_processor": "ch_1HzWElJ2zqHvZRd1TWKFFqDR"
},
"has_uncommitted_changes": false,
"line_items": [
{
"purchase_item_id": 63898947,
"external_product_id": {
"ecommerce": "4381728735283"
},
"external_variant_id": {
"ecommerce": "999999999999"
},
"grams": 454,
"handle": "shirt-package",
"images": {
"large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg",
"medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg",
"original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg",
"small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg"
},
"original_price": "10.00",
"properties": [
{
"name": "Color",
"value": "Blue"
}
],
"purchase_item_type": "subscription",
"quantity": 1,
"sku": "TOM0001",
"tax_due": "1.30",
"tax_lines": [
{
"price": "0.9931",
"rate": "0.0725",
"title": "CA State Tax",
"unit_price": "0.3310"
},
{
"price": "0.3082",
"rate": "0.0225",
"title": "LA County Tax",
"unit_price": "0.1027"
}
],
"taxable": true,
"taxable_amount": "10.00",
"title": "Shirt package",
"total_price": "11.30",
"unit_price": "10.00",
"unit_price_includes_tax": false,
"variant_title": "Blue T-shirt"
}
],
"note": "next order in sequence 3",
"order_attributes": [
{
"name": "Checkout-Method",
"value": "delivery"
}
],
"orders_count": 1,
"payment_processor": "stripe",
"processed_at": "2021-11-09T23:59:31+00:00",
"retry_date": "2021-01-01",
"scheduled_at": "2021-12-09",
"shipping_address": {
"address1": "1030 Barnum Ave",
"address2": "Suite 101",
"city": "Stratford",
"company": "Fake Company",
"country_code": "US",
"first_name": "Fake First",
"last_name": "Fake Last",
"phone": "999-999-9999",
"province": "Connecticut",
"zip": "06614"
},
"shipping_lines": [
{
"code": "Standard",
"price": "4.90",
"source": "shopify",
"taxable": true,
"tax_lines": [
{
"price": "0.355",
"rate": 0.0725,
"title": "CA State Tax"
},
{
"price": "0.110",
"rate": 0.0225,
"title": "Los Angeles County Tax"
}
],
"title": "Standard"
}
],
"status": "success",
"subtotal_price": "10.00",
"tags": "Subscription, Subscription Recurring Order",
"tax_lines": [
{
"price": "0.950",
"rate": 0.0725,
"title": "CA State Tax"
},
{
"price": "0.335",
"rate": 0.0225,
"title": "Los Angeles County Tax"
}
],
"taxable": true,
"total_discounts": "10.0",
"total_line_items_price": "10.00",
"total_price": "11.29",
"total_refunds": "0.00",
"total_tax": "1.29",
"total_weight_grams": 454,
"type": "recurring",
"updated_at": "2021-11-09T23:59:32+00:00"
}
}
Remove a discount
Remove a Discount
from a Charge
without destroying the Discount
.
HTTP request examples
POST /charges/<charge_id>/remove_discount/
In most cases the Discount
should be removed from the Address
. When the Discount
is removed from the Address
, the Discount
is also removed from any future Charges
.
If the Discount
is on the parent Address
, you cannot remove it using charge_id
. When removing your Discount
, it is preferable to pass the address_id
so that the Discount
stays removed if the Charge
is regenerated. Only pass charge_id
in edge cases in which there are two or more Charges
on a parent Address
and you only want to remove the Discount
from one Charge
. If you pass both parameters, it will remove the Discount
from the Address
.
Responses
- 200
successful response
Show response object
curl 'https://api.rechargeapps.com/charges/459904607/remove_discount' \
-H 'Content-Type: application/json' \
-H 'X-Recharge-Version: 2021-11' \
-H 'X-Recharge-Access-Token: your_api_token' \
-d '{}'
{
"charge": {
"id": 377749210,
"address_id": 42171447,
"analytics_data": {
"utm_params": [
{
"utm_source": "facebook",
"utm_medium": "cpc"
}
]
},
"billing_address": {
"address1": "601 SW Washing St.",
"address2": "Suite 101",
"city": "Portland",
"company": "Acme Corp",
"country_code": "US",
"first_name": "Jane",
"last_name": "Doe",
"phone": "888-888-8888",
"province": "Oregon",
"zip": "97205"
},
"client_details": {
"browser_ip": "192.168.0.1",
"user_agent": "safari webkit"
},
"created_at": "2021-11-09T19:22:13+00:00",
"currency": "USD",
"customer": {
"id": 37657002,
"email": "test@test.com",
"external_customer_id": {
"ecommerce": "2879413682227"
},
"hash": "7e706455cbd13e40"
},
"discounts": [],
"error": null,
"error_type": null,
"external_order_id": {
"ecommerce": "2541635698739"
},
"external_transaction_id": {
"payment_processor": "ch_1HzWElJ2zqHvZRd1TWKFFqDR"
},
"has_uncommitted_changes": false,
"line_items": [
{
"purchase_item_id": 63898947,
"external_product_id": {
"ecommerce": "4381728735283"
},
"external_variant_id": {
"ecommerce": "999999999999"
},
"grams": 454,
"handle": "shirt-package",
"images": {
"large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg",
"medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg",
"original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg",
"small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg"
},
"original_price": "10.00",
"properties": [
{
"name": "Color",
"value": "Blue"
}
],
"purchase_item_type": "subscription",
"quantity": 1,
"sku": "TOM0001",
"tax_due": "1.30",
"tax_lines": [
{
"price": "0.9931",
"rate": "0.0725",
"title": "CA State Tax",
"unit_price": "0.3310"
},
{
"price": "0.3082",
"rate": "0.0225",
"title": "LA County Tax",
"unit_price": "0.1027"
}
],
"taxable": true,
"taxable_amount": "10.00",
"title": "Shirt package",
"total_price": "11.30",
"unit_price": "10.00",
"unit_price_includes_tax": false,
"variant_title": "Blue T-shirt"
}
],
"note": "next order in sequence 3",
"order_attributes": [
{
"name": "Checkout-Method",
"value": "delivery"
}
],
"orders_count": 1,
"payment_processor": "stripe",
"processed_at": "2021-11-09T23:59:31+00:00",
"retry_date": "2021-01-01",
"scheduled_at": "2021-12-09",
"shipping_address": {
"address1": "1030 Barnum Ave",
"address2": "Suite 101",
"city": "Stratford",
"company": "Fake Company",
"country_code": "US",
"first_name": "Fake First",
"last_name": "Fake Last",
"phone": "999-999-9999",
"province": "Connecticut",
"zip": "06614"
},
"shipping_lines": [
{
"code": "Standard",
"price": "4.90",
"source": "shopify",
"taxable": true,
"tax_lines": [
{
"price": "0.355",
"rate": 0.0725,
"title": "CA State Tax"
},
{
"price": "0.110",
"rate": 0.0225,
"title": "Los Angeles County Tax"
}
],
"title": "Standard"
}
],
"status": "success",
"subtotal_price": "10.00",
"tags": "Subscription, Subscription Recurring Order",
"tax_lines": [
{
"price": "0.950",
"rate": 0.0725,
"title": "CA State Tax"
},
{
"price": "0.335",
"rate": 0.0225,
"title": "Los Angeles County Tax"
}
],
"taxable": true,
"total_discounts": "10.0",
"total_line_items_price": "10.00",
"total_price": "11.29",
"total_refunds": "0.00",
"total_tax": "1.29",
"total_weight_grams": 454,
"type": "recurring",
"updated_at": "2021-11-09T23:59:32+00:00"
}
}
Skip a charge
Skip a Charge
.
Responses
- 200
successful response
Show response object
curl 'https://api.rechargeapps.com/charges/377749210/skip' \
-H 'X-Recharge-Version: 2021-11' \
-H 'Content-Type: application/json' \
-H 'X-Recharge-Access-Token: your_api_token' \
-d '{"purchase_item_ids": [27363808, 27363809]}'
{
"charge": {
"id": 377749210,
"address_id": 42171447,
"analytics_data": {
"utm_params": [
{
"utm_source": "facebook",
"utm_medium": "cpc"
}
]
},
"billing_address": {
"address1": "601 SW Washing St.",
"address2": "Suite 101",
"city": "Portland",
"company": "Acme Corp",
"country_code": "US",
"first_name": "Jane",
"last_name": "Doe",
"phone": "888-888-8888",
"province": "Oregon",
"zip": "97205"
},
"client_details": {
"browser_ip": "192.168.0.1",
"user_agent": "safari webkit"
},
"created_at": "2021-11-09T19:22:13+00:00",
"currency": "USD",
"customer": {
"id": 37657002,
"email": "test@test.com",
"external_customer_id": {
"ecommerce": "2879413682227"
},
"hash": "7e706455cbd13e40"
},
"discounts": [
{
"id": 12345,
"code": "TESTCODE10",
"value": 10,
"value_type": "fixed_amount"
}
],
"error": null,
"error_type": null,
"external_order_id": {
"ecommerce": "2541635698739"
},
"external_transaction_id": {
"payment_processor": "ch_1HzWElJ2zqHvZRd1TWKFFqDR"
},
"has_uncommitted_changes": false,
"line_items": [
{
"purchase_item_id": 63898947,
"external_product_id": {
"ecommerce": "4381728735283"
},
"external_variant_id": {
"ecommerce": "999999999999"
},
"grams": 454,
"handle": "shirt-package",
"images": {
"large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg",
"medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg",
"original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg",
"small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg"
},
"original_price": "10.00",
"properties": [
{
"name": "Color",
"value": "Blue"
}
],
"purchase_item_type": "subscription",
"quantity": 1,
"sku": "TOM0001",
"tax_due": "1.30",
"tax_lines": [
{
"price": "0.9931",
"rate": "0.0725",
"title": "CA State Tax",
"unit_price": "0.3310"
},
{
"price": "0.3082",
"rate": "0.0225",
"title": "LA County Tax",
"unit_price": "0.1027"
}
],
"taxable": true,
"taxable_amount": "10.00",
"title": "Shirt package",
"total_price": "11.30",
"unit_price": "10.00",
"unit_price_includes_tax": false,
"variant_title": "Blue T-shirt"
}
],
"note": "next order in sequence 3",
"order_attributes": [
{
"name": "Checkout-Method",
"value": "delivery"
}
],
"orders_count": 1,
"payment_processor": "stripe",
"processed_at": null,
"retry_date": null,
"scheduled_at": "2021-12-09",
"shipping_address": {
"address1": "1030 Barnum Ave",
"address2": "Suite 101",
"city": "Stratford",
"company": "Fake Company",
"country_code": "US",
"first_name": "Fake First",
"last_name": "Fake Last",
"phone": "999-999-9999",
"province": "Connecticut",
"zip": "06614"
},
"shipping_lines": [
{
"code": "Standard",
"price": "4.90",
"source": "shopify",
"taxable": true,
"tax_lines": [
{
"price": "0.355",
"rate": 0.0725,
"title": "CA State Tax"
},
{
"price": "0.110",
"rate": 0.0225,
"title": "Los Angeles County Tax"
}
],
"title": "Standard"
}
],
"status": "skipped",
"subtotal_price": "10.00",
"tags": "Subscription, Subscription Recurring Order",
"tax_lines": [
{
"price": "0.950",
"rate": 0.0725,
"title": "CA State Tax"
},
{
"price": "0.335",
"rate": 0.0225,
"title": "Los Angeles County Tax"
}
],
"taxable": true,
"total_discounts": "10.0",
"total_line_items_price": "10.00",
"total_price": "11.29",
"total_refunds": "0.00",
"total_tax": "1.29",
"total_weight_grams": 454,
"type": "recurring",
"updated_at": "2021-11-09T23:59:32+00:00"
}
}
Unskip a charge
Unskip a Charge
.
Responses
- 200
successful response
Show response object - 422
Unprocessable
Show response object
curl 'https://api.rechargeapps.com/charges/377749210/unskip' \
-H 'X-Recharge-Version: 2021-11' \
-H 'Content-Type: application/json' \
-H 'X-Recharge-Access-Token: your_api_token' \
-d '{"purchase_item_ids": [27363808]}'
{
"charge": {
"id": 377749210,
"address_id": 42171447,
"analytics_data": {
"utm_params": [
{
"utm_source": "facebook",
"utm_medium": "cpc"
}
]
},
"billing_address": {
"address1": "601 SW Washing St.",
"address2": "Suite 101",
"city": "Portland",
"company": "Acme Corp",
"country_code": "US",
"first_name": "Jane",
"last_name": "Doe",
"phone": "888-888-8888",
"province": "Oregon",
"zip": "97205"
},
"client_details": {
"browser_ip": "192.168.0.1",
"user_agent": "safari webkit"
},
"created_at": "2021-11-09T19:22:13+00:00",
"currency": "USD",
"customer": {
"id": 37657002,
"email": "test@test.com",
"external_customer_id": {
"ecommerce": "2879413682227"
},
"hash": "7e706455cbd13e40"
},
"discounts": [
{
"id": 12345,
"code": "TESTCODE10",
"value": 10,
"value_type": "fixed_amount"
}
],
"error": null,
"error_type": null,
"external_order_id": {
"ecommerce": "2541635698739"
},
"external_transaction_id": {
"payment_processor": "ch_1HzWElJ2zqHvZRd1TWKFFqDR"
},
"has_uncommitted_changes": false,
"line_items": [
{
"purchase_item_id": 63898947,
"external_product_id": {
"ecommerce": "4381728735283"
},
"external_variant_id": {
"ecommerce": "999999999999"
},
"grams": 454,
"handle": "shirt-package",
"images": {
"large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg",
"medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg",
"original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg",
"small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg"
},
"original_price": "10.00",
"properties": [
{
"name": "Color",
"value": "Blue"
}
],
"purchase_item_type": "subscription",
"quantity": 1,
"sku": "TOM0001",
"tax_due": "1.30",
"tax_lines": [
{
"price": "0.9931",
"rate": "0.0725",
"title": "CA State Tax",
"unit_price": "0.3310"
},
{
"price": "0.3082",
"rate": "0.0225",
"title": "LA County Tax",
"unit_price": "0.1027"
}
],
"taxable": true,
"taxable_amount": "10.00",
"title": "Shirt package",
"total_price": "11.30",
"unit_price": "10.00",
"unit_price_includes_tax": false,
"variant_title": "Blue T-shirt"
}
],
"note": "next order in sequence 3",
"order_attributes": [
{
"name": "Checkout-Method",
"value": "delivery"
}
],
"orders_count": 1,
"payment_processor": "stripe",
"processed_at": null,
"retry_date": null,
"scheduled_at": "2021-12-09",
"shipping_address": {
"address1": "1030 Barnum Ave",
"address2": "Suite 101",
"city": "Stratford",
"company": "Fake Company",
"country_code": "US",
"first_name": "Fake First",
"last_name": "Fake Last",
"phone": "999-999-9999",
"province": "Connecticut",
"zip": "06614"
},
"shipping_lines": [
{
"code": "Standard",
"price": "4.90",
"source": "shopify",
"taxable": true,
"tax_lines": [
{
"price": "0.355",
"rate": 0.0725,
"title": "CA State Tax"
},
{
"price": "0.110",
"rate": 0.0225,
"title": "Los Angeles County Tax"
}
],
"title": "Standard"
}
],
"status": "queued",
"subtotal_price": "10.00",
"tags": "Subscription, Subscription Recurring Order",
"tax_lines": [
{
"price": "0.950",
"rate": 0.0725,
"title": "CA State Tax"
},
{
"price": "0.335",
"rate": 0.0225,
"title": "Los Angeles County Tax"
}
],
"taxable": true,
"total_discounts": "10.0",
"total_line_items_price": "10.00",
"total_price": "11.29",
"total_refunds": "0.00",
"total_tax": "1.29",
"total_weight_grams": 454,
"type": "recurring",
"updated_at": "2021-11-09T23:59:32+00:00"
}
}
Refund a charge
Refund a Charge
.
After the POST
request, that particular Charge
will have status
parameter updated to refunded
or partially_refunded
depending on the value of the amount
parameter. If retry
is true
, error
and error_type
are required, the Charge
will have status
parameter updated to error
. This means a new transaction would occur if the charge dunning process succeeds again. This functionality is used when the order submission attempt on the remote platform failed after the transaction succeeded.
Body Parameters
- amountstring* Required
Amount of money that will be refunded. It can be fully or partially refunded.
- full_refundboolean
If this parameter has value
true
, theCharge
will be totally refunded. - retryboolean
If this parameter has value
true
andfull_refund
has valuetrue
, theCharge
will be retried. Thestatus
on theCharge
will be returned as “error”. - errorstring
If the
retry
parameter has valuetrue
, this value is required. Valid values are “insufficient_inventory”. - error_typestring
If the
retry
parameter has valuetrue
, this value is required.
More Parameters
Responses
- 200
successful response
Show response object
curl 'https://api.rechargeapps.com/charges/377749210/refund' \
-H 'X-Recharge-Version: 2021-11' \
-H 'Content-Type: application/json' \
-H 'X-Recharge-Access-Token: your_api_token' \
-d '{"amount": 11.00}'
{
"charge": {
"id": 377749210,
"address_id": 42171447,
"analytics_data": {
"utm_params": [
{
"utm_source": "facebook",
"utm_medium": "cpc"
}
]
},
"billing_address": {
"address1": "601 SW Washing St.",
"address2": "Suite 101",
"city": "Portland",
"company": "Acme Corp",
"country_code": "US",
"first_name": "Jane",
"last_name": "Doe",
"phone": "888-888-8888",
"province": "Oregon",
"zip": "97205"
},
"client_details": {
"browser_ip": "192.168.0.1",
"user_agent": "safari webkit"
},
"created_at": "2021-11-09T19:22:13+00:00",
"currency": "USD",
"customer": {
"id": 37657002,
"email": "test@test.com",
"external_customer_id": {
"ecommerce": "2879413682227"
},
"hash": "7e706455cbd13e40"
},
"discounts": [
{
"id": 12345,
"code": "TESTCODE10",
"value": 10,
"value_type": "fixed_amount"
}
],
"error": null,
"error_type": null,
"external_order_id": {
"ecommerce": "2541635698739"
},
"external_transaction_id": {
"payment_processor": "ch_1HzWElJ2zqHvZRd1TWKFFqDR"
},
"has_uncommitted_changes": false,
"line_items": [
{
"purchase_item_id": 63898947,
"external_product_id": {
"ecommerce": "4381728735283"
},
"external_variant_id": {
"ecommerce": "999999999999"
},
"grams": 454,
"handle": "shirt-package",
"images": {
"large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg",
"medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg",
"original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg",
"small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg"
},
"original_price": "10.00",
"properties": [
{
"name": "Color",
"value": "Blue"
}
],
"purchase_item_type": "subscription",
"quantity": 1,
"sku": "TOM0001",
"tax_due": "1.30",
"tax_lines": [
{
"price": "0.9931",
"rate": "0.0725",
"title": "CA State Tax",
"unit_price": "0.3310"
},
{
"price": "0.3082",
"rate": "0.0225",
"title": "LA County Tax",
"unit_price": "0.1027"
}
],
"taxable": true,
"taxable_amount": "10.00",
"title": "Shirt package",
"total_price": "11.30",
"unit_price": "10.00",
"unit_price_includes_tax": false,
"variant_title": "Blue T-shirt"
}
],
"note": "next order in sequence 3",
"order_attributes": [
{
"name": "Checkout-Method",
"value": "delivery"
}
],
"orders_count": 1,
"payment_processor": "stripe",
"processed_at": "2021-11-09T23:59:31+00:00",
"retry_date": null,
"scheduled_at": "2021-12-09",
"shipping_address": {
"address1": "1030 Barnum Ave",
"address2": "Suite 101",
"city": "Stratford",
"company": "Fake Company",
"country_code": "US",
"first_name": "Fake First",
"last_name": "Fake Last",
"phone": "999-999-9999",
"province": "Connecticut",
"zip": "06614"
},
"shipping_lines": [
{
"code": "Standard",
"price": "4.90",
"source": "shopify",
"taxable": true,
"tax_lines": [
{
"price": "0.355",
"rate": 0.0725,
"title": "CA State Tax"
},
{
"price": "0.110",
"rate": 0.0225,
"title": "Los Angeles County Tax"
}
],
"title": "Standard"
}
],
"status": "refunded",
"subtotal_price": "10.00",
"tags": "Subscription, Subscription Recurring Order",
"tax_lines": [
{
"price": "0.950",
"rate": 0.0725,
"title": "CA State Tax"
},
{
"price": "0.335",
"rate": 0.0225,
"title": "Los Angeles County Tax"
}
],
"taxable": true,
"total_discounts": "10.0",
"total_line_items_price": "10.00",
"total_price": "11.29",
"total_refunds": "11.29",
"total_tax": "1.29",
"total_weight_grams": 454,
"type": "recurring",
"updated_at": "2021-11-09T23:59:32+00:00"
}
}
Process a charge
Pro only
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 'X-Recharge-Version: 2021-11' \
-H 'Content-Type: application/json' \
-H 'X-Recharge-Access-Token: your_api_token' \
-d '{}'
{
"charge": {
"id": 377749210,
"address_id": 42171447,
"analytics_data": {
"utm_params": [
{
"utm_source": "facebook",
"utm_medium": "cpc"
}
]
},
"billing_address": {
"address1": "601 SW Washing St.",
"address2": "Suite 101",
"city": "Portland",
"company": "Acme Corp",
"country_code": "US",
"first_name": "Jane",
"last_name": "Doe",
"phone": "888-888-8888",
"province": "Oregon",
"zip": "97205"
},
"client_details": {
"browser_ip": "192.168.0.1",
"user_agent": "safari webkit"
},
"created_at": "2021-11-09T19:22:13+00:00",
"currency": "USD",
"customer": {
"id": 37657002,
"email": "test@test.com",
"external_customer_id": {
"ecommerce": "2879413682227"
},
"hash": "7e706455cbd13e40"
},
"discounts": [
{
"id": 12345,
"code": "TESTCODE10",
"value": 10,
"value_type": "fixed_amount"
}
],
"error": null,
"error_type": null,
"external_order_id": {
"ecommerce": "2541635698739"
},
"external_transaction_id": {
"payment_processor": "ch_1HzWElJ2zqHvZRd1TWKFFqDR"
},
"has_uncommitted_changes": false,
"line_items": [
{
"purchase_item_id": 63898947,
"external_product_id": {
"ecommerce": "4381728735283"
},
"external_variant_id": {
"ecommerce": "999999999999"
},
"grams": 454,
"handle": "shirt-package",
"images": {
"large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg",
"medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg",
"original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg",
"small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg"
},
"original_price": "10.00",
"properties": [
{
"name": "Color",
"value": "Blue"
}
],
"purchase_item_type": "subscription",
"quantity": 1,
"sku": "TOM0001",
"tax_due": "1.30",
"tax_lines": [
{
"price": "0.9931",
"rate": "0.0725",
"title": "CA State Tax",
"unit_price": "0.3310"
},
{
"price": "0.3082",
"rate": "0.0225",
"title": "LA County Tax",
"unit_price": "0.1027"
}
],
"taxable": true,
"taxable_amount": "10.00",
"title": "Shirt package",
"total_price": "11.30",
"unit_price": "10.00",
"unit_price_includes_tax": false,
"variant_title": "Blue T-shirt"
}
],
"note": "next order in sequence 3",
"order_attributes": [
{
"name": "Checkout-Method",
"value": "delivery"
}
],
"orders_count": 1,
"payment_processor": "stripe",
"processed_at": "2021-11-09T23:59:31+00:00",
"retry_date": null,
"scheduled_at": "2021-12-09",
"shipping_address": {
"address1": "1030 Barnum Ave",
"address2": "Suite 101",
"city": "Stratford",
"company": "Fake Company",
"country_code": "US",
"first_name": "Fake First",
"last_name": "Fake Last",
"phone": "999-999-9999",
"province": "Connecticut",
"zip": "06614"
},
"shipping_lines": [
{
"code": "Standard",
"price": "4.90",
"source": "shopify",
"taxable": true,
"tax_lines": [
{
"price": "0.355",
"rate": 0.0725,
"title": "CA State Tax"
},
{
"price": "0.110",
"rate": 0.0225,
"title": "Los Angeles County Tax"
}
],
"title": "Standard"
}
],
"status": "success",
"subtotal_price": "10.00",
"tags": "Subscription, Subscription Recurring Order",
"tax_lines": [
{
"price": "0.950",
"rate": 0.0725,
"title": "CA State Tax"
},
{
"price": "0.335",
"rate": 0.0225,
"title": "Los Angeles County Tax"
}
],
"taxable": true,
"total_discounts": "10.0",
"total_line_items_price": "10.00",
"total_price": "11.29",
"total_refunds": "0.00",
"total_tax": "1.29",
"total_weight_grams": 454,
"type": "recurring",
"updated_at": "2021-11-09T23:59:32+00:00"
}
}
Capture a charge
If you are leveraging the authorize/capture workflow with Recharge, the charge/{id}/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 result 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 /charges/{id}/capture_payment
endpoint is available to Recharge Pro merchants in the Recharge Closed Beta group. If you’re interested in leveraging the Recharge 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": 377749210,
"address_id": 42171447,
"analytics_data": {
"utm_params": [
{
"utm_source": "facebook",
"utm_medium": "cpc"
}
]
},
"billing_address": {
"address1": "601 SW Washing St.",
"address2": "Suite 101",
"city": "Portland",
"company": "Acme Corp",
"country_code": "US",
"first_name": "Jane",
"last_name": "Doe",
"phone": "888-888-8888",
"province": "Oregon",
"zip": "97205"
},
"client_details": {
"browser_ip": "192.168.0.1",
"user_agent": "safari webkit"
},
"created_at": "2021-11-09T19:22:13+00:00",
"currency": "USD",
"customer": {
"id": 37657002,
"email": "test@test.com",
"external_customer_id": {
"ecommerce": "2879413682227"
},
"hash": "7e706455cbd13e40"
},
"discounts": [
{
"id": 12345,
"code": "TESTCODE10",
"value": 10,
"value_type": "fixed_amount"
}
],
"error": null,
"error_type": null,
"external_order_id": {
"ecommerce": "2541635698739"
},
"external_transaction_id": {
"payment_processor": "ch_1HzWElJ2zqHvZRd1TWKFFqDR"
},
"has_uncommitted_changes": false,
"line_items": [
{
"purchase_item_id": 63898947,
"external_product_id": {
"ecommerce": "4381728735283"
},
"external_variant_id": {
"ecommerce": "999999999999"
},
"grams": 454,
"handle": "shirt-package",
"images": {
"large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg",
"medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg",
"original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg",
"small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg"
},
"original_price": "10.00",
"properties": [
{
"name": "Color",
"value": "Blue"
}
],
"purchase_item_type": "subscription",
"quantity": 1,
"sku": "TOM0001",
"tax_due": "1.30",
"tax_lines": [
{
"price": "0.9931",
"rate": "0.0725",
"title": "CA State Tax",
"unit_price": "0.3310"
},
{
"price": "0.3082",
"rate": "0.0225",
"title": "LA County Tax",
"unit_price": "0.1027"
}
],
"taxable": true,
"taxable_amount": "10.00",
"title": "Shirt package",
"total_price": "11.30",
"unit_price": "10.00",
"unit_price_includes_tax": false,
"variant_title": "Blue T-shirt"
}
],
"note": "next order in sequence 3",
"order_attributes": [
{
"name": "Checkout-Method",
"value": "delivery"
}
],
"orders_count": 1,
"payment_processor": "stripe",
"processed_at": "2021-11-09T23:59:31+00:00",
"retry_date": null,
"scheduled_at": "2021-12-09",
"shipping_address": {
"address1": "1030 Barnum Ave",
"address2": "Suite 101",
"city": "Stratford",
"company": "Fake Company",
"country_code": "US",
"first_name": "Fake First",
"last_name": "Fake Last",
"phone": "999-999-9999",
"province": "Connecticut",
"zip": "06614"
},
"shipping_lines": [
{
"code": "Standard",
"price": "4.90",
"source": "shopify",
"taxable": true,
"tax_lines": [
{
"price": "0.355",
"rate": 0.0725,
"title": "CA State Tax"
},
{
"price": "0.110",
"rate": 0.0225,
"title": "Los Angeles County Tax"
}
],
"title": "Standard"
}
],
"status": "success",
"subtotal_price": "10.00",
"tags": "Subscription, Subscription Recurring Order",
"tax_lines": [
{
"price": "0.950",
"rate": 0.0725,
"title": "CA State Tax"
},
{
"price": "0.335",
"rate": 0.0225,
"title": "Los Angeles County Tax"
}
],
"taxable": true,
"total_discounts": "10.0",
"total_line_items_price": "10.00",
"total_price": "11.29",
"total_refunds": "0.00",
"total_tax": "1.29",
"total_weight_grams": 454,
"type": "recurring",
"updated_at": "2021-11-09T23:59:32+00:00"
}
}
Checkouts
Checkouts
allow you to create, update, and process a Checkout
programmatically. Shipping cost and sales tax determination are automatic functions of the Recharge Checkout resource.
Related guides: Recharge checkout integrations, How to use the Checkout resource
Important - The Checkout
endpoints are only available for BigCommerce and Custom. Checkouts on Shopify must go through Shopify.
The checkout object
Checkouts
resource allows you to create, update, and process a checkout programmatically. Shipping cost and sales tax determination are automatic functions of the Recharge Checkout resource.
The Checkout
endpoints are only available for BigCommerce and Custom. Checkouts
on Shopify must go through Shopify.
Attributes
- charge_idinteger
ID for the
Charge
resulting from processing theCheckout
. - analytics_dataobject
Urchin Tracking Module (UTM) parameters are used for online marketing campaigns.
Show object attributes - applied_discountsarray
Discount
details, populated once theDiscount
has been applied successfully to theCheckout
.Show object attributes - applied_shipping_rateobject
Shipping rates details, populated once the rates have been selected and applied successfully to the
Checkout
.Show object attributes - available_shipping_ratesarray
Shipping rates available for the shipping address provided in the
Checkout
.Checkout
object must contain theshipping_address
before theavailable_shipping_rates
are populated.Show object attributes - billing_addressobject
Billing
Address
for theCheckout
.Show object attributes - completed_atdatetime
Timestamp for when the
Checkout
was processed. - created_atdatetime
Timestamp for when the
Checkout
was created. - currencystring
Currency of the
Checkout
. - emailstring
Email address for the
Customer
. - external_checkout_idstring
External checkout reference, if one exists.
- external_checkout_sourcestring
External checkout platform, if one exists.
- external_customer_idobject
External customer reference, if one exists.
Show object attributes - external_transaction_idobject
The ID of the associated transaction in a payment processor system (like Stripe).
Show object attributes - line_itemsarray
A list of items included in the
Checkout
quantity
andexternal_variant_id
are required parameters inline_items
.Show object attributes - notestring
Custom note.
- notification_preferencesobject
Notification preferences for the
Customer
.Show object attributes - order_attributesarray
List of name-value pairs for custom attributes.
Show object attributes - payment_processorstring
Name of the payment processor.
- requires_shippingboolean
Whether or not the
Checkout
contains items that require shipping. - shipping_addressobject
Shipping
Address
for theCheckout
.Show object attributes - shipping_linesobject
Details of shipping rate, cost…
Show object attributes - subtotal_pricestring
Value of the
Checkout
minus shipping and tax. - tax_linesarray
Array of
tax_line
objects.Show object attributes - taxableboolean
Whether the
Checkout
contains items that are taxable. - taxes_includedboolean
Whether the tax is included in the price of the items.
- tokenstring
Unique token for the
Checkout
. - total_pricestring
Full price of the
Checkout
including shipping and tax. - total_taxstring
Tax charged on the
Checkout
. - updated_atdatetime
Timestamp for the latest
Checkout
update.
Error related attributes
More Attributes
{
"checkout": {
"charge_id": null,
"analytics_data": {
"utm_params": [
{
"utm_campaign": "spring_sale",
"utm_content": "textlink",
"utm_data_source": "cookie",
"utm_medium": "cpc",
"utm_source": "google",
"utm_term": "mleko",
"utm_timestamp": "2020-03-05T00:00:00+00:00"
}
]
},
"applied_discounts": [
{
"amount": "5.00",
"applicable": true,
"discount_code": "5_DOLLARS_OFF",
"non_redeemable_reason": null,
"value": "5.00",
"value_type": "fixed_amount"
}
],
"applied_shipping_rate": {
"checkout": {
"subtotal_price": null,
"total_price": null,
"total_tax": null
},
"code": "Flat rate (3 - 7 Business Days)",
"delivery_range": null,
"description": null,
"handle": "recharge-Flat%20rate%20%283%20-%207%20Business%20Days%29-7.49",
"name": "Flat rate (3 - 7 Business Days)",
"phone_required": null,
"price": "7.49",
"tax_lines": [],
"title": "Flat rate (3 - 7 Business Days)"
},
"available_shipping_rates": [
{
"checkout": {
"subtotal_price": null,
"total_price": null,
"total_tax": null
},
"code": "Flat rate (3 - 7 Business Days)",
"delivery_range": null,
"description": null,
"handle": "recharge-Flat%20rate%20%283%20-%207%20Business%20Days%29-7.49",
"name": "Flat rate (3 - 7 Business Days)",
"phone_required": null,
"price": "7.49",
"tax_lines": [],
"title": "Flat rate (3 - 7 Business Days)"
},
{
"checkout": {
"subtotal_price": null,
"total_price": null,
"total_tax": null
},
"code": "3 Days (3 Business Days)",
"delivery_range": null,
"description": null,
"handle": "recharge-3%20Days%20%283%20Business%20Days%29-11.75",
"name": "3 Days (3 Business Days)",
"phone_required": null,
"price": "11.75",
"tax_lines": [],
"title": "3 Days (3 Business Days)"
}
],
"billing_address": {
"address1": "6419 Ocean Front Walk",
"address2": "Apt 2",
"city": "Los Angeles",
"company": null,
"country_code": "US",
"first_name": "Novak",
"last_name": "Djokovic",
"phone": "1-800-800-8000",
"province": "California",
"zip": "90293"
},
"completed_at": null,
"created_at": "2021-11-16T00:51:28+00:00",
"currency": "USD",
"email": "somerandomemail@test.com",
"external_checkout_id": "<external_cart_id>",
"external_checkout_source": "custom",
"external_customer_id": {
"ecommerce": null,
"payment_processor": null
},
"external_transaction_id": {
"payment_processor": null
},
"line_items": [
{
"id": 0,
"external_inventory_policy": "decrement_obeying_policy",
"external_product_id": {
"ecommerce": "12345"
},
"external_variant_id": {
"ecommerce": "123456"
},
"handle": "shirt-with-design",
"images": {
"small": "https://veryniceimage.jpg"
},
"properties": [
{
"name": "size",
"value": "xl"
}
],
"purchase_item_type": "onetime",
"quantity": 3,
"recurring_unit_price": "12.00",
"requires_shipping": true,
"sku": null,
"subscription_preferences": {
"charge_delay": null,
"charge_interval_frequency": null,
"charge_on_day_of_month": null,
"charge_on_day_of_week": null,
"number_charges_until_expiration": null,
"shipping_interval_frequency": null,
"shipping_interval_unit_type": null
},
"tax_lines": [],
"taxable": false,
"title": "A Nice Shirt",
"total_price": "36.00",
"unit_price": "12.00",
"variant_title": null,
"weight": 340,
"weight_unit": "g"
}
],
"note": "flash sale",
"notification_preferences": {
"email": {
"promotional": {
"last_opt_in_at": null,
"last_opt_in_source": null,
"last_opt_out_at": null,
"last_opt_out_source": null,
"status": "unspecified"
},
"replenishment": {
"last_opt_in_at": null,
"last_opt_in_source": null,
"last_opt_out_at": null,
"last_opt_out_source": null,
"status": "unspecified"
},
"transactional": {
"last_opt_in_at": null,
"last_opt_in_source": null,
"last_opt_out_at": null,
"last_opt_out_source": null,
"status": "unspecified"
}
},
"sms": {
"promotional": {
"last_opt_in_at": null,
"last_opt_in_source": null,
"last_opt_out_at": null,
"last_opt_out_source": null,
"status": "unspecified"
},
"replenishment": {
"last_opt_in_at": null,
"last_opt_in_source": null,
"last_opt_out_at": null,
"last_opt_out_source": null,
"status": "unspecified"
},
"transactional": {
"last_opt_in_at": null,
"last_opt_in_source": null,
"last_opt_out_at": null,
"last_opt_out_source": null,
"status": "unspecified"
}
}
},
"order_attributes": {
"customer_niceness": "very"
},
"payment_processor": null,
"requires_shipping": true,
"shipping_address": {
"address1": "6419 Ocean Front Walk",
"address2": "Apt 2",
"city": "Los Angeles",
"company": null,
"country_code": "US",
"first_name": "Novak",
"last_name": "Djokovic",
"phone": "1-800-800-8000",
"province": "California",
"zip": "90293"
},
"shipping_lines": [
{
"code": "Flat rate (3 - 7 Business Days)",
"price": "7.49",
"tax_lines": [],
"taxable": false,
"title": "Flat rate (3 - 7 Business Days)"
}
],
"subtotal_price": "31.00",
"tax_lines": [],
"taxable": false,
"taxes_included": false,
"token": "efd5a6b12b984f439ec16ce2a00fb5c3",
"total_price": "31.00",
"total_tax": "0.00",
"updated_at": "2021-11-16T00:51:28+00:00"
}
}
Create a checkout
Create a Checkout
The Checkout
endpoints are only available for BigCommerce and Custom. Checkouts on Shopify must go through Shopify.
Query Parameters
- get_shipping_ratesboolean
If specified as a query parameter, shipping rates will be retrieved and will allow providing applied_shipping_rate upon checkout creation.
More Parameters
Body Parameters
- analytics_dataobject
Urchin Tracking Module (UTM) parameters are used for online marketing campaigns.
Show object attributes - applied_discountsarray
Discount
to apply to theCheckout
.Show object attributes - applied_shipping_rateobject
Shipping rates details, populated once the rates have been selected and applied successfully to the
Checkout
.Important: You can only create a checkout with
applied_shipping_rate
if you pass the query parameterget_shipping_rates=true
or if you supply a list of shipping rates usingcustom_shipping_rate_options
.Show object attributes - custom_shipping_rate_optionsarray
List of available shipping rates to use when selecting a shipping rate with
applied_shipping_rate
. Custom shipping rates will take precedence over any default rates fetched usingget_shipping_rates=true
.Show object attributes - billing_addressobject
Billing
Address
for theCheckout
.Show object attributes - currencystring
Currency of the
Checkout
. - emailstring
Email address for the
Customer
. - external_checkout_idstring
External checkout reference, if one exists.
- external_checkout_sourcestring
External checkout platform, if one exists.
- external_transaction_idobject
The ID of the associated transaction in a payment processor system (like Stripe).
Show object attributes - line_itemsarray* Required