Send updates

How updates reach phones

When a pass changes, Korti tells Apple and Google, and they fetch the new version. You don’t need to know which phones saved the pass. Changes to numbers people care about, like stamps and balances, show a notification on iPhone, such as “You now have 4 stamps”.

Every change returns the updated pass, and records an event (pass.updated, pass.redeemed or pass.voided) that you can get as a webhook.

Test passes

Updates you send from the dashboard (Uppfærslur) never go to passes a test key issued: they are not real customers’ cards, and the page counts them separately. To try an update on a test pass, change it with a test key: PATCH /v1/passes/{id} with values.custom.news puts the message on the back of the card and shows it on the lock screen, the same field the dashboard uses.

Add stamps

Stamp cards only. Adds one stamp, or count stamps, up to the card’s total. Adding to a full card returns 409 card_full.

curl -X POST https://korti.is/v1/passes/PASS_ID/stamps \
  -H "Authorization: Bearer $KORTI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "count": 1 }'

Redeem the reward

When rewardReady is true, give the reward and redeem it. On stamp cards this empties the card so the customer can start again. A completed round starting over is billed as one card, like issuing one, unless the pass is a trial or test pass. Redeeming a card that isn’t full returns 409 reward_not_ready. A pass can start a new round (or get a later validUntil) once every 10 minutes; asking again sooner returns 409 renewal_too_soon, so retry after the wait the message names.

A coupon can be redeemed once. The customer’s card then shows Used with the date and is greyed out in Apple Wallet and Google Wallet, so it can’t be shown again at another till. Undoing the redeem makes it valid again. The pass stays active: it isn’t a voided pass.

curl -X POST https://korti.is/v1/passes/PASS_ID/redeem \
  -H "Authorization: Bearer $KORTI_KEY"

Points and balances

Points cards take POST /v1/passes/{id}/points and gift cards take POST /v1/passes/{id}/balance. Both take a delta: positive adds, negative takes away. Points never go below 0. A balance that would go below 0 returns 422 insufficient_balance and nothing changes.

curl -X POST https://korti.is/v1/passes/PASS_ID/balance \
  -H "Authorization: Bearer $KORTI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "delta": -1500 }'

Change any value

PATCH /v1/passes/{id} sets values and customer details directly. Send only what changes. Values in custom are merged with the ones the pass already has. You can send a custom value nested, as { "custom": { "member_number": "M-0042" } }, or by the name GET /v1/cards lists, as { "custom.member_number": "M-0042" }.

curl -X PATCH https://korti.is/v1/passes/PASS_ID \
  -H "Authorization: Bearer $KORTI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "values": { "memberNumber": "004182" }, "customer": { "name": "Anna Jónsdóttir" } }'

Most updates are free. Two are billed as one card, like issuing one, unless the pass is a trial or test pass: moving values.validUntil later (or clearing it) on a pass that already had a date, and starting a new stamp round (redeeming a full card, or setting values.stamps to 0 on one).

Void a pass

Voiding stops a pass working, for example when a membership is cancelled or a gift card is refunded. Phones that saved it show it as no longer valid. It can’t be undone, and further changes return 409 pass_voided.

curl -X POST https://korti.is/v1/passes/PASS_ID/void \
  -H "Authorization: Bearer $KORTI_KEY"

A message to everyone

To tell everyone who has a card about something, such as new opening hours, use Updates in the dashboard. It sends one message to every phone holding the card.