API
GuidesWhat’s newGet API token
Release notes

What’s new in V2

V2 is the current version of the Recharge API. It was previously called 2021-11: the same API under a new name.

7new resources
41new endpoints
259new attributes
440new parameters
12new webhook topics
18new batch types
364corrections

Already sending 2021-11?

You don’t need to change anything. X-Recharge-Version: v2 and X-Recharge-Version: 2021-11 both work and behave identically, so everything on this page is available with either value. You can switch the header to v2 whenever you like.

No request or response fields were removed or renamed. Everything marked New in this reference is listed below, grouped by resource.

Use V2
curl 'https://api.rechargeapps.com/subscriptions' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token'
The previous name still works
curl 'https://api.rechargeapps.com/subscriptions' \
  -H 'X-Recharge-Version: 2021-11' \
  -H 'X-Recharge-Access-Token: your_api_token'
Addresses1 endpoint14 attributes19 parameters3 corrections

New endpoints

New attributes

  • is_giftThe address objectWhether the Address is a gift address.
  • includeThe address objectAn object containing the related resources requested with the include query parameter.
  • include.customerThe address objectThe Customer associated with the Address . Returned when include contains customer .
  • include.payment_methodsThe address objectThe Payment Methods associated with the Address . Returned when include contains payment_methods . Requires the read_payment_methods scope.
  • include.subscriptionsThe address objectThe Subscriptions on the Address . Returned when include contains subscriptions . Requires the read_subscriptions scope.
  • include.onetimesThe address objectThe Onetimes on the Address . Returned when include contains onetimes . Requires the read_subscriptions scope.
  • include.discountThe address objectThe Discount applied to the Address , or null if the Address has no discount. Returned when include contains discount . Requires the read_discounts scope.
  • include.discount.idThe address objectUnique numeric identifier for the Discount .
  • include.discount.codeThe address objectThe code used to apply the Discount .
  • include.discount.valueThe address objectThe discounted value to be applied.
  • include.discount.value_typeThe address objectThe type of the Discount value.
  • include.discount.titleThe address objectThe title of the Discount .
  • include.discount.application_methodThe address objectHow the Discount is applied.
  • include.charge_activitiesThe address objectThe charge activity records created for the Address in the last 90 days. Returned when include contains charge_activities . Requires the read_orders scope.

New parameters

  • discountsCreate an address · body parameterA discount to apply to the Address . While the discounts parameter is an array, only the first discount is applied.
  • discounts[].idCreate an address · body parameterThe id of the Discount to apply to the Address .
  • discounts[].codeCreate an address · body parameterThe code of the Discount to apply to the Address . Used when id is not passed.
  • is_giftCreate an address · body parameterWhether the Address is a gift address.
  • custom_event_attributesCreate an address · body parameterA list of up to 10 custom attributes to attach to the Event created by this request. They are returned in the custom_attributes of that Event .
  • custom_event_attributes[].keyCreate an address · body parameterA user-defined key for the custom attribute.
  • custom_event_attributes[].valueCreate an address · body parameterA user-defined value for the custom attribute. Maximum length is 255 characters.
  • includeRetrieve an address · query parameterA comma-separated list of related resources to embed in the include attribute of each Address .
  • commitUpdate an address · query parameterControls when the queued charges on the Address are updated after the request applies or removes a discount. If true , the charges are updated before the response is returned. If false , they are updated asynchronously. The default depends on the store's configuration.
  • discounts[].codeUpdate an address · body parameterThe code of the Discount to apply to the Address . Used when id is not passed.
  • custom_event_attributesUpdate an address · body parameterA list of up to 10 custom attributes to attach to the Event created by this request. They are returned in the custom_attributes of that Event .
  • custom_event_attributes[].keyUpdate an address · body parameterA user-defined key for the custom attribute.
  • custom_event_attributes[].valueUpdate an address · body parameterA user-defined value for the custom attribute. Maximum length is 255 characters.
  • includeList addresses · query parameterA comma-separated list of related resources to embed in the include attribute of each Address . onetimes can only be requested together with the customer_id filter.
  • payment_method_idList addresses · query parameterReturns addresses associated with the given Payment Method .
  • orders_countList addresses · query parameterReturns addresses that have exactly the given number of processed charges. A value of 0 is ignored.
  • sort_byList addresses · query parameterSort order of the results. Default is id-desc .
  • cursorList addresses · query parameterThe next_cursor or previous_cursor value from a previous response, used to retrieve the next or previous page of results. When cursor is passed, only limit can be passed with it.
  • source_addresses[].idMerge addresses · body parameterThe id of the address.

Corrections

  • phoneCreate an addressOptional.
  • discount_idList addressesType: integer.
  • dateSkip future chargeType: date.
Bundle productsNew resource1 object2 endpoints

New objects

New endpoints

Bundle Selections5 attributes20 parameters9 corrections

New attributes

  • charge_idThe bundle selection objectThe ID of the Charge associated with the BundleSelection , when the selection applies to a specific upcoming charge.
  • order_idThe bundle selection objectThe ID of the Order associated with the BundleSelection .
  • items_countThe bundle selection objectThe item count of the BundleVariant associated with the BundleSelection .
  • is_fallbackThe bundle selection objectWhether the selection is the default selection of the BundleVariant , returned because no selection has been made for the PurchaseItem . Fallback selections have a null id .
  • items[].priceThe bundle selection objectThe price of the item.

New parameters

  • updated_at_minList bundle selections · query parameterShow BundleSelections updated after the given date.
  • updated_at_maxList bundle selections · query parameterShow BundleSelections updated before the given date.
  • cursorList bundle selections · query parameterReturn either the next or previous page of bundle selections using the next_cursor or previous_cursor value from a previous response. Only limit can be passed together with cursor .
  • charge_idsList bundle selections · query parameterFilter BundleSelections by Charge ID. If passing multiple values, must be comma separated.
  • item_external_product_idsList bundle selections · query parameterFilter BundleSelections that contain an item with one of the given external product IDs. If passing multiple values, must be comma separated.
  • item_external_variant_idsList bundle selections · query parameterFilter BundleSelections that contain an item with one of the given external variant IDs. If passing multiple values, must be comma separated.
  • commitCreate a bundle selection · query parameterControls whether the QUEUED charges linked to the purchase item are regenerated before the response is returned ( true , default) or in the background ( false ).
  • skip_remote_validationCreate a bundle selection · query parameterIf true , the selected items are not validated against the external e-commerce platform.
  • charge_idCreate a bundle selection · body parameterThe ID of the upcoming Charge the BundleSelection applies to. The charge must be in QUEUED status.
  • order_idCreate a bundle selection · body parameterThe ID of the Order the BundleSelection applies to. Requires charge_id , and the order must belong to that charge.
  • items[].priceCreate a bundle selection · body parameterThe price of the item. Must not be negative.
  • commitUpdate a bundle selection · query parameterControls whether the QUEUED charges linked to the purchase item are regenerated before the response is returned ( true , default) or in the background ( false ).
  • skip_remote_validationUpdate a bundle selection · query parameterIf true , the selected items are not validated against the external e-commerce platform.
  • items[].idUpdate a bundle selection · body parameterThe unique numeric identifier of an existing item selection to update. Items sent without an id are created.
  • items[].collection_idUpdate a bundle selection · body parameterThe collection id as it appears in the external e-commerce platform.
  • items[].external_product_idUpdate a bundle selection · body parameterThe product id as it appears in the external e-commerce platform.
  • items[].external_variant_idUpdate a bundle selection · body parameterThe variant id as it appears in the external e-commerce platform.
  • items[].quantityUpdate a bundle selection · body parameterThe quantity of this product.
  • items[].priceUpdate a bundle selection · body parameterThe price of the item. Must not be negative.
  • commitDelete a bundle selection · query parameterControls whether the QUEUED charges linked to the purchase item are regenerated before the response is returned ( true , default) or in the background ( false ).

Corrections

Charge activitiesNew resource1 object1 endpoint

New objects

New endpoints

Charges52 attributes23 parameters19 corrections

New attributes

