> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Core Concepts

> Understand the data model behind merchants, locations, menus, carts, and orders.

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.

```ts theme={null}
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.

```ts theme={null}
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:

```ts theme={null}
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:

```ts theme={null}
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:

```ts theme={null}
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**:

```ts theme={null}
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:

```ts theme={null}
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:

```ts theme={null}
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:

```ts theme={null}
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

> [card] [Display Menu](/docs/guides/display-menu.md)
>
> Fetch menus, categories, and products for a location.

> [card] [Manage Cart](/docs/guides/manage-cart.md)
>
> Add items, apply modifiers, and manage the cart lifecycle.

> [card] [Checkout Flow](/docs/guides/checkout-flow.md)
>
> Collect customer details, set order time, and process payment.

> [card] [Fulfillment Methods](/docs/guides/fulfillment-methods.md)
>
> Configure delivery, table-side, and room service.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.