Order Injection Flow

This guide explains how to shape line items and modifiers when your marketplace application sends orders to POS Hub. Use it together with the Marketplace Integration Flow, which covers onboarding, menu publishing, and webhooks.

1. Create order endpoint

Orders are created with:

Environment	OpenAPI documentation
Production	Create order — Production
Staging	Create order — Staging

The request body is defined in those docs. The items array holds the cart lines you inject into the POS.

2. items in the request body

In the create-order payload, each element of items is one line (product, fee, etc.) as required by the schema. You must send the correct identifiers so POS Hub can match what the customer ordered to the merchant’s catalog in POS Hub.

3. Menu vs catalog identifiers

POS Hub exposes both catalog and menu data. Your integration can consume either:

• Menu (recommended) — Use partnerId, menuCategoryId, menuModifierGroupId, and related fields. These align with the menu published to your marketplace.
• Catalog — Use posReference and parentPosReference (and modifier equivalents) from the catalog.

Pick one model per integration path and stay consistent with how you published the menu to the marketplace.

---

4. Menu-based order injection (recommended)

Use IDs from the POS Hub menu that you mirrored on the marketplace.

4a. Line items (products)

For each line item, send:

Field	Meaning
partnerId	The item id from the POS Hub menu that is published to your marketplace.
menuCategoryId	The menu category id for that item in the POS Hub menu (the category the item belongs to).

Other fields (name, quantity, price, customerNotes, options, taxRateIds, etc.) follow the API schema.

Example — single item, no modifiers:

[
  {
    "customerNotes": "Light lettuce, no tomato/onions. Bread scooped, cut in 4.",
    "menuCategoryId": "25eb5639-5a20-46f5-8e44-1a5c9e8417ab",
    "name": "CHICKEN SALAD",
    "options": [],
    "partnerId": "6242aa36-ee8b-41e6-b83a-5c251316a804",
    "price": 1000,
    "quantity": 1,
    "taxRateIds": []
  }
]

4b. Modifiers (one level)

Modifiers go in options on the line item. For each modifier, send:

Field	Meaning
partnerId	The modifier id from the POS Hub menu (published to your marketplace).
menuModifierGroupId	The modifier group id that contains this modifier in the POS Hub menu.

Example — line item with modifiers:

[
  {
    "quantity": 1,
    "name": "New York Style Pizza",
    "partnerId": "1ef670db-4989-4b94-948b-822f08a3fe63",
    "customerNotes": "16 inch size unavailable.",
    "options": [
      {
        "name": "----Whole----",
        "quantity": 1,
        "partnerId": "be36d841-bf4e-4f64-a15e-7c0e332879b1",
        "menuModifierGroupId": "c0655be9-29d8-468a-8dfe-47524a065e98",
        "price": 0
      }
    ],
    "price": 1800,
    "menuCategoryId": "cf1c2947-1969-47ea-ad7b-dcc98cebc69f"
  }
]

4c. Nested modifiers

When a modifier is nested under another modifier, send the same partnerId and menuModifierGroupId as for a non-nested modifier, and add:

Field	Meaning
parentMenuModifierId	The parent modifier’s id in the POS Hub menu.
parentMenuModifierGroupId	The parent modifier’s modifier group id in the POS Hub menu.

Only include parentMenuModifierId and parentMenuModifierGroupId when the modifier is nested.

Example — nested modifier after a top-level modifier:

[
  {
    "quantity": 1,
    "name": "New York Style Pizza",
    "partnerId": "1ef670db-4989-4b94-948b-822f08a3fe63",
    "customerNotes": "16 inch size unavailable.",
    "options": [
      {
        "name": "----Whole----",
        "quantity": 1,
        "partnerId": "be36d841-bf4e-4f64-a15e-7c0e332879b1",
        "menuModifierGroupId": "c0655be9-29d8-468a-8dfe-47524a065e98",
        "price": 0
      },
      {
        "name": "PLAIN",
        "quantity": 1,
        "partnerId": "2ba9f742-4804-499c-8b15-afe1fcb0ed84",
        "menuModifierGroupId": "8d47288b-76b4-4c3d-8d53-a67422f7a2d8",
        "parentMenuModifierId": "be36d841-bf4e-4f64-a15e-7c0e332879b1",
        "parentMenuModifierGroupId": "c0655be9-29d8-468a-8dfe-47524a065e98",
        "price": 0
      }
    ],
    "price": 1800,
    "menuCategoryId": "cf1c2947-1969-47ea-ad7b-dcc98cebc69f"
  }
]

