One-time order
A one-time order is a single, non-recurring purchase. It is a separate resource from subscriptions and uses its own endpoint — a sub-path under subscriptions — but internally PaymentsAI models it on the same machinery, which is why it appears under the subscriptions/one-time-orders path.
Difference from a subscription
| One-time order | Subscription | |
|---|---|---|
| Endpoint | POST /subscriptions/one-time-orders | POST /subscriptions |
Plan requires recurringInterval | No (plan is one-time only) | Yes |
| Renewal | None | Yes, on the recurringInterval cadence |
| Trial | Not supported | Optional |
| Pause / resume | Not supported | Supported |
| Cancel / reactivate | Not supported | Supported |
| First payment on inactive instrument | Hosted form (same as subscription) | Hosted form |
The two endpoints are not interchangeable. Calling POST /subscriptions with a plan that lacks a recurringInterval, or POST /subscriptions/one-time-orders with a recurring plan, is not supported.
Available operations
| Method | Path |
|---|---|
POST | /.../subscriptions/one-time-orders — create the order |
PUT | /.../subscriptions/one-time-orders/{subscriptionId} — upsert |
GET | List and read individual orders via the same path family |
A pending order (one that has not yet been paid) can be deleted; once paid, it is final.
Example — create
curl -i -X POST \
"https://staging-api.payments.ai/v1/public-api/organizations/${ORGANIZATION_ID}/subscriptions/one-time-orders" \
-H 'Content-Type: application/json' \
-H "Authorization: ApiKey ${API_KEY}" \
-d '{
"customerId": "cus_xxx",
"items": [{ "plan": { "id": "plan_one_time" } }]
}'
If the customer's payment instrument is inactive, the response carries the same recentInvoicePaymentFormUrl pattern as a subscription — the customer completes the payment on the hosted form. See Hosted payment form and Create a subscription for the equivalent flow.