---
url: https://docs.youcan.shop/apps/billing/charges/recurring.md
---
# Create a Recurring Charge

Creates a subscription charge for your application. The seller 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](/apps/billing/plans) 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 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[].handle` | string | No | max:64 | Handle of a [pricing plan](/apps/billing/plans). Price, interval, and trial come from the plan. |
| `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 unless `plans[].handle` is given.

## Request

```json
{
  "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

```json
[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 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](/apps/billing/charges/listing) 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](/apps/billing/overview#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 seller to approve or decline the charge. Only present when status is `pending`. |