Core Resources

Checkouts

Plus planBigCommerceCustom

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

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

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

88 additions in V2, marked New

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

Endpoints

POST/checkouts
GET/checkouts/{token}
PUT/checkouts/{token}
GET/checkouts/{token}/shipping_rates
POST/checkouts/{token}/process
GET/checkouts/{token}/line_items
POST/checkouts/{token}/line_items
PUT/checkouts/{token}/line_items
DELETE/checkouts/{token}/line_items
GET/checkouts/{token}/line_items/{line_item_id}
PUT/checkouts/{token}/line_items/{line_item_id}
DELETE/checkouts/{token}/line_items/{line_item_id}
POST/checkouts/import

#The checkout object

Plus planBigCommerceCustom

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

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

Attributes

charge_idinteger
ID for the Charge resulting from processing the Checkout.
analytics_dataobject
Urchin Tracking Module (UTM) parameters are used for online marketing campaigns.
Show child attributesHide child attributes1
- utm_paramsarray of objects
  An array containing utm_param objects.
  Show child attributesHide child attributes7
  - utm_campaignstring
    The UTM campaign.
  - utm_contentstring
    The UTM content.
  - utm_data_sourcestring
    The source of the campaign parameter.
  - utm_sourcestring
    The UTM source.
  - utm_mediumstring
    The UTM medium.
  - utm_termstring
    The UTM term.
  - utm_timestampstring
    The UTM timestamp.
applied_discountsarray of objects
Discount details, populated once the Discount has been applied successfully to the Checkout.
Show child attributesHide child attributes6
- amountstring
  Financial amount of the Discount applied.
- applicableboolean
  Whether the Discount can be applied to the Checkout.
- discount_codestring
  The code for the Discount, e.g. 25_PERCENT_OFF.
- non_redeemable_reasonstring
  Reason why the Discount could not be redeemed, if applicable.
- valuestring
  The value of the Discount, used in combination with value_type to determine the amount.
- value_typestring
  The way the Discount amount is calculated.
  Possible values
  fixed_amountshipping
applied_shipping_rateobject
Shipping rates details, populated once the rates have been selected and applied successfully to the Checkout.
Show child attributesHide child attributes104 new
- checkoutobject
  Price details from the Checkout.
  Show child attributesHide child attributes3
  - subtotal_pricestring
    Price excluding shipping and tax, including discounts.
  - total_pricestring
    Total price including tax and shipping cost for that particular shipping rate.
  - total_taxstring
    Total tax value for the checkout.
- codestring
  Code corresponding to the category of shipping.
- delivery_rangearray
- descriptionstring
- handlestring
  Unique string identifying the shipping/
- namestring
- phone_requiredboolean
  Whether a phone is required for this shipping.
- pricestring
  Price of shipping.
- tax_linesarray of objectsNew
  An array of tax_line objects for the tax charged on the shipping rate.
  Show child attributesHide child attributes33 new
  - pricestringNew
    The total tax associated with the listed jurisdiction.
  - ratestringNew
    The tax rate associated with the listed jurisdiction.
  - titlestringNew
    The title/name of the taxing jurisdiction.
- titlestring
available_shipping_ratesarray of objects
Shipping rates available for the shipping address provided in the Checkout.
Checkout object must contain the shipping_address before the available_shipping_rates are populated.
Show child attributesHide child attributes104 new
- checkoutobject
  Price details from the Checkout.
  Show child attributesHide child attributes3
  - subtotal_pricestring
    Price excluding shipping and tax, including discounts.
  - total_pricestring
    Total price including tax and shipping cost for that particular shipping rate.
  - total_taxstring
    Total tax value for the checkout.
- codestring
  Code corresponding to the category of shipping.
- delivery_rangearray
- descriptionstring
- handlestring
  Unique string identifying the shipping/
- namestring
- phone_requiredboolean
  Whether a phone is required for this shipping.
- pricestring
  Price of shipping.
- tax_linesarray of objectsNew
  An array of tax_line objects for the tax charged on the shipping rate.
  Show child attributesHide child attributes33 new
  - pricestringNew
    The total tax associated with the listed jurisdiction.
  - ratestringNew
    The tax rate associated with the listed jurisdiction.
  - titlestringNew
    The title/name of the taxing jurisdiction.
- titlestring
billing_addressobject
Billing Address for the Checkout.
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.
completed_atdatetime
Timestamp for when the Checkout was processed.
custom_shipping_rate_optionsarray of objectsNew
Custom shipping rates that were supplied for the Checkout and can be selected with applied_shipping_rate.
Show child attributesHide child attributes44 new
- codestringNew
  Code for the shipping rate.
- handlestringNew
  Unique identifier for the shipping rate.
- pricestringNew
  Price for the shipping rate.
- titlestringNew
  Title for the shipping rate.
paymentsarray of objectsNew
Additional payment methods, such as store credits or gift cards, that are applied to the Checkout total before the main payment method is charged.
Only present when additional payment methods were supplied on the Checkout.
Show child attributesHide child attributes66 new
- payment_typestringNew
  The type of the additional payment method. Store credits are returned as STORED_VALUE.
- payment_processorstringNew
  The processor of the additional payment method, e.g. recharge_credits for store credits.
- payment_tokenstringNew
  The token identifying the payment method. For store credits this is the ID of the credit account; for a gift card it is the gift card code.
- authorization_tokenstringNew
  The authorization token supplied for the payment method.
  Only present when it was provided.
- amount_appliedstringNew
  The amount from this payment method that is applied to the Checkout total.
- amount_availablestringNew
  The balance available on the payment method. For store credits this is the balance remaining after amount_applied.
created_atdatetime
Timestamp for when the Checkout was created.
currencystring
Currency of the Checkout.
emailstring
Email address for the Customer.
external_checkout_idstring
External checkout reference, if one exists.
external_checkout_sourcestring
External checkout platform, if one exists.
Possible values
big_commerceheadlessmagentoshopify
external_customer_idobject
External customer reference, if one exists.
Show child attributesHide child attributes21 new
- ecommercestring
  The customer ID as it appears in the external e-commerce platform.
- payment_processorstring · nullableNew
  The customer ID as it appears in the payment processor, populated once the Checkout has been processed.
external_transaction_idobject
The ID of the associated transaction in a payment processor system (like Stripe).
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 items included in the Checkout
quantity and external_variant_id are required parameters in line_items.
Show child attributesHide child attributes234 new
- idinteger
  Unique identifier of the line_item.
- external_inventory_policystringNew
  The inventory policy configured for the store that applies to the line_item.
  Possible values
  bypassdecrement_ignoring_policydecrement_obeying_policy
- external_line_item_idobjectNew
  An object containing the ID of the line item as it appears in the external system.
  Only present when an external_line_item_id was provided for the line_item.
  Show child attributesHide child attributes11 new
  - ecommercestringNew
    The line item ID as it appears in the external e-commerce platform.
    Only present when an external_line_item_id was provided for 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.
- handlestring
  A unique, human-friendly string for the Product associated with the line_item.
- imagesobject
  An object containing URLs of the Product image.
  Show child attributesHide child attributes1
  - smallstring
- propertiesarray
  An array of name-value pairs of additional custom line_item attributes.
- purchase_item_idinteger
  The Subscription or Onetime ID associated with the line_item.
- purchase_item_typestring
  The type of the purchase applied to the item.
  Possible values
  onetimesubscription
- quantityinteger
  The quantity of the item being purchased.
- recurring_unit_pricestring
  The price of a single unit of the Product associated with the line_item that will be charged in recurring orders.
- requires_shippingboolean
  Whether the item requires shipping.
- skustring
  The SKU (stock keeping unit) of the Product associated with the line_item.
- subscription_preferencesobject
  An object containing the various subscription preferences associated with the line_item.
  Show child attributesHide child attributes8
  - charge_interval_frequencyinteger
    Frequency at which the subscriber will be charged.
  - cutoff_day_of_monthinteger
    Day of the month the plan should be charged
    Only valid for interval_unit:month
  - cutoff_day_of_weekinteger
    Day of the month the plan should be charged
    Only valid for interval_unit:week
  - expire_after_specific_number_of_chargesinteger
    A maximum number of charges on which the subscription should appear before automatic cancellation.
  - order_day_of_monthinteger
    Day of the month an order should be generated when the customer is subscribed.
  - order_day_of_weekinteger
    Day of the week an order should be generated when the customer is subscribed.
  - order_interval_frequencyinteger
    Frequency at which the subscriber will receive shipments when subscribed to this plan.
  - interval_unitstring
    The unit applied to charge_interval_frequency and order_interval_frequency.
    Possible values
    dayweekmonth
    All plans for a Product must have the same interval_unit.
- tax_linesarray of objects
  An array of tax_line objects associated with the 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 for a single unit of the line_item for the listed jurisdiction.
- taxableboolean
  Whether tax is to be applied to the line_item
- titlestring
  The title of the Product associated with the line_item.
- total_pricestring
  The total price of the line_item including tax.
- unit_pricestring
  The price of a single unit of the Product associated with the line_item.
- variant_titlestring
  The title of the Product variant associated with the line_item.
- weightinteger
  The weight of a single unit of the line_item, in grams.
- weight_unitstring
  The weight unit configured for the store. weight is always expressed in grams regardless of this value.
  Possible values
  lbozkggt
