# Redeem a treat

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

Source: https://tamr.link/docs/api/redeem-treat

`POST https://tamr.link/api/v1/sdk/treats/{treatId}/redeem`

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](https://tamr.link/docs/guides/treats).

## 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:

```bash
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"
}'
```

Node:

```js
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);
```

Python:

```python
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

```json
{
  "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](https://tamr.link/docs/errors).

| `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. |
