A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Recharge API is how an app or AI agent works with a Recharge store: listing subscriptions, skipping or processing a charge, updating a customer, and managing the products and plans behind recurring orders. Access is granted through a merchant API token, and that token carries per-resource scopes set to read or read and write, so a call reaches only the resources its scopes allow. Recharge versions its API by date and can push events to a registered endpoint when something changes in the store.
How an app or AI agent connects to Recharge determines what it can reach. There is a route for making calls with a merchant API token, and a route for receiving events as they happen, and each is governed by the token behind it and the scopes that token carries.
The REST API takes JSON request bodies, returns JSON, and pages through lists with a cursor, at https://api.rechargeapps.com. A call authenticates with a merchant API token sent in the X-Recharge-Access-Token header, and selects a dated version with the X-Recharge-Version header.
Recharge POSTs a JSON payload to an HTTPS endpoint registered through the webhooks endpoints, one per topic such as subscription/created or charge/paid. The receiver verifies the payload against the webhook's shared secret to confirm the request came from Recharge, so an integration learns about activity without polling.
A merchant API token is created in the Recharge admin, where each resource is set to no access, read, or read and write. It is sent in the X-Recharge-Access-Token header on every request. The token is the server-side credential for the merchant's own store, and a store can hold several tokens to separate integrations and spread rate-limit load.
A storefront token is a customer-facing credential used by client-side storefront integrations. It carries a narrower set of scopes, such as reading products, reading customers, and reading or writing subscriptions, so it can power a customer portal without exposing full merchant access.
The Recharge API is split into areas an agent can act on, like subscriptions, customers, charges, and orders. Each area has its own methods, and writes in some areas change recurring billing or move a charge toward processing.
Methods for working with subscriptions, the recurring line items on an address.
Methods for working with customers.
Methods for working with the addresses that subscriptions and charges sit on.
Methods for working with charges, which group what bills together.
Methods for working with orders, the records of processed charges.
Methods for working with the products and plans behind subscriptions.
Methods for one-time products and bundle selections on a subscription.
Methods for registering and managing webhook subscriptions.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
SubscriptionsMethods for working with subscriptions, the recurring line items on an address.9 | ||||||
| GET | /subscriptions | List subscriptions, cursor-paginated and filterable. | read | read_subscriptions | Current | |
Read-only; needs the read_subscriptions scope. Acts onsubscription Permission (capability) read_subscriptionsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /subscriptions/{id} | Retrieve a single subscription by id. | read | read_subscriptions | Current | |
Read-only. Acts onsubscription Permission (capability) read_subscriptionsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /subscriptions | Create a subscription on a customer's address. | write | write_subscriptions | Current | |
A core write; needs write_subscriptions. Acts onsubscription Permission (capability) write_subscriptionsVersionAvailable since the API’s base version Webhook event subscription-createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /subscriptions/{id} | Update a subscription, for example its quantity, price, frequency, or product (a product swap is done here). | write | write_subscriptions | Current | |
Swapping a subscription's product is performed by updating it, not a separate endpoint. Acts onsubscription Permission (capability) write_subscriptionsVersionAvailable since the API’s base version Webhook event subscription-updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /subscriptions/{id}/cancel | Cancel a subscription so it stops billing. | write | write_subscriptions | Current | |
Stops recurring billing on the subscription. Acts onsubscription Permission (capability) write_subscriptionsVersionAvailable since the API’s base version Webhook event subscription-cancelledRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /subscriptions/{id}/activate | Reactivate a cancelled subscription. | write | write_subscriptions | Current | |
Resumes recurring billing on a cancelled subscription. Acts onsubscription Permission (capability) write_subscriptionsVersionAvailable since the API’s base version Webhook event subscription-activatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /subscriptions/{id}/skip | Skip an upcoming charge for a subscription. | write | write_subscriptions | Current | |
Skips the next scheduled charge without cancelling the subscription. Acts onsubscription Permission (capability) write_subscriptionsVersionAvailable since the API’s base version Webhook event subscription-skippedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /subscriptions/{id}/change_next_charge_date | Change the date a subscription next charges. | write | write_subscriptions | Current | |
Moves the next charge date on the subscription. Acts onsubscription Permission (capability) write_subscriptionsVersionAvailable since the API’s base version Webhook event subscription-updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /subscriptions/{id}/change_address | Move a subscription to a different address on the customer. | write | write_subscriptions | Current | |
Reassigns the subscription to another of the customer's addresses. Acts onsubscription Permission (capability) write_subscriptionsVersionAvailable since the API’s base version Webhook event subscription-updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CustomersMethods for working with customers.3 | ||||||
| GET | /customers | List customers, cursor-paginated and filterable. | read | read_customers | Current | |
Read-only; needs read_customers. Acts oncustomer Permission (capability) read_customersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /customers/{id} | Retrieve a single customer by id. | read | read_customers | Current | |
Read-only. Acts oncustomer Permission (capability) read_customersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /customers/{id} | Update a customer's details, like email or contact information. | write | write_customers | Current | |
A core write; needs write_customers. Acts oncustomer Permission (capability) write_customersVersionAvailable since the API’s base version Webhook event customer-updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
AddressesMethods for working with the addresses that subscriptions and charges sit on.2 | ||||||
| GET | /addresses | List addresses, cursor-paginated and filterable. | read | read_customers | Current | |
Addresses are governed by the customers scopes; read needs read_customers. Acts onaddress Permission (capability) read_customersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /addresses/{id} | Update an address, like shipping details that future charges will use. | write | write_customers | Current | |
Addresses are governed by the customers scopes; a write needs write_customers. Acts onaddress Permission (capability) write_customersVersionAvailable since the API’s base version Webhook event address-updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ChargesMethods for working with charges, which group what bills together.5 | ||||||
| GET | /charges | List charges, cursor-paginated and filterable by status and date. | read | read_orders | Current | |
Charges are governed by the orders scopes; read needs read_orders. Acts oncharge Permission (capability) read_ordersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /charges/{id} | Retrieve a single charge by id. | read | read_orders | Current | |
Read-only. Acts oncharge Permission (capability) read_ordersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /charges/{id}/skip | Skip a charge so it does not process on its scheduled date. | write | write_orders | Current | |
Charges are governed by the orders scopes; a write needs write_orders. Acts oncharge Permission (capability) write_ordersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /charges/{id}/process | Process a charge immediately rather than waiting for its scheduled date. | write | write_orders | Current | |
Attempts payment now; a success produces an order. Acts oncharge Permission (capability) write_ordersVersionAvailable since the API’s base version Webhook event charge-paidRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /charges/{id}/refund | Refund a processed charge, fully or partially. | write | write_orders | Current | |
Returns money on a processed charge; needs write_orders. Acts oncharge Permission (capability) write_ordersVersionAvailable since the API’s base version Webhook event charge-refundedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
OrdersMethods for working with orders, the records of processed charges.2 | ||||||
| GET | /orders | List orders, the records of charges that have processed. | read | read_orders | Current | |
Read-only; needs read_orders. Acts onorder Permission (capability) read_ordersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /orders/{id} | Retrieve a single order by id. | read | read_orders | Current | |
Read-only. Acts onorder Permission (capability) read_ordersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Products & PlansMethods for working with the products and plans behind subscriptions.3 | ||||||
| GET | /products | List products available for subscription. | read | read_products | Current | |
Read-only; needs read_products. Acts onproduct Permission (capability) read_productsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /plans | List plans, which define how a product is sold and billed. | read | read_plans | Current | |
Read-only; needs read_plans. Acts onplan Permission (capability) read_plansVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /plans | Create a plan defining how a product is offered and billed. | write | write_plans | Current | |
A catalog write; needs write_plans. Acts onplan Permission (capability) write_plansVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
One-times & BundlesMethods for one-time products and bundle selections on a subscription.3 | ||||||
| POST | /onetimes | Add a one-time product to an address to be included on the next charge. | write | write_subscriptions | Current | |
One-times are governed by the subscriptions scopes; a write needs write_subscriptions. Acts ononetime Permission (capability) write_subscriptionsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /bundle_selections | List bundle selections, the contents chosen for a bundle subscription. | read | read_subscriptions | Current | |
Bundle selections are governed by the subscriptions scopes and are available to Recharge Plus merchants. Acts onbundle_selection Permission (capability) read_subscriptionsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /bundle_selections/{id} | Update the items chosen in a bundle selection. | write | write_subscriptions | Current | |
Changes the bundle's contents; governed by write_subscriptions and available to Recharge Plus merchants. Acts onbundle_selection Permission (capability) write_subscriptionsVersionAvailable since the API’s base version Webhook event subscription-updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WebhooksMethods for registering and managing webhook subscriptions.2 | ||||||
| GET | /webhooks | List the webhooks registered on the store. | read | — | Current | |
Webhook management is not governed by a dedicated resource scope. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /webhooks | Register a webhook so Recharge POSTs a payload when a chosen event occurs. | write | — | Current | |
Sets the topic and destination URL; webhook management is not governed by a dedicated resource scope. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Recharge can notify an app when something happens in a store, like a subscription being created or a charge being paid. It POSTs a payload describing what changed to a registered endpoint, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
subscription/created | A subscription was created on an address. | /subscriptions |
subscription/updated | A subscription changed, like its quantity, frequency, product, next charge date, address, or bundle contents. | /subscriptions/{id}/subscriptions/{id}/change_next_charge_date/subscriptions/{id}/change_address/bundle_selections/{id} |
subscription/cancelled | A subscription was cancelled and stops billing. | /subscriptions/{id}/cancel |
subscription/activated | A cancelled subscription was reactivated and resumes billing. | /subscriptions/{id}/activate |
subscription/skipped | An upcoming charge for a subscription was skipped. | /subscriptions/{id}/skip |
charge/paid | A charge processed successfully and payment was collected. | /charges/{id}/process |
charge/refunded | A processed charge was refunded, fully or partially. | /charges/{id}/refund |
customer/updated | A customer's details changed. | /customers/{id} |
address/updated | An address changed, which can affect future charges on it. | /addresses/{id} |
Recharge limits how fast an app can call with a leaky-bucket model: a token holds up to a fixed number of requests that drains at a steady rate per second, and going over returns an error.
Recharge meters requests with a leaky-bucket model per merchant token rather than a per-method cost. Each token holds a bucket of up to 40 requests that drains at 2 requests per second, so a steady 2 per second never trips a limit while short bursts up to 40 are allowed. When the bucket is full, further requests are rejected with HTTP 429 until it drains. A merchant gets this standard 1x1 allowance per token, and using more than one token spreads load across more buckets.
List endpoints are cursor-based. A response includes next_cursor and previous_cursor fields, and the next page is fetched by passing the cursor value in the cursor query parameter. The page size is set with limit, which defaults to 50 and accepts up to 250. From the 2021-11 version on, a list response does not return a total count of records, so pagination moves forward and back by cursor rather than by page number.
A single list page returns at most 250 records, the maximum value of limit. Cursor values are opaque and tie a request to a specific position in a result set; a cursor cannot be combined with most filters once paging has begun.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request was malformed or a parameter was invalid. | Fix the request body or parameters and resend. The request is not retryable as-is. |
| 401 | Unauthorized | No valid merchant API token was provided. | Send a valid token in the X-Recharge-Access-Token header, and rotate the token if it is compromised. |
| 403 | Forbidden | The token lacks the scope the request needs, for example calling a charges method without the orders scope. | Grant the required read or read and write scope on the token, then resend. |
| 404 | Not Found | The requested object does not exist or is not visible to this token. | Verify the object id and confirm the token has access to it. |
| 422 | Unprocessable Entity | The request was well-formed but could not be processed, for example a value that fails a business rule. | Read the error detail, correct the offending field, and resend. |
| 429 | Too Many Requests | The token's leaky bucket of 40 requests is full; the limit drains at 2 requests per second. | Back off and retry after the bucket drains, and keep the steady rate at or under 2 requests per second. |
| 500 | Internal Server Error | An error on Recharge's side. | Retry with backoff, and contact Recharge support if it persists. |
Recharge versions its API by date, set per request with a header, so an integration pins one dated version and moves up deliberately when a newer one ships.
The 2021-11 version is the current dated release of the Recharge API, selected per request with the X-Recharge-Version header. It introduced the payment_methods resource, renamed the shop endpoint to store, deprecated the collections endpoint, and changed pagination so list responses no longer return a total record count, moving forward and back by cursor instead.
The 2021-01 version is the base dated release, a snapshot of the resources and endpoints at that time. It remains available for older integrations, while new integrations are directed to the latest dated version.
Pin a dated version with the X-Recharge-Version header and move up on a schedule that suits the integration.
Recharge changelog ↗Bollard AI sits between a team's AI agents and Recharge. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.