Update subscription with the Recharge API
Changes an active subscription and returns it. Changing order_interval_unit, order_interval_frequency or charge_interval_frequency needs all three, recalculates the next charge date and removes skipped and manually changed charges. To move only the next charge, use Set subscription next charge date.
- Identifier
- recharge_update_subscription
The request
POST https://connect.reportei.com/api/tools/recharge_update_subscription/execute
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Content-Type: application/json
Accept: application/json
{
"customer_toolkit": "<connection UUID>",
"arguments": {
"id": 1
}
}Your system sends your customer's connection id and the tool arguments. The headers are the same as the rest of the Connect API: your product's token and your customer's token.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | integer | Yes | Id of a subscription from List subscriptions. |
| quantity | integer | No | Number of units in each order. |
| price | string | No | Price of one unit before discounts, taxes and shipping, such as 10.00. |
| external_variant_id | object | No | New product variant in the store platform, to swap the product. The variant id comes from external_variant_id of a subscription in List subscriptions, or from the product page in the store admin. |
| use_external_variant_defaults | boolean | No | With a new external_variant_id, takes the price from that variant. |
| product_title | string | No | Name of the product. |
| variant_title | string | No | Name of the product variant. |
| sku | string | No | SKU used for the charges and orders of this subscription in place of the SKU of the variant. |
| order_interval_unit | string | No | Unit of the order and charge frequencies. Send it with order_interval_frequency and charge_interval_frequency.Values: day, week, month |
| order_interval_frequency | integer | No | Number of order_interval_unit between orders. |
| charge_interval_frequency | integer | No | Number of order_interval_unit between charges. |
| order_day_of_month | integer | No | Day of the month the orders are created on. Removes skipped and manually changed charges. |
| order_day_of_week | integer | No | Day of the week the orders are created on. Removes skipped and manually changed charges. |
| expire_after_specific_number_of_charges | integer | No | Number of charges after which the subscription expires. |
| properties | array | No | Line item properties of the subscription, such as a color or an engraving text. The list replaces the current one. |
| commit | boolean | No | True waits until the queued charges of the subscription are regenerated before answering. The default is false, which regenerates them a few seconds later. |
| force_update | boolean | No | True also applies the change to a cancelled subscription. |
Supported connections
Your customer connects their Recharge account once, with one of the modes below. The same connection serves every tool of the toolkit.
API key
Your customer pastes the app's key on a Connect screen, or your system sends the key with POST /api/customer-toolkits, with no screen.
The response
On success, Connect preserves the app's response status and body. HTTP errors returned by the app use the {error, api_error} envelope; authentication or validation can fail before execution. The X-Toolkit-Execution-Id header identifies the recorded execution, available at GET /api/tools/executions/{uuid}.
Ready for AI agents
This tool's input is a JSON Schema, available at GET /api/tools/recharge_update_subscription. It becomes your agent's tool definition with no conversion.
Other Recharge tools
- List subscriptionsGETLists the subscriptions of the store with customer, address, product, quantity, price, frequency, status and next_charge_scheduled_at. Up to 250 per page: pass the next_cursor of the response as cursor to read the next page.
- Get subscriptionGETReturns one subscription with product, quantity, price, frequency, status, cancellation reason and next_charge_scheduled_at.
- Create subscriptionPOSTCreates a subscription on an address of a customer and returns it. The product needs at least one plan in Recharge. The frequency fields, the first charge date, the variant, the quantity and the address are required.
- Cancel subscriptionPOSTCancels an active subscription and returns it. Recharge may email the customer and the store owner about it, unless send_email is false.
- Activate subscriptionPOSTReactivates a cancelled subscription and returns it, clearing the cancellation date and reason.
- Set subscription next charge datePOSTMoves the next charge of a subscription to another date and returns the subscription. When two active subscriptions of the same address end up on the same date, their charges are merged into a new charge with a new id.
- List customersGETLists the customers of the store with email, name, the count of active subscriptions and whether the payment method is valid or in dunning. Filter by email to find one customer. Up to 250 per page: pass the next_cursor of the response as cursor.
- Get customerGETReturns one customer. With include, the response also brings the addresses, subscriptions or payment methods of the customer; the id of each address is the address_id that Create subscription takes.
See Connect applied to your product.
Try it for 15 days with no card, or walk our team through your use case.
