Type Definitions

Type definitions for the Marketfront API.

API Reference

The API Reference contains auto-generated endpoint documentation. This page provides supplementary type definitions and usage patterns for key data models.

Store

A Store represents a merchant/restaurant that can fulfill food orders.

interface Store {
  // Identifiers
  storeId: string;              // Unique store ID
  stem: string;                 // URL-friendly slug

  // Display information
  name: string;
  description?: string;
  imageUrl?: string;
  logoUrl?: string;

  // Categorization
  cuisineTypes: string[];       // e.g., ["Italian", "Pizza"]
  tags: string[];               // e.g., ["Family-Friendly", "Quick Service"]

  // Rating
  ratingLevel?: number;         // 1-5 scale
  reviewCount?: number;

  // Location
  address: StoreAddress;
  distance?: number;            // Distance from user in miles

  // Operational
  isOpen: boolean;
  isTransactable: boolean;      // Can accept orders now
  currentWaitTime?: number;     // Minutes

  // Fulfillment options
  fulfillmentTypes: FulfillmentType[];
  deliveryInfo?: StoreDeliveryInfo;
  pickupInfo?: StorePickupInfo;

  // Hours
  operatingHours: OperatingHours;
}

interface StoreAddress {
  streetAddress: string;
  city: string;
  state: string;
  zipCode: string;
  country: string;
  latitude: number;
  longitude: number;
}

interface StoreDeliveryInfo {
  deliveryFee: number;          // Base delivery fee
  minimumOrder?: number;        // Minimum order for delivery
  estimatedTime: string;        // e.g., "25-35 min"
  deliveryRadius?: number;      // Miles
}

interface StorePickupInfo {
  estimatedTime: string;        // e.g., "15-20 min"
  curbsideAvailable: boolean;
  instructions?: string;
}

interface OperatingHours {
  monday: TimeRange[];
  tuesday: TimeRange[];
  wednesday: TimeRange[];
  thursday: TimeRange[];
  friday: TimeRange[];
  saturday: TimeRange[];
  sunday: TimeRange[];
  timezone: string;             // IANA timezone (e.g., "America/New_York")
}

interface TimeRange {
  open: string;                 // "HH:mm" format
  close: string;                // "HH:mm" format
}

Store States

State	isOpen	isTransactable	Description
Open & Accepting	true	true	Store is open and can accept orders
Open but Busy	true	false	Store is open but temporarily not accepting orders
Closed	false	false	Store is closed

---

CatalogSet

A CatalogSet represents the complete menu structure for a store.

Why Dictionaries?

The CatalogSet uses dictionaries (Record types) rather than nested arrays because:

1. Efficient lookups - O(1) access by ID
2. No data duplication - Items referenced by multiple sections exist once
3. Flexible relationships - Items and modifiers can be reused across sections

interface CatalogSet {
  storeId: string;
  catalogs: Record<string, Catalog>;
  sections: Record<string, Section>;
  items: Record<string, Item>;
  modifierGroups: Record<string, ModifierGroup>;
}

Catalog

A Catalog represents a specific menu (e.g., "Lunch Menu", "Dinner Menu") with availability windows.

interface Catalog {
  catalogId: string;
  name: string;
  description?: string;
  sectionIds: string[];         // References to sections
  availability: CatalogAvailability;
  sortOrder: number;
}

interface CatalogAvailability {
  type: 'ALWAYS' | 'SCHEDULED';
  schedule?: ScheduleWindow[];
}

interface ScheduleWindow {
  dayOfWeek: DayOfWeek;
  startTime: string;            // "HH:mm"
  endTime: string;              // "HH:mm"
}

type DayOfWeek = 'MONDAY' | 'TUESDAY' | 'WEDNESDAY' | 'THURSDAY' | 'FRIDAY' | 'SATURDAY' | 'SUNDAY';

Section

A Section represents a menu category (e.g., "Appetizers", "Entrees").

interface Section {
  sectionId: string;
  name: string;
  description?: string;
  imageUrl?: string;
  itemIds: string[];            // References to items
  sortOrder: number;
}

Item

An Item represents a purchasable food product.

interface Item {
  itemId: string;
  name: string;
  description?: string;
  imageUrl?: string;
  basePrice: number;
  compareAtPrice?: number;      // Original price if on sale
  isAvailable: boolean;
  modifierGroupIds: string[];   // References to modifier groups
  nutritionalInfo?: NutritionalInfo;
  allergens?: string[];
  tags?: string[];              // e.g., ["Vegetarian", "Spicy"]
  sortOrder: number;
}

interface NutritionalInfo {
  calories?: number;
  protein?: number;             // grams
  carbohydrates?: number;       // grams
  fat?: number;                 // grams
  sodium?: number;              // mg
}

CatalogSet Relationships

CatalogSet
├── catalogs: { [catalogId]: Catalog }
│   └── sectionIds → sections
├── sections: { [sectionId]: Section }
│   └── itemIds → items
├── items: { [itemId]: Item }
│   └── modifierGroupIds → modifierGroups
└── modifierGroups: { [modifierGroupId]: ModifierGroup }
    └── itemIds → items (modifiers are also items!)

