Early access request — nested modifiers via Catalog API

Questions
,
1

Following up on the nested modifiers beta discussion from 5 August.

We run a cafe on Square for Restaurants (Full service) and are building a customer ordering app against the Catalog and Orders APIs. We have the nested modifier beta enabled on the seller side - “Add nested modifier set” appears in the modifier editor in our dashboard - but as I understand it the parent-child relationship is still not exposed through the Catalog API.

That distinction matters for us. We are midway through consolidating our modifier structure from 51 sets down to about 17, and nesting is the correct answer for one problem we cannot solve any other way: our deal drink size upcharge differs per drink. A large long black is +$0.50, a large flat white is +$0.60, and a large matcha latte is +$1.00. Flat modifier sets force us either to enumerate every drink-and-size combination as its own option, or to accept a flat size price that is wrong on several drinks.

We can build it nested today for the register, but our own app reads the Catalog API. If the app cannot see the nested children, it will price an order without them, Square will price the order with them, and CreatePayment will be refused on the amount mismatch - which means declined cards for real customers.

Could we be enabled for early access to nested modifiers via the Catalog API?

Application ID: sq0idp-IDFCg17-Ly5Z0m2yssnm8g

Three questions if possible:

1. Where is the parent-child relationship represented in the Catalog API response - is it a field on CatalogModifierList, on CatalogItemModifierListInfo, or somewhere else?

2. When creating an order, should parent and child modifiers both be sent as regular line-item modifiers, or is there a separate structure?

3. Is the seller-side beta enabled independently of API access, or does API access follow automatically once granted?

Thanks very much.

4

@Fernside I’ve submitted your information for approval. Once it’s approved, I’ll share answers to your questions and any documentation.

5

Thank you so much
Looking forward to hearing back from you

6

Hi @Fernside - apologies for the mixup - Nested Modifiers was just released for public beta access yesterday! Documentation is available here, and the API changelog is here.

7

Thanks @jseok — good timing on our part, no apology needed.

I’ve read the Manage Nested Modifiers page and child_modifier_list_ids answers my first question cleanly. include_options looks like exactly what our app needs for rebuilding the menu in one call.

The one thing I couldn’t find is the order side. When creating an order, are parent and child modifiers both sent as ordinary entries in line_items.modifiers, or is there a separate structure for children? And does Square reject the order if a required child set wasn’t answered?

Asking because if our app prices an order differently to how Square prices it, CreatePayment fails on the amount mismatch and a real customer’s card gets declined. Would rather get this right before we build it.

Thanks again.

Kind Regards,
Nick Maglis
Fernside Coffee Shoppe
401B Cleveland St, Redfern NSW 2016
Ph: 0481374463

8

Hi Nick - We recommend that you send parent and child modifiers as entries in the same line_items[].modifiers[] array. Give each modifier a unique order-scoped uid, then set the child’s parent_modifier_uid to the parent’s uid. Here’s a sample modifiers object:

"modifiers": [
    {
        "uid": "protein-1",
        "catalog_object_id": "STEAK_MODIFIER_ID",
        "quantity": "1"
    },
    {
        "uid": "sauce-1",
        "catalog_object_id": "SALSA_MODIFIER_ID",
        "quantity": "1",
        "parent_modifier_uid": "protein-1"
    }
]

See OrderLineItemModifier.parent_modifier_uid ( OrderLineItemModifier Object - Square API Reference ) for the order-side relationship. I’ll also following up internally to make this request structure clearer in the nested modifiers documentation.