API
GuidesWhat’s newGet API token
Core Resources

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).

75 additions in V2, marked New

Everything marked New also works when you send X-Recharge-Version: 2021-11.

How Charges relate to other resources
Endpoints

#The charge object

A Charge is the representation of the financial transaction linked to a purchase (past or future). It can be a transaction that was processed already or the representation of an upcoming transaction. A charge is linked to its corresponding Orders (one for pay as you go subscriptions and several for pre-paid).
A Charge can have many parent subscriptions. All subscriptions on a given Address with the same next_charge_date date will be merged into one Charge and that charge will contain one line_item per Subscription.

Attributes

  • idinteger
    The unique numeric identifier for the Charge.
  • address_idinteger
    The ID of the shipping Address tied to the Charge.
  • analytics_dataobject
    An object containing analytics data associated with the Charge.
    Show child attributesHide child attributes1
  • billing_addressobject
    All the billing information related to the charge.
    Show child attributesHide child attributes10
    • address1string
      Line one of the billing address.
    • address2string
      Line two of the billing address.
    • citystring
      The city of the billing address.
    • companystring
      The company name of the billing address.
    • country_codestring
      2-letter country code.
    • first_namestring
      The first name of the billing address.
    • last_namestring
      The last name of the billing address.
    • phonestring
      The phone number of the billing address.
    • provincestring
      The name of the province or state associated with the billing address.
    • zipstring
      The zip code or postcode of the address.
  • client_detailsobject
    Details of the access method used by the purchaser.
    Show child attributesHide child attributes2
    • browser_ipstring
      The IP address of the buyer as detected in Checkout.
    • user_agentstring
      The user agent detected during Checkout.
  • external_variant_not_foundstring · nullableNew
    The ID of the variant, as it appears in the external e-commerce platform, that could not be found when the Charge was processed.
    Only returned when the Charge has a status of error.
  • has_uncommitted_changesbooleanNew
    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).
  • includeobjectNew
    An object containing the related resources requested with the include query parameter.
    Only returned when the include query parameter is passed.
    Show child attributesHide child attributes1034 new
    • addressobject · nullableNew
      The Address associated with the Charge.
      Only returned when include contains address.
    • bundle_selectionsobject · nullableNew
      The BundleSelection associated with the Charge.
      Only returned when include contains bundle_selections. Populated only for stores with charge-level bundle selections enabled; otherwise null.
    • charge_activitiesarrayNew
      An array of charge activity objects recorded for the Charge in the last 90 days.
      Only returned when include contains charge_activities.
    • credit_projectionobject · nullableNew
      The credits the Charge is projected to redeem when it processes, in the currency of the Charge. null when the Charge does not have a status of queued or error, or when the projection could not be built.
      Only returned by GET /charges/{id} when include contains credit_projection.
      Show child attributesHide child attributes77 new
      • blocked_by_exclusionobjectNew
        An object keyed by credit type. Each value contains amount, the additional credit that type would have contributed if no products were excluded, and excluded_product_ids, the external product IDs on the Charge that the credit type cannot be spent on.
      • capped_by_redemption_limitbooleanNew
        Whether the store's maximum redemption limit would hold back non-gift credit if the Customer opted in to applying credit.
      • currency_codestringNew
        The code of the currency the projected amounts are expressed in.
      • gift_to_applystringNew
        The amount of gift credit the Charge is projected to redeem.
      • non_gift_to_applystringNew
        The amount of non-gift credit the Charge is projected to redeem.
      • total_to_applystringNew
        The total amount of credit the Charge will redeem if nothing changes.
      • total_to_apply_if_opted_instringNew
        The total amount of credit the Charge would redeem if the Customer had apply_credit_to_next_recurring_charge set to true.
    • customerobjectNew
      The Customer associated with the Charge.
      Only returned when include contains customer.
    • metafieldsarrayNew
      An array of Metafields attached to the Charge.
      Only returned when include contains metafields.
    • order_modificationsarray of objectsNew
      An array of the modifications, such as added free gifts, applied to the Charge.
      Only returned when include contains order_modifications.
      Show child attributesHide child attributes710 new
      • idintegerNew
        The unique numeric identifier for the order modification.
      • charge_idinteger · nullableNew
        The ID of the Charge the modification applies to.
      • order_idinteger · nullableNew
        The ID of the Order the modification applies to.
      • customer_idinteger · nullableNew
        The ID of the Customer the modification belongs to.
      • modificationsobjectNew
        An object containing the changes applied to the Charge.
        Show child attributesHide child attributes33 new
        • line_itemsarrayNew
          An array of line item modifications. Each item contains line_item_id, subscription_id, modification_type, source, source_id, reason, reason_id and a modifications array of changed attributes (attribute, value, previous_value, reason, created_at).
        • move_is_allowedbooleanNew
          Whether the modification can be carried over to the new queued Charge when this Charge is replaced.
        • order_wide_changesarray · nullableNew
          An array of modifications that apply to the whole Charge rather than to a single line item.
      • created_atdatetimeNew
        The date and time when the order modification was created.
      • updated_atdatetimeNew
        The date and time when the order modification was last updated.
    • payment_methodsarrayNew
      An array of PaymentMethods associated with the Charge.
      Only returned when include contains payment_methods.
    • subscriptionsarrayNew
      An array of the Subscriptions contained in the Charge.
      Only returned when include contains subscriptions.
    • transactionsarray of objectsNew
      An array of the payment transactions recorded for the Charge.
      Only returned when include contains transactions.
      Show child attributesHide child attributes77 new
      • external_transaction_idstring · nullableNew
        The ID of the transaction in the payment processor system.
      • processor_namestring · nullableNew
        The payment processor used for the transaction.
      • amountstringNew
        The amount of the transaction.
      • kindstring · nullableNew
        The kind of transaction, such as sale or refund.
      • payment_method_idinteger · nullableNew
        The ID of the PaymentMethod used for the transaction.
      • is_primarybooleanNew
        Whether the transaction is the primary transaction of the Charge.
      • created_atdatetimeNew
        The date and time when the transaction was created.
  • last_charge_attemptdatetime · nullableNew
    The date and time of the most recent attempt to process the Charge.
    Only returned when the Charge has a status of error.
  • merged_atdatetime · nullableNew
    The date and time when the Charge was last merged with another Charge.
  • original_scheduled_atdate · nullableNew
    The date the Charge was scheduled to process when it was first created. This value does not change if the Charge is rescheduled.
  • total_dutiesstring · nullableNew
    The sum of all duties applied to the Charge.
  • created_atdatetime
    The date and time when the transaction was created.
  • currencystring
    The code of the currency for this Charge, such as USD.
    Related guides: Supported currencies
  • customerobject
    An object containing Customer information associated with this Charge.
    Show child attributesHide child attributes4
    • idinteger
      The ID of the associated customer record.
    • emailstring
      The user email.
    • external_customer_idobject
      An object containing customer information associated with this charge.
      Show child attributesHide child attributes1
      • ecommercestring
        The customer ID as it appears in the external e-commerce platform.
    • hashstring
      The hash of the Customer associated with the Charge.
  • discountsarray of objects
    An array of Discounts associated with the Charge.
    Show child attributesHide child attributes62 new
    • idinteger
      The ID of the Discount.
    • codestring
      The code of the Discount.
    • valuefloat
      The value of the Discount.
    • value_typestring
      The type of the value of the Discount.
      Possible values
      percentagefixed_amountshipping
    • titlestring · nullableNew
      The title of the Discount.
      Populated only for stores with automatic discounts enabled; otherwise null.
    • application_methodstring · nullableNew
      How the Discount is applied, either through a code or automatically.
      Possible values
      codeautomatic
      Populated only for stores with automatic discounts enabled; otherwise null.
  • errorstring
    Error reason as sentence text (typically returned direct from the payment processor). e.g. "error": "Customer needs to update credit card"
  • error_typestring
    Structured reason why the charge failed such as CUSTOMER_NEEDS_TO_UPDATE_CARD.
  • charge_attemptsinteger
    Shows how many times an attempt to charge was placed. Only returned when the Charge has a status of error.
  • external_order_idobject
    An object containing the associated external order ID.
    Show child attributesHide child attributes1
    • ecommercestring
      The order ID as it appears in the external e-commerce platform.
  • external_transaction_idobject
    An object containing the associated external transaction ID.
    Show child attributesHide child attributes1
    • payment_processorstring
      The ID of the associated transaction in a payment processor system (like Stripe).
  • line_itemsarray of objects
    A list of line_item objects, each containing information about a distinct purchase item.
    Show child attributesHide child attributes226 new
    • external_line_item_idobjectNew
      An object containing the ID of the associated line item as it appears in the external system.
      Only returned for stores that have external line item IDs enabled.
      Show child attributesHide child attributes11 new
      • ecommercestring · nullableNew
        The line item ID as it appears in the external e-commerce platform.
        Only returned for stores that have external line item IDs enabled.
    • offer_attributesobject · nullableNew
      An object describing the offer that added the line_item to the Charge, such as a free gift. null when the line_item was not added by an offer.
      Show child attributesHide child attributes22 new
      • typestring · nullableNew
        The type of offer that added the line_item, such as free_gift.
      • sourcestring · nullableNew
        The source of the offer that added the line_item.
    • purchase_item_idinteger
      The Subscription or Onetime ID associated with the line_item.
    • external_product_idobject
      An object containing the associated product ID as it appears in the external system.
      Show child attributesHide child attributes1
      • ecommercestring
        The product id as it appears in the external e-commerce platform. The external_product_id of the Product record in Recharge, linking a Plan to a Product.
    • external_variant_idobject
      An object containing the associated variant ID as it appears in the external system.
      Show child attributesHide child attributes1
      • ecommercestring
        The variant id as it appears in the external e-commerce platform. The external_variant_id of the Product record in Recharge, linking a Plan to a Product.
    • gramsinteger
      The weight of the item in grams.
    • handlestring
      A unique, human-friendly string for the Product.
    • imagesobject
      An object containing URLs of the Product image.
      Show child attributesHide child attributes4
      • largestring
        The url where a large image file is located.
      • mediumstring
        The url where a medium image file is located.
      • smallstring
        The url where a small image file is located.
      • originalstring
        The url of the original sized product image.
    • original_pricestring
      The original price of the line_item without discounts or taxes.
    • propertiesarray of objects
      An array of name value pairs of additional line_item attributes.
      Show child attributesHide child attributes2
      • namestring
        The name of the property.
      • valuestring
        The value of the property.
    • purchase_item_typestring
      An indicator of the type of the purchase item.
      Possible values
      subscriptiononetime
    • quantityinteger
      The quantity of the line_item.
    • skustring
      The SKU (stock keeping unit) of the Product associated with the line_item.
    • tax_duestring
      The total tax due associated with the line_item.
    • tax_linesarray of objects
      an array containing tax_line objects associated with this line_item.
      Show child attributesHide child attributes41 new
      • pricestring
        The total tax associated with the listed jurisdiction.
      • ratestring
        The tax rate associated with the listed jurisdiction.
      • titlestring
        The title/name of the taxing jurisdiction.
      • unit_pricestringNew
        The tax per unit of the line_item associated with the listed jurisdiction.
    • taxableboolean
      A boolean indicating if the line_item is taxable or non-taxable.
    • taxable_amountstring
      The taxable revenue associated with the line_item.
    • titlestring
      The title of the Product of this line_item.
    • total_pricestring
      The total price of the line_item including tax.
    • unit_pricestring
      The unit price of the line_item.
    • unit_price_includes_taxboolean
      A boolean indicator if tax is included in the price of an item.
    • variant_titlestring
      The name of a variant of the Product of this line_item.
  • notestring
    Notes associated with the Charge.
  • order_attributesarray of objects
    An array of name-value pairs of order attributes on the Charge.
    Show child attributesHide child attributes2
    • namestring
      The name for the attribute.
    • valuestring
      The value for the associated attribute.
  • orders_countinteger
    The number of Orders generated from this Charge (>1 for prepaid Subscriptions).
  • payment_processorstring
    The payment processor used for this Charge.
  • processed_atdatetime
    The date and time when the transaction was processed.
  • retry_datedatetime
    The date when the next attempt will be placed.
  • scheduled_atdate
    The date time of when the Charge is/was scheduled to process.
  • shipping_addressobject
    The shipping Address of the Charge.
    Show child attributesHide child attributes10
    • address1string
      Line one of the billing address.
    • address2string
      Line two of the billing address.
    • citystring
      The city of the billing address.
    • companystring
      The company name of the billing address.
    • country_codestring
      2-letter country code.
    • first_namestring
      The first name of the billing address.
    • last_namestring
      The last name of the billing address.
    • phonestring
      The phone number of the billing address.
    • provincestring
      The name of the province or state associated with the billing address.
    • zipstring
      The zip code or postcode of the address.
  • shipping_linesarray of objects
    An array of shipping lines associated with the Charge.
    Show child attributesHide child attributes93 new
    • codestring
      The code associated with the shipping_line of a Charge.
    • pricestring
      The price of the shipping_line.
    • sourcestring
      The source of the shipping_line.
    • titlestring
      The title of the shipping_line.
    • taxableboolean
      A boolean indicating if the shipping_line is taxable.
    • tax_linesarray of objects
      An array of tax lines associated with the shipping_line.
      Show child attributesHide child attributes3
      • pricestring
        The total tax associated with the listed jurisdiction.
      • ratestring
        The tax rate associated with the listed jurisdiction.
      • titlestring
        The title/name of the taxing jurisdiction.
    • ratestringNew
      The rate associated with the shipping_line.
      Only returned when a rate is stored on the shipping_line.
    • statusstringNew
      The status of the shipping rate used for the shipping_line. Defaults to active.
      Possible values
      activependingqueued
    • retrieved_atdatetime · nullableNew
      The date and time when the shipping rate of the shipping_line was last retrieved.
  • statusstring
    The status of the Charge.
    Possible values
    successerrorqueuedskippedrefundedpartially_refundedpending_manual_paymentpending
  • subtotal_pricestring
    The combined price of all line_items without taxes and shipping.
  • tagsstring
    A comma-separated list of tags on the Charge.
  • tax_linesarray of objects
    An array of tax lines that apply to the Charge.
    Show child attributesHide child attributes3
    • pricestring
      The total tax associated with the listed jurisdiction.
    • ratestring
      The tax rate associated with the listed jurisdiction.
    • titlestring
      The title/name of the taxing jurisdiction.
  • taxableboolean
    A boolean indicator of the taxability of the Charge.
  • taxes_includedboolean
    Whether taxes are included in the order subtotal.
  • total_discountsstring
    The sum of the Discounts applied to the Charge.
  • total_line_items_pricestring
    The total price of all line items of the Charge.
  • total_pricestring
    The sum of all the prices of all the items in the Charge, taxes and discounts included (must be positive).
  • total_refundsstring
    The sum of all refunds that were applied to the Charge.
  • total_taxstring
    The total tax due associated with the Charge.
  • total_weight_gramsinteger
    The total weight of the Charge’s line items in grams.
  • typestring
    An indicator of the Charge’s type, either checkout or recurring.
    Possible values
    checkoutrecurring
  • updated_atdatetime
    The date time at which the Charge was most recently updated.
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": [
      {
        "offer_attributes": null,
        "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",
            "unit_price": "0.870"
          },
          {
            "price": "0.270",
            "rate": 0.0225,
            "title": "Los Angeles County Tax",
            "unit_price": "0.270"
          }
        ],
        "taxable": true,
        "taxable_amount": "12.00",
        "title": "Sumatra Coffee",
        "total_price": "13.14",
        "unit_price": "12.00",
        "variant_title": "Milk - a / b"
      }
    ],
    "merged_at": null,
    "note": "next order #1",
    "order_attributes": [
      {
        "name": "custom name",
        "value": "custom value"
      }
    ],
    "original_scheduled_at": "2018-12-12",
    "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": "active",
        "retrieved_at": null
      }
    ],
    "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_duties": "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