---

ModifierGroup

ModifierGroups represent customization options for menu items.

interface ModifierGroup {
  modifierGroupId: string;
  name: string;                     // Display name (e.g., "Choose Size")
  description?: string;
  itemIds: string[];                // Available modifier options
  minimumAllowed: number;           // Minimum selections required
  maximumAllowed: number;           // Maximum selections allowed
  enableDuplicateItems: boolean;    // Can select same modifier multiple times?
  sortOrder: number;
}

Selection Rules

Min	Max	Meaning
0	1	Optional single selection
1	1	Required single selection (radio button)
0	5	Optional, up to 5 selections
1	5	Required, 1-5 selections
2	2	Must select exactly 2

Nested Modifiers

Modifier items can have their own modifier groups, enabling multi-level customization:

// Stuffed crust has its own modifier (what to stuff with)
const stuffedCrust: Item = {
  itemId: "crust_stuffed",
  name: "Stuffed Crust",
  basePrice: 3.00,
  modifierGroupIds: ["mod_stuffing"],  // Nested modifier!
};

---

Cart

The Cart represents a shopping cart containing items to be ordered. Carts are managed by your application - there is no server-side cart storage. You can use the Cart Helpers for convenience, or implement your own cart logic.

interface Cart {
  storeId: string;              // Store the cart is for
  catalogSetId: string;         // CatalogSet version used
  lineItems: LineItem[];        // Items in the cart
  totals?: CartTotals;          // Calculated totals (from helpers)
}

interface CartTotals {
  subtotal: number;             // Sum of line item prices
  itemCount: number;            // Total number of items
}

interface LineItem {
  lineItemId: string;               // Unique ID within cart (you generate this)
  itemId: string;                   // Reference to Item in CatalogSet
  name?: string;                    // Item name (for display)
  quantity: number;                 // Number of this item
  unitPrice?: number;               // Price per unit including modifiers
  totalPrice?: number;              // unitPrice × quantity
  modifierGroups: CartModifierGroup[];  // Selected modifiers
  specialInstructions?: string;     // Customer notes for this item
}

interface CartModifierGroup {
  modifierGroupId: string;          // Reference to ModifierGroup
  selectedModifiers: SelectedModifier[];
}

interface SelectedModifier {
  itemId: string;                   // The modifier item ID
  quantity: number;                 // How many selected (usually 1)
  modifierGroups?: CartModifierGroup[];  // Nested modifiers (recursive)
}

Cart with Nested Modifiers

