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
write_notifications
write_orders read_orders
write_payment_methods read_payment_methods
write_products read_products
write_subscriptions read_subscriptions
write_webhooks read_webhooks
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 serparated 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 and included_objects values
Addresses GET /addresses
GET /addresses/{id}
address/created
address/updated
customer
payment_methods(beta)
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
customer
metafields
payment_methods (beta)
Customers GET /customers
GET /customers/{id}
customer/activated
customer/created
customer/deactivated
customer/payment_method_updated
customer/updated
customer/deleted
addresses
metafields
payment_methods (beta)
Orders order/cancelled
order/created
order/deleted
order/processed
order/payment_captured
order/upcoming
order/updated
order/success
GET /orders
GET /orders/{id}
customer
metafields
Payment Methods GET /payment_methods
GET /payment_methods/{id}
addresses
Subscriptions GET /subscriptions
GET /subscriptions/{id}
subscription/activated
subscription/cancelled
subscription/created
subscription/deleted
subscription/skipped
subscription/updated
subscription/unskipped
customer
metafields

Cursor Pagination

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

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

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

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

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


Retrieving total number of records

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

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

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

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

# Display results
echo $content | jq "."

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

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

Sorting

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


Resource Supported sort_by_values
Address Default: id-desc
Options: id-asc id-desc updated_at-asc updated_at-desc
Async Batch Default: id-desc
Options: id-asc id-desc created_at-asc created_at-desc
Charge Default: id-asc
Options: id-asc id-desc created_at-asc created_at-desc updated_at-asc updated_at-desc 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 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
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

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

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

Charges

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

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

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.

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

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_id
    integer

    ID for the Charge resulting from processing the Checkout.

  • analytics_data
    object

    Urchin Tracking Module (UTM) parameters are used for online marketing campaigns.

  • applied_discounts
    array

    Discount details, populated once the Discount has been applied successfully to the Checkout.

  • applied_shipping_rate
    object

    Shipping rates details, populated once the rates have been selected and applied successfully to the Checkout.

  • available_shipping_rates
    array

    Shipping rates available for the shipping address provided in the Checkout.

    Checkout object must contain the shipping_address before the available_shipping_rates are populated.

  • billing_address
    object

    Billing Address for the Checkout.

  • completed_at
    datetime

    Timestamp for when the Checkout was processed.

  • created_at
    datetime

    Timestamp for when the Checkout was created.

  • currency
    string

    Currency of the Checkout.

  • email
    string

    Email address for the Customer.

  • external_checkout_id
    string

    External checkout reference, if one exists.

  • external_checkout_source
    string

    External checkout platform, if one exists.

  • external_customer_id
    object

    External customer reference, if one exists.

  • external_transaction_id
    object

    The ID of the associated transaction in a payment processor system (like Stripe).

  • line_items
    array

    A list of items included in the Checkout

    quantity and external_variant_id are required parameters in line_items.

  • note
    string

    Custom note.

  • notification_preferences
    object

    Notification preferences for the Customer.

  • order_attributes
    array

    List of name-value pairs for custom attributes.

  • payment_processor
    string

    Name of the payment processor.

  • requires_shipping
    boolean

    Whether or not the Checkout contains items that require shipping.

  • shipping_address
    object

    Shipping Address for the Checkout.

  • shipping_lines
    object

    Details of shipping rate, cost…

  • subtotal_price
    string

    Value of the Checkout minus shipping and tax.

  • tax_lines
    array

    Array of tax_line objects.

  • taxable
    boolean

    Whether the Checkout contains items that are taxable.

  • taxes_included
    boolean

    Whether the tax is included in the price of the items.

  • token
    string

    Unique token for the Checkout.

  • total_price
    string

    Full price of the Checkout including shipping and tax.

  • total_tax
    string

    Tax charged on the Checkout.

  • updated_at
    datetime

    Timestamp for the latest Checkout update.

The checkout object
{
  "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"
        }
      ]
    },
    "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,
        "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": {
      "color": "fuschia",
      "size": "xl"
    },
    "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.

Scopes: write_checkouts
Query Parameters
  • get_shipping_rates
    boolean

    If specified as a query parameter, shipping rates will be retrieved and will allow providing applied_shipping_rate upon checkout creation.

