Redeem a treat

Redeem a treat on the house once your checkout has placed the order that priced it at zero.

POST/api/v1/sdk/treats/{treatId}/redeemServer API · secret key

A cart line can carry a treat on the house (treat.treatId): your checkout prices that line at zero, and once the order is placed your backend redeems it here, with the same key that sends your orders. Sending the same order again gets the same answer, so retry freely. When it can't be redeemed, charge the line as usual. See Treats on the house.

Authentication

Server API. Send a secret API key with the Orders (SDK) permission (orders:sdk) as Authorization: Bearer <key>. Secret keys are made in Settings > API keys by an owner or admin. Keep them on your server: no browser can call this route.

Path parameters

NameTypeRequiredDescription
treatIdstringYes1 to 200 characters.

Request body

FieldTypeRequiredDescription
externalUserIdstringYes1 to 200 characters.
externalOrderIdstringYes1 to 200 characters.

Response

FieldTypeDescription
treatIdstring1 to 200 characters.
dishIdstring or null1 to 200 characters.
externalOrderIdstring1 to 200 characters.
redeemedAtstring (date-time)

Example

curl https://tamr.link/api/v1/sdk/treats/trt_9fK2mQ7xLp4vR8sTn1Yc3Wb6/redeem \
  -H "Authorization: Bearer $TAMR_SECRET_KEY" \
  -H "content-type: application/json" \
  -d '{
  "externalUserId": "user-88213",
  "externalOrderId": "ord_55120"
}'

Example response

{
  "treatId": "trt_9fK2mQ7xLp4vR8sTn1Yc3Wb6",
  "dishId": "dish_knafeh",
  "externalOrderId": "ord_55120",
  "redeemedAt": "2026-11-02T20:05:00.000Z"
}

Errors

Every error has the same body; switch on data.code. See Errors and rate limits.

data.codeStatusWhat to do
other401No secret key, or one Tamr doesn't accept: wrong, revoked, or made by someone who is no longer an owner or admin.
other403The key doesn't have the orders:sdk permission.
invalid_request400A field doesn't match the spec. The message says which.
rate_limited429Wait retryAfter seconds (also in the Retry-After header), then try again.
not_found404Not this diner's, or doesn't exist. The two read the same on purpose.
treat_refused409A treat can't be redeemed. treatRefusal says why: expired, withdrawn or already_redeemed. Charge the line as usual.
sdk_disabled403The SDK isn't switched on for this restaurant. Ask Tamr.