API Reference

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

Related guides: Generate API tokens, Using the API



API and Platforms compatibility

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


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

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



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

Authentication

Recharge uses API keys to authenticate requests.

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

X-Recharge-Access-Token:store_api_token

Replace store_api_token with your API key.

All requests must be made over HTTPS.


API Token Scopes

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

The API currently supports the scopes below:

Write Read
read_accounts
write_batches read_batches
write_charges read_charges
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
GET /
curl -i -H 'X-Recharge-Access-Token: your_api_token'
-X GET

Versioning

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

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

Responses

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

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

Extending responses

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

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

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

Resource Endpoints Webhook topics Supported include values Supported included_objects values
Addresses GET /addresses
GET /addresses/:id		 address/created
address/updated		 customer
discount
payment_methods (beta)
subscriptions		 customer
metafields
Charges GET /charges
GET /charges/:id		 charge/created
charge/failed
charge/max_retries_reached
charge/paid
charge/refunded
charge/uncaptured
charge/upcoming
charge/updated		 metafields metafields
Customers GET /customers
GET /customers/:id		 customer/activated
customer/created
customer/deactivated
customer/payment_method_updated
customer/updated		 addresses
metafields
payment_methods (beta)
subscriptions		 addresses
metafields
Orders GET /orders
GET /orders/:id		 order/cancelled
order/created
order/deleted
order/processed
order/upcoming
order/updated		 customer
metafields		 customer
metafields
Products GET /products
GET /products/:id		 product/created
product/deleted
product/updated		 collections
metafields		 collections
metafields
Subscriptions GET /subscriptions
GET /subscriptions/:id		 subscription/activated
subscription/cancelled
subscription/created
subscription/deleted
subscription/skipped
subscription/updated
subscription/unskipped
subscription/paused		 address
metafields		 metafields

Page Based Pagination

By default API calls will return 50 results. By using the limit parameter that can be increased to 250 results.

When there are more results than can fit on a page you may loop through the results by using the page parameter.

To request a page, include page as a parameter in the url.

E.g. https://api.rechargeapps.com/subscriptions?limit=250&page=1

The example to the right shows a loop through all Subscription by page.

With minor changes this example can be used for looping through any object type: Customers, Addresses etc.


NOTE:
Page based pagination deep into large data sets is not recommended due to performance degradation. To paginate deeper into a data set, we recommend exploring cursor pagination instead.
Example Request
# request the first page (page=1)
curl -i -H 'X-Recharge-Access-Token: your_api_token'
 -X GET https://api.rechargeapps.com/subscriptions?limit=250&page=1
# request next page of results (page=2)
curl -i -H 'X-Recharge-Access-Token: your_api_token'
 -X GET https://api.rechargeapps.com/subscriptions?limit=250&page=2
Example Response
id: 123
id: 456
# ... continues through 250 records
page: 1 result_size: 250

id: 567
id: 678
# ... continues through 250 records
page: 2 result_size: 250

id: 567
id: 678
# ... continues through only 10 records, no further pages needed
page: 3 result_size: 10

Cursor Pagination

By default API calls will return 50 results. By using the limit parameter that can be increased to 250 results. When there are more results than the current limit a cursor may be used to request additional results.

Cursor based pagination is the preferred method for looping through all records in a given data set, as it is more performant than specifying a page number along with number of results. This method also provides more assurance that you will receive all of the records in a given set.

Cursor based pagination works by providing a reference to a specific item in a list of sequential data which will represent the cursor, such as a numeric id. You can then specify whether you would like to query records starting before or starting after that item.

For convenience, the API provides a Link header in all responses for which there are further pages. This header contains both a next_cursor and previous_cursor link, which is just a URL with an encoded page_info parameter that contains any filters from your first call, as well as markers to let the API know where it left off and where to begin for the next call.

Please note that the only compatible filter allowed to be used with cursors is limit.


Supported endpoints for Link
GET /addresses
GET /async_batches
GET /async_batches/:id/tasks
GET /charges
GET /customers
GET /discounts
GET /orders
GET /products
GET /subscriptions

NOTE:
/charges requests which supply either the updated_at_min or created_at_min filter will not currently return a Link header.
Requests which contain a filter for ids, shopify_product_ids will not return a Link header.
Example Request
URL="https://api.rechargeapps.com/charges?limit=5"

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

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

