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[]
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 |
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 }]
}
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 |
*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 |
Next steps