notestring
Custom note.
notification_preferencesobject
Notification preferences for the Customer.
Show child attributesHide child attributes2
- emailobject
  Details of a customer's notifications preferences for emails.
  Show child attributesHide child attributes3
  - promotionalobject
    Details of a customer's notifications preferences for promotional communication on this channel.
    Show child attributesHide child attributes5
    last_opt_in_atdatetime
    The timestamp marking the last time the user opted in for the notification channel and type.
    null if the person never opted in.
    last_opt_in_sourcestring
    Details of the source interface or process of the last opt in.
    Possible values
    apibulk_updateconciergecustomer_portalcustomer_smsmerchant_portalrecharge_checkoutrechargesms_appsci_cartscriptshopify_checkoutsms_reminderstore_opt_in_widgetsubscription_checkout_extensionthank_you_page
    null if the person never opted in.
    last_opt_out_atdatetime
    The timestamp marking the last time the user opted out for the notification channel and type.
    null if the person never opted out.
    last_opt_out_sourcestring
    Details of the source interface or process of the last opt in.
    Possible values
    apibulk_updateconciergecustomer_portalcustomer_smsmerchant_portalrecharge_checkoutrechargesms_appsci_cartscriptshopify_checkoutsms_reminderstore_opt_in_widgetsubscription_checkout_extensionthank_you_page
    null if the person never opted in.
    statusstring
    Status of the notification preferences.
    Possible values
    accepteddeclined
    Default unspecified
  - replenishmentobject
    Details of a customer's notifications preferences for replenishment communication on this channel.
    Show child attributesHide child attributes5
    last_opt_in_atdatetime
    The timestamp marking the last time the user opted in for the notification channel and type.
    null if the person never opted in.
    last_opt_in_sourcestring
    Details of the source interface or process of the last opt in.
    Possible values
    apibulk_updateconciergecustomer_portalcustomer_smsmerchant_portalrecharge_checkoutrechargesms_appsci_cartscriptshopify_checkoutsms_reminderstore_opt_in_widgetsubscription_checkout_extensionthank_you_page
    null if the person never opted in.
    last_opt_out_atdatetime
    The timestamp marking the last time the user opted out for the notification channel and type.
    null if the person never opted out.
    last_opt_out_sourcestring
    Details of the source interface or process of the last opt in.
    Possible values
    apibulk_updateconciergecustomer_portalcustomer_smsmerchant_portalrecharge_checkoutrechargesms_appsci_cartscriptshopify_checkoutsms_reminderstore_opt_in_widgetsubscription_checkout_extensionthank_you_page
    null if the person never opted in.
    statusstring
    Status of the notification preferences.
    Possible values
    accepteddeclined
    Default unspecified
  - transactionalobject
    Details of a customer's notifications preferences for transactional communication on this channel.
    Show child attributesHide child attributes5
    last_opt_in_atdatetime
    The timestamp marking the last time the user opted in for the notification channel and type.
    null if the person never opted in.
    last_opt_in_sourcestring
    Details of the source interface or process of the last opt in.
    Possible values
    apibulk_updateconciergecustomer_portalcustomer_smsmerchant_portalrecharge_checkoutrechargesms_appsci_cartscriptshopify_checkoutsms_reminderstore_opt_in_widgetsubscription_checkout_extensionthank_you_page
    null if the person never opted in.
    last_opt_out_atdatetime
    The timestamp marking the last time the user opted out for the notification channel and type.
    null if the person never opted out.
    last_opt_out_sourcestring
    Details of the source interface or process of the last opt in.
    Possible values
    apibulk_updateconciergecustomer_portalcustomer_smsmerchant_portalrecharge_checkoutrechargesms_appsci_cartscriptshopify_checkoutsms_reminderstore_opt_in_widgetsubscription_checkout_extensionthank_you_page
    null if the person never opted in.
    statusstring
    Status of the notification preferences.
    Possible values
    accepteddeclined
    Default unspecified
- smsobject
  Details of a customer's notifications preferences for sms.
  Show child attributesHide child attributes3
  - promotionalobject
    Details of a customer's notifications preferences for promotional communication on this channel.
    Show child attributesHide child attributes5
    last_opt_in_atdatetime
    The timestamp marking the last time the user opted in for the notification channel and type.
    null if the person never opted in.
    last_opt_in_sourcestring
    Details of the source interface or process of the last opt in.
    Possible values
    apibulk_updateconciergecustomer_portalcustomer_smsmerchant_portalrecharge_checkoutrechargesms_appsci_cartscriptshopify_checkoutsms_reminderstore_opt_in_widgetsubscription_checkout_extensionthank_you_page
    null if the person never opted in.
    last_opt_out_atdatetime
    The timestamp marking the last time the user opted out for the notification channel and type.
    null if the person never opted out.
    last_opt_out_sourcestring
    Details of the source interface or process of the last opt in.
    Possible values
    apibulk_updateconciergecustomer_portalcustomer_smsmerchant_portalrecharge_checkoutrechargesms_appsci_cartscriptshopify_checkoutsms_reminderstore_opt_in_widgetsubscription_checkout_extensionthank_you_page
    null if the person never opted in.
    statusstring
    Status of the notification preferences.
    Possible values
    accepteddeclined
    Default unspecified
  - replenishmentobject
    Details of a customer's notifications preferences for replenishment communication on this channel.
    Show child attributesHide child attributes5
    last_opt_in_atdatetime
    The timestamp marking the last time the user opted in for the notification channel and type.
    null if the person never opted in.
    last_opt_in_sourcestring
    Details of the source interface or process of the last opt in.
    Possible values
    apibulk_updateconciergecustomer_portalcustomer_smsmerchant_portalrecharge_checkoutrechargesms_appsci_cartscriptshopify_checkoutsms_reminderstore_opt_in_widgetsubscription_checkout_extensionthank_you_page
    null if the person never opted in.
    last_opt_out_atdatetime
    The timestamp marking the last time the user opted out for the notification channel and type.
    null if the person never opted out.
    last_opt_out_sourcestring
    Details of the source interface or process of the last opt in.
    Possible values
    apibulk_updateconciergecustomer_portalcustomer_smsmerchant_portalrecharge_checkoutrechargesms_appsci_cartscriptshopify_checkoutsms_reminderstore_opt_in_widgetsubscription_checkout_extensionthank_you_page
    null if the person never opted in.
    statusstring
    Status of the notification preferences.
    Possible values
    accepteddeclined
    Default unspecified
  - transactionalobject
    Details of a customer's notifications preferences for transactional communication on this channel.
    Show child attributesHide child attributes5
    last_opt_in_atdatetime
    The timestamp marking the last time the user opted in for the notification channel and type.
    null if the person never opted in.
    last_opt_in_sourcestring
    Details of the source interface or process of the last opt in.
    Possible values
    apibulk_updateconciergecustomer_portalcustomer_smsmerchant_portalrecharge_checkoutrechargesms_appsci_cartscriptshopify_checkoutsms_reminderstore_opt_in_widgetsubscription_checkout_extensionthank_you_page
    null if the person never opted in.
    last_opt_out_atdatetime
    The timestamp marking the last time the user opted out for the notification channel and type.
    null if the person never opted out.
    last_opt_out_sourcestring
    Details of the source interface or process of the last opt in.
    Possible values
    apibulk_updateconciergecustomer_portalcustomer_smsmerchant_portalrecharge_checkoutrechargesms_appsci_cartscriptshopify_checkoutsms_reminderstore_opt_in_widgetsubscription_checkout_extensionthank_you_page
    null if the person never opted in.
    statusstring
    Status of the notification preferences.
    Possible values
    accepteddeclined
    Default unspecified
order_attributesarray of objects
List of name-value pairs for custom attributes.
Show child attributesHide child attributes2
- namestring
  The name for the attribute.
- valuestring
  The value for the associated attribute.
payment_processorstring
Name of the payment processor.
requires_shippingboolean
Whether or not the Checkout contains items that require shipping.
shipping_addressobject
Shipping Address for the Checkout.
Show child attributesHide child attributes111 new
- 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.
- shipping_lines_overridearrayNew
  Shipping lines that will be set as the shipping lines override of the Address created when the Checkout is processed.
  Only present when it was provided on the Checkout.
- zipstring
  The zip code or postcode of the address.
shipping_linesarray of objects
Details of shipping rate, cost...
Show child attributesHide child attributes710 new
- codestringNew
  The code associated with the shipping_line.
- pricestringNew
  The price of the shipping_line.
- ratestringNew
  The rate of the shipping_line.
  Only present when a rate was supplied for the shipping line, which is only possible when the Checkout was imported.
- sourcestringNew
  The source of the shipping_line.
  Only present when a source was supplied for the shipping line, which is only possible when the Checkout was imported.
- tax_linesarray of objectsNew
  An array of tax lines associated with the shipping_line.
  Show child attributesHide child attributes33 new
  - pricestringNew
    The total tax associated with the listed jurisdiction.
  - ratestringNew
    The tax rate associated with the listed jurisdiction.
  - titlestringNew
    The title/name of the taxing jurisdiction.
- taxablebooleanNew
  Whether tax was charged on the shipping_line.
- titlestringNew
  The title of the shipping_line.
subtotal_pricestring
Value of the Checkout minus shipping and tax.
tax_linesarray of objects
Array of tax_line objects.
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
Whether the existing Customer matching the Checkout email is subject to tax. false when that Customer is tax exempt, or when no Customer exists yet for the email.
taxes_includedboolean
Whether the tax is included in the price of the items.
tokenstring
Unique token for the Checkout.
total_pricestring
Full price of the Checkout including shipping and tax.
total_taxstring
Tax charged on the Checkout.
updated_atdatetime
Timestamp for the latest Checkout update.