New parameters

  • includeRetrieve a charge · query parameterA comma-separated list of related resources to return under the include attribute of the Charge . Each value also requires the read scope of the included resource ( credit_projection requires read_credit_summary ).
  • includeList charges · query parameterA comma-separated list of related resources to return under the include attribute of each Charge . Each value also requires the read scope of the included resource.
  • cursorList charges · query parameterThe next_cursor or previous_cursor value returned by a previous call, used to retrieve the next or previous page of results. When passed, the only other parameter that can be passed is limit .
  • error_typeList charges · query parameterFilter Charges in error status by a comma-separated list of error types, such as CARD_DECLINED . Requires status to include error .
  • not_error_typeList charges · query parameterExclude Charges whose error_type matches one of the given comma-separated values. Only Charges that have an error_type are returned.
  • customer_emailList charges · query parameterFilter Charges by the email address of the Customer .
  • external_product_idsList charges · query parameterFilter Charges by a comma-separated list of product IDs, as they appear in the external e-commerce platform, contained in the Charge .
  • external_variant_idsList charges · query parameterFilter Charges by a comma-separated list of variant IDs, as they appear in the external e-commerce platform, contained in the Charge .
  • commitSkip a charge · query parameterIf set to false , the remaining queued Charge is regenerated asynchronously instead of before the response is returned. Defaults to true .
  • update_membership_expires_atSkip a charge · query parameterIf set to true , the expiration date of the Membership associated with the Charge is moved to the new charge date. Defaults to false .
  • purchase_item_idsSkip a charge · body parameterA list of the Subscription or Onetime IDs to skip on the Charge .
  • purchase_item_idSkip a charge · body parameterThe ID of a single Subscription or Onetime to skip on the Charge . Cannot be passed together with purchase_item_ids .
  • update_membership_expires_atUnskip a charge · query parameterIf set to true , the expiration date of the Membership associated with the Charge is moved to the new charge date. Defaults to false .
  • purchase_item_idsUnskip a charge · body parameterA list of the Subscription or Onetime IDs to unskip on the Charge .
  • purchase_item_idUnskip a charge · body parameterThe ID of a single Subscription or Onetime to unskip on the Charge . Cannot be passed together with purchase_item_ids .
  • line_itemsRefund a charge · body parameterA list of the line items to refund. Cannot be passed together with amount . If passed with full_refund , all line items of the Charge must be listed with their full quantities.
  • line_items[].purchase_item_idRefund a charge · body parameterThe Subscription or Onetime ID of the line item to refund. Required for each line item.
  • line_items[].quantityRefund a charge · body parameterThe quantity of the line item to refund. Must be at least 1. Required for each line item.
  • custom_gatewayProcess a charge · body parameterThe outcome of a payment taken outside of Recharge. Must be passed, and can only be passed, when the Charge uses a payment method with a custom payment gateway.
  • custom_gateway.external_statusProcess a charge · body parameterThe result of the external payment. Required when custom_gateway is passed.
  • custom_gateway.external_transaction_idProcess a charge · body parameterThe ID of the transaction in the external payment system. Required when external_status is success .
  • custom_gateway.external_error_typeProcess a charge · body parameterThe structured reason why the external payment failed, such as CARD_DECLINED . Must be a valid Charge error type. Required when external_status is error and not allowed when it is success .
  • custom_gateway.external_error_messageProcess a charge · body parameterThe error message returned by the external payment system. Required when external_status is error and not allowed when it is success .

Corrections

Checkouts8 endpoints36 attributes44 parameters98 corrections

New endpoints

New attributes

New parameters

  • partial_shippingCreate a checkout · query parameterWhen 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 .
  • paymentsCreate a checkout · body parameterAdditional 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.
  • payments[].payment_typeCreate a checkout · body parameterThe type of the additional payment method: stored_value for store credits or gift_card for a gift card.
  • payments[].payment_processorCreate a checkout · body parameterThe processor of the additional payment method. Must be recharge_credits when payment_type is stored_value and rise.ai when it is gift_card .
  • payments[].payment_tokenCreate a checkout · body parameterThe 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.
  • payments[].authorization_tokenCreate a checkout · body parameterAn authorization token for the payment method.
  • line_items[].recurring_unit_priceCreate a checkout · body parameterThe 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 .
  • line_items[].requires_shippingCreate a checkout · body parameterWhether the item requires shipping. Defaults to the value of the product in the catalog.
  • line_items[].taxableCreate a checkout · body parameterWhether tax is to be applied to the line_item .
  • line_items[].external_line_item_idCreate a checkout · body parameterAn object containing the ID of the line item as it appears in the external system.
  • line_items[].external_line_item_id.ecommerceCreate a checkout · body parameterThe line item ID as it appears in the external e-commerce platform.
  • shipping_address.shipping_lines_overrideCreate a checkout · body parameterShipping lines to set as the shipping lines override of the Address created when the Checkout is processed.
  • partial_shippingUpdate a checkout · query parameterWhen 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 .
  • applied_discountsUpdate a checkout · body parameterDiscount to apply to the Checkout . Send an empty array to remove the applied discount.
  • applied_discounts[].discount_codeUpdate a checkout · body parameterThe code for the Discount , e.g. 25_PERCENT_OFF .
  • custom_shipping_rate_optionsUpdate a checkout · body parameterList of available shipping rates to use when selecting a shipping rate with applied_shipping_rate .
  • custom_shipping_rate_options[].codeUpdate a checkout · body parameterCode for the shipping rate.
  • custom_shipping_rate_options[].priceUpdate a checkout · body parameterPrice for the shipping rate.
  • custom_shipping_rate_options[].titleUpdate a checkout · body parameterTitle for the shipping rate.
  • custom_shipping_rate_options[].handleUpdate a checkout · body parameterUnique identifier for the shipping rate.
  • paymentsUpdate a checkout · body parameterAdditional 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.
  • payments[].payment_typeUpdate a checkout · body parameterThe type of the additional payment method: stored_value for store credits or gift_card for a gift card.
  • payments[].payment_processorUpdate a checkout · body parameterThe processor of the additional payment method. Must be recharge_credits when payment_type is stored_value and rise.ai when it is gift_card .
  • payments[].payment_tokenUpdate a checkout · body parameterThe 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.
  • payments[].authorization_tokenUpdate a checkout · body parameterAn authorization token for the payment method.
  • line_items[].recurring_unit_priceUpdate a checkout · body parameterThe 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 .
  • line_items[].requires_shippingUpdate a checkout · body parameterWhether the item requires shipping. Defaults to the value of the product in the catalog.
  • line_items[].taxableUpdate a checkout · body parameterWhether tax is to be applied to the line_item .
  • line_items[].external_line_item_idUpdate a checkout · body parameterAn object containing the ID of the line item as it appears in the external system.
  • line_items[].external_line_item_id.ecommerceUpdate a checkout · body parameterThe line item ID as it appears in the external e-commerce platform.
  • shipping_address.shipping_lines_overrideUpdate a checkout · body parameterShipping lines to set as the shipping lines override of the Address created when the Checkout is processed.
  • processor_payment_method_tokenProcess a checkout · body parameterPayment method token from the payment processor that will be used in the transaction. Either this or authorization_token is required unless free is true .
  • authorization_tokenProcess a checkout · body parameterToken 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.
  • processor_customer_tokenProcess a checkout · body parameterThe ID of the customer in the payment processor.
  • freeProcess a checkout · body parameterSet to true to process the Checkout without taking a payment. payment_processor and processor_payment_method_token must not be sent when true .
  • enable_upsell_opportunityProcess a checkout · body parameterWhether to hold the payment as an authorization so that post-purchase upsell items can be added before it is captured.
  • mandate_dataProcess a checkout · body parameterMandate acceptance details for bank debit payments.
  • mandate_data.customer_acceptanceProcess a checkout · body parameterDetails of how the customer accepted the mandate.
  • mandate_data.customer_acceptance.typeProcess a checkout · body parameterThe type of acceptance, e.g. online . Required when customer_acceptance is sent.
  • mandate_data.customer_acceptance.accepted_atProcess a checkout · body parameterTimestamp of when the customer accepted the mandate. Required when customer_acceptance is sent.
  • mandate_data.customer_acceptance.onlineProcess a checkout · body parameterDetails of an online mandate acceptance.
  • mandate_data.customer_acceptance.online.ip_addressProcess a checkout · body parameterThe IP address from which the customer accepted the mandate.
  • mandate_data.customer_acceptance.online.user_agentProcess a checkout · body parameterThe user agent of the browser from which the customer accepted the mandate.
  • payment_processor_return_urlProcess a checkout · body parameterThe URL the customer is returned to after authorizing the payment with their bank.

Corrections

Collections1 endpoint1 attribute13 parameters6 corrections

New endpoints

New attributes

  • manual_sort_orderThe collection objectThe manual order of the Products in the Collection , as an array of external_product_id values.

New parameters

  • typeCreate a collection · body parameterThe type of the Collection . Defaults to manual . It cannot be changed after the collection is created.
  • manual_sort_orderUpdate a collection · body parameterAn array of external_product_id values to move to the top of the manual order of the Collection , in the order given. Products that are not in the collection are ignored and products left out keep their relative order.
  • idsList collections · query parameterFilter collections by id. If passing multiple values, must be comma separated.
  • typeList collections · query parameterReturn the collections of a specific type.
  • sort_byList collections · query parameterThe order in which the collections are returned. Defaults to id-desc .
  • limitList collections · query parameterThe number of results to return. Defaults to 50; the maximum is 250.
  • cursorList collections · query parameterThe cursor of the page to return, taken from next_cursor or previous_cursor in a previous response. Only limit can be sent together with cursor .
  • pageList collections · query parameterThe page of results to show. Page-based pagination is deprecated in favor of cursor .
  • external_product_idList collections products · query parameterReturn only the collection products with the given external_product_id , which shows the collections a product belongs to.
  • sort_byList collections products · query parameterThe order in which the results are returned. Defaults to id-desc .
  • limitList collections products · query parameterThe number of results to return. Defaults to 50; the maximum is 250.
  • cursorList collections products · query parameterThe cursor of the page to return, taken from next_cursor or previous_cursor in a previous response. Only limit can be sent together with cursor .
  • pageList collections products · query parameterThe page of results to show. Page-based pagination is deprecated in favor of cursor .

