Checkout reservations

Hold a benefit during checkout without spending it

Scopeloyalty:write

Requires loyalty:write and an Idempotency-Key. Holds part of one customer's balance while a payment is pending: a Stamp program holds its reward's stamps, a Points (or Points and tiers) program the named reward's points, a Subscription program one included use, a Cashback or Prepaid program amount of its balance (minor units, currency the program's, never converted). The balance does not move; what the customer can spend is the balance less active holds (available), and the counter, actions and a void all leave active holds funded (409 BENEFIT_RESERVED). Concurrent holds queue on the membership: they can never over-commit it (409 INSUFFICIENT_AVAILABLE when other holds are what is in the way, otherwise the card's own refusal code). reference is your checkout or order id and makes the hold happen once under any key; the same reference for something else is 409 SOURCE_EVENT_CONFLICT. The hold lasts expiresInSeconds (60 to 86,400), default 15 minutes (DEVELOPER_RESERVATION_TTL_SECONDS). A Tiered program has nothing to hold (422 UNSUPPORTED_ACTION).

Send an Idempotency-Key header. Safe to retry.

Path

iduuidRequired

Body

externalCustomerIdstringRequired

referencestringRequired

Your checkout or order id; makes the hold happen once.

branchIduuid

rewardIdstring

Points programs.

rewardNamestring

Points programs, by exact name.

amountinteger

Cashback and Prepaid, minor units of the program's currency.

currencyenum

ISO 4217. Fixed per program once money has moved. Minor-unit digits are 0 for JPY, KRW and VND, 3 for BHD, JOD, KWD and OMR, else 2. One of AED, BDT, BHD, EUR, GBP, INR, JOD, JPY, KRW, KWD, MYR, OMR, SGD, USD, VND.

expiresInSecondsinteger

Default 900 (15 minutes). 60 to 86400.

Returns 201

reservationIdstringRequired

stateenumRequired

Read from the clock. One of active, confirmed, released, expired.

amountintegerRequired

Balance units held.

balanceintegerRequired

The membership's balance now; a hold never moves it.

reservedintegerRequired

Held by every active hold on the membership now.

availableintegerRequired

balance less reserved, never below zero.

balanceAfterinteger or nullRequired

currencystring or nullRequired

customerIdstring or nullRequired

Null for a gift card with no customer.

externalCustomerIdstringRequired

giftCardIdstring or nullRequired

Set when the hold is on a gift card; then programId and membershipId are null.

membershipIdstring or nullRequired

programIdstring or nullRequired

referencestringRequired

rewardNamestring or nullRequired

transactionIdstring or nullRequired

The ledger row of the confirmed spend (the counter's pass event for a gift card).

createdAtstringRequired

expiresAtstringRequired

decidedAtstring or nullRequired

duplicatebooleanRequired

Errors

• 409BENEFIT_RESERVEDpart of the balance is held by a checkout reservation, so a counter or API spend would leave a hold unfunded. Nothing changed; confirm or release the hold, or let it expire.
• 409INSUFFICIENT_AVAILABLEnot enough is available (the balance less active holds) to hold or spend this. Nothing changed.
• 409SOURCE_EVENT_CONFLICTthis source event id was already applied with different content (another customer, program, action or amount). Nothing changed.
• 422UNSUPPORTED_ACTIONthe action is not one a service may take (top-up, spend, set or adjust a balance, void) or the program's card type does not take earning and redeeming from the API yet. Nothing changed.

Hold part of a gift card's balance during checkout

Scopepasses:write

Requires passes:write and an Idempotency-Key; confirming or releasing it later needs loyalty:write (and passes:write), reading it loyalty:read (and passes:read). Gift card holds need a key without program or branch limits. Holds amount (the card's currency minor unit, currency must match, never converted) without moving the balance: GiftCard.available is balance less reserved, and the counter, POST /gift-cards/{id}/actions spends and the counter's void of a top-up all leave active holds funded (409 BENEFIT_RESERVED). Concurrent holds queue on the card's row lock (the one the counter's spend takes) and can never over-commit it: 409 INSUFFICIENT_BALANCE when the card itself is short, 409 INSUFFICIENT_AVAILABLE when other holds are in the way. The card's PIN is asked for at confirm, not here. reference makes the hold happen once under any key; the same reference for something else is 409 SOURCE_EVENT_CONFLICT. Same expiry, confirm, release and recovery rules as a program hold. Only gift cards are reservable among the issued passes: offers, generic passes, event tickets, boarding passes and transit passes answer POST /{family}/{id}/reservations with 422 UNSUPPORTED_ACTION and write nothing.

Send an Idempotency-Key header. Safe to retry.

Path

iduuidRequired

Body

amountintegerRequired

The part of the balance to hold, in the currency's minor unit.

currencystringRequired

The card's currency (ISO 4217).

referencestringRequired

Your checkout or order id.

branchIduuid

The branch the spend will happen at. Omitted: the business's only open branch (400 BRANCH_REQUIRED with several).

expiresInSecondsinteger

60 to 86400.

Returns 201

reservationIdstringRequired

stateenumRequired

Read from the clock. One of active, confirmed, released, expired.

amountintegerRequired

Balance units held.

balanceintegerRequired

The membership's balance now; a hold never moves it.

reservedintegerRequired

Held by every active hold on the membership now.

availableintegerRequired

balance less reserved, never below zero.

balanceAfterinteger or nullRequired

currencystring or nullRequired

customerIdstring or nullRequired

Null for a gift card with no customer.

externalCustomerIdstringRequired

giftCardIdstring or nullRequired

Set when the hold is on a gift card; then programId and membershipId are null.

membershipIdstring or nullRequired

programIdstring or nullRequired

referencestringRequired

rewardNamestring or nullRequired

transactionIdstring or nullRequired

The ledger row of the confirmed spend (the counter's pass event for a gift card).

createdAtstringRequired

expiresAtstringRequired

decidedAtstring or nullRequired

duplicatebooleanRequired

Errors

• 409BENEFIT_RESERVEDpart of the balance is held by a checkout reservation, so a counter or API spend would leave a hold unfunded. Nothing changed; confirm or release the hold, or let it expire.
• 409INSUFFICIENT_BALANCE
• 409INSUFFICIENT_AVAILABLEnot enough is available (the balance less active holds) to hold or spend this. Nothing changed.
• 409SOURCE_EVENT_CONFLICTthis source event id was already applied with different content (another customer, program, action or amount). Nothing changed.
• 422UNSUPPORTED_ACTIONthe action is not one a service may take (top-up, spend, set or adjust a balance, void) or the program's card type does not take earning and redeeming from the API yet. Nothing changed.

Not supported - an offer cannot be reserved

Scopepasses:write

Requires passes:write. Always 422 UNSUPPORTED_ACTION (404 for an unknown id). The same route exists, with the same answer, under /generic-passes/{id}, /event-tickets/{id}, /boarding-passes/{id} and /transit-passes/{id}: those passes are used once, checked in or ridden, not drawn down like a balance, so there is nothing safe to hold. Nothing is written.

Path

iduuidRequired

Errors

• 422UNSUPPORTED_ACTIONthe action is not one a service may take (top-up, spend, set or adjust a balance, void) or the program's card type does not take earning and redeeming from the API yet. Nothing changed.

Not supported - a generic pass cannot be reserved

Scopepasses:write

Requires passes:write. Always 422 UNSUPPORTED_ACTION (404 for an unknown id). The same route exists, with the same answer, under /generic-passes/{id}, /event-tickets/{id}, /boarding-passes/{id} and /transit-passes/{id}: those passes are used once, checked in or ridden, not drawn down like a balance, so there is nothing safe to hold. Nothing is written.

Path

iduuidRequired

Errors

• 422UNSUPPORTED_ACTIONthe action is not one a service may take (top-up, spend, set or adjust a balance, void) or the program's card type does not take earning and redeeming from the API yet. Nothing changed.

Not supported - an event ticket cannot be reserved

Scopepasses:write

Requires passes:write. Always 422 UNSUPPORTED_ACTION (404 for an unknown id). The same route exists, with the same answer, under /generic-passes/{id}, /event-tickets/{id}, /boarding-passes/{id} and /transit-passes/{id}: those passes are used once, checked in or ridden, not drawn down like a balance, so there is nothing safe to hold. Nothing is written.

Path

iduuidRequired

Errors

• 422UNSUPPORTED_ACTIONthe action is not one a service may take (top-up, spend, set or adjust a balance, void) or the program's card type does not take earning and redeeming from the API yet. Nothing changed.

Not supported - a boarding pass cannot be reserved

Scopepasses:write

Requires passes:write. Always 422 UNSUPPORTED_ACTION (404 for an unknown id). The same route exists, with the same answer, under /generic-passes/{id}, /event-tickets/{id}, /boarding-passes/{id} and /transit-passes/{id}: those passes are used once, checked in or ridden, not drawn down like a balance, so there is nothing safe to hold. Nothing is written.

Path

iduuidRequired

Errors

• 422UNSUPPORTED_ACTIONthe action is not one a service may take (top-up, spend, set or adjust a balance, void) or the program's card type does not take earning and redeeming from the API yet. Nothing changed.

Not supported - a transit pass cannot be reserved

Scopepasses:write

Requires passes:write. Always 422 UNSUPPORTED_ACTION (404 for an unknown id). The same route exists, with the same answer, under /generic-passes/{id}, /event-tickets/{id}, /boarding-passes/{id} and /transit-passes/{id}: those passes are used once, checked in or ridden, not drawn down like a balance, so there is nothing safe to hold. Nothing is written.

Path

iduuidRequired

Errors

• 422UNSUPPORTED_ACTIONthe action is not one a service may take (top-up, spend, set or adjust a balance, void) or the program's card type does not take earning and redeeming from the API yet. Nothing changed.

List this application's reservations, newest first

Scopeloyalty:read

Requires loyalty:read. state follows the clock, so a hold past its time reads expired before the worker writes it down. At most 100 per page.

Query

externalCustomerIdstring

programIduuid

giftCardIduuid

Only the holds on this gift card. Gift card holds are listed only to a key with passes:read and no program or branch limits.

stateenum

One of active, confirmed, released, expired.

limitinteger

1 to 100.

offsetinteger

Returns 200

hasMorebooleanRequired

itemsobject[]Required

items[].reservationIdstringRequired

items[].stateenumRequired

Read from the clock. One of active, confirmed, released, expired.

items[].amountintegerRequired

Balance units held.

items[].balanceintegerRequired

The membership's balance now; a hold never moves it.

items[].reservedintegerRequired

Held by every active hold on the membership now.

items[].availableintegerRequired

balance less reserved, never below zero.

items[].balanceAfterinteger or nullRequired

items[].currencystring or nullRequired

items[].customerIdstring or nullRequired

Null for a gift card with no customer.

items[].externalCustomerIdstringRequired

items[].giftCardIdstring or nullRequired

Set when the hold is on a gift card; then programId and membershipId are null.

items[].membershipIdstring or nullRequired

items[].programIdstring or nullRequired

items[].referencestringRequired

items[].rewardNamestring or nullRequired

items[].transactionIdstring or nullRequired

The ledger row of the confirmed spend (the counter's pass event for a gift card).

items[].createdAtstringRequired

items[].expiresAtstringRequired

items[].decidedAtstring or nullRequired

items[].duplicatebooleanRequired

limitintegerRequired

offsetintegerRequired

Read one reservation

Scopeloyalty:read

Requires loyalty:read. A reservation belongs to the application that made it; another application or business reads it as 404.

Path

iduuidRequired

Returns 200

reservationIdstringRequired

stateenumRequired

Read from the clock. One of active, confirmed, released, expired.

amountintegerRequired

Balance units held.

balanceintegerRequired

The membership's balance now; a hold never moves it.

reservedintegerRequired

Held by every active hold on the membership now.

availableintegerRequired

balance less reserved, never below zero.

balanceAfterinteger or nullRequired

currencystring or nullRequired

customerIdstring or nullRequired

Null for a gift card with no customer.

externalCustomerIdstringRequired

giftCardIdstring or nullRequired

Set when the hold is on a gift card; then programId and membershipId are null.

membershipIdstring or nullRequired

programIdstring or nullRequired

referencestringRequired

rewardNamestring or nullRequired

transactionIdstring or nullRequired

The ledger row of the confirmed spend (the counter's pass event for a gift card).

createdAtstringRequired

expiresAtstringRequired

decidedAtstring or nullRequired

duplicatebooleanRequired

Spend a held benefit after the checkout succeeded

Scopeloyalty:write

Requires loyalty:write and an Idempotency-Key. Runs the ordinary redeem or spend and marks the reservation confirmed in one transaction, so the ledger row (transactionId, the one the merchant app shows) and the state commit together. A repeat, under any key, answers the same confirmed reservation (duplicate: true) and spends once; many at once spend once. A reservation that ran out is 409 RESERVATION_EXPIRED and nothing was spent: reconcile the checkout (refund the payment, or reserve again). A released one is 409 RESERVATION_NOT_ACTIVE. This is not one transaction with your payment gateway: Punchd never claims it is. A gift card hold is spent through the counter's own planner, PIN guard and ledger: send the card's pin in the optional body when it has one (403 PIN_REQUIRED / WRONG_PIN leave the hold active); the PIN is compared on the server and is never stored, echoed or part of the retry fingerprint.

Send an Idempotency-Key header. Safe to retry.

Path

iduuidRequired

Body

pinstring

Gift card holds only.

Returns 200

reservationIdstringRequired

stateenumRequired

Read from the clock. One of active, confirmed, released, expired.

amountintegerRequired

Balance units held.

balanceintegerRequired

The membership's balance now; a hold never moves it.

reservedintegerRequired

Held by every active hold on the membership now.

availableintegerRequired

balance less reserved, never below zero.

balanceAfterinteger or nullRequired

currencystring or nullRequired

customerIdstring or nullRequired

Null for a gift card with no customer.

externalCustomerIdstringRequired

giftCardIdstring or nullRequired

Set when the hold is on a gift card; then programId and membershipId are null.

membershipIdstring or nullRequired

programIdstring or nullRequired

referencestringRequired

rewardNamestring or nullRequired

transactionIdstring or nullRequired

The ledger row of the confirmed spend (the counter's pass event for a gift card).

createdAtstringRequired

expiresAtstringRequired

decidedAtstring or nullRequired

duplicatebooleanRequired

Errors

• 409RESERVATION_EXPIREDthe reservation ran out before it was confirmed. Nothing was spent: reconcile the checkout (refund the payment, or reserve again).
• 409RESERVATION_NOT_ACTIVEthe reservation is already in another terminal state (confirmed, or released) than this call needs.
• 403PIN_REQUIRED

Free a held benefit after a failed or abandoned checkout

Scopeloyalty:write

Requires loyalty:write and an Idempotency-Key. Frees the hold at once. Safe to repeat (a released or expired reservation answers its state, 200). A confirmed one is 409 RESERVATION_NOT_ACTIVE: the benefit was spent. Confirm, release and expiry are mutually exclusive terminal transitions of one row: whichever commits first wins.

Send an Idempotency-Key header. Safe to retry.

Path

iduuidRequired

Returns 200

reservationIdstringRequired

stateenumRequired

Read from the clock. One of active, confirmed, released, expired.

amountintegerRequired

Balance units held.

balanceintegerRequired

The membership's balance now; a hold never moves it.

reservedintegerRequired

Held by every active hold on the membership now.

availableintegerRequired

balance less reserved, never below zero.

balanceAfterinteger or nullRequired

currencystring or nullRequired

customerIdstring or nullRequired

Null for a gift card with no customer.

externalCustomerIdstringRequired

giftCardIdstring or nullRequired

Set when the hold is on a gift card; then programId and membershipId are null.

membershipIdstring or nullRequired

programIdstring or nullRequired

referencestringRequired

rewardNamestring or nullRequired

transactionIdstring or nullRequired

The ledger row of the confirmed spend (the counter's pass event for a gift card).

createdAtstringRequired

expiresAtstringRequired

decidedAtstring or nullRequired

duplicatebooleanRequired

Errors

• 409RESERVATION_NOT_ACTIVEthe reservation is already in another terminal state (confirmed, or released) than this call needs.