Core Concepts

The Storefront API is built around five entities: merchants, locations, menus, carts, and orders. This page explains how they relate to each other and what data each one carries.

Merchants

A merchant represents a restaurant brand. Each merchant has a name, logo, and one or more locations.

const merchant = await storefront.merchant.getBySlug("downtown-pizza");

merchant.id; // "5b2e7f71-62cf-4bd5-b84e-df17f1f18927"
merchant.name; // "Downtown Pizza Co."
merchant.locations; // MerchantLocation[]

Use merchant.getBySlug() to resolve a brand slug into its list of locations. Each location in the response includes an id, display name, address, logo, and a methodsStatus object indicating which fulfillment methods are enabled.

Locations

A location is a single restaurant site. All storefront operations — menus, carts, payments — are scoped to a location.

const location = await storefront.locations.getById(
  "f8af3da4-f70e-4521-a04f-716c0c04fb77",
);

location.restaurantDisplayName; // "Downtown Pizza — Market St"
location.addressString; // "123 Market St, San Francisco, CA 94105"
location.addressData; // { street, city, state, zipCode, country, lat, lng }

Location identifiers

You can reference a location by either its UUID or slug. Both work in storefront location endpoints:

/api/v1/storefront/locations/f8af3da4-f70e-4521-a04f-716c0c04fb77/...
/api/v1/storefront/locations/downtown-pizza/...

Fulfillment methods

Each location enables a subset of these fulfillment methods:

Method	Value	Description
Pickup	`takeout`	Customer picks up at the counter
Delivery	`delivery`	Delivered to customer’s address
Table-side	`table_side`	Served to a table number
Room service	`room_service`	Delivered to a hotel room

Check methodsStatus on the merchant location response to determine which options to show:

const loc = merchant.locations[0];
loc.methodsStatus.pickup; // true
loc.methodsStatus.delivery; // true
loc.methodsStatus.table; // false
loc.methodsStatus.roomService; // false

Order times

Locations define when they accept orders. Fetch the available time slots before showing a schedule picker:

const times = await storefront.locations.getOrderTimes(
  "f8af3da4-f70e-4521-a04f-716c0c04fb77",
);

times.scheduleAllowed; // true — scheduled orders accepted
times.requireScheduledOrders; // false — ASAP is available
times.orderDays; // RegularOrderDay[] or SpecialOrderDay[]

Menus, categories, and products

Each location has one or more menus. A menu contains categories, and each category links to products. The active menu depends on the time of day.

Merchant → Location → Menu → Category → Product → Modifier

Products

A product represents a single orderable item:

Field	Type	Description
`id`	`string`	Unique product ID
`name`	`string`	Display name
`description`	`string`	Short description
`price`	`string`	Base price as a decimal string (e.g., `"12.99"`)
`displayPrice`	`string`	Formatted price with currency symbol
`images`	`string[]`	Product image URLs
`modifiers`	`Modifier[]`	Available customizations
`availability`	`string`	Current availability status
`nutrition`	`object \| undefined`	Calorie count, dietary preferences, ingredients

Modifiers

Modifiers let customers customize a product (e.g., size, toppings, extras). Each modifier group has selection rules:

interface Modifier {
  id: string;
  name: string; // "Choose your size"
  rule: {
    min: number; // 1 — must select at least one
    max: number; // 1 — can select at most one
  };
  items: ModifierItem[]; // [{ id, name, price, maxQuantity }]
}

Modifier items can have nested child groups for multi-level customization (e.g., “Choose your protein” > “Choose your preparation”).

Carts

A cart holds the customer’s selections and computes all pricing automatically. You create a cart by starting an ordering session:

const session = await storefront.orderingSessions.start("loc_123", {
  marketplaceId: "web",
  fulfillmentMethod: "takeout",
});

const cartId = session.cart.id;

marketplaceId is optional source attribution, such as "web" or "mobile"; it is not a location identifier.

Cart lifecycle

Status	Meaning
`OPEN`	Active — items can be added, removed, or updated
`LOCKED`	Payment is processing — no modifications allowed
`COMPLETED`	Payment confirmed — order sent to the restaurant
`EXPIRED`	Capability is no longer valid; start a new cart

Automatic pricing

Every time you modify the cart, the API recalculates all totals:

