Create a Recurring Charge

Creates a subscription charge for your application. The seller must approve the charge once — YouCan then handles renewals automatically at each billing interval.

Endpoint: https://api.youcan.shop/billing/apps/charges/recurring

Method: POST

Parameters

Parameter	Type	Required	Validation	Description
name	string	Yes	max:255	Display name shown to the seller on the confirmation page.
return_url	string	Yes	url, max:2048	URL to redirect the seller to after they approve or decline.
trial_days	integer	No	min:0, max:90	Number of free trial days before the first charge. Defaults to 0.
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[].price.amount	numeric	Yes*	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 when plans[].type is "time_based".

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",
  "plans": [
    {
      "interval": 30,
      "price": {
        "amount": "19.99",
        "currency": "USD"
      }
    }
  ],
  "test": false,
  "trial_days": 7,
  "created_at": 1640995200,
  "period_ends_at": null,
  "confirmation_url": "https://..."
}

Redirect the seller to confirmation_url immediately after receiving this response.

TIP

The charge remains in pending status until the seller approves or declines it. Verify the final status via List charges after the seller is redirected back to your return_url.

WARNING

Plan upgrades and downgrades go through the same approval flow and create a new recurring charge. If both plans share the same interval (30_days), proration applies. Otherwise, the new plan is deferred to the next billing cycle.

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.
confirmation_url	string	URL for the seller to approve or decline the charge. Only present when status is pending.