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;        // "64a7b8c9d1e2f3a4b5c6d7e8"
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('loc_123');

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 ObjectId or slug. Both work in every endpoint:

/api/v1/locations/64a7b8c9d1e2f3a4b5c6d7e8/...
/api/v1/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('loc_123');

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: 'loc_123',
});

const cartId = session.cartId;

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

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

All price fields have a corresponding *Formatted variant (e.g., subTotalFormatted: "$25.98") for display.

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.totalFormatted;      // "$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(...)`	Table number string
Room service	`cart.setRoom(...)`	Room number and last name

Payments

Crave processes payments through Stripe Connect. You create a PaymentIntent via the API and confirm it on the client with Stripe.js:

const { clientSecret, stripeAccountId } = await storefront.payments.createIntent(
  'loc_123',
  cartId
);

Field	Description
`clientSecret`	Pass to `stripe.confirmPayment()` on the client
`stripeAccountId`	The restaurant’s connected Stripe account

Always pass the stripeAccountId when initializing Stripe on the client. This routes the payment to the correct connected account.

Orders

Orders are created automatically when a payment succeeds — you do not create them via the API. After payment, the order appears in the restaurant’s merchant dashboard for fulfillment. The Storefront API does not expose order management endpoints. To track order completion from the customer’s perspective, poll the cart status until it reaches COMPLETED.

Analytics events

Track key funnel events to measure storefront performance:

await storefront.analyticsEvents.track('loc_123', {
  cartId,
  eventType: 'ORDER_PLACED', // 'SCAN' | 'CART_VIEW' | 'CHECKOUT_VIEW' | 'ORDER_PLACED'
  metadata: { total: cart.orderTotalWithServiceFee },
});

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

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