GET/charges/{id}
Retrieve a Charge using the charge_id.
Scoperead_orders
Starting March 19th, 2025, processed charges (those where status equals success, refunded, or partially-refunded) that have a value for processed_at greater than 90 days in the past will no longer appear in responses. As a result, you may receive an error.

Charge data processed over 90 days ago will remain available through the Exports tool in the Recharge merchant portal and within the Merchant portal UI.

Example of unaffected API calls:
[RETRIEVE A CHARGE] /charges/{id} (if it's a charge that does not have a processed_at date or the processed_at date is within the last 90 days)

Example of API calls that will result in an error:
[RETRIEVE A CHARGE] /charges/{id} (if it's a charge with a processed_at date older than 90 days)

Query parameters

  • includestringNew
    A comma-separated list of related resources to return under the include attribute of the Charge. Each value also requires the read scope of the included resource (credit_projection requires read_credit_summary).
    Possible values
    addressbundle_selectionscharge_activitiescredit_projectioncustomermetafieldsorder_modificationspayment_methodssubscriptionstransactions
GET/charges/{id}
curl 'https://api.rechargeapps.com/charges/377749210' \
  -H 'X-Recharge-Version: v2' \
  -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": [
      {
        "offer_attributes": null,
        "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"
      }
    ],
    "merged_at": null,
    "note": "next order in sequence 3",
    "order_attributes": [
      {
        "name": "Checkout-Method",
        "value": "delivery"
      }
    ],
    "orders_count": 1,
    "original_scheduled_at": "2021-12-09",
    "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": "active",
        "retrieved_at": null
      }
    ],
    "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_duties": "0.00",
    "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