# Display results
echo $content | jq "."

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

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

Sorting

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


Resource Supported sort_by_values
Address Default: id-desc
Options: id-asc id-desc updated_at-asc updated_at-desc
Async Batch Default: id-desc
Options: id-asc id-desc created_at-asc created_at-desc
Charge Default: id-asc
Options: id-asc id-desc created_at-asc created_at-desc updated_at-asc updated_at-desc charge_date-asc charge_date-desc
Customer Default: id-desc
Options: id-asc id-desc created_at-asc created_at-desc updated_at-asc updated_at-desc
Discount Default: id-desc
Options: id-asc id-desc created_at-asc created_at-desc updated_at-asc updated_at-desc
Metafield Default: id-desc
Options:id-asc id-desc updated_at-asc updated_at-desc
Onetime Default: id-desc
Options: id-asc id-desc created_at-asc created_at-desc updated_at-asc updated_at-desc
Order Default: id-desc
Options: id-asc id-desc created_at-asc created_at-desc shipped_date-asc shipped_date-desc shipping_date-asc shipping_date-desc updated_at-asc updated_at-desc
Product Default: id-desc
Options: id-asc id-desc created_at-asc created_at-desc updated_at-asc updated_at-desc title-asc title-desc
Subscription Default: id-desc
Options: id-asc id-desc created_at-asc created_at-desc updated_at-asc updated_at-desc
Webhook Default: id-desc
Options: id-asc id-desc

Addresses

Addresses represents one of the many shipping locations a customer may have. Subscriptions are tied to a given address. Each customer can have multiple address objects (many to one aka n:1) in the relationship.

Endpoints
POST
/customers/{id}/addresses
GET
/addresses/{id}
PUT
/addresses/{id}
DELETE
/addresses/{id}
GET
/addresses
GET
/addresses/count
POST
/addresses/validate
Expand

Charges

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

Endpoints
GET
/charges/{id}
GET
/charges
GET
/charges/count
POST
/charges/{id}/change_next_charge_date
POST
/charges/{id}/skip
POST
/charges/{id}/unskip
POST
/charges/{id}/refund
POST
/charges/{id}/process
POST
/charges/{id}/capture_payment
Expand

Checkouts

Pro plan

BigCommerce

Custom

The checkout resource allows to create unique checkout experiences.
We currently support Stripe, Apple Pay, Google Pay, and Braintree as payment processor.

Related guides: Mobile payments

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

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

The checkout object

BigCommerce

Custom

The checkout resource allows to create unique checkout experiences.
We currently support Stripe, Apple Pay, Google Pay, Braintree, Authorize as payment processor.

The Checkout endpoints are only available for BigCommerce and Custom implementations. Checkouts on Shopify must go through Shopify.
If you are using test stripe keys, you can use tok_visa as your token.