Corrections

  • sort_orderThe collection objectPossible values: id-asc, id-desc, created_at-asc, created_at-desc, updated_at-asc, updated_at-desc, title-asc, title-desc, manual.
  • typeThe collection objectPossible values: automatic, manual.
  • sort_orderCreate a collectionPossible values: id-asc, id-desc, created_at-asc, created_at-desc, updated_at-asc, updated_at-desc, title-asc, title-desc, manual.
  • sort_orderUpdate a collectionPossible values: id-asc, id-desc, created_at-asc, created_at-desc, updated_at-asc, updated_at-desc, title-asc, title-desc, manual.
  • collection_products[].external_product_idAdd collection productsRequired.
  • collection_products[].external_product_idDelete collection productsRequired.
Credits2 objects4 endpoints2 attributes18 parameters9 corrections

New objects

New endpoints

New attributes

  • includeThe credit account objectAn object containing the related resources requested with the include query parameter.
  • include.customerThe credit account objectThe Customer associated with the credit account.

New parameters

  • includeRetrieve a credit account · query parameterOnly supported value is customer . If customer is included, the response will include the customer object.
  • idsList credit accounts · query parameterFilter credit accounts by id. If passing multiple values, must be comma separated.
  • includeList credit accounts · query parameterOnly supported value is customer . If customer is included, the response will include the customer object.
  • sort_byList credit accounts · query parameterSort the listed credit accounts in a specific order. Available sort options: id-asc , id-desc , expires_at-asc , expires_at-desc . Defaults to id-desc .
  • pageList credit accounts · query parameterThe page to show. Cursor pagination is recommended instead.
  • cursorList credit accounts · query parameterReturn either the next or previous page of credit accounts using the next_cursor or previous_cursor value from a previous response. Only limit can be passed together with cursor .
  • reference_typeCreate a credit adjustment · body parameterThe type of record the credit adjustment refers to. Defaults to external . The value is stored but is not returned in the response.
  • idsList Credit Adjustments for a Credit Account · query parameterReturn the list of credit adjustments linked to the given Recharge ids . If passing multiple values, must be comma separated.
  • created_at_minList Credit Adjustments for a Credit Account · query parameterReturn the list of credit adjustments created after the given date.
  • created_at_maxList Credit Adjustments for a Credit Account · query parameterReturn the list of credit adjustments created before the given date.
  • updated_at_minList Credit Adjustments for a Credit Account · query parameterReturn the list of credit adjustments updated after the given date.
  • updated_at_maxList Credit Adjustments for a Credit Account · query parameterReturn the list of credit adjustments updated before the given date.
  • sort_byList Credit Adjustments for a Credit Account · query parameterSort the listed credit adjustments in a specific order. Available sort options: id-asc , id-desc , updated_at-asc , updated_at-desc . Defaults to id-desc .
  • pageList Credit Adjustments for a Credit Account · query parameterThe page to show. Cursor pagination is recommended instead.
  • cursorList Credit Adjustments for a Credit Account · query parameterReturn either the next or previous page of credit adjustments using the next_cursor or previous_cursor value from a previous response. Only limit can be passed together with cursor .
  • sort_byList credit adjustments · query parameterSort the listed credit adjustments in a specific order. Available sort options: id-asc , id-desc , updated_at-asc , updated_at-desc . Defaults to id-desc .
  • pageList credit adjustments · query parameterThe page to show. Cursor pagination is recommended instead.
  • cursorList credit adjustments · query parameterReturn either the next or previous page of credit adjustments using the next_cursor or previous_cursor value from a previous response. Only limit can be passed together with cursor .

Corrections

  • typeThe credit account objectPossible values: manual, reward, referral, gift.
  • typeCreate a credit accountPossible values: manual, reward.
  • customer_idCreate a credit accountOptional.
  • nameCreate a credit accountOptional.
  • typeCreate a credit accountOptional.
  • customer_idUpdate a credit accountType: integer.
  • Required scopesCreate a credit adjustmentScopes: write_credit_adjustments_credit, write_credit_adjustments_debit.
  • undefinedList credit adjustmentsRemoved from the reference: the API ignores this parameter.
  • includeList credit adjustmentsRemoved from the reference: the API ignores this parameter.
Customer notification preferencesNew resource1 object2 endpoints

New objects

New endpoints

Customer sessionsNew resource1 object1 endpoint

New objects

New endpoints

Customers29 attributes35 parameters1 correction

New attributes

New parameters

Corrections

Discounts7 attributes17 parameters16 corrections

New attributes

  • application_methodThe discount objectHow the discount is applied. code discounts are applied with a discount code and automatic discounts are applied without one.
  • applies_to_existing_addressesThe discount objectWhether the discount applies to addresses that already exist. Can only be false for automatic discounts.
  • customer_segmentsThe discount objectA list of the customer segments linked to the discount. Empty when the discount is not linked to any customer segment.
  • customer_segments[].customer_segment_idThe discount objectUnique numeric identifier for the customer segment.
  • external_discount_sourceThe discount objectThe external platform that the external_discount_id belongs to.
  • titleThe discount objectThe title of the discount. For automatic discounts the title is also returned as the code .
  • usage_limits.automatic_redemptions_per_customerThe discount objectThe total number of Charges the Discount applies to for a given Customer . 0 means the discount is single use and null means it applies to all future charges.

New parameters

  • external_discount_idCreate a discount · body parameterAn object containing external ids of the discount.
  • external_discount_id.ecommerceCreate a discount · body parameterThe discount id as it appears in the external e-commerce platform. Maximum 188 characters.
  • external_discount_sourceCreate a discount · body parameterThe external platform that the external_discount_id belongs to. The combination of external_discount_source and external_discount_id must be unique.
  • titleCreate a discount · body parameterThe title of the discount. Maximum 255 characters.
  • usage_limits.automatic_redemptions_per_customerCreate a discount · body parameterThe total number of Charges the Discount applies to for a given Customer . 0 or 1 makes the discount single use and null applies it to all future charges. Ignored when max_subsequent_redemptions is also passed.
  • external_discount_idUpdate a discount · body parameterAn object containing external ids of the discount.
  • external_discount_id.ecommerceUpdate a discount · body parameterThe discount id as it appears in the external e-commerce platform. Maximum 188 characters.
  • external_discount_sourceUpdate a discount · body parameterThe external platform that the external_discount_id belongs to. The combination of external_discount_source and external_discount_id must be unique.
  • usage_limits.automatic_redemptions_per_customerUpdate a discount · body parameterThe total number of Charges the Discount applies to for a given Customer . 0 or 1 makes the discount single use and null applies it to all future charges. Ignored when max_subsequent_redemptions is also passed.
  • commitUpdate a discount · body parameterOnly used when status is set to fully_disabled . If true , the discount is removed from the addresses and queued charges it is applied to before the response is returned. Defaults to false , which removes it in the background.
  • commitDelete a discount · body parameterControls how the discount is removed from the addresses and queued charges it is applied to. If true (default), it is removed before the response is returned. If false , it is removed in the background.
  • discount_typeList discounts · query parameterFilter based on type of discount.
  • sort_byList discounts · query parameterSort listed Discounts in a specific order. Available sort options: id-asc , id-desc , created_at-asc , created_at-desc , updated_at-asc , updated_at-desc . Defaults to id-desc .
  • wildcard_searchList discounts · query parameterIf true , discount_code returns all discounts whose code starts with the given value instead of requiring an exact match.
  • cursorList discounts · query parameterReturn either the next or previous page of discounts using the next_cursor or previous_cursor value from a previous response. Only limit can be passed together with cursor .
  • application_methodList discounts · query parameterFilter discounts by how they are applied.
  • discount_titleList discounts · query parameterSearch for a particular discount title. Combine with wildcard_search to match titles that start with the given value.

Corrections

Entitlements9 attributes3 parameters2 corrections

New attributes

New parameters

  • limitList customer entitlements · query parameterThe amount of results. Default is 50 while the maximum is 250.
  • pageList customer entitlements · query parameterThe page to show. Cursor pagination is recommended instead.
  • cursorList customer entitlements · query parameterReturn either the next or previous page of customer entitlements using the next_cursor or previous_cursor value from a previous response. Only limit can be passed together with cursor .

Corrections

  • granted_by_typeThe customer entitlement objectPossible values: purchase_item, api, user, store_owner, recharge_staff_user_email, internal.
  • expires_atCreate a customer entitlementRequired.
Gift purchasesNew resource1 object3 endpoints

New objects

New endpoints

Metafields2 parameters9 corrections

New parameters

  • sort_byList metafields · query parameterSort listed Metafields in a specific order. Available sort options: id-asc , id-desc , updated_at-asc , updated_at-desc . Defaults to updated_at-desc .
  • cursorList metafields · query parameterReturn either the next or previous page of metafields using the next_cursor or previous_cursor value from a previous response. Only limit can be passed together with cursor .

Corrections

  • owner_idThe metafield objectType: integer.
  • owner_idCreate a metafieldType: integer.
  • Required scopesCreate a metafieldScopes: write_customers, write_subscriptions, write_orders, write_stores.
  • Required scopesRetrieve a metafieldScopes: read_customers, read_subscriptions, read_orders, store_info.
  • owner_idUpdate a metafieldType: integer.
  • Required scopesUpdate a metafieldScopes: write_customers, write_subscriptions, write_orders, write_stores.
  • Required scopesDelete a metafieldScopes: write_customers, write_subscriptions, write_orders, write_stores.
  • owner_idList metafieldsType: integer.
  • Required scopesList metafieldsScopes: read_customers, read_subscriptions, read_orders, store_info.
