Preview a checkout

POST/v1/checkouts/preview

Tells you what the member could use on this cart and why everything else doesn't apply. It has no side effects: nothing is held or spent, so call it whenever the cart changes. Show only the applicable entries as tappable.

Permissions: Secret key with checkout:write, or a member token for its own member.

Guide

Checkout and orders

Request headers#

Idempotency-Keystring
Any string up to 255 characters; use a UUID v4. Kept 24 hours per key (or member) and endpoint. Same key and body replays the first response with Idempotent-Replayed: true.
Max Length 255

Request body#

The cart, plus:

member_idstring (uuid)
The member. Leave it out for a guest checkout with a code. With a member token it is always the token's member.
location_idstring (uuid)Required
From GET /v1/locations.
channelstringRequired
app or web.
One of app, web
fulfillmentstringRequired
pickup, delivery, curbside or dine_in. May grow.
One of pickup, delivery, curbside, dine_in
currencystringRequired
USD.
subtotal_centsintegerRequired
The sum of every line (unit price plus modifiers, times quantity), before discounts, tax and tip.
Min 0
itemsarray of CartItemRequired
The cart lines. See below.
Show attributesCartItem
- line_idstringRequired
  Your id for the line, unique within the cart.
- pos_item_idstring
  Square catalog item variation id.
- namestringRequired
- quantityintegerRequired
  Min 1
- unit_price_centsintegerRequired
  Integer cents.
  Min 0
- pos_category_idsarray of string
- modifiersarray of object
  Show attributesHide attributes
  - pos_modifier_idstring
  - namestring
  - price_centsinteger
    Integer cents.
    Min 0
codesarray of string
Promo codes the guest typed, shared or unique.
reward_idsarray of string (uuid)
Catalog rewards to check. Empty checks every catalog reward.
wallet_item_idsarray of string (uuid)
Wallet items to check. Empty checks every available item in the member's wallet.

Response fields#

Returns 200 with Preview

member_idstring (uuid)Nullable
null for a guest checkout.
points_balanceintegerNullable
The member's balance now.
points_to_earninteger
Points this cart earns as sent, before any discount. Here $12.50 at 10 Beans per dollar. If Maya uses the pastry, the order earns on $9.00 instead: 90 Beans.
applicablearray of PreviewEntry
Everything the member can use on this cart: catalog rewards they can afford, wallet items, valid codes.
Show attributesPreviewEntry
- typestring
  Also on not_applicable entries: reward (with reward_id and points_cost), wallet_item (with wallet_item_id) or code (with code). Send that id or code to POST /v1/redemptions. May grow.
  One of reward, wallet_item, code
- reward_idstring (uuid)
- wallet_item_idstring (uuid)
- codestring
- namestring
  Label to show. Also on not_applicable entries.
- points_costinteger
  For reward.
- discount_centsinteger
  The discount on this cart. Show this amount; don't recalculate it.
- affected_line_idsarray of string
  Cart lines the discount applies to. Empty for a discount on the whole subtotal.
- reasonReasonCode
  Show valuesHide values
  - below_minimum_subtotal
  - wrong_channel
  - wrong_location
  - wrong_fulfillment
  - outside_available_times
  - item_not_in_cart
  - tier_required
  - not_enough_points
  - per_member_limit_reached
  - budget_exhausted
  - not_started
  - expired
  - already_used
- messagestring
  Not-applicable entries only. Safe to show guests.
not_applicablearray of PreviewEntry
Catalog rewards, wallet items and codes that don't apply, each with a reason from the reason codes and a message you can show the guest as is.
Show attributesPreviewEntry
- typestring
  One of reward, wallet_item, code
- reward_idstring (uuid)
- wallet_item_idstring (uuid)
- codestring
- namestring
- points_costinteger
  For reward.
- discount_centsinteger
  Applicable entries only.
- affected_line_idsarray of string
  Applicable entries only.