GET/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
Scoperead_orders
Starting March 19th, 2025, processed charges (those where status equals success, refunded, or partially- refunded) that have a value for processed_at greater than 90 days in the past will no longer appear in responses. As a result, you may receive a partial data set or an empty list.

Charge data processed over 90 days ago will remain available through the Exports tool in the Recharge merchant portal and within the Merchant portal UI.

Examples of unaffected API calls:
[LIST CHARGES] /charges?status=queued
[LIST CHARGES] /charges?status=error

Examples of API calls that may return partial results:
[LIST CHARGES] /charges?processed_at_min=2024-01-01 (this would only return results that have a processed_at date in the last 90 days)
[LIST CHARGES] /charges?status=success,queued (this would return all queued charges but only return success charges that have a processed_at date in the last 90 days)

Example of API calls that will result in an empty list:
[LIST CHARGES] /charges?processed_at_max=2024-01-01 (any date over 90 days old)

Reminder: returned charges are sorted ascending by id value by default.

When ids is passed, all other filters, sorting and pagination parameters are ignored, and a maximum of 250 IDs is accepted.

Query parameters

  • address_idstring
    Filter Charges by Address.
  • created_at_maxstring
    Show Charges created before the given date.
  • created_at_minstring
    Show Charges created after the given date.
  • cursorstringNew
    The next_cursor or previous_cursor value returned by a previous call, used to retrieve the next or previous page of results. When passed, the only other parameter that can be passed is limit.
  • customer_emailstringNew
    Filter Charges by the email address of the Customer.
  • customer_idstring
    Filter Charges by Customer.
  • discount_codestring
    List Charges that contain the given discount_code.
  • discount_idstring
    List Charges that contain the given discount_id.
  • error_typestringNew
    Filter Charges in error status by a comma-separated list of error types, such as CARD_DECLINED. Requires status to include error.
  • external_order_idstring
    Filter Charges by the associated order ID in the external e-commerce platform.
  • external_product_idsstringNew
    Filter Charges by a comma-separated list of product IDs, as they appear in the external e-commerce platform, contained in the Charge.
  • external_variant_idsstringNew
    Filter Charges by a comma-separated list of variant IDs, as they appear in the external e-commerce platform, contained in the Charge.
  • idsstring
    Filter Charges by ID.
    If passing multiple values, must be comma separated. Non-integer values will result in a 422 error.
  • includestringNew
    A comma-separated list of related resources to return under the include attribute of each Charge. Each value also requires the read scope of the included resource.
    Possible values
    addressbundle_selectionscharge_activitiescustomermetafieldsorder_modificationspayment_methodssubscriptionstransactions
  • limitstring
    The amount of results.
    Default 50Maximum 250
  • not_error_typestringNew
    Exclude Charges whose error_type matches one of the given comma-separated values. Only Charges that have an error_type are returned.
  • pagestringDeprecated
    The page to show.
    Default 1
    Page-based pagination has been deprecated but still available to use for pages up to a 100. If you need data past this point, use cursor pagination.
  • purchase_item_idstring
    Filter Charges by a Subscription or Onetime ID.
  • purchase_item_idsstring
    Filter Charges by a comma-separated list of Subscription or Onetime IDs.
  • scheduled_atstring
    Filter Charges by specific scheduled charge date.
  • scheduled_at_maxstring
    Show Charges scheduled to be processed before the given date.
  • scheduled_at_minstring
    Show Charges scheduled to be processed after the given date.
  • sort_bystring
    Sort listed Charges in a specific order.
    Available sort options: id-asc, id-desc, updated_at-asc, updated_at-desc, scheduled_at-asc, scheduled_at-desc.
    Possible values
    id-ascid-desccreated_at-asccreated_at-descupdated_at-ascupdated_at-descscheduled_at-ascscheduled_at-desc
  • statusstring
    Filter charges by status.
    Available status: success, queued, error, refunded, partially_refunded, skipped, pending_manual_payment, pending.
    Possible values
    successqueuederrorrefundedpartially_refundedskippedpending_manual_paymentpending_manual_payment_overduepending
  • updated_at_maxstring
    Show charges updated before the given date.
  • updated_at_minstring
    Show charges updated after the given date.
  • processed_at_minstring
    Show charges processed after, and including, the given date.
  • processed_at_maxstring
    Show charges processed before, and including, the given date.