Attributes
  • analytics_data
    object

    Analytics data containing amongst other things the utm_params

    Show object attributes
  • applied_discount
    object

    Details of the discount code applied to the checkout.

    Show object attributes
  • billing_address
    object

    Billing address for the checkout.

    Show object attributes
  • buyer_accepts_marketing
    boolean

    Serves as the audit trail for a buyer email marketing’s communication opt-in

  • charge_id
    integer

    The id associated to the Charge generated as a by-product of a Checkout being processed.

    This value will remain null as long as the Checkout has not been completed.

  • completed_at
    timestamp

    The timestamp at which the Checkout was processed.

    This value will remain null as long as the Checkout has not been completed.

  • created_at
    timestamp

    The timestamp at which the Checkout was created.

  • currency
    string

    The presentment currency of the Checkout.

    This will also be the currency of the resulting Address and Subscriptions created by the checkout processing.

  • discount_code
    string

    Discount code to be used on the checkout, e.g. “DISCOUNT20”.

  • email
    string

    Email address for the customer.

  • external_checkout_id
    string

    Field which will hold the value of the corresponding external checkout or cart if the checkout was branched from another platform.

  • external_checkout_source
    string

    Possible values:   big_commerce,   headless,   shopify

    Source of the creation of the checkout.

  • external_customer_id
    string

    Customer identifier in the source platform issuing the checkout.

    This field is useful for mapping to your customer id in your central CRM, ERP or any other commerce platform where you maintain your customer’s profiles.

  • line_items
    array

    The details of the different items being purchased by the user.

    Show object attributes
  • note
    string

    Note used to store free text notes.

  • note_attributes
    array

    Structured note attributes.

    Show object attributes
  • payment_processor
    string

    Name of the payment processor selected for the checkout.

    Will remain null until payment details have been filled in.

  • payment_processor_customer_id
    string

    Identifier for the customer on the payment processor platform.

    Will remain null until the checkout has been processed.

  • payment_processor_transaction_id
    string

    Identifier for the transaction on the payment processor platform.

    Will remain null until the checkout has been processed.

  • phone
    string

    Customer phone number.

  • requires_shipping
    boolean

    Signals if the Order resulting from the processing of the checkout will need to be shipped aka packed and delivered.

    This relies on whether any of the line_items requires_shipping.

  • shipping_address
    object

    Shipping address for the checkout.

    Show object attributes
  • shipping_address_validations
    object

    Results of the shipping address validation.

    only available once the shipping address has been filled in.

    Show object attributes
  • shipping_line
    array

    Shipping lines.

    Show object attributes
  • shipping_rate
    string

    The name of the shipping rate applied.

  • tax_lines
    array

    Tax details.

    Show object attributes
  • taxes_included
    boolean

    Whether taxes are included in the price of the line_items

  • token
    string

    Unique identifier of the checkout. Used by the update and processing and update endpoints.

  • total_price
    string

    Total amount for the full checkout transaction

  • total_tax
    string

    Total amount of tax for the full checkout transaction

  • updated_at
    timestamp

    The timestamp at which the Checkout was last updated.

The checkout object
{
  "checkout": {
    "analytics_data": {
      "utm_params": [
        {
          "utm_campaign": "spring_sale",
          "utm_content": "textlink",
          "utm_data_source": "shopify_cookie",
          "utm_medium": "cpc",
          "utm_source": "google",
          "utm_term": "mleko",
          "utm_timestamp": "2020-03-05T00:00:00"
        }
      ]
    },
    "applied_discount": {
      "amount": "7.50",
      "applicable": true,
      "non_applicable_reason": "",
      "value": "7.50",
      "value_type": "fixed_amount"
    },
    "billing_address": null,
    "buyer_accepts_marketing": false,
    "charge_id": null,
    "completed_at": null,
    "created_at": "2020-07-10T09:21:46+00:00",
    "currency": "USD",
    "discount_code": "POPUS_25",
    "email": "somerandomemail@test.com",
    "external_checkout_id": "<cart_token>",
    "external_checkout_source": "ecommerce_platform",
    "line_items": [
      {
        "charge_interval_frequency": 5,
        "cutoff_day_of_month": null,
        "cutoff_day_of_week": null,
        "expire_after_specific_number_of_charges": null,
        "first_recurring_charge_delay": null,
        "fulfillment_service": "manual",
        "grams": 1000,
        "image": "//cdn.example.com/s/files/1/0279/8387/2103/products/kazan_small.jpg?v=1586451337",
        "line_price": "30.00",
        "order_day_of_month": null,
        "order_day_of_week": null,
        "order_interval_frequency": 5,
        "order_interval_unit": "day",
        "order_interval_unit_type": "day",
        "original_price": "5.00",
        "price": "5.00",
        "product_id": 4546063663207,
        "product_type": "Milk",
        "properties": null,
        "quantity": 6,
        "recurring_price": "5.00",
        "requires_shipping": true,
        "sku": "kRaViCah-1",
        "tax_code": null,
        "taxable": false,
        "title": "Powder Milk",
        "type": "SUBSCRIPTION",
        "variant_id": 32165284380775,
        "variant_title": "1 / Powder",
        "vendor": "Imlek"
      }
    ],
    "note": null,
    "note_attributes": null,
    "payment_processor": null,
    "payment_processor_customer_id": null,
    "payment_processor_transaction_id": null,
    "phone": null,
    "requires_shipping": true,
    "shipping_address": {
      "address1": "6419 Ocean Front Walk",
      "address2": "Apt 2",
      "city": "Los Angeles",
      "company": "",
      "country": "United States",
      "first_name": "Novak",
      "last_name": "Djokovic",
      "phone": "1-800-800-8000",
      "province": "California",
      "zip": "90293"
    },
    "shipping_address_validations": {
      "country_is_supported": true,
      "ups": true
    },
    "shipping_line": null,
    "shipping_rate": null,
    "subtotal_price": "22.50",
    "tax_lines": [
      {
        "price": "0.950",
        "rate": 0.0725,
        "title": "CA State Tax"
      },
      {
        "price": "0.335",
        "rate": 0.0225,
        "title": "Los Angeles  County Tax"
      }
    ],
    "taxes_included": false,
    "token": "b706eecfd66c45329d3886a02d7515d6",
    "total_price": "22.50",
    "total_tax": "0.00",
    "updated_at": "2020-07-10T09:21:46+00:00"
  }
}

