Record one use of an ACTIVE purchase
POST/api/public/purchases/{purchaseId}/use
Record one use of an ACTIVE purchase: a punch card is charged amount credits (default 1), a membership logs one visit against its period allowance. Fails with 400 when not enough credits remain or the membership allowance is used up.
Authentication
Requires an API key, sent as Authorization: Bearer cp_live_....
API keys carry scopes. Get the catalog of scopes and webhook events lists every scope.
Path parameters
| Name | Type | Description |
|---|---|---|
purchaseIdrequired | string |
Header parameters
| Name | Type | Description |
|---|---|---|
Idempotency-Key | string | Optional. Send a unique key (e.g. a UUID) to make this POST safe to retry. The same key within 24h returns the original result instead of creating a duplicate. |
Request body
application/json, required
| Name | Type | Description |
|---|---|---|
amount | number | Credits to charge on a punch card. Defaults to 1. Ignored for memberships. |
note | string | Note stored on the usage record |
usageDate | string<date-time> | When the session took place. Defaults to now. |
Request examples
curl --request POST \
--url 'https://api.coach-platform.com/api/public/purchases/<purchaseId>/use' \
--header 'Authorization: Bearer cp_live_...' \
--header 'Content-Type: application/json' \
--data '{
"amount": 123
}'const response = await fetch('https://api.coach-platform.com/api/public/purchases/<purchaseId>/use', {
method: 'POST',
headers: {
Authorization: 'Bearer cp_live_...',
'Content-Type': 'application/json',
},
body: JSON.stringify({
"amount": 123
}),
});
const data = await response.json();Responses
200 OK
Successful response
{
"data": {
"id": "<string>",
"coachId": "<string>",
"traineeId": "<string>",
"productId": "<string>",
"purchaseDate": "<date-time>",
"expirationDate": "<date-time>",
"purchaseAmount": 123,
"currency": "ILS",
"status": "ACTIVE",
"initialCredits": 123,
"remainingCredits": 123,
"membershipStartDate": "<date-time>",
"membershipEndDate": "<date-time>",
"currentPeriodUsages": 123,
"periodResetDate": "<date-time>",
"createdAt": "<date-time>",
"updatedAt": "<date-time>"
}
}Response fields (18)
| Name | Type | Description |
|---|---|---|
data | object | |
data.id | string | |
data.coachId | string | |
data.traineeId | string | |
data.productId | string | |
data.purchaseDate | string<date-time> | |
data.expirationDate | string<date-time> | |
data.purchaseAmount | number | |
data.currency | string | |
data.status | string | |
data.initialCredits | number | |
data.remainingCredits | number | |
data.membershipStartDate | string<date-time> | |
data.membershipEndDate | string<date-time> | |
data.currentPeriodUsages | number | |
data.periodResetDate | string<date-time> | |
data.createdAt | string<date-time> | |
data.updatedAt | string<date-time> |
Error responses
400Bad Request401Unauthorized403Forbidden404Not Found409Conflict429Too Many Requests500Internal Server Error
These statuses share the same response body.
{
"error": {
"code": "<string>",
"message": "<string>",
"fix": "<string>",
"details": {},
"retryAfterMs": 123
}
}Error fields (6)
| Name | Type | Description |
|---|---|---|
error | object | |
error.code | string | |
error.message | string | |
error.fix | string | null | |
error.details | object | null | |
error.retryAfterMs | number | null |
More Purchases endpoints
This page is also available as Markdown. Browse it in the interactive explorer or download the OpenAPI spec.