The checkout object

{
  "checkout": {
    "charge_id": null,
    "analytics_data": {
      "utm_params": [
        {
          "utm_campaign": "spring_sale",
          "utm_content": "textlink",
          "utm_data_source": "cookie",
          "utm_medium": "cpc",
          "utm_source": "google",
          "utm_term": "mleko",
          "utm_timestamp": "2020-03-05T00:00:00+00:00"
        }
      ]
    },
    "applied_discounts": [
      {
        "amount": "5.00",
        "applicable": true,
        "discount_code": "5_DOLLARS_OFF",
        "non_redeemable_reason": null,
        "value": "5.00",
        "value_type": "fixed_amount"
      }
    ],
    "applied_shipping_rate": {
      "checkout": {
        "subtotal_price": null,
        "total_price": null,
        "total_tax": null
      },
      "code": "Flat rate (3 - 7 Business Days)",
      "delivery_range": null,
      "description": null,
      "handle": "recharge-Flat%20rate%20%283%20-%207%20Business%20Days%29-7.49",
      "name": "Flat rate (3 - 7 Business Days)",
      "phone_required": null,
      "price": "7.49",
      "tax_lines": [],
      "title": "Flat rate (3 - 7 Business Days)"
    },
    "available_shipping_rates": [
      {
        "checkout": {
          "subtotal_price": null,
          "total_price": null,
          "total_tax": null
        },
        "code": "Flat rate (3 - 7 Business Days)",
        "delivery_range": null,
        "description": null,
        "handle": "recharge-Flat%20rate%20%283%20-%207%20Business%20Days%29-7.49",
        "name": "Flat rate (3 - 7 Business Days)",
        "phone_required": null,
        "price": "7.49",
        "tax_lines": [],
        "title": "Flat rate (3 - 7 Business Days)"
      },
      {
        "checkout": {
          "subtotal_price": null,
          "total_price": null,
          "total_tax": null
        },
        "code": "3 Days (3 Business Days)",
        "delivery_range": null,
        "description": null,
        "handle": "recharge-3%20Days%20%283%20Business%20Days%29-11.75",
        "name": "3 Days (3 Business Days)",
        "phone_required": null,
        "price": "11.75",
        "tax_lines": [],
        "title": "3 Days (3 Business Days)"
      }
    ],
    "billing_address": {
      "address1": "6419 Ocean Front Walk",
      "address2": "Apt 2",
      "city": "Los Angeles",
      "company": null,
      "country_code": "US",
      "first_name": "Novak",
      "last_name": "Djokovic",
      "phone": "1-800-800-8000",
      "province": "California",
      "zip": "90293"
    },
    "completed_at": null,
    "created_at": "2021-11-16T00:51:28+00:00",
    "currency": "USD",
    "custom_shipping_rate_options": [],
    "email": "somerandomemail@test.com",
    "external_checkout_id": "<external_cart_id>",
    "external_checkout_source": "custom",
    "external_customer_id": {
      "ecommerce": null,
      "payment_processor": null
    },
    "external_transaction_id": {
      "payment_processor": null
    },
    "line_items": [
      {
        "id": 0,
        "external_inventory_policy": "decrement_obeying_policy",
        "external_product_id": {
          "ecommerce": "12345"
        },
        "external_variant_id": {
          "ecommerce": "123456"
        },
        "handle": "shirt-with-design",
        "images": {
          "small": "https://veryniceimage.jpg"
        },
        "properties": [
          {}
        ],
        "purchase_item_type": "onetime",
        "quantity": 3,
        "recurring_unit_price": "12.00",
        "requires_shipping": true,
        "sku": null,
        "subscription_preferences": {
          "charge_delay": null,
          "charge_interval_frequency": null,
          "charge_on_day_of_month": null,
          "charge_on_day_of_week": null,
          "number_charges_until_expiration": null,
          "shipping_interval_frequency": null,
          "shipping_interval_unit_type": null
        },
        "tax_lines": [],
        "taxable": false,
        "title": "A Nice Shirt",
        "total_price": "36.00",
        "unit_price": "12.00",
        "variant_title": null,
        "weight": 340,
        "weight_unit": "g"
      }
    ],
    "note": "flash sale",
    "notification_preferences": {
      "email": {
        "promotional": {
          "last_opt_in_at": null,
          "last_opt_in_source": null,
          "last_opt_out_at": null,
          "last_opt_out_source": null,
          "status": "unspecified"
        },
        "replenishment": {
          "last_opt_in_at": null,
          "last_opt_in_source": null,
          "last_opt_out_at": null,
          "last_opt_out_source": null,
          "status": "unspecified"
        },
        "transactional": {
          "last_opt_in_at": null,
          "last_opt_in_source": null,
          "last_opt_out_at": null,
          "last_opt_out_source": null,
          "status": "unspecified"
        }
      },
      "sms": {
        "promotional": {
          "last_opt_in_at": null,
          "last_opt_in_source": null,
          "last_opt_out_at": null,
          "last_opt_out_source": null,
          "status": "unspecified"
        },
        "replenishment": {
          "last_opt_in_at": null,
          "last_opt_in_source": null,
          "last_opt_out_at": null,
          "last_opt_out_source": null,
          "status": "unspecified"
        },
        "transactional": {
          "last_opt_in_at": null,
          "last_opt_in_source": null,
          "last_opt_out_at": null,
          "last_opt_out_source": null,
          "status": "unspecified"
        }
      }
    },
    "order_attributes": {
      "customer_niceness": "very"
    },
    "payment_processor": null,
    "requires_shipping": true,
    "shipping_address": {
      "address1": "6419 Ocean Front Walk",
      "address2": "Apt 2",
      "city": "Los Angeles",
      "company": null,
      "country_code": "US",
      "first_name": "Novak",
      "last_name": "Djokovic",
      "phone": "1-800-800-8000",
      "province": "California",
      "zip": "90293"
    },
    "shipping_lines": [
      {
        "code": "Flat rate (3 - 7 Business Days)",
        "price": "7.49",
        "tax_lines": [],
        "taxable": false,
        "title": "Flat rate (3 - 7 Business Days)"
      }
    ],
    "subtotal_price": "31.00",
    "tax_lines": [],
    "taxable": false,
    "taxes_included": false,
    "token": "efd5a6b12b984f439ec16ce2a00fb5c3",
    "total_price": "31.00",
    "total_tax": "0.00",
    "updated_at": "2021-11-16T00:51:28+00:00"
  }
}

#Create a checkout

POST/checkouts

Plus planBigCommerceCustom

Create a Checkout

Scopewrite_checkouts

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

Returns 201. The body can be sent with or without the checkout root key. For BigCommerce stores each line item must also include external_product_id, title and unit_price. A line item is created as a subscription when subscription_preferences.order_interval_frequency is set, otherwise as a one-time.

Query parameters

get_shipping_ratesboolean
If specified as a query parameter, shipping rates will be retrieved and will allow providing applied_shipping_rate upon checkout creation.
partial_shippingbooleanNew
When set to true, shipping address validation is reduced so that only the country and zip are required, e.g. for the partial addresses provided by wallet payments. In this mode the country must be sent as shipping_address.country (full country name) instead of shipping_address.country_code.

Body parameters

analytics_dataobject
Urchin Tracking Module (UTM) parameters are used for online marketing campaigns.
Show child attributesHide child attributes1
- utm_paramsarray of objects
  An array containing utm_param objects.
  Show child attributesHide child attributes7
  - utm_campaignstring
    The UTM campaign.
  - utm_contentstring
    The UTM content.
  - utm_data_sourcestringRequired
    The source of the campaign parameter.
  - utm_sourcestring
    The UTM source.
  - utm_mediumstring
    The UTM medium.
  - utm_termstring
    The UTM term.
  - utm_timestampstringRequired
    The UTM timestamp.
applied_discountsarray of objects
Discount to apply to the Checkout.
Show child attributesHide child attributes1
- discount_codestring
  The code for the Discount, e.g. 25_PERCENT_OFF.
applied_shipping_rateobject
Shipping rates details, populated once the rates have been selected and applied successfully to the Checkout.
Important: You can only create a checkout with applied_shipping_rate if you pass the query parameter get_shipping_rates=true or if you supply a list of shipping rates using custom_shipping_rate_options.
Show child attributesHide child attributes1
- handlestring
  Unique identifier for the shipping rate that should be applied.
custom_shipping_rate_optionsarray of objects
List of available shipping rates to use when selecting a shipping rate with applied_shipping_rate. Custom shipping rates will take precedence over any default rates fetched using get_shipping_rates=true.
Show child attributesHide child attributes4
- codestringRequired
  Code for the shipping rate.
- pricestringRequired
  Price for the shipping rate.
- titlestringRequired
  Title for the shipping rate.
- handlestringRequired
  Unique identifier for the shipping rate.
billing_addressobject
Billing Address for the Checkout.
Show child attributesHide child attributes10
- address1stringRequired
  Line one of the billing address.
- address2string
  Line two of the billing address.
- citystringRequired
  The city of the billing address.
- companystring
  The company name of the billing address.
- country_codestringRequired
  2-letter country code.
- first_namestring
  The first name of the billing address.
- last_namestringRequired
  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.