Create a checkout

BigCommerce

Custom

Endpoint to create a checkout object and start populating it.

Related guides: Checkout integrations

The Checkout endpoints are only available for BigCommerce and Custom. Checkouts on Shopify must go through Shopify.
The token field received on checkout POST response is the unique identifier for the Checkout. Use it to make updates to the Checkout.

Scopes: write_checkouts
Body Parameters
  • analytics_data
    object

    Analytics data containing amongst other things the utm_params.

    analytics_data will be added to Subscription, Customer and Charge objects created as a result of the successful processing of the Checkout.

    Show object attributes
  • billing_address
    object

    Billing address for the checkout.

    Show object attributes
  • buyer_accepts_marketing
    boolean

    Serves as the audit trail for a buyer email marketing’s communication opt-in

  • currency
    string

    The presentment currency of the Checkout.

    Only currencies set up in the store setting store_presentment_currencies are accepted. This will also be the currency of the resulting Address and Subscriptions created by the checkout processing.

  • discount_code
    string

    Discount code to be used on the checkout, e.g. “DISCOUNT20”.

  • email
    string

    Email address for the customer.

    will be required before being able to process a Checkout.

  • external_checkout_id
    string

    Cart token from ecommerce platform.

  • external_checkout_source
    string

    Possible values:   big_commerce,   headless,   shopify

    Ecommerce platform hosting the cart.

  • external_checkout_customer_id
    string

    Ecommerce platform hosting the cart.

  • line_items
    array
    * Required

    The details of the different items being purchased by the user.

    will be required before being able to process a Checkout.

    Show object attributes
  • note
    string

    Note used to store free text notes.

  • note_attributes
    array

    Structured note attributes.

    Show object attributes
  • phone
    string

    Customer phone number.

  • shipping_address
    object

    Shipping address for the checkout.

    will be required before being able to process a Checkout.

    Show object attributes
Responses
  • 200

    Success

    Show response object
  • 422

    Unprocessable

    Show response object