GET/charges
curl 'https://api.rechargeapps.com/charges?limit=3' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token'
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": [
        {
          "offer_attributes": null,
          "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"
        }
      ],
      "merged_at": null,
      "note": "next order in sequence 3",
      "order_attributes": [
        {
          "name": "Checkout-Method",
          "value": "delivery"
        }
      ],
      "orders_count": 1,
      "original_scheduled_at": "2021-12-09",
      "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": "active",
          "retrieved_at": null
        }
      ],
      "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_duties": "0.00",
      "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

POST/charges/{id}/apply_discount
Endpoint for adding Discount to an existing queued Charge.
Scopewrite_orders
You cannot add a Discount to an existing queued Charge if the Charge or the associated Address already has one.

You can provide either discount_id or discount_code. If both parameters are passed, the value for discount_id will take precedence.

If a Charge has a Discount and it gets updated, or a regeneration occurs, the Discount will be lost. Regeneration is a process that refreshes the Charge JSON with new data in the case of the Subscription or Address being updated.

Body parameters

  • discount_codestring
    Code of the Discount you want to apply to a Charge.
  • discount_idinteger
    ID of the Discount you want to apply to a Charge.

Response attributes

  • idinteger
    Unique numeric identifier for the Address.
  • payment_method_idinteger
    Unique numeric identifier for the Payment Method associated to the Address.
  • address1string
    The street associated with the Address.
  • address2string
    Any additional information associated with the Address.
  • citystring
    The city associated with the address.
  • companystring
    The company associated with the address.
  • country_codestring
    2-letter country code.
  • customer_idinteger
    Unique numeric identifier for the customer associated with the address.
  • discountsarray of objects
    A discount which will be applied on the address. While the discounts parameter is an array, only a single discount code will be applied. If multiple discount codes are provided, only the first discount in the array will apply to the address.
    Show child attributesHide child attributes1
    • idinteger
      The id of a discount associated with this address.
  • first_namestring
    The customer’s first name associated with the address.
  • last_namestring
    The customer’s last name associated with the address.
  • order_attributesarray of objects
    Replaces cart_attributes. Extra information that is added to the order.
    Show child attributesHide child attributes2
    • namestring
      The name for the attribute.
    • valuestring
      The value for the associated attribute.
  • order_notestring
    Notes to be added to all orders associated with the address.
  • phonestring
    The phone number associated with the address.
  • presentment_currencystringSCI
    The currency on the subscription contract in Shopify.
    Only set if the currency is different from the store-level currency. Else, will default to store-level currency.
  • provincestring
    The state or province associated with the address.
  • shipping_lines_conservedarray of objects
    Shipping rates that have previously been overridden via shipping_lines_override but are currently inactive.
    Show child attributesHide child attributes3
    • codestring
      The code of the associated shipping line.
    • pricestring
      The price (in store’s currency) of the associated shipping line.
    • titlestring
      The title of the associated shipping line.
  • shipping_lines_overridearray of objects
    Used when shipping rates need to be overridden.
    If this parameter has value null, rates will be fetched when Charge is created or regenerated
    Show child attributesHide child attributes3
    • codestring
      The code of the associated shipping line.
    • pricestring
      The price (in store’s currency) of the associated shipping line.
    • titlestring
      The title of the associated shipping line.
  • zipstring
    The zip or postal code associated with the address.
  • created_atdatetime
    The date and time when the address was created.
  • updated_atdatetime
    The date and time when the address was last updated.