---

5. Catalog-based order injection

If the marketplace consumes the catalog (not the menu) for products and modifiers, use POS references from the catalog instead of menu partnerId / menuCategoryId.

5a. Line items (products)

For each line item, send:

Field	Meaning
posReference	The product posReference in the catalog.
parentPosReference	The category posReference for that product in the catalog.

Example:

"items": [
  {
    "customerNotes": "Light lettuce, no tomato/onions. Bread scooped, cut in 4.",
    "name": "CHICKEN SALAD",
    "options": [],
    "parentPosReference": "830e2520-dd28-4d40-bea9-21e3e56bda03",
    "posReference": "0aed7d3e-3c10-48af-96c2-b0d99f7b32b5",
    "price": 1000,
    "quantity": 1,
    "taxRateIds": []
  }
]

5b. Modifiers

For each modifier in options, send:

Field	Meaning
posReference	The modifier posReference in the catalog.
parentPosReference	The modifier group posReference in the catalog.

Example:

[
  {
    "containsAlcohol": false,
    "containsTobacco": false,
    "customerNotes": "16 inch size unavailable.",
    "name": "New York Style Pizza",
    "options": [
      {
        "modifierGroupName": "Pizza Toppings",
        "name": "----Whole----",
        "parentPosReference": "d0c945d0-3072-41bd-a312-e3f41663cb48",
        "posReference": "db88c1f9-aea6-4e1f-a551-b1a5edfdb13a",
        "price": 0,
        "quantity": 1,
        "taxRateIds": []
      }
    ],
    "parentPosReference": "84c683a7-6eb9-4384-8f07-52fac72169b4",
    "posReference": "d1676031-0856-4134-8f2d-b0ef93b3433b",
    "price": 1800,
    "quantity": 1,
    "taxRateIds": []
  }
]

5c. Nested modifiers

For a nested modifier, still send posReference and parentPosReference for the nested modifier’s group and modifier, and add:

Field	Meaning
parentModifierPosReference	The parent modifier’s posReference in the catalog.
parentModifierGroupPosReference	The parent modifier’s modifier group posReference in the catalog.

Only include these when the modifier is nested.

Example:

[
  {
    "containsAlcohol": false,
    "containsTobacco": false,
    "customerNotes": "16 inch size unavailable.",
    "name": "New York Style Pizza",
    "options": [
      {
        "modifierGroupName": "Pizza Toppings",
        "name": "----Whole----",
        "parentPosReference": "d0c945d0-3072-41bd-a312-e3f41663cb48",
        "posReference": "db88c1f9-aea6-4e1f-a551-b1a5edfdb13a",
        "price": 0,
        "quantity": 1,
        "taxRateIds": []
      },
      {
        "name": "PLAIN",
        "parentModifierGroupPosReference": "d0c945d0-3072-41bd-a312-e3f41663cb48",
        "parentModifierPosReference": "db88c1f9-aea6-4e1f-a551-b1a5edfdb13a",
        "parentPosReference": "66863608-bc99-4b6b-803c-f1a4bba508d0",
        "posReference": "e996557c-13e2-475a-be61-7067327c55cf",
        "price": 0,
        "quantity": 1,
        "taxRateIds": []
      }
    ],
    "parentPosReference": "84c683a7-6eb9-4384-8f07-52fac72169b4",
    "posReference": "d1676031-0856-4134-8f2d-b0ef93b3433b",
    "price": 1800,
    "quantity": 1,
    "taxRateIds": []
  }
]

---

Quick reference

You use	Line item	Modifier	Nested modifier (extra fields)
Menu	partnerId + menuCategoryId	partnerId + menuModifierGroupId	parentMenuModifierId + parentMenuModifierGroupId
Catalog	posReference + parentPosReference (category)	posReference + parentPosReference (modifier group)	parentModifierPosReference + parentModifierGroupPosReference

Always validate your payloads against the create order schema for your environment (see section 1).