# cart.proposed webhook

> The cart.proposed webhook: the AI waiter proposed lines to your app's cart, with Tamr's ids and yours, quantities and prices.

Source: https://tamr.link/docs/webhooks/cart-proposed

When orders go to your app's cart, this is sent when the waiter proposes lines to it, whatever your app then answered: your cart is the record of what landed. One per proposal (`proposalId`). Each line carries Tamr's ids always, yours when the restaurant mapped them, the quantity and price, and a set's picks. Never the dish's words or the diner's note.

A treat on the house carries `treat`: price that line at zero and [redeem it](https://tamr.link/docs/api/redeem-treat) once the order is placed.

## The `data` object

| Field | Type | Description |
| --- | --- | --- |
| `conversationId` | string | 1 to 200 characters. |
| `externalUserId` | string or null | 1 to 200 characters. |
| `proposalId` | string | 1 to 200 characters. |
| `lines` | array of object | 1 to 50 items. |
| `lines[].lineId` | string | 1 to 200 characters. |
| `lines[].dishId` | string | 1 to 200 characters. |
| `lines[].variantId` | string or null | 1 to 200 characters. |
| `lines[].optionIds` | array of string | At most 20 items. 1 to 200 characters. |
| `lines[].externalId` | string or null | 1 to 200 characters. |
| `lines[].variantExternalId` | string or null | 1 to 200 characters. |
| `lines[].optionExternalIds` | array of string or null | At most 20 items. |
| `lines[].quantity` | integer | 1 to 99. |
| `lines[].unitPrice` | string | An amount in minor units, as a string. |
| `lines[].currency` | string | A three-letter currency code (ISO 4217). |
| `lines[].picks` | array of object | May be absent. At most 120 items. |
| `lines[].picks[].pickId` | string | 1 to 200 characters. |
| `lines[].picks[].dishId` | string | 1 to 200 characters. |
| `lines[].picks[].variantId` | string or null | 1 to 200 characters. |
| `lines[].picks[].externalId` | string or null | 1 to 200 characters. |
| `lines[].picks[].variantExternalId` | string or null | 1 to 200 characters. |
| `lines[].picks[].pieces` | integer | 1 to 99. |
| `lines[].picks[].count` | integer | 1 to 20. |
| `lines[].treat` | object | May be absent. |
| `lines[].treat.treatId` | string | The treat's single-use id. 1 to 200 characters. |
| `lines[].treat.expiresAt` | string (date-time) | After this the treat can't be redeemed. |

## Examples

cart.proposed:

```json
{
  "type": "cart.proposed",
  "timestamp": "2026-11-02T19:20:00.000Z",
  "livemode": true,
  "data": {
    "conversationId": "conv_0001",
    "externalUserId": "user-88213",
    "proposalId": "prop_7f3a9c2e",
    "lines": [
      {
        "lineId": "line_0001",
        "dishId": "dish_kafta",
        "variantId": null,
        "optionIds": [
          "opt_garlic"
        ],
        "externalId": "SKU-1042",
        "variantExternalId": null,
        "optionExternalIds": [
          null
        ],
        "quantity": 2,
        "unitPrice": "145000",
        "currency": "LBP"
      },
      {
        "lineId": "line_0002",
        "dishId": "dish_roll_set",
        "variantId": null,
        "optionIds": [],
        "externalId": null,
        "variantExternalId": null,
        "optionExternalIds": [],
        "quantity": 1,
        "unitPrice": "2400",
        "currency": "USD",
        "picks": [
          {
            "pickId": "pick_tuna",
            "dishId": "dish_tuna_roll",
            "variantId": "var_8pc",
            "externalId": "SKU-77",
            "variantExternalId": "SKU-77-8",
            "pieces": 8,
            "count": 2
          }
        ]
      }
    ]
  }
}
```

A proposed line that is a treat on the house (#455).

cart.proposed:

```json
{
  "type": "cart.proposed",
  "timestamp": "2026-11-02T19:20:00.000Z",
  "livemode": true,
  "data": {
    "conversationId": "conv_0001",
    "externalUserId": "user-88213",
    "proposalId": "prop_treat_01",
    "lines": [
      {
        "lineId": "line_treat_01",
        "dishId": "dish_kafta",
        "variantId": null,
        "optionIds": [
          "opt_garlic"
        ],
        "externalId": "SKU-1042",
        "variantExternalId": null,
        "optionExternalIds": [
          null
        ],
        "quantity": 2,
        "unitPrice": "145000",
        "currency": "LBP",
        "treat": {
          "treatId": "trt_9fK2mQ7xLp4vR8sTn1Yc3Wb6",
          "expiresAt": "2026-11-03T19:20:00.000Z"
        }
      }
    ]
  }
}
```

## A test event

What **Send a test event** in the dashboard sends: `livemode: false`, and every id starting `test_`.

cart.proposed, test:

```json
{
  "type": "cart.proposed",
  "timestamp": "2026-11-16T12:00:00.000Z",
  "livemode": false,
  "data": {
    "conversationId": "test_conversation",
    "externalUserId": "test_user",
    "proposalId": "test_proposal",
    "lines": [
      {
        "lineId": "test_line",
        "dishId": "test_dish",
        "variantId": null,
        "optionIds": [],
        "externalId": null,
        "variantExternalId": null,
        "optionExternalIds": [],
        "quantity": 1,
        "unitPrice": "1000",
        "currency": "USD"
      }
    ]
  }
}
```
