{ "openapi": "3.1.0", "info": { "title": "Recharge API", "version": "2021-11", "description": "Recharge API reference, version 2021-11. The current version of the Recharge API. Cursor pagination, payment methods and plans." }, "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 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": "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": "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": "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": "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": { "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." }, "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." }, "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", "phone", "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": "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": "string" } }, { "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": "limit", "in": "query", "required": false, "description": "The amount of results. Default is 50 while the maximum is 250.", "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": "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" } } ], "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" } } ], "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." }, "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. 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": {}, "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-time", "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" ] } }, "/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" } } ], "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", "quantity": 3, "updated_at": "2022-08-26T18:52:41+00:00" } ], "updated_at": "2022-08-26T18:31:28+00:00" } ] } } } } }, "x-recharge-scopes": [ "read_subscriptions" ] }, "post": { "operationId": "bundle_selection_create", "summary": "Create a bundle selection", "description": "Create a BundleSelection .", "tags": [ "Bundle Selections" ], "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", "quantity": 3, "updated_at": "2022-08-26T18:52:41+00:00" } ], "updated_at": "2022-08-26T18:31:28+00:00" } } } } }, "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." }, "quantity": { "type": "integer", "description": "The quantity of this product." } } }, "description": "A list of item objects, each containing information about a distinct product selected as part of the Bundle." } }, "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", "quantity": 3, "updated_at": "2022-08-26T18:52:41+00:00" } ], "updated_at": "2022-08-26T18:31:28+00:00" } } } } }, "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" } } ], "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", "quantity": 3, "updated_at": "2022-08-26T18:52:41+00:00" } ], "updated_at": "2022-08-26T18:31:28+00:00" } } } } }, "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": { "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": {}, "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" } } ], "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" ] } }, "/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" } } ], "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": "2021-11-09T23:59:31+00:00", "retry_date": "2021-01-01", "scheduled_at": "2021-12-09", "shipping_address": { "address1": "1030 Barnum Ave", "address2": "Suite 101", "city": "Stratford", "company": "Fake Company", "country_code": "US", "first_name": "Fake First", "last_name": "Fake Last", "phone": "999-999-9999", "province": "Connecticut", "zip": "06614" }, "shipping_lines": [ { "code": "Standard", "price": "4.90", "source": "shopify", "taxable": true, "tax_lines": [ { "price": "0.355", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.110", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "title": "Standard" } ], "status": "success", "subtotal_price": "10.00", "tags": "Subscription, Subscription Recurring Order", "tax_lines": [ { "price": "0.950", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.335", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "taxable": true, "taxes_included": true, "total_discounts": "10.0", "total_line_items_price": "10.00", "total_price": "11.29", "total_refunds": "0.00", "total_tax": "1.29", "total_weight_grams": 454, "type": "recurring", "updated_at": "2021-11-09T23:59:32+00:00" } } } } } }, "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": "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": "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": "ids", "in": "query", "required": false, "description": "Filter Charges by ID.", "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": "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" } }, { "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" } }, { "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": [ { "purchase_item_id": 63898947, "external_product_id": { "ecommerce": "4381728735283" }, "external_variant_id": { "ecommerce": "999999999999" }, "grams": 454, "handle": "shirt-package", "images": { "large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg", "medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg", "original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg", "small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg" }, "original_price": "10.00", "properties": [ { "name": "Color", "value": "Blue" } ], "purchase_item_type": "subscription", "quantity": 1, "sku": "TOM0001", "tax_due": "1.30", "tax_lines": [ { "price": "0.9931", "rate": "0.0725", "title": "CA State Tax", "unit_price": "0.3310" }, { "price": "0.3082", "rate": "0.0225", "title": "LA County Tax", "unit_price": "0.1027" } ], "taxable": true, "taxable_amount": "10.00", "title": "Shirt package", "total_price": "11.30", "unit_price": "10.00", "unit_price_includes_tax": false, "variant_title": "Blue T-shirt" } ], "note": "next order in sequence 3", "order_attributes": [ { "name": "Checkout-Method", "value": "delivery" } ], "orders_count": 1, "payment_processor": "stripe", "processed_at": "2021-11-09T23:59:31+00:00", "retry_date": "2021-01-01", "scheduled_at": "2021-12-09", "shipping_address": { "address1": "1030 Barnum Ave", "address2": "Suite 101", "city": "Stratford", "company": "Fake Company", "country_code": "US", "first_name": "Fake First", "last_name": "Fake Last", "phone": "999-999-9999", "province": "Connecticut", "zip": "06614" }, "shipping_lines": [ { "code": "Standard", "price": "4.90", "source": "shopify", "taxable": true, "tax_lines": [ { "price": "0.355", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.110", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "title": "Standard" } ], "status": "success", "subtotal_price": "10.00", "tags": "Subscription, Subscription Recurring Order", "tax_lines": [ { "price": "0.950", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.335", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "taxable": true, "taxes_included": true, "total_discounts": "10.0", "total_line_items_price": "10.00", "total_price": "11.29", "total_refunds": "0.00", "total_tax": "1.29", "total_weight_grams": 454, "type": "recurring", "updated_at": "2021-11-09T23:59:32+00:00" } ] } } } } }, "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": [ { "purchase_item_id": 63898947, "external_product_id": { "ecommerce": "4381728735283" }, "external_variant_id": { "ecommerce": "999999999999" }, "grams": 454, "handle": "shirt-package", "images": { "large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg", "medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg", "original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg", "small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg" }, "original_price": "10.00", "properties": [ { "name": "Color", "value": "Blue" } ], "purchase_item_type": "subscription", "quantity": 1, "sku": "TOM0001", "tax_due": "1.30", "tax_lines": [ { "price": "0.9931", "rate": "0.0725", "title": "CA State Tax", "unit_price": "0.3310" }, { "price": "0.3082", "rate": "0.0225", "title": "LA County Tax", "unit_price": "0.1027" } ], "taxable": true, "taxable_amount": "10.00", "title": "Shirt package", "total_price": "11.30", "unit_price": "10.00", "unit_price_includes_tax": false, "variant_title": "Blue T-shirt" } ], "note": "next order in sequence 3", "order_attributes": [ { "name": "Checkout-Method", "value": "delivery" } ], "orders_count": 1, "payment_processor": "stripe", "processed_at": "2021-11-09T23:59:31+00:00", "retry_date": "2021-01-01", "scheduled_at": "2021-12-09", "shipping_address": { "address1": "1030 Barnum Ave", "address2": "Suite 101", "city": "Stratford", "company": "Fake Company", "country_code": "US", "first_name": "Fake First", "last_name": "Fake Last", "phone": "999-999-9999", "province": "Connecticut", "zip": "06614" }, "shipping_lines": [ { "code": "Standard", "price": "4.90", "source": "shopify", "taxable": true, "tax_lines": [ { "price": "0.355", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.110", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "title": "Standard" } ], "status": "success", "subtotal_price": "10.00", "tags": "Subscription, Subscription Recurring Order", "tax_lines": [ { "price": "0.950", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.335", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "taxable": true, "total_discounts": "10.0", "total_line_items_price": "10.00", "total_price": "11.29", "total_refunds": "0.00", "total_tax": "1.29", "total_weight_grams": 454, "type": "recurring", "updated_at": "2021-11-09T23:59:32+00:00" } } } } } }, "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": [ { "purchase_item_id": 63898947, "external_product_id": { "ecommerce": "4381728735283" }, "external_variant_id": { "ecommerce": "999999999999" }, "grams": 454, "handle": "shirt-package", "images": { "large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg", "medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg", "original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg", "small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg" }, "original_price": "10.00", "properties": [ { "name": "Color", "value": "Blue" } ], "purchase_item_type": "subscription", "quantity": 1, "sku": "TOM0001", "tax_due": "1.30", "tax_lines": [ { "price": "0.9931", "rate": "0.0725", "title": "CA State Tax", "unit_price": "0.3310" }, { "price": "0.3082", "rate": "0.0225", "title": "LA County Tax", "unit_price": "0.1027" } ], "taxable": true, "taxable_amount": "10.00", "title": "Shirt package", "total_price": "11.30", "unit_price": "10.00", "unit_price_includes_tax": false, "variant_title": "Blue T-shirt" } ], "note": "next order in sequence 3", "order_attributes": [ { "name": "Checkout-Method", "value": "delivery" } ], "orders_count": 1, "payment_processor": "stripe", "processed_at": "2021-11-09T23:59:31+00:00", "retry_date": "2021-01-01", "scheduled_at": "2021-12-09", "shipping_address": { "address1": "1030 Barnum Ave", "address2": "Suite 101", "city": "Stratford", "company": "Fake Company", "country_code": "US", "first_name": "Fake First", "last_name": "Fake Last", "phone": "999-999-9999", "province": "Connecticut", "zip": "06614" }, "shipping_lines": [ { "code": "Standard", "price": "4.90", "source": "shopify", "taxable": true, "tax_lines": [ { "price": "0.355", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.110", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "title": "Standard" } ], "status": "success", "subtotal_price": "10.00", "tags": "Subscription, Subscription Recurring Order", "tax_lines": [ { "price": "0.950", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.335", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "taxable": true, "total_discounts": "10.0", "total_line_items_price": "10.00", "total_price": "11.29", "total_refunds": "0.00", "total_tax": "1.29", "total_weight_grams": 454, "type": "recurring", "updated_at": "2021-11-09T23:59:32+00:00" } } } } } }, "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" } } ], "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" } } } } } }, "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" } } ], "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": "queued", "subtotal_price": "10.00", "tags": "Subscription, Subscription Recurring Order", "tax_lines": [ { "price": "0.950", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.335", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "taxable": true, "total_discounts": "10.0", "total_line_items_price": "10.00", "total_price": "11.29", "total_refunds": "0.00", "total_tax": "1.29", "total_weight_grams": 454, "type": "recurring", "updated_at": "2021-11-09T23:59:32+00:00" } } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "example": {} } } } }, "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": [ { "purchase_item_id": 63898947, "external_product_id": { "ecommerce": "4381728735283" }, "external_variant_id": { "ecommerce": "999999999999" }, "grams": 454, "handle": "shirt-package", "images": { "large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg", "medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg", "original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg", "small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg" }, "original_price": "10.00", "properties": [ { "name": "Color", "value": "Blue" } ], "purchase_item_type": "subscription", "quantity": 1, "sku": "TOM0001", "tax_due": "1.30", "tax_lines": [ { "price": "0.9931", "rate": "0.0725", "title": "CA State Tax", "unit_price": "0.3310" }, { "price": "0.3082", "rate": "0.0225", "title": "LA County Tax", "unit_price": "0.1027" } ], "taxable": true, "taxable_amount": "10.00", "title": "Shirt package", "total_price": "11.30", "unit_price": "10.00", "unit_price_includes_tax": false, "variant_title": "Blue T-shirt" } ], "note": "next order in sequence 3", "order_attributes": [ { "name": "Checkout-Method", "value": "delivery" } ], "orders_count": 1, "payment_processor": "stripe", "processed_at": "2021-11-09T23:59:31+00:00", "retry_date": null, "scheduled_at": "2021-12-09", "shipping_address": { "address1": "1030 Barnum Ave", "address2": "Suite 101", "city": "Stratford", "company": "Fake Company", "country_code": "US", "first_name": "Fake First", "last_name": "Fake Last", "phone": "999-999-9999", "province": "Connecticut", "zip": "06614" }, "shipping_lines": [ { "code": "Standard", "price": "4.90", "source": "shopify", "taxable": true, "tax_lines": [ { "price": "0.355", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.110", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "title": "Standard" } ], "status": "refunded", "subtotal_price": "10.00", "tags": "Subscription, Subscription Recurring Order", "tax_lines": [ { "price": "0.950", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.335", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "taxable": true, "total_discounts": "10.0", "total_line_items_price": "10.00", "total_price": "11.29", "total_refunds": "11.29", "total_tax": "1.29", "total_weight_grams": 454, "type": "recurring", "updated_at": "2021-11-09T23:59:32+00:00" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "string", "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": "If the retry parameter has value true , this value is required. Valid values are “insufficient_inventory”." }, "error_type": { "type": "string", "description": "If the retry parameter has value true , this value is required." } }, "required": [ "amount" ] }, "example": { "amount": 11 } } } }, "x-recharge-scopes": [ "write_orders", "write_payment_methods" ] } }, "/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": [ { "purchase_item_id": 63898947, "external_product_id": { "ecommerce": "4381728735283" }, "external_variant_id": { "ecommerce": "999999999999" }, "grams": 454, "handle": "shirt-package", "images": { "large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg", "medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg", "original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg", "small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg" }, "original_price": "10.00", "properties": [ { "name": "Color", "value": "Blue" } ], "purchase_item_type": "subscription", "quantity": 1, "sku": "TOM0001", "tax_due": "1.30", "tax_lines": [ { "price": "0.9931", "rate": "0.0725", "title": "CA State Tax", "unit_price": "0.3310" }, { "price": "0.3082", "rate": "0.0225", "title": "LA County Tax", "unit_price": "0.1027" } ], "taxable": true, "taxable_amount": "10.00", "title": "Shirt package", "total_price": "11.30", "unit_price": "10.00", "unit_price_includes_tax": false, "variant_title": "Blue T-shirt" } ], "note": "next order in sequence 3", "order_attributes": [ { "name": "Checkout-Method", "value": "delivery" } ], "orders_count": 1, "payment_processor": "stripe", "processed_at": "2021-11-09T23:59:31+00:00", "retry_date": null, "scheduled_at": "2021-12-09", "shipping_address": { "address1": "1030 Barnum Ave", "address2": "Suite 101", "city": "Stratford", "company": "Fake Company", "country_code": "US", "first_name": "Fake First", "last_name": "Fake Last", "phone": "999-999-9999", "province": "Connecticut", "zip": "06614" }, "shipping_lines": [ { "code": "Standard", "price": "4.90", "source": "shopify", "taxable": true, "tax_lines": [ { "price": "0.355", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.110", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "title": "Standard" } ], "status": "success", "subtotal_price": "10.00", "tags": "Subscription, Subscription Recurring Order", "tax_lines": [ { "price": "0.950", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.335", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "taxable": true, "total_discounts": "10.0", "total_line_items_price": "10.00", "total_price": "11.29", "total_refunds": "0.00", "total_tax": "1.29", "total_weight_grams": 454, "type": "recurring", "updated_at": "2021-11-09T23:59:32+00:00" } } } } } }, "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": [ { "purchase_item_id": 63898947, "external_product_id": { "ecommerce": "4381728735283" }, "external_variant_id": { "ecommerce": "999999999999" }, "grams": 454, "handle": "shirt-package", "images": { "large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg", "medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg", "original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg", "small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg" }, "original_price": "10.00", "properties": [ { "name": "Color", "value": "Blue" } ], "purchase_item_type": "subscription", "quantity": 1, "sku": "TOM0001", "tax_due": "1.30", "tax_lines": [ { "price": "0.9931", "rate": "0.0725", "title": "CA State Tax", "unit_price": "0.3310" }, { "price": "0.3082", "rate": "0.0225", "title": "LA County Tax", "unit_price": "0.1027" } ], "taxable": true, "taxable_amount": "10.00", "title": "Shirt package", "total_price": "11.30", "unit_price": "10.00", "unit_price_includes_tax": false, "variant_title": "Blue T-shirt" } ], "note": "next order in sequence 3", "order_attributes": [ { "name": "Checkout-Method", "value": "delivery" } ], "orders_count": 1, "payment_processor": "stripe", "processed_at": "2021-11-09T23:59:31+00:00", "retry_date": null, "scheduled_at": "2021-12-09", "shipping_address": { "address1": "1030 Barnum Ave", "address2": "Suite 101", "city": "Stratford", "company": "Fake Company", "country_code": "US", "first_name": "Fake First", "last_name": "Fake Last", "phone": "999-999-9999", "province": "Connecticut", "zip": "06614" }, "shipping_lines": [ { "code": "Standard", "price": "4.90", "source": "shopify", "taxable": true, "tax_lines": [ { "price": "0.355", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.110", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "title": "Standard" } ], "status": "success", "subtotal_price": "10.00", "tags": "Subscription, Subscription Recurring Order", "tax_lines": [ { "price": "0.950", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.335", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "taxable": true, "total_discounts": "10.0", "total_line_items_price": "10.00", "total_price": "11.29", "total_refunds": "0.00", "total_tax": "1.29", "total_weight_grams": 454, "type": "recurring", "updated_at": "2021-11-09T23:59:32+00:00" } } } } }, "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_customers", "write_orders", "write_payment_methods", "write_subscriptions" ] } }, "/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": [ { "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" } ], "note": "next order in sequence 3", "order_attributes": [ { "name": "Checkout-Method", "value": "delivery" } ], "orders_count": 1, "payment_processor": "stripe", "processed_at": "2021-11-09T23:59:31+00:00", "retry_date": "2021-01-01", "scheduled_at": "2021-12-09", "shipping_address": { "address1": "1030 Barnum Ave", "address2": "Suite 101", "city": "Stratford", "company": "Fake Company", "country_code": "US", "first_name": "Fake First", "last_name": "Fake Last", "phone": "999-999-9999", "province": "Connecticut", "zip": "06614" }, "shipping_lines": [ { "code": "Standard", "price": "4.90", "source": "shopify", "taxable": true, "tax_lines": [ { "price": "0.355", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.110", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "title": "Standard" } ], "status": "success", "subtotal_price": "10.00", "tags": "Subscription, Subscription Recurring Order", "tax_lines": [ { "price": "0.950", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.335", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "taxable": true, "taxes_included": true, "total_discounts": "10.0", "total_line_items_price": "10.00", "total_price": "11.29", "total_refunds": "0.00", "total_tax": "1.29", "total_weight_grams": 454, "type": "recurring", "updated_at": "2021-11-09T23:59:32+00:00" } } } } }, "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 ." } } }, "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." } } }, "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": [ { "purchase_item_id": 63898947, "external_product_id": { "ecommerce": "4381728735283" }, "external_variant_id": { "ecommerce": "999999999999" }, "grams": 454, "handle": "shirt-package", "images": { "large": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_large.jpg", "medium": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_medium.jpg", "original": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h.jpg", "small": "https://example-cdn.com/s/files/1/0257/0351/4163/products/il_570xN.1723312095_a43h_small.jpg" }, "original_price": "10.00", "properties": [ { "name": "Color", "value": "Blue" } ], "purchase_item_type": "subscription", "quantity": 1, "sku": "TOM0001", "tax_due": "1.30", "tax_lines": [ { "price": "0.9931", "rate": "0.0725", "title": "CA State Tax", "unit_price": "0.3310" }, { "price": "0.3082", "rate": "0.0225", "title": "LA County Tax", "unit_price": "0.1027" } ], "taxable": true, "taxable_amount": "10.00", "title": "Shirt package", "total_price": "11.30", "unit_price": "10.00", "unit_price_includes_tax": false, "variant_title": "Blue T-shirt" } ], "note": "next order in sequence 3", "order_attributes": [ { "name": "Checkout-Method", "value": "delivery" } ], "orders_count": 1, "payment_processor": "stripe", "processed_at": "2021-11-09T23:59:31+00:00", "retry_date": "2021-01-01", "scheduled_at": "2021-12-09", "shipping_address": { "address1": "1030 Barnum Ave", "address2": "Suite 101", "city": "Stratford", "company": "Fake Company", "country_code": "US", "first_name": "Fake First", "last_name": "Fake Last", "phone": "999-999-9999", "province": "Connecticut", "zip": "06614" }, "shipping_lines": [ { "code": "Standard", "price": "4.90", "source": "shopify", "taxable": true, "tax_lines": [ { "price": "0.355", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.110", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "title": "Standard" } ], "status": "success", "subtotal_price": "10.00", "tags": "Subscription, Subscription Recurring Order", "tax_lines": [ { "price": "0.950", "rate": 0.0725, "title": "CA State Tax" }, { "price": "0.335", "rate": 0.0225, "title": "Los Angeles County Tax" } ], "taxable": true, "taxes_included": true, "total_discounts": "10.0", "total_line_items_price": "10.00", "total_price": "11.29", "total_refunds": "0.00", "total_tax": "1.29", "total_weight_grams": 454, "type": "recurring", "updated_at": "2021-11-09T23:59:32+00:00" } } } } } }, "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" } } ], "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", "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": [ { "name": "size", "value": "xl" }, { "name": "color", "value": "fuchsia" } ], "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." } } }, "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." } } }, "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." } }, "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." }, "external_transaction_id": { "type": "object", "properties": { "payment_processor": { "type": "integer", "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": { "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 ." }, "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." }, "sort_order": { "type": "integer", "description": "The sort order in which the x image from the array should appear when displayed." } }, "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." }, "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 ." }, "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 ." }, "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 ." } } }, "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." }, "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 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", "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": [ { "name": "size", "value": "xl" } ], "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" } } ], "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", "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, "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": "array", "items": { "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_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": "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." } }, "description": "Billing address for the checkout." }, "buyer_accepts_marketing": { "type": "boolean", "description": "Does the buyer accept marketing, newsletters etc." }, "discount_code": { "type": "string", "description": "Discount code to be used on the checkout, e.g. “DISCOUNT20”." }, "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 ." }, "line_items": { "type": "array", "items": { "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. 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 ." }, "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." }, "sort_order": { "type": "integer", "description": "The sort order in which the x image from the array should appear when displayed." } }, "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." }, "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 ." }, "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 ." }, "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 ." } } }, "description": "quantity , product_id and variant_id are required parameters in line_items." }, "note": { "type": "string", "description": "Note attribute used to store custom notes." }, "partial_shipping": { "type": "boolean", "description": "When set to true, shipping address validations are reduced to only require country and zip when creating/updating a checkout. The full shipping address including address line 1 must be added to the checkout before processing associated charges. This is helpful for mobile payments. Related guides: Mobile payments" }, "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." }, "phone": { "type": "string", "description": "Customer phone number." }, "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 for the checkout." }, "shipping_line": { "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": "string", "description": "A boolean indicating if the shipping_line is taxable." }, "tax_lines": { "description": "An array of tax lines associated with the shipping_line ." } } }, "description": "Shipping lines." } } }, "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}/charge": { "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": { "payment_processor": { "type": "string", "description": "The name of payment processor.", "enum": [ "stripe", "braintree", "authorize" ] }, "payment_token": { "type": "string", "description": "Payment token that will be used in transaction." }, "payment_type": { "type": "string", "description": "The payment type used for the Checkout .", "enum": [ "CREDIT_CARD", "PAYPAL", "APPLE_PAY", "GOOGLE_PAY", "SEPA_DEBIT" ] } }, "required": [ "payment_processor", "payment_token" ] }, "example": { "payment_processor": "stripe", "payment_token": "", "payment_type": "CREDIT_CARD" } } } }, "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", "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", "title-asc", "title-desc", "created-asc", "created-desc" ], "default": "id-desc" }, "title": { "type": "string", "description": "The title of the Collection . A short descriptive definition of the Collection ." } }, "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" } } ], "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", "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.", "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", "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", "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", "title-asc", "title-desc", "created-asc", "created-desc" ] }, "title": { "type": "string", "description": "The title of the Collection . A short descriptive definition of the Collection ." } } }, "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" } } ], "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 ." } } }, "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 ." } } }, "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" ] } }, "/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 ." } }, "required": [ "customer_id", "name", "type" ] } } } }, "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" } } ], "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" } } ], "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": "string", "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" ] } }, "required": [ "amount", "type" ] }, "example": { "amount": "10.00", "note": "Gift card purchase", "type": "debit" } } } }, "x-recharge-scopes": [ "write_credit_adjustments" ] }, "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" } } ], "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": "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" } }, { "name": "limit", "in": "query", "required": false, "description": "The amount of results. Default is 50 while the maximum is 250.", "schema": { "type": "string" } }, { "name": "undefined", "in": "query", "required": false, "description": "Sort the results by the given field.", "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" } } ], "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" ] } }, "/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" } ] }, "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", "phone": null, "subscriptions_active_count": 0, "subscriptions_total_count": 0, "subscription_related_charge_streak": 0, "tax_exempt": false, "updated_at": "2020-12-17T18:50:39+00:00" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "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", "write_payment_methods" ] }, "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" } } ], "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" } ] }, "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", "phone": "+16175551212", "subscriptions_active_count": 0, "subscriptions_total_count": 1, "tax_exempt": false, "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" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "customer": { "id": 37657002, "analytics_data": { "utm_params": [ { "utm_source": "facebook", "utm_medium": "cpc" } ] }, "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", "phone": "+16175551212", "subscriptions_active_count": 0, "subscriptions_total_count": 1, "subscription_related_charge_streak": 0, "tax_exempt": false, "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" } ] }, "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", "phone": "+16175551212", "subscriptions_active_count": 0, "subscriptions_total_count": 1, "tax_exempt": false, "updated_at": "2020-12-17T18:50:39+00:00" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "apply_credit_to_next_recurring_charge": { "type": "boolean", "description": "A boolean that indicates whether Recharge credits will be applied to the next recurring charge." }, "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." }, "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" } } ], "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, "applies_to": { "ids": [], "purchase_item_type": "ALL", "resource": null }, "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", "ends_at": null, "external_discount_id": { "ecommerce": null }, "external_discount_source": null, "prerequisite_subtotal_min": null, "starts_at": null, "status": "enabled", "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 }, "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": [ "product", "shopify_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 ." }, "prerequisite_subtotal_min": { "type": "integer", "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", "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." } }, "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" } } } } }, "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": "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": "discount_code", "in": "query", "required": false, "description": "Search for a particular discount code.", "schema": { "type": "string" } }, { "name": "value_type", "in": "query", "required": false, "description": "Filter based on type of discount.", "schema": { "type": "string", "enum": [ "percentage", "fixed_amount", "shipping" ] } }, { "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" } } ], "responses": { "200": { "description": "successful response", "content": { "application/json": { "example": { "next_cursor": null, "previous_cursor": null, "discounts": [ { "id": 59568555, "applies_to": { "ids": [], "purchase_item_type": "ALL", "resource": null }, "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", "ends_at": null, "external_discount_id": { "ecommerce": null }, "external_discount_source": null, "prerequisite_subtotal_min": null, "starts_at": null, "status": "enabled", "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 }, "value": "100.00", "value_type": "percentage" } ] } } } } } } }, "/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, "applies_to": { "ids": [], "purchase_item_type": "ALL", "resource": null }, "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", "ends_at": null, "external_discount_id": { "ecommerce": null }, "external_discount_source": null, "prerequisite_subtotal_min": null, "starts_at": null, "status": "enabled", "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 }, "value": "100.00", "value_type": "percentage" } } } } } } }, "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, "applies_to": { "ids": [], "purchase_item_type": "ALL", "resource": null }, "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", "ends_at": null, "external_discount_id": { "ecommerce": null }, "external_discount_source": null, "prerequisite_subtotal_min": null, "starts_at": null, "status": "enabled", "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 }, "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": [ "product", "shopify_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 ." }, "prerequisite_subtotal_min": { "type": "integer", "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." } }, "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" } } } } }, "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": {} } } } } } }, "/customer_entitlements": { "get": { "operationId": "list_customer_entitlements", "summary": "List customer entitlements", "description": "Retrieve all entitlements for a customer.", "tags": [ "Entitlements" ], "parameters": [ { "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" ] } } ], "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" ] }, "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" ] } }, "/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": "string", "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_{target_resource}" ] }, "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": "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": "string" } }, { "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 } } ], "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_{target_resource}" ] } }, "/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_{target_resource}" ] }, "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": "string", "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_{target_resource}" ] }, "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_{target_resource}" ] } }, "/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": "integer", "description": "Identifies the type of the notifications. Value can be email only." }, "template_type": { "type": "string", "description": "Identifies the type of the email notifications.", "enum": [ "upcoming_charge", "get_account_access", "shopify_update_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." } }, "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", "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 ." }, "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-time", "description": "This will set the charge date of a new Onetime purchase." }, "price": { "type": "string", "description": "The price of the product." }, "product_title": { "type": "string", "description": "The name of the product." }, "properties": { "type": "string", "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." } }, "required": [ "address_id", "external_variant_id", "next_charge_scheduled_at", "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": "array", "items": {} } } ], "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", "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" } } ], "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", "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", "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 )" }, "next_charge_scheduled_at": { "type": "string", "format": "date-time", "description": "This will set the charge date of a new Onetime purchase." }, "price": { "type": "string", "description": "The price of the product." }, "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." }, "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" } } ], "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" } }, "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_number": { "ecommerce": "1938" }, "is_prepaid": false, "line_items": [ { "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" } }, "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_number": { "ecommerce": "1938" }, "is_prepaid": false, "line_items": [ { "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": { "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": "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 ." }, "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." }, "sort_order": { "type": "integer", "description": "The sort order in which the x image from the array should appear when displayed." } }, "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." } } }, "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": "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": [ "success", "error", "queued", "cancelled" ] } } }, "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" } } ], "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" } }, "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_number": { "ecommerce": "1938" }, "is_prepaid": false, "line_items": [ { "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." } }, "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, "is_prepaid": true, "line_items": [ { "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": "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": "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": "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": "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": "status", "in": "query", "required": false, "description": "Filter orders by status.", "schema": { "type": "string", "enum": [ "success", "queued", "error", "refunded", "skipped" ] } }, { "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" } }, "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_number": { "ecommerce": "1938" }, "is_prepaid": false, "line_items": [ { "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_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": { "customer_id": { "type": "integer", "description": "The Recharge customer_id ." }, "default": { "type": "boolean", "description": "true if this is default payment method for the Customer." }, "payment_type": { "type": "string", "description": "The type of payment.", "enum": [ "CREDIT_CARD", "PAYPAL", "APPLE_PAY", "GOOGLE_PAY", "SEPA_DEBIT" ] }, "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" ] }, "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_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." }, "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", "payment_type", "processor_customer_token", "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" } } ], "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_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" } } ], "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_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_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." }, "processor_name": { "type": "string", "description": "This will impact validation on billing_details.", "enum": [ "stripe", "braintree", "authorize", "shopify_payments", "mollie" ] }, "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": "An object with the customer’s address information." } } }, "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" }, "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", "type": "subscription", "updated_at": "2021-07-27T19:07:34+00:00" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "channel_settings": { "type": "string", "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 ." } }, "description": "An object containing the product id as it appears in external platforms." }, "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." }, "type": { "type": "string", "description": "The type of the plan. Products with a prepaid plan cannot have plans of other types.", "enum": [ "subscription", "prepaid", "onetime" ] } }, "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", "onetime" ] } } ], "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" }, "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", "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" }, "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", "type": "subscription", "updated_at": "2021-07-27T19:07:34+00:00" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "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." }, "sort_order": { "type": "string", "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." } } }, "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" ] } }, "/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" }, "sort_order": 1, "title": "Concert T-Shirt", "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" }, "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 }, "updated_at": "2021-07-27T19:07:34+00:00" } ] } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "plans": { "type": "array", "items": { "type": "object", "properties": { "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" ] }, "sort_order": { "type": "string", "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." }, "type": { "type": "string", "description": "The type of the plan. Products with a prepaid plan cannot have plans of other types.", "enum": [ "subscription", "prepaid", "onetime" ] } } }, "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" }, "sort_order": 1, "title": "Concert T-Shirt", "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" }, "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 }, "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": "string", "description": "The ID of the plan." }, "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" ] }, "sort_order": { "type": "string", "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" ] } }, "description": "An object containing the various subscription preferences associated with this plan." }, "title": { "type": "string", "description": "The title of the plan." } } }, "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": "string", "description": "The ID of the plan." } } }, "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" ] } }, "/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": { "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 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": { "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": "string", "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": "integer", "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." }, "sort_order": { "type": "integer", "description": "The sort order in which the x image from the array should appear when displayed." } }, "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." } }, "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": "string", "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." } }, "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" } } ], "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." }, "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": { "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": "integer", "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." }, "sort_order": { "type": "integer", "description": "The sort order in which the x image from the array should appear when displayed." } }, "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." } }, "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": "string", "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." } } }, "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" ] } }, "/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, "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", "identifier": "store-id", "merchant_portal_base_url": null, "name": "store-name", "province": "Connecticut", "phone": "5555555555", "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" ] } }, "/subscriptions": { "post": { "operationId": "subscriptions_create", "summary": "Create a subscription", "description": "", "tags": [ "Subscriptions" ], "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_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." }, "charge_interval_frequency": { "type": "integer", "description": "The number of units, specified in order_interval_unit , between each charge." }, "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-time", "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." }, "price": { "type": "string", "description": "The price of the product." }, "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." }, "status": { "type": "string", "description": "Default is set to active .", "enum": [ "active", "cancelled", "expired" ] } }, "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": "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_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": "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": "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_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" } } ], "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_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_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": { "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." }, "expire_after_specific_number_of_charges": { "type": "integer", "description": "The number of charges until subscription expires." }, "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." }, "order_day_of_month": { "type": "string", "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": "string", "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": "string", "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" ] }, "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." }, "price": { "type": "string", "description": "The price of the item before discounts, taxes, or shipping has been applied." }, "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": "string", "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." }, "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" } } ], "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" } } ], "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_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", "description": "The next charge date desired." } }, "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_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" } } ], "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_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" } }, "required": [ "cancellation_reason" ] }, "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" } } ], "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_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" } } } } } }, "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, "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." } }, "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" ] } }, "/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": "integer", "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": [ "addresses", "collections", "customer", "metafields" ] }, "topic": { "type": "integer", "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." } }, "required": [ "address", "topic" ] }, "example": { "address": "https://request.in/foo", "topic": "subscription/created", "version": "2021-11" } } } } }, "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" ], "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": [ "addresses", "collections", "customer", "metafields" ] }, "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." } } }, "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, "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": [ "discount_create", "discount_update", "discount_delete", "bulk_plans_create", "bulk_plans_update", "bulk_plans_delete", "onetime_create", "onetime_delete" ] } } }, "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" ], "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, "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, "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, "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" } ] } } } } } } }, "/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, "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" } } } } } } } }, "/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, "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" } } } } } } } }, "/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": { "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" }, "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": "string", "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", "processing", "failed", "success" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "Indicates the date and time a task was most recently updated" } } }, "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 } } ] } } } } }, "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" } } ], "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, "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, "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, "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, "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, "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, "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, "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, "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, "started_at": null, "status": "pending", "updated_at": "2022-02-17T06:40:53+00:00" } ] } } } } } } }, "/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", "name": "token name", "scopes": [ "read_store", "write_payment_methods" ] } } } } } } } }, "/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" } } ], "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 } } } } } }, "x-recharge-scopes": [ "read_accounts" ] } }, "/accounts": { "get": { "operationId": "accounts_list", "summary": "List accounts", "description": "Returns all accounts associated to the store.", "tags": [ "Accounts" ], "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 }, { "id": 3316125, "user_id": 2056785, "created_at": "2021-05-20T09:10:19+00:00", "invited_at": null, "is_owner": true } ] } } } } }, "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" } }, { "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" } } ], "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 ." }, "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_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." }, "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_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." }, "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" ] } } }, "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." }, "external_variant_id_not_found": { "type": "boolean", "description": "Indicates if Recharge was able to find the external_variant_id from the Charge ." }, "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": "integer", "description": "The ID of the associated transaction in a payment processor system (like Stripe)." } }, "description": "An object containing the associated external transaction ID." }, "has_uncommited_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 )." }, "line_items": { "type": "array", "items": { "type": "object", "properties": { "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." }, "sort_order": { "type": "integer", "description": "The sort order in which the x image from the array should appear when displayed." } }, "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." } } }, "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", "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": "string", "description": "A boolean indicating if the shipping_line is taxable." }, "tax_lines": { "description": "An array of tax lines associated with the shipping_line ." } } }, "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", "percentage" ] } } }, "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": "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 ." }, "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": "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 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." }, "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." }, "external_customer_id": { "type": "object", "properties": { "ecommerce": { "type": "string", "description": "The customer ID as it appears in the external e-commerce platform." } }, "description": "External customer reference, if one exists." }, "external_transaction_id": { "type": "object", "properties": { "payment_processor": { "type": "integer", "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_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": "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 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": { "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" ] } }, "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." } } }, "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 total weight of the line_item ." }, "weight_unit": { "type": "string", "description": "The measurement unit of the weight of the 'line_item`.", "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": [ "sms_reminder", "store_opt_in_widget", "replenishment_checkout", "script", "rechargesms_app", "customer_sms", "subscription_checkout_extension", "recharge_checkout", "sci_cart" ] }, "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": [ "sms_reminder", "store_opt_in_widget", "replenishment_checkout", "script", "rechargesms_app", "customer_sms", "subscription_checkout_extension", "recharge_checkout", "sci_cart" ] }, "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": [ "sms_reminder", "store_opt_in_widget", "replenishment_checkout", "script", "rechargesms_app", "customer_sms", "subscription_checkout_extension", "recharge_checkout", "sci_cart" ] }, "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": [ "sms_reminder", "store_opt_in_widget", "replenishment_checkout", "script", "rechargesms_app", "customer_sms", "subscription_checkout_extension", "recharge_checkout", "sci_cart" ] }, "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": [ "sms_reminder", "store_opt_in_widget", "replenishment_checkout", "script", "rechargesms_app", "customer_sms", "subscription_checkout_extension", "recharge_checkout", "sci_cart" ] }, "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": [ "sms_reminder", "store_opt_in_widget", "replenishment_checkout", "script", "rechargesms_app", "customer_sms", "subscription_checkout_extension", "recharge_checkout", "sci_cart" ] }, "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": [ "sms_reminder", "store_opt_in_widget", "replenishment_checkout", "script", "rechargesms_app", "customer_sms", "subscription_checkout_extension", "recharge_checkout", "sci_cart" ] }, "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": [ "sms_reminder", "store_opt_in_widget", "replenishment_checkout", "script", "rechargesms_app", "customer_sms", "subscription_checkout_extension", "recharge_checkout", "sci_cart" ] }, "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": [ "sms_reminder", "store_opt_in_widget", "replenishment_checkout", "script", "rechargesms_app", "customer_sms", "subscription_checkout_extension", "recharge_checkout", "sci_cart" ] }, "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": [ "sms_reminder", "store_opt_in_widget", "replenishment_checkout", "script", "rechargesms_app", "customer_sms", "subscription_checkout_extension", "recharge_checkout", "sci_cart" ] }, "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": [ "sms_reminder", "store_opt_in_widget", "replenishment_checkout", "script", "rechargesms_app", "customer_sms", "subscription_checkout_extension", "recharge_checkout", "sci_cart" ] }, "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": [ "sms_reminder", "store_opt_in_widget", "replenishment_checkout", "script", "rechargesms_app", "customer_sms", "subscription_checkout_extension", "recharge_checkout", "sci_cart" ] }, "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." }, "zip": { "type": "string", "description": "The zip code or postcode of the address." } }, "description": "Shipping Address for the Checkout ." }, "shipping_lines": { "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": "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 Checkout contains items that are taxable." }, "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 ." }, "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", "title-asc", "title-desc", "created_at-asc", "created_at-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 .", "enum": [ "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 ." }, "updated_at": { "type": "string", "format": "date-time", "description": "The date and time at which the credit account was last updated." } } }, "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_recurring_charge": { "type": "boolean", "description": "A boolean that indicates whether Recharge credits will be applied to the next recurring charge." }, "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." }, "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": [ "product", "shopify_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. 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." }, "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." }, "first_time_customer_restriction": { "type": "boolean", "description": "Discount can be used on checkout for customer that still don’t exist in Recharge database." }, "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." } }, "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", "manual" ] }, "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." } } }, "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": "string", "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 )" }, "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": "string", "description": "An object containing the product id as it appears in external platforms." }, "external_variant_id": { "type": "string", "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-time", "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", "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": "integer", "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." } }, "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." }, "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" ] } } }, "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": { "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": { "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." }, "sort_order": { "type": "integer", "description": "The sort order in which the x image from the array should appear when displayed." } }, "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." } } }, "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": "string", "description": "A boolean indicating if the shipping_line is taxable." }, "tax_lines": { "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": [ "success", "error", "queued", "cancelled" ] }, "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": "integer", "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 ." }, "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": { "brand": { "type": "string", "description": "Payment_method brand or company powering it." }, "exp_month": { "type": "string", "description": "Payment_method expiry month." }, "exp_year": { "type": "string", "description": "Payment_method expiry year." }, "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" }, "payment_type": { "type": "string", "description": "The type of payment this is.", "enum": [ "CREDIT_CARD", "PAYPAL", "APPLE_PAY", "GOOGLE_PAY", "SEPA_DEBIT" ] }, "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" ] }, "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_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 ." }, "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." }, "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": "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." }, "type": { "type": "string", "description": "The type of the plan.", "enum": [ "subscription", "prepaid", "onetime" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "The time the plan was last updated." } } }, "products_object": { "type": "object", "properties": { "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": { "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": "integer", "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." }, "sort_order": { "type": "integer", "description": "The sort order in which the x image from the array should appear when displayed." } }, "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." } }, "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": "string", "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." } } }, "store_object": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique number identifier of the store." }, "checkout_logo_url": { "type": "string", "description": "Checkout logo url." }, "checkout_platform": { "type": "string", "description": "Checkout platform." }, "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": "integer", "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." }, "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." }, "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": "string", "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." }, "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-time", "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": [ "addresses", "collections", "customer", "metafields" ] }, "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." } } }, "async_batch_endpoints_object": { "type": "object", "properties": { "id": { "type": "string", "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": [ "discount_create", "discount_update", "discount_delete", "bulk_plans_create", "bulk_plans_update", "bulk_plans_delete", "onetime_create", "onetime_delete" ] }, "closed_at": { "type": "string", "description": "Indicates the date and time that processing was completed for a batch" }, "created_at": { "type": "string", "description": "Indicates the date and time a batch was created" }, "fail_task_count": { "type": "string", "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" }, "submitted_at": { "type": "string", "description": "Indicates the date and time that a batch was triggered to process" }, "success_task_count": { "type": "string", "description": "Indicates the number of successful tasks in a batch, during or after processing." }, "total_task_count": { "type": "string", "description": "Indicates the total number of tasks in a batch" }, "updated_at": { "type": "string", "description": "Indicates the date and time at which a batch was last updated" }, "version": { "type": "string", "description": "Indicates the API version of the batch." } } }, "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" }, "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": "string", "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", "processing", "failed", "success" ] }, "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." }, "email": { "type": "string", "description": "The client's email." } }, "description": "If the API Token was generated by an Oauth app, an object containing associated client information." }, "contact_email": { "type": "string", "description": "The email associated with the API Token record." }, "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." } } }, "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." }, "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": "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": "string", "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'" }, "user_type": { "type": "string", "description": "The type of user who initiated the event, e.g. 'customer', 'store_admin', 'recharge_admin', 'recharge_process'" } }, "description": "An object containing details about the origin of the Event ." }, "custom_attributes": { "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 ." } } } } } }