currencystring
Currency of the Checkout.
emailstring
Email address for the Customer.
external_checkout_idstring
External checkout reference, if one exists.
external_checkout_sourcestring
External checkout platform, if one exists.
Possible values
big_commerceheadlessmagentoshopify
line_itemsarray of objectsRequired
A list of items included in the Checkout
quantity and external_variant_id are required parameters in line_items.
Show child attributesHide child attributes165 new
- external_line_item_idobjectNew
  An object containing the ID of the line item as it appears in the external system.
  Show child attributesHide child attributes11 new
  - ecommercestringNew
    The line item ID as it appears in the external e-commerce platform.
- external_product_idobject
  An object containing the associated product ID as it appears in the external system.
  Show child attributesHide child attributes1
  - ecommercestringRequired
    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_idobjectRequired
  An object containing the associated variant ID as it appears in the external system.
  Show child attributesHide child attributes1
  - ecommercestringRequired
    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.
- 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.
- 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.
- quantityintegerRequired
  The quantity of the line_item.
- recurring_unit_pricestringNew
  The price of a single unit of the line_item that will be charged on recurring orders. Only applies to subscription line items and defaults to unit_price.
- requires_shippingbooleanNew
  Whether the item requires shipping. Defaults to the value of the product in the catalog.
- skustring
  The SKU (stock keeping unit) of the Product associated with the line_item.
- subscription_preferencesobject
  An object containing the various subscription preferences associated with the line_item.
  required if the purchase_item_type is subscription.
  Show child attributesHide child attributes8
  - charge_interval_frequencyinteger
    Frequency at which the subscriber will be charged.
  - cutoff_day_of_monthinteger
    Day of the month the plan should be charged
    Only valid for interval_unit:month
  - cutoff_day_of_weekinteger
    Day of the month the plan should be charged
    Only valid for interval_unit:week
  - expire_after_specific_number_of_chargesinteger
    A maximum number of charges on which the subscription should appear before automatic cancellation.
  - order_day_of_monthinteger
    Day of the month an order should be generated when the customer is subscribed.
  - order_day_of_weekinteger
    Day of the week an order should be generated when the customer is subscribed.
  - order_interval_frequencyinteger
    Frequency at which the subscriber will receive shipments when subscribed to this plan.
  - interval_unitstring
    The unit applied to charge_interval_frequency and order_interval_frequency.
    Possible values
    dayweekmonth
    All plans for a Product must have the same interval_unit.
- taxablebooleanNew
  Whether tax is to be applied to the line_item.
  Only used for BigCommerce stores. For other stores the value always comes from the product in the catalog.
- titlestring
  The title of the Product of this line_item.
- unit_pricestring
  The unit price of the line_item.
- variant_titlestring
  The title of the Product variant associated with the line_item.
- weightinteger
  The total weight of the line_item.
notestring
Custom note.
order_attributesarray of objects
List of name-value pairs for custom attributes.
Show child attributesHide child attributes2
- namestring
  The name for the attribute.
- valuestring
  The value for the associated attribute.
paymentsarray of objectsNew
Additional payment methods, such as store credits or gift cards, to apply to the Checkout total before the main payment method is charged. Duplicate entries are rejected.
Requires store credits or gift cards to be enabled for the store.
Show child attributesHide child attributes44 new
- payment_typestringRequiredNew
  The type of the additional payment method: stored_value for store credits or gift_card for a gift card.
- payment_processorstringRequiredNew
  The processor of the additional payment method. Must be recharge_credits when payment_type is stored_value and rise.ai when it is gift_card.
- payment_tokenstringRequiredNew
  The token identifying the payment method. For store credits this is the ID of the credit account; for a gift card it is the gift card code.
- authorization_tokenstringNew
  An authorization token for the payment method.
shipping_addressobject
Shipping Address for the Checkout.
Show child attributesHide child attributes111 new
- address1stringRequired
  Line one of the billing address.
- address2string
  Line two of the billing address.
- citystringRequired
  The city of the billing address.
- companystring
  The company name of the billing address.
- country_codestringRequired
  2-letter country code.
- first_namestring
  The first name of the billing address.
- last_namestringRequired
  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.
- shipping_lines_overridearrayNew
  Shipping lines to set as the shipping lines override of the Address created when the Checkout is processed.
- zipstring
  The zip code or postcode of the address.

POST/checkouts

curl -X POST 'https://api.rechargeapps.com/checkouts' \
  -H 'Content-Type: application/json' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -H 'X-Recharge-Version: v2' \
  -d '{
  "analytics_data": {
    "utm_params": [
      {
        "utm_campaign": "spring_sale",
        "utm_content": "textlink",
        "utm_data_source": "shopify_cookie",
        "utm_medium": "cpc",
        "utm_source": "google",
        "utm_term": "mleko",
        "utm_timestamp": "2020-03-05T00:00:00"
      }
    ]
  },
  "applied_discounts": [
    {
      "discount_code": "5_DOLLARS_OFF"
    }
  ],
  "billing_address": {
    "address1": "6419 Ocean Front Walk",
    "address2": "Apt 2",
    "city": "Los Angeles",
    "company": "",
    "country_code": "US",
    "first_name": "Novak",
    "last_name": "Djokovic",
    "phone": "1-800-800-8000",
    "province": "California",
    "zip": "90293"
  },
  "email": "somerandomemail@test.com",
  "external_checkout_id": "<external_cart_id>",
  "external_checkout_source": "custom",
  "line_items": [
    {
      "external_product_id": {
        "ecommerce": "12345"
      },
      "external_variant_id": {
        "ecommerce": "123456"
      },
      "handle": "shirt-with-design",
      "images": {
        "small": "http://small.jpg"
      },
      "properties": [
        {
          "name": "size",
          "value": "xl"
        },
        {
          "name": "color",
          "value": "fuchsia"
        }
      ],
      "quantity": 3,
      "subscription_preferences": {
        "charge_interval_frequency": null,
        "cutoff_day_of_month": null,
        "cutoff_day_of_week": null,
        "expire_after_specific_number_of_charges": null,
        "interval_unit": null,
        "order_day_of_month": null,
        "order_day_of_week": null,
        "order_interval_frequency": null
      },
      "tax_lines": [
        {
          "price": "0.950",
          "rate": 0.0725,
          "title": "CA State Tax"
        }
      ]
    }
  ],
  "note": "flash sale",
  "order_attributes": {
    "customer_niceness": "very"
  },
  "shipping_address": {
    "address1": "6419 Ocean Front Walk",
    "address2": "Apt 2",
    "city": "Los Angeles",
    "company": "",
    "country_code": "US",
    "first_name": "Novak",
    "last_name": "Djokovic",
    "phone": "1-800-800-8000",
    "province": "California",
    "zip": "90293"
  }
}'

Response

{
  "checkout": {
    "charge_id": null,
    "analytics_data": {
      "utm_params": [
        {
          "utm_campaign": "spring_sale",
          "utm_content": "textlink",
          "utm_data_source": "shopify_cookie",
          "utm_medium": "cpc",
          "utm_source": "google",
          "utm_term": "mleko",
          "utm_timestamp": "2020-03-05T00:00:00+00:00"
        }
      ]
    },
    "applied_discounts": [
      {
        "amount": "5.00",
        "applicable": true,
        "discount_code": "5_DOLLARS_OFF",
        "non_redeemable_reason": null,
        "value": "5.00",
        "value_type": "fixed_amount"
      }
    ],
    "billing_address": {
      "address1": "6419 Ocean Front Walk",
      "address2": "Apt 2",
      "city": "Los Angeles",
      "company": null,
      "country_code": "US",
      "first_name": "Novak",
      "last_name": "Djokovic",
      "phone": "1-800-800-8000",
      "province": "California",
      "zip": "90293"
    },
    "completed_at": null,
    "created_at": "2021-11-16T00:51:28+00:00",
    "currency": "USD",
    "custom_shipping_rate_options": [],
    "email": "somerandomemail@test.com",
    "external_checkout_id": "f71848585658686-36f6-d9efg8125rogkfdaa",
    "external_checkout_source": "custom",
    "external_customer_id": {
      "ecommerce": null,
      "payment_processor": null
    },
    "external_transaction_id": {
      "payment_processor": null
    },
    "line_items": [
      {
        "id": null,
        "external_inventory_policy": "decrement_obeying_policy",
        "external_product_id": {
          "ecommerce": "12345"
        },
        "external_variant_id": {
          "ecommerce": "123456"
        },
        "handle": "shirt-with-design",
        "images": {
          "small": "http://small.jpg"
        },
        "properties": [
          {},
          {}
        ],
        "purchase_item_type": "onetime",
        "quantity": 3,
        "requires_shipping": true,
        "sku": null,
        "subscription_preferences": {
          "charge_interval_frequency": null,
          "cutoff_day_of_month": null,
          "cutoff_day_of_week": null,
          "expire_after_specific_number_of_charges": null,
          "interval_unit": null,
          "order_day_of_month": null,
          "order_day_of_week": null,
          "order_interval_frequency": null
        },
        "tax_lines": [],
        "taxable": false,
        "title": "A Very Nice Shirt",
        "total_price": "36.00",
        "unit_price": "12.00",
        "variant_title": null,
        "weight": 340,
        "weight_unit": "g"
      }
    ],
    "note": "flash sale",
    "notification_preferences": {
      "email": {
        "promotional": {
          "last_opt_in_at": null,
          "last_opt_in_source": null,
          "last_opt_out_at": null,
          "last_opt_out_source": null,
          "status": "unspecified"
        },
        "replenishment": {
          "last_opt_in_at": null,
          "last_opt_in_source": null,
          "last_opt_out_at": null,
          "last_opt_out_source": null,
          "status": "unspecified"
        },
        "transactional": {
          "last_opt_in_at": null,
          "last_opt_in_source": null,
          "last_opt_out_at": null,
          "last_opt_out_source": null,
          "status": "unspecified"
        }
      },
      "sms": {
        "promotional": {
          "last_opt_in_at": null,
          "last_opt_in_source": null,
          "last_opt_out_at": null,
          "last_opt_out_source": null,
          "status": "unspecified"
        },
        "replenishment": {
          "last_opt_in_at": null,
          "last_opt_in_source": null,
          "last_opt_out_at": null,
          "last_opt_out_source": null,
          "status": "unspecified"
        },
        "transactional": {
          "last_opt_in_at": null,
          "last_opt_in_source": null,
          "last_opt_out_at": null,
          "last_opt_out_source": null,
          "status": "unspecified"
        }
      }
    },
    "order_attributes": {
      "customer_niceness": "very"
    },
    "payment_processor": null,
    "requires_shipping": true,
    "shipping_address": {
      "address1": "6419 Ocean Front Walk",
      "address2": "Apt 2",
      "city": "Los Angeles",
      "company": null,
      "country_code": "US",
      "first_name": "Novak",
      "last_name": "Djokovic",
      "phone": "1-800-800-8000",
      "province": "California",
      "zip": "90293"
    },
    "subtotal_price": "31.00",
    "tax_lines": [],
    "taxable": false,
    "taxes_included": false,
    "token": "efd5a6b12b984f439ec16ce2a00fb5c3",
    "total_price": "31.00",
    "total_tax": "0.00",
    "updated_at": "2021-11-16T00:51:28+00:00"
  }
}