POST
/checkouts 
curl 'https://api.rechargeapps.com/checkouts' \ 
 -H 'Content-Type: application/json' \ 
 -H 'X-Recharge-Access-Token: your_api_token' \ 
 -d '{
  "analytics_data": {
    "utm_params": [{
      "utm_campaign": "spring_sale",
      "utm_content": "textlink",
      "utm_data_source": "website_cookie",
      "utm_medium": "cpc",
      "utm_source": "google",
      "utm_term": "mleko",
      "utm_timestamp": "2020-03-05"
    }]
  },
  "discount_code": "POPUS_25",
  "email":"somerandomemail@test.com",
  "external_checkout_id": "<cart_token>",
  "external_checkout_source": "custom",
  "line_items": [
    {
      "charge_interval_frequency": 5,
      "cutoff_day_of_month": None,
      "cutoff_day_of_week": None,
      "expire_after_specific_number_of_charges": None,
      "fulfillment_service": "manual",
      "order_day_of_month": None,
      "order_day_of_week": None,
      "order_interval_frequency": 5,
      "order_interval_unit": "day",
      "product_id": 4546063663207,
      "quantity": 6,
      "requires_shipping": True,
      "taxable": True,
      "variant_id": 32165284380775
    }
  ],
  "shipping_address": {
    "address1": "6419 Ocean Front Walk",
    "address2": "Apt 2",
    "city": "Los Angeles",
    "company": "",
    "country": "United States",
    "first_name": "Novak",
    "last_name": "Djokovic",
    "phone": "1-800-800-8000",
    "province": "California",
    "zip": "90293"
  }
}'
Response 
{
  "checkout": {
    "analytics_data": {
      "utm_params": [
        {
          "utm_campaign": "spring_sale",
          "utm_content": "textlink",
          "utm_data_source": "website_cookie",
          "utm_medium": "cpc",
          "utm_source": "google",
          "utm_term": "mleko",
          "utm_timestamp": "2020-03-05T00:00:00"
        }
      ]
    },
    "applied_discount": {
      "amount": "7.50",
      "applicable": true,
      "non_applicable_reason": "",
      "value": "7.50",
      "value_type": "fixed_amount"
    },
    "billing_address": {
      "address1": "6419 Ocean Front Walk",
      "address2": "Apt 2",
      "city": "Los Angeles",
      "company": "",
      "country": "United States",
      "first_name": "Novak",
      "last_name": "Djokovic",
      "phone": "1-800-800-8000",
      "province": "California",
      "zip": "90293"
    },
    "buyer_accepts_marketing": false,
    "charge_id": null,
    "completed_at": null,
    "created_at": "2020-07-10T09:21:46.259352+00:00",
    "currency": "USD",
    "discount_code": "POPUS_25",
    "email": "somerandomemail@test.com",
    "external_checkout_id": "<cart_token>",
    "external_checkout_source": "custom",
    "external_customer_id": "someone",
    "line_items": [
      {
        "charge_interval_frequency": 5,
        "cutoff_day_of_month": null,
        "cutoff_day_of_week": null,
        "expire_after_specific_number_of_charges": null,
        "first_recurring_charge_delay": null,
        "fulfillment_service": "manual",
        "grams": 1000,
        "handle": null,
        "image": "//cdn.example.com/s/files/1/0279/8387/2103/products/kazan_small.jpg?v=1586451337",
        "line_price": "30.00",
        "order_day_of_month": null,
        "order_day_of_week": null,
        "order_interval_frequency": 5,
        "order_interval_unit": "day",
        "order_interval_unit_type": "day",
        "original_price": "5.00",
        "price": "5.00",
        "product_id": 4546063663207,
        "product_type": "Milk",
        "properties": null,
        "quantity": 6,
        "recurring_price": "5.00",
        "requires_shipping": true,
        "sku": "kRaViCah-1",
        "tax_code": null,
        "taxable": false,
        "title": "Powder Milk",
        "type": "SUBSCRIPTION",
        "variant_id": 32165284380775,
        "variant_title": "1 / Powder",
        "vendor": "Imlek"
      }
    ],
    "note": null,
    "note_attributes": null,
    "payment_processor": null,
    "payment_processor_customer_id": null,
    "payment_processor_transaction_id": null,
    "phone": null,
    "requires_shipping": true,
    "shipping_address": {
      "address1": "6419 Ocean Front Walk",
      "address2": "Apt 2",
      "city": "Los Angeles",
      "company": "",
      "country": "United States",
      "first_name": "Novak",
      "last_name": "Djokovic",
      "phone": "1-800-800-8000",
      "province": "California",
      "zip": "90293"
    },
    "shipping_address_validations": {
      "country_is_supported": true,
      "ups": true
    },
    "shipping_line": null,
    "shipping_rate": null,
    "subtotal_price": "22.50",
    "tax_lines": [
      {
        "price": "0.950",
        "rate": 0.0725,
        "title": "CA State Tax"
      },
      {
        "price": "0.335",
        "rate": 0.0225,
        "title": "Los Angeles  County Tax"
      }
    ],
    "taxes_included": false,
    "token": "b706eecfd66c45329d3886a02d7515d6",
    "total_price": "22.50",
    "total_tax": "1.28",
    "updated_at": "2020-07-10T09:21:46.284703+00:00"
  }
}

Retrieve a checkout

BigCommerce

Custom

Retrieve a checkout

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

Scopes: read_checkouts
Responses
  • 200

    Success

    Show response object