{
  "storeId": "store_abc123",
  "catalogSetId": "catalog_xyz789",
  "lineItems": [
    {
      "lineItemId": "li_004",
      "itemId": "item_combo_meal",
      "quantity": 1,
      "modifierGroups": [
        {
          "modifierGroupId": "mod_main",
          "selectedModifiers": [
            {
              "itemId": "burger_classic",
              "quantity": 1,
              "modifierGroups": [
                {
                  "modifierGroupId": "mod_burger_extras",
                  "selectedModifiers": [
                    {"itemId": "extra_bacon", "quantity": 1}
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

---

Order

An Order represents a finalized cart that has been submitted for fulfillment.

interface Order {
  // Identifiers
  gettOrderId: string;          // Gett platform order ID
  partnerOrderId?: string;      // Store/provider order ID
  userId: string;               // User who placed the order

  // Timestamps
  placedAt?: string;            // ISO 8601 placement time
  estimatedReadyAt?: string;    // Estimated ready/delivery time

  // Order contents
  cart: Cart;

  // Fulfillment
  fulfillmentType: FulfillmentType;
  deliveryInfo?: DeliveryInfo;
  pickupInfo?: PickupInfo;

  // Financials
  amounts: Amounts;
  paymentToken: string;

  // Status
  status?: OrderStatus;
  errors: OrderError[];
}

type FulfillmentType = 'PickUp' | 'DeliveryByMerchant';

interface DeliveryInfo {
  addressId: string;            // Delivery address ID
  type: DeliveryType;           // How to deliver
  instructions?: string;        // Delivery instructions
  scheduledFor?: string;        // ISO 8601 scheduled time
}

type DeliveryType = 'DoorToDoor' | 'Curbside' | 'LeaveAtDoor';

interface PickupInfo {
  scheduledFor?: string;        // ISO 8601 scheduled time
  instructions?: string;        // Pickup instructions
}

Amounts

Financial breakdown of the order.

interface Amounts {
  subTotal: number;             // Sum of line item prices
  promotions: number;           // Discounts (usually 0 or negative)
  fees: number;                 // Service/delivery fees
  taxes: number;                // Tax amount
  tip: number;                  // Tip amount
  total: number;                // Final amount
}

OrderStatus

type OrderStatus =
  | 'PENDING'           // Order submitted, awaiting confirmation
  | 'RECEIVED'          // Store received the order
  | 'CONFIRMED'         // Store confirmed the order
  | 'PREPARING'         // Order is being prepared
  | 'READY'             // Ready for pickup/delivery
  | 'OUT_FOR_DELIVERY'  // Driver has the order
  | 'DELIVERED'         // Order delivered
  | 'COMPLETED'         // Order completed
  | 'CANCELLED';        // Order cancelled

OrderError

interface OrderError {
  reason: OrderErrorReason;
  publicReasonMessage: string;  // User-friendly message
  jsonPath?: string;            // Path to problematic field
}

type OrderErrorReason =
  // Cart/Item errors
  | 'CART_EMPTY'
  | 'ITEM_UNAVAILABLE'
  | 'ITEM_PRICE_CHANGED'
  | 'MODIFIER_UNAVAILABLE'
  | 'MODIFIER_REQUIRED'
  | 'MODIFIER_LIMIT_EXCEEDED'
  | 'MINIMUM_ORDER_NOT_MET'
  // Store errors
  | 'STORE_CLOSED'
  | 'STORE_NOT_ACCEPTING_ORDERS'
  | 'STORE_OUTSIDE_DELIVERY_AREA'
  // Payment errors
  | 'PAYMENT_FAILED'
  | 'PAYMENT_METHOD_INVALID'
  | 'PAYMENT_DECLINED'
  | 'PAYMENT_METHOD_NOT_FOUND'       // Card-on-File: paymentToken not recognized
  | 'PAYMENT_RETRIEVAL_FAILED'       // Card-on-File: unable to retrieve payment data
  | 'PAYMENT_METHOD_EXPIRED'         // Card-on-File: card has expired
  | 'PAYMENT_INTERCHANGE_NOT_CONFIGURED'  // Card-on-File not enabled for partner
  // Order errors
  | 'ORDER_TOTAL_DIFFERENT'
  | 'ORDER_ALREADY_PLACED'
  // Address errors
  | 'ADDRESS_INVALID'
  | 'ADDRESS_OUTSIDE_DELIVERY_AREA'
  // General
  | 'INTERNAL_ERROR'
  | 'UNAUTHORIZED';

---

User

A User represents a consumer who can browse stores and place orders.

interface User {
  id: string;                    // Gett's internal user ID
  partner_user_id: string;       // Your platform's user ID
  email: string;
  firstName: string;
  lastName: string;
  phone?: string;
  preferences: UserPreferences;
  createdAt: string;             // ISO 8601
  lastOrderAt?: string;          // ISO 8601
}

interface UserPreferences {
  defaultAddressId?: string;     // Default delivery address
  defaultpaymentToken?: string;     // Default payment method
  marketingOptIn: boolean;       // Marketing email preference
}

interface UserPaymentMethod {
  paymentToken: string;
  type: 'CARD' | 'APPLE_PAY' | 'GOOGLE_PAY';
  card?: {
    brand: string;               // visa, mastercard, etc.
    last4: string;               // Last 4 digits
    expMonth: number;
    expYear: number;
  };
  isDefault: boolean;
  createdAt: string;
}

---

SessionPaymentMethod

A SessionPaymentMethod represents payment method metadata passed during session creation for Card-on-File integrations.

Display Data Only

Unlike UserPaymentMethod (which is Gett-managed), SessionPaymentMethod contains only display metadata from your platform's saved cards. No sensitive payment data is included.

interface SessionPaymentMethod {
  paymentToken: string;             // Your platform's payment method reference
  cardBrand: CardBrand;          // Card type for display
  lastFour: string;              // Last 4 digits for display
  expirationMonth: number;       // 1-12
  expirationYear: number;        // 4-digit year (e.g., 2027)
  isDefault?: boolean;           // Pre-select at checkout (first in array if not specified)
}

type CardBrand = 'visa' | 'mastercard' | 'amex' | 'discover';

Session Creation Example

{
  "user": { ... },
  "addresses": [ ... ],
  "paymentMethods": [
    {
      "paymentToken": "pm_abc123",
      "cardBrand": "visa",
      "lastFour": "4242",
      "expirationMonth": 12,
      "expirationYear": 2027,
      "isDefault": true
    }
  ]
}

See Payments for full Card-on-File documentation.

---

Address

An Address represents a delivery location for orders.

interface Address {
  addressId: string;
  label?: string;               // Friendly name ("Home", "Work")
  streetAddress: string;        // Street number and name
  unit?: string;                // Apartment, suite, floor
  city: string;
  state: string;                // State/province code
  zipCode: string;
  country: string;              // ISO 3166-1 alpha-2 code
  latitude: number;
  longitude: number;
  isDefault: boolean;
  instructions?: string;        // Delivery instructions
}

Address Validation

interface AddressValidationResult {
  valid: boolean;
  normalizedAddress?: {
    streetAddress: string;
    city: string;
    state: string;
    zipCode: string;
    country: string;
    latitude: number;
    longitude: number;
  };
  deliverable: boolean;         // Are there stores that deliver here?
  storeCount: number;           // Number of available stores
  error?: {
    code: string;
    message: string;
  };
}

valid	deliverable	Meaning
true	true	Valid address with available stores
true	false	Valid address but no stores deliver there
false	-	Invalid or unrecognized address

---

Related Documentation

• API Reference - Auto-generated endpoint documentation
• CatalogSets - Working with menus and modifiers
• Orders - Order validation and placement