#Retrieve a checkout

GET/checkouts/{token}

Plus planBigCommerceCustom

Retrieve a checkout.

Scoperead_checkouts

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

Returns 404 for a Checkout that was created more than 180 days ago.

GET/checkouts/{token}

curl 'https://api.rechargeapps.com/checkouts/6a7c36a1213a4d7fb746e6588fa55005' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -H 'X-Recharge-Version: v2'

Response

{
  "checkout": {
    "charge_id": null,
    "analytics_data": {
      "utm_params": [
        {
          "utm_campaign": "spring_sale",
          "utm_content": "textlink",
          "utm_data_source": "shopify_cookie",
          "utm_medium": "cpc",
          "utm_source": "google",
          "utm_term": "mleko",
          "utm_timestamp": "2020-03-05T00:00:00+00:00"
        }
      ]
    },
    "applied_discounts": [
      {
        "amount": "5.00",
        "applicable": true,
        "discount_code": "5_DOLLARS_OFF",
        "non_redeemable_reason": null,
        "value": "5.00",
        "value_type": "fixed_amount"
      }
    ],
    "applied_shipping_rate": {
      "checkout": {
        "subtotal_price": null,
        "total_price": null,
        "total_tax": null
      },
      "code": "3 Days (3 Business Days)",
      "delivery_range": null,
      "description": null,
      "handle": "recharge-3%20Days%20%283%20Business%20Days%29-11.75",
      "name": "3 Days (3 Business Days)",
      "phone_required": null,
      "price": "11.75",
      "tax_lines": [],
      "title": "3 Days (3 Business Days)"
    },
    "available_shipping_rates": [
      {
        "checkout": {
          "subtotal_price": null,
          "total_price": null,
          "total_tax": null
        },
        "code": "Flat rate (3 - 7 Business Days)",
        "delivery_range": null,
        "description": null,
        "handle": "recharge-Flat%20rate%20%283%20-%207%20Business%20Days%29-7.49",
        "name": "Flat rate (3 - 7 Business Days)",
        "phone_required": null,
        "price": "7.49",
        "tax_lines": [],
        "title": "Flat rate (3 - 7 Business Days)"
      },
      {
        "checkout": {
          "subtotal_price": null,
          "total_price": null,
          "total_tax": null
        },
        "code": "3 Days (3 Business Days)",
        "delivery_range": null,
        "description": null,
        "handle": "recharge-3%20Days%20%283%20Business%20Days%29-11.75",
        "name": "3 Days (3 Business Days)",
        "phone_required": null,
        "price": "11.75",
        "tax_lines": [],
        "title": "3 Days (3 Business Days)"
      }
    ],
    "billing_address": {
      "address1": "6419 Ocean Front Walk",
      "address2": "Apt 2",
      "city": "Los Angeles",
      "company": null,
      "country_code": "US",
      "first_name": "Novak",
      "last_name": "Djokovic",
      "phone": "1-800-800-8000",
      "province": "California",
      "zip": "90293"
    },
    "completed_at": null,
    "created_at": "2021-11-16T00:51:28+00:00",
    "currency": "USD",
    "custom_shipping_rate_options": [],
    "email": "somerandomemail@test.com",
    "external_checkout_id": "<external_cart_id>",
    "external_checkout_source": "headless",
    "external_customer_id": {
      "ecommerce": null,
      "payment_processor": null
    },
    "external_transaction_id": {
      "payment_processor": null
    },
    "line_items": [
      {
        "id": null,
        "external_inventory_policy": "decrement_obeying_policy",
        "external_product_id": {
          "ecommerce": "12345"
        },
        "external_variant_id": {
          "ecommerce": "123456"
        },
        "handle": "shirt-with-design",
        "images": {
          "small": "http://small.jpg"
        },
        "properties": [
          {}
        ],
        "purchase_item_type": "onetime",
        "quantity": 3,
        "requires_shipping": true,
        "sku": null,
        "subscription_preferences": {
          "charge_interval_frequency": null,
          "cutoff_day_of_month": null,
          "cutoff_day_of_week": null,
          "expire_after_specific_number_of_charges": null,
          "interval_unit": null,
          "order_day_of_month": null,
          "order_day_of_week": null,
          "order_interval_frequency": null
        },
        "tax_lines": [],
        "taxable": false,
        "title": "A Very Nice Shirt",
        "total_price": "36.00",
        "unit_price": "12.00",
        "variant_title": null,
        "weight": 340,
        "weight_unit": "g"
      }
    ],
    "note": "flash sale",
    "notification_preferences": {
      "email": {
        "promotional": {
          "last_opt_in_at": null,
          "last_opt_in_source": null,
          "last_opt_out_at": null,
          "last_opt_out_source": null,
          "status": "unspecified"
        },
        "replenishment": {
          "last_opt_in_at": null,
          "last_opt_in_source": null,
          "last_opt_out_at": null,
          "last_opt_out_source": null,
          "status": "unspecified"
        },
        "transactional": {
          "last_opt_in_at": null,
          "last_opt_in_source": null,
          "last_opt_out_at": null,
          "last_opt_out_source": null,
          "status": "unspecified"
        }
      },
      "sms": {
        "promotional": {
          "last_opt_in_at": null,
          "last_opt_in_source": null,
          "last_opt_out_at": null,
          "last_opt_out_source": null,
          "status": "unspecified"
        },
        "replenishment": {
          "last_opt_in_at": null,
          "last_opt_in_source": null,
          "last_opt_out_at": null,
          "last_opt_out_source": null,
          "status": "unspecified"
        },
        "transactional": {
          "last_opt_in_at": null,
          "last_opt_in_source": null,
          "last_opt_out_at": null,
          "last_opt_out_source": null,
          "status": "unspecified"
        }
      }
    },
    "order_attributes": {
      "customer_niceness": "very"
    },
    "payment_processor": null,
    "requires_shipping": true,
    "shipping_address": {
      "address1": "6419 Ocean Front Walk",
      "address2": "Apt 2",
      "city": "Los Angeles",
      "company": null,
      "country_code": "US",
      "first_name": "Novak",
      "last_name": "Djokovic",
      "phone": "1-800-800-8000",
      "province": "California",
      "zip": "90293"
    },
    "subtotal_price": "31.00",
    "tax_lines": [],
    "taxable": false,
    "taxes_included": false,
    "token": "efd5a6b12b984f439ec16ce2a00fb5c3",
    "total_price": "31.00",
    "total_tax": "0.00",
    "updated_at": "2021-11-16T00:51:28+00:00"
  }
}

#Update a checkout

PUT/checkouts/{token}

Plus planBigCommerceCustom

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

Scopewrite_checkouts

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

A Checkout that has already been processed cannot be updated (422). Sending line_items replaces the full list of line items. Only applied_shipping_rate.handle is needed to select a shipping rate; the rate details are taken from the available or custom shipping rates.

Query parameters

get_shipping_ratesboolean
If specified as a query parameter, shipping rates will be retrieved and will allow providing applied_shipping_rate upon checkout update.
partial_shippingbooleanNew
When set to true, shipping address validation is reduced so that only the country and zip are required, e.g. for the partial addresses provided by wallet payments. In this mode the country must be sent as shipping_address.country (full country name) instead of shipping_address.country_code.

Body parameters

analytics_dataobject
Urchin Tracking Module (UTM) parameters are used for online marketing campaigns.
Show child attributesHide child attributes1
- utm_paramsarray of objects
  An array containing utm_param objects.
  Show child attributesHide child attributes7
  - utm_campaignstring
    The UTM campaign.
  - utm_contentstring
    The UTM content.
  - utm_data_sourcestringRequired
    The source of the campaign parameter.
  - utm_sourcestring
    The UTM source.
  - utm_mediumstring
    The UTM medium.
  - utm_termstring
    The UTM term.
  - utm_timestampstringRequired
    The UTM timestamp.
