Redeem a treat
Redeem a treat on the house once your checkout has placed the order that priced it at zero.
/api/v1/sdk/treats/{treatId}/redeemServer API · secret keyA 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
| Name | Type | Required | Description |
|---|---|---|---|
treatId | string | Yes | 1 to 200 characters. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
externalUserId | string | Yes | 1 to 200 characters. |
externalOrderId | string | Yes | 1 to 200 characters. |
Response
| Field | Type | Description |
|---|---|---|
treatId | string | 1 to 200 characters. |
dishId | string or null | 1 to 200 characters. |
externalOrderId | string | 1 to 200 characters. |
redeemedAt | string (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"
}'import { createServerClient } from "@tamr/api/server";
const tamr = createServerClient({ secretKey: process.env.TAMR_SECRET_KEY });
const result = await tamr.sdkTreatRedeem("trt_9fK2mQ7xLp4vR8sTn1Yc3Wb6", {
externalUserId: "user-88213",
externalOrderId: "ord_55120",
});
console.log(result);import os
import requests
API = "https://tamr.link/api/v1"
headers = {"Authorization": f"Bearer {os.environ['TAMR_SECRET_KEY']}"}
treat_id = "trt_9fK2mQ7xLp4vR8sTn1Yc3Wb6"
response = requests.post(
f"{API}/sdk/treats/{treat_id}/redeem",
headers=headers,
json={
"externalUserId": "user-88213",
"externalOrderId": "ord_55120",
},
timeout=30,
)
response.raise_for_status()
print(response.json())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.code | Status | What to do |
|---|---|---|
other | 401 | No secret key, or one Tamr doesn't accept: wrong, revoked, or made by someone who is no longer an owner or admin. |
other | 403 | The key doesn't have the orders:sdk permission. |
invalid_request | 400 | A field doesn't match the spec. The message says which. |
rate_limited | 429 | Wait retryAfter seconds (also in the Retry-After header), then try again. |
not_found | 404 | Not this diner's, or doesn't exist. The two read the same on purpose. |
treat_refused | 409 | A treat can't be redeemed. treatRefusal says why: expired, withdrawn or already_redeemed. Charge the line as usual. |
sdk_disabled | 403 | The SDK isn't switched on for this restaurant. Ask Tamr. |