---
url: https://docs.youcan.shop/apps/billing/charges/onetime.md
---
# Create a One-Time Charge

Creates a single, one-time charge that requires merchant approval. Once created, redirect the merchant to the returned `confirmation_url`. After the merchant responds, YouCan redirects them to your `return_url`.

Endpoint: `https://api.youcan.shop/billing/apps/charges/onetime`

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 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. |
| `plan_handle` | string | No | max:64 | Handle of a [pricing plan](/apps/billing/plans). The charge is priced from the plan. |
| `price.amount` | numeric | Yes\* | decimal:0,2, min:0.00, max:1000.00 | Charge amount in USD. |
| `test` | boolean | No | - | Mark as a test charge. Defaults to `false`. Required for non-approved apps and development stores. |

\* Required unless `plan_handle` is given.

## Request

```json
{
  "name": "Premium Features Unlock",
  "return_url": "https://myapp.com/billing/success",
  "price": {
    "amount": 29.99
  },
  "test": false
}
```

## Response

```json
[201]
{
  "type": "onetime",
  "id": "aoch_01234567890abcdef",
  "store_id": "...",
  "name": "Premium Features Unlock",
  "status": "pending",
  "plan_id": null,
  "price": {
    "amount": "29.99",
    "currency": "USD"
  },
  "test": false,
  "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](/apps/billing/charges/listing) after the merchant is redirected back to your `return_url`.
:::

## AppOnetimeCharge object

| Field | Type | Description |
|---|---|---|
| `type` | string | Always `"onetime"` for one-time charges. |
| `id` | string | Unique charge identifier, prefixed with `aoch_`. |
| `store_id` | string | ID of the store this charge belongs to. |
| `name` | string | Name of the charge as provided in the request. |
| `status` | string | Current charge status. See [charge statuses](/apps/billing/overview#charge-statuses). |
| `price` | object | Price information object. |
| `price.amount` | string | Charge amount as a decimal string (e.g. `"29.99"`). |
| `price.currency` | string | Currency code. Always `"USD"`. |
| `test` | boolean | Whether this is a test charge. |
| `confirmation_url` | string | URL for the merchant to approve or decline the charge. Only present when status is `pending`. |