Notifications15 parameters3 corrections

New parameters

  • template_vars.payment_method_idSend email notification · body parameterThe payment_method_id of the PaymentMethod of the Customer that the notification is about. Used by the shopify_update_payment_information and shopify_migrate_payment_information template types.
  • template_vars.include_deletedSend email notification · body parameterWhether a deleted PaymentMethod may be referenced by payment_method_id . Defaults to false . Used by the shopify_update_payment_information template type.
  • template_vars.apply_to_all_subscription_addressesSend email notification · body parameterWhether the updated payment information should be applied to all of the customer's addresses. Defaults to false . Used by the shopify_migrate_payment_information template type.
  • template_vars.should_update_all_subsSend email notification · body parameterDeprecated. Use apply_to_all_subscription_addresses instead.
  • template_vars.order_idSend email notification · body parameterThe order_id of an Order on the given address. Optional; used by the subscription_activation template type.
  • template_vars.membership_idSend email notification · body parameterThe membership_id of the Membership for which the notification should be sent. Required by the membership_enrollment , membership_cancellation , membership_expiration , membership_reactivation and membership_renewal_confirmation template types.
  • template_vars.line_itemsSend email notification · body parameterThe line items to feature in the notification. Required (at least one item) by the repurchase_reminder and repurchase_welcome template types.
  • template_vars.line_items[].idSend email notification · body parameterUnique numeric identifier of the line item.
  • template_vars.line_items[].product_idSend email notification · body parameterIdentifier of the product of the line item.
  • template_vars.line_items[].variant_idSend email notification · body parameterIdentifier of the product variant of the line item.
  • template_vars.line_items[].quantitySend email notification · body parameterQuantity of the line item.
  • template_vars.line_items[].order_idSend email notification · body parameterIdentifier of the order the line item was purchased in.
  • template_vars.notificationSend email notification · body parameterThe repurchase notification the email is sent for. Required by the repurchase_reminder and repurchase_welcome template types.
  • template_vars.notification.idSend email notification · body parameterUnique numeric identifier of the repurchase notification.
  • template_vars.notification.tokenSend email notification · body parameterToken of the repurchase notification, used to build the unsubscribe link.

Corrections

  • typeSend email notificationType: string.
  • typeSend email notificationPossible values: email, sms.
  • template_typeSend email notificationPossible values: delayed_checkout_payment_failed, get_account_access, subscription_activation, upcoming_charge, repurchase_reminder, repurchase_welcome, membership_enrollment, membership_cancellation, membership_expiration, repurchase_reminder_sms, repurchase_welcome_sms, membership_upcoming_charge, membership_reactivation, membership_renewal_confirmation, membership_advanced_notice_upcoming_renewal_charge, membership_pricing_removed, gift_skipped_shipment, shopify_update_payment_information, shopify_migrate_payment_information.
Onetimes14 attributes25 parameters9 corrections

New attributes

New parameters

  • custom_event_attributesCreate a onetime · body parameterA list of up to 10 custom key-value pairs to attach to the Events generated by this request. They are returned in the custom_attributes of those Events .
  • custom_event_attributes[].keyCreate a onetime · body parameterThe name of the custom attribute.
  • custom_event_attributes[].valueCreate a onetime · body parameterThe value of the custom attribute. Maximum length is 255 characters.
  • plan_idCreate a onetime · body parameterUnique numeric identifier of a Plan of the product. When price is not provided, the discount of this Plan is used to calculate the price of the Onetime .
  • presentment_currencyCreate a onetime · body parameterThe presentment currency of the price . It must match the currency of the Address . Required when price is provided and the currency of the Address is not the store's default currency.
  • price_manually_setCreate a onetime · body parameterSet to true to indicate that the price in the request was explicitly chosen by the caller instead of being calculated by Recharge.
  • properties[].nameCreate a onetime · body parameterThe name of the property.
  • properties[].valueCreate a onetime · body parameterThe value of the property.
  • sku_overrideCreate a onetime · body parameterWhen true , the sku stored on the Onetime is used instead of the SKU of the product variant.
  • variant_titleCreate a onetime · body parameterThe name of the product variant.
  • includeRetrieve a onetime · query parameterA comma-separated list of related objects to return in the include attribute of the Onetime . address , customer and customer_entitlements also require the read_customers scope, and charge_activities also requires the read_orders scope.
  • include_deletedRetrieve a onetime · query parameterIf true , the Onetime is returned even if it has been deleted.
  • custom_event_attributesUpdate a onetime · body parameterA list of up to 10 custom key-value pairs to attach to the Events generated by this request. They are returned in the custom_attributes of those Events .
  • custom_event_attributes[].keyUpdate a onetime · body parameterThe name of the custom attribute.
  • custom_event_attributes[].valueUpdate a onetime · body parameterThe value of the custom attribute. Maximum length is 255 characters.
  • external_product_idUpdate a onetime · body parameterAn object containing the product id as it appears in external platforms.
  • external_product_id.ecommerceUpdate a onetime · body parameterThe product id as it appears in the external e-commerce platform.
  • presentment_currencyUpdate a onetime · body parameterThe presentment currency of the price . It must match the currency of the Onetime . Required when price is provided and the currency of the Onetime is not the store's default currency.
  • price_manually_setUpdate a onetime · body parameterSet to true to indicate that the price in the request was explicitly chosen by the caller instead of being calculated by Recharge.
  • sku_overrideUpdate a onetime · body parameterWhen true , the sku stored on the Onetime is used instead of the SKU of the product variant.
  • cursorList onetimes · query parameterReturn either the next or previous page of onetimes using the next_cursor or previous_cursor attributes in the response.
  • external_customer_idList onetimes · query parameterReturn the onetimes linked to the customer with the given id in the external e-commerce platform.
  • includeList onetimes · query parameterA comma-separated list of related objects to return in the include attribute of the Onetimes . address , customer and customer_entitlements also require the read_customers scope, and charge_activities also requires the read_orders scope.
  • include_deletedList onetimes · query parameterIf true the response will include the deleted Onetimes as well as the others.
  • sort_byList onetimes · query parameterSort the results by the given attribute and direction. Defaults to id-desc .

Corrections

Orders20 attributes20 parameters27 corrections

New attributes

New parameters

  • includeRetrieve an order · query parameterA comma-separated list of related resources to return in the include object of the Order . Each value other than metafields requires the matching read scope on the token: read_customers for address and customer , read_subscriptions for subscriptions , read_orders for order_modifications .
  • customer_emailList orders · query parameterFilter orders by the email of the Customer .
  • external_order_numberList orders · query parameterFilter orders by the order number as it appears in the external e-commerce platform.
  • external_order_idsList orders · query parameterFilter orders by external_order_id. Accepts a comma-separated list of up to 100 values.
  • external_product_idsList orders · query parameterFilter orders that contain any of the given external product IDs. If passing multiple values, must be comma separated.
  • external_variant_idsList orders · query parameterFilter orders that contain any of the given external variant IDs. If passing multiple values, must be comma separated.
  • includeList orders · query parameterA comma-separated list of related resources to return in the include object of each Order . Each value other than metafields requires the matching read scope on the token: read_customers for address and customer , read_subscriptions for subscriptions , read_orders for order_modifications .
  • is_prepaidList orders · query parameterPass true to return only orders generated from a prepaid purchase. Passing false does not filter the results.
  • processed_at_maxList orders · query parameterShow orders processed before the given date.
  • processed_at_minList orders · query parameterShow orders processed after the given date.
  • sort_byList orders · query parameterSort the results. Default is id-desc .
  • cursorList orders · query parameterThe cursor returned in next_cursor or previous_cursor of a previous response. When a cursor is passed, limit is the only other parameter that can be passed with it.
  • force_updateClone an order · query parameterBy default the Charge used for the clone must have a status of success . Pass true to also allow a Charge with a status of refunded , partially_refunded or cancelled .
  • charge_idClone an order · body parameterThe ID of the Charge the cloned Order is associated with. Defaults to the Charge of the original Order .
  • typeClone an order · body parameterLimits the items copied to the cloned Order . Pass subscriptions to copy only subscription items or onetimes to copy only one-time items. When omitted, all items are copied.
  • external_order_numberUpdate an order · body parameterAn object containing the external order numbers.
  • external_order_number.ecommerceUpdate an order · body parameterThe order number as it appears in the external e-commerce platform.
  • order_attributesUpdate an order · body parameterAn array of name value pairs of note attributes on the Order . Replaces the existing attributes.
  • order_attributes[].nameUpdate an order · body parameterThe name for the attribute.
  • order_attributes[].valueUpdate an order · body parameterThe value for the associated attribute.

Corrections

Payment methods8 attributes21 parameters12 corrections

New attributes

  • billing_address.countryThe payment method objectThe full country name of the billing address.
  • deleted_atThe payment method objectThe date and time when the payment method was deleted. null for payment methods that have not been deleted.
  • includeThe payment method objectAn object containing the related resources requested with the include query parameter. Returned as an empty object when no related resources are requested.
  • include.addressesThe payment method objectThe Addresses that use this payment method.
  • include.customerThe payment method objectThe Customer the payment method belongs to.
  • payment_details.bank_codeThe payment method objectThe bank code of the account.
  • payment_details.countryThe payment method objectThe country of the bank account.
  • payment_details.external_mandate_idThe payment method objectThe ID of the debit mandate at the processor.