Field	Description
`subTotal`	Sum of item prices before tax and fees
`taxTotal`	Tax based on the location’s tax rates
`serviceFeeTotal`	Platform service fee
`fulfillmentMethodFeeTotal`	Delivery or fulfillment fee
`waiterTipTotal`	Customer gratuity
`orderTotalWithServiceFee`	Final total the customer pays

Price fields are decimal strings. Format them using the cart currency and the customer’s locale.

Cart items

Each item in the cart tracks its product, quantity, modifier selections, special instructions, and computed totals:

const cart = await storefront.cart.get("loc_123", cartId);

cart.items.forEach((item) => {
  item.name; // "Margherita Pizza"
  item.quantity; // 2
  item.total; // "25.98"
  item.selections; // CartModifierGroup[] — chosen modifiers
  item.specialInstructions; // "Extra crispy"
});

Fulfillment configuration

Before checkout, set the fulfillment method on the cart. Each method requires different data:

Method	API call	Required data
Pickup	`cart.update(...)`	`{ fulfillmentMethod: 'takeout' }`
Delivery	`cart.setDelivery(...)`	Full address with `lat`/`lng`
Table-side	`cart.setTable(...)`	Numeric table string such as `"12"`
Room service	`cart.setRoom(...)`	Room number and last name

Payments

Stripe is the only online processor. Submit the order before collecting payment, then render Stripe Elements only when the outcome requires customer action:

const outcome = await storefront.checkout.submitOrder("loc_123", cartId, {
  acceptedCatalogEvidence,
  acceptedDiscountEvidence,
  collectionMode: "ONLINE",
  customerConfirmationRevision,
  quoteFingerprint,
});

CUSTOMER_ACTION_REQUIRED includes the Stripe clientSecret and immutable connectedAccountId. Square, Clover, and Toast remain provider-native POS integrations and never expose browser checkout credentials.

Orders

The order-first submission persists the canonical order before Stripe collection. Poll storefront.checkout.getOrderSubmissionOutcome() with its attempt ID after payment. It distinguishes processing, customer action, paid, accepted pay-at-store, and action-required outcomes. Signed-in customers can list and read only their own orders through storefront.customer.orders.

Analytics events

Track key funnel events to measure storefront performance:

await storefront.analyticsEvents.track("loc_123", {
  cartId,
  eventType: "CHECKOUT_VIEW", // 'SCAN' | 'CART_VIEW' | 'CHECKOUT_VIEW'
});

Every public analytics event requires authorization for its cart. ORDER_PLACED is recorded by the API during authoritative order creation and is not accepted from clients.

Currencies and countries

The API supports these currencies and countries:

Currency	Code	Countries
US Dollar	`usd`	US
British Pound	`gbp`	GB
UAE Dirham	`aed`	AE
Australian Dollar	`aud`	AU

Currency is set at the merchant level and applies to all locations under that merchant.

Next steps

Display Menu

Fetch menus, categories, and products for a location.

Manage Cart

Add items, apply modifiers, and manage the cart lifecycle.

Checkout Flow

Collect customer details, set order time, and process payment.

Fulfillment Methods

Configure delivery, table-side, and room service.

SDK Reference

API Endpoints

Staff Menu Manager authoring

Server-to-Server Integration API

Error Codes

Merchants

Locations

Location identifiers

Fulfillment methods

Order times

Menus, categories, and products

Products

Modifiers

Carts

Cart lifecycle

Automatic pricing

Cart items

Fulfillment configuration

Payments

Orders

Analytics events

Currencies and countries

Next steps

Display Menu

Manage Cart

Checkout Flow

Fulfillment Methods

​Merchants

​Locations

​Location identifiers

​Fulfillment methods

​Order times

​Menus, categories, and products

​Products

​Modifiers

​Carts

​Cart lifecycle

​Automatic pricing

​Cart items

​Fulfillment configuration

​Payments

​Orders

​Analytics events

​Currencies and countries

​Next steps

Display Menu

Manage Cart

Checkout Flow

Fulfillment Methods

Merchants

Locations

Location identifiers

Fulfillment methods

Order times

Menus, categories, and products

Products

Modifiers

Carts

Cart lifecycle

Automatic pricing

Cart items

Fulfillment configuration

Payments

Orders

Analytics events

Currencies and countries

Next steps