POST/charges/{id}/apply_discount
curl -X POST 'https://api.rechargeapps.com/charges/105805051/apply_discount' \
  -H 'Content-Type: application/json' \
  -H 'X-Recharge-Version: v2' \
  -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": [
      {
        "offer_attributes": null,
        "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"
      }
    ],
    "merged_at": null,
    "note": "next order in sequence 3",
    "order_attributes": [
      {
        "name": "Checkout-Method",
        "value": "delivery"
      }
    ],
    "orders_count": 1,
    "original_scheduled_at": "2021-12-09",
    "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": "active",
        "retrieved_at": null
      }
    ],
    "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_duties": "0.00",
    "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

POST/charges/{id}/remove_discount
Remove a Discount from a Charge without destroying the Discount.

HTTP request examples

POST /charges/<charge_id>/remove_discount/
Scopewrite_orders
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.

Response attributes

  • idinteger
    Unique numeric identifier for the Address.
  • payment_method_idinteger
    Unique numeric identifier for the Payment Method associated to the Address.
  • address1string
    The street associated with the Address.
  • address2string
    Any additional information associated with the Address.
  • citystring
    The city associated with the address.
  • companystring
    The company associated with the address.
  • country_codestring
    2-letter country code.
  • customer_idinteger
    Unique numeric identifier for the customer associated with the address.
  • discountsarray of objects
    A discount which will be applied on the address. While the discounts parameter is an array, only a single discount code will be applied. If multiple discount codes are provided, only the first discount in the array will apply to the address.
    Show child attributesHide child attributes1
    • idinteger
      The id of a discount associated with this address.
  • first_namestring
    The customer’s first name associated with the address.
  • last_namestring
    The customer’s last name associated with the address.
  • order_attributesarray of objects
    Replaces cart_attributes. Extra information that is added to the order.
    Show child attributesHide child attributes2
    • namestring
      The name for the attribute.
    • valuestring
      The value for the associated attribute.
  • order_notestring
    Notes to be added to all orders associated with the address.
  • phonestring
    The phone number associated with the address.
  • presentment_currencystringSCI
    The currency on the subscription contract in Shopify.
    Only set if the currency is different from the store-level currency. Else, will default to store-level currency.
  • provincestring
    The state or province associated with the address.
  • shipping_lines_conservedarray of objects
    Shipping rates that have previously been overridden via shipping_lines_override but are currently inactive.
    Show child attributesHide child attributes3
    • codestring
      The code of the associated shipping line.
    • pricestring
      The price (in store’s currency) of the associated shipping line.
    • titlestring
      The title of the associated shipping line.
  • shipping_lines_overridearray of objects
    Used when shipping rates need to be overridden.
    If this parameter has value null, rates will be fetched when Charge is created or regenerated
    Show child attributesHide child attributes3
    • codestring
      The code of the associated shipping line.
    • pricestring
      The price (in store’s currency) of the associated shipping line.
    • titlestring
      The title of the associated shipping line.
  • zipstring
    The zip or postal code associated with the address.
  • created_atdatetime
    The date and time when the address was created.
  • updated_atdatetime
    The date and time when the address was last updated.
