Munch Insights Partners API Developer DocsAPI Reference

Online Ordering Cookbook

Table of ContentsCopied!

IntroductionCopied!

This cookbook provides guidance for integrating with the POS Ordering System API. The API follows REST conventions and uses JSON for request/response bodies.

Base URL: /api

Authentication: All endpoints require an ApiKeyAuth header with a valid partner API key.

API EndpointsCopied!

Chain OperationsCopied!

Endpoint Method Description
/chain GET List all authorized chains
/chain/{chainId}/location GET List locations for a chain
/chain/onboard POST Start chain onboarding process
/chain/onboard/status/{taskId} GET Check onboarding status

Location OperationsCopied!

Endpoint Method Description
/chain/{chainId}/location/{locationId}/availability GET Check location availability
/chain/{chainId}/location/{locationId}/catalog GET Get full location menu
/chain/{chainId}/location/{locationId}/menu/{menuId}/catalog GET Get specific menu data

Order OperationsCopied!

Endpoint Method Description
/chain/{chainId}/location/{locationId}/order POST Create new order
/chain/{chainId}/location/{locationId}/draftOrder POST Validate order draft
/chain/{chainId}/location/{locationId}/order/{orderId} GET Get order details
/chain/{chainId}/location/{locationId}/order/{orderId}/void POST Void an order

Core OperationsCopied!

1. Chain OnboardingCopied! 

POST /api/chain/onboard
Content-Type: application/json
{
  "posSystem": "TOAST",
  "posDetails": {
    ...
  }
}

Workflow:

  1. Initiate onboarding with POST request
  2. Receive taskId in response
  3. Poll GET /chain/onboard/status/{taskId} for progress
  4. On success, chain becomes available in system

2. Menu Data RetrievalCopied! 

GET /api/chain/123/location/456/catalog
Response:
{
    "chainId": "123",
    "locationId": "456",
    "menuObjects": [
        {
            "id": "menu-1",
            "name": "Main Menu",
            "groups": [
                {
                    "id": "group-1",
                    "name": "Burgers",
                    "items": [
                        {
                            "id": "item-1",
                            "name": "Classic Burger",
                            "modifierGroups": [
                                {
                                    "id": "mod-group-1",
                                    "name": "Toppings",
                                    "modifiers": [
                                        {"id": "mod-1", "name": "Cheese"}
                                    ]
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}

This retrieves the full catalog/menu for a location.

Some locations may have multiple menus, if you only want to retrieve a specific menu, you can use the /chain/{chainId}/location/{locationId}/menu/{menuId}/catalog endpoint.

3. Order ManagementCopied!

In order to create an order, you need to provide the following information:

  • Order Type
  • Customer Information
  • Order Selections

We'll go through each of the steps needed to create an order below.

Draft OrderCopied!

Before creating an order it's recommended you draft the order first. This ensures that all the order selections and details are valid and pricing is correct. Here's an example of how to draft an order:

POST /api/chain/123/location/456/draftOrder
{
    "orderType": "TAKEOUT",
    "customerInfo": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "john@example.com",
        "phone": "+15551234567"
    },
    "orderSelections": [
        {
            "menuItemId": "item-1",
            "quantity": 2,
            "manualDiscountPercent": 10.0,
            "childSelections": [
                {
                    "modifierItemId": "mod-1",
                    "modifierGroupId": "mod-group-1",
                    "quantity": 2,
                    "isModifierSelection": true
                }
            ]
        }
    ]
}

If there's any issues with the order, you'll receive a validation error with details on what needs to be corrected.

Create OrderCopied!

The create order endpoint is identical to the draft order endpoint except it will store the order in our DB and create it on the location's POS system.

POST /api/chain/123/location/456/order
{
    "orderType": "TAKEOUT",
    "customerInfo": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "john@example.com",
        "phone": "+15551234567"
    },
    "orderSelections": [
        {
            "menuItemId": "item-1",
            "quantity": 2,
            "manualDiscountPercent": 10.0,
            "childSelections": [
                {
                    "modifierItemId": "mod-1",
                    "modifierGroupId": "mod-group-1",
                    "quantity": 2,
                    "isModifierSelection": true
                }
            ]
        }
    ]
}

Read OrderCopied!

After an order has been placed on a POS system we keep track of changes made to it via the POS. We only track certain changes, these are specifically the selection/order readiness and wether it has been voided.

GET /api/chain/123/location/456/order/{orderId}

After hitting this endpoint you'll receive a response with the order details including the status of the order.

Data ModelsCopied!

Order StructureCopied! 

type Order struct {
    Id uuid.UUID // System-generated GUID
    PosOrderId string // POS system reference
    OrderType OrderType // TAKEOUT/DELIVERY/CURBSIDE
    TotalAmount float64 // Final total with tax
    Status OrderReadinessStatus // NEW/HELD/SENT/READY
    Voided bool // Cancellation status
    // ... additional fields ...
}

Order SelectionCopied! 

type OrderSelection struct {
    MenuItemId string
    Quantity int // 1-10 allowed
    ModifierItemId string
    ModifierGroupId string
    ChildSelections []OrderSelection
    PriceDetails struct {
        BasePrice float64
        ModifiersTotal float64
        PreDiscount float64
        Discounts float64
        Taxes float64
        FinalTotal float64
    }
}

Error HandlingCopied!

Common Status Codes:

  • 400: Invalid request (validation errors)
  • 403: Unauthorized chain access
  • 404: Resource not found
  • 422: Business rule violation
  • 500: Internal server error

Error Response Format:

{
  "error": "ERROR_CODE",
  "message": "Human-readable description"
}

Best PracticesCopied!

  1. Pre-flight Checks: Always check availability before order creation
  2. Draft Validation: Use /draftOrder endpoint for price verification
  3. Data Formatting:
    • Phone numbers: E.164 format
    • Emails: RFC 5322 compliant
    • Currency: USD, 2 decimal places