applied_discountsarray of objectsNew
Discount to apply to the Checkout. Send an empty array to remove the applied discount.
Show child attributesHide child attributes11 new
- discount_codestringNew
  The code for the Discount, e.g. 25_PERCENT_OFF.
applied_shipping_rateobject
Shipping rates details, populated once the rates have been selected and applied successfully to the Checkout.
Important: You can only set applied_shipping_rate if you have already collected the available_shipping_rates by calling GET /checkout/<checkout_token>/shipping_rates or if you pass the query parameter get_shipping_rates=true when calling this route.

code, price and title are required when setting a custom shipping rate
Show child attributesHide child attributes8
- codestring
  Code corresponding to the category of shipping.
- delivery_rangestring
- descriptionstring
- handlestring
  Unique string identifying the shipping/
- namestring
- phone_requiredstring
  Whether a phone is required for this shipping.
- pricestring
  Price of shipping.
- titlestring
billing_addressobject
Billing address for the checkout.
Show child attributesHide child attributes10
- address1stringRequired
  Line one of the billing address.
- address2string
  Line two of the billing address.
- citystringRequired
  The city of the billing address.
- companystring
  The company name of the billing address.
- country_codestringRequired
  2-letter country code.
- first_namestring
  The first name of the billing address.
- last_namestringRequired
  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.
custom_shipping_rate_optionsarray of objectsNew
List of available shipping rates to use when selecting a shipping rate with applied_shipping_rate.
Show child attributesHide child attributes44 new
- codestringRequiredNew
  Code for the shipping rate.
- pricestringRequiredNew
  Price for the shipping rate.
- titlestringRequiredNew
  Title for the shipping rate.
- handlestringRequiredNew
  Unique identifier for the shipping rate.
currencystring
Currency of the Checkout.
emailstring
Email address for the customer.
external_checkout_idstring
Represents the external cart token.
external_checkout_sourcestring
Represents the source for external_checkout_id.
Possible values
big_commerceheadlessmagentoshopify
line_itemsarray of objects
A list of items included in the Checkout. quantity and external_variant_id are required for each line item. The list replaces all existing line items.
Show child attributesHide child attributes165 new
- external_line_item_idobjectNew
  An object containing the ID of the line item as it appears in the external system.
  Show child attributesHide child attributes11 new
  - ecommercestringNew
    The line item ID as it appears in the external e-commerce platform.
- external_product_idobject
  An object containing the associated product ID as it appears in the external system.
  Show child attributesHide child attributes1
  - ecommercestringRequired
    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_idobjectRequired
  An object containing the associated variant ID as it appears in the external system.
  Show child attributesHide child attributes1
  - ecommercestringRequired
    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.
- 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.
- 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.
- quantityintegerRequired
  The quantity of the line_item.
- recurring_unit_pricestringNew
  The price of a single unit of the line_item that will be charged on recurring orders. Only applies to subscription line items and defaults to unit_price.
- requires_shippingbooleanNew
  Whether the item requires shipping. Defaults to the value of the product in the catalog.
- skustring
  The SKU (stock keeping unit) of the Product associated with the line_item.
- subscription_preferencesobject
  An object containing the various subscription preferences associated with the line_item.
  required if the purchase_item_type is subscription.
  Show child attributesHide child attributes8
  - charge_interval_frequencyinteger
    Frequency at which the subscriber will be charged.
  - cutoff_day_of_monthinteger
    Day of the month the plan should be charged
    Only valid for interval_unit:month
  - cutoff_day_of_weekinteger
    Day of the month the plan should be charged
    Only valid for interval_unit:week
  - expire_after_specific_number_of_chargesinteger
    A maximum number of charges on which the subscription should appear before automatic cancellation.
  - order_day_of_monthinteger
    Day of the month an order should be generated when the customer is subscribed.
  - order_day_of_weekinteger
    Day of the week an order should be generated when the customer is subscribed.
  - order_interval_frequencyinteger
    Frequency at which the subscriber will receive shipments when subscribed to this plan.
  - interval_unitstring
    The unit applied to charge_interval_frequency and order_interval_frequency.
    Possible values
    dayweekmonth
    All plans for a Product must have the same interval_unit.
- taxablebooleanNew
  Whether tax is to be applied to the line_item.
  Only used for BigCommerce stores. For other stores the value always comes from the product in the catalog.
- titlestring
  The title of the Product of this line_item.
- unit_pricestring
  The unit price of the line_item.
- variant_titlestring
  The name of a variant of the Product of this line_item.
- weightinteger
  The total weight in grams of the line_item.
notestring
Note attribute used to store custom notes.
order_attributesarray of objects
Structured custom notes.
Show child attributesHide child attributes2
- namestring
  The name for the attribute.
- valuestring
  The value for the associated attribute.
paymentsarray of objectsNew
Additional payment methods, such as store credits or gift cards, to apply to the Checkout total before the main payment method is charged. Duplicate entries are rejected.
Requires store credits or gift cards to be enabled for the store.
Show child attributesHide child attributes44 new
- payment_typestringRequiredNew
  The type of the additional payment method: stored_value for store credits or gift_card for a gift card.
- payment_processorstringRequiredNew
  The processor of the additional payment method. Must be recharge_credits when payment_type is stored_value and rise.ai when it is gift_card.
- payment_tokenstringRequiredNew
  The token identifying the payment method. For store credits this is the ID of the credit account; for a gift card it is the gift card code.
- authorization_tokenstringNew
  An authorization token for the payment method.
shipping_addressobject
Shipping address for the checkout.
When using mobile payment options, insufficient shipping address data is available until payment intent, which causes validation errors when updating the checkout object.

Related guides: Checkout mobile payment
Show child attributesHide child attributes111 new
- address1stringRequired
  Line one of the billing address.
- address2string
  Line two of the billing address.
- citystringRequired
  The city of the billing address.
- companystring
  The company name of the billing address.
- country_codestringRequired
  2-letter country code.
- first_namestring
  The first name of the billing address.
- last_namestringRequired
  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.
- shipping_lines_overridearrayNew
  Shipping lines to set as the shipping lines override of the Address created when the Checkout is processed.
- zipstring
  The zip code or postcode of the address.

PUT/checkouts/{token}

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

Response

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

#Retrieve shipping rates

GET/checkouts/{token}/shipping_rates

Plus planBigCommerceCustom

You can retrieve all shipping rates for a specific checkout.

Scoperead_checkouts

The list is returned under the available_shipping_rates root key. A shipping_address must be set on the Checkout before shipping rates can be retrieved (422 otherwise).

Response attributes

checkoutobject
Price details from the Checkout.
Show child attributesHide child attributes3
- subtotal_pricestring
  Price excluding shipping and tax, including discounts.
- total_pricestring
  Total price including tax and shipping cost for that particular shipping rate.
- total_taxstring
  Total tax value for the checkout.
codestring
Code corresponding to the category of shipping.
delivery_rangestring
descriptionstring
handlestring
Unique string identifying the shipping/
namestring
phone_requiredstring
Whether a phone is required for this shipping.
pricestring
Price of shipping.
titlestring

GET/checkouts/{token}/shipping_rates

curl 'https://api.rechargeapps.com/checkouts/6a7c36a1213a4d7fb746e6588fa55005/shipping_rates' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -H 'X-Recharge-Version: v2'

Response

{
  "shipping_rates": [
    {
      "checkout": {
        "subtotal_price": "22.50",
        "total_price": "42.40",
        "total_tax": "0.00"
      },
      "code": "Standard",
      "delivery_range": null,
      "description": null,
      "handle": "shopify-Standard-19.90",
      "name": "Standard",
      "phone_required": false,
      "price": "19.90",
      "title": "Standard"
    }
  ]
}

#Process a checkout

POST/checkouts/{token}/process

Plus planBigCommerceCustom

You can process and charge checkout using our API.

Scopewrite_checkouts

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

We support Stripe, Apple Pay, Google Pay, and Braintree as payment processor.

If you are using test stripe keys, you can use tok_visa as your token.

Related guides: Mobile payments

Returns 201 with a checkout_charge object containing charge_id, status (successful or requires_authentication), payment_processor, payment_processor_transaction_id, processor_payment_method_token, processor_customer_token, payment_type, free and authorization_token. The Checkout must have an email, a shipping_address and at least one line item.

Body parameters

authorization_tokenstringNew
Token of a payment authorization that was already created with the payment processor (for example a Stripe intent ID) and should be confirmed instead of creating a new payment.
enable_upsell_opportunitybooleanNew
Whether to hold the payment as an authorization so that post-purchase upsell items can be added before it is captured.
Only has an effect when the store's payment capture is set to capture automatically after upsell.
freebooleanNew
Set to true to process the Checkout without taking a payment. payment_processor and processor_payment_method_token must not be sent when true.
mandate_dataobjectNew
Mandate acceptance details for bank debit payments.
Only read when the request body is wrapped in the checkout_charge root key and payment_type is SEPA_DEBIT or IDEAL.
Show child attributesHide child attributes16 new
- customer_acceptanceobjectNew
  Details of how the customer accepted the mandate.
  Only read when the request body is wrapped in the checkout_charge root key and payment_type is SEPA_DEBIT or IDEAL.
  Show child attributesHide child attributes35 new
  - typestringNew
    The type of acceptance, e.g. online. Required when customer_acceptance is sent.
    Only read when the request body is wrapped in the checkout_charge root key and payment_type is SEPA_DEBIT or IDEAL.
  - accepted_atintegerNew
    Timestamp of when the customer accepted the mandate. Required when customer_acceptance is sent.
    Only read when the request body is wrapped in the checkout_charge root key and payment_type is SEPA_DEBIT or IDEAL.
  - onlineobjectNew
    Details of an online mandate acceptance.
    Only read when the request body is wrapped in the checkout_charge root key and payment_type is SEPA_DEBIT or IDEAL.
    Show child attributesHide child attributes22 new
    ip_addressstringNew
    The IP address from which the customer accepted the mandate.
    Only read when the request body is wrapped in the checkout_charge root key and payment_type is SEPA_DEBIT or IDEAL.
    user_agentstringNew
    The user agent of the browser from which the customer accepted the mandate.
    Only read when the request body is wrapped in the checkout_charge root key and payment_type is SEPA_DEBIT or IDEAL.
