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.

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 once the order is placed.

The data object

FieldTypeDescription
conversationIdstring1 to 200 characters.
externalUserIdstring or null1 to 200 characters.
proposalIdstring1 to 200 characters.
linesarray of object1 to 50 items.
lines[].lineIdstring1 to 200 characters.
lines[].dishIdstring1 to 200 characters.
lines[].variantIdstring or null1 to 200 characters.
lines[].optionIdsarray of stringAt most 20 items. 1 to 200 characters.
lines[].externalIdstring or null1 to 200 characters.
lines[].variantExternalIdstring or null1 to 200 characters.
lines[].optionExternalIdsarray of string or nullAt most 20 items.
lines[].quantityinteger1 to 99.
lines[].unitPricestringAn amount in minor units, as a string.
lines[].currencystringA three-letter currency code (ISO 4217).
lines[].picksarray of objectMay be absent. At most 120 items.
lines[].picks[].pickIdstring1 to 200 characters.
lines[].picks[].dishIdstring1 to 200 characters.
lines[].picks[].variantIdstring or null1 to 200 characters.
lines[].picks[].externalIdstring or null1 to 200 characters.
lines[].picks[].variantExternalIdstring or null1 to 200 characters.
lines[].picks[].piecesinteger1 to 99.
lines[].picks[].countinteger1 to 20.
lines[].treatobjectMay be absent.
lines[].treat.treatIdstringThe treat's single-use id. 1 to 200 characters.
lines[].treat.expiresAtstring (date-time)After this the treat can't be redeemed.

Examples

cart.proposed
{
  "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
{
  "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
{
  "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"
      }
    ]
  }
}