Menu

API reference

Storefront

What a customer-facing website calls with a storefront key: outlets, menus, pickup windows, checkout, order status and the live order tracker (GET /v1/stream). Payment is at the counter; nothing is charged online.

get

/v1/storefront/cares

The storefront key's own live donation listings (uncached; a bad key or a non-storefront channel is 404)

operationId getStorefrontCares

Auth

Storefront keyorStorefront key+Customer token

Response 200

V1StorefrontCarescontract v1.storefront.cares

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

get

/v1/storefront/outlets

Outlets the storefront key's tenant offers

operationId storefrontOutlets

Auth

Storefront keyorStorefront key+Customer token

Response 200

StorefrontOutletsResponsecontract storefront.outlets.response
  • outletsarray of objectrequired
    • outlet_idUuid7required
    • namestringrequired
    • kindenum (3)required
      restaurantcloud_kitchenstore
    • tzstringrequired
    • addressstringrequired
    • phonestring | nullrequired
    • tax_idsarray of objectrequired
      • codestringrequired
      • labelstringrequired
      • valuestringrequired
  • pay_at_counter_methodsarray of enum (3) | nullrequired

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

get

/v1/storefront/outlets/{outlet_id}/menu

Public menu with availability, deals and the effective accepting state

operationId storefrontMenu

Auth

Storefront keyorStorefront key+Customer token

Parameters

  • outlet_idin pathstringrequired
    pattern ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Response 200

StorefrontMenuResponsecontract storefront.menu.response
  • outlet_idUuid7required
  • channel_idUuid7required
  • channel_kindone of 2required
  • brandsarray of objectrequired
    • brand_idUuid7required
    • namestringrequired
  • prices_include_taxbooleanrequired
  • acceptingStorefrontAcceptingResponserequired
  • itemsarray of objectrequired
    • item_idUuid7required
    • name_keystringrequired
      pattern ^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$
    • display_namestring | nullrequired
    • descriptionstring | nullrequired
    • dietenum (4) | nullrequired
      vegnon_vegeggvegan
    • categorystringrequired
    • brand_idUuid7 | nullrequired
    • kindenum (3)required
      dishskucombo
    • availablebooleanrequired
    • price_minorinteger | nullrequired
      ≥ -9007199254740991≤ 9007199254740991
    • currencystringrequired
      pattern ^[A-Z]{3}$
    • variantsarray of objectrequired
      • variant_idUuid7required
      • name_keystringrequired
        pattern ^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$
      • display_namestring | nullrequired
      • descriptionstring | nullrequired
      • availablebooleanrequired
      • price_minorintegerrequired
        ≥ -9007199254740991≤ 9007199254740991
    • option_groupsarray of objectrequired
      • option_group_idUuid7required
      • name_keystringrequired
        pattern ^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$
      • display_namestring | nullrequired
      • descriptionstring | nullrequired
      • min_selectintegerrequired
        ≥ 0≤ 9007199254740991
      • max_selectintegerrequired
        ≥ 1≤ 9007199254740991
      • requiredbooleanrequired
      • optionsarray of objectrequired
        Show fields of options
        • option_idUuid7required
        • name_keystringrequired
          pattern ^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$
        • display_namestring | nullrequired
        • descriptionstring | nullrequired
        • price_delta_minorintegerrequired
          ≥ -9007199254740991≤ 9007199254740991
  • dealsarray of objectrequired
    • deal_idUuid7required
    • name_keystringrequired
      pattern ^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$
    • kindstringrequired
    • windowsarray of objectrequired
      • daysarray of integerrequired
        min items 1max items 7
      • fromstringrequired
        pattern ^([01][0-9]|2[0-3]):[0-5][0-9]$
      • tostringrequired
        pattern ^([01][0-9]|2[0-3]):[0-5][0-9]$
    • valid_fromstring (date)required
      pattern ^(?:(?:[0-9][0-9][2468][048]|[0-9][0-9][13579][26]|[0-9][0-9]0[48]|[02468][048]00|[13579][26]00)-02-29|[0-9]{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12][0-9]|3[01])|(?:0[469]|11)-(?:0[1-9]|[12][0-9]|30)|(?:02)-(?:0[1-9]|1[0-9]|2[0-8])))$
    • valid_tostring (date) | nullrequired
      pattern ^(?:(?:[0-9][0-9][2468][048]|[0-9][0-9][13579][26]|[0-9][0-9]0[48]|[02468][048]00|[13579][26]00)-02-29|[0-9]{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12][0-9]|3[01])|(?:0[469]|11)-(?:0[1-9]|[12][0-9]|30)|(?:02)-(?:0[1-9]|1[0-9]|2[0-8])))$
  • pay_at_counterconst truerequired
  • pay_at_counter_methodsarray of enum (3) | nullrequired

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