New parameters

  • address_idsCreate a payment method · body parameterA list of Address IDs to associate with the new payment method. IDs that do not belong to the customer are ignored.
  • apply_to_all_subscription_addressesCreate a payment method · body parameterIf true , the new payment method is associated with all of the addresses of the customer.
  • billing_address.countryCreate a payment method · body parameterThe full country name of the billing address. Either country or country_code is required when billing_address is passed.
  • payment_detailsCreate a payment method · body parameterDetails about the specific payment method. Accepts brand , last4 , exp_month , exp_year , paypal_email , paypal_payer_id , wallet_type and funding_type . For other processors the details are retrieved from the processor and this value is ignored.
  • includeRetrieve a payment method · query parameterA comma-separated list of related resources to return in the include object of the payment method. Both values require the read_customers scope.
  • include_deletedRetrieve a payment method · query parameterIf true , a deleted payment method can be retrieved.
  • billing_address.countryUpdate a payment method · body parameterThe full country name of the billing address.
  • payment_detailsUpdate a payment method · body parameterDetails about the specific payment method. Accepts brand , last4 , exp_month , exp_year , paypal_email , paypal_payer_id , wallet_type and funding_type .
  • payment_typeUpdate a payment method · body parameterThe type of payment. Must be supported by the processor of the payment method.
  • processor_customer_tokenUpdate a payment method · body parameterThe customer token at the processor. Only applied when processor_payment_method_token is also passed.
  • processor_payment_method_tokenUpdate a payment method · body parameterThe payment token at the processor. The token is validated with the processor and the payment details are refreshed from it.
  • retry_chargesUpdate a payment method · body parameterWhether charges with a previous payment failure should be retried after the payment method is updated. Defaults to true .
  • address_idList payment methods · query parameterGets all Payment methods associated with this Address .
  • idsList payment methods · query parameterFilter payment methods by id. If passing multiple values, must be comma separated.
  • includeList payment methods · query parameterA comma-separated list of related resources to return in the include object of each payment method. Both values require the read_customers scope.
  • include_deletedList payment methods · query parameterIf true , deleted payment methods are also returned and each payment method includes a deleted_at attribute.
  • processor_nameList payment methods · query parameterFilter payment methods by processor. Can only be passed together with customer_id .
  • processor_payment_method_tokenList payment methods · query parameterFilter payment methods by the payment token at the processor. Only applied when customer_id is also passed.
  • limitList payment methods · query parameterThe number of results. Default is 50, maximum is 250.
  • pageList payment methods · query parameterThe page to show. Default is 1.
  • cursorList payment methods · query parameterThe cursor returned in next_cursor or previous_cursor of a previous response. When a cursor is passed, limit is the only other parameter that can be passed with it.

Corrections

  • payment_details.exp_monthThe payment method objectType: integer.
  • payment_details.exp_yearThe payment method objectType: integer.
  • payment_detailsThe payment method objectDescription updated.
  • payment_typeThe payment method objectPossible values: CREDIT_CARD, PAYPAL, APPLE_PAY, GOOGLE_PAY, SEPA_DEBIT, IDEAL, SHOP_PAY, PAYPAL_EXPRESS, SOFORT, GIROPAY, AMAZON_PAY, INVOICE, AFTERPAY_CLEARPAY, KLARNA.
  • processor_nameThe payment method objectPossible values: stripe, braintree, authorize, shopify_payments, mollie, custom_gateway.
  • payment_typeCreate a payment methodPossible values: CREDIT_CARD, PAYPAL, APPLE_PAY, GOOGLE_PAY, SEPA_DEBIT, IDEAL, SHOP_PAY, PAYPAL_EXPRESS, SOFORT, GIROPAY, AMAZON_PAY, INVOICE, AFTERPAY_CLEARPAY, KLARNA.
  • processor_nameCreate a payment methodPossible values: stripe, braintree, authorize, shopify_payments, mollie, custom_gateway.
  • defaultCreate a payment methodRequired.
  • billing_address.address1Create a payment methodRequired.
  • billing_address.cityCreate a payment methodRequired.
  • processor_customer_tokenCreate a payment methodOptional.
  • processor_nameUpdate a payment methodRemoved from the reference: the API ignores this parameter.
Plans2 endpoints9 attributes56 parameters20 corrections

New endpoints

New attributes

  • product_quantityThe plan objectThe quantity of the product that a subscriber receives when purchasing through this Plan . null when the plan does not set a quantity.
  • translationsThe plan objectAn array of translated titles for the Plan .
  • translations[].languageThe plan objectThe language code of the translation, for example fr .
  • translations[].titleThe plan objectThe title of the Plan in that language.
  • addon_settingsThe plan objectAn object containing the add-on configuration of the Plan . null when the plan is not an add-on plan. Add-on plans must be subscription plans charged and delivered every 1 month, and a product can have only one.
  • addon_settings.expirationThe plan objectAn object describing when an add-on purchased through this plan expires. null when it does not expire.
  • addon_settings.expiration.typeThe plan objectHow the expiration is expressed.
  • addon_settings.expiration.valueThe plan objectThe expiration value. For relative , an object with offset (an integer of 1 or more) and unit ( day , week , month or year ). For absolute , a date string in YYYY-MM-DD format.
  • addon_settings.parent_external_variant_idsThe plan objectAn array of the variant ids, as they appear in external platforms, of the parent products the add-on belongs to.

New parameters

  • external_variant_idsCreate a plan · body parameterAn array of variant ids, as they appear in external platforms, that the plan applies to.
  • has_variant_restrictionsCreate a plan · body parameterWhether this plan applies only to the variants listed in external_variant_ids . Defaults to false .
  • product_quantityCreate a plan · body parameterThe quantity of the product that a subscriber receives when purchasing through this Plan . null when the plan does not set a quantity.
  • translationsCreate a plan · body parameterAn array of translated titles for the Plan .
  • translations[].languageCreate a plan · body parameterThe language code of the translation, for example fr .
  • translations[].titleCreate a plan · body parameterThe title of the Plan in that language.
  • addon_settingsCreate a plan · body parameterAn object containing the add-on configuration of the Plan . null when the plan is not an add-on plan. Add-on plans must be subscription plans charged and delivered every 1 month, and a product can have only one.
  • addon_settings.expirationCreate a plan · body parameterAn object describing when an add-on purchased through this plan expires. null when it does not expire. The key is required when addon_settings is sent.
  • addon_settings.expiration.typeCreate a plan · body parameterHow the expiration is expressed.
  • addon_settings.expiration.valueCreate a plan · body parameterThe expiration value. For relative , an object with offset (an integer of 1 or more) and unit ( day , week , month or year ). For absolute , a date string in YYYY-MM-DD format.
  • addon_settings.parent_external_variant_idsCreate a plan · body parameterAn array of the variant ids, as they appear in external platforms, of the parent products the add-on belongs to. At least one is required when addon_settings is sent.
  • external_variant_idsUpdate a plan · body parameterAn array of variant ids, as they appear in external platforms, that the plan applies to.
  • has_variant_restrictionsUpdate a plan · body parameterWhether this plan applies only to the variants listed in external_variant_ids . Defaults to false .
  • product_quantityUpdate a plan · body parameterThe quantity of the product that a subscriber receives when purchasing through this Plan . null when the plan does not set a quantity.
  • translationsUpdate a plan · body parameterAn array of translated titles for the Plan .
  • translations[].languageUpdate a plan · body parameterThe language code of the translation, for example fr .
  • translations[].titleUpdate a plan · body parameterThe title of the Plan in that language.
  • addon_settingsUpdate a plan · body parameterAn object containing the add-on configuration of the Plan . null when the plan is not an add-on plan. Add-on plans must be subscription plans charged and delivered every 1 month, and a product can have only one.
  • addon_settings.expirationUpdate a plan · body parameterAn object describing when an add-on purchased through this plan expires. null when it does not expire. The key is required when addon_settings is sent.
  • addon_settings.expiration.typeUpdate a plan · body parameterHow the expiration is expressed.
  • addon_settings.expiration.valueUpdate a plan · body parameterThe expiration value. For relative , an object with offset (an integer of 1 or more) and unit ( day , week , month or year ). For absolute , a date string in YYYY-MM-DD format.
  • addon_settings.parent_external_variant_idsUpdate a plan · body parameterAn array of the variant ids, as they appear in external platforms, of the parent products the add-on belongs to. At least one is required when addon_settings is sent.
  • cursorList plans · query parameterThe cursor of the page to return, taken from next_cursor or previous_cursor in a previous response. Only limit can be sent together with cursor .
  • sort_byList plans · query parameterThe order in which the plans are returned. Defaults to id-desc .
  • created_at_minList plans · query parameterReturn the plans created after the given date.
  • created_at_maxList plans · query parameterReturn the plans created before the given date.
  • external_product_idsList plans · query parameterReturn the Plans linked to any of the given external_product_id values. If passing multiple values, must be comma separated.
  • external_variant_idList plans · query parameterReturn the Plans that can be used with the given variant: plans without variant restrictions and plans whose external_variant_ids contain it. Best combined with external_product_id .
  • external_plan_idList plans · query parameterReturn the Plans with the given external_plan_id .
  • external_plan_group_idList plans · query parameterReturn the Plans with the given external_plan_group_id .
  • plans[].external_variant_idsBulk create plans · body parameterAn array of variant ids, as they appear in external platforms, that the plan applies to.
  • plans[].has_variant_restrictionsBulk create plans · body parameterWhether this plan applies only to the variants listed in external_variant_ids . Defaults to false .
  • plans[].product_quantityBulk create plans · body parameterThe quantity of the product that a subscriber receives when purchasing through this Plan . null when the plan does not set a quantity.
  • plans[].translationsBulk create plans · body parameterAn array of translated titles for the Plan .
  • plans[].translations[].languageBulk create plans · body parameterThe language code of the translation, for example fr .
  • plans[].translations[].titleBulk create plans · body parameterThe title of the Plan in that language.
  • plans[].addon_settingsBulk create plans · body parameterAn object containing the add-on configuration of the Plan . null when the plan is not an add-on plan. Add-on plans must be subscription plans charged and delivered every 1 month, and a product can have only one.
  • plans[].addon_settings.expirationBulk create plans · body parameterAn object describing when an add-on purchased through this plan expires. null when it does not expire. The key is required when addon_settings is sent.
  • plans[].addon_settings.expiration.typeBulk create plans · body parameterHow the expiration is expressed.
  • plans[].addon_settings.expiration.valueBulk create plans · body parameterThe expiration value. For relative , an object with offset (an integer of 1 or more) and unit ( day , week , month or year ). For absolute , a date string in YYYY-MM-DD format.
  • plans[].addon_settings.parent_external_variant_idsBulk create plans · body parameterAn array of the variant ids, as they appear in external platforms, of the parent products the add-on belongs to. At least one is required when addon_settings is sent.
  • plans[].external_variant_idsBulk update plans · body parameterAn array of variant ids, as they appear in external platforms, that the plan applies to.
  • plans[].has_variant_restrictionsBulk update plans · body parameterWhether this plan applies only to the variants listed in external_variant_ids . Defaults to false .
  • plans[].product_quantityBulk update plans · body parameterThe quantity of the product that a subscriber receives when purchasing through this Plan . null when the plan does not set a quantity.
  • plans[].translationsBulk update plans · body parameterAn array of translated titles for the Plan .
  • plans[].translations[].languageBulk update plans · body parameterThe language code of the translation, for example fr .
  • plans[].translations[].titleBulk update plans · body parameterThe title of the Plan in that language.
  • plans[].addon_settingsBulk update plans · body parameterAn object containing the add-on configuration of the Plan . null when the plan is not an add-on plan. Add-on plans must be subscription plans charged and delivered every 1 month, and a product can have only one.
  • plans[].addon_settings.expirationBulk update plans · body parameterAn object describing when an add-on purchased through this plan expires. null when it does not expire. The key is required when addon_settings is sent.
  • plans[].addon_settings.expiration.typeBulk update plans · body parameterHow the expiration is expressed.
  • plans[].addon_settings.expiration.valueBulk update plans · body parameterThe expiration value. For relative , an object with offset (an integer of 1 or more) and unit ( day , week , month or year ). For absolute , a date string in YYYY-MM-DD format.
  • plans[].addon_settings.parent_external_variant_idsBulk update plans · body parameterAn array of the variant ids, as they appear in external platforms, of the parent products the add-on belongs to. At least one is required when addon_settings is sent.
  • plans[].subscription_preferences.pricing_progressionBulk update plans · body parameterUsed to configure a plan with dynamic pricing. Only the first item of the array is used.
  • plans[].subscription_preferences.pricing_progression[].recurring_discount_after_cycleBulk update plans · body parameterThe number of cycles after which this recurring discount should be applied.
  • plans[].subscription_preferences.pricing_progression[].recurring_discount_amountBulk update plans · body parameterThe discount amount applied to the product price after the specified number of cycles.
  • plans[].subscription_preferences.pricing_progression[].recurring_discount_typeBulk update plans · body parameterUsed in combination with the recurring discount amount to determine the discount applied after the specified number of cycles.

