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
read_credit_accounts
read_credit_adjustments
GET /
curl -i -H 'X-Recharge-Access-Token: your_api_token'
-X GET

Versioning

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

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

Responses

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

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

Extending responses

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

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

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

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

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

Cursor Pagination

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

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

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

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

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


Retrieving total number of records

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

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

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

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

# Display results
echo $content | jq "."

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

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

Sorting

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


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

Addresses

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

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

Bundle Selections

Pro plan

SCI

RCS

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

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

Charges

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

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

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
  • id
    integer

    The unique numeric identifier for the Charge.

  • address_id
    integer

    The ID of the shipping Address tied to the Charge.

  • analytics_data
    object

    An object containing analytics data associated with the Charge.

    Show object attributes
  • billing_address
    object

    All the billing information related to the charge.

    Show object attributes
  • client_details
    object

    Details of the access method used by the purchaser.

    Show object attributes
  • created_at
    datetime

    The date and time when the transaction was created.

  • currency
    string

    The code of the currency for this Charge, such as USD.

    Related guides: Supported currencies

  • customer
    object

    An object containing Customer information associated with this Charge.

    Show object attributes
  • discounts
    array

    An array of Discounts associated with the Charge.

    Show object attributes
  • external_order_id
    object

    An object containing the associated external order ID.

    Show object attributes
  • external_transaction_id
    object

    An object containing the associated external transaction ID.

    Show object attributes
  • line_items
    array

    A list of line_item objects, each containing information about a distinct purchase item.

    Show object attributes
  • note
    string

    Notes associated with the Charge.

  • order_attributes
    array

    An array of name-value pairs of order attributes on the Charge.

    Show object attributes
  • orders_count
    integer

    The number of Orders generated from this Charge (>1 for prepaid Subscriptions).

  • payment_processor
    string

    The payment processor used for this Charge.

  • processed_at
    datetime

    The date and time when the transaction was processed.

  • scheduled_at
    date

    The date time of when the Charge is/was scheduled to process.

  • shipping_address
    object

    The shipping Address of the Charge.

    Show object attributes
  • shipping_lines
    array

    An array of shipping lines associated with the Charge.

    Show object attributes
  • status
    string

    Possible values:   success,   error,   queued,   skipped,   refunded,   partially_refunded,   pending_manual_payment,   pending

    The status of the Charge.

  • subtotal_price
    string

    The combined price of all line_items without taxes and shipping.

  • tags
    string

    A comma-separated list of tags on the Charge.

  • tax_lines
    array

    An array of tax lines that apply to the Charge.

    Show object attributes
  • taxable
    boolean

    A boolean indicator of the taxability of the Charge.

  • taxes_included
    boolean

    Whether taxes are included in the order subtotal.

  • total_discounts
    string

    The sum of the Discounts applied to the Charge.

  • total_line_items_price
    string

    The total price of all line items of the Charge.

  • total_price
    string

    The sum of all the prices of all the items in the Charge, taxes and discounts included (must be positive).

  • total_refunds
    string

    The sum of all refunds that were applied to the Charge.

  • total_tax
    string

    The total tax due associated with the Charge.

  • total_weight_grams
    integer

    The total weight of the Charge’s line items in grams.

  • type
    string

    Possible values:   checkout,   recurring

    An indicator of the Charge’s type, either checkout or recurring.

  • updated_at
    datetime

    The date time at which the Charge was most recently updated.

Error related attributes
  • error
    string

    Error reason as sentence text (typically returned direct from the payment processor). e.g. "error": "Customer needs to update credit card"

  • error_type
    string

    Structured reason why the charge failed such as CUSTOMER_NEEDS_TO_UPDATE_CARD.

  • charge_attempts
    integer

    Shows how many times an attempt to charge was placed.

  • external_variant_id_not_found
    boolean

    Indicates if Recharge was able to find the external_variant_id from the Charge.

  • retry_date
    date

    The date when the next attempt will be placed.

