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

Path parameters
NameTypeDescription
purchaseIdrequiredstring

Header parameters

Header parameters
NameTypeDescription
Idempotency-Keystring

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

Request body fields
NameTypeDescription
amountnumber

Credits to charge on a punch card. Defaults to 1. Ignored for memberships.

Minimum: 1

notestring

Note stored on the usage record

Maximum length: 500

usageDatestring<date-time>

When the session took place. Defaults to now.

Request examples

cURL
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
}'
JavaScript (fetch)
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

Example body (application/json)
{
  "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)
Response fields
NameTypeDescription
dataobject
data.idstring
data.coachIdstring
data.traineeIdstring
data.productIdstring
data.purchaseDatestring<date-time>
data.expirationDatestring<date-time>
data.purchaseAmountnumber
data.currencystring

Allowed values: ILS USD EUR GBP

data.statusstring

Allowed values: ACTIVE EXPIRED CANCELLED PENDING WAITING_FOR_PAYMENT

data.initialCreditsnumber
data.remainingCreditsnumber
data.membershipStartDatestring<date-time>
data.membershipEndDatestring<date-time>
data.currentPeriodUsagesnumber
data.periodResetDatestring<date-time>
data.createdAtstring<date-time>
data.updatedAtstring<date-time>

Error responses

  • 400 Bad Request
  • 401 Unauthorized
  • 403 Forbidden
  • 404 Not Found
  • 409 Conflict
  • 429 Too Many Requests
  • 500 Internal Server Error

These statuses share the same response body.

Example body (application/json)
{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "fix": "<string>",
    "details": {},
    "retryAfterMs": 123
  }
}
Error fields (6)
Error fields
NameTypeDescription
errorobject
error.codestring
error.messagestring
error.fixstring | null
error.detailsobject | null
error.retryAfterMsnumber | null

This page is also available as Markdown. Browse it in the interactive explorer or download the OpenAPI spec.