Prices
Recurring amounts attached to products.
GET /v1/prices
List prices
Cursor-paginated (limit, starting_after).
- Authentication
- Merchant API key
- Effect
- Read-only.
Query parameters
| Name | Type | Required | Description |
|---|
limit | integer | no | Page size (1–100). · ≥ 1, ≤ 100, default 20 |
starting_after | string | no | Object ID; return objects after it (ascending ID order). · 26 chars |
product | string | no | Filter by product ID. · 26 chars |
active | boolean | no | Filter by true/false. |
Responses
| Status | Meaning | Body / error codes |
|---|
| 200 | Success. | object |
| 400 | Invalid filter. | invalid_query_param |
| 401 | Missing or invalid API key. | authentication_error |
| 429 | Rate limited; honor retry-after. | rate_limit_exceeded too_many_auth_failures |
| 500 | Server error. | api_error |
Example response
{
"object": "list",
"url": "string",
"has_more": false,
"data": [
{
"object": "price",
"id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
"merchant_id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
"product_id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
"active": false,
"amount": 1,
"currency": "RON",
"recurring": {
"interval": "day",
"interval_count": 1
},
"metadata": {},
"created_at": "2026-10-25T18:00:00.000Z"
}
]
}
POST /v1/prices
Create a price
Amount, currency and interval are immutable; create a new price and deactivate the old one to change them.
- Authentication
- Merchant API key
- Effect
- Creates a price.
Headers
| Name | Type | Required | Description |
|---|
Idempotency-Key | string | no | Makes retries safe: same key + body replays the stored response (idempotency-replayed: true); a different body returns 409 idempotency_key_in_use. · ≤ 96 chars |
Request body
| Field | Type | Required | Description |
|---|
product_id | string | yes | ULID · 26 chars |
amount | integer | yes | Minor units. · > 0 |
currency | "RON" | "EUR" | "USD" | yes | Currency. Case-insensitive on input, stored uppercase. |
recurring | object | yes | |
recurring.interval | "day" | "week" | "month" | "year" | yes | |
recurring.interval_count | integer | no | e.g. 3 + month = quarterly. · ≥ 1, default 1 |
active | boolean | no | default true |
metadata | object | no | Free-form key/value data. Each value ≤16 KiB of JSON, ≤8 nesting levels, ≤100 properties/elements. |
Example request
{
"product_id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
"amount": 1,
"currency": "RON",
"recurring": {
"interval": "day",
"interval_count": 1
},
"active": true,
"metadata": {}
}
Responses
| Status | Meaning | Body / error codes |
|---|
| 201 | Price created. | Price |
| 400 | Invalid body. | validation_failed invalid_json |
| 401 | Missing or invalid API key. | authentication_error |
| 404 | Not found, or not yours. | resource_missing |
| 429 | Rate limited; honor retry-after. | rate_limit_exceeded too_many_auth_failures |
| 500 | Server error. | api_error |
Example response
{
"object": "price",
"id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
"merchant_id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
"product_id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
"active": false,
"amount": 1,
"currency": "RON",
"recurring": {
"interval": "day",
"interval_count": 1
},
"metadata": {},
"created_at": "2026-10-25T18:00:00.000Z"
}
GET /v1/prices/:id
Retrieve a price
- Authentication
- Merchant API key
- Effect
- Read-only.
Path parameters
| Name | Type | Required | Description |
|---|
id | string | yes | Object ID (ULID). · 26 chars |
Responses
| Status | Meaning | Body / error codes |
|---|
| 200 | Success. | Price |
| 401 | Missing or invalid API key. | authentication_error |
| 404 | Not found, or not yours. | resource_missing |
| 429 | Rate limited; honor retry-after. | rate_limit_exceeded too_many_auth_failures |
| 500 | Server error. | api_error |
Example response
{
"object": "price",
"id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
"merchant_id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
"product_id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
"active": false,
"amount": 1,
"currency": "RON",
"recurring": {
"interval": "day",
"interval_count": 1
},
"metadata": {},
"created_at": "2026-10-25T18:00:00.000Z"
}
POST /v1/prices/:id
Update a price
Only active and metadata can change.
- Authentication
- Merchant API key
- Effect
- Updates
active/metadata.
Path parameters
| Name | Type | Required | Description |
|---|
id | string | yes | Object ID (ULID). · 26 chars |
Headers
| Name | Type | Required | Description |
|---|
Idempotency-Key | string | no | Makes retries safe: same key + body replays the stored response (idempotency-replayed: true); a different body returns 409 idempotency_key_in_use. · ≤ 96 chars |
Request body
| Field | Type | Required | Description |
|---|
active | boolean | no | |
metadata | object | no | Free-form key/value data. Each value ≤16 KiB of JSON, ≤8 nesting levels, ≤100 properties/elements. |
Example request
{
"active": false,
"metadata": {}
}
Responses
| Status | Meaning | Body / error codes |
|---|
| 200 | Success. | Price |
| 400 | Invalid body or no fields to update. | validation_failed invalid_json empty_update |
| 401 | Missing or invalid API key. | authentication_error |
| 404 | Not found, or not yours. | resource_missing |
| 429 | Rate limited; honor retry-after. | rate_limit_exceeded too_many_auth_failures |
| 500 | Server error. | api_error |
Example response
{
"object": "price",
"id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
"merchant_id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
"product_id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
"active": false,
"amount": 1,
"currency": "RON",
"recurring": {
"interval": "day",
"interval_count": 1
},
"metadata": {},
"created_at": "2026-10-25T18:00:00.000Z"
}