This guide explains how to configure your Square POS menu so that every order Supy receives from Square can be accurately matched to your recipes and inventory. Following these guidelines ensures that your stock levels are always correct, your cost reporting is reliable, and your team can work without manual adjustments.
Please read this document carefully before making changes to your Square catalog. If you have any questions, your Supy onboarding team is available to support you.
When a customer places an order through Square, Supy receives the full details of that order: the item sold, the variation chosen (e.g., Hot or Iced), and any modifiers selected (e.g., milk type, number of shots, add-ons). Supy then uses this information to determine exactly which ingredients were consumed and deducts them from your inventory automatically.
To do this correctly, Supy uses a POS Item recipe plus modifier recipes model. Here is how it works:
The POS Item Recipe + Modifier Recipes Model
Every drink or dish in Supy has one Item Recipe. This contains the common ingredients shared by all versions of that item — for example, the cup or any ingredient that is always present.
Variable components — such as milk type, milk volume, bean type, or number of shots — each have their own separate Modifier Recipe in Supy.
When an order arrives, Supy loads the Item Recipe and then attaches the relevant Modifier Recipes based on the variation and modifiers selected in Square. The total inventory deduction equals the sum of all recipes combined.
This model gives Supy the precision to track every ingredient accurately — but it only works when your Square POS is structured so that Supy can correctly read and map each modifier to the right Modifier Recipe.
To make this concrete, here is how a Latte would be structured in both Supy and Square POS.
In Supy, the Latte uses one Item Recipe for its common ingredients, plus a separate Modifier Recipe for each variable component:
Recipe Name | What it represents | Recipe Type |
Imagine a customer orders: Hot Latte, 2 Shots, Skim 150ml, Arabica, Vanilla Syrup
Supy will automatically:
Load the Item Recipe: LATTE_BASE (common latte ingredients)
Attach LATTE_BEANS_2_SHOTS (based on the '2 Shots' modifier)
Attach SKIM_150ML (based on the 'Skim 150ml' modifier)
Attach ARABICA_BEANS (based on the 'Arabica' modifier)
Attach SYRUP_VANILLA (based on the 'Vanilla Syrup' modifier)
The inventory deduction will be the total of all five recipes combined — automatically, in real time.
For the above to work, your Square POS catalog must be set up in a specific way. There are five key requirements.
Every drink item must include a Variation that reflects the core version of the product — typically the serving temperature (Hot / Iced) or size (Small / Medium / Large) where applicable. This allows Supy to load the correct Item Recipe for each order.
Example — Latte Variations
Item: Latte
Variations: Hot, IcedThis is the most important rule. Every modifier option in Square must correspond to exactly one Modifier Recipe in Supy. A modifier must not combine two separate inventory concepts into one option.
Modifier List: Beans Shot Count > 1 Shot → maps to LATTE_BEANS_1_SHOT > 2 Shots → maps to LATTE_BEANS_2_SHOTS
> Skim 100ml → maps to SKIM_100ML > Skim 150ml → maps to SKIM_150ML | ✘ Incorrect — Combined modifiers Modifier: 'Arabica Double Skim Latte' (Combines bean type, shot count, and milk into a single modifier. Supy cannot map this to a single recipe.) Modifier: 'Large Milk' (Ambiguous — which milk? What volume?) |
If the type and quantity of an ingredient are both variable (e.g., milk type AND milk volume), each combination must be its own modifier option. Do not create a modifier for 'milk type' and a separate modifier for 'volume' unless each combination is already a unique recipe in Supy.
For example, if you have Skim Milk and Soy Milk, each available in 100ml or 150ml, the four modifiers should be: Skim 100ml, Skim 150ml, Soy 100ml, Soy 150ml — because each maps to its own recipe.
Consistent naming makes the integration reliable and easy to maintain. Please follow these guidelines when naming your Square items, variations, and modifiers.
Element | Convention | Examples |
Modifier List: Milk > Full Cream 150ml > Full Cream 200ml > Skim 150ml > Skim 200ml > Soy 150ml > Soy 200ml > Oat 150ml > Oat 200ml Each option = one unique Supy recipe. | ✘ Incorrect Modifier List: Milk Type > Full Cream > Skim > Soy > Oat Modifier List: Milk Size > 150ml > 200ml Supy cannot combine two modifiers to find one recipe. |
Modifier List: Beans Shot Count > 1 Shot > 2 Shots > Extra Shot Modifier List: Bean Type > Arabica > Robusta > Liberica | ✘ Incorrect Modifier List: Coffee > Single Arabica > Double Arabica > Single Robusta > Double Robusta Combining bean type + shot count into |
Below is the full recommended structure for a Latte item in Square. Use this as your reference template when configuring other items.
Square POS Element | Value/Options | Supy Mapping |
Where size is a factor in your menu, Supy uses a Variant + Modifier concatenation model to determine the correct recipe mapping. This section explains how this works and why your Square POS must be configured in a specific way to support it.
Size (Small, Medium, Large) must be configured as a Variant in Square — not as a modifier. This is because each size creates a distinct sellable item in Square that Supy maps to its own base recipe. If size is set up as a modifier instead, Supy cannot correctly identify which base recipe to load, and the entire mapping breaks down.
When size is correctly set up as Variants, Square produces three distinct items:
Square Item + Variant | Supy Base Recipe | What It Contains |
After loading the base recipe, Supy reads the modifiers selected on the order and concatenates each modifier with the size variant to find the correct modifier recipe. This is necessary because the same modifier (e.g., Soy milk) has a different volume depending on the size — and therefore maps to a different recipe with a different inventory deduction.
Concatenation Logic — Example
Order: Latte Large, Soy Milk
Supy reads: Item = Latte | Variant = Large | Modifier = Soy
Concatenates: Soy <> Latte Large
Maps to: Soy Large Milk RecipeOrder: Latte Medium, Soy Milk
Concatenates: Soy <> Latte Medium → Maps to: Soy Medium Milk RecipeOrder: Latte Small, Oat Milk
Concatenates: Oat <> Latte Small → Maps to: Oat Small Milk Recipe
For every order received from Square, Supy follows this sequence:
Step | What Supy Does |
To ensure the concatenation model works reliably, the following rules must be followed in Square:
Size configured as Variants (Small / Medium / Large) — not as modifiers Each modifier represents one logical concept only (milk type, bean type, or a single add-on) Variant and modifier names are stable and agreed with Supy before go-live Any name change in Square is communicated to Supy immediately | ✘ Will Break the Mapping Size set up as a modifier option Free-text or inconsistently named modifier options |
For Supy to initiate the concatenation process, it must have access to your Square menu items — not just your sales data. This is because Supy needs to read the full structure of your catalog (items, variants, and modifiers) in order to correctly identify the size variant on each order and build the concatenated key that maps to the right recipe.
In practical terms, this means:
What Supy Needs from Square
Read access to your Square menu items and catalog structure
This allows Supy to:
• Identify each item and its associated variants (e.g., Latte Small / Medium / Large)
• Recognise the size variant on incoming sales orders
• Initiate the Variant + Modifier concatenation to find the correct modifier recipe
• Sync both your sales data and menu structure simultaneously
Without access to menu items, Supy can receive sales but cannot perform concatenation — meaning modifier recipes will not be attached and inventory deductions will be incomplete.
Your Supy onboarding team will request the necessary permissions during the integration setup. Please ensure that menu item access is granted alongside sales data access so that both can be synced correctly from day one.