get

/v1/storefront/outlets/{outlet_id}/state

Effective accepting-orders state (open / busy +N / paused / closed) with next opening

operationId storefrontState

Auth

Storefront keyorStorefront key+Customer token

Parameters

  • outlet_idin pathstringrequired
    pattern ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Response 200

StorefrontAcceptingResponsecontract storefront.accepting.response
  • outlet_idUuid7required
  • stateenum (4)required
    openbusypausedclosed
  • busy_extra_minintegerrequired
    ≥ 0≤ 9007199254740991
  • default_prep_minintegerrequired
    ≥ 0≤ 9007199254740991
  • next_openIsoDatetime | nullrequired
  • tzstringrequired
  • as_ofIsoDatetimerequired

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

get

/v1/storefront/outlets/{outlet_id}/pickup-windows

Pickup windows with spare capacity

operationId storefrontPickupWindows

Auth

Storefront keyorStorefront key+Customer token

Parameters

  • outlet_idin pathstringrequired
    pattern ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Response 200

StorefrontPickupWindowsResponsecontract storefront.pickup_windows.response
  • outlet_idUuid7required
  • windowsarray of objectrequired
    • pickup_window_idUuid7required
    • starts_atIsoDatetimerequired
    • ends_atIsoDatetimerequired
    • capacity_ordersintegerrequired
      ≥ 1≤ 9007199254740991
    • bookedintegerrequired
      ≥ 0≤ 9007199254740991

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

post

/v1/storefront/orders:preview

Price a cart (Preview; writes nothing) with tax rates, component amounts and refusal parameters; channel comes from the key

operationId storefrontPreviewOrder

Auth

Storefront keyorStorefront key+Customer token

Request body

OrdersPreviewRequestcontract orders.preview.request
  • outlet_idUuid7required
  • channel_idUuid7required
  • brand_idUuid7 | nullrequired
  • kindenum (4)required
    dine_intakeawaypickupdelivery
  • pickup_window_idUuid7 | nullrequired
  • promised_atIsoDatetime | nullrequired
  • coupon_codesarray of stringrequired
    max items 5
  • loyalty_redeem_pointsintegerrequired
    ≥ 0≤ 9007199254740991
  • linesarray of objectrequired
    min items 1
    • item_idUuid7required
    • variant_idUuid7 | nullrequired
    • option_idsarray of Uuid7required
    • qty_milliintegerrequired
      > 0≤ 9007199254740991
    • barcodestring | nullrequired
      pattern ^[0-9A-Za-z-]{4,32}$

Response 200