payment_processorstringRequired
The name of payment processor.
Possible values
authorizebraintreestripemollie
payment_processor_return_urlstringNew
The URL the customer is returned to after authorizing the payment with their bank.
Only read when the request body is wrapped in the checkout_charge root key, payment_type is IDEAL and mandate_data is also sent.
payment_typestring
The payment type used for the Checkout.
Possible values
CREDIT_CARDPAYPALAPPLE_PAYGOOGLE_PAYSEPA_DEBITIDEALSHOP_PAYPAYPAL_EXPRESSSOFORTGIROPAYSTORED_VALUEAMAZON_PAYINVOICEAFTERPAY_CLEARPAYKLARNA
processor_customer_tokenstringNew
The ID of the customer in the payment processor.
Only used when reusing an existing payment processor customer is enabled for the store.
processor_payment_method_tokenstringNew
Payment method token from the payment processor that will be used in the transaction. Either this or authorization_token is required unless free is true.

Response attributes

charge_idstring
Unique identifier for the charge resulting from the processing of the checkout.
authorization_tokenstring
Unique identifier for the authorization of the charge.
freeboolean
Boolean to identify if the checkout was free.
payment_processorstring
Payment processor used for the checkout.
payment_typestring
Payment type used for the checkout.
processor_customer_tokenstring
Unique identifier for the customer created in the payment service provider platform (aka PSP).
processor_payment_method_tokenstring
Payment method token used for the transaction.
payment_processor_transaction_idstring
Unique transaction id used for the transaction.
statusstring
Status of the checkout

POST/checkouts/{token}/process

curl -X POST 'https://api.rechargeapps.com/checkouts/5a5c19ea31c44641855017f1276db959/process' \
  -H 'Content-Type: application/json' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -H 'X-Recharge-Version: v2' \
  -d '{
  "payment_processor": "stripe",
  "payment_token": "<payment_token>",
  "payment_type": "CREDIT_CARD"
}'

Response

{
  "checkout_charge": {
    "authorization_token": null,
    "charge_id": 258065996,
    "free": false,
    "payment_processor": "stripe",
    "processor_customer_token": "cus_HcbgqiS49fABBg62E",
    "processor_payment_method_token": "pm_lkj3lkl4lk34",
    "payment_processor_transaction_id": "ch_1H3McXJ2zdqHvZaRd191xV2idRt",
    "payment_token": "tok_visa",
    "payment_type": "CREDIT_CARD",
    "status": "successful"
  }
}

#List line items of a checkoutNew

GET/checkouts/{token}/line_items

Returns the line items of a Checkout. Each item has the same attributes as line_items on the Checkout object.

Scoperead_checkouts

GET/checkouts/{token}/line_items

curl 'https://api.rechargeapps.com/checkouts/a1b2c3d4e5f6/line_items' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token'

Response

{
  "line_items": [
    {
      "id": 1,
      "external_inventory_policy": "decrement_obeying_policy",
      "external_product_id": {
        "ecommerce": "7301234"
      },
      "external_variant_id": {
        "ecommerce": "41209876"
      },
      "handle": "morning-blend-coffee",
      "images": {
        "small": "https://cdn.example.com/products/morning-blend_small.png"
      },
      "properties": [
        {
          "name": "grind",
          "value": "whole bean"
        }
      ],
      "purchase_item_type": "subscription",
      "quantity": 2,
      "recurring_unit_price": "18.00",
      "requires_shipping": true,
      "sku": "COF-MB-12",
      "subscription_preferences": {
        "charge_interval_frequency": 1,
        "cutoff_day_of_month": null,
        "cutoff_day_of_week": null,
        "expire_after_specific_number_of_charges": null,
        "interval_unit": "month",
        "order_day_of_month": null,
        "order_day_of_week": null,
        "order_interval_frequency": 1
      },
      "tax_lines": [],
      "taxable": true,
      "title": "Morning Blend Coffee",
      "total_price": "36.00",
      "unit_price": "18.00",
      "variant_title": "12 oz",
      "weight": 340,
      "weight_unit": "g"
    }
  ]
}

#Add line items to a checkoutNew

POST/checkouts/{token}/line_items

Adds one or more line items to a Checkout and recalculates it. Accepts the same line item attributes as line_items on Create a checkout and returns all line items of the Checkout. Line item id values are positional: new items are placed first and all id values are reassigned.

Scopewrite_checkouts

Body parameters

line_itemsarray of objectsRequired
A list of line items.
Show child attributesHide child attributes12
- external_variant_idobjectRequired
  An object containing the associated variant ID as it appears in the external system.
  Show child attributesHide child attributes1
  - ecommercestringRequired
    The variant id as it appears in the external e-commerce platform.
- quantityintegerRequired
  The quantity of the line_item. Must be at least 1.
- 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.
- unit_pricestring
  The unit price of the line_item.
- recurring_unit_pricestring
  The price of a single unit of the line_item that will be charged on recurring orders. Only applies to subscription line items.
- subscription_preferencesobject
  An object containing the various subscription preferences associated with the line_item. When order_interval_frequency is set the line item is a subscription, otherwise a one-time.
  Show child attributesHide child attributes3
  - charge_interval_frequencyinteger
    Frequency at which the subscriber will be charged.
  - order_interval_frequencyinteger
    Frequency at which the subscriber will receive shipments.
  - interval_unitstring
    The unit applied to charge_interval_frequency and order_interval_frequency.
    Possible values
    dayweekmonth
- 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.
- titlestring
  The title of the Product of this line_item.
- variant_titlestring
  The title of the Product variant associated with the line_item.
- skustring
  The SKU (stock keeping unit) of the Product associated with the line_item.
- weightinteger
  The weight of a single unit of the line_item, in grams.
- requires_shippingboolean
  Whether the item requires shipping.

POST/checkouts/{token}/line_items

curl -X POST 'https://api.rechargeapps.com/checkouts/a1b2c3d4e5f6/line_items' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token'

Response

{
  "line_items": [
    {
      "id": 1,
      "external_inventory_policy": "decrement_obeying_policy",
      "external_product_id": {
        "ecommerce": "7301234"
      },
      "external_variant_id": {
        "ecommerce": "41209876"
      },
      "handle": "morning-blend-coffee",
      "images": {
        "small": "https://cdn.example.com/products/morning-blend_small.png"
      },
      "properties": [
        {
          "name": "grind",
          "value": "whole bean"
        }
      ],
      "purchase_item_type": "subscription",
      "quantity": 2,
      "recurring_unit_price": "18.00",
      "requires_shipping": true,
      "sku": "COF-MB-12",
      "subscription_preferences": {
        "charge_interval_frequency": 1,
        "cutoff_day_of_month": null,
        "cutoff_day_of_week": null,
        "expire_after_specific_number_of_charges": null,
        "interval_unit": "month",
        "order_day_of_month": null,
        "order_day_of_week": null,
        "order_interval_frequency": 1
      },
      "tax_lines": [],
      "taxable": true,
      "title": "Morning Blend Coffee",
      "total_price": "36.00",
      "unit_price": "18.00",
      "variant_title": "12 oz",
      "weight": 340,
      "weight_unit": "g"
    }
  ]
}

#Update line items of a checkoutNew

PUT/checkouts/{token}/line_items

Updates several line items of a Checkout in one request and recalculates it. Each line item is matched by its id; a 404 is returned if an id does not exist on the Checkout. Returns all line items of the Checkout.

Scopewrite_checkouts

Body parameters

line_itemsarray of objectsRequired
A list of line items.
Show child attributesHide child attributes13
- idintegerRequired
  Unique identifier of the line_item to update.
- external_variant_idobjectRequired
  An object containing the associated variant ID as it appears in the external system.
  Show child attributesHide child attributes1
  - ecommercestringRequired
    The variant id as it appears in the external e-commerce platform.
- quantityintegerRequired
  The quantity of the line_item. Must be at least 1.
- 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.
- unit_pricestring
  The unit price of the line_item.
- recurring_unit_pricestring
  The price of a single unit of the line_item that will be charged on recurring orders. Only applies to subscription line items.
- subscription_preferencesobject
  An object containing the various subscription preferences associated with the line_item. When order_interval_frequency is set the line item is a subscription, otherwise a one-time.
  Show child attributesHide child attributes3
  - charge_interval_frequencyinteger
    Frequency at which the subscriber will be charged.
  - order_interval_frequencyinteger
    Frequency at which the subscriber will receive shipments.
  - interval_unitstring
    The unit applied to charge_interval_frequency and order_interval_frequency.
    Possible values
    dayweekmonth
- 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.
- titlestring
  The title of the Product of this line_item.
- variant_titlestring
  The title of the Product variant associated with the line_item.
- skustring
  The SKU (stock keeping unit) of the Product associated with the line_item.
- weightinteger
  The weight of a single unit of the line_item, in grams.