Corrections

Products6 attributes14 parameters48 corrections

New attributes

New parameters

Corrections

Retention strategiesNew resource1 object5 endpoints

New objects

New endpoints

Reward creditsNew resource1 object3 endpoints

New objects

New endpoints

Store6 attributes4 corrections

New attributes

Corrections

Subscriptions4 endpoints27 attributes61 parameters17 corrections

New endpoints

New attributes

  • is_digitalThe subscription objectValue is true if the Subscription is for a digital item, meaning the item does not require shipping and its Plan grants at least one entitlement. Always false for stores that do not have digital subscriptions enabled.
  • plan_idThe subscription objectUnique numeric identifier of the Plan the Subscription is linked to.
  • locked_pending_charge_idThe subscription objectUnique numeric identifier of the Charge that is waiting for a payment confirmation for this Subscription . The Subscription cannot be modified while this value is set.
  • additional_variant_dataThe subscription objectAn object containing variant values stored on the Subscription . Each key holds an object with the stored value and an override boolean that is true when the value was set explicitly on the Subscription . The object is empty when no values are stored.
  • additional_variant_data.fulfillment_serviceThe subscription objectThe fulfillment service of the variant, as value and override .
  • additional_variant_data.gramsThe subscription objectThe weight of the variant in grams, as value and override .
  • additional_variant_data.tax_codeThe subscription objectThe tax code of the variant, as value and override .
  • additional_variant_data.taxableThe subscription objectWhether the variant is taxable, as value and override .
  • additional_variant_data.vendorThe subscription objectThe vendor of the variant, as value and override .
  • includeThe subscription objectAn object containing the related objects requested with the include query parameter.
  • include.addressThe subscription objectThe Address the Subscription is associated with.
  • include.bundle_productThe subscription objectThe bundle product that matches the product of the Subscription . null if the product is not a bundle.
  • include.bundle_selectionsThe subscription objectThe BundleSelection linked to the Subscription . null if there is none.
  • include.charge_activitiesThe subscription objectThe charge activity records created in the last 90 days for the Charges that contain the Subscription .
  • include.customerThe subscription objectThe Customer the Subscription is tied to.
  • include.customer_entitlementsThe subscription objectThe entitlements granted to the Customer by the Subscription .
  • include.customer_entitlements[].idThe subscription objectUnique numeric identifier for the customer entitlement.
  • include.customer_entitlements[].descriptionThe subscription objectThe description of the entitlement feature.
  • include.customer_entitlements[].expires_atThe subscription objectThe time the entitlement expires. null if it does not expire.
  • include.customer_entitlements[].lookup_keyThe subscription objectThe lookup key of the entitlement feature.
  • include.customer_entitlements[].nameThe subscription objectThe name of the entitlement feature.
  • include.metafieldsThe subscription objectThe Metafields attached to the Subscription .
  • include.addonsThe subscription objectThe add-on relationships of the Subscription with other subscriptions.
  • include.addons[].typeThe subscription objectThe role of the related subscription: child when the related subscription is an add-on of this Subscription , parent when this Subscription is an add-on of the related subscription.
  • include.addons[].parent_subscription_idThe subscription objectUnique numeric identifier of the parent Subscription in the relationship.
  • include.addons[].child_subscription_idThe subscription objectUnique numeric identifier of the add-on Subscription in the relationship.
  • include.expires_atThe subscription objectA list containing the date on which the Subscription expires as an add-on, or null if it has no expiration.