StorefrontPreviewResponsecontract storefront.preview.response
  • labelconst "preview"required
  • priced_atIsoDatetimerequired
  • currencystringrequired
    pattern ^[A-Z]{3}$
  • tax_ruleobjectrequired
    • pack_codestringrequired
      pattern ^[A-Z]{2}$
    • pack_versionintegerrequired
      ≥ 1≤ 9007199254740991
  • linesarray of objectrequired
    • line_nointegerrequired
      ≥ 1≤ 9007199254740991
    • item_idUuid7required
    • variant_idUuid7 | nullrequired
    • qty_milliintegerrequired
      > 0≤ 9007199254740991
    • unit_price_minorintegerrequired
      ≥ -9007199254740991≤ 9007199254740991
    • options_minorintegerrequired
      ≥ -9007199254740991≤ 9007199254740991
    • line_discount_minorintegerrequired
      ≥ -9007199254740991≤ 9007199254740991
    • tax_classstringrequired
      pattern ^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$
    • tax_minorintegerrequired
      ≥ -9007199254740991≤ 9007199254740991
    • line_total_minorintegerrequired
      ≥ -9007199254740991≤ 9007199254740991
    • price_refstringrequired
      pattern ^⟨cite:(?:row:[a-z_][a-z0-9_]*\.[a-z_][a-z0-9_]*:[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|(?:doc|msg|claim|snapshot):[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})(?:·(?:0|[1-9][0-9]*)-(?:0|[1-9][0-9]*))?⟩$
    • option_refsarray of stringrequired
    • deal_refsarray of stringrequired
    • coupon_refsarray of stringrequired
    • tax_rate_bpintegerrequired
      ≥ 0≤ 10000
    • tax_componentsarray of objectrequired
      • codestringrequired
      • rate_bpintegerrequired
        ≥ 0≤ 10000
      • amount_minorintegerrequired
        ≥ -9007199254740991≤ 9007199254740991
  • subtotal_minorintegerrequired
    ≥ -9007199254740991≤ 9007199254740991
  • discount_minorintegerrequired
    ≥ -9007199254740991≤ 9007199254740991
  • tax_minorintegerrequired
    ≥ -9007199254740991≤ 9007199254740991
  • total_minorintegerrequired
    ≥ -9007199254740991≤ 9007199254740991
  • refusalsarray of objectrequired
    • line_nointeger | nullrequired
      ≥ 1≤ 9007199254740991
    • reason_codeReasonCoderequired
    • paramsobjectoptional
      • line_nointegeroptional
        ≥ 1≤ 9007199254740991
      • item_idUuid7optional
      • variant_idUuid7 | nulloptional
      • deal_idUuid7optional
      • codestringoptional
        pattern ^[A-Z0-9][A-Z0-9-]{2,31}$
      • min_spend_minorintegeroptional
        ≥ -9007199254740991≤ 9007199254740991
      • shortfall_minorintegeroptional
        ≥ -9007199254740991≤ 9007199254740991
      • old_total_minorintegeroptional
        ≥ -9007199254740991≤ 9007199254740991
      • new_total_minorintegeroptional
        ≥ -9007199254740991≤ 9007199254740991
      • currencystringoptional
        pattern ^[A-Z]{3}$
  • tax_componentsarray of objectrequired
    • codestringrequired
    • rate_bpintegerrequired
      ≥ 0≤ 10000
    • amount_minorintegerrequired
      ≥ -9007199254740991≤ 9007199254740991
  • prices_include_taxbooleanrequired

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

post

/v1/storefront/orders

Guest or signed-in checkout in one transaction; pay at the counter. A refusal's 409 / 422 body carries `params`

operationId storefrontPlaceOrder

Auth

Storefront keyorStorefront key+Customer token

Request body

StorefrontOrderPlaceRequestcontract storefront.order.place.request
  • orderobjectrequired
    • command_idUuid7required
    • idempotency_keystringrequired
      pattern ^[A-Za-z0-9_.:-]{8,100}$
    • typeconst "orders.place.v1"required
    • payloadOrdersPlaceV1required
  • guestobject | nullrequired
    • command_idUuid7required
    • idempotency_keystringrequired
      pattern ^[A-Za-z0-9_.:-]{8,100}$
    • typeconst "storefront.guest.create.v1"required
    • payloadStorefrontGuestCreateV1required
  • contactobject | nullrequired
    • namestringrequired
      min length 1max length 200
    • phonestring | nullrequired
      pattern ^\+[1-9][0-9]{6,14}$

Response 201

StorefrontOrderPlacedcontract storefront.order.placed
  • order_idUuid7required
  • statusenum (7)required
    placedacceptedrejectedpreparingreadycompletedcancelled
  • ticket_nointegerrequired
    ≥ 1≤ 9007199254740991
  • total_minorintegerrequired
    ≥ -9007199254740991≤ 9007199254740991
  • tax_minorintegerrequired
    ≥ -9007199254740991≤ 9007199254740991
  • prices_include_taxboolean | nullrequired
  • currencystringrequired
    pattern ^[A-Z]{3}$
  • promised_atIsoDatetime | nullrequired
  • pay_at_counterconst truerequired
  • guest_access_tokenstring | nullrequired

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

get

/v1/storefront/orders/{id}

The shopper's own order (customer token or guest access token); anything else is 404

operationId storefrontGetOrder

Auth

Storefront keyorStorefront key+Customer tokenorStorefront key+Guest token

Parameters

  • idin pathstringrequired
    pattern ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Response 200

StorefrontOrderViewcontract storefront.order.view
  • order_idUuid7required
  • outlet_idUuid7required
  • kindenum (4)required
    dine_intakeawaypickupdelivery
  • statusenum (7)required
    placedacceptedrejectedpreparingreadycompletedcancelled
  • ticket_nointegerrequired
    ≥ 1≤ 9007199254740991
  • business_datestring (date)required
    pattern ^(?:(?:[0-9][0-9][2468][048]|[0-9][0-9][13579][26]|[0-9][0-9]0[48]|[02468][048]00|[13579][26]00)-02-29|[0-9]{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12][0-9]|3[01])|(?:0[469]|11)-(?:0[1-9]|[12][0-9]|30)|(?:02)-(?:0[1-9]|1[0-9]|2[0-8])))$
  • promised_atIsoDatetime | nullrequired
  • pickup_window_idUuid7 | nullrequired
  • subtotal_minorintegerrequired
    ≥ -9007199254740991≤ 9007199254740991
  • discount_minorintegerrequired
    ≥ -9007199254740991≤ 9007199254740991
  • tax_minorintegerrequired
    ≥ -9007199254740991≤ 9007199254740991
  • total_minorintegerrequired
    ≥ -9007199254740991≤ 9007199254740991
  • currencystringrequired
    pattern ^[A-Z]{3}$
  • created_atIsoDatetimerequired
  • cancel_window_minintegerrequired
    ≥ 0≤ 9007199254740991
  • reschedule_window_minintegerrequired
    ≥ 0≤ 9007199254740991
  • pay_at_counterconst truerequired
  • prices_include_taxboolean | nullrequired
  • linesarray of objectrequired
    • line_nointegerrequired
      ≥ 1≤ 9007199254740991
    • item_idUuid7required
    • variant_idUuid7 | nullrequired
    • qty_milliintegerrequired
      ≥ -9007199254740991≤ 9007199254740991
    • unit_price_minorintegerrequired
      ≥ -9007199254740991≤ 9007199254740991
    • line_discount_minorintegerrequired
      ≥ -9007199254740991≤ 9007199254740991
    • tax_minorintegerrequired
      ≥ -9007199254740991≤ 9007199254740991
    • tax_rate_bpinteger | nullrequired
      ≥ 0≤ 10000
    • tax_component_ratesarray of objectrequired
      • codestringrequired
      • rate_bpintegerrequired
        ≥ 0≤ 10000
  • eventsarray of objectrequired
    • kindenum (2)required
      statuspromised_at
    • from_statusstring | nullrequired
    • to_statusstring | nullrequired
    • from_promised_atIsoDatetime | nullrequired
    • to_promised_atIsoDatetime | nullrequired
    • reasonstring | nullrequired
    • atIsoDatetimerequired

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