POST/charges/{id}/remove_discount
curl -X POST 'https://api.rechargeapps.com/charges/459904607/remove_discount' \
  -H 'Content-Type: application/json' \
  -H 'X-Recharge-Version: v2' \
  -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": [
      {
        "offer_attributes": null,
        "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"
      }
    ],
    "merged_at": null,
    "note": "next order in sequence 3",
    "order_attributes": [
      {
        "name": "Checkout-Method",
        "value": "delivery"
      }
    ],
    "orders_count": 1,
    "original_scheduled_at": "2021-12-09",
    "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": "active",
        "retrieved_at": null
      }
    ],
    "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_duties": "0.00",
    "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

POST/charges/{id}/skip
Skip a Charge.
Scopewrite_orders
Exactly one of purchase_item_ids or purchase_item_id must be provided. Only Charges with a status of queued or error can be skipped.

Query parameters

  • commitbooleanNew
    If set to false, the remaining queued Charge is regenerated asynchronously instead of before the response is returned. Defaults to true.
  • update_membership_expires_atbooleanNew
    If set to true, the expiration date of the Membership associated with the Charge is moved to the new charge date. Defaults to false.

Body parameters

  • purchase_item_idsarrayNew
    A list of the Subscription or Onetime IDs to skip on the Charge.
  • purchase_item_idintegerNew
    The ID of a single Subscription or Onetime to skip on the Charge. Cannot be passed together with purchase_item_ids.
