Issue Gift Card
POST/api/gift-cards
Issue (create + fund) a new gift card. The initial amount is written as an activation ledger entry and becomes the card's opening balance.
This endpoint currently requires session authentication; Personal Access Token scope support is in progress.
Authentication: Requires Bearer token.
Permission: pos.manage.
Request body fields:
amount(numeric, required, > 0) — the amount to fund the card with. Error message when not > 0: "The gift card amount must be greater than zero."code(string, nullable, max 255, unique ingift_cards.code) — explicit card code; auto-generated (unique) when omitted. Error message on collision: "That gift card code is already in use."security_code(string, nullable, max 255) — optional PIN / security code.is_digital(boolean, nullable) — whether the card is digital (emailed) vs a physical card. Defaults to false.customer_id(integer, nullable, must exist incustomers) — owning customer.recipient_name(string, nullable, max 255) — gift recipient's name.recipient_email(email, nullable, max 255) — gift recipient's email.expires_at(date, nullable) — expiry date.notes(string, nullable, max 2000) — internal note.
Returns 201 with { data: <gift card>, balance: <float>, message: "Gift card issued." }.
Request
Responses
- 201
- 401
- 403
- 422
- 429
Created
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Unprocessable Entity
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.