Create a Recurring Charge
Creates a subscription charge for your application. The merchant approves the charge once. YouCan renews it automatically at each billing interval.
Endpoint: https://api.youcan.shop/billing/apps/charges/recurring
Method: POST
Tip
Raw amounts work without any catalog. For your standard tiers, prefer referencing a pricing plan by handle, so your listing and your charges cannot drift apart.
Parameters
| Parameter | Type | Required | Validation | Description |
|---|---|---|---|---|
name | string | Yes | max:255 | Display name shown to the merchant on the confirmation page. |
return_url | string | Yes | url, max:2048 | URL to redirect the merchant to after they approve or decline. If it has the scheme, host and port of your app URL, the merchant returns to your app inside the admin, with the signed session parameters. Otherwise the merchant is redirected to it with no parameters added. |
trial_days | integer | No | min:0, max:90 | Number of free trial days before the first charge. Defaults to 0. A store gets one trial per app. If the store had a trial for your app before, the trial is ignored. If the store changes plan during a trial, the store pays for the new plan only when the current trial ends. |
plans | array | Yes | min:1, max:1 | Array of pricing plans. Currently only one plan is supported. |
plans[].type | string | Yes | "time_based" | The plan type. Must be "time_based". |
plans[].handle | string | No | max:64 | Handle of a pricing plan. Price, interval, and trial come from the plan. |
plans[].price.amount | numeric | Yes* | decimal:0,2, min:0.00, max:1000.00 | Price per billing interval, in USD. |
plans[].interval | string | Yes* | "30_days", "365_days" | Billing interval. "30_days" for monthly, "365_days" for yearly. |
test | boolean | No | - | Mark as a test charge. Defaults to false. Required for non-approved apps and development stores. |
* Required unless plans[].handle is given.
Request
{
"name": "Monthly Subscription",
"return_url": "https://myapp.com/billing/success",
"trial_days": 7,
"plans": [
{
"type": "time_based",
"price": {
"amount": 19.99
},
"interval": "30_days"
}
],
"test": false
}Response
[201]
{
"type": "recurring",
"id": "arch_01234567890abcdef",
"store_id": "...",
"name": "Monthly Subscription",
"status": "pending",
"plan_id": null,
"plans": [
{
"interval": 30,
"price": {
"amount": "19.99",
"currency": "USD"
}
}
],
"test": false,
"trial_days": 7,
"created_at": 1640995200,
"period_ends_at": null,
"canceled_at": null,
"confirmation_url": "https://..."
}Redirect the merchant to confirmation_url immediately after receiving this response.
Tip
The charge remains in pending status until the merchant approves or declines it. Verify the final status via List charges after the merchant is redirected back to your return_url.
Warning
Plan upgrades and downgrades go through the same approval flow and create a new recurring charge. See Plan upgrades and downgrades for when the new plan is applied.
AppRecurringCharge object
| Field | Type | Description |
|---|---|---|
type | string | Always "recurring" for subscription charges. |
id | string | Unique charge identifier, prefixed with arch_. |
store_id | string | ID of the store this charge belongs to. |
name | string | Name of the recurring charge as provided in the request. |
status | string | Current charge status. See charge statuses. |
plans | array | Array of pricing plans. Currently limited to one entry. |
plans[].interval | integer | Billing interval in days (30 or 365). |
plans[].price | object | Price information object. |
plans[].price.amount | string | Subscription amount as a decimal string (e.g. "19.99"). |
plans[].price.currency | string | Currency code. Always "USD". |
test | boolean | Whether this is a test charge. |
trial_days | integer | Number of trial days (0–90). |
created_at | integer | Unix timestamp of charge creation. |
period_ends_at | integer | null | Unix timestamp of when the current billing period ends. null for pending charges. |
canceled_at | integer | null | Unix timestamp of when the charge is or was canceled. Set when the charge is scheduled for cancellation; null otherwise. |
confirmation_url | string | URL for the merchant to approve or decline the charge. Only present when status is pending. |