New parameters

  • commitCreate a subscription · query parameterIf set to true , the QUEUED charges linked to the Subscription are regenerated before the response is returned. If omitted or false , the charges are regenerated asynchronously.
  • analytics_dataCreate a subscription · body parameterAn object used to contain analytics data such as utm parameters.
  • analytics_data.utm_paramsCreate a subscription · body parameterAn array containing utm_param objects.
  • analytics_data.utm_params[].utm_campaignCreate a subscription · body parameterThe UTM campaign.
  • analytics_data.utm_params[].utm_contentCreate a subscription · body parameterThe UTM content.
  • analytics_data.utm_params[].utm_data_sourceCreate a subscription · body parameterThe source of the campaign parameter. Required for each utm_param object.
  • analytics_data.utm_params[].utm_mediumCreate a subscription · body parameterThe UTM medium.
  • analytics_data.utm_params[].utm_sourceCreate a subscription · body parameterThe UTM source.
  • analytics_data.utm_params[].utm_termCreate a subscription · body parameterThe UTM term.
  • analytics_data.utm_params[].utm_timestampCreate a subscription · body parameterThe UTM timestamp. Required for each utm_param object.
  • cancellation_reasonCreate a subscription · body parameterReason for cancellation. Can only be set when status is cancelled or expired .
  • cancelled_atCreate a subscription · body parameterThe time the subscription was cancelled. Can only be set when status is cancelled or expired . Defaults to the current time when status is cancelled .
  • custom_event_attributesCreate a subscription · body parameterA list of up to 10 custom key-value pairs to attach to the Events generated by this request. They are returned in the custom_attributes of those Events .
  • custom_event_attributes[].keyCreate a subscription · body parameterThe name of the custom attribute.
  • custom_event_attributes[].valueCreate a subscription · body parameterThe value of the custom attribute. Maximum length is 255 characters.
  • presentment_currencyCreate a subscription · body parameterThe presentment currency of the price . It must match the currency of the Address . Required when price is provided and the currency of the Address is not the store's default currency.
  • price_manually_setCreate a subscription · body parameterSet to true to indicate that the price in the request was explicitly chosen by the caller instead of being calculated by Recharge.
  • skuCreate a subscription · body parameterA unique identifier of the item in the fulfillment.
  • sku_overrideCreate a subscription · body parameterWhen true , the sku stored on the Subscription is used instead of the SKU of the product variant.
  • variant_titleCreate a subscription · body parameterThe name of the product variant.
  • includeRetrieve a subscription · query parameterA comma-separated list of related objects to return in the include attribute of the Subscription . address , customer and customer_entitlements also require the read_customers scope, and charge_activities also requires the read_orders scope. addons and expires_at only return data for stores with add-on subscriptions enabled.
  • address_idUpdate a subscription · body parameterUnique numeric identifier of the Address to move the Subscription to. The Address must belong to the same Customer and use the same currency as the Subscription .
  • analytics_dataUpdate a subscription · body parameterAn object used to contain analytics data such as utm parameters. The UTM parameters passed are added to the ones already stored on the Subscription .
  • analytics_data.utm_paramsUpdate a subscription · body parameterAn array containing utm_param objects.
  • analytics_data.utm_params[].utm_campaignUpdate a subscription · body parameterThe UTM campaign.
  • analytics_data.utm_params[].utm_contentUpdate a subscription · body parameterThe UTM content.
  • analytics_data.utm_params[].utm_data_sourceUpdate a subscription · body parameterThe source of the campaign parameter. Required for each utm_param object.
  • analytics_data.utm_params[].utm_mediumUpdate a subscription · body parameterThe UTM medium.
  • analytics_data.utm_params[].utm_sourceUpdate a subscription · body parameterThe UTM source.
  • analytics_data.utm_params[].utm_termUpdate a subscription · body parameterThe UTM term.
  • analytics_data.utm_params[].utm_timestampUpdate a subscription · body parameterThe UTM timestamp. Required for each utm_param object.
  • cancellation_reasonUpdate a subscription · body parameterReason for cancellation. Can only be set when status is passed as cancelled or expired in the same request.
  • cancellation_reason_commentsUpdate a subscription · body parameterAdditional comment for cancellation. Maximum length is 1024 characters. Can only be set when status is passed as cancelled or expired in the same request.
  • cancelled_atUpdate a subscription · body parameterThe time the subscription was cancelled. Can only be set when status is passed as cancelled or expired in the same request.
  • custom_event_attributesUpdate a subscription · body parameterA list of up to 10 custom key-value pairs to attach to the Events generated by this request. They are returned in the custom_attributes of those Events .
  • custom_event_attributes[].keyUpdate a subscription · body parameterThe name of the custom attribute.
  • custom_event_attributes[].valueUpdate a subscription · body parameterThe value of the custom attribute. Maximum length is 255 characters.
  • external_product_idUpdate a subscription · body parameterAn object containing the product id as it appears in external platforms.
  • external_product_id.ecommerceUpdate a subscription · body parameterThe product id as it appears in the external e-commerce platform.
  • next_charge_scheduled_atUpdate a subscription · body parameterThe date of the next charge for the Subscription . It cannot be in the past.
  • overrideUpdate a subscription · body parameterIf set to true , allows interval changes that are otherwise rejected, such as changing the charge or order frequency of a prepaid Subscription , or changing a Subscription to a prepaid frequency.
  • presentment_currencyUpdate a subscription · body parameterThe presentment currency of the price . It must match the currency of the Subscription . Required when price is provided and the currency of the Subscription is not the store's default currency.
  • price_manually_setUpdate a subscription · body parameterSet to true to indicate that the price in the request was explicitly chosen by the caller instead of being calculated by Recharge.
  • statusUpdate a subscription · body parameterThe status of the Subscription . When set to cancelled without cancelled_at , the cancellation time is set to the current time.
  • commitDelete a subscription · query parameterIf set to true , the QUEUED charges linked to the Subscription are regenerated before the response is returned. If omitted or false , the charges are regenerated asynchronously.
  • bundles_onlyList subscriptions · query parameterIf true , only return the subscriptions whose product variant belongs to an active, published bundle product. Only true is accepted; omit the parameter to list all subscriptions.
  • external_customer_idList subscriptions · query parameterReturn the subscriptions linked to the customer with the given id in the external e-commerce platform.
  • includeList subscriptions · query parameterA comma-separated list of related objects to return in the include attribute of the Subscriptions . address , customer and customer_entitlements also require the read_customers scope, and charge_activities also requires the read_orders scope. addons and expires_at only return data for stores with add-on subscriptions enabled.
  • include_onetimesList subscriptions · query parameterIf true , the response also contains an onetimes array with the Onetimes matching the same filters. Only applied when address_id , customer_id or external_customer_id is also passed.
  • sort_byList subscriptions · query parameterSort the results by the given attribute and direction. Defaults to id-desc .
  • commitChange a subscription next charge date · query parameterIf set to true , the QUEUED charges linked to the Subscription are regenerated before the response is returned. If omitted or false , the charges are regenerated asynchronously.
  • pauseChange a subscription next charge date · query parameterIf true , the date change is also recorded as a pause of the Subscription and the subscription/paused webhook is sent.
  • custom_event_attributesChange a subscription next charge date · body parameterA list of up to 10 custom key-value pairs to attach to the Events generated by this request. They are returned in the custom_attributes of those Events .
  • custom_event_attributes[].keyChange a subscription next charge date · body parameterThe name of the custom attribute.
  • custom_event_attributes[].valueChange a subscription next charge date · body parameterThe value of the custom attribute. Maximum length is 255 characters.
  • commitCancel a subscription · query parameterIf set to true , the QUEUED charges linked to the Subscription are regenerated before the response is returned. If omitted or false , the charges are regenerated asynchronously.
  • overrideCancel a subscription · body parameterIf set to true , the cancellation reason and comments can be replaced on a Subscription that was already cancelled after reaching the maximum number of charge attempts.
  • commitActivate a subscription · query parameterIf set to true , the QUEUED charges linked to the Subscription are regenerated before the response is returned. If omitted or false , the charges are regenerated asynchronously.
  • custom_event_attributesActivate a subscription · body parameterA list of up to 10 custom key-value pairs to attach to the Events generated by this request. They are returned in the custom_attributes of those Events .
  • custom_event_attributes[].keyActivate a subscription · body parameterThe name of the custom attribute.
  • custom_event_attributes[].valueActivate a subscription · body parameterThe value of the custom attribute. Maximum length is 255 characters.

Corrections

Webhook endpoints3 parameters12 webhook topics8 corrections

New parameters

  • limitList webhooks · query parameterNumber of results to return. Defaults to 50; the maximum is 250.
  • pageList webhooks · query parameterPage to show. Cannot be greater than 300. Page-based pagination can be disabled for a token, in which case cursors must be used.
  • sort_byList webhooks · query parameterSort order of the results. Defaults to id-desc .

New webhook topics

  • address/deletedAvailable webhooksFires when an Address is deleted.
  • address/payment_method/updatedAvailable webhooksFires when the PaymentMethod associated with an Address is changed.
  • async_batch/startedAvailable webhooksFires when an async batch starts running its tasks.
  • gift_purchase/updatedAvailable webhooksFires when a gift purchase is updated. Only fires for stores that offer gift purchases.
  • gift_purchase/unclaimedAvailable webhooksFires once when a gift purchase that was sent to its recipient has not been redeemed within the reminder period. Only fires for stores that offer gift purchases.
  • gift_purchase/sentAvailable webhooksFires when the gift notification is sent to the recipient of a gift purchase. Only fires for stores that offer gift purchases.
  • order/delayedAvailable webhooksFires when a queued prepaid Order is delayed.
  • payment_method/createdAvailable webhooksFires when a PaymentMethod is created.
  • payment_method/deletedAvailable webhooksFires when a PaymentMethod is deleted.
  • payment_method/expiredAvailable webhooksFires when the card of a PaymentMethod will have expired by the date of an upcoming Charge .
  • payment_method/updatedAvailable webhooksFires when a PaymentMethod is updated.
  • subscription/expiredAvailable webhooksFires when a Subscription expires. It is followed by subscription/cancelled .

Corrections

  • included_objectsThe Webhook objectPossible values: address, addresses, charge_activities, customer, event, event_charge, metafields, payment_methods, subscriptions.
  • versionThe Webhook objectPossible values: 2021-01, 2021-11.
  • addressCreate a webhookType: string.
  • topicCreate a webhookType: string.
  • included_objectsCreate a webhookPossible values: address, addresses, charge_activities, customer, event, event_charge, metafields, payment_methods, subscriptions.
  • versionCreate a webhookPossible values: v2, 2021-01, 2021-11.
  • included_objectsUpdate a webhookPossible values: address, addresses, charge_activities, customer, event, event_charge, metafields, payment_methods, subscriptions.
  • versionUpdate a webhookPossible values: v2, 2021-01, 2021-11.
Async batch Endpoints2 endpoints2 attributes8 parameters18 batch types16 corrections

New endpoints

New attributes

  • deleted_atThe async batch objectThe date and time the batch was deleted. Deleted batches are not returned by the API, so this is null .
  • expired_atThe async batch objectThe date and time until which the batch and its tasks are retained.