GET
/checkouts/{token} 
curl 'https://api.rechargeapps.com/checkouts/6a7c36a1213a4d7fb746e6588fa55005' \ 
 -H 'X-Recharge-Access-Token: your_api_token'
Response 
{
  "checkout": {
    "analytics_data": {
      "utm_params": [
        {
          "utm_campaign": "spring_sale",
          "utm_content": "textlink",
          "utm_data_source": "website_cookie",
          "utm_medium": "cpc",
          "utm_source": "google",
          "utm_term": "mleko",
          "utm_timestamp": "2020-03-05T00:00:00"
        }
      ]
    },
    "applied_discount": {
      "amount": "7.50",
      "applicable": true,
      "non_applicable_reason": "",
      "value": "7.50",
      "value_type": "fixed_amount"
    },
    "billing_address": null,
    "buyer_accepts_marketing": false,
    "charge_id": null,
    "completed_at": null,
    "created_at": "2020-07-10T09:21:46.259352+00:00",
    "currency": "USD",
    "discount_code": "POPUS_25",
    "email": "somerandomemail@test.com",
    "external_checkout_id": "<cart_token>",
    "external_checkout_source": "headless",
    "line_items": [
      {
        "charge_interval_frequency": 5,
        "cutoff_day_of_month": null,
        "cutoff_day_of_week": null,
        "expire_after_specific_number_of_charges": null,
        "first_recurring_charge_delay": null,
        "fulfillment_service": "manual",
        "grams": 1000,
        "image": "//cdn.example.com/s/files/1/0279/8387/2103/products/kazan_small.jpg?v=1586451337",
        "line_price": "30.00",
        "order_day_of_month": null,
        "order_day_of_week": null,
        "order_interval_frequency": 5,
        "order_interval_unit": "day",
        "order_interval_unit_type": "day",
        "original_price": "5.00",
        "price": "5.00",
        "product_id": 4546063663207,
        "product_type": "Milk",
        "properties": null,
        "quantity": 6,
        "recurring_price": "5.00",
        "requires_shipping": true,
        "sku": "kRaViCah-1",
        "tax_code": null,
        "taxable": false,
        "title": "Powder Milk",
        "type": "SUBSCRIPTION",
        "variant_id": 32165284380775,
        "variant_title": "1 / Powder",
        "vendor": "Imlek"
      }
    ],
    "note": null,
    "note_attributes": null,
    "payment_processor": null,
    "payment_processor_customer_id": null,
    "payment_processor_transaction_id": null,
    "phone": null,
    "requires_shipping": true,
    "shipping_address": {
      "address1": "6419 Ocean Front Walk",
      "address2": "Apt 2",
      "city": "Los Angeles",
      "company": "",
      "country": "United States",
      "first_name": "Novak",
      "last_name": "Djokovic",
      "phone": "1-800-800-8000",
      "province": "California",
      "zip": "90293"
    },
    "shipping_address_validations": {
      "country_is_supported": true,
      "ups": true
    },
    "shipping_line": null,
    "shipping_rate": null,
    "subtotal_price": "22.50",
    "tax_lines": [
      {
        "price": "0.950",
        "rate": 0.0725,
        "title": "CA State Tax"
      },
      {
        "price": "0.335",
        "rate": 0.0225,
        "title": "Los Angeles  County Tax"
      }
    ],
    "taxes_included": false,
    "token": "b706eecfd66c45329d3886a02d7515d6",
    "total_price": "22.50",
    "total_tax": "0.00",
    "updated_at": "2020-07-10T09:21:46.284703+00:00"
  }
}

Update a checkout

BigCommerce

Custom

You can modify an existing checkout to match the specified parameters.

Related guides: Checkout integrations

The Checkout endpoints are only available for BigCommerce and Custom. Checkouts on Shopify must go through Shopify.
If you are using test stripe keys, you can use tok_visa as your token.