More Attributes
  • has_uncommited_changes
    boolean

    Specifies whether the Charge is scheduled for a regeneration (if the Subscription related to the charge was updated in the last 5 seconds using commit=false).

The charge object
{
  "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.

Scopes: read_orders
Responses
  • 200

    successful response

    Show response object
GET
/charges/{id} 
curl 'https://api.rechargeapps.com/charges/377749210' \ 
 -H 'X-Recharge-Version: 2021-11' \ 
 -H 'X-Recharge-Access-Token: your_api_token'
Response 
{
  "charge": {
    "id": 377749210,
    "address_id": 42171447,
    "analytics_data": {
      "utm_params": [
        {
          "utm_source": "facebook",
          "utm_medium": "cpc"
        }
      ]
    },
    "billing_address": {
      "address1": "601 SW Washing St.",
      "address2": "Suite 101",
      "city": "Portland",
      "company": "Acme Corp",
      "country_code": "US",
      "first_name": "Jane",
      "last_name": "Doe",
      "phone": "888-888-8888",
      "province": "Oregon",
      "zip": "97205"
    },
    "client_details": {
      "browser_ip": "192.168.0.1",
      "user_agent": "safari webkit"
    },
    "created_at": "2021-11-09T19:22:13+00:00",
    "currency": "USD",
    "customer": {
      "id": 37657002,
      "email": "test@test.com",
      "external_customer_id": {
        "ecommerce": "2879413682227"
      },
      "hash": "7e706455cbd13e40"
    },
    "discounts": [
      {
        "id": 12345,
        "code": "TESTCODE10",
        "value": 10,
        "value_type": "fixed_amount"
      }
    ],
    "error": null,
    "error_type": null,
    "external_order_id": {
      "ecommerce": "2541635698739"
    },
    "external_transaction_id": {
      "payment_processor": "ch_1HzWElJ2zqHvZRd1TWKFFqDR"
    },
    "has_uncommitted_changes": false,
    "line_items": [
      {
        "purchase_item_id": 63898947,
        "external_product_id": {
          "ecommerce": "4381728735283"
        },
        "external_variant_id": {
          "ecommerce": "999999999999"
        },
        "grams": 454,
        "handle": "shirt-package",
        "images": {
          "large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg",
          "medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg",
          "original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg",
          "small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg"
        },
        "original_price": "10.00",
        "properties": [
          {
            "name": "Color",
            "value": "Blue"
          }
        ],
        "purchase_item_type": "subscription",
        "quantity": 1,
        "sku": "TOM0001",
        "tax_due": "1.30",
        "tax_lines": [
          {
            "price": "0.9931",
            "rate": "0.0725",
            "title": "CA State Tax",
            "unit_price": "0.3310"
          },
          {
            "price": "0.3082",
            "rate": "0.0225",
            "title": "LA County Tax",
            "unit_price": "0.1027"
          }
        ],
        "taxable": true,
        "taxable_amount": "10.00",
        "title": "Shirt package",
        "total_price": "11.30",
        "unit_price": "10.00",
        "unit_price_includes_tax": false,
        "variant_title": "Blue T-shirt"
      }
    ],
    "note": "next order in sequence 3",
    "order_attributes": [
      {
        "name": "Checkout-Method",
        "value": "delivery"
      }
    ],
    "orders_count": 1,
    "payment_processor": "stripe",
    "processed_at": "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.

Scopes: read_orders
Query Parameters
  • address_id
    string

    Filter Charges by Address.

  • created_at_max
    string

    Show Charges created before the given date.

  • created_at_min
    string

    Show Charges created after the given date.

  • customer_id
    string

    Filter Charges by Customer.

  • discount_code
    string

    List Charges that contain the given discount_code.

  • discount_id
    string

    List Charges that contain the given discount_id.

  • external_order_id
    string

    Filter Charges by the associated order ID in the external e-commerce platform.

  • ids
    string

    Filter Charges by ID.

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

  • limit
    string

    Default: 50

    Max: 250

    The amount of results.

  • page
    string

    Default: 1

    The page to show.

  • purchase_item_id
    string

    Filter Charges by a Subscription or Onetime ID.

  • purchase_item_ids
    string

    Filter Charges by a comma-separated list of Subscription or Onetime IDs.

  • scheduled_at
    string

    Filter Charges by specific scheduled charge date.

  • scheduled_at_max
    string

    Show Charges scheduled to be processed before the given date.

  • scheduled_at_min
    string

    Show Charges scheduled to be processed after the given date.

  • sort_by
    string

    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.

  • status
    string

    Filter charges by status.
    Available status: success, queued, error, refunded, partially_refunded, skipped, pending_manual_payment, pending.

  • updated_at_max
    string

    Show charges updated before the given date.

  • updated_at_min
    string

    Show charges updated after the given date.

  • processed_at_min
    string

    Show charges processed after, and including, the given date.

  • processed_at_max
    string

    Show charges processed before, and including, the given date.

Responses
  • 200

    successful response

    Show response object
GET
/charges 
curl 'https://api.rechargeapps.com/charges' \ 
 -H 'X-Recharge-Version: 2021-11' \ 
 -H 'X-Recharge-Access-Token: your_api_token' \ 
 -d limit=3 -G
Response 
{
  "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.

Scopes: write_orders
Body Parameters
  • discount_code
    string

    Code of the Discount you want to apply to a Charge.

  • discount_id
    integer

    ID of the Discount you want to apply to a Charge.

Responses
  • 200

    successful response

    Show response object
POST
/charges/{id}/apply_discount 
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"}'
Response 
{
  "charge": {
    "id": 377749210,
    "address_id": 42171447,
    "analytics_data": {
      "utm_params": [
        {
          "utm_source": "facebook",
          "utm_medium": "cpc"
        }
      ]
    },
    "billing_address": {
      "address1": "601 SW Washing St.",
      "address2": "Suite 101",
      "city": "Portland",
      "company": "Acme Corp",
      "country_code": "US",
      "first_name": "Jane",
      "last_name": "Doe",
      "phone": "888-888-8888",
      "province": "Oregon",
      "zip": "97205"
    },
    "client_details": {
      "browser_ip": "192.168.0.1",
      "user_agent": "safari webkit"
    },
    "created_at": "2021-11-09T19:22:13+00:00",
    "currency": "USD",
    "customer": {
      "id": 37657002,
      "email": "test@test.com",
      "external_customer_id": {
        "ecommerce": "2879413682227"
      },
      "hash": "7e706455cbd13e40"
    },
    "discounts": [
      {
        "id": 12345,
        "code": "TESTCODE10",
        "value": 10,
        "value_type": "fixed_amount"
      }
    ],
    "error": null,
    "error_type": null,
    "external_order_id": {
      "ecommerce": "2541635698739"
    },
    "external_transaction_id": {
      "payment_processor": "ch_1HzWElJ2zqHvZRd1TWKFFqDR"
    },
    "has_uncommitted_changes": false,
    "line_items": [
      {
        "purchase_item_id": 63898947,
        "external_product_id": {
          "ecommerce": "4381728735283"
        },
        "external_variant_id": {
          "ecommerce": "999999999999"
        },
        "grams": 454,
        "handle": "shirt-package",
        "images": {
          "large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg",
          "medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg",
          "original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg",
          "small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg"
        },
        "original_price": "10.00",
        "properties": [
          {
            "name": "Color",
            "value": "Blue"
          }
        ],
        "purchase_item_type": "subscription",
        "quantity": 1,
        "sku": "TOM0001",
        "tax_due": "1.30",
        "tax_lines": [
          {
            "price": "0.9931",
            "rate": "0.0725",
            "title": "CA State Tax",
            "unit_price": "0.3310"
          },
          {
            "price": "0.3082",
            "rate": "0.0225",
            "title": "LA County Tax",
            "unit_price": "0.1027"
          }
        ],
        "taxable": true,
        "taxable_amount": "10.00",
        "title": "Shirt package",
        "total_price": "11.30",
        "unit_price": "10.00",
        "unit_price_includes_tax": false,
        "variant_title": "Blue T-shirt"
      }
    ],
    "note": "next order in sequence 3",
    "order_attributes": [
      {
        "name": "Checkout-Method",
        "value": "delivery"
      }
    ],
    "orders_count": 1,
    "payment_processor": "stripe",
    "processed_at": "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.

Scopes: write_orders
Responses
  • 200

    successful response

    Show response object
POST
/charges/{id}/remove_discount 
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 '{}'
Response 
{
  "charge": {
    "id": 377749210,
    "address_id": 42171447,
    "analytics_data": {
      "utm_params": [
        {
          "utm_source": "facebook",
          "utm_medium": "cpc"
        }
      ]
    },
    "billing_address": {
      "address1": "601 SW Washing St.",
      "address2": "Suite 101",
      "city": "Portland",
      "company": "Acme Corp",
      "country_code": "US",
      "first_name": "Jane",
      "last_name": "Doe",
      "phone": "888-888-8888",
      "province": "Oregon",
      "zip": "97205"
    },
    "client_details": {
      "browser_ip": "192.168.0.1",
      "user_agent": "safari webkit"
    },
    "created_at": "2021-11-09T19:22:13+00:00",
    "currency": "USD",
    "customer": {
      "id": 37657002,
      "email": "test@test.com",
      "external_customer_id": {
        "ecommerce": "2879413682227"
      },
      "hash": "7e706455cbd13e40"
    },
    "discounts": [],
    "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.

Scopes: write_orders
Responses
  • 200

    successful response

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

Unskip a charge

Unskip a Charge.

Scopes: write_orders
Responses
  • 200

    successful response

    Show response object
  • 422

    Unprocessable

    Show response object
POST
/charges/{id}/unskip 
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]}'
Response 
{
  "charge": {
    "id": 377749210,
    "address_id": 42171447,
    "analytics_data": {
      "utm_params": [
        {
          "utm_source": "facebook",
          "utm_medium": "cpc"
        }
      ]
    },
    "billing_address": {
      "address1": "601 SW Washing St.",
      "address2": "Suite 101",
      "city": "Portland",
      "company": "Acme Corp",
      "country_code": "US",
      "first_name": "Jane",
      "last_name": "Doe",
      "phone": "888-888-8888",
      "province": "Oregon",
      "zip": "97205"
    },
    "client_details": {
      "browser_ip": "192.168.0.1",
      "user_agent": "safari webkit"
    },
    "created_at": "2021-11-09T19:22:13+00:00",
    "currency": "USD",
    "customer": {
      "id": 37657002,
      "email": "test@test.com",
      "external_customer_id": {
        "ecommerce": "2879413682227"
      },
      "hash": "7e706455cbd13e40"
    },
    "discounts": [
      {
        "id": 12345,
        "code": "TESTCODE10",
        "value": 10,
        "value_type": "fixed_amount"
      }
    ],
    "error": null,
    "error_type": null,
    "external_order_id": {
      "ecommerce": "2541635698739"
    },
    "external_transaction_id": {
      "payment_processor": "ch_1HzWElJ2zqHvZRd1TWKFFqDR"
    },
    "has_uncommitted_changes": false,
    "line_items": [
      {
        "purchase_item_id": 63898947,
        "external_product_id": {
          "ecommerce": "4381728735283"
        },
        "external_variant_id": {
          "ecommerce": "999999999999"
        },
        "grams": 454,
        "handle": "shirt-package",
        "images": {
          "large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg",
          "medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg",
          "original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg",
          "small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg"
        },
        "original_price": "10.00",
        "properties": [
          {
            "name": "Color",
            "value": "Blue"
          }
        ],
        "purchase_item_type": "subscription",
        "quantity": 1,
        "sku": "TOM0001",
        "tax_due": "1.30",
        "tax_lines": [
          {
            "price": "0.9931",
            "rate": "0.0725",
            "title": "CA State Tax",
            "unit_price": "0.3310"
          },
          {
            "price": "0.3082",
            "rate": "0.0225",
            "title": "LA County Tax",
            "unit_price": "0.1027"
          }
        ],
        "taxable": true,
        "taxable_amount": "10.00",
        "title": "Shirt package",
        "total_price": "11.30",
        "unit_price": "10.00",
        "unit_price_includes_tax": false,
        "variant_title": "Blue T-shirt"
      }
    ],
    "note": "next order in sequence 3",
    "order_attributes": [
      {
        "name": "Checkout-Method",
        "value": "delivery"
      }
    ],
    "orders_count": 1,
    "payment_processor": "stripe",
    "processed_at": null,
    "retry_date": null,
    "scheduled_at": "2021-12-09",
    "shipping_address": {
      "address1": "1030 Barnum Ave",
      "address2": "Suite 101",
      "city": "Stratford",
      "company": "Fake Company",
      "country_code": "US",
      "first_name": "Fake First",
      "last_name": "Fake Last",
      "phone": "999-999-9999",
      "province": "Connecticut",
      "zip": "06614"
    },
    "shipping_lines": [
      {
        "code": "Standard",
        "price": "4.90",
        "source": "shopify",
        "taxable": true,
        "tax_lines": [
          {
            "price": "0.355",
            "rate": 0.0725,
            "title": "CA State Tax"
          },
          {
            "price": "0.110",
            "rate": 0.0225,
            "title": "Los Angeles  County Tax"
          }
        ],
        "title": "Standard"
      }
    ],
    "status": "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

BigCommerce

Custom

RCS

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.

Scopes: write_orders write_payment_methods
Body Parameters
  • amount
    string
    * Required

    Amount of money that will be refunded. It can be fully or partially refunded.

  • full_refund
    boolean

    If this parameter has value true, the Charge will be totally refunded.

  • retry
    boolean

    If this parameter has value true and full_refund has value true, the Charge will be retried. The status on the Charge will be returned as “error”.

  • error
    string

    If the retry parameter has value true, this value is required. Valid values are “insufficient_inventory”.

  • error_type
    string

    If the retry parameter has value true, this value is required.

Responses
  • 200

    successful response

    Show response object
POST
/charges/{id}/refund 
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}'
Response 
{
  "charge": {
    "id": 377749210,
    "address_id": 42171447,
    "analytics_data": {
      "utm_params": [
        {
          "utm_source": "facebook",
          "utm_medium": "cpc"
        }
      ]
    },
    "billing_address": {
      "address1": "601 SW Washing St.",
      "address2": "Suite 101",
      "city": "Portland",
      "company": "Acme Corp",
      "country_code": "US",
      "first_name": "Jane",
      "last_name": "Doe",
      "phone": "888-888-8888",
      "province": "Oregon",
      "zip": "97205"
    },
    "client_details": {
      "browser_ip": "192.168.0.1",
      "user_agent": "safari webkit"
    },
    "created_at": "2021-11-09T19:22:13+00:00",
    "currency": "USD",
    "customer": {
      "id": 37657002,
      "email": "test@test.com",
      "external_customer_id": {
        "ecommerce": "2879413682227"
      },
      "hash": "7e706455cbd13e40"
    },
    "discounts": [
      {
        "id": 12345,
        "code": "TESTCODE10",
        "value": 10,
        "value_type": "fixed_amount"
      }
    ],
    "error": null,
    "error_type": null,
    "external_order_id": {
      "ecommerce": "2541635698739"
    },
    "external_transaction_id": {
      "payment_processor": "ch_1HzWElJ2zqHvZRd1TWKFFqDR"
    },
    "has_uncommitted_changes": false,
    "line_items": [
      {
        "purchase_item_id": 63898947,
        "external_product_id": {
          "ecommerce": "4381728735283"
        },
        "external_variant_id": {
          "ecommerce": "999999999999"
        },
        "grams": 454,
        "handle": "shirt-package",
        "images": {
          "large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg",
          "medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg",
          "original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg",
          "small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg"
        },
        "original_price": "10.00",
        "properties": [
          {
            "name": "Color",
            "value": "Blue"
          }
        ],
        "purchase_item_type": "subscription",
        "quantity": 1,
        "sku": "TOM0001",
        "tax_due": "1.30",
        "tax_lines": [
          {
            "price": "0.9931",
            "rate": "0.0725",
            "title": "CA State Tax",
            "unit_price": "0.3310"
          },
          {
            "price": "0.3082",
            "rate": "0.0225",
            "title": "LA County Tax",
            "unit_price": "0.1027"
          }
        ],
        "taxable": true,
        "taxable_amount": "10.00",
        "title": "Shirt package",
        "total_price": "11.30",
        "unit_price": "10.00",
        "unit_price_includes_tax": false,
        "variant_title": "Blue T-shirt"
      }
    ],
    "note": "next order in sequence 3",
    "order_attributes": [
      {
        "name": "Checkout-Method",
        "value": "delivery"
      }
    ],
    "orders_count": 1,
    "payment_processor": "stripe",
    "processed_at": "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.

Scopes: write_payments
Responses
  • 200

    successful response

    Show response object
POST
/charges/{id}/process 
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 '{}'
Response 
{
  "charge": {
    "id": 377749210,
    "address_id": 42171447,
    "analytics_data": {
      "utm_params": [
        {
          "utm_source": "facebook",
          "utm_medium": "cpc"
        }
      ]
    },
    "billing_address": {
      "address1": "601 SW Washing St.",
      "address2": "Suite 101",
      "city": "Portland",
      "company": "Acme Corp",
      "country_code": "US",
      "first_name": "Jane",
      "last_name": "Doe",
      "phone": "888-888-8888",
      "province": "Oregon",
      "zip": "97205"
    },
    "client_details": {
      "browser_ip": "192.168.0.1",
      "user_agent": "safari webkit"
    },
    "created_at": "2021-11-09T19:22:13+00:00",
    "currency": "USD",
    "customer": {
      "id": 37657002,
      "email": "test@test.com",
      "external_customer_id": {
        "ecommerce": "2879413682227"
      },
      "hash": "7e706455cbd13e40"
    },
    "discounts": [
      {
        "id": 12345,
        "code": "TESTCODE10",
        "value": 10,
        "value_type": "fixed_amount"
      }
    ],
    "error": null,
    "error_type": null,
    "external_order_id": {
      "ecommerce": "2541635698739"
    },
    "external_transaction_id": {
      "payment_processor": "ch_1HzWElJ2zqHvZRd1TWKFFqDR"
    },
    "has_uncommitted_changes": false,
    "line_items": [
      {
        "purchase_item_id": 63898947,
        "external_product_id": {
          "ecommerce": "4381728735283"
        },
        "external_variant_id": {
          "ecommerce": "999999999999"
        },
        "grams": 454,
        "handle": "shirt-package",
        "images": {
          "large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg",
          "medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg",
          "original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg",
          "small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg"
        },
        "original_price": "10.00",
        "properties": [
          {
            "name": "Color",
            "value": "Blue"
          }
        ],
        "purchase_item_type": "subscription",
        "quantity": 1,
        "sku": "TOM0001",
        "tax_due": "1.30",
        "tax_lines": [
          {
            "price": "0.9931",
            "rate": "0.0725",
            "title": "CA State Tax",
            "unit_price": "0.3310"
          },
          {
            "price": "0.3082",
            "rate": "0.0225",
            "title": "LA County Tax",
            "unit_price": "0.1027"
          }
        ],
        "taxable": true,
        "taxable_amount": "10.00",
        "title": "Shirt package",
        "total_price": "11.30",
        "unit_price": "10.00",
        "unit_price_includes_tax": false,
        "variant_title": "Blue T-shirt"
      }
    ],
    "note": "next order in sequence 3",
    "order_attributes": [
      {
        "name": "Checkout-Method",
        "value": "delivery"
      }
    ],
    "orders_count": 1,
    "payment_processor": "stripe",
    "processed_at": "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.

Scopes: write_customers write_orders write_payment_methods write_subscriptions
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
POST
/charges/{id}/capture_payment 
curl 'https://api.rechargeapps.com/charges/100714428/capture_payment' \ 
 -H 'Content-Type: application/json' \ 
 -H 'X-Recharge-Access-Token: your_api_token' \ 
 -d '{}'
Response 
{
  "charge": {
    "id": 377749210,
    "address_id": 42171447,
    "analytics_data": {
      "utm_params": [
        {
          "utm_source": "facebook",
          "utm_medium": "cpc"
        }
      ]
    },
    "billing_address": {
      "address1": "601 SW Washing St.",
      "address2": "Suite 101",
      "city": "Portland",
      "company": "Acme Corp",
      "country_code": "US",
      "first_name": "Jane",
      "last_name": "Doe",
      "phone": "888-888-8888",
      "province": "Oregon",
      "zip": "97205"
    },
    "client_details": {
      "browser_ip": "192.168.0.1",
      "user_agent": "safari webkit"
    },
    "created_at": "2021-11-09T19:22:13+00:00",
    "currency": "USD",
    "customer": {
      "id": 37657002,
      "email": "test@test.com",
      "external_customer_id": {
        "ecommerce": "2879413682227"
      },
      "hash": "7e706455cbd13e40"
    },
    "discounts": [
      {
        "id": 12345,
        "code": "TESTCODE10",
        "value": 10,
        "value_type": "fixed_amount"
      }
    ],
    "error": null,
    "error_type": null,
    "external_order_id": {
      "ecommerce": "2541635698739"
    },
    "external_transaction_id": {
      "payment_processor": "ch_1HzWElJ2zqHvZRd1TWKFFqDR"
    },
    "has_uncommitted_changes": false,
    "line_items": [
      {
        "purchase_item_id": 63898947,
        "external_product_id": {
          "ecommerce": "4381728735283"
        },
        "external_variant_id": {
          "ecommerce": "999999999999"
        },
        "grams": 454,
        "handle": "shirt-package",
        "images": {
          "large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg",
          "medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg",
          "original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg",
          "small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg"
        },
        "original_price": "10.00",
        "properties": [
          {
            "name": "Color",
            "value": "Blue"
          }
        ],
        "purchase_item_type": "subscription",
        "quantity": 1,
        "sku": "TOM0001",
        "tax_due": "1.30",
        "tax_lines": [
          {
            "price": "0.9931",
            "rate": "0.0725",
            "title": "CA State Tax",
            "unit_price": "0.3310"
          },
          {
            "price": "0.3082",
            "rate": "0.0225",
            "title": "LA County Tax",
            "unit_price": "0.1027"
          }
        ],
        "taxable": true,
        "taxable_amount": "10.00",
        "title": "Shirt package",
        "total_price": "11.30",
        "unit_price": "10.00",
        "unit_price_includes_tax": false,
        "variant_title": "Blue T-shirt"
      }
    ],
    "note": "next order in sequence 3",
    "order_attributes": [
      {
        "name": "Checkout-Method",
        "value": "delivery"
      }
    ],
    "orders_count": 1,
    "payment_processor": "stripe",
    "processed_at": "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

Pro plan

BigCommerce

Custom

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

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

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

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