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

Creates a single, one-time charge that requires seller approval. Once created, redirect the seller to the returned `confirmation_url`. After the seller 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 seller on the confirmation page. |
| `return_url` | string | Yes | url, max:2048 | URL to redirect the seller to after they approve or decline. |
| `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\* | 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 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`.
:::

## 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 seller to approve or decline the charge. Only present when status is `pending`. |