Scopes: write_checkouts
Body Parameters
  • analytics_data
    object

    Analytics data containing amongst other things the utm_params.

    analytics_data will be added to Subscription, Customer and Charge objects created as a result of the successful processing of the Checkout.

    Show object attributes
  • billing_address
    object

    Billing address for the checkout.

    Show object attributes
  • buyer_accepts_marketing
    boolean

    Does the buyer accept marketing, newsletters etc.

  • currency
    string

    The presentment currency of the Checkout.

    Only currencies set up in the store setting store_presentment_currencies are accepted. This will also be the currency of the resulting Address and Subscriptions created by the checkout processing.

  • discount_code
    string

    Discount code to be used on the checkout, e.g. “DISCOUNT20”.

  • email
    string

    Email address for the customer.

  • external_checkout_id
    string

    Cart token from ecommerce platform.

  • external_checkout_source
    string

    Possible values:   big_commerce,   headless,   shopify

    Ecommerce platform hosting the cart.

  • external_checkout_customer_id
    string

    Ecommerce platform hosting the cart.

  • line_items
    array

    quantity, product_id and variant_id are required parameters in line_items.

    Show object attributes
  • note
    string

    Note attribute used to store custom notes.

  • note_attributes
    array

    Each array entry must contain a dictionary with “name” and “value” keys.

    Show object attributes
  • partial_shipping
    boolean

    When set to true, shipping address validations are reduced to only require country and zip when creating/updating a checkout. The full shipping address including address line 1 must be added to the checkout before processing associated charges. This is helpful for mobile payments.

    Related guides: Mobile payments

  • phone
    string

    Customer phone number.

  • shipping_address
    object

    Shipping address for the checkout.

    When using mobile payment options, insufficient shipping address data is available until payment intent, which causes validation errors when updating the checkout object.

    Related guides: Checkout mobile payment

    Show object attributes
Responses
  • 200

    Success

    Show response object
PUT
/checkouts/{token} 
curl -X PUT 'https://api.rechargeapps.com/checkouts/98ac7af0c9d447019379c6ccdb24d069' \ 
 -H 'Content-Type: application/json' \ 
 -H 'X-Recharge-Access-Token: your_api_token' \ 
 -d '{
  "line_items": [
    {
      "product_id": 4546063663207,
      "quantity": 6,
      "variant_id": 3844924611
    }
  ]
}'
Response 
{
  "checkout": {
    "analytics_data": {
      "utm_params": [
        {
          "utm_campaign": "spring_sale",
          "utm_content": "textlink",
          "utm_data_source": "website_cookie",
          "utm_medium": "cpc",
          "utm_source": "google",
          "utm_term": "mleko",
          "utm_timestamp": "2020-03-05T00:00:00"
        }
      ]
    },
    "applied_discount": {
      "amount": "7.50",
      "applicable": true,
      "non_applicable_reason": "",
      "value": "7.50",
      "value_type": "fixed_amount"
    },
    "billing_address": null,
    "buyer_accepts_marketing": false,
    "charge_id": null,
    "completed_at": null,
    "created_at": "2020-07-10T09:21:46.259352+00:00",
    "currency": "USD",
    "discount_code": "POPUS_25",
    "email": "somerandomemail@test.com",
    "external_checkout_id": "<cart_token>",
    "external_checkout_source": "headless",
    "line_items": [
      {
        "charge_interval_frequency": 5,
        "cutoff_day_of_month": null,
        "cutoff_day_of_week": null,
        "expire_after_specific_number_of_charges": null,
        "first_recurring_charge_delay": null,
        "fulfillment_service": "manual",
        "grams": 1000,
        "image": "//cdn.example.com/s/files/1/0279/8387/2103/products/kazan_small.jpg?v=1586451337",
        "line_price": "30.00",
        "order_day_of_month": null,
        "order_day_of_week": null,
        "order_interval_frequency": 5,
        "order_interval_unit": "day",
        "order_interval_unit_type": "day",
        "original_price": "5.00",
        "price": "5.00",
        "product_id": 4546063663207,
        "product_type": "Milk",
        "properties": null,
        "quantity": 6,
        "recurring_price": "5.00",
        "requires_shipping": true,
        "sku": "kRaViCah-1",
        "tax_code": null,
        "taxable": false,
        "title": "Powder Milk",
        "type": "SUBSCRIPTION",
        "variant_id": 32165284380775,
        "variant_title": "1 / Powder",
        "vendor": "Imlek"
      }
    ],
    "note": null,
    "note_attributes": null,
    "payment_processor": null,
    "payment_processor_customer_id": null,
    "payment_processor_transaction_id": null,
    "phone": null,
    "requires_shipping": true,
    "shipping_address": {
      "address1": "6419 Ocean Front Walk",
      "address2": "Apt 2",
      "city": "Los Angeles",
      "company": "",
      "country": "United States",
      "first_name": "Novak",
      "last_name": "Djokovic",
      "phone": "1-800-800-8000",
      "province": "California",
      "zip": "90293"
    },
    "shipping_address_validations": {
      "country_is_supported": true,
      "ups": true
    },
    "shipping_line": null,
    "shipping_rate": null,
    "subtotal_price": "22.50",
    "tax_lines": [
      {
        "price": "0.950",
        "rate": 0.0725,
        "title": "CA State Tax"
      },
      {
        "price": "0.335",
        "rate": 0.0225,
        "title": "Los Angeles  County Tax"
      }
    ],
    "taxes_included": false,
    "token": "b706eecfd66c45329d3886a02d7515d6",
    "total_price": "22.50",
    "total_tax": "0.00",
    "updated_at": "2020-07-10T09:21:46.284703+00:00"
  }
}

