Clarification on optionGroupPricingMode enum values, menu builder configuration, and undocumented price fields (menuItemPrice, receiptLinePrice) on LoyaltyTransaction.Selection

Audience: Toast Developer Relations / Menus team / Loyalty Integration team

Context

Olo  Loyalty(Formerly Spendgo) Integration with Toast POSconsumes LOYALTY_ACCRUE callbacks. While investing some production issues related to item/modifier prices, item/modifier quantities, two open questions emerged from comparing real production payloads against the published Selection schemas:

1. The full meaning of each value of optionGroupPricingMode and how to produce orders that exercise each one.
2. The semantics and stability of menuItemPrice and receiptLinePrice on Loyalty Integration callback selections, both of which appear in payloads but are not declared in the Loyalty LoyaltyTransaction.Selection schema.

Reference URLs:

• Orders API Selection schema: https://doc.toasttab.com/openapi/orders/tag/Data-definitions/schema/Selection/

• Loyalty Integration LoyaltyTransaction schema: https://doc.toasttab.com/openapi/loyalty/tag/Data-definitions/schema/LoyaltyTransaction/

   

Section A — optionGroupPricingMode

The Orders API Selection schema declares optionGroupPricingMode as an enum with values:

INCLUDED

FIXED_PRICE

ADJUSTS_PRICE

REPLACES_PRICE

LOCATION_SPECIFIC_PRICE

Questions:

A1. Menu builder source. Which Toast Web menu builder setting drives each value? We assume the modifier group "Pricing strategy" / "Pricing mode" controls, but want to confirm the exact UI path (Menus → Modifier Groups → … or Menu Items → Modifier Group settings).

A2. Multi‑mode parents. Can a single menu item carry multiple modifier groups with different optionGroupPricingMode values simultaneously (e.g., one INCLUDED group and one ADJUSTS_PRICE group)? If yes, how does each contribute to the parent Selection's preDiscountPrice?

A3. Example Request. Is there a sandbox restaurant or sample menu configuration that already exercises all five modes that we can use as a reference? If not, can Developer Relations provide step‑by‑step menu builder instructions to set up at least one item per mode in our sandbox?

A4. REPLACES_PRICE parent‑side semantics. When a modifier REPLACES_PRICE:

• Does the parent item Selection's preDiscountPrice reflect the replacement value, or the original menu base?
• Is the original menu base preserved anywhere in the order payload for audit (e.g., on the parent's menuItemPrice)?
• In a check‑level appliedDiscounts scenario combined with REPLACES_PRICE, which value does the discount apply to?

A5. LOCATION_SPECIFIC_PRICE resolution. Is the resolved per‑location price already expressed in preDiscountPrice / receiptLinePrice on the order/loyalty callback, or do consumers need to look it up via the Menus API at the order's locationGuid? Where does the resolved price live in the callback payload?

Section B — menuItemPrice and receiptLinePrice on LoyaltyTransaction.Selection

In production LOYALTY_ACCRUE callbacks we observe both menuItemPrice and receiptLinePrice on every Selection (top item and nested modifiers). However:

• The Loyalty Integration LoyaltyTransaction.Selection schema documents neither menuItemPrice nor receiptLinePrice (only preDiscountPrice, price, tax, quantity, displayName, item, modifiers[], appliedDiscounts[], appliedTaxes[], etc.).
• The Orders API Selection schema documents receiptLinePrice (with the relationship preDiscountPrice = receiptLinePrice × quantity) but not menuItemPrice.

Questions:

B1. menuItemPrice definition. What does menuItemPrice represent on a Selection?

• Per‑instance own contribution (excluding any rolled‑up child modifier prices)?
• Per‑instance menu list price (pre mode resolution)?
• Per‑instance effective price (post mode resolution)?
• Pre‑discount or post‑discount?

B2. menuItemPrice × optionGroupPricingMode. How is menuItemPrice populated in each pricing mode?

• INCLUDED → does menuItemPrice = 0?
• FIXED_PRICE → does it equal the configured fixed price?
• ADJUSTS_PRICE → does it equal the modifier's own adjustment, or the rolled‑up amount?
• REPLACES_PRICE on the parent — does the parent's menuItemPrice carry the original menu base, or the replaced value, or 0?
• LOCATION_SPECIFIC_PRICE → is it the resolved per‑location price?

B3. Relationships among price fields. Please confirm or correct the relationships at a single Selection node:

• preDiscountPrice = receiptLinePrice × quantity — confirmed in Orders API; does the same identity hold on Loyalty callbacks?
• menuItemPrice vs receiptLinePrice at the same node — is menuItemPrice the per‑instance own contribution and receiptLinePrice the per‑instance rolled‑up total? Is there a documented identity such as receiptLinePrice = menuItemPrice + Σ (per_parent_count(child) × receiptLinePrice(child))?
• For modifiers, is quantity an absolute count (i.e. parent_qty × per_parent_count) or a per‑parent ratio?

B4. Documentation gap. Why are menuItemPrice and receiptLinePrice absent from the Loyalty Integration LoyaltyTransaction.Selection schema while present in production payloads? Is there a plan to add them, and on what timeline?

B5. Stability commitment. Can iwe rely on menuItemPrice (and receiptLinePrice on Loyalty callbacks) continuing to be present with the documented semantics? Are these considered:

• Stable, just not yet documented (will be added soon)?
• Internal/experimental and subject to removal or change without notice?
• Conditionally present (some restaurants / menu configurations only)?

B6. Recommended field for partner integrations. Given that we need per‑instance cost — for both line subtotals and per‑modifier reward targeting — which single field does Toast recommend reading?

• In Loyalty Integration callbacks?
• In Orders API GET responses?
• Is the recommendation different between the two surfaces?

B7. Example payloads. Could Toast share at least one fully populated sandbox LOYALTY_ACCRUE payload covering each optionGroupPricingMode value, including menuItemPrice, receiptLinePrice, preDiscountPrice, and quantity on every Selection (item + modifiers + nested leaves)? This would let us verify their per‑mode cost extraction without having to set up each menu permutation themselves.