POST/charges/{id}/skip
curl -X POST 'https://api.rechargeapps.com/charges/377749210/skip' \
  -H 'X-Recharge-Version: v2' \
  -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": [
      {
        "offer_attributes": null,
        "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"
      }
    ],
    "merged_at": null,
    "note": "next order in sequence 3",
    "order_attributes": [
      {
        "name": "Checkout-Method",
        "value": "delivery"
      }
    ],
    "orders_count": 1,
    "original_scheduled_at": "2021-12-09",
    "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": "active",
        "retrieved_at": null
      }
    ],
    "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_duties": "0.00",
    "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

POST/charges/{id}/unskip
Unskip a Charge.
Scopewrite_orders
Exactly one of purchase_item_ids or purchase_item_id must be provided. Only Charges with a status of skipped whose scheduled date is not more than one day in the past can be unskipped.

Query parameters

  • update_membership_expires_atbooleanNew
    If set to true, the expiration date of the Membership associated with the Charge is moved to the new charge date. Defaults to false.

Body parameters

  • purchase_item_idsarrayNew
    A list of the Subscription or Onetime IDs to unskip on the Charge.
  • purchase_item_idintegerNew
    The ID of a single Subscription or Onetime to unskip on the Charge. Cannot be passed together with purchase_item_ids.

Response attributes

POST/charges/{id}/unskip
curl -X POST 'https://api.rechargeapps.com/charges/377749210/unskip' \
  -H 'X-Recharge-Version: v2' \
  -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": [
      {
        "offer_attributes": null,
        "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"
      }
    ],
    "merged_at": null,
    "note": "next order in sequence 3",
    "order_attributes": [
      {
        "name": "Checkout-Method",
        "value": "delivery"
      }
    ],
    "orders_count": 1,
    "original_scheduled_at": "2021-12-09",
    "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": "active",
        "retrieved_at": null
      }
    ],
    "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_duties": "0.00",
    "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

POST/charges/{id}/refund
BigCommerceCustomRCS
Refund a Charge.
Scopeswrite_orderswrite_payments
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.

At least one of amount, full_refund or line_items must be provided. Either the write_orders or the write_payments scope is sufficient.

Body parameters

  • amountfloat
    Amount of money that will be refunded. It can be fully or partially refunded.
  • full_refundboolean
    If this parameter has value true, the Charge will be totally refunded.
  • retryboolean
    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”.
  • errorstring
    The error message to store on the Charge. If the retry parameter has value true, this value is required.
  • error_typestring
    If the retry parameter has value true, this value is required.
    Possible values
    insufficient_inventorybc_rejected
  • line_itemsarray of objectsNew
    A list of the line items to refund. Cannot be passed together with amount. If passed with full_refund, all line items of the Charge must be listed with their full quantities.
    Show child attributesHide child attributes22 new
    • purchase_item_idintegerNew
      The Subscription or Onetime ID of the line item to refund. Required for each line item.
    • quantityintegerNew
      The quantity of the line item to refund. Must be at least 1. Required for each line item.
POST/charges/{id}/refund
curl -X POST 'https://api.rechargeapps.com/charges/377749210/refund' \
  -H 'X-Recharge-Version: v2' \
  -H 'Content-Type: application/json' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -d '{
  "amount": 11
}'
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": [
      {
        "offer_attributes": null,
        "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"
      }
    ],
    "merged_at": null,
    "note": "next order in sequence 3",
    "order_attributes": [
      {
        "name": "Checkout-Method",
        "value": "delivery"
      }
    ],
    "orders_count": 1,
    "original_scheduled_at": "2021-12-09",
    "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": "active",
        "retrieved_at": null
      }
    ],
    "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_duties": "0.00",
    "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

POST/charges/{id}/process
Plus plan
The charge processing route can be used to process Charges that are in a queued or error status.
Scopewrite_payments
The /charges/{id}/process endpoint is available to Recharge Plus 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 Plus.

Body parameters

  • custom_gatewayobjectNew
    The outcome of a payment taken outside of Recharge. Must be passed, and can only be passed, when the Charge uses a payment method with a custom payment gateway.
    Only for Charges whose payment method uses a custom payment gateway.
    Show child attributesHide child attributes44 new
    • external_statusstringNew
      The result of the external payment. Required when custom_gateway is passed.
      Possible values
      successerror
    • external_transaction_idstringNew
      The ID of the transaction in the external payment system. Required when external_status is success.
    • external_error_typestringNew
      The structured reason why the external payment failed, such as CARD_DECLINED. Must be a valid Charge error type. Required when external_status is error and not allowed when it is success.
    • external_error_messagestringNew
      The error message returned by the external payment system. Required when external_status is error and not allowed when it is success.