post

/v1/storefront/orders/{id}:cancel

storefront.order.cancel.v1 — inside the outlet's cancel window

operationId storefrontCancelOrder

Auth

Storefront keyorStorefront key+Customer token

Parameters

  • idin pathstringrequired
    pattern ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Request body

object
  • command_idUuid7required
  • idempotency_keystringrequired
    pattern ^[A-Za-z0-9_.:-]{8,100}$
  • typeconst "storefront.order.cancel.v1"required
  • payloadStorefrontOrderCancelV1required

Response 200

CommandResultcontract command-result
  • command_idUuid7required
  • typestringrequired
    pattern ^[a-z][a-z_]*(\.[a-z][a-z_]*)+\.v[1-9][0-9]*$
  • entity_idUuid7required
  • committed_atIsoDatetimerequired

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

post

/v1/storefront/orders/{id}:reschedule-preview

Re-price the order at a new pickup time; writes nothing

operationId storefrontReschedulePreview

Auth

Storefront keyorStorefront key+Customer token

Parameters

  • idin pathstringrequired
    pattern ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Request body

StorefrontReschedulePreviewRequestcontract storefront.reschedule.preview.request

Response 200

StorefrontReschedulePreviewResponsecontract storefront.reschedule.preview.response

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

post

/v1/storefront/orders/{id}:reschedule

storefront.order.reschedule.v1 — inside the outlet's reschedule window; deals re-priced (deal_rejudged carries old/new totals in `params`)

operationId storefrontRescheduleOrder

Auth

Storefront keyorStorefront key+Customer token

Parameters

  • idin pathstringrequired
    pattern ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Request body

object
  • command_idUuid7required
  • idempotency_keystringrequired
    pattern ^[A-Za-z0-9_.:-]{8,100}$
  • typeconst "storefront.order.reschedule.v1"required
  • payloadStorefrontOrderRescheduleV1required

Response 200

CommandResultcontract command-result
  • command_idUuid7required
  • typestringrequired
    pattern ^[a-z][a-z_]*(\.[a-z][a-z_]*)+\.v[1-9][0-9]*$
  • entity_idUuid7required
  • committed_atIsoDatetimerequired

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

get

/v1/stream

Server-sent events for the given topics (kds / order / inbox / trace); text/event-stream, read with the SDK's openStream; resume with Last-Event-ID; heartbeat every 20 s, closed at 55 min

operationId streamEvents

Auth

Storefront keyorStorefront key+Customer tokenorStorefront key+Guest tokenorMember token+Tenant header

Parameters

  • topicsin querystringrequired

Response 200 · OK — server-sent events; each `data:` line is the JSON of StreamEvent (read with the SDK's openStream, never EventSource)

Server-sent events — each data: line is a StreamEvent.

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

get

/v1/storefront/page

The live storefront page (theme and home page sections), or null for the built-in look

operationId storefrontPage

Auth

Storefront keyorStorefront key+Customer token

Response 200

StorefrontPagePubliccontract storefront.page.public

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.