Retrieve shipping rates

BigCommerce

Custom

Retrieve all shipping rates for a specific checkout.

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

Scopes: read_checkouts
Responses
  • 200

    success

    Show response object
GET
/checkouts/{token}/shipping_rates 
curl 'https://api.rechargeapps.com/checkouts/6a7c36a1213a4d7fb746e6588fa55005/shipping_rates' \ 
 -H 'X-Recharge-Access-Token: your_api_token'
Response 
{
  "shipping_rates": [
    {
      "checkout": {
        "subtotal_price": "22.50",
        "total_price": "42.40",
        "total_tax": "0.00"
      },
      "code": "Standard",
      "delivery_range": null,
      "description": null,
      "handle": "shopify-Standard-19.90",
      "name": "Standard",
      "phone_required": false,
      "price": "19.90",
      "tax_lines": [],
      "title": "Standard"
    }
  ]
}

Process a checkout

BigCommerce

Custom

You can process and charge checkout using our API.

The Checkout endpoints are only available for BigCommerce and Custom. Checkouts on Shopify must go through Shopify.
The Checkout API supports Stripe, Apple Pay, Google Pay, and Braintree as payment processor.

If you are using test stripe keys, you can use tok_visa as your token. For checkouts using Mobile Payments, see Mobile Payments with Checkout API

Scopes: write_checkouts
Body Parameters
  • payment_processor
    string
    * Required

    Possible values:   stripe,   braintree,   mollie,   authorize

    The name of payment processor.

  • payment_token
    string
    * Required

    Payment token that will be used in transaction.

    For stripe this field needs to be populated with a payment method.
    For braintree this field needs to be populated with a payment nonce.
    For mollie this field needs to be populated with a mandate.

  • payment_type
    string

    Possible values:   CREDIT_CARD,   PAYPAL,   APPLE_PAY,   GOOGLE_PAY

    It identifies the payment type.

Responses
  • 200

    Success

    Show response object
  • 422

    Unprocessable

    Show response object
POST
/checkouts/{token}/charge 
curl 'https://api.rechargeapps.com/checkouts/5a5c19ea31c44641855017f1276db959/charge' \ 
 -H 'Content-Type: application/json' \ 
 -H 'X-Recharge-Access-Token: your_api_token' \ 
 -d '{
  "payment_processor": "stripe",
  "payment_token": "<payment_token>",
  "payment_type": "CREDIT_CARD"
}'
Response 
{
  "checkout_charge": {
    "authorization_token": null,
    "charge_id": 258065996,
    "free": false,
    "payment_processor": "stripe",
    "payment_processor_customer_id": "cus_HcbgqiS49fABBg62E",
    "payment_processor_transaction_id": "ch_1H3McXJ2zdqHvZaRd191xV2idRt",
    "payment_token": "tok_visa",
    "payment_type": "CREDIT_CARD",
    "status": "successful"
  }
}

Customers

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

Endpoints
POST
/customers
GET
/customers/{id}
PUT
/customers/{id}
DELETE
/customers/{id}
GET
/customers
GET
/customers/count
GET
/customers/{id}/payment_sources
Expand