- reasonReasonCode
  Show valuesHide values
  - below_minimum_subtotal
  - wrong_channel
  - wrong_location
  - wrong_fulfillment
  - outside_available_times
  - item_not_in_cart
  - tier_required
  - not_enough_points
  - per_member_limit_reached
  - budget_exhausted
  - not_started
  - expired
  - already_used
- messagestring
  Not-applicable entries only. Safe to show guests.
challenge_progressarray of object
Coming soon How this order would move the member's challenges. Always empty at launch.

POST/v1/checkouts/preview

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19curl -X POST $UNPLUG_API/checkouts/preview \
  -H "Authorization: Bearer $MEMBER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "member_id": "3f2b8c1e-6d0a-4e7b-9f3c-2a1d5e8b7c40",
    "location_id": "8d4e2a17-3b9c-4f5e-a6d1-7c0b9e2f4a53",
    "channel": "app",
    "fulfillment": "pickup",
    "currency": "USD",
    "subtotal_cents": 1250,
    "items": [
      { "line_id": "1", "pos_item_id": "HV4MZ2TQ7LW3KXRB5P8NJ6DC", "name": "Oat latte", "quantity": 1, "unit_price_cents": 575, "pos_category_ids": ["C4RZ8NQ2MXK7WTP3LHB6V5JD"], "modifiers": [] },
      { "line_id": "2", "pos_item_id": "3NZQ7XKJ2Y5PLVKCW6RQ4G2T", "name": "Drip coffee", "quantity": 1, "unit_price_cents": 325, "pos_category_ids": ["C4RZ8NQ2MXK7WTP3LHB6V5JD"], "modifiers": [] },
      { "line_id": "3", "pos_item_id": "7PKD3RXN2WQ6ZLHM4TB5JV8C", "name": "Butter croissant", "quantity": 1, "unit_price_cents": 350, "pos_category_ids": ["P9MT2XQ6KZR4WLN8HCB3J7VD"], "modifiers": [] }
    ],
    "codes": ["WELCOME10"],
    "reward_ids": [],
    "wallet_item_ids": []
  }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48const response = await fetch(`${process.env.UNPLUG_API}/checkouts/preview`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MEMBER_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    member_id: "3f2b8c1e-6d0a-4e7b-9f3c-2a1d5e8b7c40",
    location_id: "8d4e2a17-3b9c-4f5e-a6d1-7c0b9e2f4a53",
    channel: "app",
    fulfillment: "pickup",
    currency: "USD",
    subtotal_cents: 1250,
    items: [
      {
        line_id: "1",
        pos_item_id: "HV4MZ2TQ7LW3KXRB5P8NJ6DC",
        name: "Oat latte",
        quantity: 1,
        unit_price_cents: 575,
        pos_category_ids: ["C4RZ8NQ2MXK7WTP3LHB6V5JD"],
        modifiers: [],
      },
      {
        line_id: "2",
        pos_item_id: "3NZQ7XKJ2Y5PLVKCW6RQ4G2T",
        name: "Drip coffee",
        quantity: 1,
        unit_price_cents: 325,
        pos_category_ids: ["C4RZ8NQ2MXK7WTP3LHB6V5JD"],
        modifiers: [],
      },
      {
        line_id: "3",
        pos_item_id: "7PKD3RXN2WQ6ZLHM4TB5JV8C",
        name: "Butter croissant",
        quantity: 1,
        unit_price_cents: 350,
        pos_category_ids: ["P9MT2XQ6KZR4WLN8HCB3J7VD"],
        modifiers: [],
      },
    ],
    codes: ["WELCOME10"],
    reward_ids: [],
    wallet_item_ids: [],
  }),
});
const data = await response.json();

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50import os
import requests