New parameters

  • tasksCreate a batch · body parameterOptional list of tasks to add to the batch when it is created. A single request can contain at most 1,000 tasks.
  • tasks[].bodyCreate a batch · body parameterThe body of the task, in the format required by the batch_type .
  • batch_typeList batches · query parameterFilter batches by batch_type . Any registered batch type can be used as a filter, including types that can only be created with API version 2021-01.
  • statusList batches · query parameterFilter batches by status .
  • sort_byList batches · query parameterSort order of the results. Defaults to id-desc .
  • limitList batches · query parameterNumber of results to return. Defaults to 50; the maximum is 250.
  • pageList batches · query parameterPage to show. Cannot be greater than 300. Page-based pagination can be disabled for a token, in which case cursors must be used.
  • cursorList batches · query parameterReturn either the next or previous page of batches using the next_cursor or previous_cursor value from a previous response. When cursor is passed, only limit may be passed with it.

New batch types

Corrections

  • idThe async batch objectType: integer.
  • batch_typeThe async batch objectPossible values: address_update, bulk_customer_notification_preferences_accepted_update, bulk_customer_notification_preferences_declined_update, bulk_customers_update, bulk_plans_create, bulk_plans_delete, bulk_plans_update, bundle_bulk_swap, bundle_selection_assign, bundle_selection_update, bundle_selections_delete, bundle_selections_sync_price, charge_process, credit_account_create, credit_account_update, discount_create, discount_delete, discount_update, free_gifts_add, free_gifts_remove, onetime_create, onetime_delete, onetime_update, plan_create, product_variant_tax_code_update, subscription_update.
  • statusThe async batch objectPossible values: not_started, processing, running, completed, failed, terminated.
  • closed_atThe async batch objectType: datetime.
  • created_atThe async batch objectType: datetime.
  • submitted_atThe async batch objectType: datetime.
  • updated_atThe async batch objectType: datetime.
  • fail_task_countThe async batch objectType: integer.
  • success_task_countThe async batch objectType: integer.
  • total_task_countThe async batch objectType: integer.
  • versionThe async batch objectPossible values: 2021-01, 2021-11.
  • batch_typeCreate a batchPossible values: address_update, bulk_customer_notification_preferences_accepted_update, bulk_customer_notification_preferences_declined_update, bulk_customers_update, bulk_plans_create, bulk_plans_delete, bulk_plans_update, bundle_bulk_swap, bundle_selection_assign, bundle_selection_update, bundle_selections_delete, bundle_selections_sync_price, charge_process, credit_account_create, credit_account_update, discount_create, discount_delete, discount_update, free_gifts_add, free_gifts_remove, onetime_create, onetime_delete, onetime_update, plan_create, product_variant_tax_code_update, subscription_update.
  • batch_typeCreate a batchRequired.
  • Required scopesRetrieve a batchScopes: read_batches.
  • Required scopesList batchesScopes: read_batches.
  • Required scopesProcess a batchScopes: write_batches.
Async batch Tasks1 endpoint1 attribute8 parameters17 corrections

New endpoints

New attributes

  • stalled_atThe async batch Tasks objectIndicates the date and time a task was flagged as stalled during processing.

New parameters

  • tasksCreate a batch task · body parameterList of tasks to add to the batch. A single request can contain at most 1,000 tasks and a batch can hold at most 10,000 tasks.
  • tasks[].bodyCreate a batch task · body parameterThe body of the task, in the format required by the batch_type of the batch.
  • statusList batch tasks · query parameterFilter tasks by status .
  • completedList batch tasks · query parameterWhen true , return only tasks that have finished processing; when false , return only tasks that have not finished.
  • sort_byList batch tasks · query parameterSort order of the results. Defaults to id-desc .
  • limitList batch tasks · query parameterNumber of results to return. Defaults to 50; the maximum is 250.
  • pageList batch tasks · query parameterPage to show. Cannot be greater than 300. Page-based pagination can be disabled for a token, in which case cursors must be used.
  • cursorList batch tasks · query parameterReturn either the next or previous page of tasks using the next_cursor or previous_cursor value from a previous response. When cursor is passed, only limit may be passed with it.

Corrections

  • statusThe async batch Tasks objectPossible values: pending, queued, processing, success, fail.
  • resultThe async batch Tasks objectType: object.
  • batch_idCreate a batch taskRemoved from the reference: the API ignores this parameter.
  • bodyCreate a batch taskRemoved from the reference: the API ignores this parameter.
  • completed_atCreate a batch taskRemoved from the reference: the API ignores this parameter.
  • created_atCreate a batch taskRemoved from the reference: the API ignores this parameter.
  • deleted_atCreate a batch taskRemoved from the reference: the API ignores this parameter.
  • idCreate a batch taskRemoved from the reference: the API ignores this parameter.
  • queued_atCreate a batch taskRemoved from the reference: the API ignores this parameter.
  • resultCreate a batch taskRemoved from the reference: the API ignores this parameter.
  • started_atCreate a batch taskRemoved from the reference: the API ignores this parameter.
  • statusCreate a batch taskRemoved from the reference: the API ignores this parameter.
  • updated_atCreate a batch taskRemoved from the reference: the API ignores this parameter.
  • tasksCreate a batch taskRequired.
  • tasks[].bodyCreate a batch taskRequired.
  • Required scopesCreate a batch taskScopes: write_batches.
  • Required scopesList batch tasksScopes: read_batches.
Token information1 endpoint3 attributes2 corrections

New endpoints

New attributes

  • client.contact_emailThe token information objectThe client's email.
  • created_by_emailThe token information objectThe email of the user on whose behalf the token was issued. null for API tokens created by a merchant or an OAuth app.
  • created_by_user_idThe token information objectThe unique numeric identifier of the user on whose behalf the token was issued. null for API tokens created by a merchant or an OAuth app.

Corrections

  • clientThe token information objectDescription updated.
  • client.emailThe token information objectRemoved from the reference: the API does not return this attribute.
Accounts8 attributes9 parameters

New attributes

  • last_login_atThe account objectThe date and time the user last logged in to the Account .
  • role_associationThe account objectThe role association recorded for the user of the Account .
  • role_departmentThe account objectThe department recorded for the user of the Account .
  • role_titleThe account objectThe job title recorded for the user of the Account .
  • role_partner_detailsThe account objectAn object with partner details recorded for the user of the Account .
  • permissionsThe account objectList of permission keys granted to the Account .
  • includeThe account objectRelated objects requested with the include query parameter.
  • include.storeThe account objectThe Store the Account belongs to.

New parameters

  • includeRetrieve an account · query parameterInclude related objects in the response. Use store to embed the Store the Account belongs to under include.store .
  • user_idList accounts · query parameterFilter accounts by the unique numeric identifier of the associated user.
  • is_ownerList accounts · query parameterFilter accounts by whether the user is the store owner.
  • email_searchList accounts · query parameterReturn accounts whose user email contains the given text.
  • include_all_ownersList accounts · query parameterWhen passed together with email_search , store owner accounts are returned in addition to the accounts matching the search.
  • includeList accounts · query parameterInclude related objects in the response. Use store to embed the Store the Account belongs to under include.store .
  • limitList accounts · query parameterNumber of results to return. Defaults to 50; the maximum is 250.
  • pageList accounts · query parameterPage to show. Cannot be greater than 300. Page-based pagination can be disabled for a token, in which case cursors must be used.
  • cursorList accounts · query parameterReturn either the next or previous page of accounts using the next_cursor or previous_cursor value from a previous response. When cursor is passed, only limit may be passed with it.
Events6 parameters9 corrections

New parameters

  • verbList events · query parameterShow events with a specific verb .
  • sort_byList events · query parameterSort order of the results. Defaults to id-desc when filtering by customer_id and to created_at-desc otherwise.
  • exclude_empty_customer_eventsList events · query parameterWhen true , customer events with the verb updated that have no updated_attributes are left out of the results.
  • limitList events · query parameterNumber of results to return. Defaults to 50; the maximum is 250.
  • pageList events · query parameterPage to show. Cannot be greater than 300. Page-based pagination can be disabled for a token, in which case cursors must be used.
  • cursorList events · query parameterReturn either the next or previous page of events using the next_cursor or previous_cursor value from a previous response. When cursor is passed, only limit may be passed with it.

Corrections

  • updated_attributesThe event objectType: array.
  • custom_attributesThe event objectType: array.
  • source.account_idThe event objectType: integer.
  • source.originThe event objectPossible values: api, customer_portal, external_platform, merchant_portal, recharge_process.
  • source.user_typeThe event objectPossible values: customer, customer_sms, recharge_admin, recharge_admin_sms, recharge_order_merge, recharge_process, store_admin, store_admin_sms, support_session.
  • created_atThe event objectDescription updated.
  • object_typeList eventsPossible values: address, address/payment_method, address_payment_method, app, async_batch, bundle_product, bundle_selection, cancellation_flow, charge, checkout, collection, collection_product, credit_account, credit_adjustment, customer, delivery_profile, discount, email, fraud_investigation, membership, membership_program, membership_program_condition, monthly_sku_swap_workflow_adapter, onetime, order, payment_method, plan, product, purchase_item, sequence_workflow_adapter, shipping_window_workflow_adapter, shop, store, subscription, theme, webhook, widget_settings.
  • originList eventsPossible values: api, customer_portal, external_platform, merchant_portal, recharge_process.
  • object_type.object_typeList eventsRemoved from the reference: the API ignores this parameter.