RelatedCharges FAQ →
POST/charges/{id}/process
curl -X POST 'https://api.rechargeapps.com/charges/100714428/process' \
  -H 'X-Recharge-Version: v2' \
  -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": [
      {
        "offer_attributes": null,
        "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"
      }
    ],
    "merged_at": null,
    "note": "next order in sequence 3",
    "order_attributes": [
      {
        "name": "Checkout-Method",
        "value": "delivery"
      }
    ],
    "orders_count": 1,
    "original_scheduled_at": "2021-12-09",
    "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": "active",
        "retrieved_at": null
      }
    ],
    "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_duties": "0.00",
    "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

POST/charges/{id}/capture_payment
Plus planBeta
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.
Scopeswrite_paymentswrite_orderswrite_subscriptionswrite_customers
The /charges/{id}/capture_payment endpoint is available to Recharge Plus 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 Plus.

All four scopes are required.

Response attributes

POST/charges/{id}/capture_payment
curl -X POST '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": [
      {
        "offer_attributes": null,
        "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"
      }
    ],
    "merged_at": null,
    "note": "next order in sequence 3",
    "order_attributes": [
      {
        "name": "Checkout-Method",
        "value": "delivery"
      }
    ],
    "orders_count": 1,
    "original_scheduled_at": "2021-12-09",
    "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": "active",
        "retrieved_at": null
      }
    ],
    "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_duties": "0.00",
    "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"
  }
}

#Add a free gift

POST/charges/{id}/add_free_gift
Endpoint for adding Free Gift to an existing queued Charge.
Scopeswrite_orderswrite_free_gifts
You can provide external_variant_id to add to the Charge.

A successful request returns a 201 status code. free_gifts[].quantity must be at least 1, and the Charge must have a status of queued or error.

Body parameters

  • free_giftsarray of objectsRequired
    List of Free Gifts you want to add to a Charge.
    Show child attributesHide child attributes2
    • external_variant_idstring
      ID of the Variant you want to add to a Charge.
    • quantityintegerRequired
      Quantity of the Free Gift you want to add to a Charge.
  • conserve_on_skipboolean
    Whether to conserve the Free Gift on a skipped charge.

Response attributes

  • errorstring
    Error message
  • messagestring
    Details about the error
POST/charges/{id}/add_free_gift
curl -X POST 'https://api.rechargeapps.com/charges/105805051/add_free_gift' \
  -H 'Content-Type: application/json' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -d '{
  "free_gifts": [
    {
      "external_variant_id": "1234567890",
      "quantity": 1
    }
  ],
  "conserve_on_skip": true
}'
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": [
      {
        "offer_attributes": null,
        "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"
      },
      {
        "purchase_item_id": null,
        "external_product_id": {
          "ecommerce": "6791118553225"
        },
        "external_variant_id": {
          "ecommerce": "39940738482313"
        },
        "grams": null,
        "handle": null,
        "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"
        },
        "offer_attributes": null,
        "original_price": "0.00",
        "properties": [
          {
            "name": "source",
            "value": "gift:API:RequestId:self.request_id,"
          }
        ],
        "purchase_item_type": null,
        "quantity": 1,
        "sku": null,
        "tax_due": "0.00",
        "tax_lines": [],
        "taxable": false,
        "taxable_amount": "0.00",
        "title": "Free Gift",
        "total_price": "0.00",
        "unit_price": "0.00",
        "unit_price_includes_tax": false,
        "variant_title": "Free Gift Title"
      }
    ],
    "merged_at": null,
    "note": "next order in sequence 3",
    "order_attributes": [
      {
        "name": "Checkout-Method",
        "value": "delivery"
      }
    ],
    "orders_count": 1,
    "original_scheduled_at": "2021-12-09",
    "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": "active",
        "retrieved_at": null
      }
    ],
    "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_duties": "0.00",
    "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 free gift

POST/charges/{id}/remove_free_gift
Endpoint for removing a free gift from an existing queued Charge.
Scopeswrite_orderswrite_free_gifts
You can provide external_variant_ids to remove from the Charge.

Body parameters

  • external_variant_idsarray
    List of ExternalVariant IDs of free gifts you want to remove from a Charge.
POST/charges/{id}/remove_free_gift
curl -X POST 'https://api.rechargeapps.com/charges/105805051/remove_free_gift' \
  -H 'Content-Type: application/json' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -d '{
  "external_variant_ids": [
    "1234567890"
  ]
}'
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": [
      {
        "offer_attributes": null,
        "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"
      }
    ],
    "merged_at": null,
    "note": "next order in sequence 3",
    "order_attributes": [
      {
        "name": "Checkout-Method",
        "value": "delivery"
      }
    ],
    "orders_count": 1,
    "original_scheduled_at": "2021-12-09",
    "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": "active",
        "retrieved_at": null
      }
    ],
    "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_duties": "0.00",
    "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"
  }
}