response = requests.post(
    f"{os.environ['UNPLUG_API']}/checkouts/preview",
    headers={
        "Authorization": f"Bearer {os.environ['MEMBER_TOKEN']}",
    },
    json={
        "member_id": "3f2b8c1e-6d0a-4e7b-9f3c-2a1d5e8b7c40",
        "location_id": "8d4e2a17-3b9c-4f5e-a6d1-7c0b9e2f4a53",
        "channel": "app",
        "fulfillment": "pickup",
        "currency": "USD",
        "subtotal_cents": 1250,
        "items": [
            {
                "line_id": "1",
                "pos_item_id": "HV4MZ2TQ7LW3KXRB5P8NJ6DC",
                "name": "Oat latte",
                "quantity": 1,
                "unit_price_cents": 575,
                "pos_category_ids": ["C4RZ8NQ2MXK7WTP3LHB6V5JD"],
                "modifiers": [],
            },
            {
                "line_id": "2",
                "pos_item_id": "3NZQ7XKJ2Y5PLVKCW6RQ4G2T",
                "name": "Drip coffee",
                "quantity": 1,
                "unit_price_cents": 325,
                "pos_category_ids": ["C4RZ8NQ2MXK7WTP3LHB6V5JD"],
                "modifiers": [],
            },
            {
                "line_id": "3",
                "pos_item_id": "7PKD3RXN2WQ6ZLHM4TB5JV8C",
                "name": "Butter croissant",
                "quantity": 1,
                "unit_price_cents": 350,
                "pos_category_ids": ["P9MT2XQ6KZR4WLN8HCB3J7VD"],
                "modifiers": [],
            },
        ],
        "codes": ["WELCOME10"],
        "reward_ids": [],
        "wallet_item_ids": [],
    },
)
data = response.json()

Response JSON200

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27{
  "member_id": "3f2b8c1e-6d0a-4e7b-9f3c-2a1d5e8b7c40",
  "points_balance": 420,
  "points_to_earn": 125,
  "applicable": [
    {
      "type": "wallet_item",
      "wallet_item_id": "7e3a9c51-0b8d-4f2e-a6c4-5d1b9e7f3a28",
      "name": "Fall pastry on us",
      "discount_cents": 350,
      "affected_line_ids": ["3"]
    },
    {
      "type": "code",
      "code": "WELCOME10",
      "name": "10% off your order",
      "discount_cents": 125,
      "affected_line_ids": ["1", "2", "3"]
    }
  ],
  "not_applicable": [
    { "type": "reward", "reward_id": "9a6e3d21-4c7b-4f8a-b2e5-0d1c6f3a7b98", "name": "Free drip coffee", "points_cost": 500, "reason": "not_enough_points", "message": "You need 80 more Beans for this reward." },
    { "type": "reward", "reward_id": "5e8b1f4c-2d9a-4b6e-8c3f-7a0d2e9b1c65", "name": "Free pastry", "points_cost": 700, "reason": "not_enough_points", "message": "You need 280 more Beans for this reward." },
    { "type": "reward", "reward_id": "b3d7a9e2-6f1c-4a8d-9e5b-2c4f7a1d3e86", "name": "$5 off", "points_cost": 900, "reason": "not_enough_points", "message": "You need 480 more Beans for this reward." }
  ],
  "challenge_progress": []
}

Error descriptions#

400Bad request

missing_param

A required cart field is missing. param names it.

400Bad request

invalid_param

A field has the wrong format, for example an unknown fulfillment.

404Not found

member_not_found

No member with this id.

404Not found

location_not_found

No location with this id in your brand.

410Gone

member_deleted

The member was deleted.

Free drip coffee costs 500 Beans and Maya has 420, so it is in not_applicable. An unknown or expired code is not an error here either: it comes back in not_applicable, so you can show the message next to the code field.

Any endpoint can also return the common errors.

400 Bad request

1
2
3
4
5
6
7{
  "type": "https://docs.unplugdining.com/reference/errors#missing_param",
  "title": "Bad request",
  "status": 400,
  "code": "missing_param",
  "detail": "A required cart field is missing. param names it."
}