Body Parameters
  • analytics_data
    object

    Urchin Tracking Module (UTM) parameters are used for online marketing campaigns.

  • applied_discounts
    array

    Discount to apply to the Checkout.

  • applied_shipping_rate
    object

    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 parameter get_shipping_rates=true or if you supply a list of shipping rates using custom_shipping_rate_options.

  • custom_shipping_rate_options
    array

    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 using get_shipping_rates=true.

  • billing_address
    object

    Billing Address for the Checkout.

  • currency
    string

    Currency of the Checkout.

  • email
    string

    Email address for the Customer.

  • external_checkout_id
    string

    External checkout reference, if one exists.

  • external_checkout_source
    string

    External checkout platform, if one exists.

  • external_transaction_id
    object

    The ID of the associated transaction in a payment processor system (like Stripe).

  • line_items
    array
    * Required

    A list of items included in the Checkout

    quantity and external_variant_id are required parameters in line_items.

  • note
    string

    Custom note.

  • order_attributes
    array

    List of name-value pairs for custom attributes.

  • shipping_address
    object

    Shipping Address for the Checkout.

Responses
  • 200

    successful response

POST
/checkouts
curl 'https://api.rechargeapps.com/checkouts' \ 
 -H 'Content-Type: application/json' \ 
 -H 'X-Recharge-Access-Token: your_api_token' \ 
 -H 'X-Recharge-Version: 2021-11' \ 
 -d '{
  "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_discounts": [
    {
      "discount_code": "5_DOLLARS_OFF"
    }
  ],
  "billing_address": {
    "address1": "6419 Ocean Front Walk",
    "address2": "Apt 2",
    "city": "Los Angeles",
    "company": "",
    "country_code": "US",
    "first_name": "Novak",
    "last_name": "Djokovic",
    "phone": "1-800-800-8000",
    "province": "California",
    "zip": "90293"
  },
  "email": "somerandomemail@test.com",
  "external_checkout_id": "<external_cart_id>",
  "external_checkout_source": "custom",
  "line_items": [
    {
      "external_product_id": {
        "ecommerce": "12345"
      },
      "external_variant_id": {
        "ecommerce": "123456"
      },
      "handle": "shirt-with-design",
      "images": {
        "small": "http://small.jpg"
      },
      "properties": [
        {
          "name": "size",
          "value": "xl"
        },
        {
          "name": "color",
          "value": "fuschia"
        }
      ],
      "quantity": 3,
      "tax_lines": [
        {
          "price": "0.950",
          "rate": 0.0725,
          "title": "CA State Tax"
        }
      ]
    }
  ],
  "note": "flash sale",
  "order_attributes": {
    "size": "xl",
    "color": "fuschia"
  },
  "shipping_address": {
    "address1": "6419 Ocean Front Walk",
    "address2": "Apt 2",
    "city": "Los Angeles",
    "company": "",
    "country_code": "US",
    "first_name": "Novak",
    "last_name": "Djokovic",
    "phone": "1-800-800-8000",
    "province": "California",
    "zip": "90293"
  }
}'
Response
{
  "checkout": {
    "charge_id": null,
    "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_discounts": [
      {
        "amount": "5.00",
        "applicable": true,
        "discount_code": "5_DOLLARS_OFF",
        "non_redeemable_reason": null,
        "value": "5.00",
        "value_type": "fixed_amount"
      }
    ],
    "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": "f71848585658686-36f6-d9efg8125rogkfdaa",
    "external_checkout_source": "custom",
    "external_customer_id": {
      "ecommerce": null,
      "payment_processor": null
    },
    "external_transaction_id": {
      "payment_processor": null
    },
    "line_items": [
      {
        "id": null,
        "external_inventory_policy": "decrement_obeying_policy",
        "external_product_id": {
          "ecommerce": "12345"
        },
        "external_variant_id": {
          "ecommerce": "123456"
        },
        "handle": "shirt-with-design",
        "images": {
          "small": "http://small.jpg"
        },
        "properties": [
          {
            "charge_delay": null,
            "charge_interval_frequency": null,
            "charge_on_day_of_month": null,
            "charge_on_day_of_week": null,
            "name": "size",
            "number_charges_until_expiration": null,
            "shipping_interval_frequency": null,
            "shipping_interval_unit_type": null,
            "value": "xl"
          }
        ],
        "purchase_item_type": "onetime",
        "quantity": 3,
        "requires_shipping": true,
        "sku": null,
        "subscription_preferences": {
          "charge_interval_frequency": null,
          "cutoff_day_of_month": null,
          "cutoff_day_of_week": null,
          "expire_after_specific_number_of_charges": null,
          "interval_unit": null,
          "order_day_of_month": null,
          "order_day_of_week": null,
          "order_interval_frequency": null
        },
        "tax_lines": [],
        "taxable": false,
        "title": "A Very 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": {
      "color": "fuschia",
      "size": "xl"
    },
    "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"
    },
    "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"
  }
}

Retrieve a checkout

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

    successful response

GET
/checkouts/{token}
curl 'https://api.rechargeapps.com/checkouts/6a7c36a1213a4d7fb746e6588fa55005' \ 
 -H 'X-Recharge-Access-Token: your_api_token' \ 
 -H 'X-Recharge-Version: 2021-11'
Response
{
  "checkout": {
    "charge_id": null,
    "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_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": "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)"
    },
    "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": "headless",
    "external_customer_id": {
      "ecommerce": null,
      "payment_processor": null
    },
    "external_transaction_id": {
      "payment_processor": null
    },
    "line_items": [
      {
        "id": null,
        "external_inventory_policy": "decrement_obeying_policy",
        "external_product_id": {
          "ecommerce": "12345"
        },
        "external_variant_id": {
          "ecommerce": "123456"
        },
        "handle": "shirt-with-design",
        "images": {
          "small": "http://small.jpg"
        },
        "properties": [
          {
            "name": "size",
            "value": "xl"
          }
        ],
        "purchase_item_type": "onetime",
        "quantity": 3,
        "requires_shipping": true,
        "sku": null,
        "subscription_preferences": {
          "charge_interval_frequency": null,
          "cutoff_day_of_month": null,
          "cutoff_day_of_week": null,
          "expire_after_specific_number_of_charges": null,
          "interval_unit": null,
          "order_day_of_month": null,
          "order_day_of_week": null,
          "order_interval_frequency": null
        },
        "tax_lines": [],
        "taxable": false,
        "title": "A Very 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": {
      "color": "fuschia",
      "size": "xl"
    },
    "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"
    },
    "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"
  }
}

Update a checkout

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

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

Scopes: write_checkouts
Query Parameters
  • get_shipping_rates
    boolean

    If specified as a query parameter, shipping rates will be retrieved and will allow providing applied_shipping_rate upon checkout update.

Body Parameters
  • analytics_data
    array

    Urchin Tracking Module (UTM) parameters are used for online marketing campaigns.

  • applied_shipping_rate
    object

    Shipping rates details, populated once the rates have been selected and applied successfully to the Checkout.

    Important: You can only set applied_shipping_rate if you have already collected the available_shipping_rates by calling GET /checkout/<checkout_token>/shipping_rates or if you pass the query parameter get_shipping_rates=true when calling this route.

  • billing_address
    object

    Billing address for the checkout.

  • buyer_accepts_marketing
    boolean

    Does the buyer accept marketing, newsletters etc.

  • discount_code
    string

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

  • currency
    string

    Currency of the Checkout.

  • email
    string

    Email address for the customer.

  • external_checkout_id
    string

    Represents the external cart token.

  • external_checkout_source
    string

    Represents the source for external_checkout_id.

  • line_items
    array

    quantity, product_id and variant_id are required parameters in line_items.

  • note
    string

    Note attribute used to store custom notes.

  • order_attributes
    array

    Structured custom notes.

  • 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

  • shipping_line
    array

    Shipping lines.

Responses
  • 200

    successful response

PUT
/checkouts/{token}
curl -X PUT 'https://api.rechargeapps.com/checkouts/b706eecfd66c45329d3886a02d7515d6' \ 
 -H 'Content-Type: application/json' \ 
 -H 'X-Recharge-Access-Token: your_api_token' \ 
 -H 'X-Recharge-Version: 2021-11' \ 
 -d '{
  "line_items": [
    {
      "product_id": 4546063663207,
      "quantity": 6,
      "variant_id": 3844924611
    }
  ]
}'