{ "openapi": "3.1.0", "info": { "title": "Recharge API", "version": "v2", "description": "Recharge API reference, version V2. The current version of the Recharge API. Previously called 2021-11. Send X-Recharge-Version: v2 or 2021-11; both select this version." }, "servers": [ { "url": "https://api.rechargeapps.com" } ], "security": [ { "apiToken": [] } ], "tags": [ { "name": "Addresses", "description": "An Addresses record represents a shipping address. Each customer can have multiple addresses. Subscriptions are a child object of an address." }, { "name": "Bundle products", "description": "A Bundle Product describes a product that is sold as a bundle: its variants, the collections customers can choose the contents from, the default contents and the display settings. Bundle products can be listed and retrieved through the API; they are created and edited in the Recharge merchant portal." }, { "name": "Bundle Selections", "description": "A bundle selection represents the contents within a Bundle linked to an individual Subscription. It can represent the selection for upcoming orders or past orders. A BundleSelection is associated with a corresponding Subscription and a BundleVariant (the BundleVariant is used to validate contents in the selection). When a new order for the associated Subscription occurs, it will extract the current contents of the BundleSelection for the Bundle item in the order." }, { "name": "Charge activities", "description": "A charge activity is a record of something that happened to a Charge , such as a payment attempt, a payment failure, a skip, a reschedule or a refund. Charge activities give a timeline of a Charge together with a description of each event and, for failures, a suggested solution. Only charge activities created in the last 90 days are available." }, { "name": "Charges", "description": "A charge is the representation of a financial transaction linked to the purchase of an item (past or future). It can be a transaction that was processed already or the representation of an upcoming transaction. A Charge is linked to its corresponding Orders (one Order for pay as you go subscriptions and several for pre-paid). Orders are created once the corresponding Charge is successful. After successful payment, the first Order will be immediately submitted to the external platform if applicable (e.g. Shopify, BigCommerce)." }, { "name": "Checkouts", "description": "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." }, { "name": "Collections", "description": "Collections allow to create and manage a logical list of Products called a Collection . A Collection contains an ordered list of Products and can be used for selective display of Products on chosen interfaces or for business logic automation (e.g. Discounts definition...)." }, { "name": "Credits", "description": "The Credit Account object represents a set of positive and negative credit adjustments that when summed equal an available balance. Credit accounts may not have negative balances. A credit account may be associated with a customer, via the customer_id attribute. A customer may be associated with many credit accounts. A credit adjustment represents a financial adjustment to the balance of a Credit Account. An adjustment of type ‘credit’ results in an increase in the available balance of a credit account, where an adjustment of type ‘debit’ results in a decrease. Access to the Credits endpoints are only available for merchants using Retain ." }, { "name": "Customer notification preferences", "description": "Notification preferences record whether a Customer has opted in or out of transactional, promotional and replenishment communication over email and SMS, and when and where each choice was last made." }, { "name": "Customer sessions", "description": "Customer sessions are short-lived tokens scoped to a single Customer . They allow a storefront or application to act on behalf of that customer without exposing the store's API token." }, { "name": "Customers", "description": "The Customer object holds account information. Email is unique on the Customer ; no two customers for a store can have the same email. Address is a child of the Customer object. There can be many child Addresses on a customer, but only one parent Customer per Address ." }, { "name": "Discounts", "description": "Discounts can be applied to a Checkout , or can be applied directly to an Address . Depending on configuration they allow for single use, or recurring discounts. More details on how to add or remove discounts from an Address can be found at Update an address . Often discounts can be used in combination with webhooks, such that when a specific event occurs, it can apply a discount dependent on custom business logic. There are various options that can be utilized for discounts such as minimum price, single use, recurring for a set number of charges, or ongoing. You can also set the date from which time the discount will become applicable and when it can no longer be applied to a new subscription." }, { "name": "Entitlements", "description": "A Customer Entitlement represents access to a specific entitlement feature granted to a customer, typically driven by an active subscription. While you own and host your content, Recharge provides the logic engine that determines a customer's real-time access status based on their active subscriptions." }, { "name": "Gift purchases", "description": "A Gift purchase is created when a customer buys a gift for someone else. It links the sender, the recipient and the Credit account that holds the value of the gift, and tracks when the recipient was notified and when the gift was redeemed. Gift purchases are only available for stores with gifting enabled." }, { "name": "Metafields", "description": "Metafields allow users to add additional information to other resources. They can be used for adding custom fields to objects, and are useful for storing specialized information." }, { "name": "Notifications", "description": "The Customer Notifications resource is used to dispatch email notifications to customers within Recharge. The endpoint uses your configured Recharge email templates, and will dispatch an email to the address associated with the indicated customer_id . Some email templates require variable values, which are sent through the Customer Notifications resource via the template_vars attribute. See below examples for all available template types." }, { "name": "Onetimes", "description": "Onetimes represent non-recurring line items on a QUEUED Charge ." }, { "name": "Orders", "description": "An order is created after a Charge is successfully processed. The Order contains all the same json data as the Charge . In case of a prepaid order creation, the order will be queued for a particular date and submitted on that date to the external platform." }, { "name": "Payment methods", "description": "The Payment Method object holds payment and billing information. A Customer may be associated with many Payment Methods , and an Addresses record must be associated with at least one Payment_method . Important - If you see the following error when accessing Payment Methods endpoints: \"You do not have sufficient permissions (scopes) for this object\", the token you are using has not been configured with correct access permissions. Update the token to have \"Read access\" or \"Read and Write access\" depending on your use case." }, { "name": "Plans", "description": "The Plans resource is used to create and configure the transactional options for the Product (subscription, prepaid, and onetime purchase options) in Recharge." }, { "name": "Products", "description": "Representation of the Products from your catalog in Recharge." }, { "name": "Retention strategies", "description": "A Retention strategy is a cancellation reason a customer can choose when cancelling, together with the message and optional incentive (a discount, skipping a charge, delaying the subscription or swapping the product) offered to keep them subscribed." }, { "name": "Reward credits", "description": "A Reward credit is store credit issued to a Customer as a reward. Each reward credit keeps track of its initial value, the balance still available and an optional expiration date. A reward credit is a Credit account of type reward and shares its id with that credit account." }, { "name": "Store", "description": "The store endpoint includes ReCharge settings and other store specific information." }, { "name": "Subscriptions", "description": "Subscriptions are individual items a customer receives on a recurring basis. A Subscription is a Product added to an Address ." }, { "name": "Webhook endpoints", "description": "Webhooks are a mechanism for reacting to specific events that are triggered in the Recharge system. For example, a checkout completion, a customer activation or subscription cancellation. Webhooks will deliver you the data of the specific event in real-time. This data can be used to custom code logic behind automated subscription management, dashboards creation, discounts applying... When a webhook is triggered, the payload will be identical to the payload you would receive from another API endpoint. For example, a webhook on subscription/created will be identical to the payload for retrieving a subscription by ID from the Recharge API. There are a lot of things that can be done via Webhooks: It can be used to collect all kinds of data from our API and then create a custom Dashboard to show how much and when your customers are buying in real time, or use all this data to do Analytics of some kind in order to create a better customer experience. Webhooks can be used as a “Trigger” on your backend to update subscription products. If you have some kind of a Subscription where you want to change the Product that the customer gets every month, you can do it by waiting for an order/created webhook on your backend, and when it fires you can make an API call to change the Product of that subscription or the next shipping date, etc. Retries / Idempotency Due to webhook retries, it’s possible that your application receives the same webhook more than once. Ensure idempotency of the webhook call by detecting such duplicates within your application. Respond to a webhook Your webhook acknowledges that it received data by sending a 200 OK response. Any response outside of the 200 range will let Recharge know that you didn’t receive your webhook. Recharge has implemented a 5 second time-out period. We wait 5 seconds, if our system doesn’t get a response in that period we consider that request as failed. Our system will try 20 times to send the same webhook over the next 2 days, if the request fails every time our system will delete this webhook. At this moment our system is logging those deleted webhooks." }, { "name": "Async batch Endpoints", "description": "The Async batches API can be used for processing large volumes of operations asynchronously, in order to reduce aggregate processing time and network traffic when interacting with many unique objects. For example, a user can leverage async_batches to create 1000 discounts with only 3 API requests. As shown in the diagram below, the necessary steps to create and process a batch are: 1. Create an async_batch with the desired batch_type 2. Add tasks (individual operations) to your batch. You can add up to 1,000 tasks with each request, up to 10,000 tasks per batch. 3. Submit the batch for processing. Until a batch is submitted for processing, no tasks are attempted. 4. You may retrieve the batch to view progress details while it processes, or register for the async_batch/processed webhook to receive immediate notification of batch completion. 5. Page through the tasks in the batch to view results of each completed or failed task. Related guides: Examples of Async batches" }, { "name": "Async batch Tasks", "description": "Most commonly, the response from listing tasks on an async_batch id will be identical to the body of a singular request to standard Recharge API endpoints. However, in some instances there are variations from the standard list task response body. See below for examples corresponding to each batch_type. Related guides: Examples of async batches" }, { "name": "Token information", "description": "This resource allows a caller to inspect basic information regarding the token in use. It will only return a single object related to the calling token ( ie - a call with api_token.id=1 will only return information regarding api_token.id=1 ." }, { "name": "Accounts", "description": "This resource allows a caller to inspect basic information regarding the staff accounts in the store." }, { "name": "Events", "description": "This resource allows a caller to inspect recent events in the store." } ], "paths": { "/addresses": { "post": { "operationId": "create_address", "summary": "Create an address", "description": "Create a new address for a customer.", "tags": [ "Addresses" ], "responses": { "201": { "description": "OK: The request was successful, created a new resource, and resource created is in the body.", "content": { "application/json": { "example": { "address": { "id": 42171447, "address1": "1030 Barnum Ave", "address2": "Suite 101", "city": "Stratford", "company": "Fake Company", "country_code": "US", "created_at": "2022-10-12T20:16:09+00:00", "customer_id": 37657002, "discounts": [], "first_name": "Fake First", "last_name": "Fake Last", "order_attributes": [ { "name": "custom name", "value": "custom value" } ], "order_note": "My recurring order note", "phone": "999-999-9999", "presentment_currency": "USD", "province": "Connecticut", "shipping_lines_conserved": [], "shipping_lines_override": [], "updated_at": "2022-10-12T20:16:09+00:00", "zip": "06614" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "custom_event_attributes": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "A user-defined key for the custom attribute." }, "value": { "type": "string", "description": "A user-defined value for the custom attribute. Maximum length is 255 characters." } } }, "description": "A 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 ." }, "customer_id": { "type": "integer", "description": "Unique numeric identifier for the customer associated with the address." }, "address1": { "type": "string", "description": "The street associated with the Address . Minimum length is 1 character." }, "address2": { "type": "string", "description": "Any additional information associated with the shipping address." }, "city": { "type": "string", "description": "The city associated with the shipping address." }, "company": { "type": "string", "description": "The company associated with the shipping address." }, "country_code": { "type": "string", "description": "2-letter country code." }, "discounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "The id of the Discount to apply to the Address ." }, "code": { "type": "string", "description": "The code of the Discount to apply to the Address . Used when id is not passed." } } }, "description": "A discount to apply to the Address . While the discounts parameter is an array, only the first discount is applied." }, "first_name": { "type": "string", "description": "The customer’s first name associated with the address. Minimum length is 1 character." }, "is_gift": { "type": "boolean", "description": "Whether the Address is a gift address." }, "last_name": { "type": "string", "description": "The customer’s last name associated with the address. Minimum length is 1 character." }, "order_attributes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name for the attribute." }, "value": { "type": "string", "description": "The value for the associated attribute." } } }, "description": "Extra information that is added to the order." }, "order_note": { "type": "string", "description": "Notes to be added to all orders associated with the address." }, "payment_method_id": { "type": "integer", "description": "Payment method id for the Payment_method to be associated to this address." }, "phone": { "type": "string", "description": "The phone number associated with the address. Must be included in the request schema but can be an empty string." }, "presentment_currency": { "type": "string", "description": "The currency that charges on this address will be processed in. If no presentment_currency is passed, it will be set to your default store currency." }, "province": { "type": "string", "description": "The state or province associated with the address. Check if country requires a province COUNTRIES_REQUIRING_PROVINCE ." }, "shipping_lines_override": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "The code of the associated shipping line." }, "price": { "type": "string", "description": "The price (in store’s currency) of the associated shipping line." }, "title": { "type": "string", "description": "The title of the associated shipping line." } } }, "description": "Used when shipping rates need to be overridden. If this parameter has value null , rates will be fetched when a related Charge is created or regenerated" }, "zip": { "type": "string", "description": "The zip or postal code associated with the address." } }, "required": [ "customer_id", "address1", "city", "country_code", "first_name", "last_name", "province", "zip" ] }, "example": { "customer_id": 22152215, "address1": "1776 Washington Street", "address2": "", "city": "Los Angeles", "company": "Recharge", "country_code": "US", "first_name": "John", "last_name": "Doe", "order_attributes": [ { "name": "custom name", "value": "custom value" } ], "phone": "5551234567", "presentment_currency": "USD", "province": "California", "zip": "90404" } } } }, "x-recharge-scopes": [ "write_customers" ] }, "get": { "operationId": "list_addresses", "summary": "List addresses", "description": "Returns all addresses from the store, or addresses for the user given in the parameter. HTTP examples GET /addresses GET /addresses?customer_id= GET /addresses?discount_id= GET /addresses?discount_code=", "tags": [ "Addresses" ], "parameters": [ { "name": "created_at_max", "in": "query", "required": false, "description": "Returns addresses created before the given time.", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at_min", "in": "query", "required": false, "description": "Returns addresses created after the given time.", "schema": { "type": "string", "format": "date-time" } }, { "name": "cursor", "in": "query", "required": false, "description": "The 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.", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "required": false, "description": "Unique identifier of the customer.", "schema": { "type": "integer" } }, { "name": "discount_code", "in": "query", "required": false, "description": "Returns addresses that have the provided discount_code.", "schema": { "type": "string" } }, { "name": "discount_id", "in": "query", "required": false, "description": "Returns addresses that have the provided discount_id.", "schema": { "type": "integer" } }, { "name": "ids", "in": "query", "required": false, "description": "Filter addresses by id. If passing multiple values, must be comma separated. Non-integer values will result in a 422 error", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "A 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.", "schema": { "type": "string", "enum": [ "customer", "payment_methods", "subscriptions", "discount", "onetimes", "charge_activities" ] } }, { "name": "limit", "in": "query", "required": false, "description": "The amount of results. Default is 50 while the maximum is 250.", "schema": { "type": "string", "default": 50 } }, { "name": "orders_count", "in": "query", "required": false, "description": "Returns addresses that have exactly the given number of processed charges. A value of 0 is ignored.", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "The page to show. Default is 1.", "schema": { "type": "string", "deprecated": true, "default": 1 } }, { "name": "payment_method_id", "in": "query", "required": false, "description": "Returns addresses associated with the given Payment Method .", "schema": { "type": "integer" } }, { "name": "sort_by", "in": "query", "required": false, "description": "Sort order of the results. Default is id-desc .", "schema": { "type": "string", "enum": [ "id-asc", "id-desc", "updated_at-asc", "updated_at-desc" ] } }, { "name": "updated_at_max", "in": "query", "required": false, "description": "Returns addresses updated before the given date.", "schema": { "type": "string" } }, { "name": "updated_at_min", "in": "query", "required": false, "description": "Returns addresses updated after the given time.", "schema": { "type": "string" } }, { "name": "is_active", "in": "query", "required": false, "description": "Returns active addresses.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "addresses": [ { "id": 42171447, "payment_method_id": 17874235, "address1": "1030 Barnum Ave", "address2": "Suite 101", "city": "Stratford", "company": "Fake Company", "country_code": "US", "created_at": "2022-10-12T20:16:09+00:00", "customer_id": 37657002, "discounts": [ { "id": 123456 } ], "first_name": "Fake First", "last_name": "Fake Last", "order_attributes": [ { "name": "custom name", "value": "custom value" } ], "order_note": "My recurring order note", "phone": "999-999-9999", "presentment_currency": "USD", "province": "Connecticut", "shipping_lines_conserved": [], "shipping_lines_override": [ { "code": "Standard Shipping", "price": "0.00", "title": "Standard Shipping" } ], "updated_at": "2022-10-12T20:16:09+00:00", "zip": "06614" } ] } } } } }, "x-recharge-scopes": [ "read_customers" ] } }, "/addresses/{id}": { "get": { "operationId": "retrieve_address", "summary": "Retrieve an address", "description": "Retrieves address for customer based on specified address id.", "tags": [ "Addresses" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "A comma-separated list of related resources to embed in the include attribute of each Address .", "schema": { "type": "string", "enum": [ "customer", "payment_methods", "subscriptions", "discount", "onetimes", "charge_activities" ] } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "address": { "id": 42171447, "payment_method_id": 17874235, "address1": "1030 Barnum Ave", "address2": "Suite 101", "city": "Stratford", "company": "Fake Company", "country_code": "US", "created_at": "2022-10-12T20:16:09+00:00", "customer_id": 37657002, "discounts": [], "first_name": "Fake First", "last_name": "Fake Last", "order_attributes": [ { "name": "custom name", "value": "custom value" } ], "order_note": "My recurring order note", "phone": "999-999-9999", "presentment_currency": "USD", "province": "Connecticut", "shipping_lines_conserved": [], "shipping_lines_override": [], "updated_at": "2022-10-12T20:16:09+00:00", "zip": "06614" } } } } } }, "x-recharge-scopes": [ "read_customers" ] }, "put": { "operationId": "update_address", "summary": "Update an address", "description": "Updates an existing address to match the specified parameters. Example: remove discounts from an address To remove all discounts from an address, set the discounts parameter to an empty array: {\"discounts\": []}", "tags": [ "Addresses" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "commit", "in": "query", "required": false, "description": "Controls 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.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "address": { "id": 42171447, "payment_method_id": 17874235, "address1": "1030 Barnum Ave", "address2": "Suite 101", "city": "Stratford", "company": "Fake Company", "country_code": "US", "created_at": "2022-10-12T20:16:09+00:00", "customer_id": 37657002, "discounts": [], "first_name": "Fake First", "last_name": "Fake Last", "order_attributes": [ { "name": "custom name", "value": "custom value" } ], "order_note": "My recurring order note", "phone": "999-999-9999", "presentment_currency": "USD", "province": "Connecticut", "shipping_lines_conserved": [], "shipping_lines_override": [], "updated_at": "2022-10-12T20:16:09+00:00", "zip": "06614" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "address1": { "type": "string", "description": "The street associated with the Address . Minimum length is 1 character." }, "address2": { "type": "string", "description": "Any additional information associated with the shipping address." }, "city": { "type": "string", "description": "The city associated with the shipping address. Minimum length is 1 character." }, "company": { "type": "string", "description": "The company associated with the shipping address." }, "country_code": { "type": "string", "description": "2-letter country code." }, "custom_event_attributes": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "A user-defined key for the custom attribute." }, "value": { "type": "string", "description": "A user-defined value for the custom attribute. Maximum length is 255 characters." } } }, "description": "A 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 ." }, "discounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "The id of a discount associated with this address." }, "code": { "type": "string", "description": "The code of the Discount to apply to the Address . Used when id is not passed." } } }, "description": "A discount which will be applied on the address. While the discounts parameter is an array, only a single discount code will be applied. If multiple discount codes are provided, only the first discount in the array will apply to the address." }, "first_name": { "type": "string", "description": "The customer’s first name associated with the address. Minimum length is 1 character." }, "last_name": { "type": "string", "description": "The customer’s last name associated with the address. Minimum length is 1 character." }, "order_attributes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name for the attribute." }, "value": { "type": "string", "description": "The value for the associated attribute." } } }, "description": "Extra information that is added to the order." }, "order_note": { "type": "string", "description": "Notes to be added to all orders associated with the address." }, "payment_method_id": { "type": "integer", "description": "Payment method id for the Payment_method to be associated to this address." }, "phone": { "type": "string", "description": "The phone number associated with the address. Must be included in the request schema but can be an empty string." }, "province": { "type": "string", "description": "The state or province associated with the address. Check if country requires a province COUNTRIES_REQUIRING_PROVINCE ." }, "shipping_lines_override": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "The code of the associated shipping line." }, "price": { "type": "string", "description": "The price (in store’s currency) of the associated shipping line." }, "title": { "type": "string", "description": "The title of the associated shipping line." } } }, "description": "Used when shipping rates need to be overridden. If this parameter has value null , rates will be fetched when a related Charge is created or regenerated." }, "zip": { "type": "string", "description": "The zip or postal code associated with the address. Check if the country requires a zip code COUNTRIES_NOT_REQUIRING_ZIP . If not included in the list then a zip code with the minimum length of 1 character is required. If the country is United States then validate against regex UNITED_STATES_ZIP_REGEX . If country is United Kingdom then validate against regex UNITED_KINGDOM_ZIP_REGEX ." } } }, "example": { "address1": "1776 Washington Street" } } } }, "x-recharge-scopes": [ "write_customers" ] }, "delete": { "operationId": "delete_address", "summary": "Delete an address", "description": "It is possible to delete certain addresses from the store using API.", "tags": [ "Addresses" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Content Deleted: The server has successfully fulfilled the request and deleted the desired object and there is no content to send in the response body.", "content": { "application/json": { "example": {} } } } }, "x-recharge-scopes": [ "write_customers" ] } }, "/addresses/merge": { "post": { "operationId": "merge_addresses", "summary": "Merge addresses", "description": "Merges up to 10 source addresses into 1 target address.", "tags": [ "Addresses" ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "address": { "id": 42171447, "payment_method_id": 17874235, "address1": "1030 Barnum Ave", "address2": "Suite 101", "city": "Stratford", "company": "Fake Company", "country_code": "US", "created_at": "2022-10-12T20:16:09+00:00", "customer_id": 37657002, "discounts": [], "first_name": "Fake First", "last_name": "Fake Last", "order_attributes": [ { "name": "custom name", "value": "custom value" } ], "order_note": "My recurring order note", "phone": "999-999-9999", "presentment_currency": "USD", "province": "Connecticut", "shipping_lines_conserved": [], "shipping_lines_override": [], "updated_at": "2022-10-12T20:16:09+00:00", "zip": "06614" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "delete_source_addresses": { "type": "boolean", "description": "Indicates whether source addresses should be deleted." }, "next_charge_date": { "type": "string", "description": "Specifies the next charge date of the associated subscriptions on the target address." }, "target_address": { "type": "object", "properties": { "id": { "type": "integer", "description": "The id of the address." } }, "description": "The address all of the subscriptions should be moved to." }, "source_addresses": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "The id of the address." } } }, "description": "The list of addresses that the subscriptions should move from." } }, "required": [ "target_address", "source_addresses" ] }, "example": { "target_address": { "id": 42171447 }, "source_addresses": [ { "id": 42171446 }, { "id": 42171445 } ] } } } }, "x-recharge-scopes": [ "write_customers" ] } }, "/addresses/{id}/charges/skip": { "post": { "operationId": "skip_future_charge_address", "summary": "Skip future charge", "description": "Skip a Charge in the future for one or multiple Subscriptions associated with the Address .", "tags": [ "Addresses" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "charge": { "id": 377749210, "address_id": 42171447, "analytics_data": { "utm_params": [ { "utm_source": "facebook", "utm_medium": "cpc" } ] }, "billing_address": { "address1": "601 SW Washing St.", "address2": "Suite 101", "city": "Portland", "company": "Acme Corp", "country_code": "US", "first_name": "Jane", "last_name": "Doe", "phone": "888-888-8888", "province": "Oregon", "zip": "97205" }, "client_details": { "browser_ip": "192.168.0.1", "user_agent": "safari webkit" }, "created_at": "2021-11-09T19:22:13+00:00", "currency": "USD", "customer": { "id": 37657002, "email": "test@test.com", "external_customer_id": { "ecommerce": "2879413682227" }, "hash": "7e706455cbd13e40" }, "discounts": [ { "id": 12345, "code": "TESTCODE10", "value": 10, "value_type": "fixed_amount" } ], "error": null, "error_type": null, "external_order_id": { "ecommerce": "2541635698739" }, "external_transaction_id": { "payment_processor": "ch_1HzWElJ2zqHvZRd1TWKFFqDR" }, "has_uncommitted_changes": false, "line_items": [ { "purchase_item_id": 63898947, "external_product_id": { "ecommerce": "4381728735283" }, "external_variant_id": { "ecommerce": "999999999999" }, "grams": 454, "handle": "shirt-package", "images": { "large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg", "medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg", "original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg", "small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg" }, "original_price": "10.00", "properties": [ { "name": "Color", "value": "Blue" } ], "purchase_item_type": "subscription", "quantity": 1, "sku": "TOM0001", "tax_due": "1.30", "tax_lines": [ { "price": "0.9931", "rate": "0.0725", "title": "CA State Tax", "unit_price": "0.3310" }, { "price": "0.3082", "rate": "0.0225", "title": "LA County Tax", "unit_price": "0.1027" } ], "taxable": true, "taxable_amount": "10.00", "title": "Shirt package", "total_price": "11.30", "unit_price": "10.00", "unit_price_includes_tax": false, "variant_title": "Blue T-shirt" } ], "note": "next order in sequence 3", "order_attributes": [ { "name": "Checkout-Method", "value": "delivery" } ], "orders_count": 1, "payment_processor": "stripe", "processed_at": null, "retry_date": null, "scheduled_at": "2021-12-09", "shipping_address": { "address1": "1030 Barnum Ave", "address2": "Suite 101", "city": "Stratford", "company": "Fake Company", "country_code": "US", "first_name": "Fake First", "last_name": "Fake Last", "phone": "999-999-9999", "province": "Connecticut", "zip": "06614" }, "shipping_lines": [ { "code": "Standard", "price": "4.90", "source": "shopify", "taxable": true, "tax_lines": [ { "price": "0.355", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.110", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "title": "Standard" } ], "status": "skipped", "subtotal_price": "10.00", "tags": "Subscription, Subscription Recurring Order", "tax_lines": [ { "price": "0.950", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.335", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "taxable": true, "total_discounts": "10.0", "total_line_items_price": "10.00", "total_price": "11.29", "total_refunds": "0.00", "total_tax": "1.29", "total_weight_grams": 454, "type": "recurring", "updated_at": "2021-11-09T23:59:32+00:00" } } } } }, "404": { "description": "the Address with id does not exist", "content": { "application/json": { "example": { "error": "address not found" } } } }, "422": { "description": "invalid data passed to the endpoint", "content": { "application/json": { "example": { "errors": { "date": [ "Date must be at least one day in the future" ] } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "The date in the future of the Charge to be skipped." }, "subscription_ids": { "type": "array", "items": {}, "description": "A list containing the Subscription IDs to be skipped." } }, "required": [ "date", "subscription_ids" ] }, "example": { "date": "2022-09-15", "purchase_item_ids": [ 27363808, 27363809 ] } } } }, "x-recharge-scopes": [ "write_orders" ] } }, "/addresses/validate": { "post": { "operationId": "validate_address", "summary": "Validate an address", "description": "Validates that the zip code and state of a US address match. Returns 200 with the normalized state and zip code when the address is valid, and 422 with an errors object when it is not. No specific scope is required.", "tags": [ "Addresses" ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "city": "santa monica", "state": "CA", "state_name": "California", "zipcode": "90404", "errors": {} } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "address1": { "type": "string", "description": "The street associated with the address." }, "address2": { "type": "string", "description": "Any additional information associated with the address." }, "city": { "type": "string", "description": "The city associated with the address." }, "province": { "type": "string", "description": "The state associated with the address. Accepts the full name or the 2-letter abbreviation." }, "zip": { "type": "string", "description": "The zip code associated with the address, in the 5 digit or 5-4 format." } } } } } } } }, "/bundle_products": { "get": { "operationId": "bundle_products_list", "summary": "List bundle products", "description": "Returns a list of the Bundle Products of the store.", "tags": [ "Bundle products" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "The number of results to return. Defaults to 50; the maximum is 250.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The 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 .", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "The page of results to show. Page-based pagination is deprecated in favor of cursor .", "schema": { "type": "integer" } }, { "name": "sort_by", "in": "query", "required": false, "description": "The order in which the bundle products are returned. Defaults to id-desc .", "schema": { "type": "string", "enum": [ "id-asc", "id-desc", "updated_at-asc", "updated_at-desc" ] } }, { "name": "external_product_ids", "in": "query", "required": false, "description": "Filter bundle products by external_product_id . If passing multiple values, must be comma separated.", "schema": { "type": "string" } }, { "name": "created_at_min", "in": "query", "required": false, "description": "Return the bundle products created after the given date.", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at_max", "in": "query", "required": false, "description": "Return the bundle products created before the given date.", "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_at_min", "in": "query", "required": false, "description": "Return the bundle products updated after the given date.", "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_at_max", "in": "query", "required": false, "description": "Return the bundle products updated before the given date.", "schema": { "type": "string", "format": "date-time" } }, { "name": "price_rules", "in": "query", "required": false, "description": "Filter bundle products by kind. If passing multiple values, must be comma separated. preset returns bundles that are not customizable; fixed and dynamic return customizable bundles with that price_rule .", "schema": { "type": "string", "enum": [ "preset", "fixed", "dynamic" ] } }, { "name": "reset_box_contents", "in": "query", "required": false, "description": "Return the bundle products with the given reset_box_contents value.", "schema": { "type": "boolean" } }, { "name": "published", "in": "query", "required": false, "description": "Return only the bundle products that are published ( true ) or not published ( false ).", "schema": { "type": "boolean" } }, { "name": "search_term", "in": "query", "required": false, "description": "Return the bundle products whose title contains the given text.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "next_cursor": null, "previous_cursor": null, "bundle_products": [ { "id": 51842, "created_at": "2026-03-02T15:04:31+00:00", "custom_prices": false, "customization_window": null, "customization_window_disabled_message": null, "default_bundle_variant_id": null, "delivery_cycles": {}, "delivery_cycles_version": "2021-11", "description": null, "external_product_id": "7654321098", "is_customizable": true, "layout_settings": {}, "layout_settings_version": "2021-11", "max_quantity_per_variant": 5, "price_rule": "fixed", "reset_box_contents": false, "settings": { "display_variants_as_separate_products_in_list": false, "dynamic_filter_products_by_discount": false, "show_product_and_variant_name_in_products_list": false }, "title": "Build your own coffee box", "updated_at": "2026-03-02T15:04:31+00:00", "variants": [ { "id": 90411, "created_at": "2026-03-02T15:04:31+00:00", "enabled": true, "external_variant_id": "44100001", "items_count": 6, "option_sources": [ { "id": 77120, "created_at": "2026-03-02T15:04:31+00:00", "option_source_id": "301234567890", "position": 1, "quantity_max": 6, "quantity_min": 1, "source_platform": "shopify", "updated_at": "2026-03-02T15:04:31+00:00" } ], "position": 0, "ranges": [ { "id": 3310, "created_at": "2026-03-02T15:04:31+00:00", "quantity_max": 6, "quantity_min": 6, "updated_at": "2026-03-02T15:04:31+00:00" } ], "selection_defaults": [ { "id": 66204, "created_at": "2026-03-02T15:04:31+00:00", "external_variant_id": "44100777", "quantity": 6, "updated_at": "2026-03-02T15:04:31+00:00" } ], "title": "6 bags", "updated_at": "2026-03-02T15:04:31+00:00" } ] } ] } } } } }, "x-recharge-scopes": [ "read_bundle_products" ] } }, "/bundle_products/{id}": { "get": { "operationId": "bundle_products_retrieve", "summary": "Retrieve a bundle product", "description": "Retrieves a single Bundle Product by its id. Returns a 404 when it does not exist or has been deleted.", "tags": [ "Bundle products" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "bundle_product": { "id": 51842, "created_at": "2026-03-02T15:04:31+00:00", "custom_prices": false, "customization_window": null, "customization_window_disabled_message": null, "default_bundle_variant_id": null, "delivery_cycles": {}, "delivery_cycles_version": "2021-11", "description": null, "external_product_id": "7654321098", "is_customizable": true, "layout_settings": {}, "layout_settings_version": "2021-11", "max_quantity_per_variant": 5, "price_rule": "fixed", "reset_box_contents": false, "settings": { "display_variants_as_separate_products_in_list": false, "dynamic_filter_products_by_discount": false, "show_product_and_variant_name_in_products_list": false }, "title": "Build your own coffee box", "updated_at": "2026-03-02T15:04:31+00:00", "variants": [ { "id": 90411, "created_at": "2026-03-02T15:04:31+00:00", "enabled": true, "external_variant_id": "44100001", "items_count": 6, "option_sources": [ { "id": 77120, "created_at": "2026-03-02T15:04:31+00:00", "option_source_id": "301234567890", "position": 1, "quantity_max": 6, "quantity_min": 1, "source_platform": "shopify", "updated_at": "2026-03-02T15:04:31+00:00" } ], "position": 0, "ranges": [ { "id": 3310, "created_at": "2026-03-02T15:04:31+00:00", "quantity_max": 6, "quantity_min": 6, "updated_at": "2026-03-02T15:04:31+00:00" } ], "selection_defaults": [ { "id": 66204, "created_at": "2026-03-02T15:04:31+00:00", "external_variant_id": "44100777", "quantity": 6, "updated_at": "2026-03-02T15:04:31+00:00" } ], "title": "6 bags", "updated_at": "2026-03-02T15:04:31+00:00" } ] } } } } } }, "x-recharge-scopes": [ "read_bundle_products" ] } }, "/bundle_selections": { "get": { "operationId": "bundle_selection_list", "summary": "List bundle selections", "description": "Returns a list of BundleSelections . HTTP request examples GET /bundle_selections?purchase_item_ids=:purchase_item_id_1,:purchase_item_id_2 GET /bundle_selections?bundle_variant_ids=:bundle_variant_id_1,:bundle_variant_id_2 GET /bundle_selections?limit=1 GET /bundle_selections?limit=1&page=2 GET /bundle_selections?sort_by=updated_at-desc Returned BundleSelections are sorted descending by ID value by default.", "tags": [ "Bundle Selections" ], "parameters": [ { "name": "purchase_item_ids", "in": "query", "required": false, "description": "Filter BundleSelections by Subscription or Onetime ID.", "schema": { "type": "string" } }, { "name": "bundle_variant_ids", "in": "query", "required": false, "description": "Filter BundleSelections by BundleVariants .", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "The amount of results.", "schema": { "type": "string", "default": 50 } }, { "name": "page", "in": "query", "required": false, "description": "The page to show.", "schema": { "type": "string", "deprecated": true, "default": 1 } }, { "name": "sort_by", "in": "query", "required": false, "description": "Sort listed BundleSelections in a specific order. Available sort options: id-asc , id-desc , updated_at-asc , updated_at-desc .", "schema": { "type": "string" } }, { "name": "active_purchase_items", "in": "query", "required": false, "description": "Bundle selections are not directly linked to Subscriptions. By default, the endpoint returns Bundle Selections, even those associated with cancelled subscriptions, unless the Bundle Selection has been deleted. To exclude cancelled subscriptions from your results, include active_purchase_items=true in your query.", "schema": { "type": "boolean" } }, { "name": "updated_at_min", "in": "query", "required": false, "description": "Show BundleSelections updated after the given date.", "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_at_max", "in": "query", "required": false, "description": "Show BundleSelections updated before the given date.", "schema": { "type": "string", "format": "date-time" } }, { "name": "cursor", "in": "query", "required": false, "description": "Return 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 .", "schema": { "type": "string" } }, { "name": "charge_ids", "in": "query", "required": false, "description": "Filter BundleSelections by Charge ID. If passing multiple values, must be comma separated.", "schema": { "type": "string" } }, { "name": "item_external_product_ids", "in": "query", "required": false, "description": "Filter BundleSelections that contain an item with one of the given external product IDs. If passing multiple values, must be comma separated.", "schema": { "type": "string" } }, { "name": "item_external_variant_ids", "in": "query", "required": false, "description": "Filter BundleSelections that contain an item with one of the given external variant IDs. If passing multiple values, must be comma separated.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "next_cursor": null, "previous_cursor": null, "bundle_selections": [ { "id": 100714428, "bundle_variant": 382417, "purchase_item_id": 199820883, "created_at": "2022-08-26T18:31:28+00:00", "external_product_id": "7121697210548", "external_variant_id": "41450875650228", "items": [ { "id": 541, "collection_id": "287569608884", "collection_source": "shopify", "created_at": "2022-08-26T18:31:28+00:00", "external_product_id": "7121693671604", "external_variant_id": "41450853105844", "price": "10.00", "quantity": 3, "updated_at": "2022-08-26T18:52:41+00:00" } ], "updated_at": "2022-08-26T18:31:28+00:00", "charge_id": null, "order_id": null, "items_count": 3 } ] } } } } }, "x-recharge-scopes": [ "read_subscriptions" ] }, "post": { "operationId": "bundle_selection_create", "summary": "Create a bundle selection", "description": "Create a BundleSelection .", "tags": [ "Bundle Selections" ], "parameters": [ { "name": "commit", "in": "query", "required": false, "description": "Controls whether the QUEUED charges linked to the purchase item are regenerated before the response is returned ( true , default) or in the background ( false ).", "schema": { "type": "boolean" } }, { "name": "skip_remote_validation", "in": "query", "required": false, "description": "If true , the selected items are not validated against the external e-commerce platform.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "bundle_selection": { "id": 100714428, "bundle_variant": 382417, "purchase_item_id": 199820883, "created_at": "2022-08-26T18:31:28+00:00", "external_product_id": "7121697210548", "external_variant_id": "41450875650228", "items": [ { "id": 541, "collection_id": "287569608884", "collection_source": "shopify", "created_at": "2022-08-26T18:31:28+00:00", "external_product_id": "7121693671604", "external_variant_id": "41450853105844", "price": "10.00", "quantity": 3, "updated_at": "2022-08-26T18:52:41+00:00" } ], "updated_at": "2022-08-26T18:31:28+00:00", "charge_id": null, "order_id": null, "items_count": 3 } } } } }, "422": { "description": "missing required field or invalid items passed", "content": { "application/json": { "example": { "errors": { "bundle_variant_id": [ "Bundle variant 41450853105840 does not exist" ] } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "purchase_item_id": { "type": "integer", "description": "The ID of the PurchaseItem associated with the BundleSelection ." }, "plan_id": { "type": "integer", "description": "A Recharge Plan ID. If provided in a dynamically-priced Bundle, the unit price of each product variant will be inferred from the plan associated with the ID; otherwise, it will be inferred from the plan with the greatest discount for each product in the selection. This is not used in fixed-priced Bundles." }, "items": { "type": "array", "items": { "type": "object", "properties": { "collection_id": { "type": "string", "description": "The collection id as it appears in the external e-commerce platform." }, "collection_source": { "type": "string", "description": "The identifier of the external e-commerce platform." }, "external_product_id": { "type": "string", "description": "The product id as it appears in the external e-commerce platform. This is the item which is going to be extracted when the Bundle is processed." }, "external_variant_id": { "type": "string", "description": "The variant id as it appears in the external e-commerce platform. This is the item which is going to be extracted when the Bundle is processed." }, "price": { "type": "string", "description": "The price of the item. Must not be negative." }, "quantity": { "type": "integer", "description": "The quantity of this product." } }, "required": [ "collection_id", "external_product_id", "external_variant_id", "quantity" ] }, "description": "A list of item objects, each containing information about a distinct product selected as part of the Bundle." }, "charge_id": { "type": "integer", "description": "The ID of the upcoming Charge the BundleSelection applies to. The charge must be in QUEUED status." }, "order_id": { "type": "integer", "description": "The ID of the Order the BundleSelection applies to. Requires charge_id , and the order must belong to that charge." } }, "required": [ "purchase_item_id", "items" ] }, "example": { "purchase_item_id": 199820883, "items": [ { "collection_id": "287569608884", "collection_source": "shopify", "external_product_id": "7121693671604", "external_variant_id": "41450853105844", "quantity": 3 } ] } } } }, "x-recharge-scopes": [ "write_subscriptions" ] } }, "/bundle_selections/{id}": { "get": { "operationId": "bundle_selection_retrieve", "summary": "Retrieve a bundle selection", "description": "Retrieve a BundleSelection using the bundle_selection_id .", "tags": [ "Bundle Selections" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "bundle_selection": { "id": 100714428, "bundle_variant": 382417, "purchase_item_id": 199820883, "created_at": "2022-08-26T18:31:28+00:00", "external_product_id": "7121697210548", "external_variant_id": "41450875650228", "items": [ { "id": 541, "collection_id": "287569608884", "collection_source": "shopify", "created_at": "2022-08-26T18:31:28+00:00", "external_product_id": "7121693671604", "external_variant_id": "41450853105844", "price": "10.00", "quantity": 3, "updated_at": "2022-08-26T18:52:41+00:00" } ], "updated_at": "2022-08-26T18:31:28+00:00", "charge_id": null, "order_id": null, "items_count": 3 } } } } }, "404": { "description": "the BundleSelection with bundle_selection_id does not exist", "content": { "application/json": { "example": { "error": "Bundle Selection not found" } } } } }, "x-recharge-scopes": [ "read_subscriptions" ] }, "put": { "operationId": "bundle_selection_update", "summary": "Update a bundle selection", "description": "Modify an existing BundleSelection to match the specified parameters.", "tags": [ "Bundle Selections" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "commit", "in": "query", "required": false, "description": "Controls whether the QUEUED charges linked to the purchase item are regenerated before the response is returned ( true , default) or in the background ( false ).", "schema": { "type": "boolean" } }, { "name": "skip_remote_validation", "in": "query", "required": false, "description": "If true , the selected items are not validated against the external e-commerce platform.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "bundle_selection": { "id": 100714428, "bundle_variant": 382417, "purchase_item_id": 199820883, "created_at": "2022-08-26T18:31:28+00:00", "external_product_id": "7121697210548", "external_variant_id": "41450875650228", "items": [ { "id": 541, "collection_id": "287569608884", "collection_source": "shopify", "created_at": "2022-08-26T18:31:28+00:00", "external_product_id": "7121693671604", "external_variant_id": "41450853105844", "price": "10.00", "quantity": 3, "updated_at": "2022-08-26T18:52:41+00:00" } ], "updated_at": "2022-08-26T18:31:28+00:00", "charge_id": null, "order_id": null, "items_count": 3 } } } } }, "404": { "description": "the BundleSelection with bundle_selection_id does not exist", "content": { "application/json": { "example": { "error": "Bundle Selection not found" } } } }, "422": { "description": "invalid items passed", "content": { "application/json": { "example": { "errors": { "bundle_variant_id": [ "Bundle variant 41450853105840 not found" ] } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "plan_id": { "type": "integer", "description": "A Recharge Plan ID. If provided in a dynamically-priced Bundle, the unit price of each product variant will be inferred from the plan associated with the ID; otherwise, it will be inferred from the plan with the greatest discount for each product in the selection. This is not used in fixed-priced Bundles." }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique numeric identifier of an existing item selection to update. Items sent without an id are created." }, "collection_id": { "type": "string", "description": "The collection id as it appears in the external e-commerce platform." }, "external_product_id": { "type": "string", "description": "The product id as it appears in the external e-commerce platform." }, "external_variant_id": { "type": "string", "description": "The variant id as it appears in the external e-commerce platform." }, "price": { "type": "string", "description": "The price of the item. Must not be negative." }, "quantity": { "type": "integer", "description": "The quantity of this product." } }, "required": [ "collection_id", "external_product_id", "external_variant_id", "quantity" ] }, "description": "A list of item objects, each containing information about a distinct product selected as part of the Bundle." } } }, "example": { "purchase_item_id": 199820883, "items": [ { "collection_id": "287569608884", "collection_source": "shopify", "external_product_id": "7121693671604", "external_variant_id": "41450853105844", "quantity": 3 } ] } } } }, "x-recharge-scopes": [ "write_subscriptions" ] }, "delete": { "operationId": "bundle_selection_delete", "summary": "Delete a bundle selection", "description": "Delete a BundleSelection", "tags": [ "Bundle Selections" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "commit", "in": "query", "required": false, "description": "Controls whether the QUEUED charges linked to the purchase item are regenerated before the response is returned ( true , default) or in the background ( false ).", "schema": { "type": "boolean" } } ], "responses": { "204": { "description": "the BundleSelection has been removed and there is no content to send back in the response body.", "content": { "application/json": { "example": {} } } }, "404": { "description": "the BundleSelection with id does not exist", "content": { "application/json": { "example": { "error": "Bundle Selection not found" } } } } }, "x-recharge-scopes": [ "write_subscriptions" ] } }, "/charge_activities": { "get": { "operationId": "charge_activity_list", "summary": "List charge activities", "description": "Returns a list of charge activities created in the last 90 days. Either the read_orders or the read_payment_methods scope is sufficient.", "tags": [ "Charge activities" ], "parameters": [ { "name": "ids", "in": "query", "required": false, "description": "Filter charge activities by a comma-separated list of IDs.", "schema": { "type": "string" } }, { "name": "charge_id", "in": "query", "required": false, "description": "Filter charge activities by Charge .", "schema": { "type": "integer" } }, { "name": "address_id", "in": "query", "required": false, "description": "Filter charge activities by Address .", "schema": { "type": "integer" } }, { "name": "payment_method_id", "in": "query", "required": false, "description": "Filter charge activities by PaymentMethod .", "schema": { "type": "integer" } }, { "name": "activity_type", "in": "query", "required": false, "description": "Filter charge activities by activity_type , such as payment_failure .", "schema": { "type": "string" } }, { "name": "activity_sub_type", "in": "query", "required": false, "description": "Filter charge activities by activity_sub_type , such as card_declined .", "schema": { "type": "string" } }, { "name": "created_at_min", "in": "query", "required": false, "description": "Show charge activities created after the given date. Must be within the last 90 days, which is also the default.", "schema": { "type": "string" } }, { "name": "created_at_max", "in": "query", "required": false, "description": "Show charge activities created before the given date. Must be within the last 90 days and cannot be in the future.", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "A comma-separated list of related resources to return under the include attribute of each charge activity. payment_methods requires the read_payment_methods scope and charge requires the read_orders scope.", "schema": { "type": "string", "enum": [ "payment_methods", "charge" ] } }, { "name": "sort_by", "in": "query", "required": false, "description": "Sort listed charge activities in a specific order. Defaults to id-desc .", "schema": { "type": "string", "enum": [ "id-asc", "id-desc" ] } }, { "name": "limit", "in": "query", "required": false, "description": "The amount of results. The default is 50 and the maximum is 250.", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "The page to show. Page-based pagination is deprecated; use cursor instead.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor or previous_cursor value returned by a previous call, used to retrieve the next or previous page of results. When passed, the only other parameter that can be passed is limit .", "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "next_cursor": null, "previous_cursor": null, "charge_activities": [ { "id": 987654321, "address_id": 21317826, "charge_id": 100714428, "customer_id": 12345, "order_id": null, "payment_method_id": 55501, "store_id": 1234, "activity_details": { "charge_attempts": 1, "description": "Charge was successfully paid.", "links": {}, "payment_gateway": "stripe", "payment_transaction_id": "ch_XXXXXXXXXXXXXXX", "presentment_currency": "USD", "suggested_solution": "" }, "activity_sub_type": "attempt_success", "activity_type": "payment_success", "charge_amount": 13.14, "created_at": "2026-11-10T09:45:44+00:00", "external_payment_method_id": "pm_XXXXXXXXXXXXXXX", "payment_methods_info": [ { "payment_method_id": 55501, "payment_type": "CREDIT_CARD", "brand": "visa", "exp_month": 12, "exp_year": 2030, "last4": "4242" } ], "updated_at": "2026-11-10T09:45:44+00:00" } ] } } } } }, "x-recharge-scopes": [ "read_orders", "read_payment_methods" ] } }, "/charges/{id}": { "get": { "operationId": "charge_retrieve", "summary": "Retrieve a charge", "description": "Retrieve a Charge using the charge_id .", "tags": [ "Charges" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "A comma-separated list of related resources to return under the include attribute of the Charge . Each value also requires the read scope of the included resource ( credit_projection requires read_credit_summary ).", "schema": { "type": "string", "enum": [ "address", "bundle_selections", "charge_activities", "credit_projection", "customer", "metafields", "order_modifications", "payment_methods", "subscriptions", "transactions" ] } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "charge": { "id": 377749210, "address_id": 42171447, "analytics_data": { "utm_params": [ { "utm_source": "facebook", "utm_medium": "cpc" } ] }, "billing_address": { "address1": "601 SW Washing St.", "address2": "Suite 101", "city": "Portland", "company": "Acme Corp", "country_code": "US", "first_name": "Jane", "last_name": "Doe", "phone": "888-888-8888", "province": "Oregon", "zip": "97205" }, "client_details": { "browser_ip": "192.168.0.1", "user_agent": "safari webkit" }, "created_at": "2021-11-09T19:22:13+00:00", "currency": "USD", "customer": { "id": 37657002, "email": "test@test.com", "external_customer_id": { "ecommerce": "2879413682227" }, "hash": "7e706455cbd13e40" }, "discounts": [ { "id": 12345, "code": "TESTCODE10", "value": 10, "value_type": "fixed_amount" } ], "error": null, "error_type": null, "external_order_id": { "ecommerce": "2541635698739" }, "external_transaction_id": { "payment_processor": "ch_1HzWElJ2zqHvZRd1TWKFFqDR" }, "has_uncommitted_changes": false, "line_items": [ { "offer_attributes": null, "purchase_item_id": 63898947, "external_product_id": { "ecommerce": "4381728735283" }, "external_variant_id": { "ecommerce": "999999999999" }, "grams": 454, "handle": "shirt-package", "images": { "large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg", "medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg", "original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg", "small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg" }, "original_price": "10.00", "properties": [ { "name": "Color", "value": "Blue" } ], "purchase_item_type": "subscription", "quantity": 1, "sku": "TOM0001", "tax_due": "1.30", "tax_lines": [ { "price": "0.9931", "rate": "0.0725", "title": "CA State Tax", "unit_price": "0.3310" }, { "price": "0.3082", "rate": "0.0225", "title": "LA County Tax", "unit_price": "0.1027" } ], "taxable": true, "taxable_amount": "10.00", "title": "Shirt package", "total_price": "11.30", "unit_price": "10.00", "unit_price_includes_tax": false, "variant_title": "Blue T-shirt" } ], "merged_at": null, "note": "next order in sequence 3", "order_attributes": [ { "name": "Checkout-Method", "value": "delivery" } ], "orders_count": 1, "original_scheduled_at": "2021-12-09", "payment_processor": "stripe", "processed_at": "2021-11-09T23:59:31+00:00", "retry_date": "2021-01-01", "scheduled_at": "2021-12-09", "shipping_address": { "address1": "1030 Barnum Ave", "address2": "Suite 101", "city": "Stratford", "company": "Fake Company", "country_code": "US", "first_name": "Fake First", "last_name": "Fake Last", "phone": "999-999-9999", "province": "Connecticut", "zip": "06614" }, "shipping_lines": [ { "code": "Standard", "price": "4.90", "source": "shopify", "taxable": true, "tax_lines": [ { "price": "0.355", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.110", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "title": "Standard", "status": "active", "retrieved_at": null } ], "status": "success", "subtotal_price": "10.00", "tags": "Subscription, Subscription Recurring Order", "tax_lines": [ { "price": "0.950", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.335", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "taxable": true, "taxes_included": true, "total_discounts": "10.0", "total_duties": "0.00", "total_line_items_price": "10.00", "total_price": "11.29", "total_refunds": "0.00", "total_tax": "1.29", "total_weight_grams": 454, "type": "recurring", "updated_at": "2021-11-09T23:59:32+00:00" } } } } } }, "x-recharge-scopes": [ "read_orders" ] } }, "/charges": { "get": { "operationId": "charge_list", "summary": "List charges", "description": "Returns a list of Charges . HTTP request examples GET /charges?address_id=:address_id GET /charges?created_at_min=2016-05-18&created_at_max=2016-06-18 GET /charges?customer_id=:customer_id GET /charges?discount_code=10PERCENTOFF GET /charges?discount_id=:discount_id GET /charges?external_order_id=:external_order_id GET /charges?ids=1123551,262667345,12341535 GET /charges?purchase_item_id=:purchase_item_id GET /charges?scheduled_at=2016-06-18 GET /charges?scheduled_at_min=2016-05-18&scheduled_at_max=2016-06-18 GET /charges?sort_by=id-desc GET /charges?status=queued GET /charges?status=queued,refunded,partially_refunded GET /charges?updated_at_min=2016-05-18&updated_at_max=2016-06-18 GET /charges?processed_at_min=2022-01-18&processed_at_max=2022-02-18", "tags": [ "Charges" ], "parameters": [ { "name": "address_id", "in": "query", "required": false, "description": "Filter Charges by Address .", "schema": { "type": "string" } }, { "name": "created_at_max", "in": "query", "required": false, "description": "Show Charges created before the given date.", "schema": { "type": "string" } }, { "name": "created_at_min", "in": "query", "required": false, "description": "Show Charges created after the given date.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor or previous_cursor value returned by a previous call, used to retrieve the next or previous page of results. When passed, the only other parameter that can be passed is limit .", "schema": { "type": "string" } }, { "name": "customer_email", "in": "query", "required": false, "description": "Filter Charges by the email address of the Customer .", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "required": false, "description": "Filter Charges by Customer .", "schema": { "type": "string" } }, { "name": "discount_code", "in": "query", "required": false, "description": "List Charges that contain the given discount_code .", "schema": { "type": "string" } }, { "name": "discount_id", "in": "query", "required": false, "description": "List Charges that contain the given discount_id .", "schema": { "type": "string" } }, { "name": "error_type", "in": "query", "required": false, "description": "Filter Charges in error status by a comma-separated list of error types, such as CARD_DECLINED . Requires status to include error .", "schema": { "type": "string" } }, { "name": "external_order_id", "in": "query", "required": false, "description": "Filter Charges by the associated order ID in the external e-commerce platform.", "schema": { "type": "string" } }, { "name": "external_product_ids", "in": "query", "required": false, "description": "Filter Charges by a comma-separated list of product IDs, as they appear in the external e-commerce platform, contained in the Charge .", "schema": { "type": "string" } }, { "name": "external_variant_ids", "in": "query", "required": false, "description": "Filter Charges by a comma-separated list of variant IDs, as they appear in the external e-commerce platform, contained in the Charge .", "schema": { "type": "string" } }, { "name": "ids", "in": "query", "required": false, "description": "Filter Charges by ID.", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "A comma-separated list of related resources to return under the include attribute of each Charge . Each value also requires the read scope of the included resource.", "schema": { "type": "string", "enum": [ "address", "bundle_selections", "charge_activities", "customer", "metafields", "order_modifications", "payment_methods", "subscriptions", "transactions" ] } }, { "name": "limit", "in": "query", "required": false, "description": "The amount of results.", "schema": { "type": "string", "default": 50 } }, { "name": "not_error_type", "in": "query", "required": false, "description": "Exclude Charges whose error_type matches one of the given comma-separated values. Only Charges that have an error_type are returned.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "The page to show.", "schema": { "type": "string", "deprecated": true, "default": 1 } }, { "name": "purchase_item_id", "in": "query", "required": false, "description": "Filter Charges by a Subscription or Onetime ID.", "schema": { "type": "string" } }, { "name": "purchase_item_ids", "in": "query", "required": false, "description": "Filter Charges by a comma-separated list of Subscription or Onetime IDs.", "schema": { "type": "string" } }, { "name": "scheduled_at", "in": "query", "required": false, "description": "Filter Charges by specific scheduled charge date.", "schema": { "type": "string" } }, { "name": "scheduled_at_max", "in": "query", "required": false, "description": "Show Charges scheduled to be processed before the given date.", "schema": { "type": "string" } }, { "name": "scheduled_at_min", "in": "query", "required": false, "description": "Show Charges scheduled to be processed after the given date.", "schema": { "type": "string" } }, { "name": "sort_by", "in": "query", "required": false, "description": "Sort listed Charges in a specific order. Available sort options: id-asc , id-desc , updated_at-asc , updated_at-desc , scheduled_at-asc , scheduled_at-desc .", "schema": { "type": "string", "enum": [ "id-asc", "id-desc", "created_at-asc", "created_at-desc", "updated_at-asc", "updated_at-desc", "scheduled_at-asc", "scheduled_at-desc" ] } }, { "name": "status", "in": "query", "required": false, "description": "Filter charges by status. Available status: success , queued , error , refunded , partially_refunded , skipped , pending_manual_payment , pending .", "schema": { "type": "string", "enum": [ "success", "queued", "error", "refunded", "partially_refunded", "skipped", "pending_manual_payment", "pending_manual_payment_overdue", "pending" ] } }, { "name": "updated_at_max", "in": "query", "required": false, "description": "Show charges updated before the given date.", "schema": { "type": "string" } }, { "name": "updated_at_min", "in": "query", "required": false, "description": "Show charges updated after the given date.", "schema": { "type": "string" } }, { "name": "processed_at_min", "in": "query", "required": false, "description": "Show charges processed after, and including, the given date.", "schema": { "type": "string" } }, { "name": "processed_at_max", "in": "query", "required": false, "description": "Show charges processed before, and including, the given date.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "next": "next_cursor", "previous": "previous_cursor", "charges": [ { "id": 377749210, "address_id": 42171447, "analytics_data": { "utm_params": [ { "utm_source": "facebook", "utm_medium": "cpc" } ] }, "billing_address": { "address1": "601 SW Washing St.", "address2": "Suite 101", "city": "Portland", "company": "Acme Corp", "country_code": "US", "first_name": "Jane", "last_name": "Doe", "phone": "888-888-8888", "province": "Oregon", "zip": "97205" }, "client_details": { "browser_ip": "192.168.0.1", "user_agent": "safari webkit" }, "created_at": "2021-11-09T19:22:13+00:00", "currency": "USD", "customer": { "id": 37657002, "email": "test@test.com", "external_customer_id": { "ecommerce": "2879413682227" }, "hash": "7e706455cbd13e40" }, "discounts": [ { "id": 12345, "code": "TESTCODE10", "value": 10, "value_type": "fixed_amount" } ], "error": null, "error_type": null, "external_order_id": { "ecommerce": "2541635698739" }, "external_transaction_id": { "payment_processor": "ch_1HzWElJ2zqHvZRd1TWKFFqDR" }, "has_uncommitted_changes": false, "line_items": [ { "offer_attributes": null, "purchase_item_id": 63898947, "external_product_id": { "ecommerce": "4381728735283" }, "external_variant_id": { "ecommerce": "999999999999" }, "grams": 454, "handle": "shirt-package", "images": { "large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg", "medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg", "original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg", "small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg" }, "original_price": "10.00", "properties": [ { "name": "Color", "value": "Blue" } ], "purchase_item_type": "subscription", "quantity": 1, "sku": "TOM0001", "tax_due": "1.30", "tax_lines": [ { "price": "0.9931", "rate": "0.0725", "title": "CA State Tax", "unit_price": "0.3310" }, { "price": "0.3082", "rate": "0.0225", "title": "LA County Tax", "unit_price": "0.1027" } ], "taxable": true, "taxable_amount": "10.00", "title": "Shirt package", "total_price": "11.30", "unit_price": "10.00", "unit_price_includes_tax": false, "variant_title": "Blue T-shirt" } ], "merged_at": null, "note": "next order in sequence 3", "order_attributes": [ { "name": "Checkout-Method", "value": "delivery" } ], "orders_count": 1, "original_scheduled_at": "2021-12-09", "payment_processor": "stripe", "processed_at": "2021-11-09T23:59:31+00:00", "retry_date": "2021-01-01", "scheduled_at": "2021-12-09", "shipping_address": { "address1": "1030 Barnum Ave", "address2": "Suite 101", "city": "Stratford", "company": "Fake Company", "country_code": "US", "first_name": "Fake First", "last_name": "Fake Last", "phone": "999-999-9999", "province": "Connecticut", "zip": "06614" }, "shipping_lines": [ { "code": "Standard", "price": "4.90", "source": "shopify", "taxable": true, "tax_lines": [ { "price": "0.355", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.110", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "title": "Standard", "status": "active", "retrieved_at": null } ], "status": "success", "subtotal_price": "10.00", "tags": "Subscription, Subscription Recurring Order", "tax_lines": [ { "price": "0.950", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.335", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "taxable": true, "taxes_included": true, "total_discounts": "10.0", "total_duties": "0.00", "total_line_items_price": "10.00", "total_price": "11.29", "total_refunds": "0.00", "total_tax": "1.29", "total_weight_grams": 454, "type": "recurring", "updated_at": "2021-11-09T23:59:32+00:00" } ] } } } } }, "x-recharge-scopes": [ "read_orders" ] } }, "/charges/{id}/apply_discount": { "post": { "operationId": "apply_discount", "summary": "Apply a discount", "description": "Endpoint for adding Discount to an existing queued Charge .", "tags": [ "Charges" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "charge": { "id": 377749210, "address_id": 42171447, "analytics_data": { "utm_params": [ { "utm_source": "facebook", "utm_medium": "cpc" } ] }, "billing_address": { "address1": "601 SW Washing St.", "address2": "Suite 101", "city": "Portland", "company": "Acme Corp", "country_code": "US", "first_name": "Jane", "last_name": "Doe", "phone": "888-888-8888", "province": "Oregon", "zip": "97205" }, "client_details": { "browser_ip": "192.168.0.1", "user_agent": "safari webkit" }, "created_at": "2021-11-09T19:22:13+00:00", "currency": "USD", "customer": { "id": 37657002, "email": "test@test.com", "external_customer_id": { "ecommerce": "2879413682227" }, "hash": "7e706455cbd13e40" }, "discounts": [ { "id": 12345, "code": "TESTCODE10", "value": 10, "value_type": "fixed_amount" } ], "error": null, "error_type": null, "external_order_id": { "ecommerce": "2541635698739" }, "external_transaction_id": { "payment_processor": "ch_1HzWElJ2zqHvZRd1TWKFFqDR" }, "has_uncommitted_changes": false, "line_items": [ { "offer_attributes": null, "purchase_item_id": 63898947, "external_product_id": { "ecommerce": "4381728735283" }, "external_variant_id": { "ecommerce": "999999999999" }, "grams": 454, "handle": "shirt-package", "images": { "large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg", "medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg", "original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg", "small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg" }, "original_price": "10.00", "properties": [ { "name": "Color", "value": "Blue" } ], "purchase_item_type": "subscription", "quantity": 1, "sku": "TOM0001", "tax_due": "1.30", "tax_lines": [ { "price": "0.9931", "rate": "0.0725", "title": "CA State Tax", "unit_price": "0.3310" }, { "price": "0.3082", "rate": "0.0225", "title": "LA County Tax", "unit_price": "0.1027" } ], "taxable": true, "taxable_amount": "10.00", "title": "Shirt package", "total_price": "11.30", "unit_price": "10.00", "unit_price_includes_tax": false, "variant_title": "Blue T-shirt" } ], "merged_at": null, "note": "next order in sequence 3", "order_attributes": [ { "name": "Checkout-Method", "value": "delivery" } ], "orders_count": 1, "original_scheduled_at": "2021-12-09", "payment_processor": "stripe", "processed_at": "2021-11-09T23:59:31+00:00", "retry_date": "2021-01-01", "scheduled_at": "2021-12-09", "shipping_address": { "address1": "1030 Barnum Ave", "address2": "Suite 101", "city": "Stratford", "company": "Fake Company", "country_code": "US", "first_name": "Fake First", "last_name": "Fake Last", "phone": "999-999-9999", "province": "Connecticut", "zip": "06614" }, "shipping_lines": [ { "code": "Standard", "price": "4.90", "source": "shopify", "taxable": true, "tax_lines": [ { "price": "0.355", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.110", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "title": "Standard", "status": "active", "retrieved_at": null } ], "status": "success", "subtotal_price": "10.00", "tags": "Subscription, Subscription Recurring Order", "tax_lines": [ { "price": "0.950", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.335", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "taxable": true, "total_discounts": "10.0", "total_duties": "0.00", "total_line_items_price": "10.00", "total_price": "11.29", "total_refunds": "0.00", "total_tax": "1.29", "total_weight_grams": 454, "type": "recurring", "updated_at": "2021-11-09T23:59:32+00:00" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "discount_code": { "type": "string", "description": "Code of the Discount you want to apply to a Charge ." }, "discount_id": { "type": "integer", "description": "ID of the Discount you want to apply to a Charge ." } } }, "example": { "discount_code": "test" } } } }, "x-recharge-scopes": [ "write_orders" ] } }, "/charges/{id}/remove_discount": { "post": { "operationId": "remove_discount", "summary": "Remove a discount", "description": "Remove a Discount from a Charge without destroying the Discount . HTTP request examples POST /charges//remove_discount/", "tags": [ "Charges" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "charge": { "id": 377749210, "address_id": 42171447, "analytics_data": { "utm_params": [ { "utm_source": "facebook", "utm_medium": "cpc" } ] }, "billing_address": { "address1": "601 SW Washing St.", "address2": "Suite 101", "city": "Portland", "company": "Acme Corp", "country_code": "US", "first_name": "Jane", "last_name": "Doe", "phone": "888-888-8888", "province": "Oregon", "zip": "97205" }, "client_details": { "browser_ip": "192.168.0.1", "user_agent": "safari webkit" }, "created_at": "2021-11-09T19:22:13+00:00", "currency": "USD", "customer": { "id": 37657002, "email": "test@test.com", "external_customer_id": { "ecommerce": "2879413682227" }, "hash": "7e706455cbd13e40" }, "discounts": [], "error": null, "error_type": null, "external_order_id": { "ecommerce": "2541635698739" }, "external_transaction_id": { "payment_processor": "ch_1HzWElJ2zqHvZRd1TWKFFqDR" }, "has_uncommitted_changes": false, "line_items": [ { "offer_attributes": null, "purchase_item_id": 63898947, "external_product_id": { "ecommerce": "4381728735283" }, "external_variant_id": { "ecommerce": "999999999999" }, "grams": 454, "handle": "shirt-package", "images": { "large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg", "medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg", "original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg", "small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg" }, "original_price": "10.00", "properties": [ { "name": "Color", "value": "Blue" } ], "purchase_item_type": "subscription", "quantity": 1, "sku": "TOM0001", "tax_due": "1.30", "tax_lines": [ { "price": "0.9931", "rate": "0.0725", "title": "CA State Tax", "unit_price": "0.3310" }, { "price": "0.3082", "rate": "0.0225", "title": "LA County Tax", "unit_price": "0.1027" } ], "taxable": true, "taxable_amount": "10.00", "title": "Shirt package", "total_price": "11.30", "unit_price": "10.00", "unit_price_includes_tax": false, "variant_title": "Blue T-shirt" } ], "merged_at": null, "note": "next order in sequence 3", "order_attributes": [ { "name": "Checkout-Method", "value": "delivery" } ], "orders_count": 1, "original_scheduled_at": "2021-12-09", "payment_processor": "stripe", "processed_at": "2021-11-09T23:59:31+00:00", "retry_date": "2021-01-01", "scheduled_at": "2021-12-09", "shipping_address": { "address1": "1030 Barnum Ave", "address2": "Suite 101", "city": "Stratford", "company": "Fake Company", "country_code": "US", "first_name": "Fake First", "last_name": "Fake Last", "phone": "999-999-9999", "province": "Connecticut", "zip": "06614" }, "shipping_lines": [ { "code": "Standard", "price": "4.90", "source": "shopify", "taxable": true, "tax_lines": [ { "price": "0.355", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.110", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "title": "Standard", "status": "active", "retrieved_at": null } ], "status": "success", "subtotal_price": "10.00", "tags": "Subscription, Subscription Recurring Order", "tax_lines": [ { "price": "0.950", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.335", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "taxable": true, "total_discounts": "10.0", "total_duties": "0.00", "total_line_items_price": "10.00", "total_price": "11.29", "total_refunds": "0.00", "total_tax": "1.29", "total_weight_grams": 454, "type": "recurring", "updated_at": "2021-11-09T23:59:32+00:00" } } } } } }, "x-recharge-scopes": [ "write_orders" ] } }, "/charges/{id}/skip": { "post": { "operationId": "charge_skip", "summary": "Skip a charge", "description": "Skip a Charge .", "tags": [ "Charges" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "commit", "in": "query", "required": false, "description": "If set to false , the remaining queued Charge is regenerated asynchronously instead of before the response is returned. Defaults to true .", "schema": { "type": "boolean" } }, { "name": "update_membership_expires_at", "in": "query", "required": false, "description": "If set to true , the expiration date of the Membership associated with the Charge is moved to the new charge date. Defaults to false .", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "charge": { "id": 377749210, "address_id": 42171447, "analytics_data": { "utm_params": [ { "utm_source": "facebook", "utm_medium": "cpc" } ] }, "billing_address": { "address1": "601 SW Washing St.", "address2": "Suite 101", "city": "Portland", "company": "Acme Corp", "country_code": "US", "first_name": "Jane", "last_name": "Doe", "phone": "888-888-8888", "province": "Oregon", "zip": "97205" }, "client_details": { "browser_ip": "192.168.0.1", "user_agent": "safari webkit" }, "created_at": "2021-11-09T19:22:13+00:00", "currency": "USD", "customer": { "id": 37657002, "email": "test@test.com", "external_customer_id": { "ecommerce": "2879413682227" }, "hash": "7e706455cbd13e40" }, "discounts": [ { "id": 12345, "code": "TESTCODE10", "value": 10, "value_type": "fixed_amount" } ], "error": null, "error_type": null, "external_order_id": { "ecommerce": "2541635698739" }, "external_transaction_id": { "payment_processor": "ch_1HzWElJ2zqHvZRd1TWKFFqDR" }, "has_uncommitted_changes": false, "line_items": [ { "offer_attributes": null, "purchase_item_id": 63898947, "external_product_id": { "ecommerce": "4381728735283" }, "external_variant_id": { "ecommerce": "999999999999" }, "grams": 454, "handle": "shirt-package", "images": { "large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg", "medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg", "original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg", "small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg" }, "original_price": "10.00", "properties": [ { "name": "Color", "value": "Blue" } ], "purchase_item_type": "subscription", "quantity": 1, "sku": "TOM0001", "tax_due": "1.30", "tax_lines": [ { "price": "0.9931", "rate": "0.0725", "title": "CA State Tax", "unit_price": "0.3310" }, { "price": "0.3082", "rate": "0.0225", "title": "LA County Tax", "unit_price": "0.1027" } ], "taxable": true, "taxable_amount": "10.00", "title": "Shirt package", "total_price": "11.30", "unit_price": "10.00", "unit_price_includes_tax": false, "variant_title": "Blue T-shirt" } ], "merged_at": null, "note": "next order in sequence 3", "order_attributes": [ { "name": "Checkout-Method", "value": "delivery" } ], "orders_count": 1, "original_scheduled_at": "2021-12-09", "payment_processor": "stripe", "processed_at": null, "retry_date": null, "scheduled_at": "2021-12-09", "shipping_address": { "address1": "1030 Barnum Ave", "address2": "Suite 101", "city": "Stratford", "company": "Fake Company", "country_code": "US", "first_name": "Fake First", "last_name": "Fake Last", "phone": "999-999-9999", "province": "Connecticut", "zip": "06614" }, "shipping_lines": [ { "code": "Standard", "price": "4.90", "source": "shopify", "taxable": true, "tax_lines": [ { "price": "0.355", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.110", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "title": "Standard", "status": "active", "retrieved_at": null } ], "status": "skipped", "subtotal_price": "10.00", "tags": "Subscription, Subscription Recurring Order", "tax_lines": [ { "price": "0.950", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.335", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "taxable": true, "total_discounts": "10.0", "total_duties": "0.00", "total_line_items_price": "10.00", "total_price": "11.29", "total_refunds": "0.00", "total_tax": "1.29", "total_weight_grams": 454, "type": "recurring", "updated_at": "2021-11-09T23:59:32+00:00" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "purchase_item_ids": { "type": "array", "items": {}, "description": "A list of the Subscription or Onetime IDs to skip on the Charge ." }, "purchase_item_id": { "type": "integer", "description": "The ID of a single Subscription or Onetime to skip on the Charge . Cannot be passed together with purchase_item_ids ." } } }, "example": { "purchase_item_ids": [ 27363808, 27363809 ] } } } }, "x-recharge-scopes": [ "write_orders" ] } }, "/charges/{id}/unskip": { "post": { "operationId": "charge_unskip", "summary": "Unskip a charge", "description": "Unskip a Charge .", "tags": [ "Charges" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "update_membership_expires_at", "in": "query", "required": false, "description": "If set to true , the expiration date of the Membership associated with the Charge is moved to the new charge date. Defaults to false .", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "charge": { "id": 377749210, "address_id": 42171447, "analytics_data": { "utm_params": [ { "utm_source": "facebook", "utm_medium": "cpc" } ] }, "billing_address": { "address1": "601 SW Washing St.", "address2": "Suite 101", "city": "Portland", "company": "Acme Corp", "country_code": "US", "first_name": "Jane", "last_name": "Doe", "phone": "888-888-8888", "province": "Oregon", "zip": "97205" }, "client_details": { "browser_ip": "192.168.0.1", "user_agent": "safari webkit" }, "created_at": "2021-11-09T19:22:13+00:00", "currency": "USD", "customer": { "id": 37657002, "email": "test@test.com", "external_customer_id": { "ecommerce": "2879413682227" }, "hash": "7e706455cbd13e40" }, "discounts": [ { "id": 12345, "code": "TESTCODE10", "value": 10, "value_type": "fixed_amount" } ], "error": null, "error_type": null, "external_order_id": { "ecommerce": "2541635698739" }, "external_transaction_id": { "payment_processor": "ch_1HzWElJ2zqHvZRd1TWKFFqDR" }, "has_uncommitted_changes": false, "line_items": [ { "offer_attributes": null, "purchase_item_id": 63898947, "external_product_id": { "ecommerce": "4381728735283" }, "external_variant_id": { "ecommerce": "999999999999" }, "grams": 454, "handle": "shirt-package", "images": { "large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg", "medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg", "original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg", "small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg" }, "original_price": "10.00", "properties": [ { "name": "Color", "value": "Blue" } ], "purchase_item_type": "subscription", "quantity": 1, "sku": "TOM0001", "tax_due": "1.30", "tax_lines": [ { "price": "0.9931", "rate": "0.0725", "title": "CA State Tax", "unit_price": "0.3310" }, { "price": "0.3082", "rate": "0.0225", "title": "LA County Tax", "unit_price": "0.1027" } ], "taxable": true, "taxable_amount": "10.00", "title": "Shirt package", "total_price": "11.30", "unit_price": "10.00", "unit_price_includes_tax": false, "variant_title": "Blue T-shirt" } ], "merged_at": null, "note": "next order in sequence 3", "order_attributes": [ { "name": "Checkout-Method", "value": "delivery" } ], "orders_count": 1, "original_scheduled_at": "2021-12-09", "payment_processor": "stripe", "processed_at": null, "retry_date": null, "scheduled_at": "2021-12-09", "shipping_address": { "address1": "1030 Barnum Ave", "address2": "Suite 101", "city": "Stratford", "company": "Fake Company", "country_code": "US", "first_name": "Fake First", "last_name": "Fake Last", "phone": "999-999-9999", "province": "Connecticut", "zip": "06614" }, "shipping_lines": [ { "code": "Standard", "price": "4.90", "source": "shopify", "taxable": true, "tax_lines": [ { "price": "0.355", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.110", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "title": "Standard", "status": "active", "retrieved_at": null } ], "status": "queued", "subtotal_price": "10.00", "tags": "Subscription, Subscription Recurring Order", "tax_lines": [ { "price": "0.950", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.335", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "taxable": true, "total_discounts": "10.0", "total_duties": "0.00", "total_line_items_price": "10.00", "total_price": "11.29", "total_refunds": "0.00", "total_tax": "1.29", "total_weight_grams": 454, "type": "recurring", "updated_at": "2021-11-09T23:59:32+00:00" } } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "example": {} } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "purchase_item_ids": { "type": "array", "items": {}, "description": "A list of the Subscription or Onetime IDs to unskip on the Charge ." }, "purchase_item_id": { "type": "integer", "description": "The ID of a single Subscription or Onetime to unskip on the Charge . Cannot be passed together with purchase_item_ids ." } } }, "example": { "purchase_item_ids": [ 27363808 ] } } } }, "x-recharge-scopes": [ "write_orders" ] } }, "/charges/{id}/refund": { "post": { "operationId": "charge_refund", "summary": "Refund a charge", "description": "Refund a Charge .", "tags": [ "Charges" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "charge": { "id": 377749210, "address_id": 42171447, "analytics_data": { "utm_params": [ { "utm_source": "facebook", "utm_medium": "cpc" } ] }, "billing_address": { "address1": "601 SW Washing St.", "address2": "Suite 101", "city": "Portland", "company": "Acme Corp", "country_code": "US", "first_name": "Jane", "last_name": "Doe", "phone": "888-888-8888", "province": "Oregon", "zip": "97205" }, "client_details": { "browser_ip": "192.168.0.1", "user_agent": "safari webkit" }, "created_at": "2021-11-09T19:22:13+00:00", "currency": "USD", "customer": { "id": 37657002, "email": "test@test.com", "external_customer_id": { "ecommerce": "2879413682227" }, "hash": "7e706455cbd13e40" }, "discounts": [ { "id": 12345, "code": "TESTCODE10", "value": 10, "value_type": "fixed_amount" } ], "error": null, "error_type": null, "external_order_id": { "ecommerce": "2541635698739" }, "external_transaction_id": { "payment_processor": "ch_1HzWElJ2zqHvZRd1TWKFFqDR" }, "has_uncommitted_changes": false, "line_items": [ { "offer_attributes": null, "purchase_item_id": 63898947, "external_product_id": { "ecommerce": "4381728735283" }, "external_variant_id": { "ecommerce": "999999999999" }, "grams": 454, "handle": "shirt-package", "images": { "large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg", "medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg", "original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg", "small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg" }, "original_price": "10.00", "properties": [ { "name": "Color", "value": "Blue" } ], "purchase_item_type": "subscription", "quantity": 1, "sku": "TOM0001", "tax_due": "1.30", "tax_lines": [ { "price": "0.9931", "rate": "0.0725", "title": "CA State Tax", "unit_price": "0.3310" }, { "price": "0.3082", "rate": "0.0225", "title": "LA County Tax", "unit_price": "0.1027" } ], "taxable": true, "taxable_amount": "10.00", "title": "Shirt package", "total_price": "11.30", "unit_price": "10.00", "unit_price_includes_tax": false, "variant_title": "Blue T-shirt" } ], "merged_at": null, "note": "next order in sequence 3", "order_attributes": [ { "name": "Checkout-Method", "value": "delivery" } ], "orders_count": 1, "original_scheduled_at": "2021-12-09", "payment_processor": "stripe", "processed_at": "2021-11-09T23:59:31+00:00", "retry_date": null, "scheduled_at": "2021-12-09", "shipping_address": { "address1": "1030 Barnum Ave", "address2": "Suite 101", "city": "Stratford", "company": "Fake Company", "country_code": "US", "first_name": "Fake First", "last_name": "Fake Last", "phone": "999-999-9999", "province": "Connecticut", "zip": "06614" }, "shipping_lines": [ { "code": "Standard", "price": "4.90", "source": "shopify", "taxable": true, "tax_lines": [ { "price": "0.355", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.110", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "title": "Standard", "status": "active", "retrieved_at": null } ], "status": "refunded", "subtotal_price": "10.00", "tags": "Subscription, Subscription Recurring Order", "tax_lines": [ { "price": "0.950", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.335", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "taxable": true, "total_discounts": "10.0", "total_duties": "0.00", "total_line_items_price": "10.00", "total_price": "11.29", "total_refunds": "11.29", "total_tax": "1.29", "total_weight_grams": 454, "type": "recurring", "updated_at": "2021-11-09T23:59:32+00:00" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "description": "Amount of money that will be refunded. It can be fully or partially refunded." }, "full_refund": { "type": "boolean", "description": "If this parameter has value true , the Charge will be totally refunded." }, "retry": { "type": "boolean", "description": "If this parameter has value true and full_refund has value true , the Charge will be retried. The status on the Charge will be returned as “error”." }, "error": { "type": "string", "description": "The error message to store on the Charge . If the retry parameter has value true , this value is required." }, "error_type": { "type": "string", "description": "If the retry parameter has value true , this value is required.", "enum": [ "insufficient_inventory", "bc_rejected" ] }, "line_items": { "type": "array", "items": { "type": "object", "properties": { "purchase_item_id": { "type": "integer", "description": "The Subscription or Onetime ID of the line item to refund. Required for each line item." }, "quantity": { "type": "integer", "description": "The quantity of the line item to refund. Must be at least 1. Required for each line item." } } }, "description": "A list of the line items to refund. Cannot be passed together with amount . If passed with full_refund , all line items of the Charge must be listed with their full quantities." } } }, "example": { "amount": 11 } } } }, "x-recharge-scopes": [ "write_orders", "write_payments" ] } }, "/charges/{id}/process": { "post": { "operationId": "charge_process", "summary": "Process a charge", "description": "The charge processing route can be used to process Charges that are in a queued or error status.", "tags": [ "Charges" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "charge": { "id": 377749210, "address_id": 42171447, "analytics_data": { "utm_params": [ { "utm_source": "facebook", "utm_medium": "cpc" } ] }, "billing_address": { "address1": "601 SW Washing St.", "address2": "Suite 101", "city": "Portland", "company": "Acme Corp", "country_code": "US", "first_name": "Jane", "last_name": "Doe", "phone": "888-888-8888", "province": "Oregon", "zip": "97205" }, "client_details": { "browser_ip": "192.168.0.1", "user_agent": "safari webkit" }, "created_at": "2021-11-09T19:22:13+00:00", "currency": "USD", "customer": { "id": 37657002, "email": "test@test.com", "external_customer_id": { "ecommerce": "2879413682227" }, "hash": "7e706455cbd13e40" }, "discounts": [ { "id": 12345, "code": "TESTCODE10", "value": 10, "value_type": "fixed_amount" } ], "error": null, "error_type": null, "external_order_id": { "ecommerce": "2541635698739" }, "external_transaction_id": { "payment_processor": "ch_1HzWElJ2zqHvZRd1TWKFFqDR" }, "has_uncommitted_changes": false, "line_items": [ { "offer_attributes": null, "purchase_item_id": 63898947, "external_product_id": { "ecommerce": "4381728735283" }, "external_variant_id": { "ecommerce": "999999999999" }, "grams": 454, "handle": "shirt-package", "images": { "large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg", "medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg", "original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg", "small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg" }, "original_price": "10.00", "properties": [ { "name": "Color", "value": "Blue" } ], "purchase_item_type": "subscription", "quantity": 1, "sku": "TOM0001", "tax_due": "1.30", "tax_lines": [ { "price": "0.9931", "rate": "0.0725", "title": "CA State Tax", "unit_price": "0.3310" }, { "price": "0.3082", "rate": "0.0225", "title": "LA County Tax", "unit_price": "0.1027" } ], "taxable": true, "taxable_amount": "10.00", "title": "Shirt package", "total_price": "11.30", "unit_price": "10.00", "unit_price_includes_tax": false, "variant_title": "Blue T-shirt" } ], "merged_at": null, "note": "next order in sequence 3", "order_attributes": [ { "name": "Checkout-Method", "value": "delivery" } ], "orders_count": 1, "original_scheduled_at": "2021-12-09", "payment_processor": "stripe", "processed_at": "2021-11-09T23:59:31+00:00", "retry_date": null, "scheduled_at": "2021-12-09", "shipping_address": { "address1": "1030 Barnum Ave", "address2": "Suite 101", "city": "Stratford", "company": "Fake Company", "country_code": "US", "first_name": "Fake First", "last_name": "Fake Last", "phone": "999-999-9999", "province": "Connecticut", "zip": "06614" }, "shipping_lines": [ { "code": "Standard", "price": "4.90", "source": "shopify", "taxable": true, "tax_lines": [ { "price": "0.355", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.110", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "title": "Standard", "status": "active", "retrieved_at": null } ], "status": "success", "subtotal_price": "10.00", "tags": "Subscription, Subscription Recurring Order", "tax_lines": [ { "price": "0.950", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.335", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "taxable": true, "total_discounts": "10.0", "total_duties": "0.00", "total_line_items_price": "10.00", "total_price": "11.29", "total_refunds": "0.00", "total_tax": "1.29", "total_weight_grams": 454, "type": "recurring", "updated_at": "2021-11-09T23:59:32+00:00" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "custom_gateway": { "type": "object", "properties": { "external_status": { "type": "string", "description": "The result of the external payment. Required when custom_gateway is passed.", "enum": [ "success", "error" ] }, "external_transaction_id": { "type": "string", "description": "The ID of the transaction in the external payment system. Required when external_status is success ." }, "external_error_type": { "type": "string", "description": "The structured reason why the external payment failed, such as CARD_DECLINED . Must be a valid Charge error type. Required when external_status is error and not allowed when it is success ." }, "external_error_message": { "type": "string", "description": "The error message returned by the external payment system. Required when external_status is error and not allowed when it is success ." } }, "description": "The outcome of a payment taken outside of Recharge. Must be passed, and can only be passed, when the Charge uses a payment method with a custom payment gateway." } } }, "example": {} } } }, "x-recharge-scopes": [ "write_payments" ] } }, "/charges/{id}/capture_payment": { "post": { "operationId": "charge_capture", "summary": "Capture a charge", "description": "If you are leveraging the authorize/capture workflow with Recharge, the charge/{id}/capture_payment endpoint is how to capture the funds of a previously authorized Charge . Capture Window You can only capture payment on Charges that have been authorized within the last 7 days. This is a limitation of payment providers/financial institutions and Recharge cannot configure or override this limit. Any Charges that are attempted to be captured beyond that 7 day window may result in an error indicating the Charge cannot be captured. As a result, Recharge provides a charge/uncaptured Webhook . If subscribed, this Webhook will notify you of any Charges that are not captured 6 days after authorization. Please refer to the webhooks section for more information.", "tags": [ "Charges" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Charge captured successfully", "content": { "application/json": { "example": { "charge": { "id": 377749210, "address_id": 42171447, "analytics_data": { "utm_params": [ { "utm_source": "facebook", "utm_medium": "cpc" } ] }, "billing_address": { "address1": "601 SW Washing St.", "address2": "Suite 101", "city": "Portland", "company": "Acme Corp", "country_code": "US", "first_name": "Jane", "last_name": "Doe", "phone": "888-888-8888", "province": "Oregon", "zip": "97205" }, "client_details": { "browser_ip": "192.168.0.1", "user_agent": "safari webkit" }, "created_at": "2021-11-09T19:22:13+00:00", "currency": "USD", "customer": { "id": 37657002, "email": "test@test.com", "external_customer_id": { "ecommerce": "2879413682227" }, "hash": "7e706455cbd13e40" }, "discounts": [ { "id": 12345, "code": "TESTCODE10", "value": 10, "value_type": "fixed_amount" } ], "error": null, "error_type": null, "external_order_id": { "ecommerce": "2541635698739" }, "external_transaction_id": { "payment_processor": "ch_1HzWElJ2zqHvZRd1TWKFFqDR" }, "has_uncommitted_changes": false, "line_items": [ { "offer_attributes": null, "purchase_item_id": 63898947, "external_product_id": { "ecommerce": "4381728735283" }, "external_variant_id": { "ecommerce": "999999999999" }, "grams": 454, "handle": "shirt-package", "images": { "large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg", "medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg", "original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg", "small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg" }, "original_price": "10.00", "properties": [ { "name": "Color", "value": "Blue" } ], "purchase_item_type": "subscription", "quantity": 1, "sku": "TOM0001", "tax_due": "1.30", "tax_lines": [ { "price": "0.9931", "rate": "0.0725", "title": "CA State Tax", "unit_price": "0.3310" }, { "price": "0.3082", "rate": "0.0225", "title": "LA County Tax", "unit_price": "0.1027" } ], "taxable": true, "taxable_amount": "10.00", "title": "Shirt package", "total_price": "11.30", "unit_price": "10.00", "unit_price_includes_tax": false, "variant_title": "Blue T-shirt" } ], "merged_at": null, "note": "next order in sequence 3", "order_attributes": [ { "name": "Checkout-Method", "value": "delivery" } ], "orders_count": 1, "original_scheduled_at": "2021-12-09", "payment_processor": "stripe", "processed_at": "2021-11-09T23:59:31+00:00", "retry_date": null, "scheduled_at": "2021-12-09", "shipping_address": { "address1": "1030 Barnum Ave", "address2": "Suite 101", "city": "Stratford", "company": "Fake Company", "country_code": "US", "first_name": "Fake First", "last_name": "Fake Last", "phone": "999-999-9999", "province": "Connecticut", "zip": "06614" }, "shipping_lines": [ { "code": "Standard", "price": "4.90", "source": "shopify", "taxable": true, "tax_lines": [ { "price": "0.355", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.110", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "title": "Standard", "status": "active", "retrieved_at": null } ], "status": "success", "subtotal_price": "10.00", "tags": "Subscription, Subscription Recurring Order", "tax_lines": [ { "price": "0.950", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.335", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "taxable": true, "total_discounts": "10.0", "total_duties": "0.00", "total_line_items_price": "10.00", "total_price": "11.29", "total_refunds": "0.00", "total_tax": "1.29", "total_weight_grams": 454, "type": "recurring", "updated_at": "2021-11-09T23:59:32+00:00" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": {} } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": {} } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "example": {} } } } }, "x-recharge-scopes": [ "write_payments", "write_orders", "write_subscriptions", "write_customers" ] } }, "/charges/{id}/add_free_gift": { "post": { "operationId": "charge_add_free_gift", "summary": "Add a free gift", "description": "Endpoint for adding Free Gift to an existing queued Charge .", "tags": [ "Charges" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Free gift added to charge", "content": { "application/json": { "example": { "charge": { "id": 377749210, "address_id": 42171447, "analytics_data": { "utm_params": [ { "utm_source": "facebook", "utm_medium": "cpc" } ] }, "billing_address": { "address1": "601 SW Washing St.", "address2": "Suite 101", "city": "Portland", "company": "Acme Corp", "country_code": "US", "first_name": "Jane", "last_name": "Doe", "phone": "888-888-8888", "province": "Oregon", "zip": "97205" }, "client_details": { "browser_ip": "192.168.0.1", "user_agent": "safari webkit" }, "created_at": "2021-11-09T19:22:13+00:00", "currency": "USD", "customer": { "id": 37657002, "email": "test@test.com", "external_customer_id": { "ecommerce": "2879413682227" }, "hash": "7e706455cbd13e40" }, "discounts": [ { "id": 12345, "code": "TESTCODE10", "value": 10, "value_type": "fixed_amount" } ], "error": null, "error_type": null, "external_order_id": { "ecommerce": "2541635698739" }, "external_transaction_id": { "payment_processor": "ch_1HzWElJ2zqHvZRd1TWKFFqDR" }, "has_uncommitted_changes": false, "line_items": [ { "offer_attributes": null, "purchase_item_id": 63898947, "external_product_id": { "ecommerce": "4381728735283" }, "external_variant_id": { "ecommerce": "999999999999" }, "grams": 454, "handle": "shirt-package", "images": { "large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg", "medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg", "original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg", "small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg" }, "original_price": "10.00", "properties": [ { "name": "Color", "value": "Blue" } ], "purchase_item_type": "subscription", "quantity": 1, "sku": "TOM0001", "tax_due": "1.30", "tax_lines": [ { "price": "0.9931", "rate": "0.0725", "title": "CA State Tax", "unit_price": "0.3310" }, { "price": "0.3082", "rate": "0.0225", "title": "LA County Tax", "unit_price": "0.1027" } ], "taxable": true, "taxable_amount": "10.00", "title": "Shirt package", "total_price": "11.30", "unit_price": "10.00", "unit_price_includes_tax": false, "variant_title": "Blue T-shirt" }, { "purchase_item_id": null, "external_product_id": { "ecommerce": "6791118553225" }, "external_variant_id": { "ecommerce": "39940738482313" }, "grams": null, "handle": null, "images": { "large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg", "medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg", "original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg", "small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg" }, "offer_attributes": null, "original_price": "0.00", "properties": [ { "name": "source", "value": "gift:API:RequestId:self.request_id," } ], "purchase_item_type": null, "quantity": 1, "sku": null, "tax_due": "0.00", "tax_lines": [], "taxable": false, "taxable_amount": "0.00", "title": "Free Gift", "total_price": "0.00", "unit_price": "0.00", "unit_price_includes_tax": false, "variant_title": "Free Gift Title" } ], "merged_at": null, "note": "next order in sequence 3", "order_attributes": [ { "name": "Checkout-Method", "value": "delivery" } ], "orders_count": 1, "original_scheduled_at": "2021-12-09", "payment_processor": "stripe", "processed_at": "2021-11-09T23:59:31+00:00", "retry_date": "2021-01-01", "scheduled_at": "2021-12-09", "shipping_address": { "address1": "1030 Barnum Ave", "address2": "Suite 101", "city": "Stratford", "company": "Fake Company", "country_code": "US", "first_name": "Fake First", "last_name": "Fake Last", "phone": "999-999-9999", "province": "Connecticut", "zip": "06614" }, "shipping_lines": [ { "code": "Standard", "price": "4.90", "source": "shopify", "taxable": true, "tax_lines": [ { "price": "0.355", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.110", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "title": "Standard", "status": "active", "retrieved_at": null } ], "status": "success", "subtotal_price": "10.00", "tags": "Subscription, Subscription Recurring Order", "tax_lines": [ { "price": "0.950", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.335", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "taxable": true, "taxes_included": true, "total_discounts": "10.0", "total_duties": "0.00", "total_line_items_price": "10.00", "total_price": "11.29", "total_refunds": "0.00", "total_tax": "1.29", "total_weight_grams": 454, "type": "recurring", "updated_at": "2021-11-09T23:59:32+00:00" } } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "example": {} } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "free_gifts": { "type": "array", "items": { "type": "object", "properties": { "external_variant_id": { "type": "string", "description": "ID of the Variant you want to add to a Charge ." }, "quantity": { "type": "integer", "description": "Quantity of the Free Gift you want to add to a Charge ." } }, "required": [ "quantity" ] }, "description": "List of Free Gift s you want to add to a Charge ." }, "conserve_on_skip": { "type": "boolean", "description": "Whether to conserve the Free Gift on a skipped charge." } }, "required": [ "free_gifts" ] }, "example": { "free_gifts": [ { "external_variant_id": "1234567890", "quantity": 1 } ], "conserve_on_skip": true } } } }, "x-recharge-scopes": [ "write_orders", "write_free_gifts" ] } }, "/charges/{id}/remove_free_gift": { "post": { "operationId": "charge_remove_free_gift", "summary": "Remove a free gift", "description": "Endpoint for removing a free gift from an existing queued Charge .", "tags": [ "Charges" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Free gift removed from charge", "content": { "application/json": { "example": { "charge": { "id": 377749210, "address_id": 42171447, "analytics_data": { "utm_params": [ { "utm_source": "facebook", "utm_medium": "cpc" } ] }, "billing_address": { "address1": "601 SW Washing St.", "address2": "Suite 101", "city": "Portland", "company": "Acme Corp", "country_code": "US", "first_name": "Jane", "last_name": "Doe", "phone": "888-888-8888", "province": "Oregon", "zip": "97205" }, "client_details": { "browser_ip": "192.168.0.1", "user_agent": "safari webkit" }, "created_at": "2021-11-09T19:22:13+00:00", "currency": "USD", "customer": { "id": 37657002, "email": "test@test.com", "external_customer_id": { "ecommerce": "2879413682227" }, "hash": "7e706455cbd13e40" }, "discounts": [ { "id": 12345, "code": "TESTCODE10", "value": 10, "value_type": "fixed_amount" } ], "error": null, "error_type": null, "external_order_id": { "ecommerce": "2541635698739" }, "external_transaction_id": { "payment_processor": "ch_1HzWElJ2zqHvZRd1TWKFFqDR" }, "has_uncommitted_changes": false, "line_items": [ { "offer_attributes": null, "purchase_item_id": 63898947, "external_product_id": { "ecommerce": "4381728735283" }, "external_variant_id": { "ecommerce": "999999999999" }, "grams": 454, "handle": "shirt-package", "images": { "large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg", "medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg", "original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg", "small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg" }, "original_price": "10.00", "properties": [ { "name": "Color", "value": "Blue" } ], "purchase_item_type": "subscription", "quantity": 1, "sku": "TOM0001", "tax_due": "1.30", "tax_lines": [ { "price": "0.9931", "rate": "0.0725", "title": "CA State Tax", "unit_price": "0.3310" }, { "price": "0.3082", "rate": "0.0225", "title": "LA County Tax", "unit_price": "0.1027" } ], "taxable": true, "taxable_amount": "10.00", "title": "Shirt package", "total_price": "11.30", "unit_price": "10.00", "unit_price_includes_tax": false, "variant_title": "Blue T-shirt" } ], "merged_at": null, "note": "next order in sequence 3", "order_attributes": [ { "name": "Checkout-Method", "value": "delivery" } ], "orders_count": 1, "original_scheduled_at": "2021-12-09", "payment_processor": "stripe", "processed_at": "2021-11-09T23:59:31+00:00", "retry_date": "2021-01-01", "scheduled_at": "2021-12-09", "shipping_address": { "address1": "1030 Barnum Ave", "address2": "Suite 101", "city": "Stratford", "company": "Fake Company", "country_code": "US", "first_name": "Fake First", "last_name": "Fake Last", "phone": "999-999-9999", "province": "Connecticut", "zip": "06614" }, "shipping_lines": [ { "code": "Standard", "price": "4.90", "source": "shopify", "taxable": true, "tax_lines": [ { "price": "0.355", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.110", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "title": "Standard", "status": "active", "retrieved_at": null } ], "status": "success", "subtotal_price": "10.00", "tags": "Subscription, Subscription Recurring Order", "tax_lines": [ { "price": "0.950", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.335", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "taxable": true, "taxes_included": true, "total_discounts": "10.0", "total_duties": "0.00", "total_line_items_price": "10.00", "total_price": "11.29", "total_refunds": "0.00", "total_tax": "1.29", "total_weight_grams": 454, "type": "recurring", "updated_at": "2021-11-09T23:59:32+00:00" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "external_variant_ids": { "type": "array", "items": {}, "description": "List of ExternalVariant IDs of free gifts you want to remove from a Charge ." } } }, "example": { "external_variant_ids": [ "1234567890" ] } } } }, "x-recharge-scopes": [ "write_orders", "write_free_gifts" ] } }, "/checkouts": { "post": { "operationId": "checkout_create", "summary": "Create a checkout", "description": "Create a Checkout", "tags": [ "Checkouts" ], "parameters": [ { "name": "get_shipping_rates", "in": "query", "required": false, "description": "If specified as a query parameter, shipping rates will be retrieved and will allow providing applied_shipping_rate upon checkout creation.", "schema": { "type": "boolean" } }, { "name": "partial_shipping", "in": "query", "required": false, "description": "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 .", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "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" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "analytics_data": { "type": "object", "properties": { "utm_params": { "type": "array", "items": { "type": "object", "properties": { "utm_campaign": { "type": "string", "description": "The UTM campaign." }, "utm_content": { "type": "string", "description": "The UTM content." }, "utm_data_source": { "type": "string", "description": "The source of the campaign parameter." }, "utm_source": { "type": "string", "description": "The UTM source." }, "utm_medium": { "type": "string", "description": "The UTM medium." }, "utm_term": { "type": "string", "description": "The UTM term." }, "utm_timestamp": { "type": "string", "description": "The UTM timestamp." } }, "required": [ "utm_data_source", "utm_timestamp" ] }, "description": "An array containing utm_param objects." } }, "description": "Urchin Tracking Module (UTM) parameters are used for online marketing campaigns." }, "applied_discounts": { "type": "array", "items": { "type": "object", "properties": { "discount_code": { "type": "string", "description": "The code for the Discount , e.g. 25_PERCENT_OFF ." } } }, "description": "Discount to apply to the Checkout ." }, "applied_shipping_rate": { "type": "object", "properties": { "handle": { "type": "string", "description": "Unique identifier for the shipping rate that should be applied." } }, "description": "Shipping rates details, populated once the rates have been selected and applied successfully to the Checkout ." }, "custom_shipping_rate_options": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Code for the shipping rate." }, "price": { "type": "string", "description": "Price for the shipping rate." }, "title": { "type": "string", "description": "Title for the shipping rate." }, "handle": { "type": "string", "description": "Unique identifier for the shipping rate." } }, "required": [ "code", "price", "title", "handle" ] }, "description": "List of available shipping rates to use when selecting a shipping rate with applied_shipping_rate . Custom shipping rates will take precedence over any default rates fetched using get_shipping_rates=true ." }, "billing_address": { "type": "object", "properties": { "address1": { "type": "string", "description": "Line one of the billing address." }, "address2": { "type": "string", "description": "Line two of the billing address." }, "city": { "type": "string", "description": "The city of the billing address." }, "company": { "type": "string", "description": "The company name of the billing address." }, "country_code": { "type": "string", "description": "2-letter country code." }, "first_name": { "type": "string", "description": "The first name of the billing address." }, "last_name": { "type": "string", "description": "The last name of the billing address." }, "phone": { "type": "string", "description": "The phone number of the billing address." }, "province": { "type": "string", "description": "The name of the province or state associated with the billing address." }, "zip": { "type": "string", "description": "The zip code or postcode of the address." } }, "required": [ "address1", "city", "country_code", "last_name" ], "description": "Billing Address for the Checkout ." }, "currency": { "type": "string", "description": "Currency of the Checkout ." }, "email": { "type": "string", "description": "Email address for the Customer ." }, "external_checkout_id": { "type": "string", "description": "External checkout reference, if one exists." }, "external_checkout_source": { "type": "string", "description": "External checkout platform, if one exists.", "enum": [ "big_commerce", "headless", "magento", "shopify" ] }, "line_items": { "type": "array", "items": { "type": "object", "properties": { "external_line_item_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "The line item ID as it appears in the external e-commerce platform." } }, "description": "An object containing the ID of the line item as it appears in the external system." }, "external_product_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "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 ." } }, "required": [ "ecommerce" ], "description": "An object containing the associated product ID as it appears in the external system." }, "external_variant_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "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 ." } }, "required": [ "ecommerce" ], "description": "An object containing the associated variant ID as it appears in the external system." }, "handle": { "type": "string", "description": "A unique, human-friendly string for the Product ." }, "images": { "type": "object", "properties": { "large": { "type": "string", "description": "The url where a large image file is located." }, "medium": { "type": "string", "description": "The url where a medium image file is located." }, "small": { "type": "string", "description": "The url where a small image file is located." }, "original": { "type": "string", "description": "The url of the original sized product image." } }, "description": "An object containing URLs of the Product image." }, "properties": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the property." }, "value": { "type": "string", "description": "The value of the property." } } }, "description": "An array of name value pairs of additional line_item attributes." }, "quantity": { "type": "integer", "description": "The quantity of the line_item ." }, "recurring_unit_price": { "type": "string", "description": "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_shipping": { "type": "boolean", "description": "Whether the item requires shipping. Defaults to the value of the product in the catalog." }, "sku": { "type": "string", "description": "The SKU (stock keeping unit) of the Product associated with the line_item ." }, "subscription_preferences": { "type": "object", "properties": { "charge_interval_frequency": { "type": "integer", "description": "Frequency at which the subscriber will be charged." }, "cutoff_day_of_month": { "type": "integer", "description": "Day of the month the plan should be charged" }, "cutoff_day_of_week": { "type": "integer", "description": "Day of the month the plan should be charged" }, "expire_after_specific_number_of_charges": { "type": "integer", "description": "A maximum number of charges on which the subscription should appear before automatic cancellation." }, "order_day_of_month": { "type": "integer", "description": "Day of the month an order should be generated when the customer is subscribed." }, "order_day_of_week": { "type": "integer", "description": "Day of the week an order should be generated when the customer is subscribed." }, "order_interval_frequency": { "type": "integer", "description": "Frequency at which the subscriber will receive shipments when subscribed to this plan." }, "interval_unit": { "type": "string", "description": "The unit applied to charge_interval_frequency and order_interval_frequency .", "enum": [ "day", "week", "month" ] } }, "description": "An object containing the various subscription preferences associated with the line_item ." }, "taxable": { "type": "boolean", "description": "Whether tax is to be applied to the line_item ." }, "title": { "type": "string", "description": "The title of the Product of this line_item ." }, "unit_price": { "type": "string", "description": "The unit price of the line_item ." }, "variant_title": { "type": "string", "description": "The title of the Product variant associated with the line_item ." }, "weight": { "type": "integer", "description": "The total weight of the line_item ." } }, "required": [ "external_variant_id", "quantity" ] }, "description": "A list of items included in the Checkout" }, "note": { "type": "string", "description": "Custom note." }, "order_attributes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name for the attribute." }, "value": { "type": "string", "description": "The value for the associated attribute." } } }, "description": "List of name-value pairs for custom attributes." }, "payments": { "type": "array", "items": { "type": "object", "properties": { "payment_type": { "type": "string", "description": "The type of the additional payment method: stored_value for store credits or gift_card for a gift card." }, "payment_processor": { "type": "string", "description": "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_token": { "type": "string", "description": "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_token": { "type": "string", "description": "An authorization token for the payment method." } }, "required": [ "payment_type", "payment_processor", "payment_token" ] }, "description": "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." }, "shipping_address": { "type": "object", "properties": { "address1": { "type": "string", "description": "Line one of the billing address." }, "address2": { "type": "string", "description": "Line two of the billing address." }, "city": { "type": "string", "description": "The city of the billing address." }, "company": { "type": "string", "description": "The company name of the billing address." }, "country_code": { "type": "string", "description": "2-letter country code." }, "first_name": { "type": "string", "description": "The first name of the billing address." }, "last_name": { "type": "string", "description": "The last name of the billing address." }, "phone": { "type": "string", "description": "The phone number of the billing address." }, "province": { "type": "string", "description": "The name of the province or state associated with the billing address." }, "shipping_lines_override": { "type": "array", "items": {}, "description": "Shipping lines to set as the shipping lines override of the Address created when the Checkout is processed." }, "zip": { "type": "string", "description": "The zip code or postcode of the address." } }, "required": [ "address1", "city", "country_code", "last_name" ], "description": "Shipping Address for the Checkout ." } }, "required": [ "line_items" ] }, "example": { "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_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" } } } } }, "x-recharge-scopes": [ "write_checkouts" ] } }, "/checkouts/{token}": { "get": { "operationId": "checkout_retrieve", "summary": "Retrieve a checkout", "description": "Retrieve a checkout.", "tags": [ "Checkouts" ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "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_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" } } } } } }, "x-recharge-scopes": [ "read_checkouts" ] }, "put": { "operationId": "checkout_update", "summary": "Update a checkout", "description": "You can modify an existing checkout to match the specified parameters.", "tags": [ "Checkouts" ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "get_shipping_rates", "in": "query", "required": false, "description": "If specified as a query parameter, shipping rates will be retrieved and will allow providing applied_shipping_rate upon checkout update.", "schema": { "type": "boolean" } }, { "name": "partial_shipping", "in": "query", "required": false, "description": "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 .", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "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": "", "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" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "analytics_data": { "type": "object", "properties": { "utm_params": { "type": "array", "items": { "type": "object", "properties": { "utm_campaign": { "type": "string", "description": "The UTM campaign." }, "utm_content": { "type": "string", "description": "The UTM content." }, "utm_data_source": { "type": "string", "description": "The source of the campaign parameter." }, "utm_source": { "type": "string", "description": "The UTM source." }, "utm_medium": { "type": "string", "description": "The UTM medium." }, "utm_term": { "type": "string", "description": "The UTM term." }, "utm_timestamp": { "type": "string", "description": "The UTM timestamp." } }, "required": [ "utm_data_source", "utm_timestamp" ] }, "description": "An array containing utm_param objects." } }, "description": "Urchin Tracking Module (UTM) parameters are used for online marketing campaigns." }, "applied_discounts": { "type": "array", "items": { "type": "object", "properties": { "discount_code": { "type": "string", "description": "The code for the Discount , e.g. 25_PERCENT_OFF ." } } }, "description": "Discount to apply to the Checkout . Send an empty array to remove the applied discount." }, "applied_shipping_rate": { "type": "object", "properties": { "code": { "type": "string", "description": "Code corresponding to the category of shipping." }, "delivery_range": { "type": "string" }, "description": { "type": "string" }, "handle": { "type": "string", "description": "Unique string identifying the shipping/" }, "name": { "type": "string" }, "phone_required": { "type": "string", "description": "Whether a phone is required for this shipping." }, "price": { "type": "string", "description": "Price of shipping." }, "title": { "type": "string" } }, "description": "Shipping rates details, populated once the rates have been selected and applied successfully to the Checkout ." }, "billing_address": { "type": "object", "properties": { "address1": { "type": "string", "description": "Line one of the billing address." }, "address2": { "type": "string", "description": "Line two of the billing address." }, "city": { "type": "string", "description": "The city of the billing address." }, "company": { "type": "string", "description": "The company name of the billing address." }, "country_code": { "type": "string", "description": "2-letter country code." }, "first_name": { "type": "string", "description": "The first name of the billing address." }, "last_name": { "type": "string", "description": "The last name of the billing address." }, "phone": { "type": "string", "description": "The phone number of the billing address." }, "province": { "type": "string", "description": "The name of the province or state associated with the billing address." }, "zip": { "type": "string", "description": "The zip code or postcode of the address." } }, "required": [ "address1", "city", "country_code", "last_name" ], "description": "Billing address for the checkout." }, "custom_shipping_rate_options": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Code for the shipping rate." }, "price": { "type": "string", "description": "Price for the shipping rate." }, "title": { "type": "string", "description": "Title for the shipping rate." }, "handle": { "type": "string", "description": "Unique identifier for the shipping rate." } }, "required": [ "code", "price", "title", "handle" ] }, "description": "List of available shipping rates to use when selecting a shipping rate with applied_shipping_rate ." }, "currency": { "type": "string", "description": "Currency of the Checkout ." }, "email": { "type": "string", "description": "Email address for the customer." }, "external_checkout_id": { "type": "string", "description": "Represents the external cart token." }, "external_checkout_source": { "type": "string", "description": "Represents the source for external_checkout_id .", "enum": [ "big_commerce", "headless", "magento", "shopify" ] }, "line_items": { "type": "array", "items": { "type": "object", "properties": { "external_line_item_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "The line item ID as it appears in the external e-commerce platform." } }, "description": "An object containing the ID of the line item as it appears in the external system." }, "external_product_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "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 ." } }, "required": [ "ecommerce" ], "description": "An object containing the associated product ID as it appears in the external system." }, "external_variant_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "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 ." } }, "required": [ "ecommerce" ], "description": "An object containing the associated variant ID as it appears in the external system." }, "handle": { "type": "string", "description": "A unique, human-friendly string for the Product ." }, "images": { "type": "object", "properties": { "large": { "type": "string", "description": "The url where a large image file is located." }, "medium": { "type": "string", "description": "The url where a medium image file is located." }, "small": { "type": "string", "description": "The url where a small image file is located." }, "original": { "type": "string", "description": "The url of the original sized product image." } }, "description": "An object containing URLs of the Product image." }, "properties": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the property." }, "value": { "type": "string", "description": "The value of the property." } } }, "description": "An array of name value pairs of additional line_item attributes." }, "quantity": { "type": "integer", "description": "The quantity of the line_item ." }, "recurring_unit_price": { "type": "string", "description": "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_shipping": { "type": "boolean", "description": "Whether the item requires shipping. Defaults to the value of the product in the catalog." }, "sku": { "type": "string", "description": "The SKU (stock keeping unit) of the Product associated with the line_item ." }, "subscription_preferences": { "type": "object", "properties": { "charge_interval_frequency": { "type": "integer", "description": "Frequency at which the subscriber will be charged." }, "cutoff_day_of_month": { "type": "integer", "description": "Day of the month the plan should be charged" }, "cutoff_day_of_week": { "type": "integer", "description": "Day of the month the plan should be charged" }, "expire_after_specific_number_of_charges": { "type": "integer", "description": "A maximum number of charges on which the subscription should appear before automatic cancellation." }, "order_day_of_month": { "type": "integer", "description": "Day of the month an order should be generated when the customer is subscribed." }, "order_day_of_week": { "type": "integer", "description": "Day of the week an order should be generated when the customer is subscribed." }, "order_interval_frequency": { "type": "integer", "description": "Frequency at which the subscriber will receive shipments when subscribed to this plan." }, "interval_unit": { "type": "string", "description": "The unit applied to charge_interval_frequency and order_interval_frequency .", "enum": [ "day", "week", "month" ] } }, "description": "An object containing the various subscription preferences associated with the line_item ." }, "taxable": { "type": "boolean", "description": "Whether tax is to be applied to the line_item ." }, "title": { "type": "string", "description": "The title of the Product of this line_item ." }, "unit_price": { "type": "string", "description": "The unit price of the line_item ." }, "variant_title": { "type": "string", "description": "The name of a variant of the Product of this line_item ." }, "weight": { "type": "integer", "description": "The total weight in grams of the line_item ." } }, "required": [ "external_variant_id", "quantity" ] }, "description": "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." }, "note": { "type": "string", "description": "Note attribute used to store custom notes." }, "order_attributes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name for the attribute." }, "value": { "type": "string", "description": "The value for the associated attribute." } } }, "description": "Structured custom notes." }, "payments": { "type": "array", "items": { "type": "object", "properties": { "payment_type": { "type": "string", "description": "The type of the additional payment method: stored_value for store credits or gift_card for a gift card." }, "payment_processor": { "type": "string", "description": "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_token": { "type": "string", "description": "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_token": { "type": "string", "description": "An authorization token for the payment method." } }, "required": [ "payment_type", "payment_processor", "payment_token" ] }, "description": "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." }, "shipping_address": { "type": "object", "properties": { "address1": { "type": "string", "description": "Line one of the billing address." }, "address2": { "type": "string", "description": "Line two of the billing address." }, "city": { "type": "string", "description": "The city of the billing address." }, "company": { "type": "string", "description": "The company name of the billing address." }, "country_code": { "type": "string", "description": "2-letter country code." }, "first_name": { "type": "string", "description": "The first name of the billing address." }, "last_name": { "type": "string", "description": "The last name of the billing address." }, "phone": { "type": "string", "description": "The phone number of the billing address." }, "province": { "type": "string", "description": "The name of the province or state associated with the billing address." }, "shipping_lines_override": { "type": "array", "items": {}, "description": "Shipping lines to set as the shipping lines override of the Address created when the Checkout is processed." }, "zip": { "type": "string", "description": "The zip code or postcode of the address." } }, "required": [ "address1", "city", "country_code", "last_name" ], "description": "Shipping address for the checkout." } } }, "example": { "line_items": [ { "product_id": 4546063663207, "quantity": 6, "variant_id": 3844924611 } ] } } } }, "x-recharge-scopes": [ "write_checkouts" ] } }, "/checkouts/{token}/shipping_rates": { "get": { "operationId": "checkout_retrieve_shipping_address", "summary": "Retrieve shipping rates", "description": "You can retrieve all shipping rates for a specific checkout.", "tags": [ "Checkouts" ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "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" } ] } } } } }, "x-recharge-scopes": [ "read_checkouts" ] } }, "/checkouts/{token}/process": { "post": { "operationId": "checkout_process", "summary": "Process a checkout", "description": "You can process and charge checkout using our API.", "tags": [ "Checkouts" ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "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" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "authorization_token": { "type": "string", "description": "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_opportunity": { "type": "boolean", "description": "Whether to hold the payment as an authorization so that post-purchase upsell items can be added before it is captured." }, "free": { "type": "boolean", "description": "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_data": { "type": "object", "properties": { "customer_acceptance": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of acceptance, e.g. online . Required when customer_acceptance is sent." }, "accepted_at": { "type": "integer", "description": "Timestamp of when the customer accepted the mandate. Required when customer_acceptance is sent." }, "online": { "type": "object", "properties": { "ip_address": { "type": "string", "description": "The IP address from which the customer accepted the mandate." }, "user_agent": { "type": "string", "description": "The user agent of the browser from which the customer accepted the mandate." } }, "description": "Details of an online mandate acceptance." } }, "description": "Details of how the customer accepted the mandate." } }, "description": "Mandate acceptance details for bank debit payments." }, "payment_processor": { "type": "string", "description": "The name of payment processor.", "enum": [ "authorize", "braintree", "stripe", "mollie" ] }, "payment_processor_return_url": { "type": "string", "description": "The URL the customer is returned to after authorizing the payment with their bank." }, "payment_type": { "type": "string", "description": "The payment type used for the Checkout .", "enum": [ "CREDIT_CARD", "PAYPAL", "APPLE_PAY", "GOOGLE_PAY", "SEPA_DEBIT", "IDEAL", "SHOP_PAY", "PAYPAL_EXPRESS", "SOFORT", "GIROPAY", "STORED_VALUE", "AMAZON_PAY", "INVOICE", "AFTERPAY_CLEARPAY", "KLARNA" ] }, "processor_customer_token": { "type": "string", "description": "The ID of the customer in the payment processor." }, "processor_payment_method_token": { "type": "string", "description": "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 ." } }, "required": [ "payment_processor" ] }, "example": { "payment_processor": "stripe", "payment_token": "", "payment_type": "CREDIT_CARD" } } } }, "x-recharge-scopes": [ "write_checkouts" ] } }, "/checkouts/{token}/line_items": { "get": { "operationId": "checkout_line_items_list", "summary": "List line items of a checkout", "description": "Returns the line items of a Checkout . Each item has the same attributes as line_items on the Checkout object.", "tags": [ "Checkouts" ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "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" } ] } } } } }, "x-recharge-scopes": [ "read_checkouts" ] }, "post": { "operationId": "checkout_line_items_create", "summary": "Add line items to a checkout", "description": "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.", "tags": [ "Checkouts" ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "OK: The request was successful, created a new resource, and resource created is in the body.", "content": { "application/json": { "example": { "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" } ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "line_items": { "type": "array", "items": { "type": "object", "properties": { "external_variant_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "The variant id as it appears in the external e-commerce platform." } }, "required": [ "ecommerce" ], "description": "An object containing the associated variant ID as it appears in the external system." }, "quantity": { "type": "integer", "description": "The quantity of the line_item . Must be at least 1." }, "external_product_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "The product id as it appears in the external e-commerce platform." } }, "description": "An object containing the associated product ID as it appears in the external system." }, "unit_price": { "type": "string", "description": "The unit price of the line_item ." }, "recurring_unit_price": { "type": "string", "description": "The price of a single unit of the line_item that will be charged on recurring orders. Only applies to subscription line items." }, "subscription_preferences": { "type": "object", "properties": { "charge_interval_frequency": { "type": "integer", "description": "Frequency at which the subscriber will be charged." }, "order_interval_frequency": { "type": "integer", "description": "Frequency at which the subscriber will receive shipments." }, "interval_unit": { "type": "string", "description": "The unit applied to charge_interval_frequency and order_interval_frequency .", "enum": [ "day", "week", "month" ] } }, "description": "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." }, "properties": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the property." }, "value": { "type": "string", "description": "The value of the property." } } }, "description": "An array of name value pairs of additional line_item attributes." }, "title": { "type": "string", "description": "The title of the Product of this line_item ." }, "variant_title": { "type": "string", "description": "The title of the Product variant associated with the line_item ." }, "sku": { "type": "string", "description": "The SKU (stock keeping unit) of the Product associated with the line_item ." }, "weight": { "type": "integer", "description": "The weight of a single unit of the line_item , in grams." }, "requires_shipping": { "type": "boolean", "description": "Whether the item requires shipping." } }, "required": [ "external_variant_id", "quantity" ] }, "description": "A list of line items." } }, "required": [ "line_items" ] } } } }, "x-recharge-scopes": [ "write_checkouts" ] }, "put": { "operationId": "checkout_line_items_bulk_update", "summary": "Update line items of a checkout", "description": "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 .", "tags": [ "Checkouts" ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "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" } ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "line_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier of the line_item to update." }, "external_variant_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "The variant id as it appears in the external e-commerce platform." } }, "required": [ "ecommerce" ], "description": "An object containing the associated variant ID as it appears in the external system." }, "quantity": { "type": "integer", "description": "The quantity of the line_item . Must be at least 1." }, "external_product_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "The product id as it appears in the external e-commerce platform." } }, "description": "An object containing the associated product ID as it appears in the external system." }, "unit_price": { "type": "string", "description": "The unit price of the line_item ." }, "recurring_unit_price": { "type": "string", "description": "The price of a single unit of the line_item that will be charged on recurring orders. Only applies to subscription line items." }, "subscription_preferences": { "type": "object", "properties": { "charge_interval_frequency": { "type": "integer", "description": "Frequency at which the subscriber will be charged." }, "order_interval_frequency": { "type": "integer", "description": "Frequency at which the subscriber will receive shipments." }, "interval_unit": { "type": "string", "description": "The unit applied to charge_interval_frequency and order_interval_frequency .", "enum": [ "day", "week", "month" ] } }, "description": "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." }, "properties": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the property." }, "value": { "type": "string", "description": "The value of the property." } } }, "description": "An array of name value pairs of additional line_item attributes." }, "title": { "type": "string", "description": "The title of the Product of this line_item ." }, "variant_title": { "type": "string", "description": "The title of the Product variant associated with the line_item ." }, "sku": { "type": "string", "description": "The SKU (stock keeping unit) of the Product associated with the line_item ." }, "weight": { "type": "integer", "description": "The weight of a single unit of the line_item , in grams." }, "requires_shipping": { "type": "boolean", "description": "Whether the item requires shipping." } }, "required": [ "id", "external_variant_id", "quantity" ] }, "description": "A list of line items." } }, "required": [ "line_items" ] } } } }, "x-recharge-scopes": [ "write_checkouts" ] }, "delete": { "operationId": "checkout_line_items_bulk_delete", "summary": "Remove line items from a checkout", "description": "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.", "tags": [ "Checkouts" ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content: The request was successful and there is no content to return." } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "line_item_ids": { "type": "array", "items": {}, "description": "The id values of the line items to remove." } }, "required": [ "line_item_ids" ] } } } }, "x-recharge-scopes": [ "write_checkouts" ] } }, "/checkouts/{token}/line_items/{line_item_id}": { "get": { "operationId": "checkout_line_item_retrieve", "summary": "Retrieve a line item of a checkout", "description": "Returns a single line item of a Checkout by its id .", "tags": [ "Checkouts" ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "line_item_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "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" } } } } } }, "x-recharge-scopes": [ "read_checkouts" ] }, "put": { "operationId": "checkout_line_item_update", "summary": "Update a line item of a checkout", "description": "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.", "tags": [ "Checkouts" ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "line_item_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "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" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "quantity": { "type": "integer", "description": "The quantity of the line_item . Must be at least 1." }, "unit_price": { "type": "string", "description": "The unit price of the line_item ." }, "recurring_unit_price": { "type": "string", "description": "The price of a single unit of the line_item that will be charged on recurring orders. Only applies to subscription line items." }, "subscription_preferences": { "type": "object", "properties": { "charge_interval_frequency": { "type": "integer", "description": "Frequency at which the subscriber will be charged." }, "order_interval_frequency": { "type": "integer", "description": "Frequency at which the subscriber will receive shipments." }, "interval_unit": { "type": "string", "description": "The unit applied to charge_interval_frequency and order_interval_frequency .", "enum": [ "day", "week", "month" ] } }, "description": "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." }, "properties": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the property." }, "value": { "type": "string", "description": "The value of the property." } } }, "description": "An array of name value pairs of additional line_item attributes." }, "requires_shipping": { "type": "boolean", "description": "Whether the item requires shipping." } } } } } }, "x-recharge-scopes": [ "write_checkouts" ] }, "delete": { "operationId": "checkout_line_item_delete", "summary": "Remove a line item from a checkout", "description": "Removes a single line item from a Checkout and recalculates it. The id values of the remaining line items are reassigned.", "tags": [ "Checkouts" ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "line_item_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content: The request was successful and there is no content to return." } }, "x-recharge-scopes": [ "write_checkouts" ] } }, "/checkouts/import": { "post": { "operationId": "checkout_import", "summary": "Import a checkout", "description": "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 .", "tags": [ "Checkouts" ], "responses": { "201": { "description": "OK: The request was successful, created a new resource, and resource created is in the body.", "content": { "application/json": { "example": { "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" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "payments": { "type": "array", "items": { "type": "object", "properties": { "payment_processor": { "type": "string", "description": "The name of the payment processor, or recharge_credits for store credits." }, "payment_type": { "type": "string", "description": "The payment type, e.g. CREDIT_CARD , or STORED_VALUE for store credits." }, "processor_payment_method_token": { "type": "string", "description": "Payment method token from the payment processor. Either this or authorization_token is required unless the payment is store credit." }, "authorization_token": { "type": "string", "description": "Token of a payment authorization that was already created with the payment processor." }, "payment_token": { "type": "string", "description": "The ID of the credit account. Required when payment_processor is recharge_credits ." } } }, "description": "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." }, "payment_data": { "type": "array", "items": {}, "description": "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_lines": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "The code associated with the shipping_line ." }, "price": { "type": "string", "description": "The price of the shipping_line ." }, "title": { "type": "string", "description": "The title of the shipping_line ." }, "source": { "type": "string", "description": "The source of the shipping_line ." }, "handle": { "type": "string", "description": "Unique identifier for the shipping rate." }, "taxable": { "type": "boolean", "description": "Whether the shipping_line is taxable." }, "tax_lines": { "type": "array", "items": {}, "description": "An array of tax lines associated with the shipping_line ." } } }, "description": "The shipping line to apply to the Checkout . Only the first entry is used." }, "tax_lines": { "type": "array", "items": { "type": "object", "properties": { "price": { "type": "string", "description": "The total tax associated with the listed jurisdiction." }, "rate": { "type": "string", "description": "The tax rate associated with the listed jurisdiction." }, "title": { "type": "string", "description": "The title/name of the taxing jurisdiction." } } }, "description": "Array of tax_line objects for the Checkout . Their prices are summed to obtain total_tax ." }, "line_items": { "type": "object", "properties": { "tax_lines": { "type": "array", "items": { "type": "object", "properties": { "price": { "type": "string", "description": "The total tax associated with the listed jurisdiction." }, "rate": { "type": "string", "description": "The tax rate associated with the listed jurisdiction." }, "title": { "type": "string", "description": "The title/name of the taxing jurisdiction." } } }, "description": "An array of tax_line objects associated with the line_item ." } } }, "total_price": { "type": "string", "description": "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_invoice": { "type": "boolean", "description": "Whether an invoice is sent to Avalara for this Checkout when the store uses Avalara for taxes. Defaults to true ." }, "send_taxjar_invoice": { "type": "boolean", "description": "Whether an invoice is sent to TaxJar for this Checkout when the store uses TaxJar for taxes. Defaults to true ." } }, "required": [ "line_items" ] } } } }, "x-recharge-scopes": [ "write_checkouts" ] } }, "/collections": { "post": { "operationId": "collection_create", "summary": "Create a collection", "description": "Create a Collection in Recharge.", "tags": [ "Collections" ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "collection": { "id": 134157, "created_at": "2022-03-29T04:57:36+00:00", "description": "cat products new release", "manual_sort_order": [], "sort_order": "id-desc", "title": "Cats Spring 2022", "type": "manual", "updated_at": "2020-12-17T18:50:39+00:00" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "description": "The Collection description. Used to store a detailed explanation of the Collection content and its purpose." }, "sort_order": { "type": "string", "description": "The order in which the Products in the collection should appear.", "enum": [ "id-asc", "id-desc", "created_at-asc", "created_at-desc", "updated_at-asc", "updated_at-desc", "title-asc", "title-desc", "manual" ], "default": "id-desc" }, "title": { "type": "string", "description": "The title of the Collection . A short descriptive definition of the Collection ." }, "type": { "type": "string", "description": "The type of the Collection . Defaults to manual . It cannot be changed after the collection is created.", "enum": [ "automatic", "manual" ] } }, "required": [ "description", "title" ] }, "example": { "description": "cat products new release", "title": "Cats Spring 2022" } } } }, "x-recharge-scopes": [ "write_products" ] }, "get": { "operationId": "collections_list", "summary": "List collections", "description": "Return a list of Collections in your store. HTTP request examples GET /collections GET /collections?title=Cats", "tags": [ "Collections" ], "parameters": [ { "name": "title", "in": "query", "required": false, "description": "The title of the Collection . A short descriptive definition of the Collection .", "schema": { "type": "string" } }, { "name": "ids", "in": "query", "required": false, "description": "Filter collections by id. If passing multiple values, must be comma separated.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "Return the collections of a specific type.", "schema": { "type": "string", "enum": [ "automatic", "manual" ] } }, { "name": "sort_by", "in": "query", "required": false, "description": "The order in which the collections are returned. Defaults to id-desc .", "schema": { "type": "string", "enum": [ "id-asc", "id-desc", "created_at-asc", "created_at-desc", "updated_at-asc", "updated_at-desc", "title-asc", "title-desc" ] } }, { "name": "limit", "in": "query", "required": false, "description": "The number of results to return. Defaults to 50; the maximum is 250.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The 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 .", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "The page of results to show. Page-based pagination is deprecated in favor of cursor .", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "next_cursor": null, "previous_cursor": null, "collections": [ { "id": 134136, "created_at": "2022-03-28T15:38:27+00:00", "description": "cat products august 2022", "manual_sort_order": [], "sort_order": "title-asc", "title": "Cats", "type": "manual", "updated_at": "2022-03-28T15:38:27+00:00" }, { "id": 134129, "created_at": "2022-03-28T12:27:03+00:00", "description": "kitten accessories soft.", "manual_sort_order": [], "sort_order": "id-asc", "title": "Soft Kitty", "type": "manual", "updated_at": "2022-02-23T11:27:34+00:00" } ] } } } } }, "x-recharge-scopes": [ "read_products" ] } }, "/collections/{id}": { "get": { "operationId": "collection_retrieve", "summary": "Retrieve a collection", "description": "Retrieve one Collection using collection_id .", "tags": [ "Collections" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "collection": { "id": 134157, "created_at": "2022-03-29T04:57:36+00:00", "description": "cat products new release", "manual_sort_order": [], "sort_order": "id-desc", "title": "Cats Spring 2022", "type": "manual", "updated_at": "2022-03-29T04:57:36+00:00" } } } } }, "404": { "description": "Not found", "content": { "application/json": { "example": { "error": "Not found." } } } } }, "x-recharge-scopes": [ "read_products" ] }, "put": { "operationId": "collection_update", "summary": "Update a collection", "description": "Modify an existing Collection to match the specified parameters.", "tags": [ "Collections" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "collection": { "id": 134157, "created_at": "2022-03-29T04:57:36+00:00", "description": "cats products new release", "manual_sort_order": [], "sort_order": "title-asc", "title": "Cats Spring 2022", "type": "manual", "updated_at": "2022-03-29T05:27:39+00:00" } } } } }, "404": { "description": "Not found", "content": { "application/json": { "example": { "error": "Not found." } } } }, "415": { "description": "Unprocessable entity", "content": { "application/json": { "example": { "errors": { "sort_order": [ "Not a valid choice." ] } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "description": "The Collection description. Used to store a detailed explanation of the Collection content and its purpose." }, "sort_order": { "type": "string", "description": "The order in which the Products in the collection should appear.", "enum": [ "id-asc", "id-desc", "created_at-asc", "created_at-desc", "updated_at-asc", "updated_at-desc", "title-asc", "title-desc", "manual" ] }, "title": { "type": "string", "description": "The title of the Collection . A short descriptive definition of the Collection ." }, "manual_sort_order": { "type": "array", "items": {}, "description": "An 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." } } }, "example": { "sort_order": "title-asc" } } } }, "x-recharge-scopes": [ "write_products" ] }, "delete": { "operationId": "collection_delete", "summary": "Delete a collection", "description": "Delete a Collection", "tags": [ "Collections" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Content Deleted: The server has successfully fulfilled the request and deleted the desired object and there is no content to send in the response body.", "content": { "application/json": { "example": {} } } }, "404": { "description": "Not found", "content": { "application/json": { "example": { "error": "Not found." } } } } }, "x-recharge-scopes": [ "write_products" ] } }, "/collection_products": { "get": { "operationId": "collection_products", "summary": "List collections products", "description": "Return a list of the product ids included in Collections in your store. HTTP request examples GET /collection_products GET /collection_products?collection_id=134157", "tags": [ "Collections" ], "parameters": [ { "name": "collection_id", "in": "query", "required": false, "description": "The id of the Collection for which you want to see the products.", "schema": { "type": "integer" } }, { "name": "external_product_id", "in": "query", "required": false, "description": "Return only the collection products with the given external_product_id , which shows the collections a product belongs to.", "schema": { "type": "string" } }, { "name": "sort_by", "in": "query", "required": false, "description": "The order in which the results are returned. Defaults to id-desc .", "schema": { "type": "string", "enum": [ "id-asc", "id-desc" ] } }, { "name": "limit", "in": "query", "required": false, "description": "The number of results to return. Defaults to 50; the maximum is 250.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The 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 .", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "The page of results to show. Page-based pagination is deprecated in favor of cursor .", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "next_cursor": null, "previous_cursor": null, "collection_products": [ { "collection_id": 111733, "created_at": "2022-03-30T18:12:09+00:00", "external_product_id": "5", "updated_at": "2022-03-30T18:12:09+00:00" }, { "collection_id": 111733, "created_at": "2022-02-12T12:53:33+00:00", "external_product_id": "2", "updated_at": "2022-02-12T12:53:33+00:00" }, { "collection_id": 111735, "created_at": "2022-02-12T06:46:49+00:00", "external_product_id": "3", "updated_at": "2022-02-12T06:46:49+00:00" } ] } } } }, "422": { "description": "Errors. Unprocessable entity.", "content": { "application/json": { "example": { "errors": { "collection_id": [ "Not a valid integer." ] } } } } } }, "x-recharge-scopes": [ "read_products" ] } }, "/collections/{id}/collection_products-bulk": { "post": { "operationId": "collection_products_add", "summary": "Add collection products", "description": "Add products to a Collection in Recharge.", "tags": [ "Collections" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "successful response", "content": { "application/json": { "example": { "collection_products": [ { "collection_id": 111733, "created_at": "2022-03-29T04:57:36+00:00", "external_product_id": "7", "updated_at": "2022-03-30T18:32:35+00:00" } ] } } } }, "422": { "description": "unprocessable entity", "content": { "application/json": { "example": { "errors": { "collection_products": { "0": { "_schema": [ "product_id is a required field." ] } } } } } } }, "500": { "description": "internal server error. (often the external_product_id entered does not exist)", "content": { "application/json": { "example": { "error": "internal server error. Please try again." } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "collection_products": { "type": "array", "items": { "type": "object", "properties": { "external_product_id": { "type": "string", "description": "The external_product_id.ecommerce of the Product ." } }, "required": [ "external_product_id" ] }, "description": "An array of products and their collection definition to be added to the Collection ." } }, "required": [ "collection_products" ] }, "example": { "collection_products": [ { "external_product_id": "7" } ] } } } }, "x-recharge-scopes": [ "write_products" ] }, "delete": { "operationId": "collection_products_delete", "summary": "Delete collection products", "description": "Removes products from a Collection in Recharge.", "tags": [ "Collections" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Content Deleted: The server has successfully fulfilled the request and deleted the desired object and there is no content to send in the response body.", "content": { "application/json": { "example": {} } } }, "404": { "description": "Not found", "content": { "application/json": { "example": { "error": "Not found." } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "collection_products": { "type": "array", "items": { "type": "object", "properties": { "external_product_id": { "type": "string", "description": "The external_product_id.ecommerce of the Product ." } }, "required": [ "external_product_id" ] }, "description": "The array of products to be removed from the Collection identified by their external_product_id ." } }, "required": [ "collection_products" ] } } } }, "x-recharge-scopes": [ "write_products" ] } }, "/collections/{id}/modify_sort": { "post": { "operationId": "collection_modify_sort", "summary": "Reorder collection products", "description": "Changes the manual order of the Products in a Collection and returns the updated collection. Send exactly one of move_to_top , move_to_bottom or move_to_position . The moved products keep their order relative to each other, and products that are not in the collection are ignored.", "tags": [ "Collections" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "collection": { "id": 134129, "created_at": "2026-03-02T15:04:31", "description": "Our seasonal coffee selection", "manual_sort_order": [ "7654321099", "7654321098" ], "sort_order": "manual", "title": "Seasonal coffees", "type": "manual", "updated_at": "2026-03-04T09:12:00" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "move_to_top": { "type": "array", "items": {}, "description": "An array of external_product_id values to move to the top of the collection." }, "move_to_bottom": { "type": "array", "items": {}, "description": "An array of external_product_id values to move to the bottom of the collection." }, "move_to_position": { "type": "object", "properties": { "external_product_ids": { "type": "array", "items": {}, "description": "An array of external_product_id values to move. Required, with at least one value." }, "new_position": { "type": "integer", "description": "The position, starting at 1, to which the first of the products is moved. Required." } }, "description": "An object describing products to move to a specific position in the collection." } } } } } }, "x-recharge-scopes": [ "write_products" ] } }, "/credit_accounts": { "post": { "operationId": "credit_account_create", "summary": "Create a credit account", "description": "Create a new credit account.", "tags": [ "Credits" ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "credit_account": { "id": 697470, "customer_id": 36885098, "available_balance": "0.00", "created_at": "2024-07-08T20:40:30+00:00", "currency_code": "USD", "expires_at": null, "initial_value": "0.45", "name": "Reward Credit", "type": "reward", "updated_at": "2024-07-08T20:40:30+00:00" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "integer", "description": "The ID of the customer to create the credit account for." }, "expires_at": { "type": "string", "format": "date-time", "description": "The date and time at which the credit account expires, and can no longer be adjusted." }, "initial_value": { "type": "string", "description": "The initial value of the credit account at the time of creation." }, "name": { "type": "string", "description": "The name of the credit account." }, "type": { "type": "string", "description": "The type of the credit account. Accepted values are reward and manual .", "enum": [ "manual", "reward" ] } } } } } }, "x-recharge-scopes": [ "write_credit_accounts" ] }, "get": { "operationId": "credit_account_list", "summary": "List credit accounts", "description": "Return a list of credit accounts.", "tags": [ "Credits" ], "parameters": [ { "name": "customer_id", "in": "query", "required": false, "description": "Return the list of credit accounts linked to the given Recharge customer_id", "schema": { "type": "string" } }, { "name": "customer_ids", "in": "query", "required": false, "description": "Return the list of credit accounts linked to any of the given Recharge customer_ids . If passing multiple values, must be comma separated. Non-integer values will result in a 422 error", "schema": { "type": "string" } }, { "name": "expires_at_min", "in": "query", "required": false, "description": "Return the list of credit accounts that expire after the given date (inclusive).", "schema": { "type": "string", "format": "date-time" } }, { "name": "expires_at_max", "in": "query", "required": false, "description": "Return the list of credit accounts that expire before the given date (inclusive).", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "description": "The amount of results. Default is 50 while the maximum is 250.", "schema": { "type": "string" } }, { "name": "ids", "in": "query", "required": false, "description": "Filter credit accounts by id. If passing multiple values, must be comma separated.", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "Only supported value is customer . If customer is included, the response will include the customer object.", "schema": { "type": "string", "enum": [ "customer" ] } }, { "name": "sort_by", "in": "query", "required": false, "description": "Sort 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 .", "schema": { "type": "string", "enum": [ "id-asc", "id-desc", "expires_at-asc", "expires_at-desc" ] } }, { "name": "page", "in": "query", "required": false, "description": "The page to show. Cursor pagination is recommended instead.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Return 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 .", "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "next_cursor": "eyJzdGFydGluZ19iZWZvcmVfaWQiOjQ5ODg2NywibGFzdF92YWx1ZSI6NDk4ODY3LCJzb3J0X2J5IjoiaWQtZGVzYyIsImN1cnNvcl9kaXIiOiJuZXh0In0", "previous_cursor": null, "credit_accounts": [ { "id": 697470, "customer_id": 36885098, "available_balance": "0.00", "created_at": "2024-07-08T20:40:30+00:00", "currency_code": "USD", "expires_at": null, "initial_value": "0.45", "name": "Reward Credit", "type": "reward", "updated_at": "2024-07-08T20:40:30+00:00" } ] } } } } }, "x-recharge-scopes": [ "read_credit_accounts" ] } }, "/credit_accounts/{id}": { "get": { "operationId": "credit_account_retrieve", "summary": "Retrieve a credit account", "description": "Retrieve one credit account using credit_account_id .", "tags": [ "Credits" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "Only supported value is customer . If customer is included, the response will include the customer object.", "schema": { "type": "string", "enum": [ "customer" ] } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "credit_account": { "id": 697470, "customer_id": 36885098, "available_balance": "0.00", "created_at": "2024-07-08T20:40:30+00:00", "currency_code": "USD", "expires_at": null, "initial_value": "0.45", "name": "Reward Credit", "type": "reward", "updated_at": "2024-07-08T20:40:30+00:00" } } } } } }, "x-recharge-scopes": [ "read_credit_accounts" ] }, "put": { "operationId": "credit_account_update", "summary": "Update a credit account", "description": "Update a credit account name, expiration date or assign to a customer.", "tags": [ "Credits" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "credit_account": { "id": 697470, "customer_id": 36885098, "available_balance": "0.00", "created_at": "2024-07-08T20:40:30+00:00", "currency_code": "USD", "expires_at": null, "initial_value": "0.45", "name": "Reward Credit", "type": "reward", "updated_at": "2024-07-08T20:40:30+00:00" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the credit account." }, "customer_id": { "type": "integer", "description": "The ID of the customer to assign the credit account to." }, "expires_at": { "type": "string", "format": "date-time", "description": "The date and time at which the credit account expires, and can no longer be adjusted." } } } } } }, "x-recharge-scopes": [ "write_credit_accounts" ] } }, "/credit_accounts/{id}/credit_adjustments": { "post": { "operationId": "credit_adjustment_create", "summary": "Create a credit adjustment", "description": "Create a new credit adjustment for a specific credit account using credit_account_id .", "tags": [ "Credits" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "credit_adjustment": [ { "id": 4866849, "credit_account_id": 697470, "amount": "0.45", "created_at": "2024-08-08T04:06:37+00:00", "created_by": { "resource_id": null, "identifier": "API", "type": "external" }, "currency_code": "USD", "ending_balance": "0.00", "note": "Amount related with order Charge Id: 11888235", "type": "debit", "updated_at": "2024-08-08T04:06:37+00:00" } ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "string", "description": "The amount of the credit adjustment." }, "note": { "type": "string", "description": "The note for the credit adjustment." }, "type": { "type": "string", "description": "The type of the credit adjustment. Accepted values are debit and credit .", "enum": [ "debit", "credit" ] }, "reference_type": { "type": "string", "description": "The type of record the credit adjustment refers to. Defaults to external . The value is stored but is not returned in the response.", "enum": [ "charge", "credit_adjustment", "reward_program", "external", "internal", "manual_adjustment" ] } }, "required": [ "amount", "type" ] }, "example": { "amount": "10.00", "note": "Gift card purchase", "type": "debit" } } } }, "x-recharge-scopes": [ "write_credit_adjustments_credit", "write_credit_adjustments_debit" ] }, "get": { "operationId": "credit_adjustment_retrieve_by_credit_account", "summary": "List Credit Adjustments for a Credit Account", "description": "Retrieve credit adjustments associated with specific credit account using credit_account_id .", "tags": [ "Credits" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "The amount of results. Default is 50 while the maximum is 250.", "schema": { "type": "string" } }, { "name": "ids", "in": "query", "required": false, "description": "Return the list of credit adjustments linked to the given Recharge ids . If passing multiple values, must be comma separated.", "schema": { "type": "string" } }, { "name": "created_at_min", "in": "query", "required": false, "description": "Return the list of credit adjustments created after the given date.", "schema": { "type": "string" } }, { "name": "created_at_max", "in": "query", "required": false, "description": "Return the list of credit adjustments created before the given date.", "schema": { "type": "string" } }, { "name": "updated_at_min", "in": "query", "required": false, "description": "Return the list of credit adjustments updated after the given date.", "schema": { "type": "string" } }, { "name": "updated_at_max", "in": "query", "required": false, "description": "Return the list of credit adjustments updated before the given date.", "schema": { "type": "string" } }, { "name": "sort_by", "in": "query", "required": false, "description": "Sort 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 .", "schema": { "type": "string", "enum": [ "id-asc", "id-desc", "updated_at-asc", "updated_at-desc" ] } }, { "name": "page", "in": "query", "required": false, "description": "The page to show. Cursor pagination is recommended instead.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Return 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 .", "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "next_cursor": null, "previous_cursor": null, "credit_adjustments": [ { "id": 4866849, "credit_account_id": 697470, "amount": "0.45", "created_at": "2024-08-08T04:06:37+00:00", "currency_code": "USD", "ending_balance": "0.00", "note": "Amount related with shop order store.myshopify.com Address Id: 169902120 Charge Id: 1125729345", "type": "debit", "updated_at": "2024-08-08T04:06:37+00:00" }, { "id": 4719708, "credit_account_id": 697470, "amount": "0.45", "created_at": "2024-07-08T20:40:31+00:00", "currency_code": "USD", "ending_balance": "0.45", "note": "3% Cash back on curious tomatoes", "type": "credit", "updated_at": "2024-07-08T20:40:31+00:00" } ] } } } } }, "x-recharge-scopes": [ "read_credit_adjustments" ] } }, "/credit_adjustments": { "get": { "operationId": "credit_adjustment_list", "summary": "List credit adjustments", "description": "Retrieve a list of credit adjustments.", "tags": [ "Credits" ], "parameters": [ { "name": "ids", "in": "query", "required": false, "description": "Return the list of credit adjustments linked to the given Recharge ids . If passing multiple values, must be comma separated. Non-integer values will result in a 422 error", "schema": { "type": "string" } }, { "name": "created_at_min", "in": "query", "required": false, "description": "Return the list of credit adjustments created after the given date.", "schema": { "type": "string" } }, { "name": "created_at_max", "in": "query", "required": false, "description": "Return the list of credit adjustments created before the given date.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "The amount of results. Default is 50 while the maximum is 250.", "schema": { "type": "string" } }, { "name": "updated_at_min", "in": "query", "required": false, "description": "Return the list of credit adjustments updated after the given date.", "schema": { "type": "string" } }, { "name": "updated_at_max", "in": "query", "required": false, "description": "Return the list of credit adjustments updated before the given date.", "schema": { "type": "string" } }, { "name": "sort_by", "in": "query", "required": false, "description": "Sort 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 .", "schema": { "type": "string", "enum": [ "id-asc", "id-desc", "updated_at-asc", "updated_at-desc" ] } }, { "name": "page", "in": "query", "required": false, "description": "The page to show. Cursor pagination is recommended instead.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Return 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 .", "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "next_cursor": "eyJzdGFydGluZ19iZWZvcmVfaWQiOjQ4NjY4NDksImxhc3RfdmFsdWUiOjQ4NjY4NDksInNvcnRfYnkiOiJpZC1kZXNjIiwiY3Vyc29yX2RpciI6Im5leHQifQ", "previous_cursor": null, "credit_adjustments": [ { "id": 4866849, "credit_account_id": 697470, "amount": "0.45", "created_at": "2024-08-08T04:06:37+00:00", "created_by": { "resource_id": null, "identifier": "API", "type": "external" }, "currency_code": "USD", "ending_balance": "0.00", "note": "Amount related with shop order shop.myshopify.com. Address Id: 169902120 Charge Id: 1125729345", "type": "debit", "updated_at": "2024-08-08T04:06:37+00:00" } ] } } } } }, "x-recharge-scopes": [ "read_credit_adjustments" ] } }, "/credit_accounts/{id}/summary": { "get": { "operationId": "credit_account_summary", "summary": "Retrieve a credit account summary", "description": "Retrieve a credit account together with a summary of its credit adjustments: the current balance and the total amounts credited to and debited from the account.", "tags": [ "Credits" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "credit_account": { "id": 1234, "customer_id": 98765, "available_balance": "25.00", "created_at": "2026-01-15T14:30:00+00:00", "currency_code": "USD", "expires_at": null, "initial_value": "50.00", "name": "Manual Credit", "type": "manual", "updated_at": "2026-01-20T09:00:00+00:00", "adjustment_summary": { "available_balance": "25.00", "total_credits": "50.00", "total_debits": "25.00" } } } } } } }, "x-recharge-scopes": [ "read_credit_accounts" ] } }, "/credit_adjustments/{id}": { "get": { "operationId": "credit_adjustment_retrieve", "summary": "Retrieve a credit adjustment", "description": "Retrieve a credit adjustment by its ID.", "tags": [ "Credits" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "Only supported value is customer . If customer is included, the response will include the customer object.", "schema": { "type": "string", "enum": [ "customer" ] } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "credit_adjustment": { "id": 5551, "credit_account_id": 1234, "amount": "10.00", "created_at": "2026-01-20T09:00:00+00:00", "created_by": { "identifier": "API", "resource_id": null, "type": "external" }, "currency_code": "USD", "ending_balance": "35.00", "note": "Goodwill credit", "type": "credit", "updated_at": "2026-01-20T09:00:00+00:00" } } } } } }, "x-recharge-scopes": [ "read_credit_adjustments" ] } }, "/credit_accounts/{id}/credit_adjustments/{credit_adjustment_id}": { "get": { "operationId": "credit_adjustment_retrieve_for_credit_account", "summary": "Retrieve a credit adjustment for a credit account", "description": "Retrieve a credit adjustment that belongs to the given credit account. Returns a 404 if the credit adjustment does not belong to the credit account.", "tags": [ "Credits" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "credit_adjustment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "Only supported value is customer . If customer is included, the response will include the customer object.", "schema": { "type": "string", "enum": [ "customer" ] } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "credit_adjustment": { "id": 5551, "credit_account_id": 1234, "amount": "10.00", "created_at": "2026-01-20T09:00:00+00:00", "created_by": { "identifier": "API", "resource_id": null, "type": "external" }, "currency_code": "USD", "ending_balance": "35.00", "note": "Goodwill credit", "type": "credit", "updated_at": "2026-01-20T09:00:00+00:00" } } } } } }, "x-recharge-scopes": [ "read_credit_adjustments" ] }, "put": { "operationId": "credit_adjustment_update", "summary": "Update a credit adjustment", "description": "Update the note of a credit adjustment. No other attribute of a credit adjustment can be changed. Updating a credit adjustment requires the write_credit_adjustments_credit scope and updating a debit adjustment requires the write_credit_adjustments_debit scope.", "tags": [ "Credits" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "credit_adjustment_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "credit_adjustment": { "id": 5551, "credit_account_id": 1234, "amount": "10.00", "created_at": "2026-01-20T09:00:00+00:00", "created_by": { "identifier": "API", "resource_id": null, "type": "external" }, "currency_code": "USD", "ending_balance": "35.00", "note": "Goodwill credit for a delayed order", "type": "credit", "updated_at": "2026-01-21T11:15:00+00:00" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string", "description": "The note for the credit adjustment. Must be between 1 and 1000 characters." } } } } } }, "x-recharge-scopes": [ "write_credit_adjustments_credit", "write_credit_adjustments_debit" ] } }, "/customers/{id}/notification_preferences": { "get": { "operationId": "customer_notification_preferences_retrieve", "summary": "Retrieve a customer's notification preferences", "description": "Retrieves the notification preferences of a Customer . Preferences that the customer has never set are returned with a status of unspecified .", "tags": [ "Customer notification preferences" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "notification_preferences": { "email": { "transactional": { "status": "accepted", "last_opt_in_at": "2026-08-03T15:22:10+00:00", "last_opt_in_source": "api", "last_opt_out_at": null, "last_opt_out_source": null }, "promotional": { "status": "declined", "last_opt_in_at": null, "last_opt_in_source": null, "last_opt_out_at": "2026-08-20T09:41:55+00:00", "last_opt_out_source": "customer_portal" }, "replenishment": { "status": "unspecified", "last_opt_in_at": null, "last_opt_in_source": null, "last_opt_out_at": null, "last_opt_out_source": null } }, "sms": { "transactional": { "status": "unspecified", "last_opt_in_at": null, "last_opt_in_source": null, "last_opt_out_at": null, "last_opt_out_source": null }, "promotional": { "status": "unspecified", "last_opt_in_at": null, "last_opt_in_source": null, "last_opt_out_at": null, "last_opt_out_source": null }, "replenishment": { "status": "unspecified", "last_opt_in_at": null, "last_opt_in_source": null, "last_opt_out_at": null, "last_opt_out_source": null } } } } } } } }, "x-recharge-scopes": [ "read_customers" ] }, "put": { "operationId": "customer_notification_preferences_update", "summary": "Update a customer's notification preferences", "description": "Updates one or more notification preferences of a Customer . Only the preferences passed in the request are changed, and the opt in or opt out time is set to the time of the request. The response contains the preferences changed by the request; preferences that were not changed are returned with their default values.", "tags": [ "Customer notification preferences" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "notification_preferences": { "email": { "transactional": { "status": "unspecified", "last_opt_in_at": null, "last_opt_in_source": null, "last_opt_out_at": null, "last_opt_out_source": null }, "promotional": { "status": "accepted", "last_opt_in_at": "2026-09-02T11:05:42+00:00", "last_opt_in_source": "api", "last_opt_out_at": null, "last_opt_out_source": null }, "replenishment": { "status": "unspecified", "last_opt_in_at": null, "last_opt_in_source": null, "last_opt_out_at": null, "last_opt_out_source": null } }, "sms": { "transactional": { "status": "unspecified", "last_opt_in_at": null, "last_opt_in_source": null, "last_opt_out_at": null, "last_opt_out_source": null }, "promotional": { "status": "unspecified", "last_opt_in_at": null, "last_opt_in_source": null, "last_opt_out_at": null, "last_opt_out_source": null }, "replenishment": { "status": "unspecified", "last_opt_in_at": null, "last_opt_in_source": null, "last_opt_out_at": null, "last_opt_out_source": null } } } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "object", "properties": { "transactional": { "type": "object", "properties": { "status": { "type": "string", "description": "The new status of the notification preference.", "enum": [ "accepted", "declined" ] }, "last_opt_in_source": { "type": "string", "description": "The interface or process through which the customer opted in. Used when status is accepted .", "enum": [ "api", "bulk_update", "concierge", "customer_portal", "customer_sms", "merchant_portal", "recharge_checkout", "rechargesms_app", "sci_cart", "script", "shopify_checkout", "sms_reminder", "store_opt_in_widget", "subscription_checkout_extension", "thank_you_page" ] }, "last_opt_out_source": { "type": "string", "description": "The interface or process through which the customer opted out. Used when status is declined .", "enum": [ "api", "bulk_update", "concierge", "customer_portal", "customer_sms", "merchant_portal", "recharge_checkout", "rechargesms_app", "sci_cart", "script", "shopify_checkout", "sms_reminder", "store_opt_in_widget", "subscription_checkout_extension", "thank_you_page" ] } }, "description": "The preference for transactional communication on this channel. status is required when this object is passed." }, "promotional": { "type": "object", "properties": { "status": { "type": "string", "description": "The new status of the notification preference.", "enum": [ "accepted", "declined" ] }, "last_opt_in_source": { "type": "string", "description": "The interface or process through which the customer opted in. Used when status is accepted .", "enum": [ "api", "bulk_update", "concierge", "customer_portal", "customer_sms", "merchant_portal", "recharge_checkout", "rechargesms_app", "sci_cart", "script", "shopify_checkout", "sms_reminder", "store_opt_in_widget", "subscription_checkout_extension", "thank_you_page" ] }, "last_opt_out_source": { "type": "string", "description": "The interface or process through which the customer opted out. Used when status is declined .", "enum": [ "api", "bulk_update", "concierge", "customer_portal", "customer_sms", "merchant_portal", "recharge_checkout", "rechargesms_app", "sci_cart", "script", "shopify_checkout", "sms_reminder", "store_opt_in_widget", "subscription_checkout_extension", "thank_you_page" ] } }, "description": "The preference for promotional communication on this channel. status is required when this object is passed." }, "replenishment": { "type": "object", "properties": { "status": { "type": "string", "description": "The new status of the notification preference.", "enum": [ "accepted", "declined" ] }, "last_opt_in_source": { "type": "string", "description": "The interface or process through which the customer opted in. Used when status is accepted .", "enum": [ "api", "bulk_update", "concierge", "customer_portal", "customer_sms", "merchant_portal", "recharge_checkout", "rechargesms_app", "sci_cart", "script", "shopify_checkout", "sms_reminder", "store_opt_in_widget", "subscription_checkout_extension", "thank_you_page" ] }, "last_opt_out_source": { "type": "string", "description": "The interface or process through which the customer opted out. Used when status is declined .", "enum": [ "api", "bulk_update", "concierge", "customer_portal", "customer_sms", "merchant_portal", "recharge_checkout", "rechargesms_app", "sci_cart", "script", "shopify_checkout", "sms_reminder", "store_opt_in_widget", "subscription_checkout_extension", "thank_you_page" ] } }, "description": "The preference for replenishment communication on this channel. status is required when this object is passed." } }, "description": "The email notification preferences to update." }, "sms": { "type": "object", "properties": { "transactional": { "type": "object", "properties": { "status": { "type": "string", "description": "The new status of the notification preference.", "enum": [ "accepted", "declined" ] }, "last_opt_in_source": { "type": "string", "description": "The interface or process through which the customer opted in. Used when status is accepted .", "enum": [ "api", "bulk_update", "concierge", "customer_portal", "customer_sms", "merchant_portal", "recharge_checkout", "rechargesms_app", "sci_cart", "script", "shopify_checkout", "sms_reminder", "store_opt_in_widget", "subscription_checkout_extension", "thank_you_page" ] }, "last_opt_out_source": { "type": "string", "description": "The interface or process through which the customer opted out. Used when status is declined .", "enum": [ "api", "bulk_update", "concierge", "customer_portal", "customer_sms", "merchant_portal", "recharge_checkout", "rechargesms_app", "sci_cart", "script", "shopify_checkout", "sms_reminder", "store_opt_in_widget", "subscription_checkout_extension", "thank_you_page" ] } }, "description": "The preference for transactional communication on this channel. status is required when this object is passed." }, "promotional": { "type": "object", "properties": { "status": { "type": "string", "description": "The new status of the notification preference.", "enum": [ "accepted", "declined" ] }, "last_opt_in_source": { "type": "string", "description": "The interface or process through which the customer opted in. Used when status is accepted .", "enum": [ "api", "bulk_update", "concierge", "customer_portal", "customer_sms", "merchant_portal", "recharge_checkout", "rechargesms_app", "sci_cart", "script", "shopify_checkout", "sms_reminder", "store_opt_in_widget", "subscription_checkout_extension", "thank_you_page" ] }, "last_opt_out_source": { "type": "string", "description": "The interface or process through which the customer opted out. Used when status is declined .", "enum": [ "api", "bulk_update", "concierge", "customer_portal", "customer_sms", "merchant_portal", "recharge_checkout", "rechargesms_app", "sci_cart", "script", "shopify_checkout", "sms_reminder", "store_opt_in_widget", "subscription_checkout_extension", "thank_you_page" ] } }, "description": "The preference for promotional communication on this channel. status is required when this object is passed." }, "replenishment": { "type": "object", "properties": { "status": { "type": "string", "description": "The new status of the notification preference.", "enum": [ "accepted", "declined" ] }, "last_opt_in_source": { "type": "string", "description": "The interface or process through which the customer opted in. Used when status is accepted .", "enum": [ "api", "bulk_update", "concierge", "customer_portal", "customer_sms", "merchant_portal", "recharge_checkout", "rechargesms_app", "sci_cart", "script", "shopify_checkout", "sms_reminder", "store_opt_in_widget", "subscription_checkout_extension", "thank_you_page" ] }, "last_opt_out_source": { "type": "string", "description": "The interface or process through which the customer opted out. Used when status is declined .", "enum": [ "api", "bulk_update", "concierge", "customer_portal", "customer_sms", "merchant_portal", "recharge_checkout", "rechargesms_app", "sci_cart", "script", "shopify_checkout", "sms_reminder", "store_opt_in_widget", "subscription_checkout_extension", "thank_you_page" ] } }, "description": "The preference for replenishment communication on this channel. status is required when this object is passed." } }, "description": "The SMS notification preferences to update." }, "email_address": { "type": "string", "description": "The email address the consent applies to. Recorded with the change when email preferences are updated." }, "phone_number": { "type": "string", "description": "The phone number the consent applies to. Recorded with the change when SMS preferences are updated." }, "source_details": { "type": "object", "description": "Additional free-form details about where the consent was collected." }, "attestation_provided": { "type": "boolean", "description": "Whether the customer's consent was attested to when it was collected." } } } } } }, "x-recharge-scopes": [ "write_customers" ] } }, "/customers/{id}/sessions": { "post": { "operationId": "customer_session_create", "summary": "Create a customer session", "description": "Creates a session token for a Customer . Send an empty JSON object as the request body. If a storefront access token is passed in the X-Recharge-Storefront-Access-Token header, the scopes of the session are derived from that token.", "tags": [ "Customer sessions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "OK: The request was successful, created a new resource, and resource created is in the body.", "content": { "application/json": { "example": { "customer_session": { "apiToken": "eyJhbGciOiJIUzI1NiJ9.example.signature", "customerId": 90210001 } } } } } }, "x-recharge-scopes": [ "write_sessions" ] } }, "/customers": { "post": { "operationId": "customers_create", "summary": "Create a customer", "description": "Create a customer in Recharge.", "tags": [ "Customers" ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "customer": { "id": 37657002, "analytics_data": { "utm_params": [ { "utm_source": "facebook", "utm_medium": "cpc" } ] }, "apply_credit_to_next_checkout_charge": false, "backup_payment_methods_enabled": null, "can_add_payment_method": true, "created_at": "2020-02-19T17:40:07+00:00", "email": "fake@example.com", "external_customer_id": { "ecommerce": "2879413682227" }, "first_charge_processed_at": "2020-02-19T17:40:11+00:00", "first_name": "Jane", "has_payment_method_in_dunning": false, "has_valid_payment_method": true, "hash": "7e706455cbd13e40", "last_name": "Doe", "payment_method_fallback_on_failure_disabled": false, "phone": null, "recharge_lifetime_value_total_amount_store_default_currency": null, "subscriptions_active_count": 0, "subscriptions_total_count": 0, "subscription_related_charge_streak": 0, "tax_exempt": false, "total_processed_charge_count": 0, "updated_at": "2020-12-17T18:50:39+00:00" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "analytics_data": { "type": "object", "properties": { "utm_params": { "type": "array", "items": { "type": "object", "properties": { "utm_data_source": { "type": "string", "description": "The source of the campaign parameter. Required for each utm_param object." }, "utm_source": { "type": "string", "description": "The UTM source." }, "utm_medium": { "type": "string", "description": "The UTM medium." }, "utm_campaign": { "type": "string", "description": "The UTM campaign." }, "utm_term": { "type": "string", "description": "The UTM term." }, "utm_content": { "type": "string", "description": "The UTM content." }, "utm_timestamp": { "type": "string", "description": "The UTM timestamp. Required for each utm_param object." } } }, "description": "An array containing utm_param objects." } }, "description": "An object containing analytics data associated with the customer." }, "custom_event_attributes": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "A user-defined key for the custom attribute." }, "value": { "type": "string", "description": "A user-defined value for the custom attribute. Maximum length is 255 characters." } } }, "description": "A 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 ." }, "email": { "type": "string", "description": "The customer’s email address." }, "external_customer_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "The customer ID as it appears in the external e-commerce platform." } }, "description": "An object containing external ids for the customer record." }, "first_name": { "type": "string", "description": "The customer’s first name." }, "last_name": { "type": "string", "description": "The customer’s last name." }, "phone": { "type": "string", "description": "The customer's phone number." }, "tax_exempt": { "type": "boolean", "description": "Whether or not the customer is tax exempt." } }, "required": [ "email", "first_name", "last_name" ] }, "example": { "first_name": "Niels", "last_name": "Bohr", "email": "fake@example.com" } } } }, "x-recharge-scopes": [ "write_customers" ] }, "get": { "operationId": "customers_list", "summary": "List customers", "description": "Return a list of customers in your store. HTTP request examples GET /customers GET /customers?email=example@email.com GET /customers?hash=143806234a9ff87a8d9e GET /customers?limit=250 GET /customers?page=2 GET /customers?external_customer_id=98273498", "tags": [ "Customers" ], "parameters": [ { "name": "email", "in": "query", "required": false, "description": "Returns the user linked to the email address provided.", "schema": { "type": "string" } }, { "name": "created_at_max", "in": "query", "required": false, "description": "Gets all customers created before this date.", "schema": { "type": "string" } }, { "name": "created_at_min", "in": "query", "required": false, "description": "Gets all customers created after this date.", "schema": { "type": "string" } }, { "name": "hash", "in": "query", "required": false, "description": "Returns the user linked to the given recharge customer hash.", "schema": { "type": "string" } }, { "name": "ids", "in": "query", "required": false, "description": "Filter customers by id. If passing multiple values, must be comma separated. Non-integer values will result in a 422 error", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of results.", "schema": { "type": "string", "default": 50 } }, { "name": "page", "in": "query", "required": false, "description": "Page to show.", "schema": { "type": "string", "deprecated": true, "default": 1 } }, { "name": "external_customer_id", "in": "query", "required": false, "description": "Returns the user linked to the given external_customer_id .", "schema": { "type": "string" } }, { "name": "updated_at_max", "in": "query", "required": false, "description": "Gets all customers updated before this date.", "schema": { "type": "string" } }, { "name": "updated_at_min", "in": "query", "required": false, "description": "Gets all customers updated after this date.", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "A comma-separated list of related resources to embed in the include attribute of each Customer .", "schema": { "type": "string", "enum": [ "addresses", "announcements", "gift_purchases", "memberships", "metafields", "payment_methods", "punch_card_progress", "referral_info", "subscriptions" ] } }, { "name": "phone", "in": "query", "required": false, "description": "Returns the customer linked to the given phone number. Must be in E.164 format, including the country code.", "schema": { "type": "string" } }, { "name": "sort_by", "in": "query", "required": false, "description": "Sort order of the results. Default is id-desc .", "schema": { "type": "string", "enum": [ "id-asc", "id-desc", "updated_at-asc", "updated_at-desc", "created_at-asc", "created_at-desc" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "The 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "next_cursor": "next_cursor", "previous_cursor": "previous_cursor", "customers": [ { "id": 37657002, "analytics_data": { "utm_params": [ { "utm_source": "facebook", "utm_medium": "cpc" } ] }, "apply_credit_to_next_checkout_charge": false, "backup_payment_methods_enabled": null, "can_add_payment_method": true, "created_at": "2020-02-19T17:40:07+00:00", "email": "fake@example.com", "external_customer_id": { "ecommerce": "2879413682227" }, "first_charge_processed_at": "2020-02-19T17:40:11+00:00", "first_name": "Jane", "has_payment_method_in_dunning": false, "has_valid_payment_method": true, "hash": "7e706455cbd13e40", "last_name": "Doe", "payment_method_fallback_on_failure_disabled": false, "phone": "+16175551212", "recharge_lifetime_value_total_amount_store_default_currency": null, "subscriptions_active_count": 0, "subscriptions_total_count": 1, "tax_exempt": false, "total_processed_charge_count": 0, "updated_at": "2020-12-17T18:50:39+00:00" } ] } } } } }, "x-recharge-scopes": [ "read_customers" ] } }, "/customers/{id}": { "get": { "operationId": "customers_retrieve", "summary": "Retrieve a customer", "description": "Retrieve one customer using customer_id .", "tags": [ "Customers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "A comma-separated list of related resources to embed in the include attribute of each Customer .", "schema": { "type": "string", "enum": [ "addresses", "announcements", "gift_purchases", "memberships", "metafields", "payment_methods", "punch_card_progress", "referral_info", "subscriptions" ] } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "customer": { "id": 37657002, "analytics_data": { "utm_params": [ { "utm_source": "facebook", "utm_medium": "cpc" } ] }, "apply_credit_to_next_checkout_charge": false, "backup_payment_methods_enabled": null, "can_add_payment_method": true, "created_at": "2020-02-19T17:40:07+00:00", "email": "fake@example.com", "external_customer_id": { "ecommerce": "2879413682227" }, "first_charge_processed_at": "2020-02-19T17:40:11+00:00", "first_name": "Jane", "has_payment_method_in_dunning": false, "has_valid_payment_method": true, "hash": "7e706455cbd13e40", "last_name": "Doe", "payment_method_fallback_on_failure_disabled": false, "phone": "+16175551212", "recharge_lifetime_value_total_amount_store_default_currency": null, "subscriptions_active_count": 0, "subscriptions_total_count": 1, "subscription_related_charge_streak": 0, "tax_exempt": false, "total_processed_charge_count": 0, "updated_at": "2020-12-17T18:50:39+00:00" } } } } } }, "x-recharge-scopes": [ "read_customers" ] }, "put": { "operationId": "customers_update", "summary": "Update a customer", "description": "Modify an existing Customer to match the specified parameters.", "tags": [ "Customers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "customer": { "id": 37657002, "analytics_data": { "utm_params": [ { "utm_source": "facebook", "utm_medium": "cpc" } ] }, "apply_credit_to_next_checkout_charge": false, "backup_payment_methods_enabled": null, "can_add_payment_method": true, "created_at": "2020-02-19T17:40:07+00:00", "email": "fake@example.com", "external_customer_id": { "ecommerce": "2879413682227" }, "first_charge_processed_at": "2020-02-19T17:40:11+00:00", "first_name": "Jane", "has_payment_method_in_dunning": false, "has_valid_payment_method": true, "hash": "7e706455cbd13e40", "last_name": "Doe", "payment_method_fallback_on_failure_disabled": false, "phone": "+16175551212", "recharge_lifetime_value_total_amount_store_default_currency": null, "subscriptions_active_count": 0, "subscriptions_total_count": 1, "tax_exempt": false, "total_processed_charge_count": 0, "updated_at": "2020-12-17T18:50:39+00:00" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "analytics_data": { "type": "object", "properties": { "utm_params": { "type": "array", "items": { "type": "object", "properties": { "utm_data_source": { "type": "string", "description": "The source of the campaign parameter. Required for each utm_param object." }, "utm_source": { "type": "string", "description": "The UTM source." }, "utm_medium": { "type": "string", "description": "The UTM medium." }, "utm_campaign": { "type": "string", "description": "The UTM campaign." }, "utm_term": { "type": "string", "description": "The UTM term." }, "utm_content": { "type": "string", "description": "The UTM content." }, "utm_timestamp": { "type": "string", "description": "The UTM timestamp. Required for each utm_param object." } } }, "description": "An array containing utm_param objects." } }, "description": "An object containing analytics data associated with the customer. UTM parameters passed in the request are added to the customer's existing utm_params ." }, "apply_credit_to_next_checkout_charge": { "type": "boolean", "description": "A boolean that indicates whether Recharge credits will be applied to the next checkout charge. Cannot be changed when the store's credit settings always or never apply credits to checkout charges." }, "apply_credit_to_next_recurring_charge": { "type": "boolean", "description": "A boolean that indicates whether Recharge credits will be applied to the next recurring charge." }, "apply_credit_to_next_recurring_charge_channel": { "type": "string", "description": "The channel recorded as the origin of the change when apply_credit_to_next_recurring_charge is set to true . Default is api .", "enum": [ "merchant_portal", "customer_portal", "checkout", "cancellation_prevention", "winbacks", "api" ] }, "backup_payment_methods_enabled": { "type": "boolean", "description": "A boolean that indicates whether backup payment methods can be used for the customer when a charge fails." }, "custom_event_attributes": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "A user-defined key for the custom attribute." }, "value": { "type": "string", "description": "A user-defined value for the custom attribute. Maximum length is 255 characters." } } }, "description": "A 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 ." }, "email": { "type": "string", "description": "Email address of the customer." }, "external_customer_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "The customer ID as it appears in the external e-commerce platform." } }, "description": "An object containing external ids for the customer record." }, "first_name": { "type": "string", "description": "Customer’s first name." }, "last_name": { "type": "string", "description": "Customer’s last name." }, "payment_method_fallback_on_failure_disabled": { "type": "boolean", "description": "A boolean that indicates whether falling back to the customer's default payment method with the payment processor is disabled when a charge on the assigned payment method fails." }, "phone": { "type": "string", "description": "The customer's phone number." }, "tax_exempt": { "type": "boolean", "description": "Whether or not the customer is tax exempt." } } }, "example": { "last_name": "Doe" } } } }, "x-recharge-scopes": [ "write_customers" ] }, "delete": { "operationId": "customers_delete", "summary": "Delete a customer", "description": "Customer deletion will automatically cancel and delete all child Address, Subscription, Onetime, etc. resources of that customer to eliminate orphaned child data. To delete a certain address without deleting the customer you can use the Delete Address endpoint.", "tags": [ "Customers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Content Deleted: The server has successfully fulfilled the request and deleted the desired object and there is no content to send in the response body.", "content": { "application/json": { "example": {} } } } }, "x-recharge-scopes": [ "write_customers" ] } }, "/customers/{id}/delivery_schedule": { "get": { "operationId": "customer_delivery_schedule", "summary": "Retrieve a customer delivery schedule", "description": "Returns the list of projected deliveries in a specific interval.", "tags": [ "Customers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "delivery_count_future", "in": "query", "required": false, "description": "The count of delivery objects that should be included that reference projected orders.", "schema": { "type": "integer" } }, { "name": "future_interval", "in": "query", "required": false, "description": "The count of days forward to report deliveries on.", "schema": { "type": "integer" } }, { "name": "date_max", "in": "query", "required": false, "description": "The end date of the requested delivery schedule.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "deliverySchedule": { "customer": { "id": 73720164, "email": "test@example.com", "first_name": "Aria", "last_name": "Beciu" }, "deliveries": [ { "date": "2022-02-07", "orders": [ { "id": null, "address_id": 79342717, "charge_id": 507503288, "line_items": [ { "subscription_id": 186930285, "external_product_id": { "ecommerce": "1642443555555" }, "external_variant_id": { "ecommerce": null }, "images": {}, "is_skippable": true, "is_skipped": false, "is_prepaid": false, "original_price": "17.00", "plan_type": "subscription", "product_title": "Organic coffee beans", "properties": [ { "name": "shipping_interval_unit_type", "value": "month" }, { "name": "shipping_interval_frequency", "value": "1" }, { "name": "subscription_id", "value": null } ], "quantity": 1, "subtotal_price": "17.00", "unit_price": "17.00", "variant_title": "Refill large" } ], "order_subtotal": "17.00", "payment_method": { "id": 769874, "billing_address": { "address1": "90 avenue du Rouergue", "address2": null, "city": "Rodez", "company": null, "country_code": "FR", "first_name": "Diane", "last_name": "Farley", "phone": null, "province": null, "zip": "12000" }, "payment_details": {} }, "shipping_address": { "address1": "149 Forest Avenue", "address2": null, "city": "New York City", "company": null, "country_code": "US", "first_name": "Aria", "last_name": "Beciu", "phone": "1234567890", "province": "New York", "zip": "10019" } } ] } ] } } } } } }, "x-recharge-scopes": [ "read_customers" ] } }, "/customers/{id}/credit_summary": { "get": { "operationId": "customer_credit_summary", "summary": "Retrieve a customer's credit summary", "description": "Returns a credit summary for the customer.", "tags": [ "Customers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "If credit_details is passed, the response includes the individual credit accounts of the customer in include.credit_details .", "schema": { "type": "string", "enum": [ "credit_details" ] } }, { "name": "presentment_currency_code", "in": "query", "required": false, "description": "A 3-letter currency code. When passed, the response also includes the balances converted to this currency.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "credit_summary": { "customer_id": 37657002, "total_available_balance": "0.00", "currency_code": "USD" } } } } } }, "x-recharge-scopes": [ "read_credit_summary" ] } }, "/discounts": { "post": { "operationId": "discounts_create", "summary": "Create a discount", "description": "Create a new discount.", "tags": [ "Discounts" ], "responses": { "201": { "description": "successful response", "content": { "application/json": { "example": { "discount": { "id": 59568555, "application_method": "code", "applies_to": { "ids": [], "purchase_item_type": "ALL", "resource": null }, "applies_to_existing_addresses": true, "channel_settings": { "api": { "can_apply": true }, "checkout_page": { "can_apply": true }, "customer_portal": { "can_apply": true }, "merchant_portal": { "can_apply": true } }, "code": "Discount1", "created_at": "2021-07-26T19:16:17+00:00", "customer_segments": [], "ends_at": null, "external_discount_id": { "ecommerce": null }, "external_discount_source": null, "prerequisite_subtotal_min": null, "starts_at": null, "status": "enabled", "title": null, "updated_at": "2021-07-26T19:16:17+00:00", "usage_limits": { "first_time_customer_restriction": false, "max_subsequent_redemptions": null, "one_application_per_customer": false, "automatic_redemptions_per_customer": null }, "value": "100.00", "value_type": "percentage" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "applies_to": { "type": "object", "properties": { "ids": { "type": "array", "items": {}, "description": "A list of ids of the type indicated in applies_to.resource for which the discount can be applied. Currently only supports a list with one value." }, "purchase_item_type": { "type": "string", "description": "An indicator of whether the discount applies to onetimes, subscriptions, or all purchase item types.", "enum": [ "ALL", "ONETIME", "SUBSCRIPTION" ] }, "resource": { "type": "string", "description": "An indicator of the type of resource to which applies_to_id refers.", "enum": [ "shopify_product", "shopify_collection_id", "collection_id" ] } }, "description": "An object encompassing data that limits discount application on the basis of an associated record (such as customer, products, etc.)" }, "channel_settings": { "type": "object", "properties": { "api": { "type": "object", "properties": { "can_apply": { "type": "boolean", "description": "A boolean to indicate if the discount may be applied using the associated channel (defaults to true for all channels).", "default": true } }, "description": "An object containing api channel settings." }, "customer_portal": { "type": "object", "properties": { "can_apply": { "type": "boolean", "description": "A boolean to indicate if the discount may be applied using the associated channel (defaults to true for all channels).", "default": true } }, "description": "An object containing customer portal channel settings." }, "merchant_portal": { "type": "object", "properties": { "can_apply": { "type": "boolean", "description": "A boolean to indicate if the discount may be applied using the associated channel (defaults to true for all channels).", "default": true } }, "description": "An object containing merchant portal channel settings." }, "checkout_page": { "type": "object", "properties": { "can_apply": { "type": "boolean", "description": "A boolean to indicate if the discount may be applied using the associated channel (defaults to true for all channels).", "default": true } }, "description": "An object containing checkout channel settings." } }, "description": "A list of channel objects containing information regarding discount behaviors for each. * can_apply: a boolean to indicate if the discount may be applied using the associated channel (defaults to true for all channels)." }, "code": { "type": "string", "description": "The code used to apply the discount." }, "ends_at": { "type": "string", "format": "date-time", "description": "The expiration timestamp of the discount. Past this time the Discount can no longer be redeemed. After ends_at the status of the Discount will go from active to disabled ." }, "external_discount_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "The discount id as it appears in the external e-commerce platform. Maximum 188 characters." } }, "description": "An object containing external ids of the discount." }, "external_discount_source": { "type": "string", "description": "The external platform that the external_discount_id belongs to. The combination of external_discount_source and external_discount_id must be unique.", "enum": [ "big_commerce", "shopify", "recharge", "headless", "magento" ] }, "prerequisite_subtotal_min": { "type": "string", "description": "The minimum cart subtotal needed for the discount to be applicable." }, "starts_at": { "type": "string", "format": "date-time", "description": "The date when the discount becomes ACTIVE ." }, "status": { "type": "string", "description": "The status of the discount.", "enum": [ "enabled", "disabled" ] }, "title": { "type": "string", "description": "The title of the discount. Maximum 255 characters." }, "usage_limits": { "type": "object", "properties": { "one_application_per_customer": { "type": "boolean", "description": "The discount can only be used once for a given customer checkout or manually applied once on the customer portal (irrespective of which address). Once applied, it will continue being re-applied to each new charge on the address." }, "first_time_customer_restriction": { "type": "boolean", "description": "Discount can be used on checkout for customer that still don’t exist in Recharge database." }, "max_subsequent_redemptions": { "type": "integer", "description": "The number of Charges the Discount will apply to besides the initial redemption for a given Customer . For example, if you want a discount to apply for 5 consecutive charges max_subsequent_redemptions should be 4." }, "redemptions": { "type": "integer", "description": "Sets the limit on the number of times a discount can be used by all customers. Only accepted for stores that have legacy discount usage limits enabled; otherwise the value is ignored." }, "automatic_redemptions_per_customer": { "type": "integer", "description": "The 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." } }, "description": "Sets the limit on the number of times a discount can be used by all customers." }, "value": { "type": "string", "description": "The discounted value to be applied." }, "value_type": { "type": "string", "description": "The discount type.", "enum": [ "fixed_amount", "percentage", "shipping" ] } }, "required": [ "code", "value", "value_type" ] }, "example": { "applies_to": { "purchase_item_type": "ALL" }, "channel_settings": { "api": { "can_apply": true }, "checkout_page": { "can_apply": true }, "customer_portal": { "can_apply": true }, "merchant_portal": { "can_apply": true } }, "code": "Discount1", "status": "enabled", "usage_limits": { "first_time_customer_restriction": false, "one_application_per_customer": false }, "value": "100.00", "value_type": "percentage" } } } }, "x-recharge-scopes": [ "write_discounts" ] }, "get": { "operationId": "discounts_list", "summary": "List discounts", "description": "Return a list of discounts in your store. HTTP request examples GET /discounts GET /discounts?created_at_max=2017-10-01 GET /discounts?created_at_max=2017-10-01 GET /discounts?created_at_min=2017-10-01 GET /discounts?discount_code=Discount GET /discounts?discount_type=percentage GET /discounts?updated_at_min=2017-10-01", "tags": [ "Discounts" ], "parameters": [ { "name": "application_method", "in": "query", "required": false, "description": "Filter discounts by how they are applied.", "schema": { "type": "string", "enum": [ "code", "automatic" ] } }, { "name": "created_at_max", "in": "query", "required": false, "description": "Get all discounts created before a specified date.", "schema": { "type": "string" } }, { "name": "created_at_min", "in": "query", "required": false, "description": "Get all discounts created after a specified date.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Return 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 .", "schema": { "type": "string" } }, { "name": "discount_code", "in": "query", "required": false, "description": "Search for a particular discount code.", "schema": { "type": "string" } }, { "name": "discount_title", "in": "query", "required": false, "description": "Search for a particular discount title. Combine with wildcard_search to match titles that start with the given value.", "schema": { "type": "string" } }, { "name": "discount_type", "in": "query", "required": false, "description": "Filter based on type of discount.", "schema": { "type": "string", "enum": [ "percentage", "fixed_amount", "shipping" ] } }, { "name": "sort_by", "in": "query", "required": false, "description": "Sort 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 .", "schema": { "type": "string", "enum": [ "id-asc", "id-desc", "created_at-asc", "created_at-desc", "updated_at-asc", "updated_at-desc" ] } }, { "name": "ids", "in": "query", "required": false, "description": "Filter discounts by id. If passing multiple values, must be comma separated. Non-integer values will result in a 422 error", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of results to return.", "schema": { "type": "string", "default": 50 } }, { "name": "page", "in": "query", "required": false, "description": "Page to show.", "schema": { "type": "string", "deprecated": true, "default": 1 } }, { "name": "status", "in": "query", "required": false, "description": "Returns all discounts with status enabled , disabled or fully_disabled .", "schema": { "type": "string", "enum": [ "enabled", "disabled", "fully_disabled" ] } }, { "name": "updated_at_max", "in": "query", "required": false, "description": "Get all discounts updated before a specified date.", "schema": { "type": "string" } }, { "name": "updated_at_min", "in": "query", "required": false, "description": "Get all discounts updated after a specified date.", "schema": { "type": "string" } }, { "name": "wildcard_search", "in": "query", "required": false, "description": "If true , discount_code returns all discounts whose code starts with the given value instead of requiring an exact match.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "next_cursor": null, "previous_cursor": null, "discounts": [ { "id": 59568555, "application_method": "code", "applies_to": { "ids": [], "purchase_item_type": "ALL", "resource": null }, "applies_to_existing_addresses": true, "channel_settings": { "api": { "can_apply": true }, "checkout_page": { "can_apply": true }, "customer_portal": { "can_apply": true }, "merchant_portal": { "can_apply": true } }, "code": "Discount1", "created_at": "2021-07-26T19:16:17+00:00", "customer_segments": [], "ends_at": null, "external_discount_id": { "ecommerce": null }, "external_discount_source": null, "prerequisite_subtotal_min": null, "starts_at": null, "status": "enabled", "title": null, "updated_at": "2021-07-26T19:16:17+00:00", "usage_limits": { "first_time_customer_restriction": false, "max_subsequent_redemptions": null, "one_application_per_customer": false, "automatic_redemptions_per_customer": null }, "value": "100.00", "value_type": "percentage" } ] } } } } }, "x-recharge-scopes": [ "read_discounts" ] } }, "/discounts/{id}": { "get": { "operationId": "discounts_retrieve", "summary": "Retrieve a discount", "description": "Retrieve a single Recharge Discount", "tags": [ "Discounts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "discount": { "id": 59568555, "application_method": "code", "applies_to": { "ids": [], "purchase_item_type": "ALL", "resource": null }, "applies_to_existing_addresses": true, "channel_settings": { "api": { "can_apply": true }, "checkout_page": { "can_apply": true }, "customer_portal": { "can_apply": true }, "merchant_portal": { "can_apply": true } }, "code": "Discount1", "created_at": "2021-07-26T19:16:17+00:00", "customer_segments": [], "ends_at": null, "external_discount_id": { "ecommerce": null }, "external_discount_source": null, "prerequisite_subtotal_min": null, "starts_at": null, "status": "enabled", "title": null, "updated_at": "2021-07-26T19:16:17+00:00", "usage_limits": { "first_time_customer_restriction": false, "max_subsequent_redemptions": null, "one_application_per_customer": false, "automatic_redemptions_per_customer": null }, "value": "100.00", "value_type": "percentage" } } } } } }, "x-recharge-scopes": [ "read_discounts" ] }, "put": { "operationId": "discounts_update", "summary": "Update a discount", "description": "You can modify an existing discount to match the specified parameters.", "tags": [ "Discounts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "discount": { "id": 59568555, "application_method": "code", "applies_to": { "ids": [], "purchase_item_type": "ALL", "resource": null }, "applies_to_existing_addresses": true, "channel_settings": { "api": { "can_apply": true }, "checkout_page": { "can_apply": true }, "customer_portal": { "can_apply": true }, "merchant_portal": { "can_apply": true } }, "code": "Discount1", "created_at": "2021-07-26T19:16:17+00:00", "customer_segments": [], "ends_at": null, "external_discount_id": { "ecommerce": null }, "external_discount_source": null, "prerequisite_subtotal_min": null, "starts_at": null, "status": "enabled", "title": null, "updated_at": "2021-07-26T19:16:17+00:00", "usage_limits": { "first_time_customer_restriction": false, "max_subsequent_redemptions": null, "one_application_per_customer": false, "automatic_redemptions_per_customer": null }, "value": "100.00", "value_type": "percentage" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "applies_to": { "type": "object", "properties": { "ids": { "type": "array", "items": {}, "description": "A list of ids of the type indicated in applies_to.resource for which the discount can be applied. Currently only supports a list with one value." }, "purchase_item_type": { "type": "string", "description": "An indicator of whether the discount applies to onetimes, subscriptions, or all purchase item types.", "enum": [ "ALL", "ONETIME", "SUBSCRIPTION" ] }, "resource": { "type": "string", "description": "An indicator of the type of resource to which applies_to_id refers.", "enum": [ "shopify_product", "shopify_collection_id", "collection_id" ] } }, "description": "An object encompassing data that limits discount application on the basis of an associated record (such as customer, products, etc.)" }, "channel_settings": { "type": "object", "properties": { "api": { "type": "object", "properties": { "can_apply": { "type": "boolean", "description": "A boolean to indicate if the discount may be applied using the associated channel (defaults to true for all channels).", "default": true } }, "description": "An object containing api channel settings." }, "customer_portal": { "type": "object", "properties": { "can_apply": { "type": "boolean", "description": "A boolean to indicate if the discount may be applied using the associated channel (defaults to true for all channels).", "default": true } }, "description": "An object containing customer portal channel settings." }, "merchant_portal": { "type": "object", "properties": { "can_apply": { "type": "boolean", "description": "A boolean to indicate if the discount may be applied using the associated channel (defaults to true for all channels).", "default": true } }, "description": "An object containing merchant portal channel settings." }, "checkout_page": { "type": "object", "properties": { "can_apply": { "type": "boolean", "description": "A boolean to indicate if the discount may be applied using the associated channel (defaults to true for all channels).", "default": true } }, "description": "An object containing checkout channel settings." } }, "description": "A list of channel objects containing information regarding discount behaviors for each. * can_apply: a boolean to indicate if the discount may be applied using the associated channel (defaults to true for all channels)." }, "code": { "type": "string", "description": "The code used to apply the discount.." }, "commit": { "type": "boolean", "description": "Only 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." }, "ends_at": { "type": "string", "format": "date-time", "description": "The expiration timestamp of the discount. Past this time the Discount can no longer be redeemed. After ends_at the status of the Discount will go from active to disabled ." }, "external_discount_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "The discount id as it appears in the external e-commerce platform. Maximum 188 characters." } }, "description": "An object containing external ids of the discount." }, "external_discount_source": { "type": "string", "description": "The external platform that the external_discount_id belongs to. The combination of external_discount_source and external_discount_id must be unique.", "enum": [ "big_commerce", "shopify", "recharge", "headless", "magento" ] }, "prerequisite_subtotal_min": { "type": "string", "description": "The minimum cart subtotal needed for the discount to be applicable." }, "starts_at": { "type": "string", "format": "date-time", "description": "The date when the discount becomes active." }, "status": { "type": "string", "description": "The status of the discount. Value can be: * enabled discount is active to be applied * disabled discount can’t be applied on new purchases. Discount will remain on existing charges to which it has already been applied. * fully_disabled discount can no longer be applied. In addition, Discount is removed from every queued charge.", "enum": [ "enabled", "disabled", "fully_disabled" ] }, "usage_limits": { "type": "object", "properties": { "one_application_per_customer": { "type": "boolean", "description": "The discount can only be used once for a given customer checkout or manually applied once on the customer portal (irrespective of which address). Once applied, it will continue being re-applied to each new charge on the address." }, "first_time_customer_restriction": { "type": "boolean", "description": "Discount can be used on checkout for customer that still don’t exist in Recharge database." }, "max_subsequent_redemptions": { "type": "integer", "description": "The number of Charges the Discount will apply to besides the initial redemption for a given Customer . For example, if you want a discount to apply for 5 consecutive charges max_subsequent_redemptions should be 4." }, "redemptions": { "type": "integer", "description": "Sets the limit on the number of times a discount can be used by all customers. Only accepted for stores that have legacy discount usage limits enabled; otherwise the value is ignored." }, "automatic_redemptions_per_customer": { "type": "integer", "description": "The 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." } }, "description": "Sets the limit on the number of times a discount can be used by all customers." }, "value": { "type": "string", "description": "The discounted value to be applied." }, "value_type": { "type": "string", "description": "The discount type.", "enum": [ "fixed_amount", "percentage", "shipping" ] } } }, "example": { "usage_limits": {}, "starts_at": "2021-11-01T00:00:00+00:00" } } } }, "x-recharge-scopes": [ "write_discounts" ] }, "delete": { "operationId": "discounts_delete", "summary": "Delete a discount", "description": "Delete a discount For safety reasons, to delete a discount you will need to set its status to fully_disabled .", "tags": [ "Discounts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Content Deleted: The server has successfully fulfilled the request and deleted the desired object and there is no content to send in the response body.", "content": { "application/json": { "example": {} } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "commit": { "type": "boolean", "description": "Controls 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." } } } } } }, "x-recharge-scopes": [ "write_discounts" ] } }, "/customer_entitlements": { "get": { "operationId": "list_customer_entitlements", "summary": "List customer entitlements", "description": "Retrieve all entitlements for a customer.", "tags": [ "Entitlements" ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Return 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 .", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "required": false, "description": "The ID of the customer to retrieve entitlements for.", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "Optionally include related resources. Use include=entitlement_feature to embed the entitlement feature details (name, id, lookup_key, etc.) in each result.", "schema": { "type": "string", "enum": [ "entitlement_feature" ] } }, { "name": "limit", "in": "query", "required": false, "description": "The amount of results. Default is 50 while the maximum is 250.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "The page to show. Cursor pagination is recommended instead.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": [ { "id": 72, "customer_id": 226536730, "entitlement_feature_id": 21, "granted_by_id": "747832689", "granted_by_type": "purchase_item", "expires_at": "2026-02-06T05:59:59+00:00", "created_at": "2026-01-05T15:11:23+00:00", "deleted_at": null, "updated_at": "2026-01-05T15:11:23+00:00" } ] } } } }, "x-recharge-scopes": [ "read_customers" ] }, "post": { "operationId": "create_customer_entitlement", "summary": "Create a customer entitlement", "description": "Create a new entitlement for a customer.", "tags": [ "Entitlements" ], "responses": { "201": { "description": "OK: The request was successful and a new resource was created.", "content": { "application/json": { "example": { "customer_entitlement": { "id": 74, "customer_id": 12345, "entitlement_feature_id": 56789, "granted_by_id": "385088", "granted_by_type": "api", "expires_at": "2026-07-01T04:59:59+00:00", "created_at": "2026-01-07T04:20:40+00:00", "deleted_at": null, "updated_at": "2026-01-07T04:20:40+00:00" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "integer", "description": "The ID of the customer to grant the entitlement to." }, "entitlement_feature_id": { "type": "integer", "description": "The ID of the entitlement feature to grant." }, "expires_at": { "type": "string", "format": "date-time", "description": "The date and time at which the entitlement expires. If null or omitted, the entitlement does not expire." } }, "required": [ "customer_id", "entitlement_feature_id", "expires_at" ] }, "example": { "customer_id": 12345, "entitlement_feature_id": 56789, "expires_at": "2026-06-30T00:00:00+00:00" } } } }, "x-recharge-scopes": [ "write_customer_entitlements" ] } }, "/customer_entitlements/{id}": { "put": { "operationId": "update_customer_entitlement", "summary": "Update a customer entitlement", "description": "Update the expiration date of a customer's entitlement.", "tags": [ "Entitlements" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "customer_entitlement": { "id": 74, "customer_id": 210979738, "entitlement_feature_id": 21, "granted_by_id": "385088", "granted_by_type": "api", "expires_at": "2026-12-31T04:59:59+00:00", "created_at": "2026-01-07T04:20:40+00:00", "deleted_at": null, "updated_at": "2026-01-07T04:31:14+00:00" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "expires_at": { "type": "string", "format": "date-time", "description": "The updated date and time at which the entitlement expires. Set to null to make the entitlement non-expiring." } }, "required": [ "expires_at" ] }, "example": { "expires_at": "2026-12-31T00:00:00+00:00" } } } }, "x-recharge-scopes": [ "write_customer_entitlements" ] }, "delete": { "operationId": "delete_customer_entitlement", "summary": "Delete a customer entitlement", "description": "Delete a customer's entitlement.", "tags": [ "Entitlements" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content: The request was successful and the resource was deleted.", "content": { "application/json": { "example": {} } } } }, "x-recharge-scopes": [ "write_customer_entitlements" ] } }, "/gift_purchases": { "get": { "operationId": "gift_purchases_list", "summary": "List gift purchases", "description": "Returns a list of the store's Gift purchases , sorted by id in descending order. Cancelled gift purchases are not returned.", "tags": [ "Gift purchases" ], "parameters": [ { "name": "recipient_customer_id", "in": "query", "required": false, "description": "Return the gift purchases received by the given Customer .", "schema": { "type": "integer" } }, { "name": "sender_customer_id", "in": "query", "required": false, "description": "Return the gift purchases bought by the given Customer .", "schema": { "type": "integer" } }, { "name": "credit_account_id", "in": "query", "required": false, "description": "Return the gift purchase funded by the given Credit account .", "schema": { "type": "integer" } }, { "name": "shopify_order_id", "in": "query", "required": false, "description": "Return the gift purchases bought in the order with the given ID in the external e-commerce platform.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "The amount of results. Default is 50 while the maximum is 250.", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "The page of results to show. Default is 1. Use cursor instead where possible.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor or previous_cursor value returned by a previous list request. When a cursor is passed, only limit can be passed with it.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "gift_purchases": [ { "id": 2204, "credit_account_id": 30877, "recipient_customer_id": 71990, "redeemable_collection_id": null, "sender_customer_id": 71542, "amount": "60.00", "created_at": "2026-11-02T16:40:12+00:00", "external_gift_product_id": { "ecommerce": "7003555" }, "external_gift_variant_id": { "ecommerce": "41201544" }, "external_order_id": { "ecommerce": "5120099334" }, "external_redeemable_product_ids": [ { "ecommerce": "7003112" } ], "gift_currency": "USD", "gift_note": "Happy birthday! Enjoy three months of coffee.", "notification_scheduled_at": "2026-11-20T14:00:00+00:00", "notification_sent_at": null, "redeemed_at": null, "redemption_link": "https://example-store.example.com/gifts/redeem/2204", "sender_name": "Jordan Example", "updated_at": "2026-11-02T16:40:12+00:00" } ], "next_cursor": null, "previous_cursor": null } } } } }, "x-recharge-scopes": [ "read_gift_purchases" ] } }, "/gift_purchases/{id}": { "get": { "operationId": "gift_purchases_retrieve", "summary": "Retrieve a gift purchase", "description": "Returns a single Gift purchase by its id .", "tags": [ "Gift purchases" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "gift_purchase": { "id": 2204, "credit_account_id": 30877, "recipient_customer_id": 71990, "redeemable_collection_id": null, "sender_customer_id": 71542, "amount": "60.00", "created_at": "2026-11-02T16:40:12+00:00", "external_gift_product_id": { "ecommerce": "7003555" }, "external_gift_variant_id": { "ecommerce": "41201544" }, "external_order_id": { "ecommerce": "5120099334" }, "external_redeemable_product_ids": [ { "ecommerce": "7003112" } ], "gift_currency": "USD", "gift_note": "Happy birthday! Enjoy three months of coffee.", "notification_scheduled_at": "2026-11-20T14:00:00+00:00", "notification_sent_at": null, "redeemed_at": null, "redemption_link": "https://example-store.example.com/gifts/redeem/2204", "sender_name": "Jordan Example", "updated_at": "2026-11-02T16:40:12+00:00" } } } } } }, "x-recharge-scopes": [ "read_gift_purchases" ] }, "delete": { "operationId": "gift_purchases_delete", "summary": "Cancel a gift purchase", "description": "Cancels a Gift purchase that has not been redeemed yet. The remaining balance of the gift's Credit account is removed and any gift notification that has not been sent yet is cancelled. A Gift purchase that has already been redeemed cannot be cancelled.", "tags": [ "Gift purchases" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content: The request was successful and there is no content to return." } }, "x-recharge-scopes": [ "write_gift_purchases" ] } }, "/metafields": { "post": { "operationId": "metafields_create", "summary": "Create a metafield", "description": "Creates a metafield for a specific object.", "tags": [ "Metafields" ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "metafield": { "id": 33, "created_at": "2018-11-07T14:00:10", "description": "customer_phone_number", "key": "phone_number", "namespace": "personal_info", "owner_id": 18301938, "owner_resource": "customer", "updated_at": "2018-11-07T14:00:10", "value": "3103103101", "value_type": "integer" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "description": "Description of the metafield." }, "key": { "type": "string", "description": "The name of the metafield." }, "namespace": { "type": "string", "description": "A category or container that differentiates your metadata from other metafields." }, "owner_id": { "type": "integer", "description": "Unique numeric identifier of the owner resource." }, "owner_resource": { "type": "string", "description": "The owner of the resource.", "enum": [ "address", "store", "customer", "subscription", "order", "charge" ] }, "value": { "type": "string", "description": "The content of the metafield." }, "value_type": { "type": "string", "description": "The type of the value parameter.", "enum": [ "string", "integer", "json_string" ] } }, "required": [ "key", "namespace", "owner_id", "owner_resource", "value", "value_type" ] }, "example": { "metafield": { "description": "customer_phone_number", "key": "phone_number", "namespace": "personal_info", "owner_resource": "customer", "owner_id": 18301938, "value_type": "integer", "value": "3103103101" } } } } }, "x-recharge-scopes": [ "write_customers", "write_subscriptions", "write_orders", "write_stores" ] }, "get": { "operationId": "metafields_list", "summary": "List metafields", "description": "Retrieves a list of metafields. HTTP request examples GET /metafields?owner_resource= GET /metafields?owner_resource=subscription&owner_id= GET /metafields?owner_resource=customer&owner_id= GET /metafields?owner_resource=store&owner_id= When getting metafields, you must specify owner_resource in the URL. It can be address , store , customer , subscription , order , charge You can list metafields that are created for all subscription objects using: GET /metafields?owner_resource=subscription - owner_id in the response will be the ID of the subscription.", "tags": [ "Metafields" ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Return 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 .", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Amount of results. (default:50) (maximum: 250).", "schema": { "type": "string", "default": 50 } }, { "name": "namespace", "in": "query", "required": false, "description": "A category or container that differentiates your metadata from other metafields.", "schema": { "type": "string" } }, { "name": "owner_id", "in": "query", "required": false, "description": "Unique numeric identifier of the owner resource.", "schema": { "type": "integer" } }, { "name": "owner_resource", "in": "query", "required": false, "description": "The owner of the resource can be one of the following values: address , store , customer , subscription , order , charge . There may be more objects added in the future.", "schema": { "type": "string", "enum": [ "address", "store", "customer", "subscription", "order", "charge" ] } }, { "name": "page", "in": "query", "required": false, "description": "Page to show.", "schema": { "type": "string", "deprecated": true, "default": 1 } }, { "name": "sort_by", "in": "query", "required": false, "description": "Sort listed Metafields in a specific order. Available sort options: id-asc , id-desc , updated_at-asc , updated_at-desc . Defaults to updated_at-desc .", "schema": { "type": "string", "enum": [ "id-asc", "id-desc", "updated_at-asc", "updated_at-desc" ] } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "next_cursor": "next_cursor", "previous_cursor": "previous_cursor", "metafields": [ { "id": 33, "created_at": "2018-11-07T14:00:10", "description": "customer_phone_number", "key": "phone_number", "namespace": "personal_info", "owner_id": 18301938, "owner_resource": "customer", "updated_at": "2018-11-07T14:00:10", "value": "3103103101", "value_type": "integer" }, { "id": 15, "created_at": "2018-11-05T12:59:30", "description": "desc lorem ipsum", "key": "marjan", "namespace": "nmsp2c", "owner_id": 17868054, "owner_resource": "customer", "updated_at": "2018-11-05T15:48:42", "value": "5", "value_type": "integer" }, { "id": 9, "created_at": "2018-11-05T12:47:27", "description": "desc lorem ipsum", "key": "marjan", "namespace": "nmspc", "owner_id": 17868054, "owner_resource": "customer", "updated_at": "2018-11-05T12:47:27", "value": "5", "value_type": "integer" } ] } } } } }, "x-recharge-scopes": [ "read_customers", "read_subscriptions", "read_orders", "store_info" ] } }, "/metafields/{id}": { "get": { "operationId": "metafields_retrieve", "summary": "Retrieve a metafield", "description": "Retrieves a single metafield based on a specified id. HTTP request examples GET /metafields/ In addition to that, you can retrieve them by subscription_id by using: GET /metafields?owner_resource=subscription&owner_id=", "tags": [ "Metafields" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "metafield": { "id": 33, "created_at": "2018-11-07T14:00:10", "description": "customer_phone_number", "key": "phone_number", "namespace": "personal_info", "owner_id": 18301938, "owner_resource": "customer", "updated_at": "2018-11-07T14:00:10", "value": "3103103101", "value_type": "integer" } } } } } }, "x-recharge-scopes": [ "read_customers", "read_subscriptions", "read_orders", "store_info" ] }, "put": { "operationId": "metafields_update", "summary": "Update a metafield", "description": "Updates a metafield based on a specified owner_resource .", "tags": [ "Metafields" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "OK: The request was successful, created a new resource, and resource created is in the body.", "content": { "application/json": { "example": { "metafield": { "id": 33, "created_at": "2018-11-07T14:00:10", "description": "customer_phone_number", "key": "phone_number", "namespace": "personal_info", "owner_id": 18301938, "owner_resource": "customer", "updated_at": "2018-11-07T14:00:10", "value": "3103103101", "value_type": "integer" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "description": "Description of the metafield." }, "owner_id": { "type": "integer", "description": "Unique numeric identifier of the resource." }, "owner_resource": { "type": "string", "description": "The owner of the resource can be one of the following values: address , store , customer , subscription , order , charge . There may be more objects added in the future.", "enum": [ "address", "store", "customer", "subscription", "order", "charge" ] }, "value": { "type": "string", "description": "The content of the metafield." }, "value_type": { "type": "string", "description": "The type of the value parameter.", "enum": [ "string", "integer", "json_string" ] } } }, "example": { "metafield": { "description": "phone_number_of_customer", "owner_id": 18293088, "owner_resource": "customer", "value": "0333103133", "value_type": "integer" } } } } }, "x-recharge-scopes": [ "write_customers", "write_subscriptions", "write_orders", "write_stores" ] }, "delete": { "operationId": "metafields_delete", "summary": "Delete a metafield", "description": "Delete a metafield based on a specified id.", "tags": [ "Metafields" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Content Deleted: The server has successfully fulfilled the request and deleted the desired object and there is no content to send in the response body.", "content": { "application/json": { "example": {} } } } }, "x-recharge-scopes": [ "write_customers", "write_subscriptions", "write_orders", "write_stores" ] } }, "/customers/{id}/notifications": { "post": { "operationId": "notifications_send", "summary": "Send email notification", "description": "Sends a notification email to the customer with the customer_id indicated in the route. To view the upcoming charge email template, visit the Notifications section in your Recharge Merchant Admin Portal.", "tags": [ "Notifications" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": {} } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "Identifies the type of the notifications. Value can be email only.", "enum": [ "email", "sms" ] }, "template_type": { "type": "string", "description": "Identifies the type of the email notifications.", "enum": [ "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" ] }, "template_vars": { "type": "object", "properties": { "template_vars.address_id": { "type": "integer", "description": "If needed by the template_type , the address_id associated with the indicated Customer , and the object of the Notification ." }, "template_vars.charge_id": { "type": "boolean", "description": "If needed by the template_type , the charge_id of the Charge for which the notification should be sent." }, "payment_method_id": { "type": "integer", "description": "The 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." }, "include_deleted": { "type": "boolean", "description": "Whether a deleted PaymentMethod may be referenced by payment_method_id . Defaults to false . Used by the shopify_update_payment_information template type." }, "apply_to_all_subscription_addresses": { "type": "boolean", "description": "Whether 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." }, "should_update_all_subs": { "type": "boolean", "description": "Deprecated. Use apply_to_all_subscription_addresses instead." }, "order_id": { "type": "integer", "description": "The order_id of an Order on the given address. Optional; used by the subscription_activation template type." }, "membership_id": { "type": "integer", "description": "The 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." }, "line_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique numeric identifier of the line item." }, "product_id": { "type": "integer", "description": "Identifier of the product of the line item." }, "variant_id": { "type": "integer", "description": "Identifier of the product variant of the line item." }, "quantity": { "type": "integer", "description": "Quantity of the line item." }, "order_id": { "type": "integer", "description": "Identifier of the order the line item was purchased in." } } }, "description": "The line items to feature in the notification. Required (at least one item) by the repurchase_reminder and repurchase_welcome template types." }, "notification": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique numeric identifier of the repurchase notification." }, "token": { "type": "string", "description": "Token of the repurchase notification, used to build the unsubscribe link." } }, "description": "The repurchase notification the email is sent for. Required by the repurchase_reminder and repurchase_welcome template types." } }, "description": "An object containing the necessary template variables for this email template type." } }, "required": [ "type", "template_type" ] }, "example": { "type": "email", "template_type": "upcoming_charge", "template_vars": { "address_id": 1234567890, "charge_id": 9876543210 } } } } }, "x-recharge-scopes": [ "write_notifications" ] } }, "/onetimes": { "post": { "operationId": "onetimes_create", "summary": "Create a onetime", "description": "Create a new Onetime .", "tags": [ "Onetimes" ], "responses": { "201": { "description": "OK: The request was successful, created a new resource, and resource created is in the body.", "content": { "application/json": { "example": { "onetime": { "id": 156155818, "address_id": 45154492, "customer_id": 40565990, "created_at": "2021-05-24T19:14:25+00:00", "external_product_id": { "ecommerce": "4950280863846" }, "external_variant_id": { "ecommerce": "32139793137766" }, "is_cancelled": false, "next_charge_scheduled_at": "2021-12-17T05:00:00+00:00", "presentment_currency": "USD", "price": "6.00", "product_title": "ABC Shirt", "properties": [ { "name": "Color", "value": "Red" } ], "quantity": 1, "sku": "TOM0001", "sku_override": false, "updated_at": "2021-05-24T19:30:14+00:00", "variant_title": "Blue star" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "address_id": { "type": "integer", "description": "Unique numeric identifier for the address the one time purchase is associated with." }, "add_to_next_charge": { "type": "boolean", "description": "Instructs to add the Onetime to the next charge scheduled under this Address ." }, "custom_event_attributes": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "The name of the custom attribute." }, "value": { "type": "string", "description": "The value of the custom attribute. Maximum length is 255 characters." } } }, "description": "A 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 ." }, "external_product_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "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 ." } }, "description": "Unique numeric identifier of the product in external platform." }, "external_variant_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "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 ." } }, "description": "Unique numeric identifier of the product variant in external platform." }, "next_charge_scheduled_at": { "type": "string", "format": "date", "description": "This will set the charge date of a new Onetime purchase." }, "plan_id": { "type": "integer", "description": "Unique 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_currency": { "type": "string", "description": "The 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": { "type": "string", "description": "The price of the product." }, "price_manually_set": { "type": "boolean", "description": "Set to true to indicate that the price in the request was explicitly chosen by the caller instead of being calculated by Recharge." }, "product_title": { "type": "string", "description": "The name of the product." }, "properties": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the property." }, "value": { "type": "string", "description": "The value of the property." } } }, "description": "List of properties." }, "quantity": { "type": "integer", "description": "The quantity of the product." }, "sku": { "type": "string", "description": "A unique identifier of the item in the fulfillment." }, "sku_override": { "type": "boolean", "description": "When true , the sku stored on the Onetime is used instead of the SKU of the product variant." }, "variant_title": { "type": "string", "description": "The name of the product variant." } }, "required": [ "address_id", "external_variant_id", "quantity" ] }, "example": { "address_id": 45154492, "next_charge_scheduled_at": "2021-12-17", "price": 6, "product_title": "ABC Shirt", "properties": [ { "name": "Color", "value": "Blue" }, { "name": "Size", "value": "Medium" } ], "quantity": 1, "external_variant_id": { "ecommerce": "3844892483" } } } } }, "x-recharge-scopes": [ "write_subscriptions" ] }, "get": { "operationId": "onetimes_list", "summary": "List onetimes", "description": "Returns a list of all Onetime products from store.", "tags": [ "Onetimes" ], "parameters": [ { "name": "address_id", "in": "query", "required": false, "description": "Return the onetimes linked to the given address_id .", "schema": { "type": "string" } }, { "name": "address_ids", "in": "query", "required": false, "description": "Return the onetimes linked to the given comma-separated list of address_ids .", "schema": { "type": "string" } }, { "name": "created_at_max", "in": "query", "required": false, "description": "Return the onetimes created before the given date.", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at_min", "in": "query", "required": false, "description": "Return the onetimes created after the given date.", "schema": { "type": "string", "format": "date-time" } }, { "name": "customer_id", "in": "query", "required": false, "description": "Return the onetimes linked to the given Recharge customer_id .", "schema": { "type": "string" } }, { "name": "include_cancelled", "in": "query", "required": false, "description": "If true the response will include the cancelled Onetimes as well as the others.", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "description": "The number of results.", "schema": { "type": "string", "default": 50 } }, { "name": "page", "in": "query", "required": false, "description": "The page to show.", "schema": { "type": "string", "deprecated": true, "default": 1 } }, { "name": "external_variant_id", "in": "query", "required": false, "description": "Return the one time purchases linked to the given external platform product variant_id .", "schema": { "type": "string" } }, { "name": "updated_at_max", "in": "query", "required": false, "description": "Return the onetimes updated before the given date.", "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_at_min", "in": "query", "required": false, "description": "Return the onetimes updated after the given date.", "schema": { "type": "string", "format": "date-time" } }, { "name": "ids", "in": "query", "required": false, "description": "Comma-separated list of one time purchase ids to filter.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Return either the next or previous page of onetimes using the next_cursor or previous_cursor attributes in the response.", "schema": { "type": "string" } }, { "name": "external_customer_id", "in": "query", "required": false, "description": "Return the onetimes linked to the customer with the given id in the external e-commerce platform.", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "A 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.", "schema": { "type": "string", "enum": [ "address", "bundle_product", "bundle_selections", "charge_activities", "customer", "customer_entitlements", "metafields" ] } }, { "name": "include_deleted", "in": "query", "required": false, "description": "If true the response will include the deleted Onetimes as well as the others.", "schema": { "type": "boolean" } }, { "name": "sort_by", "in": "query", "required": false, "description": "Sort the results by the given attribute and direction. Defaults to id-desc .", "schema": { "type": "string", "enum": [ "id-asc", "id-desc", "created_at-asc", "created_at-desc", "updated_at-asc", "updated_at-desc" ] } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "next": "next_cursor", "previous": "previous_cursor", "onetimes": [ { "id": 16909886, "address_id": 45154492, "created_at": "2021-05-24T19:14:25+00:00", "customer_id": 40565990, "external_product_id": { "ecommerce": "4950280863846" }, "external_variant_id": { "ecommerce": "32139793137766" }, "is_cancelled": false, "next_charge_scheduled_at": "2021-12-17T05:00:00+00:00", "presentment_currency": "USD", "price": "6.00", "product_title": "ABC Shirt", "properties": [ { "name": "Color", "value": "Blue" } ], "quantity": 1, "sku": "TOM0001", "sku_override": false, "updated_at": "2021-05-24T19:30:14+00:00", "variant_title": "Blue star" } ] } } } } }, "x-recharge-scopes": [ "read_subscriptions" ] } }, "/onetimes/{id}": { "get": { "operationId": "onetimes_retrieve", "summary": "Retrieve a onetime", "description": "Retrieve a Onetime.", "tags": [ "Onetimes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "A 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.", "schema": { "type": "string", "enum": [ "address", "bundle_product", "bundle_selections", "charge_activities", "customer", "customer_entitlements", "metafields" ] } }, { "name": "include_deleted", "in": "query", "required": false, "description": "If true , the Onetime is returned even if it has been deleted.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "onetime": { "id": 16909886, "address_id": 45154492, "created_at": "2021-05-24T19:14:25+00:00", "customer_id": 40565990, "external_product_id": { "ecommerce": "4950280863846" }, "external_variant_id": { "ecommerce": "32139793137766" }, "is_cancelled": false, "next_charge_scheduled_at": "2021-12-17T05:00:00+00:00", "presentment_currency": "USD", "price": "6.00", "product_title": "ABC Shirt", "properties": [ { "name": "Color", "value": "Blue" } ], "quantity": 1, "sku": "TOM0001", "sku_override": false, "updated_at": "2021-05-24T19:30:14+00:00", "variant_title": "Blue star" } } } } } }, "x-recharge-scopes": [ "read_subscriptions" ] }, "put": { "operationId": "onetimes_update", "summary": "Update a onetime", "description": "Update an existing Onetime item.", "tags": [ "Onetimes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "onetime": { "id": 16909886, "address_id": 45154492, "created_at": "2021-05-24T19:14:25+00:00", "customer_id": 40565990, "external_product_id": { "ecommerce": "4950280863846" }, "external_variant_id": { "ecommerce": "32139793137766" }, "is_cancelled": false, "next_charge_scheduled_at": "2021-12-17T05:00:00+00:00", "presentment_currency": "USD", "price": "6.00", "product_title": "ABC Shirt", "properties": [ { "name": "Color", "value": "Blue" } ], "quantity": 1, "sku": "TOM0001", "sku_override": false, "updated_at": "2021-05-24T19:30:14+00:00", "variant_title": "Blue star" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "address_id": { "type": "integer", "description": "Unique numeric identifier for the address the Onetime Purchase is associated with (cannot be used with next_charge_scheduled_at )" }, "custom_event_attributes": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "The name of the custom attribute." }, "value": { "type": "string", "description": "The value of the custom attribute. Maximum length is 255 characters." } } }, "description": "A 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 ." }, "external_product_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "The product id as it appears in the external e-commerce platform." } }, "description": "An object containing the product id as it appears in external platforms." }, "next_charge_scheduled_at": { "type": "string", "format": "date", "description": "This will set the charge date of a new Onetime purchase." }, "presentment_currency": { "type": "string", "description": "The 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": { "type": "string", "description": "The price of the product." }, "price_manually_set": { "type": "boolean", "description": "Set to true to indicate that the price in the request was explicitly chosen by the caller instead of being calculated by Recharge." }, "product_title": { "type": "string", "description": "The name of the product." }, "properties": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the property." }, "value": { "type": "string", "description": "The value of the property." } } }, "description": "List of properties." }, "quantity": { "type": "integer", "description": "The quantity of the product." }, "external_variant_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "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 ." } }, "description": "Unique numeric identifier of the product variant." }, "sku": { "type": "string", "description": "A unique alphanumeric identifier of the item in the fulfillment." }, "sku_override": { "type": "boolean", "description": "When true , the sku stored on the Onetime is used instead of the SKU of the product variant." }, "variant_title": { "type": "string", "description": "The name of the product variant." } } }, "example": { "quantity": 1 } } } }, "x-recharge-scopes": [ "write_subscriptions" ] }, "delete": { "operationId": "onetimes_delete", "summary": "Delete a onetime", "description": "Delete a Onetime .", "tags": [ "Onetimes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Content Deleted: The server has successfully fulfilled the request and deleted the desired object and there is no content to send in the response body.", "content": { "application/json": { "example": {} } } } }, "x-recharge-scopes": [ "write_subscriptions" ] } }, "/orders/{id}": { "get": { "operationId": "orders_retrieve", "summary": "Retrieve an order", "description": "Retrieve one Order using the Recharge order_id .", "tags": [ "Orders" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "A 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 .", "schema": { "type": "string", "enum": [ "address", "customer", "metafields", "order_modifications", "subscriptions" ] } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "order": { "id": 210987092, "address_id": 42171447, "billing_address": { "address1": "601 SW Washing St.", "address2": "", "city": "Portland", "company": "Fake Company Billing", "country_code": "US", "first_name": "Fake Billing First", "last_name": "Fake Billing Last", "phone": "888-888-8888", "province": "Oregon", "zip": "97205" }, "charge": { "id": 272382456, "external_transaction_id": { "payment_processor": "ch_1HzWElJ2zqHvZRd1TWKFFqDR" }, "payment_processor_name": "stripe", "status": "success" }, "client_details": { "browser_ip": "192.168.0.1", "user_agent": "safari webkit" }, "created_at": "2020-12-17T18:50:25+00:00", "currency": "usd", "customer": { "id": 37657002, "email": "test@test.com", "external_customer_id": { "ecommerce": "382028302" }, "hash": "7e706455cbd13e40" }, "discounts": [ { "id": 12345, "code": "TESTCODE10", "value": 10, "value_type": "fixed_amount" } ], "error": null, "external_cart_token": "aeic8101918fs0f8810", "external_order_id": { "ecommerce": "27117383938" }, "external_order_name": { "ecommerce": "#1938" }, "external_order_number": { "ecommerce": "1938" }, "is_prepaid": false, "line_items": [ { "offer_attributes": null, "purchase_item_id": 63898947, "external_inventory_policy": "decrement_obeying_policy", "external_product_id": { "ecommerce": "4381728735283" }, "external_variant_id": { "ecommerce": "999999999999" }, "grams": 454, "images": { "large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg", "medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg", "original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg", "small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg" }, "original_price": "10.00", "properties": [ { "name": "Color", "value": "Blue" } ], "purchase_item_type": "subscription", "quantity": 1, "sku": "TOM0001", "tax_lines": [ { "price": "0.993", "rate": "0.0725", "title": "CA State Tax", "unit_price": "0.331" }, { "price": "0.308", "rate": "0.0225", "title": "LA County Tax", "unit_price": "0.102" } ], "taxable": true, "taxable_amount": "10.00", "tax_due": "1.30", "title": "Shirt bundle", "total_price": "11.30", "unit_price": "10.00", "unit_price_includes_tax": false, "variant_title": "Blue t-shirts" } ], "note": "next order in sequence 3", "order_attributes": [ { "name": "subscription_cycle_count_min", "value": "3" } ], "processed_at": "2020-12-17T18:50:27+00:00", "scheduled_at": "2020-12-17T18:50:27+00:00", "shipping_address": { "address1": "1030 Barnum Ave", "address2": "Suite 101", "city": "Stratford", "company": "Fake Company", "country_code": "US", "first_name": "Fake First", "last_name": "Fake Last", "phone": "999-999-9999", "province": "Connecticut", "zip": "06614" }, "shipping_lines": [ { "code": "Standard", "price": "4.90", "taxable": true, "tax_lines": [ { "price": "0.355", "rate": "0.0725", "title": "CA State Tax" }, { "price": "0.110", "rate": "0.0225", "title": "Los Angeles County Tax" } ], "title": "Standard" } ], "status": "success", "subtotal_price": "10.00", "tags": "Subscription, Subscription Recurring Order", "tax_lines": [ { "price": "0.950", "rate": "0.0725", "title": "CA State Tax" }, { "price": "0.335", "rate": "0.0225", "title": "Los Angeles County Tax" } ], "taxable": true, "total_discounts": "10.00", "total_duties": "0.0", "total_line_items_price": "10.00", "total_price": "14.90", "total_refunds": "0.00", "total_tax": "10.00", "total_weight_grams": 454, "type": "recurring", "updated_at": "2020-12-17T18:50:27+00:00" } } } } } }, "x-recharge-scopes": [ "read_orders" ] }, "put": { "operationId": "orders_update", "summary": "Update an order", "description": "Updating existing Order using the order_id .", "tags": [ "Orders" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "order": { "id": 210987092, "address_id": 42171447, "billing_address": { "address1": "601 SW Washing St.", "address2": "", "city": "Portland", "company": "Fake Company Billing", "country_code": "US", "first_name": "Fake Billing First", "last_name": "Fake Billing Last", "phone": "888-888-8888", "province": "Oregon", "zip": "97205" }, "charge": { "id": 272382456, "external_transaction_id": { "payment_processor": "ch_1HzWElJ2zqHvZRd1TWKFFqDR" }, "payment_processor_name": "stripe", "status": "success" }, "client_details": { "browser_ip": "192.168.0.1", "user_agent": "safari webkit" }, "created_at": "2020-12-17T18:50:25+00:00", "currency": "usd", "customer": { "id": 37657002, "email": "test@test.com", "external_customer_id": { "ecommerce": "382028302" }, "hash": "7e706455cbd13e40" }, "discounts": [ { "id": 12345, "code": "TESTCODE10", "value": 10, "value_type": "fixed_amount" } ], "error": null, "external_cart_token": "aeic8101918fs0f8810", "external_order_id": { "ecommerce": "27117383938" }, "external_order_name": { "ecommerce": "#1938" }, "external_order_number": { "ecommerce": "1938" }, "is_prepaid": false, "line_items": [ { "offer_attributes": null, "purchase_item_id": 63898947, "external_inventory_policy": "decrement_obeying_policy", "external_product_id": { "ecommerce": "4381728735283" }, "external_variant_id": { "ecommerce": "999999999999" }, "grams": 454, "images": { "large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg", "medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg", "original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg", "small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg" }, "original_price": "10.00", "properties": [ { "name": "Color", "value": "Blue" } ], "purchase_item_type": "subscription", "quantity": 1, "sku": "TOM0001", "tax_lines": [ { "price": "0.725", "rate": "0.0725", "title": "CA State Tax", "unit_price": "0.331" }, { "price": "0.225", "rate": "0.0225", "title": "LA County Tax", "unit_price": "0.102" } ], "taxable": true, "taxable_amount": "10.00", "tax_due": "0.95", "title": "Shirt bundle", "total_price": "10.95", "unit_price": "10.00", "unit_price_includes_tax": false, "variant_title": "Blue t-shirts" } ], "note": "next order in sequence 3", "order_attributes": [ { "name": "subscription_cycle_count_min", "value": "3" } ], "processed_at": "2020-12-17T18:50:27+00:00", "scheduled_at": "2020-12-17T18:50:27+00:00", "shipping_address": { "address1": "1030 Barnum Ave", "address2": "Suite 101", "city": "Stratford", "company": "Fake Company", "country_code": "US", "first_name": "Fake First", "last_name": "Fake Last", "phone": "999-999-9999", "province": "Connecticut", "zip": "06614" }, "shipping_lines": [ { "code": "Standard", "price": "4.90", "taxable": true, "tax_lines": [ { "price": "0.355", "rate": "0.0725", "title": "CA State Tax" }, { "price": "0.110", "rate": "0.0225", "title": "Los Angeles County Tax" } ], "title": "Standard" } ], "status": "success", "subtotal_price": "10.00", "tags": "Subscription, Subscription Recurring Order", "tax_lines": [ { "price": "0.355", "rate": "0.0725", "title": "CA State Tax" }, { "price": "0.110", "rate": "0.0225", "title": "Los Angeles County Tax" } ], "taxable": true, "total_discounts": "10.00", "total_line_items_price": "10.00", "total_price": "5.37", "total_refunds": "0.00", "total_tax": "0.47", "total_weight_grams": 454, "type": "recurring", "updated_at": "2020-12-17T18:50:27+00:00" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "billing_address": { "type": "object", "properties": { "address1": { "type": "string", "description": "Line one of the billing address." }, "address2": { "type": "string", "description": "Line two of the billing address." }, "city": { "type": "string", "description": "The city of the billing address." }, "company": { "type": "string", "description": "The company name of the billing address." }, "country_code": { "type": "string", "description": "2-letter country code." }, "first_name": { "type": "string", "description": "The first name of the billing address." }, "last_name": { "type": "string", "description": "The last name of the billing address." }, "phone": { "type": "string", "description": "The phone number of the billing address." }, "province": { "type": "string", "description": "The name of the province or state associated with the billing address." }, "zip": { "type": "string", "description": "The zip code or postcode of the address." } }, "description": "Billing address details." }, "customer": { "type": "object", "properties": { "email": { "type": "string", "description": "The user email." } }, "description": "The key values related with customer." }, "line_items": { "type": "array", "items": { "type": "object", "properties": { "purchase_item_id": { "type": "integer", "description": "The Subscription or Onetime ID associated with the line_item . By default this value is ignored and the line_item is linked to the active Subscription on the same Address that has the same external variant ID." }, "external_product_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "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 ." } }, "description": "An object containing the associated product ID as it appears in the external system." }, "external_variant_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "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 ." } }, "description": "An object containing the associated variant ID as it appears in the external system." }, "grams": { "type": "integer", "description": "The weight of the item in grams." }, "properties": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the property." }, "value": { "type": "string", "description": "The value of the property." } } }, "description": "An array of name value pairs of additional line_item attributes." }, "quantity": { "type": "integer", "description": "The quantity of the line_item ." }, "sku": { "type": "string", "description": "The SKU (stock keeping unit) of the Product associated with the line_item ." }, "title": { "type": "string", "description": "The title of the Product of this line_item ." }, "unit_price": { "type": "string", "description": "The unit price of the line_item ." }, "variant_title": { "type": "string", "description": "The name of a variant of the Product of this line_item ." } }, "required": [ "external_product_id", "external_variant_id", "quantity" ] }, "description": "Line item properties can be updated on Prepaid Queued Orders. To change Queued Charges you must change the parent subscription(s) or address." }, "external_order_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "The order ID as it appears in the external e-commerce platform." } }, "description": "An object containing external order ids." }, "scheduled_at": { "type": "string", "format": "date-time", "description": "The date when the order will be shipped." }, "shipping_address": { "type": "object", "properties": { "address1": { "type": "string", "description": "Line one of the billing address." }, "address2": { "type": "string", "description": "Line two of the billing address." }, "city": { "type": "string", "description": "The city of the billing address." }, "company": { "type": "string", "description": "The company name of the billing address." }, "country_code": { "type": "string", "description": "2-letter country code." }, "first_name": { "type": "string", "description": "The first name of the billing address." }, "last_name": { "type": "string", "description": "The last name of the billing address." }, "phone": { "type": "string", "description": "The phone number of the billing address." }, "province": { "type": "string", "description": "The name of the province or state associated with the billing address." }, "zip": { "type": "string", "description": "The zip code or postcode of the address." } }, "description": "Shipping address details." }, "status": { "type": "string", "description": "The status of the order", "enum": [ "cancelled" ] }, "external_order_number": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "The order number as it appears in the external e-commerce platform." } }, "description": "An object containing the external order numbers." }, "order_attributes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name for the attribute." }, "value": { "type": "string", "description": "The value for the associated attribute." } } }, "description": "An array of name value pairs of note attributes on the Order . Replaces the existing attributes." } } }, "example": { "billing_address": { "city": "Los Angeles", "first_name": "mike", "last_name": "flynn", "zip": "90025" } } } } }, "x-recharge-scopes": [ "write_orders" ] }, "delete": { "operationId": "orders_delete", "summary": "Delete an order", "description": "You can delete a scheduled order.", "tags": [ "Orders" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Content Deleted: The server has successfully fulfilled the request and deleted the desired object and there is no content to send in the response body.", "content": { "application/json": { "example": {} } } } }, "x-recharge-scopes": [ "write_orders" ] } }, "/orders/{id}/clone": { "post": { "operationId": "orders_clone", "summary": "Clone an order", "description": "You may add additional Orders onto a success Charge if it has existing prepaid Orders by cloning an existing Order .", "tags": [ "Orders" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "force_update", "in": "query", "required": false, "description": "By 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 .", "schema": { "type": "boolean" } } ], "responses": { "201": { "description": "OK: The request was successful, created a new resource, and resource created is in the body.", "content": { "application/json": { "example": { "order": { "id": 210987092, "address_id": 42171447, "billing_address": { "address1": "601 SW Washing St.", "address2": "", "city": "Portland", "company": "Fake Company Billing", "country_code": "US", "first_name": "Fake Billing First", "last_name": "Fake Billing Last", "phone": "888-888-8888", "province": "Oregon", "zip": "97205" }, "charge": { "id": 272382456, "external_transaction_id": { "payment_processor": "ch_1HzWElJ2zqHvZRd1TWKFFqDR" }, "payment_processor_name": "stripe", "status": "success" }, "client_details": { "browser_ip": "192.168.0.1", "user_agent": "safari webkit" }, "created_at": "2020-12-17T18:50:25+00:00", "currency": "usd", "customer": { "id": 37657002, "email": "test@test.com", "external_customer_id": { "ecommerce": "382028302" }, "hash": "7e706455cbd13e40" }, "discounts": [ { "id": 12345, "code": "TESTCODE10", "value": 10, "value_type": "fixed_amount" } ], "error": null, "external_cart_token": "aeic8101918fs0f8810", "external_order_id": { "ecommerce": "27117383938" }, "external_order_name": { "ecommerce": "#1938" }, "external_order_number": { "ecommerce": "1938" }, "is_prepaid": false, "line_items": [ { "offer_attributes": null, "purchase_item_id": 63898947, "external_inventory_policy": "decrement_obeying_policy", "external_product_id": { "ecommerce": "4381728735283" }, "external_variant_id": { "ecommerce": "999999999999" }, "grams": 454, "images": { "large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg", "medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg", "original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg", "small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg" }, "original_price": "10.00", "properties": [ { "name": "Color", "value": "Blue" } ], "purchase_item_type": "subscription", "quantity": 1, "sku": "TOM0001", "tax_lines": [ { "price": "0.993", "rate": "0.0725", "title": "CA State Tax", "unit_price": "0.331" }, { "price": "0.308", "rate": "0.0225", "title": "LA County Tax", "unit_price": "0.102" } ], "taxable": true, "taxable_amount": "10.00", "tax_due": "1.30", "title": "Shirt bundle", "total_price": "11.30", "unit_price": "10.00", "unit_price_includes_tax": false, "variant_title": "Blue t-shirts" } ], "note": "next order in sequence 3", "order_attributes": [ { "name": "subscription_cycle_count_min", "value": "3" } ], "processed_at": "2020-12-17T18:50:27+00:00", "scheduled_at": "2020-12-17T18:50:27+00:00", "shipping_address": { "address1": "1030 Barnum Ave", "address2": "Suite 101", "city": "Stratford", "company": "Fake Company", "country_code": "US", "first_name": "Fake First", "last_name": "Fake Last", "phone": "999-999-9999", "province": "Connecticut", "zip": "06614" }, "shipping_lines": [ { "code": "Standard", "price": "4.90", "taxable": true, "tax_lines": [ { "price": "0.355", "rate": "0.0725", "title": "CA State Tax" }, { "price": "0.110", "rate": "0.0225", "title": "Los Angeles County Tax" } ], "title": "Standard" } ], "status": "success", "subtotal_price": "10.00", "tags": "Subscription, Subscription Recurring Order", "tax_lines": [ { "price": "0.950", "rate": "0.0725", "title": "CA State Tax" }, { "price": "0.335", "rate": "0.0225", "title": "Los Angeles County Tax" } ], "taxable": true, "total_discounts": "10.00", "total_duties": "0.0", "total_line_items_price": "10.00", "total_price": "14.90", "total_refunds": "0.00", "total_tax": "10.00", "total_weight_grams": 454, "type": "recurring", "updated_at": "2020-12-17T18:50:27+00:00" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduled_at": { "type": "string", "format": "date-time", "description": "Date in future when this order will be sent." }, "charge_id": { "type": "integer", "description": "The ID of the Charge the cloned Order is associated with. Defaults to the Charge of the original Order ." }, "type": { "type": "string", "description": "Limits 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.", "enum": [ "subscriptions", "onetimes" ] } }, "required": [ "scheduled_at" ] }, "example": { "scheduled_at": "2022-11-16" } } } }, "x-recharge-scopes": [ "write_orders" ] } }, "/orders/{id}/delay": { "post": { "operationId": "orders_delay", "summary": "Delay an order", "description": "Delay a prepaid Order by one interval", "tags": [ "Orders" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "order": { "id": 70071255, "address_id": 4029306, "created_at": "2022-02-04T23:19:52+00:00", "currency": "usd", "discounts": [], "error": null, "external_cart_token": null, "external_order_name": { "ecommerce": null }, "is_prepaid": true, "line_items": [ { "offer_attributes": null, "purchase_item_id": 63898947, "external_inventory_policy": "decrement_obeying_policy", "external_product_id": { "ecommerce": "4381728735283" }, "external_variant_id": { "ecommerce": "999999999999" }, "grams": 454, "images": { "large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg", "medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg", "original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg", "small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg" }, "original_price": "10.00", "properties": [ { "name": "Color", "value": "Blue" } ], "purchase_item_type": "subscription", "quantity": 1, "sku": "TOM0001", "tax_lines": [ { "price": "0.993", "rate": "0.0725", "title": "CA State Tax", "unit_price": "0.331" }, { "price": "0.308", "rate": "0.0225", "title": "LA County Tax", "unit_price": "0.102" } ], "taxable": true, "taxable_amount": "10.00", "tax_due": "1.30", "title": "Shirt bundle", "total_price": "11.30", "unit_price": "10.00", "unit_price_includes_tax": false, "variant_title": "Blue t-shirts" } ], "note": null, "order_attributes": [], "processed_at": null, "scheduled_at": "2023-02-07T05:00:00+00:00", "shipping_lines": [ { "code": "Standard", "price": "4.90", "taxable": true, "tax_lines": [ { "price": "0.355", "rate": "0.0725", "title": "CA State Tax" }, { "price": "0.110", "rate": "0.0225", "title": "Los Angeles County Tax" } ], "title": "Standard" } ], "status": "queued", "subtotal_price": "10.00", "tags": "Subscription, Subscription Recurring Order", "tax_lines": [ { "price": "0.950", "rate": "0.0725", "title": "CA State Tax" }, { "price": "0.335", "rate": "0.0225", "title": "Los Angeles County Tax" } ], "taxable": true, "total_discounts": "0.00", "total_duties": "0.0", "total_line_items_price": "10.00", "total_price": "14.90", "total_refunds": "0.00", "total_tax": "10.00", "total_weight_grams": 454, "type": "recurring", "updated_at": "2023-01-05T22:11:46+00:00" } } } } } }, "x-recharge-scopes": [ "write_orders" ] } }, "/orders": { "get": { "operationId": "orders_list", "summary": "List orders", "description": "Returns a list of orders. HTTP request examples GET /orders GET /orders?customer_id=123 GET /orders?address_id=4587216 GET /orders?charge_id=45678542 GET /orders?created_at_min=2016-05-18&created_at_max=2016-06-18", "tags": [ "Orders" ], "parameters": [ { "name": "address_id", "in": "query", "required": false, "description": "Filter orders by address.", "schema": { "type": "string" } }, { "name": "charge_id", "in": "query", "required": false, "description": "Filter orders by charge.", "schema": { "type": "string" } }, { "name": "created_at_max", "in": "query", "required": false, "description": "Show orders created before the given date.", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at_min", "in": "query", "required": false, "description": "Show orders created after the given date.", "schema": { "type": "string", "format": "date-time" } }, { "name": "cursor", "in": "query", "required": false, "description": "The 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.", "schema": { "type": "string" } }, { "name": "customer_email", "in": "query", "required": false, "description": "Filter orders by the email of the Customer .", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "required": false, "description": "Filter orders by customer.", "schema": { "type": "string" } }, { "name": "external_customer_id", "in": "query", "required": false, "description": "Filter orders by external_customer_id.", "schema": { "type": "string" } }, { "name": "external_order_id", "in": "query", "required": false, "description": "Filter orders by external_order_id.", "schema": { "type": "string" } }, { "name": "external_order_ids", "in": "query", "required": false, "description": "Filter orders by external_order_id. Accepts a comma-separated list of up to 100 values.", "schema": { "type": "string" } }, { "name": "external_order_number", "in": "query", "required": false, "description": "Filter orders by the order number as it appears in the external e-commerce platform.", "schema": { "type": "integer" } }, { "name": "external_product_ids", "in": "query", "required": false, "description": "Filter orders that contain any of the given external product IDs. If passing multiple values, must be comma separated.", "schema": { "type": "string" } }, { "name": "external_variant_ids", "in": "query", "required": false, "description": "Filter orders that contain any of the given external variant IDs. If passing multiple values, must be comma separated.", "schema": { "type": "string" } }, { "name": "ids", "in": "query", "required": false, "description": "Filter orders by id. If passing multiple values, must be comma separated. Non-integer values will result in a 422 error", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "A 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 .", "schema": { "type": "string", "enum": [ "address", "customer", "metafields", "order_modifications", "subscriptions" ] } }, { "name": "is_prepaid", "in": "query", "required": false, "description": "Pass true to return only orders generated from a prepaid purchase. Passing false does not filter the results.", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "description": "The number of results.", "schema": { "type": "string", "default": 50 } }, { "name": "page", "in": "query", "required": false, "description": "The page to show. Default is 1.", "schema": { "type": "string", "deprecated": true, "default": 1 } }, { "name": "processed_at_max", "in": "query", "required": false, "description": "Show orders processed before the given date.", "schema": { "type": "string", "format": "date-time" } }, { "name": "processed_at_min", "in": "query", "required": false, "description": "Show orders processed after the given date.", "schema": { "type": "string", "format": "date-time" } }, { "name": "scheduled_at_max", "in": "query", "required": false, "description": "Show orders scheduled before the given date.", "schema": { "type": "string", "format": "date-time" } }, { "name": "scheduled_at_min", "in": "query", "required": false, "description": "Show orders scheduled after the given date.", "schema": { "type": "string", "format": "date-time" } }, { "name": "has_external_order", "in": "query", "required": false, "description": "Filter orders with/without external_order_id.", "schema": { "type": "string" } }, { "name": "sort_by", "in": "query", "required": false, "description": "Sort the results. Default is id-desc .", "schema": { "type": "string", "enum": [ "id-asc", "id-desc", "updated_at-asc", "updated_at-desc", "processed_at-asc", "processed_at-desc", "scheduled_at-asc", "scheduled_at-desc" ] } }, { "name": "status", "in": "query", "required": false, "description": "Filter orders by status.", "schema": { "type": "string", "enum": [ "cancelled", "error", "pending_charge_status", "pending_fraud", "queued", "skipped", "success" ] } }, { "name": "type", "in": "query", "required": false, "description": "Filter orders by type.", "schema": { "type": "string", "enum": [ "checkout", "recurring" ] } }, { "name": "purchase_item_id", "in": "query", "required": false, "description": "Filter orders by subscription or onetime.", "schema": { "type": "string" } }, { "name": "updated_at_max", "in": "query", "required": false, "description": "Show orders updated before the given date.", "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_at_min", "in": "query", "required": false, "description": "Show orders updated after the given date.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "next": "next_cursor", "previous": "previous_cursor", "orders": [ { "id": 210987092, "address_id": 42171447, "billing_address": { "address1": "601 SW Washing St.", "address2": "", "city": "Portland", "company": "Fake Company Billing", "country_code": "US", "first_name": "Fake Billing First", "last_name": "Fake Billing Last", "phone": "888-888-8888", "province": "Oregon", "zip": "97205" }, "charge": { "id": 272382456, "external_transaction_id": { "payment_processor": "ch_1HzWElJ2zqHvZRd1TWKFFqDR" }, "payment_processor_name": "stripe", "status": "success" }, "client_details": { "browser_ip": "192.168.0.1", "user_agent": "safari webkit" }, "created_at": "2020-12-17T18:50:25+00:00", "currency": "usd", "customer": { "id": 37657002, "email": "test@test.com", "external_customer_id": { "ecommerce": "382028302" }, "hash": "7e706455cbd13e40" }, "discounts": [ { "id": 12345, "code": "TESTCODE10", "value": 10, "value_type": "fixed_amount" } ], "error": null, "external_cart_token": "aeic8101918fs0f8810", "external_order_id": { "ecommerce": "27117383938" }, "external_order_name": { "ecommerce": "#1938" }, "external_order_number": { "ecommerce": "1938" }, "is_prepaid": false, "line_items": [ { "offer_attributes": null, "purchase_item_id": 63898947, "external_inventory_policy": "decrement_obeying_policy", "external_product_id": { "ecommerce": "4381728735283" }, "external_variant_id": { "ecommerce": "999999999999" }, "grams": 454, "images": { "large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg", "medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg", "original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg", "small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg" }, "original_price": "10.00", "properties": [ { "name": "Color", "value": "Blue" } ], "purchase_item_type": "subscription", "quantity": 1, "sku": "TOM0001", "tax_lines": [ { "price": "0.993", "rate": "0.0725", "title": "CA State Tax", "unit_price": "0.331" }, { "price": "0.308", "rate": "0.0225", "title": "LA County Tax", "unit_price": "0.102" } ], "taxable": true, "taxable_amount": "10.00", "tax_due": "1.30", "title": "Shirt bundle", "total_price": "11.30", "unit_price": "10.00", "unit_price_includes_tax": false, "variant_title": "Blue t-shirts" } ], "note": "next order in sequence 3", "order_attributes": [ { "name": "subscription_cycle_count_min", "value": "3" } ], "processed_at": "2020-12-17T18:50:27+00:00", "scheduled_at": "2020-12-17T18:50:27+00:00", "shipping_address": { "address1": "1030 Barnum Ave", "address2": "Suite 101", "city": "Stratford", "company": "Fake Company", "country_code": "US", "first_name": "Fake First", "last_name": "Fake Last", "phone": "999-999-9999", "province": "Connecticut", "zip": "06614" }, "shipping_lines": [ { "code": "Standard", "price": "4.90", "taxable": true, "tax_lines": [ { "price": "0.355", "rate": "0.0725", "title": "CA State Tax" }, { "price": "0.110", "rate": "0.0225", "title": "Los Angeles County Tax" } ], "title": "Standard" } ], "status": "success", "subtotal_price": "10.00", "tags": "Subscription, Subscription Recurring Order", "tax_lines": [ { "price": "0.950", "rate": "0.0725", "title": "CA State Tax" }, { "price": "0.335", "rate": "0.0225", "title": "Los Angeles County Tax" } ], "taxable": true, "total_discounts": "10.00", "total_duties": "0.0", "total_line_items_price": "10.00", "total_price": "14.90", "total_refunds": "0.00", "total_tax": "10.00", "total_weight_grams": 454, "type": "recurring", "updated_at": "2020-12-17T18:50:27+00:00" } ] } } } } }, "x-recharge-scopes": [ "read_orders" ] } }, "/payment_methods": { "post": { "operationId": "payment_methods_create", "summary": "Create a payment method", "description": "Create a Payment Method in Recharge.", "tags": [ "Payment methods" ], "responses": { "201": { "description": "OK: The request was successful, created a new resource, and resource created is in the body.", "content": { "application/json": { "example": { "payment_method": { "id": 1234567, "customer_id": 62459147, "billing_address": { "address1": "123 Washington Street", "address2": "Suite 101", "city": "Los Angeles", "company": "Recharge", "country": "United States", "country_code": "US", "first_name": "Jane", "last_name": "Doe", "phone": "1234567890", "province": "California", "zip": "90210" }, "created_at": "2018-11-14T09:00:01", "default": true, "payment_details": { "brand": "visa", "exp_month": 12, "exp_year": 2021, "last4": "1234" }, "payment_type": "CREDIT_CARD", "processor_customer_token": "cus_AB3457BaL90Cx9", "processor_name": "stripe", "processor_payment_method_token": "pm_1LdKdfj2zqHvUId1uGheBEHy", "status": null, "status_reason": null, "updated_at": "2018-11-14T09:00:01" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "address_ids": { "type": "array", "items": {}, "description": "A 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_addresses": { "type": "boolean", "description": "If true , the new payment method is associated with all of the addresses of the customer." }, "customer_id": { "type": "integer", "description": "The Recharge customer_id ." }, "default": { "type": "boolean", "description": "true if this is default payment method for the Customer." }, "payment_details": { "type": "object", "description": "Details 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." }, "payment_type": { "type": "string", "description": "The type of payment.", "enum": [ "CREDIT_CARD", "PAYPAL", "APPLE_PAY", "GOOGLE_PAY", "SEPA_DEBIT", "IDEAL", "SHOP_PAY", "PAYPAL_EXPRESS", "SOFORT", "GIROPAY", "AMAZON_PAY", "INVOICE", "AFTERPAY_CLEARPAY", "KLARNA" ] }, "processor_customer_token": { "type": "string", "description": "The customer token at the processor." }, "processor_name": { "type": "string", "description": "This will impact validation on billing_details.", "enum": [ "stripe", "braintree", "authorize", "shopify_payments", "mollie", "custom_gateway" ] }, "processor_payment_method_token": { "type": "string", "description": "The payment token at the processor." }, "billing_address": { "type": "object", "properties": { "address1": { "type": "string", "description": "Line one of the billing address." }, "address2": { "type": "string", "description": "Line two of the billing address." }, "city": { "type": "string", "description": "The city of the billing address." }, "company": { "type": "string", "description": "The company name of the billing address." }, "country": { "type": "string", "description": "The full country name of the billing address. Either country or country_code is required when billing_address is passed." }, "country_code": { "type": "string", "description": "2-letter country code." }, "first_name": { "type": "string", "description": "The first name of the billing address." }, "last_name": { "type": "string", "description": "The last name of the billing address." }, "phone": { "type": "string", "description": "The phone number of the billing address." }, "province": { "type": "string", "description": "The name of the province or state associated with the billing address." }, "zip": { "type": "string", "description": "The zip code or postcode of the address." } }, "required": [ "address1", "city" ], "description": "An object with the customer’s address information." }, "retry_charges": { "type": "boolean", "description": "Whether charges associated with this payment method should be retried. If true then charges with previous payment-related errors will be set to retry during the next automated processing." } }, "required": [ "customer_id", "default", "payment_type", "processor_name" ] }, "example": { "customer_id": 62824147, "default": true, "payment_type": "CREDIT_CARD", "processor_customer_token": "cus_JGYtLWi2HS8ymD", "processor_name": "stripe", "processor_payment_method_token": "pm_34jdshjs" } } } }, "x-recharge-scopes": [ "write_payment_methods" ] }, "get": { "operationId": "payment_methods_list", "summary": "List payment methods", "description": "Return a list of payment methods in your store. HTTP request examples GET /payment_methods", "tags": [ "Payment methods" ], "parameters": [ { "name": "customer_id", "in": "query", "required": false, "description": "Gets all Payment methods for this customer.", "schema": { "type": "string" } }, { "name": "address_id", "in": "query", "required": false, "description": "Gets all Payment methods associated with this Address .", "schema": { "type": "integer" } }, { "name": "ids", "in": "query", "required": false, "description": "Filter payment methods by id. If passing multiple values, must be comma separated.", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "A comma-separated list of related resources to return in the include object of each payment method. Both values require the read_customers scope.", "schema": { "type": "string", "enum": [ "addresses", "customer" ] } }, { "name": "include_deleted", "in": "query", "required": false, "description": "If true , deleted payment methods are also returned and each payment method includes a deleted_at attribute.", "schema": { "type": "boolean" } }, { "name": "processor_name", "in": "query", "required": false, "description": "Filter payment methods by processor. Can only be passed together with customer_id .", "schema": { "type": "string", "enum": [ "stripe", "braintree", "authorize", "shopify_payments", "mollie", "custom_gateway" ] } }, { "name": "processor_payment_method_token", "in": "query", "required": false, "description": "Filter payment methods by the payment token at the processor. Only applied when customer_id is also passed.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "The number of results. Default is 50, maximum is 250.", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "The page to show. Default is 1.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "payment_methods": [ { "id": 1234567, "billing_address": { "address1": "123 Washington Street", "address2": "Suite 101", "city": "Los Angeles", "company_name": "Acme Corp", "country": "United States", "country_code": "US", "name": "Jane Doe", "phone": "1234567890", "province": "California", "zip": "90210" }, "created_at": "2018-11-14T09:00:01", "customer_id": 999123999, "default": true, "payment_details": [ { "brand": "visa", "exp_month": 12, "exp_year": 2021, "last4": 1234 } ], "payment_type": "CREDIT_CARD", "processor_customer_token": "cus_AB3ebcBaL6pCx9", "processor_name": "stripe", "processor_payment_method_token": "pm_123123", "updated_at": "2018-11-14T09:00:01" } ] } } } } }, "x-recharge-scopes": [ "read_payment_methods" ] } }, "/payment_methods/{id}": { "get": { "operationId": "payment_methods_retrieve", "summary": "Retrieve a payment method", "description": "Retrieve an existing Payment Method using the Recharge Payment Method id .", "tags": [ "Payment methods" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "A comma-separated list of related resources to return in the include object of the payment method. Both values require the read_customers scope.", "schema": { "type": "string", "enum": [ "addresses", "customer" ] } }, { "name": "include_deleted", "in": "query", "required": false, "description": "If true , a deleted payment method can be retrieved.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "payment_method": { "id": 1234567, "customer_id": 62459147, "billing_address": { "address1": "123 Washington Street", "address2": "Suite 101", "city": "Los Angeles", "company": "Recharge", "country": "United States", "country_code": "US", "first_name": "Jane", "last_name": "Doe", "phone": "1234567890", "province": "California", "zip": "90210" }, "created_at": "2018-11-14T09:00:01", "default": true, "payment_details": { "brand": "visa", "exp_month": 12, "exp_year": 2021, "last4": "1234" }, "payment_type": "CREDIT_CARD", "processor_customer_token": "cus_AB3457BaL90Cx9", "processor_name": "stripe", "processor_payment_method_token": "pm_1LdKdfj2zqHvUId1uGheBEHy", "status": null, "status_reason": null, "updated_at": "2018-11-14T09:00:01" } } } } } }, "x-recharge-scopes": [ "read_payment_methods" ] }, "put": { "operationId": "payment_methods_update", "summary": "Update a payment method", "description": "Modify an existing Payment Method .", "tags": [ "Payment methods" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "payment_method": { "id": 1234567, "customer_id": 62459147, "billing_address": { "address1": "123 Washington Street", "address2": "Suite 101", "city": "Los Angeles", "company": "Recharge", "country": "United States", "country_code": "US", "first_name": "Jane", "last_name": "Doe", "phone": "1234567890", "province": "California", "zip": "90210" }, "created_at": "2018-11-14T09:00:01", "default": true, "payment_details": { "brand": "visa", "exp_month": 12, "exp_year": 2021, "last4": "1234" }, "payment_type": "CREDIT_CARD", "processor_customer_token": "cus_AB3457BaL90Cx9", "processor_name": "stripe", "processor_payment_method_token": "pm_1LdKdfj2zqHvUId1uGheBEHy", "status": null, "status_reason": null, "updated_at": "2018-11-14T09:00:01" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "default": { "type": "boolean", "description": "true if this is default payment method for the Customer." }, "billing_address": { "type": "object", "properties": { "address1": { "type": "string", "description": "Line one of the billing address." }, "address2": { "type": "string", "description": "Line two of the billing address." }, "city": { "type": "string", "description": "The city of the billing address." }, "company": { "type": "string", "description": "The company name of the billing address." }, "country": { "type": "string", "description": "The full country name of the billing address." }, "country_code": { "type": "string", "description": "2-letter country code." }, "first_name": { "type": "string", "description": "The first name of the billing address." }, "last_name": { "type": "string", "description": "The last name of the billing address." }, "phone": { "type": "string", "description": "The phone number of the billing address." }, "province": { "type": "string", "description": "The name of the province or state associated with the billing address." }, "zip": { "type": "string", "description": "The zip code or postcode of the address." } }, "description": "An object with the customer’s address information." }, "payment_details": { "type": "object", "description": "Details about the specific payment method. Accepts brand , last4 , exp_month , exp_year , paypal_email , paypal_payer_id , wallet_type and funding_type ." }, "payment_type": { "type": "string", "description": "The type of payment. Must be supported by the processor of the payment method.", "enum": [ "CREDIT_CARD", "PAYPAL", "APPLE_PAY", "GOOGLE_PAY", "SEPA_DEBIT", "IDEAL", "SHOP_PAY", "PAYPAL_EXPRESS", "SOFORT", "GIROPAY", "AMAZON_PAY", "INVOICE", "AFTERPAY_CLEARPAY", "KLARNA" ] }, "processor_customer_token": { "type": "string", "description": "The customer token at the processor. Only applied when processor_payment_method_token is also passed." }, "processor_payment_method_token": { "type": "string", "description": "The payment token at the processor. The token is validated with the processor and the payment details are refreshed from it." }, "retry_charges": { "type": "boolean", "description": "Whether charges with a previous payment failure should be retried after the payment method is updated. Defaults to true ." } } }, "example": { "default": true } } } }, "x-recharge-scopes": [ "write_payment_methods" ] }, "delete": { "operationId": "payment_methods_delete", "summary": "Delete a payment method", "description": "Permanently delete a Payment Method .", "tags": [ "Payment methods" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Content Deleted: The server has successfully fulfilled the request and deleted the desired object and there is no content to send in the response body.", "content": { "application/json": { "example": {} } } } }, "x-recharge-scopes": [ "write_payment_methods" ] } }, "/plans": { "post": { "operationId": "plans_create", "summary": "Create a plan", "description": "Create a Plan for a Product in Recharge.", "tags": [ "Plans" ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "plan": { "id": 88237, "channel_settings": { "api": { "display": true }, "checkout_page": { "display": true }, "customer_portal": { "display": true }, "merchant_portal": { "display": true } }, "created_at": "2021-07-27T19:07:34+00:00", "deleted_at": null, "discount_amount": "10", "discount_type": "percentage", "external_product_id": { "ecommerce": "2103271587891" }, "product_quantity": null, "sort_order": 1, "subscription_preferences": { "charge_interval_frequency": 30, "cutoff_day_of_month": null, "cutoff_day_of_week": null, "expire_after_specific_number_of_charges": 6, "interval_unit": "day", "order_day_of_month": 1, "order_day_of_week": null, "order_interval_frequency": 30 }, "title": "Concert TShirt", "translations": [], "type": "subscription", "updated_at": "2021-07-27T19:07:34+00:00" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "addon_settings": { "type": "object", "properties": { "expiration": { "type": "object", "properties": { "type": { "type": "string", "description": "How the expiration is expressed.", "enum": [ "relative", "absolute" ] }, "value": { "type": "object", "description": "The 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." } }, "description": "An 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." }, "parent_external_variant_ids": { "type": "array", "items": {}, "description": "An 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." } }, "description": "An 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." }, "channel_settings": { "type": "object", "properties": { "api": { "type": "object", "properties": { "display": { "type": "boolean", "description": "A boolean to indicate if the plan may be used in the associated channel (defaults to true for all channels).", "default": true } }, "description": "An object containing api channel settings." }, "customer_portal": { "type": "object", "properties": { "display": { "type": "boolean", "description": "A boolean to indicate if the plan may be used in the associated channel (defaults to true for all channels).", "default": true } }, "description": "An object containing customer portal channel settings." }, "merchant_portal": { "type": "object", "properties": { "display": { "type": "boolean", "description": "A boolean to indicate if the plan may be used in the associated channel (defaults to true for all channels).", "default": true } }, "description": "An object containing merchant portal channel settings." }, "checkout_page": { "type": "object", "properties": { "display": { "type": "boolean", "description": "A boolean to indicate if the plan may be used in the associated channel (defaults to true for all channels).", "default": true } }, "description": "An object containing checkout channel settings." } }, "description": "An object containing the availability of the plan through various supported channels." }, "discount_amount": { "type": "string", "description": "The discount amount applied to the product price when purchased through this plan." }, "discount_type": { "type": "string", "description": "Used in combination with discount amount to determine the discount applied on a product price when purchased through this plan. percentage applies the discount amount as a percent off the price; fixed_amount applies it as a flat amount in the store's currency. (accepts: percentage, fixed_amount)", "enum": [ "percentage", "fixed_amount" ] }, "external_product_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "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 ." } }, "required": [ "ecommerce" ], "description": "An object containing the product id as it appears in external platforms." }, "external_variant_ids": { "type": "array", "items": {}, "description": "An array of variant ids, as they appear in external platforms, that the plan applies to." }, "has_variant_restrictions": { "type": "boolean", "description": "Whether this plan applies only to the variants listed in external_variant_ids . Defaults to false ." }, "product_quantity": { "type": "integer", "description": "The quantity of the product that a subscriber receives when purchasing through this Plan . null when the plan does not set a quantity." }, "sort_order": { "type": "integer", "description": "The number indicating the order which the plan will be in a list of related plans." }, "subscription_preferences": { "type": "object", "properties": { "apply_cutoff_date_to_checkout": { "type": "boolean", "description": "Whether the specified cutoff day should be applied to the initial checkout order" }, "charge_interval_frequency": { "type": "integer", "description": "Frequency at which the subscriber will be charged." }, "cutoff_day_of_month": { "type": "integer", "description": "Day of the month the plan should be charged" }, "cutoff_day_of_week": { "type": "integer", "description": "Day of the month the plan should be charged" }, "expire_after_specific_number_of_charges": { "type": "integer", "description": "A maximum number of charges on which the subscription should appear before automatic cancellation." }, "order_day_of_month": { "type": "integer", "description": "Day of the month an order should be generated when the customer is subscribed." }, "order_day_of_week": { "type": "integer", "description": "Day of the week an order should be generated when the customer is subscribed." }, "order_interval_frequency": { "type": "integer", "description": "Frequency at which the subscriber will receive shipments when subscribed to this plan." }, "interval_unit": { "type": "string", "description": "The unit applied to charge_interval_frequency and order_interval_frequency .", "enum": [ "day", "week", "month" ] }, "pricing_progression": { "type": "array", "items": { "type": "object", "properties": { "recurring_discount_after_cycle": { "type": "integer", "description": "The number of cycles after which this recurring discount should be applied. The checkout order is cycle 1. The first recurring order is cycle 2." }, "recurring_discount_amount": { "type": "string", "description": "The discount amount applied to the product price after the specified number of cycles." }, "recurring_discount_type": { "type": "string", "description": "Used in combination with discount amount to determine the discount applied on a product price after the specified number of cycles. percentage applies the discount amount as a percent off the price; fixed_amount applies it as a flat amount in the store's currency.", "enum": [ "percentage", "fixed_amount" ] } } }, "description": "Used to configure a plan with dynamic pricing. For regular subscription plans, this is field is null. For dynamically priced plans, this field is an array of one item." } }, "required": [ "charge_interval_frequency", "order_interval_frequency", "interval_unit" ], "description": "An object containing the various subscription preferences associated with this plan." }, "title": { "type": "string", "description": "The title of the plan." }, "translations": { "type": "array", "items": { "type": "object", "properties": { "language": { "type": "string", "description": "The language code of the translation, for example fr ." }, "title": { "type": "string", "description": "The title of the Plan in that language." } } }, "description": "An array of translated titles for the Plan ." }, "type": { "type": "string", "description": "The type of the plan. Products with a prepaid plan cannot have plans of other types.", "enum": [ "subscription", "prepaid", "prepaid_v2", "onetime", "membership_subscription" ] } }, "required": [ "external_product_id", "subscription_preferences", "title", "type" ] } } } }, "x-recharge-scopes": [ "write_plans" ] }, "get": { "operationId": "plans_list", "summary": "List plans", "description": "Returns a list of all plans from Store .", "tags": [ "Plans" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "The number of results.", "schema": { "type": "string", "default": 50 } }, { "name": "page", "in": "query", "required": false, "description": "The page to show.", "schema": { "type": "string", "deprecated": true, "default": 1 } }, { "name": "external_product_id", "in": "query", "required": false, "description": "Return the Plans linked to the Product record in Recharge with the indicated external_product_id", "schema": { "type": "string" } }, { "name": "ids", "in": "query", "required": false, "description": "Filter plans by id. If passing multiple values, must be comma separated. Non-integer values will result in a 422 error", "schema": { "type": "string" } }, { "name": "updated_at_max", "in": "query", "required": false, "description": "Return the plans updated before the given date.", "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_at_min", "in": "query", "required": false, "description": "Return the plans updated after the given date.", "schema": { "type": "string", "format": "date-time" } }, { "name": "type", "in": "query", "required": false, "description": "Return the plans that are of a specific type.", "schema": { "type": "string", "enum": [ "subscription", "prepaid", "prepaid_v2", "onetime", "membership_subscription" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "The 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 .", "schema": { "type": "string" } }, { "name": "sort_by", "in": "query", "required": false, "description": "The order in which the plans are returned. Defaults to id-desc .", "schema": { "type": "string", "enum": [ "id-asc", "id-desc", "updated_at-asc", "updated_at-desc" ] } }, { "name": "created_at_min", "in": "query", "required": false, "description": "Return the plans created after the given date.", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at_max", "in": "query", "required": false, "description": "Return the plans created before the given date.", "schema": { "type": "string", "format": "date-time" } }, { "name": "external_product_ids", "in": "query", "required": false, "description": "Return the Plans linked to any of the given external_product_id values. If passing multiple values, must be comma separated.", "schema": { "type": "string" } }, { "name": "external_variant_id", "in": "query", "required": false, "description": "Return 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 .", "schema": { "type": "string" } }, { "name": "external_plan_id", "in": "query", "required": false, "description": "Return the Plans with the given external_plan_id .", "schema": { "type": "string" } }, { "name": "external_plan_group_id", "in": "query", "required": false, "description": "Return the Plans with the given external_plan_group_id .", "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "plans": [ { "id": 88237, "channel_settings": { "api": { "display": true }, "checkout_page": { "display": true }, "customer_portal": { "display": true }, "merchant_portal": { "display": true } }, "created_at": "2021-07-27T19:07:34+00:00", "deleted_at": null, "discount_amount": null, "discount_type": null, "external_product_id": { "ecommerce": "2103271587891" }, "product_quantity": null, "sort_order": 1, "subscription_preferences": { "charge_interval_frequency": 30, "cutoff_day_of_month": null, "cutoff_day_of_week": null, "expire_after_specific_number_of_charges": null, "interval_unit": "day", "order_day_of_month": 1, "order_day_of_week": null, "order_interval_frequency": 30 }, "title": "Jarred Pickles", "translations": [], "type": "subscription", "updated_at": "2021-07-27T19:07:34+00:00" } ] } } } } }, "x-recharge-scopes": [ "read_plans" ] } }, "/plans/{id}": { "put": { "operationId": "plans_update", "summary": "Update a plan", "description": "Update an existing Plan.", "tags": [ "Plans" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "plan": { "id": 88237, "channel_settings": { "api": { "display": true }, "checkout_page": { "display": true }, "customer_portal": { "display": true }, "merchant_portal": { "display": true } }, "created_at": "2021-07-27T19:07:34+00:00", "deleted_at": null, "discount_amount": "10", "discount_type": "percentage", "external_product_id": { "ecommerce": "2103271587891" }, "product_quantity": null, "sort_order": 1, "subscription_preferences": { "charge_interval_frequency": 30, "cutoff_day_of_month": null, "cutoff_day_of_week": null, "expire_after_specific_number_of_charges": 6, "interval_unit": "day", "order_day_of_month": 1, "order_day_of_week": null, "order_interval_frequency": 30 }, "title": "Concert TShirt", "translations": [], "type": "subscription", "updated_at": "2021-07-27T19:07:34+00:00" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "addon_settings": { "type": "object", "properties": { "expiration": { "type": "object", "properties": { "type": { "type": "string", "description": "How the expiration is expressed.", "enum": [ "relative", "absolute" ] }, "value": { "type": "object", "description": "The 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." } }, "description": "An 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." }, "parent_external_variant_ids": { "type": "array", "items": {}, "description": "An 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." } }, "description": "An 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." }, "channel_settings": { "type": "object", "properties": { "api": { "type": "object", "properties": { "display": { "type": "boolean", "description": "A boolean to indicate if the plan may be used in the associated channel (defaults to true for all channels).", "default": true } }, "description": "An object containing api channel settings." }, "customer_portal": { "type": "object", "properties": { "display": { "type": "boolean", "description": "A boolean to indicate if the plan may be used in the associated channel (defaults to true for all channels).", "default": true } }, "description": "An object containing customer portal channel settings." }, "merchant_portal": { "type": "object", "properties": { "display": { "type": "boolean", "description": "A boolean to indicate if the plan may be used in the associated channel (defaults to true for all channels).", "default": true } }, "description": "An object containing merchant portal channel settings." }, "checkout_page": { "type": "object", "properties": { "display": { "type": "boolean", "description": "A boolean to indicate if the plan may be used in the associated channel (defaults to true for all channels).", "default": true } }, "description": "An object containing checkout channel settings." } }, "description": "An object containing the availability of the plan through various supported channels." }, "discount_amount": { "type": "string", "description": "The discount amount applied to the product price when purchased through this plan." }, "discount_type": { "type": "string", "description": "Used in combination with discount amount to determine the discount applied on a product price when purchased through this plan. percentage applies the discount amount as a percent off the price; fixed_amount applies it as a flat amount in the store's currency.", "enum": [ "percentage", "fixed_amount" ] }, "external_product_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "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 ." } }, "description": "An object containing the product id as it appears in external platforms." }, "external_variant_ids": { "type": "array", "items": {}, "description": "An array of variant ids, as they appear in external platforms, that the plan applies to." }, "has_variant_restrictions": { "type": "boolean", "description": "Whether this plan applies only to the variants listed in external_variant_ids . Defaults to false ." }, "product_quantity": { "type": "integer", "description": "The quantity of the product that a subscriber receives when purchasing through this Plan . null when the plan does not set a quantity." }, "sort_order": { "type": "integer", "description": "The number indicating the order which the plan will be in a list of related plans." }, "subscription_preferences": { "type": "object", "properties": { "apply_cutoff_date_to_checkout": { "type": "boolean", "description": "Whether the specified cutoff day should be applied to the initial checkout order" }, "charge_interval_frequency": { "type": "integer", "description": "Frequency at which the subscriber will be charged." }, "cutoff_day_of_month": { "type": "integer", "description": "Day of the month the plan should be charged" }, "cutoff_day_of_week": { "type": "integer", "description": "Day of the month the plan should be charged" }, "expire_after_specific_number_of_charges": { "type": "integer", "description": "A maximum number of charges on which the subscription should appear before automatic cancellation." }, "order_day_of_month": { "type": "integer", "description": "Day of the month an order should be generated when the customer is subscribed." }, "order_day_of_week": { "type": "integer", "description": "Day of the week an order should be generated when the customer is subscribed." }, "order_interval_frequency": { "type": "integer", "description": "Frequency at which the subscriber will receive shipments when subscribed to this plan." }, "interval_unit": { "type": "string", "description": "The unit applied to charge_interval_frequency and order_interval_frequency .", "enum": [ "day", "week", "month" ] }, "pricing_progression": { "type": "array", "items": { "type": "object", "properties": { "recurring_discount_after_cycle": { "type": "integer", "description": "The number of cycles after which this recurring discount should be applied. The checkout order is cycle 1. The first recurring order is cycle 2." }, "recurring_discount_amount": { "type": "string", "description": "The discount amount applied to the product price after the specified number of cycles." }, "recurring_discount_type": { "type": "string", "description": "Used in combination with discount amount to determine the discount applied on a product price after the specified number of cycles. percentage applies the discount amount as a percent off the price; fixed_amount applies it as a flat amount in the store's currency.", "enum": [ "percentage", "fixed_amount" ] } } }, "description": "Used to configure a plan with dynamic pricing. For regular subscription plans, this is field is null. For dynamically priced plans, this field is an array of one item." } }, "description": "An object containing the various subscription preferences associated with this plan." }, "title": { "type": "string", "description": "The title of the plan." }, "translations": { "type": "array", "items": { "type": "object", "properties": { "language": { "type": "string", "description": "The language code of the translation, for example fr ." }, "title": { "type": "string", "description": "The title of the Plan in that language." } } }, "description": "An array of translated titles for the Plan ." } } }, "example": { "discount_amount": "12.0", "title": "Concert T-Shirt" } } } }, "x-recharge-scopes": [ "write_plans" ] }, "delete": { "operationId": "plans_delete", "summary": "Delete a plan", "description": "Delete a plan.", "tags": [ "Plans" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Content Deleted: The server has successfully fulfilled the request and deleted the desired object and there is no content to send in the response body.", "content": { "application/json": { "example": {} } } } }, "x-recharge-scopes": [ "write_plans" ] }, "get": { "operationId": "plans_retrieve", "summary": "Retrieve a plan", "description": "Retrieves a single Plan by its id. Deleted plans return a 404 .", "tags": [ "Plans" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "plan": { "id": 1298456, "channel_settings": { "api": { "display": true }, "checkout_page": { "display": true }, "customer_portal": { "display": true }, "merchant_portal": { "display": true } }, "created_at": "2026-03-02T15:04:31+00:00", "deleted_at": null, "discount_amount": "10.00", "discount_type": "percentage", "external_plan_group_id": null, "external_plan_id": null, "external_plan_name": null, "external_product_id": { "ecommerce": "7654321098" }, "external_variant_ids": [], "has_variant_restrictions": false, "product_quantity": null, "sort_order": 1, "subscription_preferences": { "apply_cutoff_date_to_checkout": false, "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, "pricing_progression": [] }, "title": "Monthly coffee", "translations": [ { "language": "fr", "title": "Cafe mensuel" } ], "type": "subscription", "updated_at": "2026-03-02T15:04:31+00:00" } } } } } }, "x-recharge-scopes": [ "read_plans" ] } }, "/products/{external_product_id}/plans-bulk": { "post": { "operationId": "plans_bulk_create", "summary": "Bulk create plans", "description": "Bulk create new plans. There is a limit of 20 plans per request.", "tags": [ "Plans" ], "parameters": [ { "name": "external_product_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "plans": [ { "id": 88237, "channel_settings": { "api": { "display": true }, "checkout_page": { "display": true }, "customer_portal": { "display": true }, "merchant_portal": { "display": true } }, "created_at": "2021-07-27T19:07:34+00:00", "discount_amount": "10", "discount_type": "percentage", "external_product_id": { "ecommerce": "2103271587891" }, "product_quantity": null, "sort_order": 1, "title": "Concert T-Shirt", "translations": [], "type": "subscription", "subscription_preferences": { "charge_interval_frequency": 30, "cutoff_day_of_month": null, "cutoff_day_of_week": null, "expire_after_specific_number_of_charges": 6, "interval_unit": "day", "order_day_of_month": 1, "order_interval_frequency": 30 }, "updated_at": "2021-07-27T19:07:34+00:00" }, { "id": 88238, "channel_settings": { "api": { "display": true }, "checkout_page": { "display": true }, "customer_portal": { "display": true }, "merchant_portal": { "display": true } }, "created_at": "2021-07-27T19:07:34+00:00", "discount_amount": "10", "discount_type": "percentage", "external_product_id": { "ecommerce": "2103271587891" }, "product_quantity": null, "sort_order": 2, "title": "Concert T-Shirt", "translations": [], "type": "subscription", "subscription_preferences": { "charge_interval_frequency": 60, "expire_after_specific_number_of_charges": 6, "interval_unit": "day", "order_day_of_month": 1, "order_interval_frequency": 60 }, "updated_at": "2021-07-27T19:07:34+00:00" } ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "plans": { "type": "array", "items": { "type": "object", "properties": { "addon_settings": { "type": "object", "properties": { "expiration": { "type": "object", "properties": { "type": { "type": "string", "description": "How the expiration is expressed.", "enum": [ "relative", "absolute" ] }, "value": { "type": "object", "description": "The 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." } }, "description": "An 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." }, "parent_external_variant_ids": { "type": "array", "items": {}, "description": "An 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." } }, "description": "An 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." }, "channel_settings": { "type": "object", "properties": { "api": { "type": "object", "properties": { "display": { "type": "boolean", "description": "A boolean to indicate if the plan may be used in the associated channel (defaults to true for all channels).", "default": true } }, "description": "An object containing api channel settings." }, "customer_portal": { "type": "object", "properties": { "display": { "type": "boolean", "description": "A boolean to indicate if the plan may be used in the associated channel (defaults to true for all channels).", "default": true } }, "description": "An object containing customer portal channel settings." }, "merchant_portal": { "type": "object", "properties": { "display": { "type": "boolean", "description": "A boolean to indicate if the plan may be used in the associated channel (defaults to true for all channels).", "default": true } }, "description": "An object containing merchant portal channel settings." }, "checkout_page": { "type": "object", "properties": { "display": { "type": "boolean", "description": "A boolean to indicate if the plan may be used in the associated channel (defaults to true for all channels).", "default": true } }, "description": "An object containing checkout channel settings." } }, "description": "An object containing the availability of the plan through various supported channels." }, "discount_amount": { "type": "string", "description": "The discount amount applied to the product price when purchased through this plan." }, "discount_type": { "type": "string", "description": "Used in combination with discount amount to determine the discount applied on a product price when purchased through this plan. percentage applies the discount amount as a percent off the price; fixed_amount applies it as a flat amount in the store's currency.", "enum": [ "percentage", "fixed_amount" ] }, "external_variant_ids": { "type": "array", "items": {}, "description": "An array of variant ids, as they appear in external platforms, that the plan applies to." }, "has_variant_restrictions": { "type": "boolean", "description": "Whether this plan applies only to the variants listed in external_variant_ids . Defaults to false ." }, "product_quantity": { "type": "integer", "description": "The quantity of the product that a subscriber receives when purchasing through this Plan . null when the plan does not set a quantity." }, "sort_order": { "type": "integer", "description": "The number indicating the order which the plan will be in a list of related plans." }, "subscription_preferences": { "type": "object", "properties": { "apply_cutoff_date_to_checkout": { "type": "boolean", "description": "Whether the specified cutoff day should be applied to the initial checkout order" }, "charge_interval_frequency": { "type": "integer", "description": "Frequency at which the subscriber will be charged." }, "cutoff_day_of_month": { "type": "integer", "description": "Day of the month the plan should be charged" }, "cutoff_day_of_week": { "type": "integer", "description": "Day of the month the plan should be charged" }, "expire_after_specific_number_of_charges": { "type": "integer", "description": "A maximum number of charges on which the subscription should appear before automatic cancellation." }, "order_day_of_month": { "type": "integer", "description": "Day of the month an order should be generated when the customer is subscribed." }, "order_day_of_week": { "type": "integer", "description": "Day of the week an order should be generated when the customer is subscribed." }, "order_interval_frequency": { "type": "integer", "description": "Frequency at which the subscriber will receive shipments when subscribed to this plan." }, "interval_unit": { "type": "string", "description": "The unit applied to charge_interval_frequency and order_interval_frequency .", "enum": [ "day", "week", "month" ] }, "pricing_progression": { "type": "array", "items": { "type": "object", "properties": { "recurring_discount_after_cycle": { "type": "integer", "description": "The number of cycles after which this recurring discount should be applied. The checkout order is cycle 1. The first recurring order is cycle 2." }, "recurring_discount_amount": { "type": "string", "description": "The discount amount applied to the product price after the specified number of cycles." }, "recurring_discount_type": { "type": "string", "description": "Used in combination with discount amount to determine the discount applied on a product price after the specified number of cycles. percentage applies the discount amount as a percent off the price; fixed_amount applies it as a flat amount in the store's currency.", "enum": [ "percentage", "fixed_amount" ] } } }, "description": "Used to configure a plan with dynamic pricing. For regular subscription plans, this is field is null. For dynamically priced plans, this field is an array of one item." } }, "description": "An object containing the various subscription preferences associated with this plan." }, "title": { "type": "string", "description": "The title of the plan." }, "translations": { "type": "array", "items": { "type": "object", "properties": { "language": { "type": "string", "description": "The language code of the translation, for example fr ." }, "title": { "type": "string", "description": "The title of the Plan in that language." } } }, "description": "An array of translated titles for the Plan ." }, "type": { "type": "string", "description": "The type of the plan. Products with a prepaid plan cannot have plans of other types.", "enum": [ "subscription", "prepaid", "prepaid_v2", "onetime", "membership_subscription" ] } }, "required": [ "title", "type" ] }, "description": "An array of plans to be created." } }, "required": [ "plans" ] }, "example": { "plans": [ { "discount_amount": "10", "discount_type": "percentage", "sort_order": 1, "title": "Concert T-Shirt", "type": "subscription", "subscription_preferences": { "charge_interval_frequency": 30, "expire_after_specific_number_of_charges": 6, "interval_unit": "day", "order_day_of_month": 1, "order_interval_frequency": 30 } }, { "discount_amount": "10", "discount_type": "percentage", "sort_order": 2, "title": "Concert T-Shirt", "type": "subscription", "subscription_preferences": { "charge_interval_frequency": 60, "expire_after_specific_number_of_charges": 6, "interval_unit": "day", "order_day_of_month": 1, "order_interval_frequency": 60 } } ] } } } }, "x-recharge-scopes": [ "write_plans" ] }, "put": { "operationId": "plans_bulk_update", "summary": "Bulk update plans", "description": "Bulk update existing plans. There is a limit of 20 plans per request.", "tags": [ "Plans" ], "parameters": [ { "name": "external_product_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "plans": [ { "id": 88237, "channel_settings": { "api": { "display": true }, "checkout_page": { "display": true }, "customer_portal": { "display": true }, "merchant_portal": { "display": true } }, "created_at": "2021-07-27T19:07:34+00:00", "discount_amount": "10", "discount_type": "percentage", "external_product_id": { "ecommerce": "2103271587891" }, "product_quantity": null, "sort_order": 1, "title": "Concert T-Shirt", "translations": [], "type": "subscription", "subscription_preferences": { "charge_interval_frequency": 30, "cutoff_day_of_month": null, "cutoff_day_of_week": null, "expire_after_specific_number_of_charges": 6, "interval_unit": "day", "order_day_of_month": 1, "order_interval_frequency": 30 }, "updated_at": "2021-07-27T19:07:34+00:00" }, { "id": 88238, "channel_settings": { "api": { "display": true }, "checkout_page": { "display": true }, "customer_portal": { "display": true }, "merchant_portal": { "display": true } }, "created_at": "2021-07-27T19:07:34+00:00", "discount_amount": "10", "discount_type": "percentage", "external_product_id": { "ecommerce": "2103271587891" }, "product_quantity": null, "sort_order": 2, "title": "Concert T-Shirt", "translations": [], "type": "subscription", "subscription_preferences": { "charge_interval_frequency": 60, "expire_after_specific_number_of_charges": 6, "interval_unit": "day", "order_day_of_month": 1, "order_interval_frequency": 60 }, "updated_at": "2021-07-27T19:07:34+00:00" } ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "plans": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "The ID of the plan." }, "addon_settings": { "type": "object", "properties": { "expiration": { "type": "object", "properties": { "type": { "type": "string", "description": "How the expiration is expressed.", "enum": [ "relative", "absolute" ] }, "value": { "type": "object", "description": "The 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." } }, "description": "An 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." }, "parent_external_variant_ids": { "type": "array", "items": {}, "description": "An 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." } }, "description": "An 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." }, "channel_settings": { "type": "object", "properties": { "api": { "type": "object", "properties": { "display": { "type": "boolean", "description": "A boolean to indicate if the plan may be used in the associated channel (defaults to true for all channels).", "default": true } }, "description": "An object containing api channel settings." }, "customer_portal": { "type": "object", "properties": { "display": { "type": "boolean", "description": "A boolean to indicate if the plan may be used in the associated channel (defaults to true for all channels).", "default": true } }, "description": "An object containing customer portal channel settings." }, "merchant_portal": { "type": "object", "properties": { "display": { "type": "boolean", "description": "A boolean to indicate if the plan may be used in the associated channel (defaults to true for all channels).", "default": true } }, "description": "An object containing merchant portal channel settings." }, "checkout_page": { "type": "object", "properties": { "display": { "type": "boolean", "description": "A boolean to indicate if the plan may be used in the associated channel (defaults to true for all channels).", "default": true } }, "description": "An object containing checkout channel settings." } }, "description": "An object containing the availability of the plan through various supported channels." }, "discount_amount": { "type": "string", "description": "The discount amount applied to the product price when purchased through this plan." }, "discount_type": { "type": "string", "description": "Used in combination with discount amount to determine the discount applied on a product price when purchased through this plan. percentage applies the discount amount as a percent off the price; fixed_amount applies it as a flat amount in the store's currency.", "enum": [ "percentage", "fixed_amount" ] }, "external_variant_ids": { "type": "array", "items": {}, "description": "An array of variant ids, as they appear in external platforms, that the plan applies to." }, "has_variant_restrictions": { "type": "boolean", "description": "Whether this plan applies only to the variants listed in external_variant_ids . Defaults to false ." }, "product_quantity": { "type": "integer", "description": "The quantity of the product that a subscriber receives when purchasing through this Plan . null when the plan does not set a quantity." }, "sort_order": { "type": "integer", "description": "The number indicating the order which the plan will be in a list of related plans." }, "subscription_preferences": { "type": "object", "properties": { "apply_cutoff_date_to_checkout": { "type": "boolean", "description": "Whether the specified cutoff day should be applied to the initial checkout order" }, "charge_interval_frequency": { "type": "integer", "description": "Frequency at which the subscriber will be charged." }, "cutoff_day_of_month": { "type": "integer", "description": "Day of the month the plan should be charged" }, "cutoff_day_of_week": { "type": "integer", "description": "Day of the month the plan should be charged" }, "expire_after_specific_number_of_charges": { "type": "integer", "description": "A maximum number of charges on which the subscription should appear before automatic cancellation." }, "order_day_of_month": { "type": "integer", "description": "Day of the month an order should be generated when the customer is subscribed." }, "order_day_of_week": { "type": "integer", "description": "Day of the week an order should be generated when the customer is subscribed." }, "order_interval_frequency": { "type": "integer", "description": "Frequency at which the subscriber will receive shipments when subscribed to this plan." }, "interval_unit": { "type": "string", "description": "The unit applied to charge_interval_frequency and order_interval_frequency .", "enum": [ "day", "week", "month" ] }, "pricing_progression": { "type": "array", "items": { "type": "object", "properties": { "recurring_discount_after_cycle": { "type": "integer", "description": "The number of cycles after which this recurring discount should be applied." }, "recurring_discount_amount": { "type": "number", "description": "The discount amount applied to the product price after the specified number of cycles." }, "recurring_discount_type": { "type": "string", "description": "Used in combination with the recurring discount amount to determine the discount applied after the specified number of cycles.", "enum": [ "percentage", "fixed_amount" ] } } }, "description": "Used to configure a plan with dynamic pricing. Only the first item of the array is used." } }, "description": "An object containing the various subscription preferences associated with this plan." }, "title": { "type": "string", "description": "The title of the plan." }, "translations": { "type": "array", "items": { "type": "object", "properties": { "language": { "type": "string", "description": "The language code of the translation, for example fr ." }, "title": { "type": "string", "description": "The title of the Plan in that language." } } }, "description": "An array of translated titles for the Plan ." } }, "required": [ "id" ] }, "description": "An array of plans to be updated. Must provide ID for each plan." } }, "required": [ "plans" ] }, "example": { "plans": [ { "id": 88237, "title": "Updated T-Shirt" }, { "id": 88238, "title": "Updated T-Shirt" } ] } } } }, "x-recharge-scopes": [ "write_plans" ] }, "delete": { "operationId": "plans_bulk_delete", "summary": "Bulk delete plans", "description": "Bulk delete existing plans. There is a limit of 20 plans per request.", "tags": [ "Plans" ], "parameters": [ { "name": "external_product_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Content Deleted: The server has successfully fulfilled the request and deleted the desired object and there is no content to send in the response body.", "content": { "application/json": { "example": {} } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "plans": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "The ID of the plan." } }, "required": [ "id" ] }, "description": "An array of plans to be deleted. Must provide ID for each plan." } }, "required": [ "plans" ] }, "example": { "plans": [ { "id": 88237 }, { "id": 88238 } ] } } } }, "x-recharge-scopes": [ "write_plans" ] } }, "/plans/charge_frequencies": { "get": { "operationId": "plans_charge_frequencies", "summary": "List plan charge frequencies", "description": "Returns the distinct charge frequencies used by the store's active subscription plans. Each item has the charge_interval_frequency , the interval_unit and a normalized_frequency_key that joins the two, for example 30_day .", "tags": [ "Plans" ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "data": [ { "charge_interval_frequency": 30, "interval_unit": "day", "normalized_frequency_key": "30_day" }, { "charge_interval_frequency": 1, "interval_unit": "month", "normalized_frequency_key": "1_month" } ] } } } } }, "x-recharge-scopes": [ "read_plans" ] } }, "/products": { "post": { "operationId": "products_create", "summary": "Create a product", "description": "Create a new product in your Recharge Product Catalog. After adding the record, subscription preferences may be added using the Products page of Recharge Admin Portal or with the Plans resource.", "tags": [ "Products" ], "responses": { "202": { "description": "successful response", "content": { "application/json": { "example": { "product": { "brand": "Recharge", "description": "A cotton shirt with the Recharge logo", "external_created_at": "2021-01-01T00:00:00+00:00", "external_product_id": "10", "external_updated_at": "2021-01-01T00:00:00+00:00", "images": [ { "large": "https:...", "medium": "https:...", "original": "https:...", "small": "https:...", "sort_order": 2 } ], "options": [ { "name": "Size", "position": 0, "values": [ { "label": "small", "position": 0 }, { "label": "medium", "position": 1 }, { "label": "large", "position": 2 } ] } ], "published_at": "2021-01-01T00:00:00+00:00", "requires_shipping": true, "title": "Recharge Logo Shirt", "variants": [ { "dimensions": { "weight": 1234.5, "weight_unit": "lb" }, "external_variant_id": "9", "image": { "large": "https:...", "medium": "https:...", "original": "https:...", "small": "https:..." }, "option_values": [ { "label": "small" } ], "prices": { "compare_at_price": "14.22", "unit_price": "12.22" }, "sku": "CLO123", "tax_code": "CLOTHING", "taxable": true, "title": "Recharge Logo Shirt - Small", "requires_shipping": true } ], "vendor": "Recharge Apparel Store" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "description": "The description of the product." }, "external_product_id": { "type": "string", "description": "Unique numeric identifier of the product record in Recharge. The primary id of the record." }, "brand": { "type": "string", "description": "The brand name of the product." }, "images": { "type": "array", "items": { "type": "object", "properties": { "large": { "type": "string", "description": "The url where a large image file is located." }, "medium": { "type": "string", "description": "The url where a medium image file is located." }, "small": { "type": "string", "description": "The url where a small image file is located." }, "original": { "type": "string", "description": "The url of the original sized product image." }, "sort_order": { "type": "integer", "description": "The sort order in which the x image from the array should appear when displayed." } } }, "description": "An array of urls for various sizes of image files." }, "options": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the option, such as size, color, etc." }, "position": { "type": "integer", "description": "The position in which the x option from the array should appear when displayed." }, "values": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "The label of the option value. For example, if the option name is size, this value may be small, medium, large, etc." }, "position": { "type": "integer", "description": "The position in which the y option value from the array should appear when displayed." } }, "required": [ "label", "position" ] }, "description": "An array of values for the x option in the options array." } }, "required": [ "name", "position", "values" ] }, "description": "An array of options for the product record, such as size, color, etc." }, "published_at": { "type": "string", "format": "date-time", "description": "The date and time at which the product became available for purchase. To make the product available, this should be set in the past." }, "requires_shipping": { "type": "boolean", "description": "Indicator of shipping requirement. If true the product associated to the variant needs to be shipped." }, "title": { "type": "string", "description": "The title of the product." }, "variants": { "type": "array", "items": { "type": "object", "properties": { "dimensions": { "type": "object", "properties": { "weight": { "type": "number", "description": "The weight of the product in the weight unit configured for your store." } }, "required": [ "weight" ], "description": "A container of variant dimensions." }, "external_variant_id": { "type": "string", "description": "The variant id in your PIM. The primary key for the variant." }, "image": { "type": "object", "properties": { "large": { "type": "string", "description": "The url where a large image file is located." }, "medium": { "type": "string", "description": "The url where a medium image file is located." }, "small": { "type": "string", "description": "The url where a small image file is located." }, "original": { "type": "string", "description": "The url of the original sized product image." } }, "description": "An object containing image urls for the variant." }, "option_values": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "The label of the option value. Maps to a value specified in the product options list" } }, "required": [ "label" ] }, "description": "An array of option values, linking the variant to the options listed at the product level." }, "prices": { "type": "object", "properties": { "compare_at_price": { "type": "string", "description": "The compare-at price for the variant." }, "unit_price": { "type": "string", "description": "The unit price for the variant." }, "prices": { "type": "object", "properties": { "presentment_prices": { "type": "object", "properties": { "currency": { "type": "string", "description": "The three-letter currency code of the presentment price." }, "unit_price_currency": { "type": "string", "description": "The unit price of the variant in the presentment currency." }, "discounted_price_currency": { "type": "string", "description": "The discounted price of the variant in the presentment currency." } }, "description": "An object containing the price of the variant in a presentment currency. When sent, currency , unit_price_currency and discounted_price_currency are all required." } }, "description": "An object containing the prices of the variant in other currencies." } }, "required": [ "unit_price" ], "description": "An object containing prices for the variant." }, "requires_shipping": { "type": "boolean", "description": "Indicator of shipping requirement. If true the product associated to the variant needs to be shipped." }, "sku": { "type": "string", "description": "The stock keeping unit of the variant." }, "tax_code": { "type": "string", "description": "The tax code of the variant. This value will be used when calculating tax with a third party tax service." }, "taxable": { "type": "boolean", "description": "A boolean indicator of the variant’s taxability." }, "title": { "type": "string", "description": "The title of the variant." } }, "required": [ "dimensions", "external_variant_id", "option_values", "prices", "taxable" ] }, "description": "An array of variants of the product." }, "vendor": { "type": "string", "description": "The vendor of the product." } }, "required": [ "external_product_id", "options", "title", "variants", "vendor" ] }, "example": { "external_product_id": "10", "brand": "Recharge", "description": "A cotton shirt with the Recharge logo", "images": [ { "small": "https:...", "medium": "https:...", "large": "https:...", "original": "https:...", "sort_order": 2 } ], "options": [ { "name": "Size", "position": 0, "values": [ { "label": "small", "position": 0 }, { "label": "medium", "position": 1 }, { "label": "large", "position": 2 } ] } ], "published_at": "2021-01-01:00:00+00:00", "requires_shipping": true, "title": "Recharge Logo Shirt", "variants": [ { "external_variant_id": "9", "dimensions": { "weight": 1234.5 }, "image": { "small": "https:...", "medium": "https:...", "large": "https:...", "original": "https:..." }, "option_values": [ { "label": "small" } ], "sku": "CLO123", "title": "Recharge Logo Shirt - Small", "taxable": true, "tax_code": "CLOTHING", "prices": { "compare_at_price": "14.22", "unit_price": "12.22" } } ], "vendor": "Recharge Apparel Store" } } } }, "x-recharge-scopes": [ "write_products" ] }, "get": { "operationId": "products_list", "summary": "List products", "description": "List products from store’s product catalog.", "tags": [ "Products" ], "parameters": [ { "name": "external_product_ids", "in": "query", "required": false, "description": "Filter products by external product ids.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "The number of results to return. Defaults to 50; the maximum is 250.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The 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 .", "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "next_cursor": null, "previous_cursor": null, "products": [ { "brand": "Recharge", "description": "A cotton shirt with the Recharge logo", "external_created_at": null, "external_product_id": "10", "external_updated_at": "2021-07-21T17:25:46+00:00", "images": [ { "large": "https:...", "medium": "https:...", "original": "https:...", "small": "https:...", "sort_order": 2 } ], "options": [ { "name": "Size", "position": 0, "values": [ { "label": "small", "position": 0 }, { "label": "medium", "position": 1 }, { "label": "large", "position": 2 } ] } ], "published_at": "2021-01-01T00:00:00+00:00", "requires_shipping": true, "title": "Recharge Logo Shirt", "variants": [ { "dimensions": { "weight": 1234.5, "weight_unit": "lb" }, "external_variant_id": "101", "image": { "large": "https:...", "medium": "https:...", "original": "https:...", "small": "https:..." }, "option_values": [ { "label": "small" } ], "prices": { "compare_at_price": "14.22", "unit_price": "12.22" }, "sku": "CLO123", "tax_code": "CLOTHING", "taxable": true, "title": "Small Recharge Logo Shirt", "requires_shipping": true }, { "dimensions": { "weight": 1234.5, "weight_unit": "lb" }, "external_variant_id": "102", "image": { "large": "https:...", "medium": "https:...", "original": "https:...", "small": "https:..." }, "option_values": [ { "label": "medium" } ], "prices": { "compare_at_price": "14.22", "unit_price": "12.22" }, "sku": "CLO124", "tax_code": "CLOTHING", "taxable": true, "title": "Medium Recharge Logo Shirt", "requires_shipping": true } ], "vendor": "Recharge Apparel Store" } ] } } } } }, "x-recharge-scopes": [ "read_products" ] } }, "/products/{external_product_id}": { "get": { "operationId": "products_retrieve", "summary": "Retrieve a product", "description": "Retrieves a Product from store’s product catalog using the external_product_id as lookup id.", "tags": [ "Products" ], "parameters": [ { "name": "external_product_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "product": { "brand": "Recharge", "description": "A cotton shirt with the Recharge logo", "external_created_at": "2021-01-01T00:00:00+00:00", "external_product_id": "10", "external_updated_at": "2021-01-01T00:00:00+00:00", "images": [ { "large": "https:...", "medium": "https:...", "original": "https:...", "small": "https:...", "sort_order": 2 } ], "options": [ { "name": "Size", "position": 0, "values": [ { "label": "small", "position": 0 }, { "label": "medium", "position": 1 }, { "label": "large", "position": 2 } ] } ], "published_at": "2021-01-01T00:00:00+00:00", "requires_shipping": true, "title": "Recharge Logo Shirt", "variants": [ { "dimensions": { "weight": 1234.5, "weight_unit": "lb" }, "external_variant_id": "9", "image": { "large": "https:...", "medium": "https:...", "original": "https:...", "small": "https:..." }, "option_values": [ { "label": "small" } ], "prices": { "compare_at_price": "14.22", "unit_price": "12.22" }, "sku": "CLO123", "tax_code": "CLOTHING", "taxable": true, "title": "Recharge Logo Shirt - Small", "requires_shipping": true } ], "vendor": "Recharge Apparel Store" } } } } } }, "x-recharge-scopes": [ "read_products" ] }, "put": { "operationId": "products_update", "summary": "Update a product", "description": "Update an existing product.", "tags": [ "Products" ], "parameters": [ { "name": "external_product_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "product": { "brand": "Recharge", "description": "A cotton shirt with the Recharge logo", "external_created_at": "2021-01-01T00:00:00+00:00", "external_product_id": "10", "external_updated_at": "2021-01-01T00:00:00+00:00", "images": [ { "large": "https:...", "medium": "https:...", "original": "https:...", "small": "https:...", "sort_order": 2 } ], "options": [ { "name": "Size", "position": 0, "values": [ { "label": "small", "position": 0 }, { "label": "medium", "position": 1 }, { "label": "large", "position": 2 } ] } ], "published_at": "2021-01-01T00:00:00+00:00", "requires_shipping": true, "title": "Recharge Logo Shirt", "variants": [ { "dimensions": { "weight": 1234.5, "weight_unit": "lb" }, "external_variant_id": "9", "image": { "large": "https:...", "medium": "https:...", "original": "https:...", "small": "https:..." }, "option_values": [ { "label": "small" } ], "prices": { "compare_at_price": "14.22", "unit_price": "12.22" }, "sku": "CLO123", "tax_code": "CLOTHING", "taxable": true, "title": "Recharge Logo Shirt - Small", "requires_shipping": true } ], "vendor": "Recharge Apparel Store" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "brand": { "type": "string", "description": "The brand name of the product." }, "description": { "type": "string", "description": "The description of the product." }, "images": { "type": "array", "items": { "type": "object", "properties": { "large": { "type": "string", "description": "The url where a large image file is located." }, "medium": { "type": "string", "description": "The url where a medium image file is located." }, "small": { "type": "string", "description": "The url where a small image file is located." }, "original": { "type": "string", "description": "The url of the original sized product image." }, "sort_order": { "type": "integer", "description": "The sort order in which the x image from the array should appear when displayed." } } }, "description": "An array of urls for various sizes of image files." }, "options": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the option, such as size, color, etc." }, "position": { "type": "integer", "description": "The position in which the x option from the array should appear when displayed." }, "values": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "The label of the option value. For example, if the option name is size, this value may be small, medium, large, etc." }, "position": { "type": "integer", "description": "The position in which the y option value from the array should appear when displayed." } }, "required": [ "label", "position" ] }, "description": "An array of values for the x option in the options array." } }, "required": [ "name", "position", "values" ] }, "description": "An array of options for the product record, such as size, color, etc." }, "published_at": { "type": "string", "format": "date-time", "description": "The datetime at which the product became available for purchase. To make the product available, this should be set in the past." }, "requires_shipping": { "type": "boolean", "description": "Indicator of shipping requirement. If true the product associated to the variant needs to be shipped." }, "title": { "type": "string", "description": "The title of the product." }, "variants": { "type": "array", "items": { "type": "object", "properties": { "dimensions": { "type": "object", "properties": { "weight": { "type": "number", "description": "The weight of the product in the weight unit configured for your store." } }, "description": "A container of variant dimensions." }, "external_variant_id": { "type": "string", "description": "The variant id in your PIM. The primary key for the variant." }, "image": { "type": "object", "properties": { "large": { "type": "string", "description": "The url where a large image file is located." }, "medium": { "type": "string", "description": "The url where a medium image file is located." }, "small": { "type": "string", "description": "The url where a small image file is located." }, "original": { "type": "string", "description": "The url of the original sized product image." } }, "description": "An object containing image urls for the variant." }, "option_values": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "The label of the option value. Maps to a value specified in the product options list" } }, "required": [ "label" ] }, "description": "An array of option values, linking the variant to the options listed at the product level." }, "prices": { "type": "object", "properties": { "compare_at_price": { "type": "string", "description": "The compare-at price for the variant." }, "unit_price": { "type": "string", "description": "The unit price for the variant." }, "prices": { "type": "object", "properties": { "presentment_prices": { "type": "object", "properties": { "currency": { "type": "string", "description": "The three-letter currency code of the presentment price." }, "unit_price_currency": { "type": "string", "description": "The unit price of the variant in the presentment currency." }, "discounted_price_currency": { "type": "string", "description": "The discounted price of the variant in the presentment currency." } }, "description": "An object containing the price of the variant in a presentment currency. When sent, currency , unit_price_currency and discounted_price_currency are all required." } }, "description": "An object containing the prices of the variant in other currencies." } }, "required": [ "unit_price" ], "description": "An object containing prices for the variant." }, "requires_shipping": { "type": "boolean", "description": "Indicator of shipping requirement. If true the product associated to the variant needs to be shipped." }, "sku": { "type": "string", "description": "The stock keeping unit of the variant." }, "tax_code": { "type": "string", "description": "The tax code of the variant. This value will be used when calculating tax with a third party tax service." }, "taxable": { "type": "boolean", "description": "A boolean indicator of the variant’s taxability." }, "title": { "type": "string", "description": "The title of the variant." } }, "required": [ "dimensions", "option_values", "prices", "taxable" ] }, "description": "An array of variants of the product." }, "vendor": { "type": "string", "description": "The vendor of the product." } } }, "example": { "brand": "Recharge", "variants": [ { "external_variant_id": "101", "dimensions": { "weight": 1234.5 }, "image": { "small": "https:...", "medium": "https:...", "large": "https:...", "original": "https:..." }, "option_values": [ { "label": "small" } ], "sku": "CLO123", "title": "Small Recharge Logo Shirt", "taxable": true, "tax_code": "CLOTHING", "prices": { "compare_at_price": "14.22", "unit_price": "12.22" } }, { "external_variant_id": "102", "dimensions": { "weight": 1234.5 }, "image": { "small": "https:...", "medium": "https:...", "large": "https:...", "original": "https:..." }, "option_values": [ { "label": "medium" } ], "sku": "CLO124", "title": "Medium Recharge Logo Shirt", "taxable": true, "tax_code": "CLOTHING", "prices": { "compare_at_price": "14.22", "unit_price": "12.22" } } ] } } } }, "x-recharge-scopes": [ "write_products" ] }, "delete": { "operationId": "products_delete", "summary": "Delete a product", "description": "Delete product from Store .", "tags": [ "Products" ], "parameters": [ { "name": "external_product_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "successful response", "content": { "application/json": { "example": {} } } } }, "x-recharge-scopes": [ "write_products" ] } }, "/retention_strategies": { "get": { "operationId": "retention_strategies_list", "summary": "List retention strategies", "description": "Returns a list of the store's Retention strategies . By default only strategies without an origin are returned.", "tags": [ "Retention strategies" ], "parameters": [ { "name": "cancellation_flow_type", "in": "query", "required": false, "description": "Return the retention strategies offered for the given kind of cancellation.", "schema": { "type": "string", "enum": [ "subscription", "membership" ] } }, { "name": "origin", "in": "query", "required": false, "description": "Pass active_churn_flow to also return the retention strategies that belong to a cancellation flow.", "schema": { "type": "string", "enum": [ "active_churn_flow" ] } }, { "name": "include", "in": "query", "required": false, "description": "Pass discount to return the Discount matching discount_code under include . Also requires the read_discounts scope.", "schema": { "type": "string", "enum": [ "discount" ] } }, { "name": "sort_by", "in": "query", "required": false, "description": "Sort the results by the given field and direction. Default is id-desc .", "schema": { "type": "string", "enum": [ "id-asc", "id-desc" ] } }, { "name": "limit", "in": "query", "required": false, "description": "The amount of results. Default is 50 while the maximum is 250.", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "The page of results to show. Default is 1. Use cursor instead where possible.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor or previous_cursor value returned by a previous list request. When a cursor is passed, only limit can be passed with it.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "retention_strategies": [ { "id": 9042, "cancellation_flow_type": "subscription", "created_at": "2026-08-03T18:22:10+00:00", "discount_code": "STAY10", "incentive_type": "discount", "origin": null, "prevention_text": "Stay with us and save 10% on your next order.", "reason": "This is too expensive", "updated_at": "2026-08-03T18:22:10+00:00" }, { "id": 9041, "cancellation_flow_type": "subscription", "created_at": "2026-08-03T18:20:47+00:00", "discount_code": null, "incentive_type": "skip_charge", "origin": null, "prevention_text": "Need a break? Skip your next order instead.", "reason": "I have too much product", "updated_at": "2026-08-03T18:20:47+00:00" } ], "next_cursor": null, "previous_cursor": null } } } } }, "x-recharge-scopes": [ "read_subscriptions" ] }, "post": { "operationId": "retention_strategies_create", "summary": "Create a retention strategy", "description": "Creates a Retention strategy : a cancellation reason with the message, and optionally the incentive, shown to a customer who selects it.", "tags": [ "Retention strategies" ], "responses": { "201": { "description": "OK: The request was successful, created a new resource, and resource created is in the body.", "content": { "application/json": { "example": { "retention_strategy": { "id": 9042, "cancellation_flow_type": "subscription", "created_at": "2026-08-03T18:22:10+00:00", "discount_code": "STAY10", "incentive_type": "discount", "origin": null, "prevention_text": "Stay with us and save 10% on your next order.", "reason": "This is too expensive", "updated_at": "2026-08-03T18:22:10+00:00" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "The cancellation reason shown to the customer. Maximum 255 characters." }, "prevention_text": { "type": "string", "description": "The message shown to the customer after selecting the cancellation reason. Maximum 255 characters." }, "incentive_type": { "type": "string", "description": "The incentive offered to the customer to prevent the cancellation. Strategies with a cancellation_flow_type of membership only support discount , swap_product or no incentive.", "enum": [ "discount", "skip_charge", "delay_subscription", "swap_product" ] }, "discount_code": { "type": "string", "description": "The code of an existing, enabled Discount to offer. Required when incentive_type is discount , and ignored for any other incentive_type ." }, "cancellation_flow_type": { "type": "string", "description": "The kind of cancellation the Retention strategy is offered for. Defaults to subscription .", "enum": [ "subscription", "membership" ] }, "origin": { "type": "string", "description": "Pass active_churn_flow to attach the Retention strategy to a cancellation flow.", "enum": [ "active_churn_flow" ] } }, "required": [ "reason", "prevention_text" ] } } } }, "x-recharge-scopes": [ "write_retention_strategies" ] } }, "/retention_strategies/{id}": { "get": { "operationId": "retention_strategies_retrieve", "summary": "Retrieve a retention strategy", "description": "Returns a single Retention strategy by its id .", "tags": [ "Retention strategies" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "Pass discount to return the Discount matching discount_code under include . Also requires the read_discounts scope.", "schema": { "type": "string", "enum": [ "discount" ] } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "retention_strategy": { "id": 9042, "cancellation_flow_type": "subscription", "created_at": "2026-08-03T18:22:10+00:00", "discount_code": "STAY10", "incentive_type": "discount", "origin": null, "prevention_text": "Stay with us and save 10% on your next order.", "reason": "This is too expensive", "updated_at": "2026-08-03T18:22:10+00:00" } } } } } }, "x-recharge-scopes": [ "read_subscriptions" ] }, "put": { "operationId": "retention_strategies_update", "summary": "Update a retention strategy", "description": "Updates a Retention strategy . Only the attributes passed in the request are changed; at least one attribute is required.", "tags": [ "Retention strategies" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "retention_strategy": { "id": 9042, "cancellation_flow_type": "subscription", "created_at": "2026-08-03T18:22:10+00:00", "discount_code": "STAY10", "incentive_type": "discount", "origin": null, "prevention_text": "Stay with us and save 10% on your next order.", "reason": "This is too expensive", "updated_at": "2026-08-03T18:22:10+00:00" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "The cancellation reason shown to the customer. Maximum 255 characters." }, "prevention_text": { "type": "string", "description": "The message shown to the customer after selecting the cancellation reason. Maximum 255 characters." }, "incentive_type": { "type": "string", "description": "The incentive offered to the customer to prevent the cancellation. Strategies with a cancellation_flow_type of membership only support discount , swap_product or no incentive.", "enum": [ "discount", "skip_charge", "delay_subscription", "swap_product" ] }, "discount_code": { "type": "string", "description": "The code of an existing, enabled Discount to offer. Required when incentive_type is discount , and ignored for any other incentive_type ." }, "cancellation_flow_type": { "type": "string", "description": "The kind of cancellation the Retention strategy is offered for. Defaults to subscription .", "enum": [ "subscription", "membership" ] }, "origin": { "type": "string", "description": "Pass active_churn_flow to attach the Retention strategy to a cancellation flow.", "enum": [ "active_churn_flow" ] } } } } } }, "x-recharge-scopes": [ "write_retention_strategies" ] }, "delete": { "operationId": "retention_strategies_delete", "summary": "Delete a retention strategy", "description": "Permanently deletes a Retention strategy .", "tags": [ "Retention strategies" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content: The request was successful and there is no content to return." } }, "x-recharge-scopes": [ "write_retention_strategies" ] } }, "/reward_credits": { "get": { "operationId": "reward_credits_list", "summary": "List reward credits", "description": "Returns a list of the store's Reward credits . Results are sorted by id in descending order unless sort_by is passed.", "tags": [ "Reward credits" ], "parameters": [ { "name": "customer_id", "in": "query", "required": false, "description": "Return the reward credits of the given Customer .", "schema": { "type": "integer" } }, { "name": "customer_ids", "in": "query", "required": false, "description": "Return the reward credits of any of the given customers. If passing multiple values, must be comma separated.", "schema": { "type": "string" } }, { "name": "ids", "in": "query", "required": false, "description": "Filter reward credits by id . If passing multiple values, must be comma separated.", "schema": { "type": "string" } }, { "name": "expires_at_min", "in": "query", "required": false, "description": "Return the reward credits that expire on or after the given date.", "schema": { "type": "string", "format": "date-time" } }, { "name": "expires_at_max", "in": "query", "required": false, "description": "Return the reward credits that expire on or before the given date.", "schema": { "type": "string", "format": "date-time" } }, { "name": "sort_by", "in": "query", "required": false, "description": "Sort the results by the given field and direction.", "schema": { "type": "string", "enum": [ "id-asc", "id-desc", "expires_at-asc", "expires_at-desc" ] } }, { "name": "limit", "in": "query", "required": false, "description": "The amount of results. Default is 50 while the maximum is 250.", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "The page of results to show. Default is 1. Use cursor instead where possible.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor or previous_cursor value returned by a previous list request. When a cursor is passed, only limit can be passed with it.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "reward_credits": [ { "id": 30514, "customer_id": 71542, "available_balance": "7.50", "created_at": "2026-10-01T13:15:42+00:00", "currency_code": "USD", "expires_at": "2027-10-01T23:59:59+00:00", "initial_value": "10.00", "name": "Loyalty reward", "updated_at": "2026-10-19T09:03:11+00:00" } ], "next_cursor": null, "previous_cursor": null } } } } }, "x-recharge-scopes": [ "read_reward_credits" ] }, "post": { "operationId": "reward_credits_create", "summary": "Create a reward credit", "description": "Issues a Reward credit of the given value to a Customer . The credit can then be used by the customer to pay for their charges.", "tags": [ "Reward credits" ], "responses": { "201": { "description": "OK: The request was successful, created a new resource, and resource created is in the body.", "content": { "application/json": { "example": { "reward_credit": { "id": 30514, "customer_id": 71542, "available_balance": "10.00", "created_at": "2026-10-01T13:15:42+00:00", "currency_code": "USD", "expires_at": "2027-10-01T23:59:59+00:00", "initial_value": "10.00", "name": "Loyalty reward", "updated_at": "2026-10-01T13:15:42+00:00" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "integer", "description": "Unique numeric identifier for the Customer to issue the Reward credit to." }, "initial_value": { "type": "string", "description": "The value of the Reward credit , in the default currency of the store. Must be passed as a string, between 0 and 999999.99 ." }, "name": { "type": "string", "description": "The name of the Reward credit . Maximum 255 characters. Defaults to Reward Credit ." }, "expires_at": { "type": "string", "format": "date-time", "description": "The date and time when the Reward credit expires. When omitted, the expiration date is derived from the store's reward credit expiration settings, or the credit never expires if the store has none." } }, "required": [ "customer_id", "initial_value" ] } } } }, "x-recharge-scopes": [ "write_reward_credits" ] } }, "/reward_credits/{id}": { "get": { "operationId": "reward_credits_retrieve", "summary": "Retrieve a reward credit", "description": "Returns a single Reward credit by its id .", "tags": [ "Reward credits" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "reward_credit": { "id": 30514, "customer_id": 71542, "available_balance": "7.50", "created_at": "2026-10-01T13:15:42+00:00", "currency_code": "USD", "expires_at": "2027-10-01T23:59:59+00:00", "initial_value": "10.00", "name": "Loyalty reward", "updated_at": "2026-10-19T09:03:11+00:00" } } } } } }, "x-recharge-scopes": [ "read_reward_credits" ] } }, "/store": { "get": { "operationId": "store_retrieve", "summary": "Retrieve a store", "description": "Retrieve store details.", "tags": [ "Store" ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "store": { "id": 4797, "allow_customers_to_skip_delivery": 1, "checkout_logo_url": null, "checkout_platform": "recharge", "created_at": "2020-04-22T00:20:52+00:00", "currency": "USD", "customer_portal_base_url": null, "default_api_version": "2021-01", "email": "email@email.com", "enabled_presentment_currencies": [ "USD" ], "enabled_presentment_currencies_symbols": [ { "currency": "USD", "location": "before", "suffix": "", "symbol": "$" } ], "disabled_currencies_historical": [], "external_platform": "custom", "external_platform_domain": "store-id.myshopify.com", "identifier": "store-id", "merchant_portal_base_url": null, "name": "store-name", "platform_domain": "store-id.myshopify.com", "province": "Connecticut", "phone": "5555555555", "storefront_domain": "shop.store-name.com", "subscriptions_enabled": true, "test_mode": false, "timezone": { "iana_name": "America/New_York", "name": "(GMT-05:00) Eastern Time (US & Canada)" }, "updated_at": "2020-04-25T00:20:52+00:00", "weight_unit": "g" } } } } } }, "x-recharge-scopes": [ "read_store", "store_info" ] } }, "/subscriptions": { "post": { "operationId": "subscriptions_create", "summary": "Create a subscription", "description": "", "tags": [ "Subscriptions" ], "parameters": [ { "name": "commit", "in": "query", "required": false, "description": "If 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.", "schema": { "type": "boolean" } } ], "responses": { "201": { "description": "successful response", "content": { "application/json": { "example": { "subscription": { "id": 63898947, "address_id": 48563471, "customer_id": 37657002, "analytics_data": { "utm_params": { "utm_source": "facebook", "utm_medium": "cpc" } }, "cancellation_reason": null, "cancellation_reason_comments": null, "cancelled_at": null, "charge_interval_frequency": 30, "created_at": "2020-02-19T17:40:09+00:00", "expire_after_specific_number_of_charges": null, "external_product_id": { "ecommerce": "4381728735283" }, "external_variant_id": { "ecommerce": "32165284380775" }, "has_queued_charges": true, "is_digital": false, "is_prepaid": false, "is_skippable": true, "is_swappable": false, "max_retries_reached": false, "next_charge_scheduled_at": "2021-12-17", "order_day_of_month": null, "order_day_of_week": null, "order_interval_frequency": 30, "order_interval_unit": "day", "presentment_currency": "USD", "price": "10.00", "product_title": "ABC Shirt", "properties": [ { "name": "Color", "value": "Blue" }, { "name": "Size", "value": "Large" } ], "quantity": 1, "sku": "TOM0001", "sku_override": false, "status": "active", "updated_at": "2020-02-19T17:40:10+00:00", "variant_title": "Blue star" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "address_id": { "type": "integer", "description": "Unique numeric identifier of the customer’s address." }, "analytics_data": { "type": "object", "properties": { "utm_params": { "type": "array", "items": { "type": "object", "properties": { "utm_campaign": { "type": "string", "description": "The UTM campaign." }, "utm_content": { "type": "string", "description": "The UTM content." }, "utm_data_source": { "type": "string", "description": "The source of the campaign parameter. Required for each utm_param object." }, "utm_medium": { "type": "string", "description": "The UTM medium." }, "utm_source": { "type": "string", "description": "The UTM source." }, "utm_term": { "type": "string", "description": "The UTM term." }, "utm_timestamp": { "type": "string", "format": "date-time", "description": "The UTM timestamp. Required for each utm_param object." } } }, "description": "An array containing utm_param objects." } }, "description": "An object used to contain analytics data such as utm parameters." }, "cancellation_reason": { "type": "string", "description": "Reason for cancellation. Can only be set when status is cancelled or expired ." }, "cancelled_at": { "type": "string", "format": "date-time", "description": "The time the subscription was cancelled. Can only be set when status is cancelled or expired . Defaults to the current time when status is cancelled ." }, "charge_interval_frequency": { "type": "integer", "description": "The number of units, specified in order_interval_unit , between each charge." }, "custom_event_attributes": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "The name of the custom attribute." }, "value": { "type": "string", "description": "The value of the custom attribute. Maximum length is 255 characters." } } }, "description": "A 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 ." }, "expire_after_specific_number_of_charges": { "type": "integer", "description": "The number of charges until the subscription expires." }, "next_charge_scheduled_at": { "type": "string", "format": "date", "description": "This will set the first charge date of a new subscription." }, "order_day_of_month": { "type": "integer", "description": "This is populated when order_interval_unit has value “month”. Default value is 0." }, "order_day_of_week": { "type": "integer", "description": "This is populated when order_interval_unit has value “week”." }, "order_interval_frequency": { "type": "integer", "description": "The number of units, specified in order_interval_unit, between each order." }, "order_interval_unit": { "type": "string", "description": "The frequency unit used to determine when a subscription order is created.", "enum": [ "day", "week", "month" ] }, "plan_id": { "type": "integer", "description": "A Recharge Plan id that provides interval information. Automatically fills the following properties from the plan if they were not provided directly: charge_interval_frequency, expire_after_specific_number_of_charges, order_day_of_month, order_day_of_week, order_interval_frequency, order_interval_unit." }, "presentment_currency": { "type": "string", "description": "The 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": { "type": "string", "description": "The price of the product." }, "price_manually_set": { "type": "boolean", "description": "Set to true to indicate that the price in the request was explicitly chosen by the caller instead of being calculated by Recharge." }, "product_title": { "type": "string", "description": "The name of the product." }, "properties": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the property." }, "value": { "type": "string", "description": "The value of the property." } } }, "description": "A list of key/value pairs representing properties of the subscription." }, "quantity": { "type": "integer", "description": "The quantity of the product." }, "external_product_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "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 ." } }, "description": "Unique numeric identifier of the product id." }, "external_variant_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "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 ." } }, "description": "Unique numeric identifier of the product variant id." }, "sku": { "type": "string", "description": "A unique identifier of the item in the fulfillment." }, "sku_override": { "type": "boolean", "description": "When true , the sku stored on the Subscription is used instead of the SKU of the product variant." }, "status": { "type": "string", "description": "Default is set to active .", "enum": [ "active", "cancelled", "expired" ] }, "variant_title": { "type": "string", "description": "The name of the product variant." } }, "required": [ "address_id", "charge_interval_frequency", "next_charge_scheduled_at", "order_interval_frequency", "order_interval_unit", "quantity", "external_variant_id" ] }, "example": { "address_id": 48563471, "charge_interval_frequency": "30", "next_charge_scheduled_at": "2021-12-17", "order_interval_frequency": "30", "order_interval_unit": "day", "properties": [ { "name": "Colour", "value": "Yellow" }, { "name": "Bottle Material", "value": "Glass" } ], "external_variant_id": { "ecommerce": "32165284380775" }, "quantity": 3 } } } }, "x-recharge-scopes": [ "write_subscriptions" ] }, "get": { "operationId": "subscriptions_list", "summary": "List subscriptions", "description": "Returns a list of all your subscriptions. HTTP request examples GET /subscriptions GET /subscriptions?created_at_min=2018-10-10&created_at_max=2019-10-16 GET /subscriptions?customer_id=", "tags": [ "Subscriptions" ], "parameters": [ { "name": "address_id", "in": "query", "required": false, "description": "Return the subscriptions linked to the given address_id .", "schema": { "type": "string" } }, { "name": "address_ids", "in": "query", "required": false, "description": "Return the subscriptions linked to the given address_ids .", "schema": { "type": "string" } }, { "name": "bundles_only", "in": "query", "required": false, "description": "If 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.", "schema": { "type": "boolean" } }, { "name": "created_at_max", "in": "query", "required": false, "description": "Return the subscriptions created before the given date.", "schema": { "type": "string" } }, { "name": "created_at_min", "in": "query", "required": false, "description": "Return the subscriptions created after the given date.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Return either the next or previous page of subscriptions using next_cursor or previous_cursor attributes in the response.", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "required": false, "description": "Return the subscriptions linked to the given Recharge customer id.", "schema": { "type": "string" } }, { "name": "external_customer_id", "in": "query", "required": false, "description": "Return the subscriptions linked to the customer with the given id in the external e-commerce platform.", "schema": { "type": "string" } }, { "name": "external_variant_id", "in": "query", "required": false, "description": "Return the subscriptions linked to the given external_variant_id", "schema": { "type": "string" } }, { "name": "ids", "in": "query", "required": false, "description": "Comma-separated list of subscription_ids to filter", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "A 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.", "schema": { "type": "string", "enum": [ "address", "addons", "bundle_product", "bundle_selections", "charge_activities", "customer", "customer_entitlements", "expires_at", "metafields" ] } }, { "name": "include_onetimes", "in": "query", "required": false, "description": "If 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.", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "description": "The number of results.", "schema": { "type": "string", "default": 50 } }, { "name": "page", "in": "query", "required": false, "description": "The page to show.", "schema": { "type": "string", "deprecated": true, "default": 1 } }, { "name": "sort_by", "in": "query", "required": false, "description": "Sort the results by the given attribute and direction. Defaults to id-desc .", "schema": { "type": "string", "enum": [ "id-asc", "id-desc", "created_at-asc", "created_at-desc", "updated_at-asc", "updated_at-desc" ] } }, { "name": "status", "in": "query", "required": false, "description": "Return the subscriptions with specified status.", "schema": { "type": "string", "enum": [ "active", "cancelled", "expired" ] } }, { "name": "updated_at_max", "in": "query", "required": false, "description": "Return the subscriptions updated before the given date.", "schema": { "type": "string" } }, { "name": "updated_at_min", "in": "query", "required": false, "description": "Return the subscriptions updated after the given date.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "next_cursor": "next_cursor", "previous_cursor": "previous_cursor", "subscriptions": [ { "id": 63898947, "address_id": 42171447, "customer_id": 37657002, "analytics_data": { "utm_params": { "utm_source": "facebook", "utm_medium": "cpc" } }, "cancellation_reason": null, "cancellation_reason_comments": null, "cancelled_at": null, "charge_interval_frequency": 1, "created_at": "2020-02-19T17:40:09+00:00", "expire_after_specific_number_of_charges": 5, "external_product_id": { "ecommerce": "4381728735283" }, "external_variant_id": { "ecommerce": "32165284380775" }, "has_queued_charges": false, "is_digital": false, "is_prepaid": false, "is_skippable": true, "is_swappable": false, "max_retries_reached": false, "next_charge_scheduled_at": "2021-12-17", "order_day_of_month": null, "order_day_of_week": null, "order_interval_frequency": 1, "order_interval_unit": "month", "presentment_currency": "USD", "price": "10.00", "product_title": "ABC Shirt", "properties": [ { "name": "Color", "value": "Blue" }, { "name": "Size", "value": "Large" } ], "quantity": 1, "sku": "TOM0001", "sku_override": false, "status": "active", "updated_at": "2020-02-19T17:40:10+00:00", "variant_title": "Blue star" } ] } } } } }, "x-recharge-scopes": [ "read_subscriptions" ] } }, "/subscriptions/{id}": { "get": { "operationId": "subscriptions_retrieve", "summary": "Retrieve a subscription", "description": "Retrieve a subscription using the Recharge subscription_id .", "tags": [ "Subscriptions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "A 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.", "schema": { "type": "string", "enum": [ "address", "addons", "bundle_product", "bundle_selections", "charge_activities", "customer", "customer_entitlements", "expires_at", "metafields" ] } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "subscription": { "id": 63898947, "address_id": 48563471, "customer_id": 37657002, "analytics_data": { "utm_params": { "utm_source": "facebook", "utm_medium": "cpc" } }, "cancellation_reason": null, "cancellation_reason_comments": null, "cancelled_at": null, "charge_interval_frequency": 30, "created_at": "2020-02-19T17:40:09+00:00", "expire_after_specific_number_of_charges": null, "external_product_id": { "ecommerce": "4381728735283" }, "external_variant_id": { "ecommerce": "32165284380775" }, "has_queued_charges": true, "is_digital": false, "is_prepaid": false, "is_skippable": true, "is_swappable": false, "max_retries_reached": false, "next_charge_scheduled_at": "2021-12-17", "order_day_of_month": null, "order_day_of_week": null, "order_interval_frequency": 30, "order_interval_unit": "day", "presentment_currency": "USD", "price": "10.00", "product_title": "ABC Shirt", "properties": [ { "name": "Color", "value": "Blue" }, { "name": "Size", "value": "Large" } ], "quantity": 1, "sku": "TOM0001", "sku_override": false, "status": "active", "updated_at": "2020-02-19T17:40:10+00:00", "variant_title": "Blue star" } } } } } }, "x-recharge-scopes": [ "read_subscriptions" ] }, "put": { "operationId": "subscriptions_update", "summary": "Update a subscription", "description": "Update an existing subscription.", "tags": [ "Subscriptions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "commit", "in": "query", "required": false, "description": "Controls whether the QUEUED charges linked to the subscription should be regenerated upon subscription update. By default the flag is set to false which will delay charge regeneration 5 seconds. This enables running multiple calls to perform changes and receive responses much faster since the API won’t wait for a charge regeneration to complete. Setting this parameter to true will cause charge regeneration to complete before returning a response.", "schema": { "type": "boolean" } }, { "name": "force_update", "in": "query", "required": false, "description": "If set to True , updates will also be applied to CANCELLED subscriptions. If null or False , only ACTIVE subscriptions will be updated.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "subscription": { "id": 63898947, "address_id": 48563471, "customer_id": 37657002, "analytics_data": { "utm_params": { "utm_source": "facebook", "utm_medium": "cpc" } }, "cancellation_reason": null, "cancellation_reason_comments": null, "cancelled_at": null, "charge_interval_frequency": 30, "created_at": "2020-02-19T17:40:09+00:00", "expire_after_specific_number_of_charges": null, "external_product_id": { "ecommerce": "4381728735283" }, "external_variant_id": { "ecommerce": "32165284380775" }, "has_queued_charges": true, "is_digital": false, "is_prepaid": false, "is_skippable": true, "is_swappable": false, "max_retries_reached": false, "next_charge_scheduled_at": "2021-12-17", "order_day_of_month": null, "order_day_of_week": null, "order_interval_frequency": 30, "order_interval_unit": "day", "presentment_currency": "USD", "price": "10.00", "product_title": "ABC Shirt", "properties": [ { "name": "Color", "value": "Blue" }, { "name": "Size", "value": "Large" } ], "quantity": 1, "sku": "TOM0001", "sku_override": false, "status": "active", "updated_at": "2020-02-19T17:40:10+00:00", "variant_title": "Blue star" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "address_id": { "type": "integer", "description": "Unique 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_data": { "type": "object", "properties": { "utm_params": { "type": "array", "items": { "type": "object", "properties": { "utm_campaign": { "type": "string", "description": "The UTM campaign." }, "utm_content": { "type": "string", "description": "The UTM content." }, "utm_data_source": { "type": "string", "description": "The source of the campaign parameter. Required for each utm_param object." }, "utm_medium": { "type": "string", "description": "The UTM medium." }, "utm_source": { "type": "string", "description": "The UTM source." }, "utm_term": { "type": "string", "description": "The UTM term." }, "utm_timestamp": { "type": "string", "format": "date-time", "description": "The UTM timestamp. Required for each utm_param object." } } }, "description": "An array containing utm_param objects." } }, "description": "An object used to contain analytics data such as utm parameters. The UTM parameters passed are added to the ones already stored on the Subscription ." }, "cancellation_reason": { "type": "string", "description": "Reason for cancellation. Can only be set when status is passed as cancelled or expired in the same request." }, "cancellation_reason_comments": { "type": "string", "description": "Additional 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_at": { "type": "string", "format": "date-time", "description": "The time the subscription was cancelled. Can only be set when status is passed as cancelled or expired in the same request." }, "charge_interval_frequency": { "type": "integer", "description": "The number of units (specified in order_interval_unit) between each charge. Required when updating order_interval_unit. WARNING: This update will remove skipped and manually changed charges." }, "custom_event_attributes": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "The name of the custom attribute." }, "value": { "type": "string", "description": "The value of the custom attribute. Maximum length is 255 characters." } } }, "description": "A 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 ." }, "expire_after_specific_number_of_charges": { "type": "integer", "description": "The number of charges until subscription expires." }, "external_product_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "The product id as it appears in the external e-commerce platform." } }, "description": "An object containing the product id as it appears in external platforms." }, "external_variant_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "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 ." } }, "description": "Unique number identifier of the product variant in your external platform." }, "next_charge_scheduled_at": { "type": "string", "format": "date", "description": "The date of the next charge for the Subscription . It cannot be in the past." }, "order_day_of_month": { "type": "integer", "description": "The day of the month the order is created on. WARNING: this update will remove skips and manually changed charges." }, "order_day_of_week": { "type": "integer", "description": "The day of the week the order is created on. WARNING: this update will remove skips and manually changed charges." }, "order_interval_frequency": { "type": "integer", "description": "The number of units (specified in order_interval_unit) between each order. Required when updating order_interval_unit. WARNING: This update will remove skipped and manually changed charges." }, "order_interval_unit": { "type": "string", "description": "The frequency unit used to determine when a subscription order is created. WARNING: This update will remove skipped and manually changed charges.", "enum": [ "day", "week", "month" ] }, "override": { "type": "boolean", "description": "If 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." }, "plan_id": { "type": "integer", "description": "A Recharge Plan id that provides interval information. Automatically fills the following properties from the plan if they were not provided directly: charge_interval_frequency, expire_after_specific_number_of_charges, order_day_of_month, order_day_of_week, order_interval_frequency, order_interval_unit." }, "presentment_currency": { "type": "string", "description": "The 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": { "type": "string", "description": "The price of the item before discounts, taxes, or shipping has been applied." }, "price_manually_set": { "type": "boolean", "description": "Set to true to indicate that the price in the request was explicitly chosen by the caller instead of being calculated by Recharge." }, "product_title": { "type": "string", "description": "The name of the product." }, "properties": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the property." }, "value": { "type": "string", "description": "The value of the property." } } }, "description": "A list of key/value pairs representing properties of the subscription." }, "quantity": { "type": "integer", "description": "The number of items in the subscription." }, "sku": { "type": "string", "description": "A unique identifier of the item in the fulfillment." }, "sku_override": { "type": "boolean", "description": "Flag is automatically updated to true when SKU is passed on create or update. When sku_override is true , the SKU on the subscription will be used to generate charges and orders. When sku_override is false , Recharge will dynamically fetch the sku from the corresponding external platform variant." }, "status": { "type": "string", "description": "The status of the Subscription . When set to cancelled without cancelled_at , the cancellation time is set to the current time.", "enum": [ "active", "cancelled", "expired" ] }, "use_external_variant_defaults": { "type": "boolean", "description": "Flag instructing to pull the price from the product variant passed." }, "variant_title": { "type": "string", "description": "The name of the product variant." } } }, "example": { "quantity": 4 } } } }, "x-recharge-scopes": [ "write_subscriptions" ] }, "delete": { "operationId": "subscriptions_delete", "summary": "Delete a subscription", "description": "We now have a feature for deleting a subscription.", "tags": [ "Subscriptions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "commit", "in": "query", "required": false, "description": "If 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.", "schema": { "type": "boolean" } } ], "responses": { "204": { "description": "successful response", "content": { "application/json": { "example": {} } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "send_email": { "type": "boolean", "description": "When your store setting indicates that cancellation emails should be sent, this value determines if the email should be sent for the specified subscription cancellation." } } } } } }, "x-recharge-scopes": [ "write_subscriptions" ] } }, "/subscriptions/{id}/set_next_charge_date": { "post": { "operationId": "subscriptions_change_next_charge", "summary": "Change a subscription next charge date", "description": "Update an existing subscription’s next charge date.", "tags": [ "Subscriptions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "commit", "in": "query", "required": false, "description": "If 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.", "schema": { "type": "boolean" } }, { "name": "pause", "in": "query", "required": false, "description": "If true , the date change is also recorded as a pause of the Subscription and the subscription/paused webhook is sent.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "subscription": { "id": 27363808, "address_id": 42171447, "customer_id": 37657002, "analytics_data": { "utm_params": { "utm_source": "facebook", "utm_medium": "cpc" } }, "cancellation_reason": null, "cancellation_reason_comments": null, "cancelled_at": null, "charge_interval_frequency": 1, "created_at": "2020-02-19T17:40:09+00:00", "expire_after_specific_number_of_charges": null, "external_product_id": { "ecommerce": "4381728735283" }, "external_variant_id": { "ecommerce": "32309455192167" }, "has_queued_charges": true, "is_digital": false, "is_prepaid": false, "is_skippable": true, "is_swappable": false, "max_retries_reached": false, "next_charge_scheduled_at": "2021-08-05", "order_day_of_month": null, "order_day_of_week": null, "order_interval_frequency": 1, "order_interval_unit": "month", "presentment_currency": "USD", "price": "10.00", "product_title": "ABC Shirt", "properties": [ { "name": "Color", "value": "Blue" }, { "name": "Size", "value": "Large" } ], "quantity": 1, "sku": "TOM0001", "sku_override": false, "status": "active", "updated_at": "2020-02-19T17:40:10+00:00", "variant_title": "Blue star" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "The next charge date desired." }, "custom_event_attributes": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "The name of the custom attribute." }, "value": { "type": "string", "description": "The value of the custom attribute. Maximum length is 255 characters." } } }, "description": "A 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 ." } }, "required": [ "date" ] }, "example": { "date": "2021-08-05" } } } }, "x-recharge-scopes": [ "write_subscriptions" ] } }, "/subscriptions/{id}/change_address": { "post": { "operationId": "subscriptions_change_address", "summary": "Change a subscription address", "description": "Update an existing subscription’s address.", "tags": [ "Subscriptions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "subscription": { "id": 27363808, "address_id": 42171447, "customer_id": 37657002, "analytics_data": { "utm_params": { "utm_source": "facebook", "utm_medium": "cpc" } }, "cancellation_reason": null, "cancellation_reason_comments": null, "cancelled_at": null, "charge_interval_frequency": 1, "created_at": "2020-02-19T17:40:09+00:00", "expire_after_specific_number_of_charges": null, "external_product_id": { "ecommerce": "4381728735283" }, "external_variant_id": { "ecommerce": "32309455192167" }, "has_queued_charges": true, "is_digital": false, "is_prepaid": false, "is_skippable": true, "is_swappable": false, "max_retries_reached": false, "next_charge_scheduled_at": "2021-08-05", "order_day_of_month": null, "order_day_of_week": null, "order_interval_frequency": 1, "order_interval_unit": "month", "presentment_currency": "USD", "price": "10.00", "product_title": "ABC Shirt", "properties": [ { "name": "Color", "value": "Blue" }, { "name": "Size", "value": "Large" } ], "quantity": 1, "sku": "TOM0001", "sku_override": false, "status": "active", "updated_at": "2020-02-19T17:40:10+00:00", "variant_title": "Blue star" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "address_id": { "type": "integer", "description": "Unique id of the address that need to be associated with subscription." }, "next_charge_scheduled_at": { "type": "string", "description": "The next charge date desired." } }, "required": [ "address_id" ] }, "example": { "address_id": 23397943 } } } }, "x-recharge-scopes": [ "write_subscriptions" ] } }, "/subscriptions/{id}/cancel": { "post": { "operationId": "subscriptions_cancel", "summary": "Cancel a subscription", "description": "Cancel an active subscription.", "tags": [ "Subscriptions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "commit", "in": "query", "required": false, "description": "If 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.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "subscription": { "id": 27363808, "address_id": 42171447, "customer_id": 37657002, "analytics_data": { "utm_params": { "utm_source": "facebook", "utm_medium": "cpc" } }, "cancellation_reason": null, "cancellation_reason_comments": null, "cancelled_at": null, "charge_interval_frequency": 1, "created_at": "2020-02-19T17:40:09+00:00", "expire_after_specific_number_of_charges": null, "external_product_id": { "ecommerce": "4381728735283" }, "external_variant_id": { "ecommerce": "32309455192167" }, "has_queued_charges": true, "is_digital": false, "is_prepaid": false, "is_skippable": true, "is_swappable": false, "max_retries_reached": false, "next_charge_scheduled_at": "2021-08-05", "order_day_of_month": null, "order_day_of_week": null, "order_interval_frequency": 1, "order_interval_unit": "month", "presentment_currency": "USD", "price": "10.00", "product_title": "ABC Shirt", "properties": [ { "name": "Color", "value": "Blue" }, { "name": "Size", "value": "Large" } ], "quantity": 1, "sku": "TOM0001", "sku_override": false, "status": "active", "updated_at": "2020-02-19T17:40:10+00:00", "variant_title": "Blue star" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "cancellation_reason": { "type": "string", "description": "Reason for subscription cancellation." }, "cancellation_reason_comments": { "type": "string", "description": "Cancellation reason comment. Maximum length is 1024 characters." }, "send_email": { "type": "boolean", "description": "If set to false , subscription cancelled email will not be sent to customer and store owner. Note: even if set to True, there are some conditions where an email will not be sent. They are: inactive subscription_cancellation email template, customer or subscription was created on the same day, subscription is for a membership, email already sent for this subscription in the last 24 hours, customer has other active subscriptions or onetimes" }, "override": { "type": "boolean", "description": "If 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." } } }, "example": { "cancellation_reason": "other reason" } } } }, "x-recharge-scopes": [ "write_subscriptions" ] } }, "/subscriptions/{id}/activate": { "post": { "operationId": "subscriptions_activate", "summary": "Activate a subscription", "description": "Activate a cancelled subscription.", "tags": [ "Subscriptions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "commit", "in": "query", "required": false, "description": "If 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.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "subscription": { "id": 27363808, "address_id": 42171447, "customer_id": 37657002, "analytics_data": { "utm_params": { "utm_source": "facebook", "utm_medium": "cpc" } }, "cancellation_reason": null, "cancellation_reason_comments": null, "cancelled_at": null, "charge_interval_frequency": 1, "created_at": "2020-02-19T17:40:09+00:00", "expire_after_specific_number_of_charges": null, "external_product_id": { "ecommerce": "4381728735283" }, "external_variant_id": { "ecommerce": "32309455192167" }, "has_queued_charges": true, "is_digital": false, "is_prepaid": false, "is_skippable": true, "is_swappable": false, "max_retries_reached": false, "next_charge_scheduled_at": "2021-08-05", "order_day_of_month": null, "order_day_of_week": null, "order_interval_frequency": 1, "order_interval_unit": "month", "presentment_currency": "USD", "price": "10.00", "product_title": "ABC Shirt", "properties": [ { "name": "Color", "value": "Blue" }, { "name": "Size", "value": "Large" } ], "quantity": 1, "sku": "TOM0001", "sku_override": false, "status": "active", "updated_at": "2020-02-19T17:40:10+00:00", "variant_title": "Blue star" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "custom_event_attributes": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "The name of the custom attribute." }, "value": { "type": "string", "description": "The value of the custom attribute. Maximum length is 255 characters." } } }, "description": "A 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 ." } } }, "example": {} } } }, "x-recharge-scopes": [ "write_subscriptions" ] } }, "/subscriptions/skip_gift": { "post": { "operationId": "subscriptions_skip_gift", "summary": "Gift a skipped subscription", "description": "Gift a skipped Subscription to a recipient.", "tags": [ "Subscriptions" ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "onetimes": [ { "id": 16909886, "address_id": 45154492, "created_at": "2021-05-24T19:14:25+00:00", "customer_id": 40565990, "external_product_id": { "ecommerce": "4950280863846" }, "external_variant_id": { "ecommerce": "32139793137766" }, "is_cancelled": false, "is_digital": false, "next_charge_scheduled_at": "2021-12-17T05:00:00+00:00", "price": "6.00", "product_title": "ABC Shirt", "properties": [ { "name": "Color", "value": "Blue" } ], "quantity": 1, "sku": "TOM0001", "sku_override": false, "updated_at": "2021-05-24T19:30:14+00:00", "variant_title": "Blue star" } ] } } } }, "422": { "description": "invalid data passed to the endpoint", "content": { "application/json": { "example": { "errors": { "purchase_item_ids": [ "Missing data for required field." ] } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "purchase_item_ids": { "type": "array", "items": {}, "description": "A list containing the Subscription IDs to be skipped." }, "recipient_address": { "type": "object", "properties": { "address1": { "type": "string", "description": "The street associated with the giftee Address ." }, "address2": { "type": "string", "description": "Any additional information associated with the giftee Address ." }, "city": { "type": "string", "description": "The city associated with the giftee address." }, "company": { "type": "string", "description": "The company associated with the giftee address." }, "country_code": { "type": "string", "description": "2-letter country code." }, "first_name": { "type": "string", "description": "The giftee's first name associated with the address." }, "last_name": { "type": "string", "description": "The giftee's last name associated with the address." }, "phone": { "type": "string", "description": "The giftee's phone number associated with the address." }, "province": { "type": "string", "description": "The state or province associated with the giftee address." }, "zip": { "type": "string", "description": "The zip or postal code associated with the giftee address." }, "email": { "type": "string", "description": "Email address for the giftee." } }, "required": [ "address1", "city", "country_code", "first_name", "last_name", "province", "zip", "email" ], "description": "An object that contains information associated with the giftee's Address" } }, "required": [ "purchase_item_ids", "recipient_address" ] }, "example": { "recipient_address": { "address1": "1776 Washington Street", "address2": "", "city": "Los Angeles", "company": "Recharge", "country_code": "US", "first_name": "John", "last_name": "Doe", "phone": "5551234567", "province": "California", "zip": "90404", "email": "fake@example.com" }, "purchase_item_ids": [ 27363808, 27363809 ] } } } }, "x-recharge-scopes": [ "write_subscriptions" ] } }, "/subscriptions/{id}/charges/skip": { "post": { "operationId": "subscriptions_skip_future_charge", "summary": "Skip a future charge for a subscription", "description": "Skip an upcoming charge date of a Subscription for which no Charge exists yet. A Charge with the status skipped is created for the date, or the Subscription is added to a Charge that is already skipped on that date. If a Charge containing the Subscription already exists on the date, use the skip a charge endpoint instead.", "tags": [ "Subscriptions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "charge": { "id": 880000001, "address_id": 120000001, "status": "skipped", "type": "recurring", "scheduled_at": "2027-01-15" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "The date of the upcoming charge to skip. It must be at least one day in the future, match a date in the customer's upcoming delivery schedule, and be within the number of days the store allows charges to be skipped in advance (90 by default)." } }, "required": [ "date" ] } } } }, "x-recharge-scopes": [ "write_orders" ] } }, "/subscriptions/{id}/charges/skip/preview": { "get": { "operationId": "subscriptions_skip_preview", "summary": "Preview skipping the next charge of a subscription", "description": "Retrieve the date of the next charge of a Subscription and the date its following charge would be scheduled on if the next charge were skipped. Nothing is changed by this request. A 400 error is returned when the Subscription has no upcoming charge.", "tags": [ "Subscriptions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "subscription_id": 510000001, "current_next_charge_date": "2027-01-15", "expected_next_charge_date": "2027-02-15" } } } } }, "x-recharge-scopes": [ "read_subscriptions" ] } }, "/addresses/{address_id}/subscriptions-bulk-change-address": { "post": { "operationId": "subscriptions_bulk_change_address", "summary": "Bulk change subscription addresses", "description": "Move several Subscriptions from the Address in the path to other addresses of the same Customer in one request. Every Subscription must currently belong to the Address in the path, and each destination Address must use the same currency.", "tags": [ "Subscriptions" ], "parameters": [ { "name": "address_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "commit", "in": "query", "required": false, "description": "If 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.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "subscriptions": [ { "id": 510000001, "address_id": 120000002, "customer_id": 90000001, "status": "active", "next_charge_scheduled_at": "2027-01-15" } ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriptions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique numeric identifier of the Subscription to move." }, "address_id": { "type": "integer", "description": "Unique numeric identifier of the Address the Subscription is moved to." }, "next_charge_scheduled_at": { "type": "string", "format": "date-time", "description": "The next charge date desired for the Subscription on the new Address . It must be in the future." } }, "required": [ "id", "address_id" ] }, "description": "The list of subscriptions to move." } }, "required": [ "subscriptions" ] } } } }, "x-recharge-scopes": [ "write_subscriptions" ] } }, "/bundles/{purchase_item_id}": { "put": { "operationId": "bundles_update_subscription", "summary": "Update a bundle subscription and its contents", "description": "Update a Subscription or Onetime for a bundle product and the contents of its BundleSelection in a single request. The request accepts the same body parameters as the update a subscription endpoint, plus items . It can only be used when the current or the new product is a bundle product, and only for items with the status active or onetime .", "tags": [ "Subscriptions" ], "parameters": [ { "name": "purchase_item_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "commit", "in": "query", "required": false, "description": "If 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.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "subscription": { "id": 510000001, "address_id": 120000001, "customer_id": 90000001, "status": "active", "quantity": 1, "price": "45.00", "items": [ { "id": 7700001, "collection_id": "400000000001", "external_product_id": "8000000000001", "external_variant_id": "44000000000001", "quantity": 2, "price": "0.00" } ] } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "external_product_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "The product id as it appears in the external e-commerce platform." } }, "description": "An object containing the product id as it appears in external platforms." }, "external_variant_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "The variant id as it appears in the external e-commerce platform." } }, "description": "An object containing the variant id as it appears in external platforms." }, "items": { "type": "array", "items": { "type": "object", "properties": { "collection_id": { "type": "string", "description": "The id of the collection the item belongs to." }, "external_product_id": { "type": "string", "description": "The product id of the item as it appears in the external e-commerce platform." }, "external_variant_id": { "type": "string", "description": "The variant id of the item as it appears in the external e-commerce platform." }, "price": { "type": "string", "description": "The price of the item. It cannot be negative." }, "quantity": { "type": "integer", "description": "The quantity of the item." } }, "required": [ "collection_id", "external_product_id", "external_variant_id", "quantity" ] }, "description": "The list of items that make up the contents of the bundle." }, "plan_id": { "type": "integer", "description": "A Recharge Plan id that provides interval information for the Subscription ." } } } } } }, "x-recharge-scopes": [ "write_subscriptions" ] } }, "/webhooks": { "post": { "operationId": "webhooks_create", "summary": "Create a webhook", "description": "Create a webhook. Currently, only the API can be used to create a webhook. To register a webhook endpoint for a specific object, you will need to have read permissions for that object on your Recharge API token. For example, if you want to register a webhook for subscription/created, you will need the read_subscriptions permissions. Each API token can register a maximum of 10 webhooks of the same topic. Related guides: Webhook payload examples", "tags": [ "Webhook endpoints" ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "webhook": { "id": 6, "address": "https://request.in/foo", "topic": "subscription/created", "included_objects": [], "version": "2021-11" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string", "description": "The URI where the webhook should send the POST request when the event occurs." }, "included_objects": { "type": "array", "items": {}, "description": "List of objects set to enrich the webhook payload. cf. extending responses", "enum": [ "address", "addresses", "charge_activities", "customer", "event", "event_charge", "metafields", "payment_methods", "subscriptions" ] }, "topic": { "type": "string", "description": "The event that will trigger the webhook." }, "version": { "type": "string", "description": "The version of the API used to populate the body of the webhook. If not set, this will default to the store's default API version. For V2, send v2 or 2021-11 . Both are saved and returned as 2021-11 .", "enum": [ "v2", "2021-01", "2021-11" ] } }, "required": [ "address", "topic" ] }, "example": { "address": "https://request.in/foo", "topic": "subscription/created", "version": "v2" } } } } }, "get": { "operationId": "webhooks_list", "summary": "List webhooks", "description": "Returns all the webhooks of the given store that are owned by the current requesting client (note that a a private token shows all of the store’s webhooks, an integration token only shows that integration’s webhooks).", "tags": [ "Webhook endpoints" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Number of results to return. Defaults to 50; the maximum is 250.", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page to show. Cannot be greater than 300. Page-based pagination can be disabled for a token, in which case cursors must be used.", "schema": { "type": "integer" } }, { "name": "sort_by", "in": "query", "required": false, "description": "Sort order of the results. Defaults to id-desc .", "schema": { "type": "string", "enum": [ "id-asc", "id-desc" ] } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "webhooks": [ { "id": 19451, "address": "https://request.in/foo", "included_objects": [], "topic": "subscription/created", "version": "2021-11" }, { "id": 19453, "address": "https://request.in/foo", "included_objects": [], "topic": "subscription/cancelled", "version": "2021-11" } ] } } } } } } }, "/webhooks/{id}": { "get": { "operationId": "webhooks_retrieve", "summary": "Retrieve a webhook", "description": "Retrieve a webhook using the Recharge webhook id.", "tags": [ "Webhook endpoints" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "webhook": { "id": 6, "address": "https://request.in/foo", "topic": "subscription/created", "included_objects": [], "version": "2021-11" } } } } } } }, "put": { "operationId": "webhooks_update", "summary": "Update a webhook", "description": "Modifies an existing Webhook to match the specified parameters.", "tags": [ "Webhook endpoints" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "webhook": { "id": 6, "address": "https://request.in/foo", "topic": "subscription/created", "included_objects": [], "version": "2021-11" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string", "description": "The URI where the webhook should send the POST request when the event occurs." }, "included_objects": { "type": "array", "items": {}, "description": "List of objects set to enrich the webhook payload. cf. extending responses", "enum": [ "address", "addresses", "charge_activities", "customer", "event", "event_charge", "metafields", "payment_methods", "subscriptions" ] }, "topic": { "type": "string", "description": "The event that will trigger the webhook." }, "version": { "type": "string", "description": "The version of the API used to populate the body of the webhook. For V2, send v2 or 2021-11 . Both are saved and returned as 2021-11 .", "enum": [ "v2", "2021-01", "2021-11" ] } } }, "example": { "address": "https://request.in/foo" } } } } }, "delete": { "operationId": "webhooks_delete", "summary": "Delete a webhook", "description": "Delete a Webhook", "tags": [ "Webhook endpoints" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Content Deleted: The server has successfully fulfilled the request and deleted the desired object and there is no content to send in the response body.", "content": { "application/json": { "example": {} } } } } } }, "/webhooks/{id}/test": { "post": { "operationId": "webhooks_test", "summary": "Test webhooks", "description": "In order to test webhook connectivity, you can trigger the dispatch of a test webhook with our webhook test endpoint. Sending a POST request to the webhook endpoint containing a webhook id will dispatch an empty webhook body to the specified webhook’s destination url.", "tags": [ "Webhook endpoints" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": {} } } } } } }, "/async_batches": { "post": { "operationId": "async_batch_endpoints_create", "summary": "Create a batch", "description": "In order to create, retrieve, or process batches, the API token requires the write_batches permission. Additional permissions are required, dependent upon the indicated batch_type. For example, for a batch type of discount_create, the API token requires the write_discounts permission. Create a new batch, and indicate the desired outcome of the batch using batch_type. CAUTION Async batches and their tasks will only be retained in Recharge for one month after batch creation. Available batch types The async_batches API supports many functions, each identified as a batch_type. Typically, the task body for a batch_type will be representative of a single request to our standard endpoints, however, some variations may be present. Related guides: Examples of Async Batches", "tags": [ "Async batch Endpoints" ], "responses": { "201": { "description": "successful response", "content": { "application/json": { "example": { "async_batch": { "id": 19, "batch_type": "discount_create", "closed_at": null, "created_at": "2022-10-12T20:16:09+00:00", "deleted_at": null, "expired_at": "2022-03-19T08:52:10+00:00", "fail_task_count": 0, "status": "not_started", "submitted_at": null, "success_task_count": 0, "total_task_count": 0, "updated_at": "2022-10-12T20:16:09+00:00", "version": "2021-11" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "batch_type": { "type": "string", "description": "Desired batch type", "enum": [ "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" ] }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "body": { "type": "object", "description": "The body of the task, in the format required by the batch_type ." } } }, "description": "Optional list of tasks to add to the batch when it is created. A single request can contain at most 1,000 tasks." } }, "required": [ "batch_type" ] }, "example": { "batch_type": "desired_batch_type" } } } }, "x-recharge-scopes": [ "write_batches" ] }, "get": { "operationId": "async_batch_endpoints_list", "summary": "List batches", "description": "Returns a list of all your async_batches.", "tags": [ "Async batch Endpoints" ], "parameters": [ { "name": "batch_type", "in": "query", "required": false, "description": "Filter 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.", "schema": { "type": "string", "enum": [ "address_discount_apply", "address_discount_remove", "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", "bulk_subscriptions_create", "bulk_subscriptions_delete", "bulk_subscriptions_update", "bundle_bulk_swap", "bundle_selection_assign", "bundle_selection_update", "bundle_selections_delete", "bundle_selections_sync_price", "change_next_charge_date", "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_create", "product_delete", "product_update", "product_variant_tax_code_update", "subscription_cancel", "subscription_update" ] } }, { "name": "status", "in": "query", "required": false, "description": "Filter batches by status .", "schema": { "type": "string", "enum": [ "not_started", "processing", "running", "completed", "failed", "terminated" ] } }, { "name": "sort_by", "in": "query", "required": false, "description": "Sort order of the results. Defaults to id-desc .", "schema": { "type": "string", "enum": [ "id-asc", "id-desc", "created_at-asc", "created_at-desc" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Number of results to return. Defaults to 50; the maximum is 250.", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page to show. Cannot be greater than 300. Page-based pagination can be disabled for a token, in which case cursors must be used.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Return 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "async_batches": [ { "id": 20, "batch_type": "discount_delete", "closed_at": null, "created_at": "2022-10-12T20:16:09+00:00", "deleted_at": null, "expired_at": "2022-03-19T08:52:10+00:00", "fail_task_count": 0, "status": "not_started", "submitted_at": null, "success_task_count": 0, "total_task_count": 40, "updated_at": "2022-10-12T20:16:09+00:00", "version": "2021-11" }, { "id": 19, "batch_type": "discount_update", "closed_at": null, "created_at": "2022-10-12T20:16:09+00:00", "deleted_at": null, "expired_at": "2022-03-19T08:52:10+00:00", "fail_task_count": 0, "status": "not_started", "submitted_at": null, "success_task_count": 0, "total_task_count": 0, "updated_at": "2022-10-12T20:16:09+00:00", "version": "2021-11" }, { "id": 16, "batch_type": "discount_create", "closed_at": "2022-10-12T20:16:09+00:00", "created_at": "2022-10-12T20:16:09+00:00", "deleted_at": null, "expired_at": "2022-03-19T08:52:10+00:00", "fail_task_count": 0, "status": "completed", "submitted_at": "2022-10-12T20:16:09+00:00", "success_task_count": 2000, "total_task_count": 2000, "updated_at": "2022-10-12T20:16:09+00:00", "version": "2021-11" } ] } } } } }, "x-recharge-scopes": [ "read_batches" ] } }, "/async_batches/{id}": { "get": { "operationId": "async_batch_endpoints_retrieve", "summary": "Retrieve a batch", "description": "Retrieve a batch using the Recharge batch id. A batch can be retrieved during processing to evaluate batch progress. ## HTTP request examples GET /async_batches/", "tags": [ "Async batch Endpoints" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "async_batch": { "id": 19, "batch_type": "discount_create", "closed_at": null, "created_at": "2022-10-12T20:16:09+00:00", "deleted_at": null, "expired_at": "2022-03-19T08:52:10+00:00", "fail_task_count": 0, "status": "not_started", "submitted_at": null, "success_task_count": 0, "total_task_count": 0, "updated_at": "2022-10-12T20:16:09+00:00", "version": "2021-11" } } } } } }, "x-recharge-scopes": [ "read_batches" ] }, "delete": { "operationId": "async_batch_endpoints_delete", "summary": "Delete a batch", "description": "Deletes a batch. Only batches with status not_started , processing or running can be deleted. The token also needs the write scope of the resource the batch type operates on.", "tags": [ "Async batch Endpoints" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content: The request was successful and there is no content to return." } }, "x-recharge-scopes": [ "write_batches" ] }, "put": { "operationId": "async_batch_endpoints_terminate", "summary": "Terminate a batch", "description": "Stops a batch by setting its status to terminated . Only batches with status not_started , processing or running can be terminated. terminated is the only status that can be set through this endpoint.", "tags": [ "Async batch Endpoints" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "The request has been accepted for processing.", "content": { "application/json": { "example": {} } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "The new status of the batch. Must be terminated .", "enum": [ "terminated" ] } }, "required": [ "status" ] } } } }, "x-recharge-scopes": [ "write_batches" ] } }, "/async_batches/{batch_id}/process": { "post": { "operationId": "async_batch_endpoints_process", "summary": "Process a batch", "description": "Until a batch is submitted for processing, no tasks are attempted. Once you have ensured the tasks in a batch are ready for processing, you can submit for processing using this endpoint and the associated batch id. Webhooks - Batches process quickly, and may result in Recharge dispatching many webhooks at a high rate. Ensure any systems subscribed to resulting webhooks are capable of handling such load.", "tags": [ "Async batch Endpoints" ], "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "successful response", "content": { "application/json": { "example": { "async_batch": { "id": 21, "batch_type": "discount_create", "closed_at": null, "created_at": "2022-06-05T10:53:36+00:00", "deleted_at": null, "expired_at": "2022-03-19T08:52:10+00:00", "fail_task_count": 0, "status": "processing", "submitted_at": "2022-06-05T10:54:54+00:00", "success_task_count": 0, "total_task_count": 10, "updated_at": "2022-06-05T10:54:54+00:00", "version": "2021-11" } } } } } }, "x-recharge-scopes": [ "write_batches" ] } }, "/async_batches/{batch_id}/tasks": { "post": { "operationId": "async_batch_tasks_create", "summary": "Create a batch task", "description": "A batch contains operations of similar type (indicated by batch_type), called tasks. A task is typically representative of a single API request, with a body parameter containing the standard request body for the associated batch_type. A single request to add tasks may contain up to 1,000 tasks, and a batch may contain up to 10,000 tasks. ##HTTP examples POST /async_batches//tasks", "tags": [ "Async batch Tasks" ], "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "count": 10 } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "properties": { "body": { "type": "object", "description": "The body of the task, in the format required by the batch_type of the batch." } }, "required": [ "body" ] }, "description": "List 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." } }, "required": [ "tasks" ] }, "example": { "tasks": [ { "body": { "code": "indexing", "discount_type": "shipping", "duration": "forever", "status": "enabled", "value": 100 } }, { "body": { "code": "maroon", "discount_type": "shipping", "duration": "forever", "status": "enabled", "value": 100 } }, { "body": { "code": "web services", "value": 100, "discount_type": "shipping", "duration": "forever", "status": "enabled" } }, { "body": { "code": "PCI", "discount_type": "shipping", "duration": "forever", "status": "enabled", "value": 100 } }, { "body": { "code": "Cheese", "discount_type": "shipping", "duration": "forever", "status": "enabled", "value": 100 } }, { "body": { "code": "overriding", "discount_type": "shipping", "duration": "forever", "status": "enabled", "value": 100 } }, { "body": { "code": "bandwidth-monitored", "value": 100, "discount_type": "shipping", "duration": "forever", "status": "enabled" } }, { "body": { "code": "Falkland Islands (Malvinas)", "discount_type": "shipping", "duration": "forever", "status": "enabled", "value": 100 } }, { "body": { "code": "Computer", "discount_type": "shipping", "duration": "forever", "status": "enabled", "value": 100 } }, { "body": { "code": "digital", "discount_type": "shipping", "duration": "forever", "status": "enabled", "value": 100 } } ] } } } }, "x-recharge-scopes": [ "write_batches" ] }, "get": { "operationId": "async_batch_tasks_retrieve", "summary": "List batch tasks", "description": "Returns a list of all tasks in the indicated batch, using batch id. For batches with many tasks, pagination is supported when listing tasks. Use this function to evaluate the task-level results of a batch during, or after processing. Task results will be contained in the results object of each task.", "tags": [ "Async batch Tasks" ], "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "ids", "in": "query", "required": false, "description": "Filter tasks by id. If passing multiple values, must be comma separated. Non-integer values will result in a 422 error", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter tasks by status .", "schema": { "type": "string", "enum": [ "pending", "queued", "processing", "success", "fail" ] } }, { "name": "completed", "in": "query", "required": false, "description": "When true , return only tasks that have finished processing; when false , return only tasks that have not finished.", "schema": { "type": "boolean" } }, { "name": "sort_by", "in": "query", "required": false, "description": "Sort order of the results. Defaults to id-desc .", "schema": { "type": "string", "enum": [ "id-asc", "id-desc" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Number of results to return. Defaults to 50; the maximum is 250.", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page to show. Cannot be greater than 300. Page-based pagination can be disabled for a token, in which case cursors must be used.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Return 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "next_cursor": null, "previous_cursor": null, "async_batch_tasks": [ { "id": 1490831511, "batch_id": 765278, "body": { "code": "Computer", "discount_type": "shipping", "duration": "forever", "status": "enabled", "value": 100 }, "completed_at": null, "created_at": "2022-02-17T06:40:53+00:00", "deleted_at": null, "queued_at": null, "result": null, "stalled_at": null, "started_at": null, "status": "pending", "updated_at": "2022-02-17T06:40:53+00:00" }, { "id": 1490831510, "batch_id": 765278, "body": { "code": "Falkland Islands (Malvinas)", "discount_type": "shipping", "duration": "forever", "status": "enabled", "value": 100 }, "completed_at": null, "created_at": "2022-02-17T06:40:53+00:00", "deleted_at": null, "queued_at": null, "result": null, "stalled_at": null, "started_at": null, "status": "pending", "updated_at": "2022-02-17T06:40:53+00:00" }, { "id": 1490831509, "batch_id": 765278, "body": { "code": "bandwidth-monitored", "discount_type": "shipping", "duration": "forever", "status": "enabled", "value": 100 }, "completed_at": null, "created_at": "2022-02-17T06:40:53+00:00", "deleted_at": null, "queued_at": null, "result": null, "stalled_at": null, "started_at": null, "status": "pending", "updated_at": "2022-02-17T06:40:53+00:00" }, { "id": 1490831508, "batch_id": 765278, "body": { "code": "overriding", "discount_type": "shipping", "duration": "forever", "status": "enabled", "value": 100 }, "completed_at": null, "created_at": "2022-02-17T06:40:53+00:00", "deleted_at": null, "queued_at": null, "result": null, "stalled_at": null, "started_at": null, "status": "pending", "updated_at": "2022-02-17T06:40:53+00:00" }, { "id": 1490831507, "batch_id": 765278, "body": { "code": "Cheese", "discount_type": "shipping", "duration": "forever", "status": "enabled", "value": 100 }, "completed_at": null, "created_at": "2022-02-17T06:40:53+00:00", "deleted_at": null, "queued_at": null, "result": null, "stalled_at": null, "started_at": null, "status": "pending", "updated_at": "2022-02-17T06:40:53+00:00" }, { "id": 1490831506, "batch_id": 765278, "body": { "code": "PCI", "discount_type": "shipping", "duration": "forever", "status": "enabled", "value": 100 }, "completed_at": null, "created_at": "2022-02-17T06:40:53+00:00", "deleted_at": null, "queued_at": null, "result": null, "stalled_at": null, "started_at": null, "status": "pending", "updated_at": "2022-02-17T06:40:53+00:00" }, { "id": 1490831505, "batch_id": 765278, "body": { "code": "web services", "discount_type": "shipping", "duration": "forever", "status": "enabled", "value": 100 }, "completed_at": null, "created_at": "2022-02-17T06:40:53+00:00", "deleted_at": null, "queued_at": null, "result": null, "stalled_at": null, "started_at": null, "status": "pending", "updated_at": "2022-02-17T06:40:53+00:00" }, { "id": 1490831504, "batch_id": 765278, "body": { "code": "maroon", "discount_type": "shipping", "duration": "forever", "status": "enabled", "value": 100 }, "completed_at": null, "created_at": "2022-02-17T06:40:53+00:00", "deleted_at": null, "queued_at": null, "result": null, "stalled_at": null, "started_at": null, "status": "pending", "updated_at": "2022-02-17T06:40:53+00:00" }, { "id": 1490831503, "batch_id": 765278, "body": { "code": "indexing", "discount_type": "shipping", "duration": "forever", "status": "enabled", "value": 100 }, "completed_at": null, "created_at": "2022-02-17T06:40:53+00:00", "deleted_at": null, "queued_at": null, "result": null, "stalled_at": null, "started_at": null, "status": "pending", "updated_at": "2022-02-17T06:40:53+00:00" } ] } } } } }, "x-recharge-scopes": [ "read_batches" ] } }, "/async_batches/{batch_id}/tasks/{task_id}": { "get": { "operationId": "async_batch_tasks_retrieve_one", "summary": "Retrieve a batch task", "description": "Retrieves a single task of a batch by its id .", "tags": [ "Async batch Tasks" ], "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "async_batch_task": { "id": 4058301, "batch_id": 31250, "body": { "discount_id": 88012 }, "status": "pending", "result": null, "queued_at": null, "started_at": null, "stalled_at": null, "completed_at": null, "deleted_at": null, "created_at": "2026-09-14T10:01:40", "updated_at": "2026-09-14T10:01:40" } } } } } }, "x-recharge-scopes": [ "read_batches" ] } }, "/token_information": { "get": { "operationId": "token_information_retrieve", "summary": "Retrieve token information", "description": "Retrieve token details.", "tags": [ "Token information" ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "token_information": { "client": { "name": "PARTNER", "contact_email": "ed@partner.com" }, "contact_email": "jbluhm@example.com", "created_by_email": null, "created_by_user_id": null, "name": "token name", "scopes": [ "read_store", "write_payment_methods" ] } } } } } } } }, "/token_information/rotate": { "post": { "operationId": "token_information_rotate", "summary": "Rotate the current token", "description": "Replaces the API token used to make the request with a new token that has the same name, scopes and expiry. The previous token keeps working for the grace period and then expires. The new token value is returned only in this response. Only API tokens created by a merchant in the Recharge admin can be rotated, and the endpoint is only available on stores where expiring API tokens are enabled (otherwise 404 ).", "tags": [ "Token information" ], "responses": { "201": { "description": "OK: The request was successful, created a new resource, and resource created is in the body.", "content": { "application/json": { "example": { "token": { "id": 70213, "name": "Warehouse sync", "access_token": "sk_1x1_0f3c9d1e5b7a4c2e8f6a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e", "access_token_hint": "sk_1x1_...0d1e", "scopes": [ "read_orders", "write_orders" ], "expires_at": "2126-08-21T14:03:55Z" }, "rotated_token": { "id": 69877, "access_token_hint": "sk_1x1_...a41c", "expires_at": "2026-09-15T14:03:55Z" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "grace_period_seconds": { "type": "integer", "description": "Number of seconds the previous token remains valid after rotation. Must be between 0 and 604800 (7 days). Defaults to 86400 (24 hours); 0 expires the previous token immediately." } } } } } } } }, "/accounts/{id}": { "get": { "operationId": "account_retrieve", "summary": "Retrieve an account", "description": "Retrieves an account for the store.", "tags": [ "Accounts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "Include related objects in the response. Use store to embed the Store the Account belongs to under include.store .", "schema": { "type": "string", "enum": [ "store" ] } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "account": { "id": 3315125, "user_id": 2057785, "created_at": "2021-07-20T09:10:19+00:00", "invited_at": "2021-07-18T09:10:19+00:00", "is_owner": false, "last_login_at": null, "role_association": null, "role_department": null, "role_title": null, "role_partner_details": null } } } } } }, "x-recharge-scopes": [ "read_accounts" ] } }, "/accounts": { "get": { "operationId": "accounts_list", "summary": "List accounts", "description": "Returns all accounts associated to the store.", "tags": [ "Accounts" ], "parameters": [ { "name": "user_id", "in": "query", "required": false, "description": "Filter accounts by the unique numeric identifier of the associated user.", "schema": { "type": "integer" } }, { "name": "is_owner", "in": "query", "required": false, "description": "Filter accounts by whether the user is the store owner.", "schema": { "type": "boolean" } }, { "name": "email_search", "in": "query", "required": false, "description": "Return accounts whose user email contains the given text.", "schema": { "type": "string" } }, { "name": "include_all_owners", "in": "query", "required": false, "description": "When passed together with email_search , store owner accounts are returned in addition to the accounts matching the search.", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "Include related objects in the response. Use store to embed the Store the Account belongs to under include.store .", "schema": { "type": "string", "enum": [ "store" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Number of results to return. Defaults to 50; the maximum is 250.", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page to show. Cannot be greater than 300. Page-based pagination can be disabled for a token, in which case cursors must be used.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Return 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "accounts": [ { "id": 3315125, "user_id": 2057785, "created_at": "2021-07-20T09:10:19+00:00", "invited_at": "2021-07-18T09:10:19+00:00", "is_owner": false, "last_login_at": null, "role_association": null, "role_department": null, "role_title": null, "role_partner_details": null }, { "id": 3316125, "user_id": 2056785, "created_at": "2021-05-20T09:10:19+00:00", "invited_at": null, "is_owner": true, "last_login_at": null, "role_association": null, "role_department": null, "role_title": null, "role_partner_details": null } ] } } } } }, "x-recharge-scopes": [ "read_accounts" ] } }, "/events": { "get": { "operationId": "events_list", "summary": "List events", "description": "Returns all events associated with the store. The Events API is limited to events that occurred in the last 7 days", "tags": [ "Events" ], "parameters": [ { "name": "created_at_min", "in": "query", "required": false, "description": "Show events that occurred after a certain date", "schema": { "type": "string" } }, { "name": "created_at_max", "in": "query", "required": false, "description": "Show events that occurred before a certain date", "schema": { "type": "string" } }, { "name": "object_type", "in": "query", "required": false, "description": "Filter events by specific object_type , such as address , customer , or subscription . For a full list of available object types, refer to the list below.", "schema": { "type": "string", "enum": [ "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" ] } }, { "name": "object_id", "in": "query", "required": false, "description": "Show events with a specific object_id . This filter should be used with the object_type filter.", "schema": { "type": "integer" } }, { "name": "verbs", "in": "query", "required": false, "description": "Show events with a specific verb or comma-separated list of verbs", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "required": false, "description": "Show events related to a specific customer using the customer's primary identifier", "schema": { "type": "integer" } }, { "name": "origin", "in": "query", "required": false, "description": "Filter events by specific source origin. Available origins: api , customer_portal , merchant_portal , recharge_process , external_platform .", "schema": { "type": "string", "enum": [ "api", "customer_portal", "external_platform", "merchant_portal", "recharge_process" ] } }, { "name": "verb", "in": "query", "required": false, "description": "Show events with a specific verb .", "schema": { "type": "string", "enum": [ "activated", "apply_discount", "cancelled", "captured", "change_next_charge_date", "completed", "create_contract", "created", "deactivated", "delayed", "deleted", "expired", "failed", "login", "max_retries_reached", "notification_activated", "notification_deactivated", "paid", "paused", "payment_captured", "payment_method_updated", "processed", "redeemed", "refund", "refunded", "remove_discount", "selling_plans_syncing", "set_next_charge_date", "skipped", "started", "success", "swapped", "uninstalled", "unskipped", "updated", "workflow_updated" ] } }, { "name": "sort_by", "in": "query", "required": false, "description": "Sort order of the results. Defaults to id-desc when filtering by customer_id and to created_at-desc otherwise.", "schema": { "type": "string", "enum": [ "id-asc", "id-desc", "created_at-asc", "created_at-desc" ] } }, { "name": "exclude_empty_customer_events", "in": "query", "required": false, "description": "When true , customer events with the verb updated that have no updated_attributes are left out of the results.", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of results to return. Defaults to 50; the maximum is 250.", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page to show. Cannot be greater than 300. Page-based pagination can be disabled for a token, in which case cursors must be used.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Return 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "events": [ { "id": 7160141294, "object_id": 362310818, "customer_id": 36885098, "created_at": "2023-05-31T14:16:07", "object_type": "subscription", "verb": "updated", "description": "Updated subscription #362310818", "updated_attributes": [ { "attribute": "price", "previous_value": "12.00", "value": "15.00" }, { "attribute": "quantity", "previous_value": "3", "value": "5" } ], "source": { "account_id": null, "api_token_id": 987654321, "api_token_name": "Subscription API token", "account_email": null, "origin": "api", "user_type": null }, "custom_attributes": [ { "key": "ab_testing_flag", "value": "a" } ] } ] } } } } }, "x-recharge-scopes": [ "read_events" ] } } }, "components": { "securitySchemes": { "apiToken": { "type": "apiKey", "in": "header", "name": "X-Recharge-Access-Token" } }, "schemas": { "address_object": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique numeric identifier for the Address ." }, "include": { "type": "object", "properties": { "customer": { "type": "object", "description": "The Customer associated with the Address . Returned when include contains customer ." }, "payment_methods": { "type": "array", "items": {}, "description": "The Payment Methods associated with the Address . Returned when include contains payment_methods . Requires the read_payment_methods scope." }, "subscriptions": { "type": "array", "items": {}, "description": "The Subscriptions on the Address . Returned when include contains subscriptions . Requires the read_subscriptions scope." }, "onetimes": { "type": "array", "items": {}, "description": "The Onetimes on the Address . Returned when include contains onetimes . Requires the read_subscriptions scope." }, "discount": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique numeric identifier for the Discount ." }, "code": { "type": "string", "description": "The code used to apply the Discount ." }, "value": { "type": "number", "description": "The discounted value to be applied." }, "value_type": { "type": "string", "description": "The type of the Discount value.", "enum": [ "fixed_amount", "percentage", "shipping" ] }, "title": { "type": "string", "description": "The title of the Discount ." }, "application_method": { "type": "string", "description": "How the Discount is applied.", "enum": [ "code", "automatic" ] } }, "description": "The Discount applied to the Address , or null if the Address has no discount. Returned when include contains discount . Requires the read_discounts scope." }, "charge_activities": { "type": "array", "items": {}, "description": "The charge activity records created for the Address in the last 90 days. Returned when include contains charge_activities . Requires the read_orders scope." } }, "description": "An object containing the related resources requested with the include query parameter." }, "is_gift": { "type": "boolean", "description": "Whether the Address is a gift address." }, "payment_method_id": { "type": "integer", "description": "Unique numeric identifier for the Payment Method associated to the Address ." }, "address1": { "type": "string", "description": "The street associated with the Address ." }, "address2": { "type": "string", "description": "Any additional information associated with the Address ." }, "city": { "type": "string", "description": "The city associated with the address." }, "company": { "type": "string", "description": "The company associated with the address." }, "country_code": { "type": "string", "description": "2-letter country code." }, "customer_id": { "type": "integer", "description": "Unique numeric identifier for the customer associated with the address." }, "discounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "The id of a discount associated with this address." } } }, "description": "A discount which will be applied on the address. While the discounts parameter is an array, only a single discount code will be applied. If multiple discount codes are provided, only the first discount in the array will apply to the address." }, "first_name": { "type": "string", "description": "The customer’s first name associated with the address." }, "last_name": { "type": "string", "description": "The customer’s last name associated with the address." }, "order_attributes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name for the attribute." }, "value": { "type": "string", "description": "The value for the associated attribute." } } }, "description": "Replaces cart_attributes. Extra information that is added to the order." }, "order_note": { "type": "string", "description": "Notes to be added to all orders associated with the address." }, "phone": { "type": "string", "description": "The phone number associated with the address." }, "presentment_currency": { "type": "string", "description": "The currency on the subscription contract in Shopify." }, "province": { "type": "string", "description": "The state or province associated with the address." }, "shipping_lines_conserved": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "The code of the associated shipping line." }, "price": { "type": "string", "description": "The price (in store’s currency) of the associated shipping line." }, "title": { "type": "string", "description": "The title of the associated shipping line." } } }, "description": "Shipping rates that have previously been overridden via shipping_lines_override but are currently inactive." }, "shipping_lines_override": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "The code of the associated shipping line." }, "price": { "type": "string", "description": "The price (in store’s currency) of the associated shipping line." }, "title": { "type": "string", "description": "The title of the associated shipping line." } } }, "description": "Used when shipping rates need to be overridden." }, "zip": { "type": "string", "description": "The zip or postal code associated with the address." }, "created_at": { "type": "string", "format": "date-time", "description": "The date and time when the address was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "The date and time when the address was last updated." } } }, "bundle_product_object": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique numeric identifier for the Bundle Product ." }, "delivery_cycles": { "type": "object", "description": "An object containing the delivery cycle configuration of the Bundle Product ." }, "is_customizable": { "type": "boolean", "description": "Whether customers can choose the contents of the bundle." }, "layout_settings": { "type": "object", "description": "An object containing the settings used to display the bundle to customers." }, "layout_settings_version": { "type": "string", "description": "The version of the format used by layout_settings ." }, "max_quantity_per_variant": { "type": "integer", "description": "The maximum quantity of a single item that can be selected in the bundle." }, "price_rule": { "type": "string", "description": "How the price of the bundle is determined.", "enum": [ "dynamic", "fixed" ] }, "reset_box_contents": { "type": "boolean", "description": "Whether the contents of the bundle are reset after each order." }, "settings": { "type": "object", "properties": { "display_variants_as_separate_products_in_list": { "type": "boolean", "description": "Whether the variants of a product are listed as separate products when choosing the contents of the bundle." }, "dynamic_filter_products_by_discount": { "type": "boolean", "description": "Whether discounts are calculated from the plan of the bundle product instead of from each product in the bundle." }, "show_product_and_variant_name_in_products_list": { "type": "boolean", "description": "Whether both the product name and the variant name are shown when choosing the contents of the bundle." } }, "description": "An object containing additional settings of the Bundle Product ." }, "title": { "type": "string", "description": "The title of the Bundle Product ." }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique numeric identifier for the bundle variant." }, "position": { "type": "integer", "description": "The position in which the bundle variant is displayed." }, "updated_at": { "type": "string", "format": "date-time", "description": "The date and time when the bundle variant was last updated." }, "created_at": { "type": "string", "format": "date-time", "description": "The date and time when the bundle variant was created." }, "enabled": { "type": "boolean", "description": "Whether the bundle variant is enabled." }, "external_variant_id": { "type": "string", "description": "The id of the variant as it appears in the external e-commerce platform." }, "items_count": { "type": "integer", "description": "The number of items the bundle variant contains." }, "option_sources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique numeric identifier for the option source." }, "source_platform": { "type": "string", "description": "The platform the option source comes from, for example shopify ." }, "created_at": { "type": "string", "format": "date-time", "description": "The date and time when the option source was created." }, "option_source_id": { "type": "string", "description": "The id of the collection, as it appears in the source platform, that contents can be chosen from." }, "position": { "type": "integer", "description": "The position in which the option source is displayed." }, "quantity_max": { "type": "integer", "description": "The maximum number of items that can be chosen from this option source." }, "quantity_min": { "type": "integer", "description": "The minimum number of items that must be chosen from this option source." }, "updated_at": { "type": "string", "format": "date-time", "description": "The date and time when the option source was last updated." } } }, "description": "An array of the collections from which the contents of the bundle variant can be chosen." }, "ranges": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique numeric identifier for the range." }, "created_at": { "type": "string", "format": "date-time", "description": "The date and time when the range was created." }, "quantity_max": { "type": "integer", "description": "The maximum number of items the bundle variant can contain." }, "quantity_min": { "type": "integer", "description": "The minimum number of items the bundle variant must contain." }, "updated_at": { "type": "string", "format": "date-time", "description": "The date and time when the range was last updated." } } }, "description": "An array of the quantity ranges allowed for the contents of the bundle variant." }, "selection_defaults": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique numeric identifier for the default selection." }, "created_at": { "type": "string", "format": "date-time", "description": "The date and time when the default selection was created." }, "external_variant_id": { "type": "string", "description": "The id of the variant, as it appears in the external e-commerce platform, that is included by default." }, "quantity": { "type": "integer", "description": "The quantity of the variant that is included by default." }, "updated_at": { "type": "string", "format": "date-time", "description": "The date and time when the default selection was last updated." } } }, "description": "An array of the default contents of the bundle variant." }, "title": { "type": "string", "description": "The title of the bundle variant." } } }, "description": "An array of the variants of the Bundle Product ." }, "updated_at": { "type": "string", "format": "date-time", "description": "The date and time when the Bundle Product was last updated." }, "created_at": { "type": "string", "format": "date-time", "description": "The date and time when the Bundle Product was created." }, "custom_prices": { "type": "boolean", "description": "Whether the Bundle Product uses custom prices." }, "customization_window": { "type": "integer", "description": "The customization window of the Bundle Product , which limits when customers can change its contents. null when there is no limit." }, "customization_window_disabled_message": { "type": "string", "description": "The message shown to customers when the contents can no longer be changed." }, "default_bundle_variant_id": { "type": "integer", "description": "The id of the bundle variant that is used by default." }, "delivery_cycles_version": { "type": "string", "description": "The version of the format used by delivery_cycles ." }, "description": { "type": "string", "description": "The description of the Bundle Product ." }, "external_product_id": { "type": "string", "description": "The id of the product, as it appears in the external e-commerce platform, that is sold as a bundle." } } }, "bundle_selection_object": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique numeric identifier for the BundleSelection ." }, "bundle_variant_id": { "type": "integer", "description": "The ID of the BundleVariant associated with the BundleSelection ." }, "purchase_item_id": { "type": "integer", "description": "The ID of the PurchaseItem associated with the BundleSelection ." }, "created_at": { "type": "string", "format": "date-time", "description": "The date and time when the contents were selected." }, "external_product_id": { "type": "string", "description": "The product id as it appears in the external e-commerce platform. The external_product_id of the Product record in Recharge, linking the BundleSelection to a Product associated with a Bundle." }, "external_variant_id": { "type": "string", "description": "The variant id as it appears in the external e-commerce platform. The external_variant_id of the Product record in Recharge, linking the BundleSelection to a Product associated with a Bundle." }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique numeric identifier for the item selection." }, "collection_id": { "type": "string", "description": "The collection id as it appears in the external e-commerce platform." }, "collection_source": { "type": "string", "description": "The identifier of the external e-commerce platform." }, "price": { "type": "string", "description": "The price of the item." }, "created_at": { "type": "string", "format": "date-time", "description": "The date and time when this item was selected." }, "external_product_id": { "type": "string", "description": "The product id as it appears in the external e-commerce platform. This is the item which is going to be extracted when the Bundle is processed." }, "external_variant_id": { "type": "string", "description": "The variant id as it appears in the external e-commerce platform. This is the item which is going to be extracted when the Bundle is processed." }, "quantity": { "type": "integer", "description": "The quantity of this product." }, "updated_at": { "type": "string", "format": "date-time", "description": "The date and time at which the item selection was most recently updated." } } }, "description": "A list of item objects, each containing information about a distinct product selected as part of the Bundle." }, "updated_at": { "type": "string", "format": "date-time", "description": "The date and time at which the BundleSelection was most recently updated." }, "charge_id": { "type": "integer", "description": "The ID of the Charge associated with the BundleSelection , when the selection applies to a specific upcoming charge." }, "order_id": { "type": "integer", "description": "The ID of the Order associated with the BundleSelection ." }, "items_count": { "type": "integer", "description": "The item count of the BundleVariant associated with the BundleSelection ." }, "is_fallback": { "type": "boolean", "description": "Whether 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 ." } } }, "charge_activity_object": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique numeric identifier for the charge activity." }, "activity_details": { "type": "object", "properties": { "description": { "type": "string", "description": "A human-readable description of the event." }, "suggested_solution": { "type": "string", "description": "A suggested way to resolve the issue, when the event is a failure. An empty string when there is no suggestion." }, "links": { "type": "object", "description": "An object containing links to help articles referenced by description and suggested_solution ." } }, "description": "An object containing additional details about the event. Its contents depend on the activity_type and activity_sub_type ." }, "activity_sub_type": { "type": "string", "description": "A more specific classification of the event within its activity_type , such as card_declined for a payment_failure . Can be an empty string." }, "activity_type": { "type": "string", "description": "The type of event that was recorded, such as payment_success , payment_failure , skipped , rescheduled or refund_success ." }, "address_id": { "type": "integer", "description": "The ID of the Address of the Charge ." }, "charge_amount": { "type": "number", "description": "The amount of the Charge at the time of the event." }, "charge_id": { "type": "integer", "description": "The ID of the Charge the activity belongs to." }, "include": { "type": "object", "properties": { "payment_methods": { "type": "array", "items": {}, "description": "An array of PaymentMethods associated with the Charge of the activity." }, "charge": { "type": "object", "description": "The Charge the activity belongs to." } }, "description": "An object containing the related resources requested with the include query parameter." }, "updated_at": { "type": "string", "format": "date-time", "description": "The date and time when the charge activity was last updated." }, "created_at": { "type": "string", "format": "date-time", "description": "The date and time when the charge activity was created." }, "customer_id": { "type": "integer", "description": "The ID of the Customer the Charge belongs to." }, "external_payment_method_id": { "type": "string", "description": "The ID of the payment method as it appears in the payment processor system." }, "order_id": { "type": "integer", "description": "The ID of the Order associated with the activity, if any." }, "payment_method_id": { "type": "integer", "description": "The ID of the PaymentMethod used for the activity, if any." }, "payment_methods_info": { "type": "array", "items": { "type": "object", "properties": { "payment_method_id": { "type": "integer", "description": "The ID of the PaymentMethod ." }, "payment_type": { "type": "string", "description": "The type of the payment method, such as CREDIT_CARD or PAYPAL ." }, "brand": { "type": "string", "description": "The brand of the card." }, "last4": { "type": "string", "description": "The last four digits of the card or bank account." }, "exp_month": { "type": "integer", "description": "The expiration month of the card." }, "exp_year": { "type": "integer", "description": "The expiration year of the card." }, "paypal_email": { "type": "string", "description": "The email address of the PayPal account." } } }, "description": "An array describing the payment methods in use when the event was recorded." }, "store_id": { "type": "integer", "description": "The ID of the store the charge activity belongs to." } } }, "charge_object": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique numeric identifier for the Charge ." }, "address_id": { "type": "integer", "description": "The ID of the shipping Address tied to the Charge ." }, "analytics_data": { "type": "object", "properties": { "utm_params": { "type": "array", "items": { "type": "object", "properties": { "utm_campaign": { "type": "string", "description": "The UTM campaign." }, "utm_content": { "type": "string", "description": "The UTM content." }, "utm_data_source": { "type": "string", "description": "The source of the campaign parameter." }, "utm_source": { "type": "string", "description": "The UTM source." }, "utm_medium": { "type": "string", "description": "The UTM medium." }, "utm_term": { "type": "string", "description": "The UTM term." }, "utm_timestamp": { "type": "string", "description": "The UTM timestamp." } } }, "description": "An array containing utm_param objects." } }, "description": "An object containing analytics data associated with the Charge ." }, "billing_address": { "type": "object", "properties": { "address1": { "type": "string", "description": "Line one of the billing address." }, "address2": { "type": "string", "description": "Line two of the billing address." }, "city": { "type": "string", "description": "The city of the billing address." }, "company": { "type": "string", "description": "The company name of the billing address." }, "country_code": { "type": "string", "description": "2-letter country code." }, "first_name": { "type": "string", "description": "The first name of the billing address." }, "last_name": { "type": "string", "description": "The last name of the billing address." }, "phone": { "type": "string", "description": "The phone number of the billing address." }, "province": { "type": "string", "description": "The name of the province or state associated with the billing address." }, "zip": { "type": "string", "description": "The zip code or postcode of the address." } }, "description": "All the billing information related to the charge." }, "client_details": { "type": "object", "properties": { "browser_ip": { "type": "string", "description": "The IP address of the buyer as detected in Checkout ." }, "user_agent": { "type": "string", "description": "The user agent detected during Checkout ." } }, "description": "Details of the access method used by the purchaser." }, "external_variant_not_found": { "type": "string", "description": "The ID of the variant, as it appears in the external e-commerce platform, that could not be found when the Charge was processed." }, "has_uncommitted_changes": { "type": "boolean", "description": "Specifies whether the Charge is scheduled for a regeneration (if the Subscription related to the charge was updated in the last 5 seconds using commit=false )." }, "include": { "type": "object", "properties": { "address": { "type": "object", "description": "The Address associated with the Charge ." }, "bundle_selections": { "type": "object", "description": "The BundleSelection associated with the Charge ." }, "charge_activities": { "type": "array", "items": {}, "description": "An array of charge activity objects recorded for the Charge in the last 90 days." }, "credit_projection": { "type": "object", "properties": { "blocked_by_exclusion": { "type": "object", "description": "An object keyed by credit type. Each value contains amount , the additional credit that type would have contributed if no products were excluded, and excluded_product_ids , the external product IDs on the Charge that the credit type cannot be spent on." }, "capped_by_redemption_limit": { "type": "boolean", "description": "Whether the store's maximum redemption limit would hold back non-gift credit if the Customer opted in to applying credit." }, "currency_code": { "type": "string", "description": "The code of the currency the projected amounts are expressed in." }, "gift_to_apply": { "type": "string", "description": "The amount of gift credit the Charge is projected to redeem." }, "non_gift_to_apply": { "type": "string", "description": "The amount of non-gift credit the Charge is projected to redeem." }, "total_to_apply": { "type": "string", "description": "The total amount of credit the Charge will redeem if nothing changes." }, "total_to_apply_if_opted_in": { "type": "string", "description": "The total amount of credit the Charge would redeem if the Customer had apply_credit_to_next_recurring_charge set to true ." } }, "description": "The credits the Charge is projected to redeem when it processes, in the currency of the Charge . null when the Charge does not have a status of queued or error , or when the projection could not be built." }, "customer": { "type": "object", "description": "The Customer associated with the Charge ." }, "metafields": { "type": "array", "items": {}, "description": "An array of Metafields attached to the Charge ." }, "order_modifications": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique numeric identifier for the order modification." }, "charge_id": { "type": "integer", "description": "The ID of the Charge the modification applies to." }, "order_id": { "type": "integer", "description": "The ID of the Order the modification applies to." }, "customer_id": { "type": "integer", "description": "The ID of the Customer the modification belongs to." }, "modifications": { "type": "object", "properties": { "line_items": { "type": "array", "items": {}, "description": "An array of line item modifications. Each item contains line_item_id , subscription_id , modification_type , source , source_id , reason , reason_id and a modifications array of changed attributes ( attribute , value , previous_value , reason , created_at )." }, "move_is_allowed": { "type": "boolean", "description": "Whether the modification can be carried over to the new queued Charge when this Charge is replaced." }, "order_wide_changes": { "type": "array", "items": {}, "description": "An array of modifications that apply to the whole Charge rather than to a single line item." } }, "description": "An object containing the changes applied to the Charge ." }, "created_at": { "type": "string", "format": "date-time", "description": "The date and time when the order modification was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "The date and time when the order modification was last updated." } } }, "description": "An array of the modifications, such as added free gifts, applied to the Charge ." }, "payment_methods": { "type": "array", "items": {}, "description": "An array of PaymentMethods associated with the Charge ." }, "subscriptions": { "type": "array", "items": {}, "description": "An array of the Subscriptions contained in the Charge ." }, "transactions": { "type": "array", "items": { "type": "object", "properties": { "external_transaction_id": { "type": "string", "description": "The ID of the transaction in the payment processor system." }, "processor_name": { "type": "string", "description": "The payment processor used for the transaction." }, "amount": { "type": "string", "description": "The amount of the transaction." }, "kind": { "type": "string", "description": "The kind of transaction, such as sale or refund ." }, "payment_method_id": { "type": "integer", "description": "The ID of the PaymentMethod used for the transaction." }, "is_primary": { "type": "boolean", "description": "Whether the transaction is the primary transaction of the Charge ." }, "created_at": { "type": "string", "format": "date-time", "description": "The date and time when the transaction was created." } } }, "description": "An array of the payment transactions recorded for the Charge ." } }, "description": "An object containing the related resources requested with the include query parameter." }, "last_charge_attempt": { "type": "string", "format": "date-time", "description": "The date and time of the most recent attempt to process the Charge ." }, "merged_at": { "type": "string", "format": "date-time", "description": "The date and time when the Charge was last merged with another Charge ." }, "original_scheduled_at": { "type": "string", "format": "date", "description": "The date the Charge was scheduled to process when it was first created. This value does not change if the Charge is rescheduled." }, "total_duties": { "type": "string", "description": "The sum of all duties applied to the Charge ." }, "created_at": { "type": "string", "format": "date-time", "description": "The date and time when the transaction was created." }, "currency": { "type": "string", "description": "The code of the currency for this Charge , such as USD ." }, "customer": { "type": "object", "properties": { "id": { "type": "integer", "description": "The ID of the associated customer record." }, "email": { "type": "string", "description": "The user email." }, "external_customer_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "The customer ID as it appears in the external e-commerce platform." } }, "description": "An object containing customer information associated with this charge." }, "hash": { "type": "string", "description": "The hash of the Customer associated with the Charge ." } }, "description": "An object containing Customer information associated with this Charge ." }, "discounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "The ID of the Discount ." }, "code": { "type": "string", "description": "The code of the Discount ." }, "value": { "type": "number", "description": "The value of the Discount ." }, "value_type": { "type": "string", "description": "The type of the value of the Discount .", "enum": [ "percentage", "fixed_amount", "shipping" ] }, "title": { "type": "string", "description": "The title of the Discount ." }, "application_method": { "type": "string", "description": "How the Discount is applied, either through a code or automatically.", "enum": [ "code", "automatic" ] } } }, "description": "An array of Discounts associated with the Charge ." }, "error": { "type": "string", "description": "Error reason as sentence text (typically returned direct from the payment processor). e.g. \"error\": \"Customer needs to update credit card\"" }, "error_type": { "type": "string", "description": "Structured reason why the charge failed such as CUSTOMER_NEEDS_TO_UPDATE_CARD ." }, "charge_attempts": { "type": "integer", "description": "Shows how many times an attempt to charge was placed. Only returned when the Charge has a status of error ." }, "external_order_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "The order ID as it appears in the external e-commerce platform." } }, "description": "An object containing the associated external order ID." }, "external_transaction_id": { "type": "object", "properties": { "payment_processor": { "type": "string", "description": "The ID of the associated transaction in a payment processor system (like Stripe)." } }, "description": "An object containing the associated external transaction ID." }, "line_items": { "type": "array", "items": { "type": "object", "properties": { "external_line_item_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "The line item ID as it appears in the external e-commerce platform." } }, "description": "An object containing the ID of the associated line item as it appears in the external system." }, "offer_attributes": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of offer that added the line_item , such as free_gift ." }, "source": { "type": "string", "description": "The source of the offer that added the line_item ." } }, "description": "An object describing the offer that added the line_item to the Charge , such as a free gift. null when the line_item was not added by an offer." }, "purchase_item_id": { "type": "integer", "description": "The Subscription or Onetime ID associated with the line_item ." }, "external_product_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "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 ." } }, "description": "An object containing the associated product ID as it appears in the external system." }, "external_variant_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "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 ." } }, "description": "An object containing the associated variant ID as it appears in the external system." }, "grams": { "type": "integer", "description": "The weight of the item in grams." }, "handle": { "type": "string", "description": "A unique, human-friendly string for the Product ." }, "images": { "type": "object", "properties": { "large": { "type": "string", "description": "The url where a large image file is located." }, "medium": { "type": "string", "description": "The url where a medium image file is located." }, "small": { "type": "string", "description": "The url where a small image file is located." }, "original": { "type": "string", "description": "The url of the original sized product image." } }, "description": "An object containing URLs of the Product image." }, "original_price": { "type": "string", "description": "The original price of the line_item without discounts or taxes." }, "properties": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the property." }, "value": { "type": "string", "description": "The value of the property." } } }, "description": "An array of name value pairs of additional line_item attributes." }, "purchase_item_type": { "type": "string", "description": "An indicator of the type of the purchase item.", "enum": [ "subscription", "onetime" ] }, "quantity": { "type": "integer", "description": "The quantity of the line_item ." }, "sku": { "type": "string", "description": "The SKU (stock keeping unit) of the Product associated with the line_item ." }, "tax_due": { "type": "string", "description": "The total tax due associated with the line_item ." }, "tax_lines": { "type": "array", "items": { "type": "object", "properties": { "price": { "type": "string", "description": "The total tax associated with the listed jurisdiction." }, "rate": { "type": "string", "description": "The tax rate associated with the listed jurisdiction." }, "title": { "type": "string", "description": "The title/name of the taxing jurisdiction." }, "unit_price": { "type": "string", "description": "The tax per unit of the line_item associated with the listed jurisdiction." } } }, "description": "an array containing tax_line objects associated with this line_item ." }, "taxable": { "type": "boolean", "description": "A boolean indicating if the line_item is taxable or non-taxable." }, "taxable_amount": { "type": "string", "description": "The taxable revenue associated with the line_item ." }, "title": { "type": "string", "description": "The title of the Product of this line_item ." }, "total_price": { "type": "string", "description": "The total price of the line_item including tax." }, "unit_price": { "type": "string", "description": "The unit price of the line_item ." }, "unit_price_includes_tax": { "type": "boolean", "description": "A boolean indicator if tax is included in the price of an item." }, "variant_title": { "type": "string", "description": "The name of a variant of the Product of this line_item ." } } }, "description": "A list of line_item objects, each containing information about a distinct purchase item." }, "note": { "type": "string", "description": "Notes associated with the Charge ." }, "order_attributes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name for the attribute." }, "value": { "type": "string", "description": "The value for the associated attribute." } } }, "description": "An array of name-value pairs of order attributes on the Charge ." }, "orders_count": { "type": "integer", "description": "The number of Orders generated from this Charge (>1 for prepaid Subscriptions )." }, "payment_processor": { "type": "string", "description": "The payment processor used for this Charge ." }, "processed_at": { "type": "string", "format": "date-time", "description": "The date and time when the transaction was processed." }, "retry_date": { "type": "string", "format": "date-time", "description": "The date when the next attempt will be placed." }, "scheduled_at": { "type": "string", "format": "date", "description": "The date time of when the Charge is/was scheduled to process." }, "shipping_address": { "type": "object", "properties": { "address1": { "type": "string", "description": "Line one of the billing address." }, "address2": { "type": "string", "description": "Line two of the billing address." }, "city": { "type": "string", "description": "The city of the billing address." }, "company": { "type": "string", "description": "The company name of the billing address." }, "country_code": { "type": "string", "description": "2-letter country code." }, "first_name": { "type": "string", "description": "The first name of the billing address." }, "last_name": { "type": "string", "description": "The last name of the billing address." }, "phone": { "type": "string", "description": "The phone number of the billing address." }, "province": { "type": "string", "description": "The name of the province or state associated with the billing address." }, "zip": { "type": "string", "description": "The zip code or postcode of the address." } }, "description": "The shipping Address of the Charge ." }, "shipping_lines": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "The code associated with the shipping_line of a Charge ." }, "price": { "type": "string", "description": "The price of the shipping_line ." }, "source": { "type": "string", "description": "The source of the shipping_line ." }, "title": { "type": "string", "description": "The title of the shipping_line ." }, "taxable": { "type": "boolean", "description": "A boolean indicating if the shipping_line is taxable." }, "tax_lines": { "type": "array", "items": { "type": "object", "properties": { "price": { "type": "string", "description": "The total tax associated with the listed jurisdiction." }, "rate": { "type": "string", "description": "The tax rate associated with the listed jurisdiction." }, "title": { "type": "string", "description": "The title/name of the taxing jurisdiction." } } }, "description": "An array of tax lines associated with the shipping_line ." }, "rate": { "type": "string", "description": "The rate associated with the shipping_line ." }, "status": { "type": "string", "description": "The status of the shipping rate used for the shipping_line . Defaults to active .", "enum": [ "active", "pending", "queued" ] }, "retrieved_at": { "type": "string", "format": "date-time", "description": "The date and time when the shipping rate of the shipping_line was last retrieved." } } }, "description": "An array of shipping lines associated with the Charge ." }, "status": { "type": "string", "description": "The status of the Charge .", "enum": [ "success", "error", "queued", "skipped", "refunded", "partially_refunded", "pending_manual_payment", "pending" ] }, "subtotal_price": { "type": "string", "description": "The combined price of all line_items without taxes and shipping." }, "tags": { "type": "string", "description": "A comma-separated list of tags on the Charge ." }, "tax_lines": { "type": "array", "items": { "type": "object", "properties": { "price": { "type": "string", "description": "The total tax associated with the listed jurisdiction." }, "rate": { "type": "string", "description": "The tax rate associated with the listed jurisdiction." }, "title": { "type": "string", "description": "The title/name of the taxing jurisdiction." } } }, "description": "An array of tax lines that apply to the Charge ." }, "taxable": { "type": "boolean", "description": "A boolean indicator of the taxability of the Charge ." }, "taxes_included": { "type": "boolean", "description": "Whether taxes are included in the order subtotal." }, "total_discounts": { "type": "string", "description": "The sum of the Discounts applied to the Charge ." }, "total_line_items_price": { "type": "string", "description": "The total price of all line items of the Charge ." }, "total_price": { "type": "string", "description": "The sum of all the prices of all the items in the Charge , taxes and discounts included (must be positive)." }, "total_refunds": { "type": "string", "description": "The sum of all refunds that were applied to the Charge ." }, "total_tax": { "type": "string", "description": "The total tax due associated with the Charge ." }, "total_weight_grams": { "type": "integer", "description": "The total weight of the Charge ’s line items in grams." }, "type": { "type": "string", "description": "An indicator of the Charge ’s type, either checkout or recurring.", "enum": [ "checkout", "recurring" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "The date time at which the Charge was most recently updated." } } }, "checkout_object": { "type": "object", "properties": { "charge_id": { "type": "integer", "description": "ID for the Charge resulting from processing the Checkout ." }, "analytics_data": { "type": "object", "properties": { "utm_params": { "type": "array", "items": { "type": "object", "properties": { "utm_campaign": { "type": "string", "description": "The UTM campaign." }, "utm_content": { "type": "string", "description": "The UTM content." }, "utm_data_source": { "type": "string", "description": "The source of the campaign parameter." }, "utm_source": { "type": "string", "description": "The UTM source." }, "utm_medium": { "type": "string", "description": "The UTM medium." }, "utm_term": { "type": "string", "description": "The UTM term." }, "utm_timestamp": { "type": "string", "description": "The UTM timestamp." } } }, "description": "An array containing utm_param objects." } }, "description": "Urchin Tracking Module (UTM) parameters are used for online marketing campaigns." }, "applied_discounts": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string", "description": "Financial amount of the Discount applied." }, "applicable": { "type": "boolean", "description": "Whether the Discount can be applied to the Checkout ." }, "discount_code": { "type": "string", "description": "The code for the Discount , e.g. 25_PERCENT_OFF ." }, "non_redeemable_reason": { "type": "string", "description": "Reason why the Discount could not be redeemed, if applicable." }, "value": { "type": "string", "description": "The value of the Discount , used in combination with value_type to determine the amount." }, "value_type": { "type": "string", "description": "The way the Discount amount is calculated.", "enum": [ "fixed_amount", "shipping" ] } } }, "description": "Discount details, populated once the Discount has been applied successfully to the Checkout ." }, "applied_shipping_rate": { "type": "object", "properties": { "checkout": { "type": "object", "properties": { "subtotal_price": { "type": "string", "description": "Price excluding shipping and tax, including discounts." }, "total_price": { "type": "string", "description": "Total price including tax and shipping cost for that particular shipping rate." }, "total_tax": { "type": "string", "description": "Total tax value for the checkout." } }, "description": "Price details from the Checkout ." }, "code": { "type": "string", "description": "Code corresponding to the category of shipping." }, "delivery_range": { "type": "array", "items": {} }, "description": { "type": "string" }, "handle": { "type": "string", "description": "Unique string identifying the shipping/" }, "name": { "type": "string" }, "phone_required": { "type": "boolean", "description": "Whether a phone is required for this shipping." }, "price": { "type": "string", "description": "Price of shipping." }, "tax_lines": { "type": "array", "items": { "type": "object", "properties": { "price": { "type": "string", "description": "The total tax associated with the listed jurisdiction." }, "rate": { "type": "string", "description": "The tax rate associated with the listed jurisdiction." }, "title": { "type": "string", "description": "The title/name of the taxing jurisdiction." } } }, "description": "An array of tax_line objects for the tax charged on the shipping rate." }, "title": { "type": "string" } }, "description": "Shipping rates details, populated once the rates have been selected and applied successfully to the Checkout ." }, "available_shipping_rates": { "type": "array", "items": { "type": "object", "properties": { "checkout": { "type": "object", "properties": { "subtotal_price": { "type": "string", "description": "Price excluding shipping and tax, including discounts." }, "total_price": { "type": "string", "description": "Total price including tax and shipping cost for that particular shipping rate." }, "total_tax": { "type": "string", "description": "Total tax value for the checkout." } }, "description": "Price details from the Checkout ." }, "code": { "type": "string", "description": "Code corresponding to the category of shipping." }, "delivery_range": { "type": "array", "items": {} }, "description": { "type": "string" }, "handle": { "type": "string", "description": "Unique string identifying the shipping/" }, "name": { "type": "string" }, "phone_required": { "type": "boolean", "description": "Whether a phone is required for this shipping." }, "price": { "type": "string", "description": "Price of shipping." }, "tax_lines": { "type": "array", "items": { "type": "object", "properties": { "price": { "type": "string", "description": "The total tax associated with the listed jurisdiction." }, "rate": { "type": "string", "description": "The tax rate associated with the listed jurisdiction." }, "title": { "type": "string", "description": "The title/name of the taxing jurisdiction." } } }, "description": "An array of tax_line objects for the tax charged on the shipping rate." }, "title": { "type": "string" } } }, "description": "Shipping rates available for the shipping address provided in the Checkout ." }, "billing_address": { "type": "object", "properties": { "address1": { "type": "string", "description": "Line one of the billing address." }, "address2": { "type": "string", "description": "Line two of the billing address." }, "city": { "type": "string", "description": "The city of the billing address." }, "company": { "type": "string", "description": "The company name of the billing address." }, "country_code": { "type": "string", "description": "2-letter country code." }, "first_name": { "type": "string", "description": "The first name of the billing address." }, "last_name": { "type": "string", "description": "The last name of the billing address." }, "phone": { "type": "string", "description": "The phone number of the billing address." }, "province": { "type": "string", "description": "The name of the province or state associated with the billing address." }, "zip": { "type": "string", "description": "The zip code or postcode of the address." } }, "description": "Billing Address for the Checkout ." }, "completed_at": { "type": "string", "format": "date-time", "description": "Timestamp for when the Checkout was processed." }, "custom_shipping_rate_options": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Code for the shipping rate." }, "handle": { "type": "string", "description": "Unique identifier for the shipping rate." }, "price": { "type": "string", "description": "Price for the shipping rate." }, "title": { "type": "string", "description": "Title for the shipping rate." } } }, "description": "Custom shipping rates that were supplied for the Checkout and can be selected with applied_shipping_rate ." }, "payments": { "type": "array", "items": { "type": "object", "properties": { "payment_type": { "type": "string", "description": "The type of the additional payment method. Store credits are returned as STORED_VALUE ." }, "payment_processor": { "type": "string", "description": "The processor of the additional payment method, e.g. recharge_credits for store credits." }, "payment_token": { "type": "string", "description": "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_token": { "type": "string", "description": "The authorization token supplied for the payment method." }, "amount_applied": { "type": "string", "description": "The amount from this payment method that is applied to the Checkout total." }, "amount_available": { "type": "string", "description": "The balance available on the payment method. For store credits this is the balance remaining after amount_applied ." } } }, "description": "Additional payment methods, such as store credits or gift cards, that are applied to the Checkout total before the main payment method is charged." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp for when the Checkout was created." }, "currency": { "type": "string", "description": "Currency of the Checkout ." }, "email": { "type": "string", "description": "Email address for the Customer ." }, "external_checkout_id": { "type": "string", "description": "External checkout reference, if one exists." }, "external_checkout_source": { "type": "string", "description": "External checkout platform, if one exists.", "enum": [ "big_commerce", "headless", "magento", "shopify" ] }, "external_customer_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "The customer ID as it appears in the external e-commerce platform." }, "payment_processor": { "type": "string", "description": "The customer ID as it appears in the payment processor, populated once the Checkout has been processed." } }, "description": "External customer reference, if one exists." }, "external_transaction_id": { "type": "object", "properties": { "payment_processor": { "type": "string", "description": "The ID of the associated transaction in a payment processor system (like Stripe)." } }, "description": "The ID of the associated transaction in a payment processor system (like Stripe)." }, "line_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier of the line_item ." }, "external_inventory_policy": { "type": "string", "description": "The inventory policy configured for the store that applies to the line_item .", "enum": [ "bypass", "decrement_ignoring_policy", "decrement_obeying_policy" ] }, "external_line_item_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "The line item ID as it appears in the external e-commerce platform." } }, "description": "An object containing the ID of the line item as it appears in the external system." }, "external_product_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "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 ." } }, "description": "An object containing the associated product ID as it appears in the external system." }, "external_variant_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "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 ." } }, "description": "An object containing the associated variant ID as it appears in the external system." }, "handle": { "type": "string", "description": "A unique, human-friendly string for the Product associated with the line_item ." }, "images": { "type": "object", "properties": { "small": { "type": "string" } }, "description": "An object containing URLs of the Product image." }, "properties": { "type": "array", "items": {}, "description": "An array of name-value pairs of additional custom line_item attributes." }, "purchase_item_id": { "type": "integer", "description": "The Subscription or Onetime ID associated with the line_item ." }, "purchase_item_type": { "type": "string", "description": "The type of the purchase applied to the item.", "enum": [ "onetime", "subscription" ] }, "quantity": { "type": "integer", "description": "The quantity of the item being purchased." }, "recurring_unit_price": { "type": "string", "description": "The price of a single unit of the Product associated with the line_item that will be charged in recurring orders." }, "requires_shipping": { "type": "boolean", "description": "Whether the item requires shipping." }, "sku": { "type": "string", "description": "The SKU (stock keeping unit) of the Product associated with the line_item ." }, "subscription_preferences": { "type": "object", "properties": { "charge_interval_frequency": { "type": "integer", "description": "Frequency at which the subscriber will be charged." }, "cutoff_day_of_month": { "type": "integer", "description": "Day of the month the plan should be charged" }, "cutoff_day_of_week": { "type": "integer", "description": "Day of the month the plan should be charged" }, "expire_after_specific_number_of_charges": { "type": "integer", "description": "A maximum number of charges on which the subscription should appear before automatic cancellation." }, "order_day_of_month": { "type": "integer", "description": "Day of the month an order should be generated when the customer is subscribed." }, "order_day_of_week": { "type": "integer", "description": "Day of the week an order should be generated when the customer is subscribed." }, "order_interval_frequency": { "type": "integer", "description": "Frequency at which the subscriber will receive shipments when subscribed to this plan." }, "interval_unit": { "type": "string", "description": "The unit applied to charge_interval_frequency and order_interval_frequency .", "enum": [ "day", "week", "month" ] } }, "description": "An object containing the various subscription preferences associated with the line_item ." }, "tax_lines": { "type": "array", "items": { "type": "object", "properties": { "price": { "type": "string", "description": "The total tax associated with the listed jurisdiction." }, "rate": { "type": "string", "description": "The tax rate associated with the listed jurisdiction." }, "title": { "type": "string", "description": "The title/name of the taxing jurisdiction." }, "unit_price": { "type": "string", "description": "The tax for a single unit of the line_item for the listed jurisdiction." } } }, "description": "An array of tax_line objects associated with the line_item ." }, "taxable": { "type": "boolean", "description": "Whether tax is to be applied to the line_item" }, "title": { "type": "string", "description": "The title of the Product associated with the line_item ." }, "total_price": { "type": "string", "description": "The total price of the line_item including tax." }, "unit_price": { "type": "string", "description": "The price of a single unit of the Product associated with the line_item ." }, "variant_title": { "type": "string", "description": "The title of the Product variant associated with the line_item ." }, "weight": { "type": "integer", "description": "The weight of a single unit of the line_item , in grams." }, "weight_unit": { "type": "string", "description": "The weight unit configured for the store. weight is always expressed in grams regardless of this value.", "enum": [ "lb", "oz", "kg", "g", "t" ] } } }, "description": "A list of items included in the Checkout" }, "note": { "type": "string", "description": "Custom note." }, "notification_preferences": { "type": "object", "properties": { "email": { "type": "object", "properties": { "promotional": { "type": "object", "properties": { "last_opt_in_at": { "type": "string", "format": "date-time", "description": "The timestamp marking the last time the user opted in for the notification channel and type." }, "last_opt_in_source": { "type": "string", "description": "Details of the source interface or process of the last opt in.", "enum": [ "api", "bulk_update", "concierge", "customer_portal", "customer_sms", "merchant_portal", "recharge_checkout", "rechargesms_app", "sci_cart", "script", "shopify_checkout", "sms_reminder", "store_opt_in_widget", "subscription_checkout_extension", "thank_you_page" ] }, "last_opt_out_at": { "type": "string", "format": "date-time", "description": "The timestamp marking the last time the user opted out for the notification channel and type." }, "last_opt_out_source": { "type": "string", "description": "Details of the source interface or process of the last opt in.", "enum": [ "api", "bulk_update", "concierge", "customer_portal", "customer_sms", "merchant_portal", "recharge_checkout", "rechargesms_app", "sci_cart", "script", "shopify_checkout", "sms_reminder", "store_opt_in_widget", "subscription_checkout_extension", "thank_you_page" ] }, "status": { "type": "string", "description": "Status of the notification preferences.", "enum": [ "accepted", "declined" ], "default": "unspecified" } }, "description": "Details of a customer's notifications preferences for promotional communication on this channel." }, "replenishment": { "type": "object", "properties": { "last_opt_in_at": { "type": "string", "format": "date-time", "description": "The timestamp marking the last time the user opted in for the notification channel and type." }, "last_opt_in_source": { "type": "string", "description": "Details of the source interface or process of the last opt in.", "enum": [ "api", "bulk_update", "concierge", "customer_portal", "customer_sms", "merchant_portal", "recharge_checkout", "rechargesms_app", "sci_cart", "script", "shopify_checkout", "sms_reminder", "store_opt_in_widget", "subscription_checkout_extension", "thank_you_page" ] }, "last_opt_out_at": { "type": "string", "format": "date-time", "description": "The timestamp marking the last time the user opted out for the notification channel and type." }, "last_opt_out_source": { "type": "string", "description": "Details of the source interface or process of the last opt in.", "enum": [ "api", "bulk_update", "concierge", "customer_portal", "customer_sms", "merchant_portal", "recharge_checkout", "rechargesms_app", "sci_cart", "script", "shopify_checkout", "sms_reminder", "store_opt_in_widget", "subscription_checkout_extension", "thank_you_page" ] }, "status": { "type": "string", "description": "Status of the notification preferences.", "enum": [ "accepted", "declined" ], "default": "unspecified" } }, "description": "Details of a customer's notifications preferences for replenishment communication on this channel." }, "transactional": { "type": "object", "properties": { "last_opt_in_at": { "type": "string", "format": "date-time", "description": "The timestamp marking the last time the user opted in for the notification channel and type." }, "last_opt_in_source": { "type": "string", "description": "Details of the source interface or process of the last opt in.", "enum": [ "api", "bulk_update", "concierge", "customer_portal", "customer_sms", "merchant_portal", "recharge_checkout", "rechargesms_app", "sci_cart", "script", "shopify_checkout", "sms_reminder", "store_opt_in_widget", "subscription_checkout_extension", "thank_you_page" ] }, "last_opt_out_at": { "type": "string", "format": "date-time", "description": "The timestamp marking the last time the user opted out for the notification channel and type." }, "last_opt_out_source": { "type": "string", "description": "Details of the source interface or process of the last opt in.", "enum": [ "api", "bulk_update", "concierge", "customer_portal", "customer_sms", "merchant_portal", "recharge_checkout", "rechargesms_app", "sci_cart", "script", "shopify_checkout", "sms_reminder", "store_opt_in_widget", "subscription_checkout_extension", "thank_you_page" ] }, "status": { "type": "string", "description": "Status of the notification preferences.", "enum": [ "accepted", "declined" ], "default": "unspecified" } }, "description": "Details of a customer's notifications preferences for transactional communication on this channel." } }, "description": "Details of a customer's notifications preferences for emails." }, "sms": { "type": "object", "properties": { "promotional": { "type": "object", "properties": { "last_opt_in_at": { "type": "string", "format": "date-time", "description": "The timestamp marking the last time the user opted in for the notification channel and type." }, "last_opt_in_source": { "type": "string", "description": "Details of the source interface or process of the last opt in.", "enum": [ "api", "bulk_update", "concierge", "customer_portal", "customer_sms", "merchant_portal", "recharge_checkout", "rechargesms_app", "sci_cart", "script", "shopify_checkout", "sms_reminder", "store_opt_in_widget", "subscription_checkout_extension", "thank_you_page" ] }, "last_opt_out_at": { "type": "string", "format": "date-time", "description": "The timestamp marking the last time the user opted out for the notification channel and type." }, "last_opt_out_source": { "type": "string", "description": "Details of the source interface or process of the last opt in.", "enum": [ "api", "bulk_update", "concierge", "customer_portal", "customer_sms", "merchant_portal", "recharge_checkout", "rechargesms_app", "sci_cart", "script", "shopify_checkout", "sms_reminder", "store_opt_in_widget", "subscription_checkout_extension", "thank_you_page" ] }, "status": { "type": "string", "description": "Status of the notification preferences.", "enum": [ "accepted", "declined" ], "default": "unspecified" } }, "description": "Details of a customer's notifications preferences for promotional communication on this channel." }, "replenishment": { "type": "object", "properties": { "last_opt_in_at": { "type": "string", "format": "date-time", "description": "The timestamp marking the last time the user opted in for the notification channel and type." }, "last_opt_in_source": { "type": "string", "description": "Details of the source interface or process of the last opt in.", "enum": [ "api", "bulk_update", "concierge", "customer_portal", "customer_sms", "merchant_portal", "recharge_checkout", "rechargesms_app", "sci_cart", "script", "shopify_checkout", "sms_reminder", "store_opt_in_widget", "subscription_checkout_extension", "thank_you_page" ] }, "last_opt_out_at": { "type": "string", "format": "date-time", "description": "The timestamp marking the last time the user opted out for the notification channel and type." }, "last_opt_out_source": { "type": "string", "description": "Details of the source interface or process of the last opt in.", "enum": [ "api", "bulk_update", "concierge", "customer_portal", "customer_sms", "merchant_portal", "recharge_checkout", "rechargesms_app", "sci_cart", "script", "shopify_checkout", "sms_reminder", "store_opt_in_widget", "subscription_checkout_extension", "thank_you_page" ] }, "status": { "type": "string", "description": "Status of the notification preferences.", "enum": [ "accepted", "declined" ], "default": "unspecified" } }, "description": "Details of a customer's notifications preferences for replenishment communication on this channel." }, "transactional": { "type": "object", "properties": { "last_opt_in_at": { "type": "string", "format": "date-time", "description": "The timestamp marking the last time the user opted in for the notification channel and type." }, "last_opt_in_source": { "type": "string", "description": "Details of the source interface or process of the last opt in.", "enum": [ "api", "bulk_update", "concierge", "customer_portal", "customer_sms", "merchant_portal", "recharge_checkout", "rechargesms_app", "sci_cart", "script", "shopify_checkout", "sms_reminder", "store_opt_in_widget", "subscription_checkout_extension", "thank_you_page" ] }, "last_opt_out_at": { "type": "string", "format": "date-time", "description": "The timestamp marking the last time the user opted out for the notification channel and type." }, "last_opt_out_source": { "type": "string", "description": "Details of the source interface or process of the last opt in.", "enum": [ "api", "bulk_update", "concierge", "customer_portal", "customer_sms", "merchant_portal", "recharge_checkout", "rechargesms_app", "sci_cart", "script", "shopify_checkout", "sms_reminder", "store_opt_in_widget", "subscription_checkout_extension", "thank_you_page" ] }, "status": { "type": "string", "description": "Status of the notification preferences.", "enum": [ "accepted", "declined" ], "default": "unspecified" } }, "description": "Details of a customer's notifications preferences for transactional communication on this channel." } }, "description": "Details of a customer's notifications preferences for sms." } }, "description": "Notification preferences for the Customer ." }, "order_attributes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name for the attribute." }, "value": { "type": "string", "description": "The value for the associated attribute." } } }, "description": "List of name-value pairs for custom attributes." }, "payment_processor": { "type": "string", "description": "Name of the payment processor." }, "requires_shipping": { "type": "boolean", "description": "Whether or not the Checkout contains items that require shipping." }, "shipping_address": { "type": "object", "properties": { "address1": { "type": "string", "description": "Line one of the billing address." }, "address2": { "type": "string", "description": "Line two of the billing address." }, "city": { "type": "string", "description": "The city of the billing address." }, "company": { "type": "string", "description": "The company name of the billing address." }, "country_code": { "type": "string", "description": "2-letter country code." }, "first_name": { "type": "string", "description": "The first name of the billing address." }, "last_name": { "type": "string", "description": "The last name of the billing address." }, "phone": { "type": "string", "description": "The phone number of the billing address." }, "province": { "type": "string", "description": "The name of the province or state associated with the billing address." }, "shipping_lines_override": { "type": "array", "items": {}, "description": "Shipping lines that will be set as the shipping lines override of the Address created when the Checkout is processed." }, "zip": { "type": "string", "description": "The zip code or postcode of the address." } }, "description": "Shipping Address for the Checkout ." }, "shipping_lines": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "The code associated with the shipping_line ." }, "price": { "type": "string", "description": "The price of the shipping_line ." }, "rate": { "type": "string", "description": "The rate of the shipping_line ." }, "source": { "type": "string", "description": "The source of the shipping_line ." }, "tax_lines": { "type": "array", "items": { "type": "object", "properties": { "price": { "type": "string", "description": "The total tax associated with the listed jurisdiction." }, "rate": { "type": "string", "description": "The tax rate associated with the listed jurisdiction." }, "title": { "type": "string", "description": "The title/name of the taxing jurisdiction." } } }, "description": "An array of tax lines associated with the shipping_line ." }, "taxable": { "type": "boolean", "description": "Whether tax was charged on the shipping_line ." }, "title": { "type": "string", "description": "The title of the shipping_line ." } } }, "description": "Details of shipping rate, cost..." }, "subtotal_price": { "type": "string", "description": "Value of the Checkout minus shipping and tax." }, "tax_lines": { "type": "array", "items": { "type": "object", "properties": { "price": { "type": "string", "description": "The total tax associated with the listed jurisdiction." }, "rate": { "type": "string", "description": "The tax rate associated with the listed jurisdiction." }, "title": { "type": "string", "description": "The title/name of the taxing jurisdiction." } } }, "description": "Array of tax_line objects." }, "taxable": { "type": "boolean", "description": "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_included": { "type": "boolean", "description": "Whether the tax is included in the price of the items." }, "token": { "type": "string", "description": "Unique token for the Checkout ." }, "total_price": { "type": "string", "description": "Full price of the Checkout including shipping and tax." }, "total_tax": { "type": "string", "description": "Tax charged on the Checkout ." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp for the latest Checkout update." } } }, "collection_object": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique numeric identifier for the Collection ." }, "manual_sort_order": { "type": "array", "items": {}, "description": "The manual order of the Products in the Collection , as an array of external_product_id values." }, "created_at": { "type": "string", "format": "date-time", "description": "The date and time when the Collection was created." }, "description": { "type": "string", "description": "The Collection description. Used to store a detailed explanation of the Collection content and its purpose." }, "sort_order": { "type": "string", "description": "The order in which the Products in the collection should appear.", "enum": [ "id-asc", "id-desc", "created_at-asc", "created_at-desc", "updated_at-asc", "updated_at-desc", "title-asc", "title-desc", "manual" ] }, "title": { "type": "string", "description": "The title of the Collection . A short descriptive definition of the Collection ." }, "type": { "type": "string", "description": "The type of the Collection .", "enum": [ "automatic", "manual" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "The date and time when the Collection was last updated." } } }, "credit_account_object": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique numeric identifier for the Credit Account" }, "customer_id": { "type": "integer", "description": "Unique numeric identifier for the customer associated with the credit_account ." }, "available_balance": { "type": "string", "description": "The dollar amount of available credit in the credit account, in the associated Store’s default currency as configured in Recharge" }, "created_at": { "type": "string", "format": "date-time", "description": "The date and time at which the credit account was created." }, "currency_code": { "type": "string", "description": "The currency code for the credit account." }, "expires_at": { "type": "string", "format": "date-time", "description": "The date and time at which the credit account expires, and can no longer be adjusted." }, "initial_value": { "type": "string", "description": "The initial value of the credit account at the time of creation." }, "name": { "type": "string", "description": "The name of the credit account" }, "type": { "type": "string", "description": "The type of the credit account. Accepted values are rewards and manual .", "enum": [ "manual", "reward", "referral", "gift" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "The date and time at which the credit account was last updated." }, "include": { "type": "object", "properties": { "customer": { "type": "object", "description": "The Customer associated with the credit account." } }, "description": "An object containing the related resources requested with the include query parameter." } } }, "customer_notification_preferences_object": { "type": "object", "properties": { "email": { "type": "object", "properties": { "transactional": { "type": "object", "properties": { "status": { "type": "string", "description": "Status of the notification preference. unspecified when the customer has never opted in or out.", "enum": [ "accepted", "declined", "unspecified" ] }, "last_opt_in_at": { "type": "string", "format": "date-time", "description": "The date and time when the customer last opted in." }, "last_opt_in_source": { "type": "string", "description": "The interface or process through which the customer last opted in." }, "last_opt_out_at": { "type": "string", "format": "date-time", "description": "The date and time when the customer last opted out." }, "last_opt_out_source": { "type": "string", "description": "The interface or process through which the customer last opted out." } }, "description": "Details of the customer's notification preferences for transactional communication on this channel." }, "promotional": { "type": "object", "properties": { "status": { "type": "string", "description": "Status of the notification preference. unspecified when the customer has never opted in or out.", "enum": [ "accepted", "declined", "unspecified" ] }, "last_opt_in_at": { "type": "string", "format": "date-time", "description": "The date and time when the customer last opted in." }, "last_opt_in_source": { "type": "string", "description": "The interface or process through which the customer last opted in." }, "last_opt_out_at": { "type": "string", "format": "date-time", "description": "The date and time when the customer last opted out." }, "last_opt_out_source": { "type": "string", "description": "The interface or process through which the customer last opted out." } }, "description": "Details of the customer's notification preferences for promotional communication on this channel." }, "replenishment": { "type": "object", "properties": { "status": { "type": "string", "description": "Status of the notification preference. unspecified when the customer has never opted in or out.", "enum": [ "accepted", "declined", "unspecified" ] }, "last_opt_in_at": { "type": "string", "format": "date-time", "description": "The date and time when the customer last opted in." }, "last_opt_in_source": { "type": "string", "description": "The interface or process through which the customer last opted in." }, "last_opt_out_at": { "type": "string", "format": "date-time", "description": "The date and time when the customer last opted out." }, "last_opt_out_source": { "type": "string", "description": "The interface or process through which the customer last opted out." } }, "description": "Details of the customer's notification preferences for replenishment communication on this channel." } }, "description": "Details of the customer's notification preferences for email." }, "sms": { "type": "object", "properties": { "transactional": { "type": "object", "properties": { "status": { "type": "string", "description": "Status of the notification preference. unspecified when the customer has never opted in or out.", "enum": [ "accepted", "declined", "unspecified" ] }, "last_opt_in_at": { "type": "string", "format": "date-time", "description": "The date and time when the customer last opted in." }, "last_opt_in_source": { "type": "string", "description": "The interface or process through which the customer last opted in." }, "last_opt_out_at": { "type": "string", "format": "date-time", "description": "The date and time when the customer last opted out." }, "last_opt_out_source": { "type": "string", "description": "The interface or process through which the customer last opted out." } }, "description": "Details of the customer's notification preferences for transactional communication on this channel." }, "promotional": { "type": "object", "properties": { "status": { "type": "string", "description": "Status of the notification preference. unspecified when the customer has never opted in or out.", "enum": [ "accepted", "declined", "unspecified" ] }, "last_opt_in_at": { "type": "string", "format": "date-time", "description": "The date and time when the customer last opted in." }, "last_opt_in_source": { "type": "string", "description": "The interface or process through which the customer last opted in." }, "last_opt_out_at": { "type": "string", "format": "date-time", "description": "The date and time when the customer last opted out." }, "last_opt_out_source": { "type": "string", "description": "The interface or process through which the customer last opted out." } }, "description": "Details of the customer's notification preferences for promotional communication on this channel." }, "replenishment": { "type": "object", "properties": { "status": { "type": "string", "description": "Status of the notification preference. unspecified when the customer has never opted in or out.", "enum": [ "accepted", "declined", "unspecified" ] }, "last_opt_in_at": { "type": "string", "format": "date-time", "description": "The date and time when the customer last opted in." }, "last_opt_in_source": { "type": "string", "description": "The interface or process through which the customer last opted in." }, "last_opt_out_at": { "type": "string", "format": "date-time", "description": "The date and time when the customer last opted out." }, "last_opt_out_source": { "type": "string", "description": "The interface or process through which the customer last opted out." } }, "description": "Details of the customer's notification preferences for replenishment communication on this channel." } }, "description": "Details of the customer's notification preferences for SMS." } } }, "customer_session_object": { "type": "object", "properties": { "apiToken": { "type": "string", "description": "The session token scoped to the Customer ." }, "customerId": { "type": "integer", "description": "Unique numeric identifier for the Customer the session was created for." }, "admin_email": { "type": "string", "description": "The email address of the store user the session was created for." } } }, "customers_object": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique numeric identifier for the Customer ." }, "analytics_data": { "type": "object", "properties": { "utm_params": { "type": "array", "items": { "type": "object", "properties": { "utm_campaign": { "type": "string", "description": "The UTM campaign." }, "utm_content": { "type": "string", "description": "The UTM content." }, "utm_data_source": { "type": "string", "description": "The source of the campaign parameter." }, "utm_source": { "type": "string", "description": "The UTM source." }, "utm_medium": { "type": "string", "description": "The UTM medium." }, "utm_term": { "type": "string", "description": "The UTM term." }, "utm_timestamp": { "type": "string", "description": "The UTM timestamp." } } }, "description": "An array containing utm_param objects." } }, "description": "An object containing analytics data associated with the customer." }, "apply_credit_to_next_checkout_charge": { "type": "boolean", "description": "A boolean that indicates whether Recharge credits will be applied to the next checkout charge." }, "apply_credit_to_next_recurring_charge": { "type": "boolean", "description": "A boolean that indicates whether Recharge credits will be applied to the next recurring charge." }, "backup_payment_methods_enabled": { "type": "boolean", "description": "A boolean that indicates whether backup payment methods can be used for the customer when a charge fails. null when no preference has been set for the customer, in which case the store's default applies." }, "can_add_payment_method": { "type": "boolean", "description": "A boolean that indicates whether a payment method can be added to the customer in Recharge." }, "include": { "type": "object", "properties": { "addresses": { "type": "array", "items": {}, "description": "The Addresses associated with the Customer . Returned when include contains addresses ." }, "announcements": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique numeric identifier for the announcement." }, "customer_id": { "type": "integer", "description": "Unique numeric identifier for the Customer the announcement is for." }, "flow_id": { "type": "integer", "description": "Unique numeric identifier for the flow that created the announcement." }, "view_schema": { "type": "object", "description": "An object describing the content of the announcement shown in the customer portal." }, "created_at": { "type": "string", "format": "date-time", "description": "The date and time when the announcement was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "The date and time when the announcement was last updated." } } }, "description": "The most recent customer portal announcement for the Customer . Returned when include contains announcements ." }, "gift_purchases": { "type": "array", "items": {}, "description": "The gift purchases for which the Customer is the recipient. Returned when include contains gift_purchases . Requires the read_gift_purchases scope." }, "memberships": { "type": "array", "items": { "type": "object", "properties": { "membership_program_name": { "type": "string", "description": "The name of the membership program the membership belongs to." }, "membership_program_type": { "type": "string", "description": "The type of the membership program the membership belongs to." } } }, "description": "The memberships of the Customer . Returned when include contains memberships . Requires the read_memberships scope." }, "metafields": { "type": "array", "items": {}, "description": "The Metafields owned by the Customer . Returned when include contains metafields ." }, "payment_methods": { "type": "array", "items": {}, "description": "The Payment Methods of the Customer . Returned when include contains payment_methods . Requires the read_payment_methods scope." }, "punch_card_progress": { "type": "object", "description": "An object keyed by punch card id that contains the progress of the Customer in each punch card: punch_card_order_count , punch_card_streak_count , punch_card_total_order_value_in_store_currency and the punch_card_previous_* values recorded before the latest order. Returned when include contains punch_card_progress ." }, "referral_info": { "type": "object", "properties": { "referral_url": { "type": "object", "properties": { "url": { "type": "string", "description": "The URL the Customer can share to refer others." }, "slug": { "type": "string", "description": "The unique identifier of the Customer used in the referral URL." } }, "description": "The referral link of the Customer . Empty when the store has no active referral program." } }, "description": "An object containing referral information for the Customer . Returned when include contains referral_info ." }, "subscriptions": { "type": "array", "items": {}, "description": "The Subscriptions of the Customer . Returned when include contains subscriptions . Requires the read_subscriptions scope." } }, "description": "An object containing the related resources requested with the include query parameter." }, "memberships_active_count": { "type": "integer", "description": "The number of active memberships the customer has." }, "memberships_total_count": { "type": "integer", "description": "The total number of memberships created for the customer." }, "payment_method_fallback_on_failure_disabled": { "type": "boolean", "description": "A boolean that indicates whether falling back to the customer's default payment method with the payment processor is disabled when a charge on the assigned payment method fails." }, "recharge_lifetime_value_total_amount_store_default_currency": { "type": "string", "description": "The lifetime value of the customer in Recharge, expressed in the store's default currency." }, "total_processed_charge_count": { "type": "integer", "description": "The total number of charges successfully processed for the customer." }, "created_at": { "type": "string", "format": "date-time", "description": "The date and time when the customer was created." }, "email": { "type": "string", "description": "The email address of the customer." }, "external_customer_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "The customer ID as it appears in the external e-commerce platform." } }, "description": "An object containing external ids for the customer record." }, "first_charge_processed_at": { "type": "string", "format": "date-time", "description": "Date when first charge was processed for the customer." }, "first_name": { "type": "string", "description": "The customer’s first name." }, "has_payment_method_in_dunning": { "type": "boolean", "description": "A boolean that indicates if the customer has a payment method that is in dunning (failed charge)." }, "has_valid_payment_method": { "type": "boolean", "description": "Is the payment method valid or not." }, "hash": { "type": "string", "description": "The unique string identifier used in a customers portal link." }, "last_name": { "type": "string", "description": "The customer’s last name." }, "phone": { "type": "string", "description": "The customer's phone number." }, "subscriptions_active_count": { "type": "integer", "description": "The number of active subscriptions on addresses associated with the customer." }, "subscriptions_total_count": { "type": "integer", "description": "The total number of subscriptions created on addresses associated with the customer." }, "subscription_related_charge_streak": { "type": "integer", "description": "The number of consecutive subscription-related charges processed for this customer, while they retain at least one active subscription. When all subscriptions for this customer are cancelled or expired, this value will reset to zero." }, "tax_exempt": { "type": "boolean", "description": "Whether the customer tax exempt or not." }, "updated_at": { "type": "string", "format": "date-time", "description": "The date and time when the customer was last updated." } } }, "discounts_object": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique numeric identifier for the discount in Recharge." }, "application_method": { "type": "string", "description": "How the discount is applied. code discounts are applied with a discount code and automatic discounts are applied without one.", "enum": [ "code", "automatic" ] }, "applies_to": { "type": "object", "properties": { "ids": { "type": "array", "items": {}, "description": "A list of ids of the type indicated in applies_to.resource for which the discount can be applied. Currently only supports a list with one value." }, "purchase_item_type": { "type": "string", "description": "An indicator of whether the discount applies to onetimes, subscriptions, or all purchase item types.", "enum": [ "ALL", "ONETIME", "SUBSCRIPTION" ] }, "resource": { "type": "string", "description": "An indicator of the type of resource to which applies_to_id refers.", "enum": [ "shopify_product", "shopify_collection_id", "collection_id" ] } }, "description": "An object encompassing data that limits discount application on the basis of an associated record (such as customer, products, etc.)." }, "applies_to_existing_addresses": { "type": "boolean", "description": "Whether the discount applies to addresses that already exist. Can only be false for automatic discounts." }, "channel_settings": { "type": "object", "properties": { "api": { "type": "object", "properties": { "can_apply": { "type": "boolean", "description": "A boolean to indicate if the discount may be applied using the associated channel (defaults to true for all channels).", "default": true } }, "description": "An object containing api channel settings." }, "customer_portal": { "type": "object", "properties": { "can_apply": { "type": "boolean", "description": "A boolean to indicate if the discount may be applied using the associated channel (defaults to true for all channels).", "default": true } }, "description": "An object containing customer portal channel settings." }, "merchant_portal": { "type": "object", "properties": { "can_apply": { "type": "boolean", "description": "A boolean to indicate if the discount may be applied using the associated channel (defaults to true for all channels).", "default": true } }, "description": "An object containing merchant portal channel settings." }, "checkout_page": { "type": "object", "properties": { "can_apply": { "type": "boolean", "description": "A boolean to indicate if the discount may be applied using the associated channel (defaults to true for all channels).", "default": true } }, "description": "An object containing checkout channel settings." } }, "description": "A list of channel objects containing information regarding discount behaviors for each. If you're on the SCI Platform, checkout channel will not apply during Shopify checkouts." }, "code": { "type": "string", "description": "The code used to apply the discount." }, "customer_segments": { "type": "array", "items": { "type": "object", "properties": { "customer_segment_id": { "type": "integer", "description": "Unique numeric identifier for the customer segment." } } }, "description": "A list of the customer segments linked to the discount. Empty when the discount is not linked to any customer segment." }, "external_discount_source": { "type": "string", "description": "The external platform that the external_discount_id belongs to.", "enum": [ "big_commerce", "shopify", "recharge", "headless", "magento" ] }, "title": { "type": "string", "description": "The title of the discount. For automatic discounts the title is also returned as the code ." }, "created_at": { "type": "string", "format": "date-time", "description": "The date and time when the discount was created." }, "ends_at": { "type": "string", "format": "date-time", "description": "The expiration timestamp of the discount. Past this time the Discount can no longer be redeemed. After ends_at the status of the Discount will go from active to disabled ." }, "external_discount_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "The discount id as it appears in the external e-commerce platform." } }, "description": "An object containing external ids of the discount." }, "prerequisite_subtotal_min": { "type": "string", "description": "The minimum cart subtotal needed for the discount to be applicable." }, "starts_at": { "type": "string", "format": "date-time", "description": "The date when the discount becomes active." }, "status": { "type": "string", "description": "The status of the discount. Value can be: * enabled discount is active to be applied * disabled discount can’t be applied on new purchases. Discount will remain on existing charges to which it has already been applied. * fully_disabled discount can no longer be applied. In addition, Discount is removed from every queued charge.", "enum": [ "enabled", "disabled", "fully_disabled" ] }, "usage_limits": { "type": "object", "properties": { "one_application_per_customer": { "type": "boolean", "description": "The discount can only be used once for a given customer checkout or manually applied once on the customer portal (irrespective of which address). Once applied, it will continue being re-applied to each new charge on the address." }, "first_time_customer_restriction": { "type": "boolean", "description": "Discount can be used on checkout for customer that still don’t exist in Recharge database." }, "max_subsequent_redemptions": { "type": "integer", "description": "The number of Charges the Discount will apply to besides the initial redemption for a given Customer . For example, if you want a discount to apply for 5 consecutive charges max_subsequent_redemptions should be 4." }, "redemptions": { "type": "integer", "description": "Sets the limit on the number of times a discount can be used by all customers. Only returned for stores that have legacy discount usage limits enabled." }, "automatic_redemptions_per_customer": { "type": "integer", "description": "The 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." } }, "description": "An object containing limitations on a discount based on usage_counts results" }, "updated_at": { "type": "string", "format": "date-time", "description": "The date and time when the discount was last updated." }, "value": { "type": "string", "description": "The discounted value to be applied." }, "value_type": { "type": "string", "description": "Type of discount mechanic.", "enum": [ "fixed_amount", "percentage", "shipping" ] } } }, "customer_entitlement_object": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique numeric identifier for the customer entitlement." }, "customer_id": { "type": "integer", "description": "Unique numeric identifier for the customer associated with this entitlement." }, "entitlement_feature_id": { "type": "integer", "description": "Unique numeric identifier for the entitlement feature being granted." }, "granted_by_id": { "type": "string", "description": "The ID of the entity that granted this entitlement (e.g. the purchase item ID or API token ID)." }, "granted_by_type": { "type": "string", "description": "How the entitlement was granted to the customer.", "enum": [ "purchase_item", "api", "user", "store_owner", "recharge_staff_user_email", "internal" ] }, "expires_at": { "type": "string", "format": "date-time", "description": "The date and time at which the entitlement expires. If null, the entitlement does not expire." }, "created_at": { "type": "string", "format": "date-time", "description": "The date and time at which the customer entitlement was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "The date and time at which the customer entitlement was last updated." }, "deleted_at": { "type": "string", "format": "date-time", "description": "The date and time at which the customer entitlement was deleted. If null, the entitlement has not been deleted." }, "include": { "type": "object", "properties": { "entitlement_feature": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique numeric identifier for the entitlement feature." }, "lookup_key": { "type": "string", "description": "A unique key that identifies the entitlement feature." }, "name": { "type": "string", "description": "The name of the entitlement feature." }, "description": { "type": "string", "description": "The description of the entitlement feature." }, "created_at": { "type": "string", "format": "date-time", "description": "The date and time at which the entitlement feature was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "The date and time at which the entitlement feature was last updated." }, "deleted_at": { "type": "string", "format": "date-time", "description": "The date and time at which the entitlement feature was deleted. If null, the entitlement feature has not been deleted." } }, "description": "The entitlement feature granted by the customer entitlement." } }, "description": "An object containing the related resources requested with the include query parameter." } } }, "gift_purchase_object": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique numeric identifier for the Gift purchase ." }, "amount": { "type": "string", "description": "The value of the gift." }, "gift_currency": { "type": "string", "description": "The currency code of the gift." }, "credit_account_id": { "type": "integer", "description": "Unique numeric identifier for the Credit account that holds the value of the gift." }, "sender_customer_id": { "type": "integer", "description": "Unique numeric identifier for the Customer who purchased the gift." }, "sender_name": { "type": "string", "description": "The name of the person who purchased the gift, as shown to the recipient." }, "recipient_customer_id": { "type": "integer", "description": "Unique numeric identifier for the Customer who receives the gift." }, "gift_note": { "type": "string", "description": "The note from the sender to the recipient." }, "redemption_link": { "type": "string", "description": "The URL the recipient uses to redeem the gift." }, "redeemable_collection_id": { "type": "integer", "description": "Unique numeric identifier for the Collection of products the gift can be redeemed for." }, "external_gift_product_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "The product ID in the external e-commerce platform." } }, "description": "The product purchased as a gift." }, "external_gift_variant_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "The variant ID in the external e-commerce platform." } }, "description": "The variant purchased as a gift." }, "external_order_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "The order ID in the external e-commerce platform." } }, "description": "The order in which the gift was purchased." }, "external_redeemable_product_ids": { "type": "array", "items": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "The product ID in the external e-commerce platform." } } }, "description": "The products the gift can be redeemed for." }, "notification_scheduled_at": { "type": "string", "format": "date-time", "description": "The date and time when the gift notification is scheduled to be sent to the recipient." }, "notification_sent_at": { "type": "string", "format": "date-time", "description": "The date and time when the gift notification was sent to the recipient." }, "redeemed_at": { "type": "string", "format": "date-time", "description": "The date and time when the gift was redeemed. null when it has not been redeemed yet." }, "created_at": { "type": "string", "format": "date-time", "description": "The date and time when the Gift purchase was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "The date and time when the Gift purchase was last updated." } } }, "metafields_object": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique numeric identifier for the metafield." }, "created_at": { "type": "string", "format": "date-time", "description": "The date and time when the metafield was created." }, "description": { "type": "string", "description": "Description of the metafield." }, "key": { "type": "string", "description": "The name of the metafield." }, "namespace": { "type": "string", "description": "A category or container that differentiates your metadata from other metafields." }, "owner_id": { "type": "integer", "description": "Unique numeric identifier of the owner_resource ." }, "owner_resource": { "type": "string", "description": "Objects which support Metafields", "enum": [ "address", "store", "customer", "subscription", "order", "charge" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "The date and time when the metafield was last updated." }, "value": { "type": "string", "description": "The content of the metafield." }, "value_type": { "type": "string", "description": "The type of the value parameter.", "enum": [ "string", "integer", "json_string" ] } } }, "onetimes_object": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique numeric identifier for the Onetime purchase." }, "address_id": { "type": "integer", "description": "Unique numeric identifier for the address the Onetime Purchase is associated with (cannot be used with next_charge_scheduled_at )" }, "include": { "type": "object", "properties": { "address": { "type": "object", "description": "The Address the Onetime is associated with." }, "bundle_product": { "type": "object", "description": "The bundle product that matches the product of the Onetime . null if the product is not a bundle." }, "bundle_selections": { "type": "object", "description": "The BundleSelection linked to the Onetime . null if there is none." }, "charge_activities": { "type": "array", "items": {}, "description": "The charge activity records created in the last 90 days for the Charges that contain the Onetime ." }, "customer": { "type": "object", "description": "The Customer the Onetime is tied to." }, "customer_entitlements": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique numeric identifier for the customer entitlement." }, "description": { "type": "string", "description": "The description of the entitlement feature." }, "expires_at": { "type": "string", "format": "date-time", "description": "The time the entitlement expires. null if it does not expire." }, "lookup_key": { "type": "string", "description": "The lookup key of the entitlement feature." }, "name": { "type": "string", "description": "The name of the entitlement feature." } } }, "description": "The entitlements granted to the Customer by the Onetime ." }, "metafields": { "type": "array", "items": {}, "description": "The Metafields attached to the Onetime ." } }, "description": "An object containing the related objects requested with the include query parameter." }, "presentment_currency": { "type": "string", "description": "The presentment currency of the Onetime ." }, "created_at": { "type": "string", "format": "date-time", "description": "The time the Onetime item was first created." }, "customer_id": { "type": "integer", "description": "Unique numeric identifier for the customer the Onetime purchase is tied to." }, "external_product_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "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 ." } }, "description": "An object containing the product id as it appears in external platforms." }, "external_variant_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "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 ." } }, "description": "An object containing the variant id as it appears in external platforms." }, "is_cancelled": { "type": "boolean", "description": "Flag indicating if the the onetime is cancelled." }, "next_charge_scheduled_at": { "type": "string", "format": "date", "description": "Date of the Onetime purchase execution." }, "price": { "type": "string", "description": "The price of the item before discounts, taxes, or shipping have been applied." }, "product_title": { "type": "string", "description": "The name of the product in a shop’s catalog." }, "properties": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the property." }, "value": { "type": "string", "description": "The value of the property." } } }, "description": "An array containing key value pairs for any supplementary data." }, "quantity": { "type": "integer", "description": "The number of items in the Onetime purchase." }, "sku": { "type": "string", "description": "A unique identifier of the item in the fulfillment." }, "sku_override": { "type": "boolean", "description": "Flag that is automatically updated to true when SKU is passed on POST or PUT ." }, "updated_at": { "type": "string", "format": "date-time", "description": "The time the Onetime purchase was last updated." }, "variant_title": { "type": "string", "description": "The name of the variant in a shop’s catalog." } } }, "orders_object": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique numeric identifier for the order." }, "address_id": { "type": "integer", "description": "The id of the associated Address within Recharge." }, "billing_address": { "type": "object", "properties": { "address1": { "type": "string", "description": "Line one of the billing address." }, "address2": { "type": "string", "description": "Line two of the billing address." }, "city": { "type": "string", "description": "The city of the billing address." }, "company": { "type": "string", "description": "The company name of the billing address." }, "country_code": { "type": "string", "description": "2-letter country code." }, "first_name": { "type": "string", "description": "The first name of the billing address." }, "last_name": { "type": "string", "description": "The last name of the billing address." }, "phone": { "type": "string", "description": "The phone number of the billing address." }, "province": { "type": "string", "description": "The name of the province or state associated with the billing address." }, "zip": { "type": "string", "description": "The zip code or postcode of the address." } }, "description": "The billing address at the time the order was created. See Addresses for detailed address information." }, "charge": { "type": "object", "properties": { "id": { "type": "integer", "description": "The id of the charge associated with this order." }, "external_transaction_id": { "type": "object", "properties": { "payment_processor": { "type": "string", "description": "The ID of the associated transaction in a payment processor system (like Stripe)." } }, "description": "An object containing external transaction ids associated with this charge, as they appear in external platforms." }, "payment_processor_name": { "type": "string", "description": "The name of the payment processor used to process the Charge ." }, "status": { "type": "string", "description": "The status of the Charge associated with the Order ." } }, "description": "An object containing parameters of the Charge ." }, "client_details": { "type": "object", "properties": { "browser_ip": { "type": "string", "description": "The IP address of the buyer as detected in Checkout ." }, "user_agent": { "type": "string", "description": "The user agent detected during Checkout ." } }, "description": "Details of the access method used by the purchase." }, "error": { "type": "string", "description": "The error message recorded when the Order could not be submitted to the external e-commerce platform." }, "external_order_name": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "The order name as it appears in the external e-commerce platform, for example #1001 ." } }, "description": "An object containing the external order names." }, "include": { "type": "object", "properties": { "address": { "type": "object", "description": "The Address associated with the Order ." }, "customer": { "type": "object", "description": "The Customer associated with the Order ." }, "metafields": { "type": "array", "items": {}, "description": "The Metafields associated with the Order ." }, "order_modifications": { "type": "array", "items": {}, "description": "A list of the modifications made to the line items of the Order ." }, "subscriptions": { "type": "array", "items": {}, "description": "The Subscriptions on the Charge associated with the Order ." } }, "description": "An object containing the related resources requested with the include query parameter." }, "created_at": { "type": "string", "format": "date-time", "description": "The date when the order was created." }, "currency": { "type": "string", "description": "The currency of the payment used to create the order." }, "customer": { "type": "object", "properties": { "id": { "type": "integer", "description": "The ID of the associated customer record." }, "email": { "type": "string", "description": "The user email." }, "external_customer_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "The customer ID as it appears in the external e-commerce platform." } }, "description": "An object containing customer information associated with this charge." }, "hash": { "type": "string", "description": "The hash of the Customer associated with the Charge ." } }, "description": "Object that contains information about the Customer ." }, "discounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "The ID of the Discount ." }, "code": { "type": "string", "description": "The code of the Discount ." }, "value": { "type": "number", "description": "The value of the Discount ." }, "value_type": { "type": "string", "description": "The type of the value of the Discount .", "enum": [ "percentage", "fixed_amount", "shipping" ] }, "application_method": { "type": "string", "description": "How the Discount is applied. Returned as null unless automatic discounts are enabled for the store.", "enum": [ "code", "automatic" ] }, "title": { "type": "string", "description": "The title of the Discount . Returned as null unless automatic discounts are enabled for the store." } } }, "description": "An array of Discounts associated with the Order ." }, "external_cart_token": { "type": "string", "description": "The cart token as it appears in an external system." }, "external_order_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "The order ID as it appears in the external e-commerce platform." } }, "description": "An object containing external order ids." }, "external_order_number": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "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 ." } }, "description": "An object containing the external order numbers." }, "is_prepaid": { "type": "boolean", "description": "A boolean representing if this Order is generated from a prepaid purchase." }, "line_items": { "type": "array", "items": { "type": "object", "properties": { "external_inventory_policy": { "type": "string", "description": "The inventory behavior applied to the line_item when the Order is created in the external e-commerce platform.", "enum": [ "bypass", "decrement_ignoring_policy", "decrement_obeying_policy" ] }, "external_line_item_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "The ID of the line_item as it appears in the external e-commerce platform." } }, "description": "An object containing the ID of the line_item as it appears in the external system." }, "offer_attributes": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of the offer, for example free_gift ." }, "source": { "type": "string", "description": "The source of the offer." } }, "description": "An object describing the offer that added the line_item to the Order . Returned as null when the line_item was not added by an offer." }, "purchase_item_id": { "type": "integer", "description": "The Subscription or Onetime ID associated with the line_item ." }, "external_product_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "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 ." } }, "description": "An object containing the associated product ID as it appears in the external system." }, "external_variant_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "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 ." } }, "description": "An object containing the associated variant ID as it appears in the external system." }, "grams": { "type": "integer", "description": "The weight of the item in grams." }, "handle": { "type": "string", "description": "A unique, human-friendly string for the Product ." }, "images": { "type": "object", "properties": { "large": { "type": "string", "description": "The url where a large image file is located." }, "medium": { "type": "string", "description": "The url where a medium image file is located." }, "small": { "type": "string", "description": "The url where a small image file is located." }, "original": { "type": "string", "description": "The url of the original sized product image." } }, "description": "An object containing URLs of the Product image." }, "original_price": { "type": "string", "description": "The original price of the line_item without discounts or taxes." }, "properties": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the property." }, "value": { "type": "string", "description": "The value of the property." } } }, "description": "An array of name value pairs of additional line_item attributes." }, "purchase_item_type": { "type": "string", "description": "An indicator of the type of the purchase item.", "enum": [ "subscription", "onetime" ] }, "quantity": { "type": "integer", "description": "The quantity of the line_item ." }, "sku": { "type": "string", "description": "The SKU (stock keeping unit) of the Product associated with the line_item ." }, "tax_due": { "type": "string", "description": "The total tax due associated with the line_item ." }, "tax_lines": { "type": "array", "items": { "type": "object", "properties": { "price": { "type": "string", "description": "The total tax associated with the listed jurisdiction." }, "rate": { "type": "string", "description": "The tax rate associated with the listed jurisdiction." }, "title": { "type": "string", "description": "The title/name of the taxing jurisdiction." }, "unit_price": { "type": "string", "description": "The tax amount per unit of the line_item for the listed jurisdiction. Defaults to 0.00 when not available." } } }, "description": "an array containing tax_line objects associated with this line_item ." }, "taxable": { "type": "boolean", "description": "A boolean indicating if the line_item is taxable or non-taxable." }, "taxable_amount": { "type": "string", "description": "The taxable revenue associated with the line_item ." }, "title": { "type": "string", "description": "The title of the Product of this line_item ." }, "total_price": { "type": "string", "description": "The total price of the line_item including tax." }, "unit_price": { "type": "string", "description": "The unit price of the line_item ." }, "unit_price_includes_tax": { "type": "boolean", "description": "A boolean indicator if tax is included in the price of an item." }, "variant_title": { "type": "string", "description": "The name of a variant of the Product of this line_item ." } } }, "description": "A list of line_item objects." }, "note": { "type": "string", "description": "Notes associated with the Order ." }, "order_attributes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name for the attribute." }, "value": { "type": "string", "description": "The value for the associated attribute." } } }, "description": "An array of name value pairs of note attributes on the Order ." }, "processed_at": { "type": "string", "format": "date-time", "description": "The date time that the associated charge was processed at." }, "scheduled_at": { "type": "string", "format": "date-time", "description": "The date time of when the associated charge is/was scheduled to process." }, "shipping_address": { "type": "object", "properties": { "address1": { "type": "string", "description": "Line one of the billing address." }, "address2": { "type": "string", "description": "Line two of the billing address." }, "city": { "type": "string", "description": "The city of the billing address." }, "company": { "type": "string", "description": "The company name of the billing address." }, "country_code": { "type": "string", "description": "2-letter country code." }, "first_name": { "type": "string", "description": "The first name of the billing address." }, "last_name": { "type": "string", "description": "The last name of the billing address." }, "phone": { "type": "string", "description": "The phone number of the billing address." }, "province": { "type": "string", "description": "The name of the province or state associated with the billing address." }, "zip": { "type": "string", "description": "The zip code or postcode of the address." } }, "description": "The shipping address where the order will be shipped. See Addresses for detailed Address information." }, "shipping_lines": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "The code associated with the shipping_line of a Charge ." }, "price": { "type": "string", "description": "The price of the shipping_line ." }, "source": { "type": "string", "description": "The source of the shipping_line ." }, "title": { "type": "string", "description": "The title of the shipping_line ." }, "taxable": { "type": "boolean", "description": "A boolean indicating if the shipping_line is taxable." }, "tax_lines": { "type": "array", "items": { "type": "object", "properties": { "price": { "type": "string", "description": "The total tax associated with the listed jurisdiction." }, "rate": { "type": "string", "description": "The tax rate associated with the listed jurisdiction." }, "title": { "type": "string", "description": "The title/name of the taxing jurisdiction." } } }, "description": "An array of tax lines associated with the shipping_line ." } } }, "description": "An array of shipping lines associated with the order." }, "status": { "type": "string", "description": "The status of creating the Order .", "enum": [ "queued", "success", "error", "cancelled", "skipped", "pending_fraud", "pending_charge_status", "merged" ] }, "subtotal_price": { "type": "string", "description": "The subtotal price (sum of all line items * their quantity) of the order less discounts." }, "tags": { "type": "string", "description": "A comma separated list of tags on the Order ." }, "tax_lines": { "type": "array", "items": { "type": "object", "properties": { "price": { "type": "string", "description": "The total tax associated with the listed jurisdiction." }, "rate": { "type": "string", "description": "The tax rate associated with the listed jurisdiction." }, "title": { "type": "string", "description": "The title/name of the taxing jurisdiction." } } }, "description": "An array of tax lines that apply to the Order ." }, "taxable": { "type": "boolean", "description": "A boolean indicator of the taxability of the Order ." }, "total_discounts": { "type": "string", "description": "The total discounted dollar value of the Order ." }, "total_duties": { "type": "string", "description": "The total cost of duties for the order." }, "total_line_items_price": { "type": "string", "description": "The total price of all line items of the Order ." }, "total_price": { "type": "string", "description": "The total amount due of the Order ." }, "total_refunds": { "type": "string", "description": "The total dollar amount of refunds associated with the Order ." }, "total_tax": { "type": "string", "description": "The total tax due associated with the Order ." }, "total_weight_grams": { "type": "integer", "description": "The total weight of the order in grams." }, "type": { "type": "string", "description": "An indicator of the order’s type.", "enum": [ "checkout", "recurring" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "The date time at which the order was most recently updated." } } }, "payment_methods_object": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique payment method id for a customer." }, "customer_id": { "type": "integer", "description": "The Recharge customer_id ." }, "include": { "type": "object", "properties": { "addresses": { "type": "array", "items": {}, "description": "The Addresses that use this payment method." }, "customer": { "type": "object", "description": "The Customer the payment method belongs to." } }, "description": "An object containing the related resources requested with the include query parameter. Returned as an empty object when no related resources are requested." }, "deleted_at": { "type": "string", "format": "date-time", "description": "The date and time when the payment method was deleted. null for payment methods that have not been deleted." }, "created_at": { "type": "string", "format": "date-time", "description": "The date and time when the payment method was created." }, "default": { "type": "boolean", "description": "true if this is default payment method for the Customer." }, "payment_details": { "type": "object", "properties": { "bank_code": { "type": "string", "description": "The bank code of the account." }, "brand": { "type": "string", "description": "Payment_method brand or company powering it." }, "country": { "type": "string", "description": "The country of the bank account." }, "exp_month": { "type": "integer", "description": "Payment_method expiry month." }, "exp_year": { "type": "integer", "description": "Payment_method expiry year." }, "external_mandate_id": { "type": "string", "description": "The ID of the debit mandate at the processor." }, "last4": { "type": "string", "description": "last 4-digits of the identifier." }, "paypal_email": { "type": "string", "description": "email linked to ." }, "paypal_payer_id": { "type": "string", "description": "paypal user identifier." }, "wallet_type": { "type": "string", "description": "If a digital wallet." }, "funding_type": { "type": "string", "description": "Type of funding for the Payment Method ." } }, "description": "Details about the specific payment method. The keys returned depend on payment_type : CREDIT_CARD and AMAZON_PAY return brand , last4 , exp_month and exp_year (plus wallet_type and funding_type when available); APPLE_PAY and GOOGLE_PAY return brand , last4 , exp_month and exp_year ; SEPA_DEBIT returns bank_code , country , external_mandate_id and last4 ; PAYPAL returns paypal_email and paypal_payer_id ." }, "payment_type": { "type": "string", "description": "The type of payment this is.", "enum": [ "CREDIT_CARD", "PAYPAL", "APPLE_PAY", "GOOGLE_PAY", "SEPA_DEBIT", "IDEAL", "SHOP_PAY", "PAYPAL_EXPRESS", "SOFORT", "GIROPAY", "AMAZON_PAY", "INVOICE", "AFTERPAY_CLEARPAY", "KLARNA" ] }, "processor_customer_token": { "type": "string", "description": "The customer token at the processor." }, "processor_name": { "type": "string", "description": "This will impact validation on billing_details.", "enum": [ "stripe", "braintree", "authorize", "shopify_payments", "mollie", "custom_gateway" ] }, "processor_payment_method_token": { "type": "string", "description": "The payment token at the processor." }, "status": { "type": "string", "description": "State of the Payment Method .", "enum": [ "unvalidated", "valid", "invalid", "empty" ] }, "status_reason": { "type": "string", "description": "The status reason for the payment method." }, "updated_at": { "type": "string", "format": "date-time", "description": "Last time the Payment_method was updated." }, "billing_address": { "type": "object", "properties": { "address1": { "type": "string", "description": "Line one of the billing address." }, "address2": { "type": "string", "description": "Line two of the billing address." }, "city": { "type": "string", "description": "The city of the billing address." }, "company": { "type": "string", "description": "The company name of the billing address." }, "country": { "type": "string", "description": "The full country name of the billing address." }, "country_code": { "type": "string", "description": "2-letter country code." }, "first_name": { "type": "string", "description": "The first name of the billing address." }, "last_name": { "type": "string", "description": "The last name of the billing address." }, "phone": { "type": "string", "description": "The phone number of the billing address." }, "province": { "type": "string", "description": "The name of the province or state associated with the billing address." }, "zip": { "type": "string", "description": "The zip code or postcode of the address." } }, "description": "An object with the customer’s address information." } } }, "plans_object": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique numeric identifier for the Plan ." }, "addon_settings": { "type": "object", "properties": { "expiration": { "type": "object", "properties": { "type": { "type": "string", "description": "How the expiration is expressed.", "enum": [ "relative", "absolute" ] }, "value": { "type": "object", "description": "The 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." } }, "description": "An object describing when an add-on purchased through this plan expires. null when it does not expire." }, "parent_external_variant_ids": { "type": "array", "items": {}, "description": "An array of the variant ids, as they appear in external platforms, of the parent products the add-on belongs to." } }, "description": "An 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." }, "channel_settings": { "type": "object", "properties": { "api": { "type": "object", "properties": { "display": { "type": "boolean", "description": "A boolean to indicate if the plan may be used in the associated channel (defaults to true for all channels).", "default": true } }, "description": "An object containing api channel settings." }, "customer_portal": { "type": "object", "properties": { "display": { "type": "boolean", "description": "A boolean to indicate if the plan may be used in the associated channel (defaults to true for all channels).", "default": true } }, "description": "An object containing customer portal channel settings." }, "merchant_portal": { "type": "object", "properties": { "display": { "type": "boolean", "description": "A boolean to indicate if the plan may be used in the associated channel (defaults to true for all channels).", "default": true } }, "description": "An object containing merchant portal channel settings." }, "checkout_page": { "type": "object", "properties": { "display": { "type": "boolean", "description": "A boolean to indicate if the plan may be used in the associated channel (defaults to true for all channels).", "default": true } }, "description": "An object containing checkout channel settings." } }, "description": "An object containing the availability of the plan through various supported channels." }, "product_quantity": { "type": "integer", "description": "The quantity of the product that a subscriber receives when purchasing through this Plan . null when the plan does not set a quantity." }, "translations": { "type": "array", "items": { "type": "object", "properties": { "language": { "type": "string", "description": "The language code of the translation, for example fr ." }, "title": { "type": "string", "description": "The title of the Plan in that language." } } }, "description": "An array of translated titles for the Plan ." }, "created_at": { "type": "string", "format": "date-time", "description": "The time the plan was created." }, "deleted_at": { "type": "string", "format": "date-time", "description": "If deleted, the time the plan was deleted." }, "discount_amount": { "type": "string", "description": "The discount amount applied to the product price when purchased through this Plan ." }, "discount_type": { "type": "string", "description": "Used in combination with discount amount to determine the discount applied on a product price when purchased through this Plan . percentage applies the discount amount as a percent off the price; fixed_amount applies it as a flat amount in the store's currency.", "enum": [ "percentage", "fixed_amount" ] }, "external_plan_group_id": { "type": "string", "description": "The id of the selling plan group as it appears in external platforms." }, "external_plan_id": { "type": "string", "description": "The id of the selling plan as it appears in external platforms." }, "external_plan_name": { "type": "string", "description": "The name of the selling plan as it appears in external platforms." }, "external_product_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "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 ." } }, "description": "An object containing the product id as it appears in external platforms." }, "external_variant_ids": { "type": "array", "items": {}, "description": "An array of variant ids as they appear in external platforms." }, "has_variant_restrictions": { "type": "boolean", "description": "Whether this plan applies to specific variants of the product", "default": "false" }, "sort_order": { "type": "integer", "description": "The number indicating the order which the plan will be in a list of related plans." }, "subscription_preferences": { "type": "object", "properties": { "apply_cutoff_date_to_checkout": { "type": "boolean", "description": "Whether the specified cutoff day should be applied to the initial checkout order" }, "charge_interval_frequency": { "type": "integer", "description": "Frequency at which the subscriber will be charged." }, "cutoff_day_of_month": { "type": "integer", "description": "Day of the month the plan should be charged" }, "cutoff_day_of_week": { "type": "integer", "description": "Day of the month the plan should be charged" }, "expire_after_specific_number_of_charges": { "type": "integer", "description": "A maximum number of charges on which the subscription should appear before automatic cancellation." }, "order_day_of_month": { "type": "integer", "description": "Day of the month an order should be generated when the customer is subscribed." }, "order_day_of_week": { "type": "integer", "description": "Day of the week an order should be generated when the customer is subscribed." }, "order_interval_frequency": { "type": "integer", "description": "Frequency at which the subscriber will receive shipments when subscribed to this plan." }, "interval_unit": { "type": "string", "description": "The unit applied to charge_interval_frequency and order_interval_frequency .", "enum": [ "day", "week", "month" ] }, "pricing_progression": { "type": "array", "items": { "type": "object", "properties": { "recurring_discount_after_cycle": { "type": "integer", "description": "The number of cycles after which this recurring discount should be applied. The checkout order is cycle 1. The first recurring order is cycle 2." }, "recurring_discount_amount": { "type": "number", "description": "The discount amount applied to the product price after the specified number of cycles." }, "recurring_discount_type": { "type": "string", "description": "Used in combination with discount amount to determine the discount applied on a product price after the specified number of cycles. percentage applies the discount amount as a percent off the price; fixed_amount applies it as a flat amount in the store's currency.", "enum": [ "percentage", "fixed_amount" ] } } }, "description": "For regular subscription plans, this field is an empty array." } }, "description": "An object containing the various subscription preferences associated with this plan." }, "title": { "type": "string", "description": "The title of the plan." }, "type": { "type": "string", "description": "The type of the plan.", "enum": [ "subscription", "prepaid", "prepaid_v2", "onetime", "membership_subscription" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "The time the plan was last updated." } } }, "products_object": { "type": "object", "properties": { "description": { "type": "string", "description": "The description of the product." }, "external_product_id": { "type": "string", "description": "Unique numeric identifier of the product record in Recharge. The primary id of the record." }, "brand": { "type": "string", "description": "The brand name of the product." }, "external_created_at": { "type": "string", "format": "date-time", "description": "The date and time at which the product was created in an external product catalog." }, "external_updated_at": { "type": "string", "format": "date-time", "description": "The date and time at which the product was updated in an external product catalog." }, "images": { "type": "array", "items": { "type": "object", "properties": { "large": { "type": "string", "description": "The url where a large image file is located." }, "medium": { "type": "string", "description": "The url where a medium image file is located." }, "small": { "type": "string", "description": "The url where a small image file is located." }, "original": { "type": "string", "description": "The url of the original sized product image." }, "sort_order": { "type": "integer", "description": "The sort order in which the x image from the array should appear when displayed." } } }, "description": "An array of urls for various sizes of image files." }, "options": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the option, such as size, color, etc." }, "position": { "type": "integer", "description": "The position in which the x option from the array should appear when displayed." }, "values": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "The label of the option value. For example, if the option name is size, this value may be small, medium, large, etc." }, "position": { "type": "integer", "description": "The position in which the y option value from the array should appear when displayed." } } }, "description": "An array of values for the x option in the options array." } } }, "description": "An array of options for the product record, such as size, color, etc." }, "published_at": { "type": "string", "format": "date-time", "description": "The datetime at which the product became available for purchase. To make the product available, this should be set in the past." }, "requires_shipping": { "type": "boolean", "description": "Indicator of shipping requirement." }, "title": { "type": "string", "description": "The title of the product." }, "variants": { "type": "array", "items": { "type": "object", "properties": { "dimensions": { "type": "object", "properties": { "weight": { "type": "number", "description": "The weight of the product in the weight unit configured for your store." }, "weight_unit": { "type": "string", "description": "Read only. The weight unit specified for your store." } }, "description": "A container of variant dimensions." }, "external_variant_id": { "type": "string", "description": "The variant id in your PIM. The primary key for the variant." }, "image": { "type": "object", "properties": { "large": { "type": "string", "description": "The url where a large image file is located." }, "medium": { "type": "string", "description": "The url where a medium image file is located." }, "small": { "type": "string", "description": "The url where a small image file is located." }, "original": { "type": "string", "description": "The url of the original sized product image." } }, "description": "An object containing image urls for the variant." }, "option_values": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "The label of the option value. Maps to a value specified in the product options list" } } }, "description": "An array of option values, linking the variant to the options listed at the product level." }, "prices": { "type": "object", "properties": { "compare_at_price": { "type": "string", "description": "The compare-at price for the variant." }, "unit_price": { "type": "string", "description": "The unit price for the variant." }, "prices": { "type": "object", "properties": { "presentment_prices": { "type": "object", "properties": { "currency": { "type": "string", "description": "The three-letter currency code of the presentment price." }, "unit_price_currency": { "type": "string", "description": "The unit price of the variant in the presentment currency." }, "discounted_price_currency": { "type": "string", "description": "The discounted price of the variant in the presentment currency." } }, "description": "An object containing the price of the variant in a presentment currency. When sent, currency , unit_price_currency and discounted_price_currency are all required." } }, "description": "An object containing the prices of the variant in other currencies." } }, "description": "An object containing prices for the variant." }, "requires_shipping": { "type": "boolean", "description": "Indicator of shipping requirement. If true the product associated to the variant needs to be shipped." }, "sku": { "type": "string", "description": "The stock keeping unit of the variant." }, "tax_code": { "type": "string", "description": "The tax code of the variant. This value will be used when calculating tax with a third party tax service." }, "taxable": { "type": "boolean", "description": "A boolean indicator of the variant’s taxability." }, "title": { "type": "string", "description": "The title of the variant." } } }, "description": "An array of variants of the product." }, "vendor": { "type": "string", "description": "The vendor of the product." } } }, "retention_strategy_object": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique numeric identifier for the Retention strategy ." }, "cancellation_flow_type": { "type": "string", "description": "The kind of cancellation the Retention strategy is offered for.", "enum": [ "subscription", "membership" ] }, "reason": { "type": "string", "description": "The cancellation reason shown to the customer." }, "prevention_text": { "type": "string", "description": "The message shown to the customer after selecting the cancellation reason, to encourage them not to cancel." }, "incentive_type": { "type": "string", "description": "The incentive offered to the customer to prevent the cancellation. null when no incentive is offered.", "enum": [ "discount", "skip_charge", "delay_subscription", "swap_product" ] }, "discount_code": { "type": "string", "description": "The code of the Discount offered to the customer. Only set when incentive_type is discount ." }, "origin": { "type": "string", "description": "Set to active_churn_flow when the Retention strategy belongs to a cancellation flow; otherwise null .", "enum": [ "active_churn_flow" ] }, "created_at": { "type": "string", "format": "date-time", "description": "The date and time when the Retention strategy was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "The date and time when the Retention strategy was last updated." }, "include": { "type": "object", "properties": { "discount": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique numeric identifier for the Discount ." }, "code": { "type": "string", "description": "The code used to apply the Discount ." }, "value": { "type": "number", "description": "The discounted value to be applied." }, "value_type": { "type": "string", "description": "The type of the discount value.", "enum": [ "fixed_amount", "percentage", "shipping" ] }, "title": { "type": "string", "description": "The title of the Discount ." }, "application_method": { "type": "string", "description": "How the Discount is applied.", "enum": [ "code", "automatic" ] } }, "description": "The Discount matching discount_code ." } }, "description": "Related objects requested with the include query parameter." } } }, "reward_credit_object": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique numeric identifier for the Reward credit ." }, "customer_id": { "type": "integer", "description": "Unique numeric identifier for the Customer the Reward credit belongs to." }, "name": { "type": "string", "description": "The name of the Reward credit ." }, "initial_value": { "type": "string", "description": "The value of the Reward credit at the time of creation." }, "available_balance": { "type": "string", "description": "The amount of the Reward credit that is still available to spend." }, "currency_code": { "type": "string", "description": "The currency code of the Reward credit . This is the default currency of the store." }, "expires_at": { "type": "string", "format": "date-time", "description": "The date and time when the Reward credit expires. null when it does not expire." }, "created_at": { "type": "string", "format": "date-time", "description": "The date and time when the Reward credit was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "The date and time when the Reward credit was last updated." } } }, "store_object": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique number identifier of the store." }, "allow_customers_to_skip_delivery": { "type": "integer", "description": "Whether customers are allowed to skip a delivery in the customer portal ( 1 ) or not ( 0 )." }, "checkout_logo_url": { "type": "string", "description": "Checkout logo url." }, "checkout_platform": { "type": "string", "description": "Checkout platform.", "enum": [ "recharge", "shopify" ] }, "external_platform_domain": { "type": "string", "description": "Domain of the store on the external platform." }, "platform_domain": { "type": "string", "description": "The store's domain as registered with Recharge." }, "storefront_domain": { "type": "string", "description": "Domain of the store's storefront." }, "subscriptions_enabled": { "type": "boolean", "description": "Whether subscriptions are enabled for the store." }, "test_mode": { "type": "boolean", "description": "Whether the store is in test mode. Currently always returned as false by this endpoint." }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the store is created." }, "currency": { "type": "string", "description": "Currency of the store." }, "customer_portal_base_url": { "type": "string", "description": "Customer Portal Base URL." }, "default_api_version": { "type": "string", "description": "Default API version." }, "email": { "type": "string", "description": "E-mail address of the store owner." }, "enabled_presentment_currencies": { "type": "array", "items": {}, "description": "Enabled currencies the store sells in." }, "enabled_presentment_currencies_symbols": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string", "description": "Currency used." }, "location": { "type": "string", "description": "Describes if the symbol appears before or after currency." }, "suffix": { "type": "string", "description": "Suffix appended to symbol." }, "symbol": { "type": "string", "description": "The symbol of the currency." } } }, "description": "Currency symbol used for enabled currencies the store sells in." }, "disabled_currencies_historical": { "type": "array", "items": {}, "description": "A ledger of currencies that the store no longer sells in. If a currency is present in both the enabled_presentment_currencies and disabled_currencies_historical ledger it is because it was disabled at one point in time but is now enabled." }, "external_platform": { "type": "string", "description": "External platform connected to Recharge.", "enum": [ "big_commerce", "headless", "magento", "shopify" ] }, "identifier": { "type": "string", "description": "Unique identifier of the store on the external platform." }, "merchant_portal_base_url": { "type": "string", "description": "Merchant portal base URL." }, "name": { "type": "string", "description": "Name of the store." }, "phone": { "type": "string", "description": "Phone number of the store owner." }, "timezone": { "type": "object", "properties": { "iana_name": { "type": "string", "description": "Iana database timezone format." }, "name": { "type": "string", "description": "Timezone for the Store" } }, "description": "Timezone of the store." }, "updated_at": { "type": "string", "format": "date-time", "description": "The date and time when the address was last updated." }, "weight_unit": { "type": "string", "description": "Weight unit for the store." } } }, "subscriptions_object": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique numeric identifier for the subscription." }, "additional_variant_data": { "type": "object", "properties": { "fulfillment_service": { "type": "object", "description": "The fulfillment service of the variant, as value and override ." }, "grams": { "type": "object", "description": "The weight of the variant in grams, as value and override ." }, "tax_code": { "type": "object", "description": "The tax code of the variant, as value and override ." }, "taxable": { "type": "object", "description": "Whether the variant is taxable, as value and override ." }, "vendor": { "type": "object", "description": "The vendor of the variant, as value and override ." } }, "description": "An 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." }, "address_id": { "type": "integer", "description": "Unique numeric identifier for the address the subscription is associated with." }, "customer_id": { "type": "integer", "description": "Unique numeric identifier for the customer the subscription is tied to." }, "analytics_data": { "type": "object", "properties": { "utm_params": { "type": "array", "items": { "type": "object", "properties": { "utm_campaign": { "type": "string", "description": "The UTM campaign." }, "utm_content": { "type": "string", "description": "The UTM content." }, "utm_data_source": { "type": "string", "description": "The source of the campaign parameter." }, "utm_source": { "type": "string", "description": "The UTM source." }, "utm_medium": { "type": "string", "description": "The UTM medium." }, "utm_term": { "type": "string", "description": "The UTM term." }, "utm_timestamp": { "type": "string", "description": "The UTM timestamp." } } }, "description": "An array containing utm_param objects." } }, "description": "An object used to contain analytics data such as utm parameters." }, "cancellation_reason": { "type": "string", "description": "Reason provided for cancellation." }, "cancellation_reason_comments": { "type": "string", "description": "Additional comment for cancellation. Maximum length is 1024 characters." }, "cancelled_at": { "type": "string", "format": "date-time", "description": "The time the subscription was cancelled." }, "charge_interval_frequency": { "type": "integer", "description": "The number of units (specified in order_interval_unit ) between each Charge . For example, order_interval_unit=month and charge_interval_frequency=3 , indicate charge every 3 months." }, "include": { "type": "object", "properties": { "addons": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "The 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.", "enum": [ "child", "parent" ] }, "parent_subscription_id": { "type": "integer", "description": "Unique numeric identifier of the parent Subscription in the relationship." }, "child_subscription_id": { "type": "integer", "description": "Unique numeric identifier of the add-on Subscription in the relationship." } } }, "description": "The add-on relationships of the Subscription with other subscriptions." }, "address": { "type": "object", "description": "The Address the Subscription is associated with." }, "bundle_product": { "type": "object", "description": "The bundle product that matches the product of the Subscription . null if the product is not a bundle." }, "bundle_selections": { "type": "object", "description": "The BundleSelection linked to the Subscription . null if there is none." }, "charge_activities": { "type": "array", "items": {}, "description": "The charge activity records created in the last 90 days for the Charges that contain the Subscription ." }, "customer": { "type": "object", "description": "The Customer the Subscription is tied to." }, "customer_entitlements": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique numeric identifier for the customer entitlement." }, "description": { "type": "string", "description": "The description of the entitlement feature." }, "expires_at": { "type": "string", "format": "date-time", "description": "The time the entitlement expires. null if it does not expire." }, "lookup_key": { "type": "string", "description": "The lookup key of the entitlement feature." }, "name": { "type": "string", "description": "The name of the entitlement feature." } } }, "description": "The entitlements granted to the Customer by the Subscription ." }, "expires_at": { "type": "array", "items": {}, "description": "A list containing the date on which the Subscription expires as an add-on, or null if it has no expiration." }, "metafields": { "type": "array", "items": {}, "description": "The Metafields attached to the Subscription ." } }, "description": "An object containing the related objects requested with the include query parameter." }, "is_digital": { "type": "boolean", "description": "Value 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." }, "locked_pending_charge_id": { "type": "integer", "description": "Unique 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." }, "plan_id": { "type": "integer", "description": "Unique numeric identifier of the Plan the Subscription is linked to." }, "created_at": { "type": "string", "format": "date-time", "description": "The time the subscription was created." }, "expire_after_specific_number_of_charges": { "type": "integer", "description": "Set the number of charges until subscription expires." }, "external_product_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "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 ." } }, "description": "An object containing the product id as it appears in external platforms." }, "external_variant_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "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 ." } }, "description": "An object containing the variant id as it appears in external platforms." }, "has_queued_charges": { "type": "boolean", "description": "Retrieves true if there is queued charge. Otherwise, retrieves false ." }, "is_prepaid": { "type": "boolean", "description": "Value is set to true if it is a prepaid item." }, "is_skippable": { "type": "boolean", "description": "Value is set to true if it is not a prepaid item" }, "is_swappable": { "type": "boolean", "description": "Value is set to true if it is not a prepaid item and if in Customer portal settings swap is allowed for customers." }, "max_retries_reached": { "type": "boolean", "description": "Retrieves true if charge has an error max retries reached. Otherwise, retrieves false ." }, "next_charge_scheduled_at": { "type": "string", "format": "date", "description": "Date of the next charge for the subscription." }, "order_day_of_month": { "type": "integer", "description": "The set day of the month order is created. Default is that there isn’t a strict day of the month when the order is created." }, "order_day_of_week": { "type": "integer", "description": "The set day of the week order is created. Default is that there isn’t a strict day of the week order is created." }, "order_interval_frequency": { "type": "integer", "description": "The number of units (specified in order_interval_unit ) between each order. For example, order_interval_unit=month and order_interval_frequency=3, indicate order every 3 months. Max value: 1000" }, "order_interval_unit": { "type": "string", "description": "The frequency unit used to determine when a subscription's order is created.", "enum": [ "day", "week", "month" ] }, "presentment_currency": { "type": "string", "description": "The presentment currency of the subscription." }, "price": { "type": "string", "description": "The price of the item before discounts, taxes, or shipping have been applied." }, "product_title": { "type": "string", "description": "The name of the product in a store's catalog." }, "properties": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the property." }, "value": { "type": "string", "description": "The value of the property." } } }, "description": "A list of line item objects, each one containing information about the subscription. Custom key-value pairs can be installed here, they will appear on the connected queued charge and after it is processed on the order itself." }, "quantity": { "type": "integer", "description": "The number of items in the subscription." }, "sku": { "type": "string", "description": "A unique identifier of the item in the fulfillment. In cases where SKU is blank, it will be dynamically pulled whenever it is used." }, "sku_override": { "type": "boolean", "description": "Flag that is automatically updated to true when SKU is passed on create or update. When sku_override is true , the SKU on the subscription will be used to generate charges and orders. When sku_override is false , Recharge will dynamically fetch the SKU from the corresponding external platform variant." }, "status": { "type": "string", "description": "The status of the subscription.", "enum": [ "active", "cancelled", "expired" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "The date time at which the purchase_item record was last updated." }, "variant_title": { "type": "string", "description": "The name of the variant in a shop’s catalog." } } }, "webhooks_object": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique numeric identifier for the webhook." }, "address": { "type": "string", "description": "The URI where the webhook should send the POST request when the event occurs." }, "included_objects": { "type": "array", "items": {}, "description": "List of objects set to enrich the webhook payload. cf. extending responses", "enum": [ "address", "addresses", "charge_activities", "customer", "event", "event_charge", "metafields", "payment_methods", "subscriptions" ] }, "topic": { "type": "string", "description": "The event that will trigger the webhook." }, "version": { "type": "string", "description": "The version of the API used to populate the body of the webhook. If not set, this will default to the store's default API version. 2021-11 is V2.", "enum": [ "2021-01", "2021-11" ] } } }, "async_batch_endpoints_object": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier of the batch, used for adding tasks to a batch and to initiate batch processing" }, "batch_type": { "type": "string", "description": "Indicates the object type and operation required for all tasks in a batch", "enum": [ "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" ] }, "closed_at": { "type": "string", "format": "date-time", "description": "Indicates the date and time that processing was completed for a batch" }, "expired_at": { "type": "string", "format": "date-time", "description": "The date and time until which the batch and its tasks are retained." }, "deleted_at": { "type": "string", "format": "date-time", "description": "The date and time the batch was deleted. Deleted batches are not returned by the API, so this is null ." }, "created_at": { "type": "string", "format": "date-time", "description": "Indicates the date and time a batch was created" }, "fail_task_count": { "type": "integer", "description": "Indicates the number of failed tasks in a batch, during or after processing" }, "status": { "type": "string", "description": "Indicates the status of the batch. Available statuses are not_started, processing, completed, failed", "enum": [ "not_started", "processing", "running", "completed", "failed", "terminated" ] }, "submitted_at": { "type": "string", "format": "date-time", "description": "Indicates the date and time that a batch was triggered to process" }, "success_task_count": { "type": "integer", "description": "Indicates the number of successful tasks in a batch, during or after processing." }, "total_task_count": { "type": "integer", "description": "Indicates the total number of tasks in a batch" }, "updated_at": { "type": "string", "format": "date-time", "description": "Indicates the date and time at which a batch was last updated" }, "version": { "type": "string", "description": "Indicates the API version of the batch. 2021-11 is V2.", "enum": [ "2021-01", "2021-11" ] } } }, "async_batch_tasks_object": { "type": "object", "properties": { "batch_id": { "type": "integer", "description": "Indicates the batch that the task is contained by" }, "body": { "type": "object", "description": "This object contains the body of a standard API request. For example, when creating discounts with a discount_create batch, this parameter contains a standard body for POST /discounts" }, "completed_at": { "type": "string", "format": "date-time", "description": "Indicates the date and time a task was completed" }, "stalled_at": { "type": "string", "format": "date-time", "description": "Indicates the date and time a task was flagged as stalled during processing." }, "created_at": { "type": "string", "format": "date-time", "description": "Indicates the date and time that a task was created and added to the batch" }, "deleted_at": { "type": "string", "format": "date-time", "description": "Indicates the date and time that a task was deleted from the batch" }, "id": { "type": "integer", "description": "Unique identifier for the task within a batch" }, "queued_at": { "type": "string", "format": "date-time", "description": "Indicates the date and time a task was queued for processing within batch processing" }, "result": { "type": "object", "description": "Contains the individual response body for the task" }, "started_at": { "type": "string", "format": "date-time", "description": "Indicates the date and time a task was processed" }, "status": { "type": "string", "description": "Indicates the status of the task within a batch.", "enum": [ "pending", "queued", "processing", "success", "fail" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "Indicates the date and time a task was most recently updated" } } }, "token_information_object": { "type": "object", "properties": { "client": { "type": "object", "properties": { "name": { "type": "string", "description": "The client's name." }, "contact_email": { "type": "string", "description": "The client's email." } }, "description": "An object containing information about the client associated with the API Token. Present for every token; name and contact_email are null when the token has no client." }, "contact_email": { "type": "string", "description": "The email associated with the API Token record." }, "created_by_email": { "type": "string", "description": "The 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_id": { "type": "integer", "description": "The 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." }, "name": { "type": "string", "description": "The name of the API Token as created by merchant." }, "scopes": { "type": "array", "items": {}, "description": "A list of scopes on the API Token." } } }, "account_object": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique numeric identifier for the Account ." }, "user_id": { "type": "integer", "description": "The unique numeric identifier of the user associated to the Account ." }, "created_at": { "type": "string", "format": "date-time", "description": "The date and time when the Account was created." }, "invited_at": { "type": "string", "format": "date-time", "description": "The date and time the user was last invited to open their Account" }, "is_owner": { "type": "boolean", "description": "Flags whether this user is the store owner." }, "last_login_at": { "type": "string", "format": "date-time", "description": "The date and time the user last logged in to the Account ." }, "role_association": { "type": "string", "description": "The role association recorded for the user of the Account ." }, "role_department": { "type": "string", "description": "The department recorded for the user of the Account ." }, "role_title": { "type": "string", "description": "The job title recorded for the user of the Account ." }, "role_partner_details": { "type": "object", "description": "An object with partner details recorded for the user of the Account ." }, "permissions": { "type": "array", "items": {}, "description": "List of permission keys granted to the Account ." }, "include": { "type": "object", "properties": { "store": { "type": "object", "description": "The Store the Account belongs to." } }, "description": "Related objects requested with the include query parameter." } } }, "event_object": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique numeric identifier for the Event ." }, "object_id": { "type": "integer", "description": "The unique numeric identifier of the object associated with the Event ." }, "customer_id": { "type": "integer", "description": "The unique numeric identifier of the customer associated with the Event ." }, "created_at": { "type": "string", "format": "date-time", "description": "The date and time when the Event was created. Returned in YYYY-MM-DDTHH:MM:SS format by default; stores that have been moved to timezone-aware event timestamps receive an ISO 8601 value with a UTC offset." }, "object_type": { "type": "string", "description": "The resource type of the object associated with the Event , e.g. 'customer' or 'subscription'" }, "verb": { "type": "string", "description": "The action describing the Event , e.g. 'created' or 'updated'" }, "description": { "type": "string", "description": "The short description that summarizes the Event ." }, "updated_attributes": { "type": "array", "items": { "type": "object", "properties": { "attribute": { "type": "string", "description": "The key of an attribute updated on the object during this Event ." }, "previous_value": { "type": "string", "description": "The previous value of the updated attribute." }, "value": { "type": "string", "description": "The new value of the updated attribute." } } }, "description": "A list of objects describing attributes that were changed during the Event ." }, "source": { "type": "object", "properties": { "account_id": { "type": "integer", "description": "If the event resulted from action by a Store Admin, the account id of the store admin." }, "api_token_id": { "type": "string", "description": "If the event resulted from action by an external API call, the primary key of the API token used to take the action." }, "api_token_name": { "type": "string", "description": "If the event resulted from action by an external API call, the name of the API token used to take the action, as it is saved in Recharge Merchant Admin portal." }, "account_email": { "type": "string", "description": "If the event resulted from action by a Store Admin, the email associated with the store admin account." }, "origin": { "type": "string", "description": "The origin of the event, e.g. 'api', 'customer_portal', 'merchant_portal', 'recharge_process'", "enum": [ "api", "customer_portal", "external_platform", "merchant_portal", "recharge_process" ] }, "user_type": { "type": "string", "description": "The type of user who initiated the event, e.g. 'customer', 'store_admin', 'recharge_admin', 'recharge_process'", "enum": [ "customer", "customer_sms", "recharge_admin", "recharge_admin_sms", "recharge_order_merge", "recharge_process", "store_admin", "store_admin_sms", "support_session" ] } }, "description": "An object containing details about the origin of the Event ." }, "custom_attributes": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "A user-defined key for the custom attribute associated with this Event ." }, "value": { "type": "string", "description": "A user-defined value for the custom attribute associated with this Event ." } } }, "description": "A list of objects passed explicitly to a Recharge API call that created the Event ." } } } } } }