Core Concepts

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

merchant.id;        // "64a7b8c9d1e2f3a4b5c6d7e8"
merchant.name;      // "Downtown Pizza Co."
merchant.locations;  // MerchantLocation[]

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 }

/api/v1/locations/64a7b8c9d1e2f3a4b5c6d7e8/...
/api/v1/locations/downtown-pizza/...

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

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[]

Merchant → Location → Menu → Category → Product → Modifier

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 }]
}

const session = await storefront.orderingSessions.start('loc_123', {
  marketplaceId: 'loc_123',
});

const cartId = session.cartId;

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"
});

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

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