- requires_shippingboolean
  Whether the item requires shipping.

PUT/checkouts/{token}/line_items

curl -X PUT 'https://api.rechargeapps.com/checkouts/a1b2c3d4e5f6/line_items' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token'

Response

{
  "line_items": [
    {
      "id": 1,
      "external_inventory_policy": "decrement_obeying_policy",
      "external_product_id": {
        "ecommerce": "7301234"
      },
      "external_variant_id": {
        "ecommerce": "41209876"
      },
      "handle": "morning-blend-coffee",
      "images": {
        "small": "https://cdn.example.com/products/morning-blend_small.png"
      },
      "properties": [
        {
          "name": "grind",
          "value": "whole bean"
        }
      ],
      "purchase_item_type": "subscription",
      "quantity": 2,
      "recurring_unit_price": "18.00",
      "requires_shipping": true,
      "sku": "COF-MB-12",
      "subscription_preferences": {
        "charge_interval_frequency": 1,
        "cutoff_day_of_month": null,
        "cutoff_day_of_week": null,
        "expire_after_specific_number_of_charges": null,
        "interval_unit": "month",
        "order_day_of_month": null,
        "order_day_of_week": null,
        "order_interval_frequency": 1
      },
      "tax_lines": [],
      "taxable": true,
      "title": "Morning Blend Coffee",
      "total_price": "36.00",
      "unit_price": "18.00",
      "variant_title": "12 oz",
      "weight": 340,
      "weight_unit": "g"
    }
  ]
}

#Remove line items from a checkoutNew

DELETE/checkouts/{token}/line_items

Removes several line items from a Checkout and recalculates it. A 404 is returned if an id does not exist on the Checkout. The id values of the remaining line items are reassigned.

Scopewrite_checkouts

Body parameters

line_item_idsarrayRequired
The id values of the line items to remove.

DELETE/checkouts/{token}/line_items

curl -X DELETE 'https://api.rechargeapps.com/checkouts/a1b2c3d4e5f6/line_items' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token'

Response

No content is returned for this response.

#Retrieve a line item of a checkoutNew

GET/checkouts/{token}/line_items/{line_item_id}

Returns a single line item of a Checkout by its id.

Scoperead_checkouts

GET/checkouts/{token}/line_items/{line_item_id}

curl 'https://api.rechargeapps.com/checkouts/a1b2c3d4e5f6/line_items/209176' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token'

Response

{
  "line_item": {
    "id": 1,
    "external_inventory_policy": "decrement_obeying_policy",
    "external_product_id": {
      "ecommerce": "7301234"
    },
    "external_variant_id": {
      "ecommerce": "41209876"
    },
    "handle": "morning-blend-coffee",
    "images": {
      "small": "https://cdn.example.com/products/morning-blend_small.png"
    },
    "properties": [
      {
        "name": "grind",
        "value": "whole bean"
      }
    ],
    "purchase_item_type": "subscription",
    "quantity": 2,
    "recurring_unit_price": "18.00",
    "requires_shipping": true,
    "sku": "COF-MB-12",
    "subscription_preferences": {
      "charge_interval_frequency": 1,
      "cutoff_day_of_month": null,
      "cutoff_day_of_week": null,
      "expire_after_specific_number_of_charges": null,
      "interval_unit": "month",
      "order_day_of_month": null,
      "order_day_of_week": null,
      "order_interval_frequency": 1
    },
    "tax_lines": [],
    "taxable": true,
    "title": "Morning Blend Coffee",
    "total_price": "36.00",
    "unit_price": "18.00",
    "variant_title": "12 oz",
    "weight": 340,
    "weight_unit": "g"
  }
}

#Update a line item of a checkoutNew

PUT/checkouts/{token}/line_items/{line_item_id}

Updates a single line item of a Checkout and recalculates it. The attributes to change are sent at the top level of the request body, without a root key; attributes that are not sent keep their current value.

Scopewrite_checkouts

Body parameters

quantityinteger
The quantity of the line_item. Must be at least 1.
unit_pricestring
The unit price of the line_item.
recurring_unit_pricestring
The price of a single unit of the line_item that will be charged on recurring orders. Only applies to subscription line items.
subscription_preferencesobject
An object containing the various subscription preferences associated with the line_item. When order_interval_frequency is set the line item is a subscription, otherwise a one-time.
Show child attributesHide child attributes3
- charge_interval_frequencyinteger
  Frequency at which the subscriber will be charged.
- order_interval_frequencyinteger
  Frequency at which the subscriber will receive shipments.
- interval_unitstring
  The unit applied to charge_interval_frequency and order_interval_frequency.
  Possible values
  dayweekmonth
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.
requires_shippingboolean
Whether the item requires shipping.

PUT/checkouts/{token}/line_items/{line_item_id}

curl -X PUT 'https://api.rechargeapps.com/checkouts/a1b2c3d4e5f6/line_items/209176' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token'

Response

{
  "line_item": {
    "id": 1,
    "external_inventory_policy": "decrement_obeying_policy",
    "external_product_id": {
      "ecommerce": "7301234"
    },
    "external_variant_id": {
      "ecommerce": "41209876"
    },
    "handle": "morning-blend-coffee",
    "images": {
      "small": "https://cdn.example.com/products/morning-blend_small.png"
    },
    "properties": [
      {
        "name": "grind",
        "value": "whole bean"
      }
    ],
    "purchase_item_type": "subscription",
    "quantity": 2,
    "recurring_unit_price": "18.00",
    "requires_shipping": true,
    "sku": "COF-MB-12",
    "subscription_preferences": {
      "charge_interval_frequency": 1,
      "cutoff_day_of_month": null,
      "cutoff_day_of_week": null,
      "expire_after_specific_number_of_charges": null,
      "interval_unit": "month",
      "order_day_of_month": null,
      "order_day_of_week": null,
      "order_interval_frequency": 1
    },
    "tax_lines": [],
    "taxable": true,
    "title": "Morning Blend Coffee",
    "total_price": "36.00",
    "unit_price": "18.00",
    "variant_title": "12 oz",
    "weight": 340,
    "weight_unit": "g"
  }
}

#Remove a line item from a checkoutNew

DELETE/checkouts/{token}/line_items/{line_item_id}

Removes a single line item from a Checkout and recalculates it. The id values of the remaining line items are reassigned.

Scopewrite_checkouts

DELETE/checkouts/{token}/line_items/{line_item_id}

curl -X DELETE 'https://api.rechargeapps.com/checkouts/a1b2c3d4e5f6/line_items/209176' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token'

Response

No content is returned for this response.

#Import a checkoutNew

POST/checkouts/import

Creates a Checkout from an order that was already priced in an external system and, when payment details are included, processes it in the same request. Taxes and shipping are not calculated: the tax lines, shipping line and total supplied in the request are used as they are. The body must be wrapped in the checkout root key and accepts the same attributes as Create a checkout plus the ones listed here. Subscription line items must also include external_product_id.

Scopewrite_checkouts

Body parameters

paymentsarray of objects
Payment methods used to process the Checkout. The first payment method that is not store credit is charged; store credits are applied to the total first.
Show child attributesHide child attributes5
- payment_processorstring
  The name of the payment processor, or recharge_credits for store credits.
- payment_typestring
  The payment type, e.g. CREDIT_CARD, or STORED_VALUE for store credits.
- processor_payment_method_tokenstring
  Payment method token from the payment processor. Either this or authorization_token is required unless the payment is store credit.
- authorization_tokenstring
  Token of a payment authorization that was already created with the payment processor.
- payment_tokenstring
  The ID of the credit account. Required when payment_processor is recharge_credits.
payment_dataarray
Alternative to payments: a list whose first entry is used to process the Checkout, with the same attributes as the body of Process a checkout.
shipping_linesarray of objects
The shipping line to apply to the Checkout. Only the first entry is used.
Show child attributesHide child attributes7
- codestring
  The code associated with the shipping_line.
- pricestring
  The price of the shipping_line.
- titlestring
  The title of the shipping_line.
- sourcestring
  The source of the shipping_line.
- handlestring
  Unique identifier for the shipping rate.
- taxableboolean
  Whether the shipping_line is taxable.
- tax_linesarray
  An array of tax lines associated with the shipping_line.
tax_linesarray of objects
Array of tax_line objects for the Checkout. Their prices are summed to obtain total_tax.
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.
line_itemsobjectRequired
Show child attributesHide child attributes1
- tax_linesarray of objects
  An array of tax_line objects associated with the line_item.
  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.
total_pricestring
Full price of the Checkout including shipping and tax. When omitted it is calculated from the line items, shipping line and tax lines.
send_avalara_invoiceboolean
Whether an invoice is sent to Avalara for this Checkout when the store uses Avalara for taxes. Defaults to true.
send_taxjar_invoiceboolean
Whether an invoice is sent to TaxJar for this Checkout when the store uses TaxJar for taxes. Defaults to true.

POST/checkouts/import

curl -X POST 'https://api.rechargeapps.com/checkouts/import' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token'

Response

{
  "checkout": {
    "token": "3b1f6a0e2c9d4f7a8e5b6c1d2a3f4e5b",
    "charge_id": 880012345,
    "email": "jane.doe@example.com",
    "currency": "USD",
    "requires_shipping": true,
    "taxes_included": false,
    "subtotal_price": "70.00",
    "total_tax": "1.33",
    "total_price": "71.33",
    "created_at": "2026-09-14T15:02:11+00:00",
    "updated_at": "2026-09-14T15:02:11+00:00"
  }
}