I am trying to create a PHP web app that will read my catalog, but it seems to be missing some data points. When I use the API Explorer to query the catalog, the JSON returned includes a few “ecom_*” elements in the CatalogObject::itemData property. When I try to output that using print json_encode($api_response->getResult()); it doesn’t include those json elements. And I can’t tell from the square/src directory where those might be coming from. This is my require from the composer.json "square/square": "10.0.0.20210421",, so it looks like the latest version of the SDK. Any suggestions?
Hi @gemcityjunction welcome to the forums!
Technically speaking these fields aren’t really meant to be used (they’re not documented in our public tech ref either), so they aren’t returned in the SDKs. There’s no guarantee that they will continue being returned in the REST API either, so I would not rely on them.
So then is there a way that I can determine if an item is available online? The way that I had to create my menu I have duplicate items…one is available online, the other is not. If I want to just look for items that are available online what would I query or validate is there? The availableOnline property is not visible in the JSON. I have an am using the SDK, so I can go either route.
The available_online attribute is solely referring to the Square Online store, and if the item is available to be purchased “online” (versus available_for_pickup for example). Are you specifically trying to find if the item is on Square Online? Or what exactly do you mean by “available online”?
I’m wanting to know if something is available in my Square Online store. I know there are 4 options to make it available (shipping, pickup, delivery, self-service order). And then there is the “visibility” attribute? So how would I find out what the status of each of these parameters is? I would prefer through the SDK.
Can you share an item where you’re not seeing available_online? This is a documented field, and should be returned (if it was set in Square Online). You cannot set this field, though, it’s read-only as far as I know.
I don’t see the available_online JSON attribute in any of my items. Below is one example item directly from my catalog. There are 3 methods in the SDK in the CatalogItem class, but I’m unclear as to what they represent. getAvailableOnline(), getAvailableForPickup(), & getAvailableElectronically(). Looking at the docblock comments, they appear to represent something different than I would think.
Where would available_online be set in the Square Online store? I can check to see if it’s set.
{
"type": "ITEM",
"id": "GOR32BPOVILDUMM7FVLVLJD3",
"updated_at": "2021-04-23T22:09:28.84Z",
"version": 1619215768840,
"is_deleted": false,
"present_at_all_locations": true,
"image_id": "WGGIPXFFSKHQMQSRFNEMT7E4",
"item_data": {
"name": "Mocha",
"description": "Espresso + Chocolate + Milk",
"abbreviation": "M",
"label_color": "b21212",
"visibility": "PRIVATE",
"category_id": "KS7G3HZT2RWIT2SXX6AQB3XM",
"tax_ids": [
"3LTAEIYGLE5LWU4YBIPJ5GOH"
],
"modifier_list_info": [
{
"modifier_list_id": "CFH2RESTB5C3HKKKZQCFM32K",
"modifier_overrides": [
{
"modifier_id": "3JOKBXQQDBWRY3A24X4TLXID",
"on_by_default": true
}
],
"min_selected_modifiers": 1,
"max_selected_modifiers": 1,
"enabled": true
},
{
"modifier_list_id": "5WJYNO7GBCILB467Q2JRLFXP",
"min_selected_modifiers": -1,
"max_selected_modifiers": -1,
"enabled": true
},
{
"modifier_list_id": "IPCHYCPPUIXCM3SUBMFJX3SH",
"min_selected_modifiers": 0,
"max_selected_modifiers": 5,
"enabled": true
},
{
"modifier_list_id": "WLQ6DA3IZHMP65GZ4CTMPTNM",
"min_selected_modifiers": -1,
"max_selected_modifiers": -1,
"enabled": true
},
{
"modifier_list_id": "FKUY7FZIT73MTDSUU6A5H6UV",
"min_selected_modifiers": 0,
"max_selected_modifiers": 1,
"enabled": true
},
{
"modifier_list_id": "N4QFWO57RTQJGKLCGZXE4IEU",
"min_selected_modifiers": -1,
"max_selected_modifiers": -1,
"enabled": true
}
],
"variations": [
{
"type": "ITEM_VARIATION",
"id": "EBQJA2NIU2C6S6AGNZNE7UQ3",
"updated_at": "2021-04-22T15:29:56.416Z",
"version": 1619105396416,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "GOR32BPOVILDUMM7FVLVLJD3",
"name": "Small",
"ordinal": 0,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 300,
"currency": "USD"
},
"item_option_values": [
{
"item_option_id": "ZATGAIJG7VG5QCVIFBIY44XD",
"item_option_value_id": "SCEXXOVCQV3W5CY7YDGOPGVO"
}
]
}
},
{
"type": "ITEM_VARIATION",
"id": "7PE4MVNUD2HUGEAUG7RDXBOR",
"updated_at": "2021-04-22T15:29:56.416Z",
"version": 1619105396416,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "GOR32BPOVILDUMM7FVLVLJD3",
"name": "Medium",
"ordinal": 1,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 350,
"currency": "USD"
},
"item_option_values": [
{
"item_option_id": "ZATGAIJG7VG5QCVIFBIY44XD",
"item_option_value_id": "T2ZGSXOOMGTTUCENNOPCMMJK"
}
]
}
},
{
"type": "ITEM_VARIATION",
"id": "MSXSEGP4RW6EI2O6F2AAXDQX",
"updated_at": "2021-04-22T15:29:56.416Z",
"version": 1619105396416,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "GOR32BPOVILDUMM7FVLVLJD3",
"name": "Large",
"ordinal": 2,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 400,
"currency": "USD"
},
"item_option_values": [
{
"item_option_id": "ZATGAIJG7VG5QCVIFBIY44XD",
"item_option_value_id": "NRU3RAV2PVRO3XEZYAXDJUXU"
}
]
}
}
],
"product_type": "REGULAR",
"skip_modifier_screen": false,
"item_options": [
{
"item_option_id": "ZATGAIJG7VG5QCVIFBIY44XD"
}
],
"ecom_uri": "https://gemcityjunction.square.site/product/mocha/180",
"ecom_image_uris": [
"https://gemcityjunction.square.site/uploads/1/3/6/6/136664970/s459591996224995529_p180_i1_w2534.jpeg"
],
"ecom_available": true,
"ecom_visibility": "VISIBLE",
"legacy_tax_ids": [
"3LTAEIYGLE5LWU4YBIPJ5GOH"
]
}
},
To make sure things are understood. I have a coffee shop and because I can’t “hide” a variation/option I had to make a duplicate item (I have a “travel” mug size option that I provide a discount on, but I don’t want people ordering online to select that so I have to create a second item without that size option). Through the SDK, I ran a retrieveCatalogObject() to find out the specifics of two such items as I explained above. Both objects return a false in the availableOnline class property. Looking at those exact same items on the API Explorer’s JSON return…one returns "ecom_available": true, the other returns "ecom_available": false. So this tells me that the ecom_* are accurate, but as you say, not documented so they shouldn’t be relied on. So it looks like the SDK doesn’t have the data I’m looking for…can you confirm that? It also appears that the SDK and API Explorer are operating on different code since everything I can find, “ecom_*” are no where in the code, so I can’t tell where they are coming from.
Apologies for the delay here. So I checked in with the team, and it sounds like available_online was used on older instances of Square Online, so there’s actually not a great way to do it currently. The ecom fields are up to date and correct, but as mentioned, they are not guaranteed to stay.
Can you clarify your use-case a bit? What are you meaning by wanting to hide a duplicate item? Trying to understand better so I can offer an alternative solution besides these fields, if possible. For example, you could put these items under a special category that you do not show on your online store.
My use case is that I have a small coffee shop. We offer a “travel” mug size and customers get 50% off select drinks after purchasing a refillable mug. I don’t want them to be able to select that size when ordering online. I was told that the only way is to create a duplicate item because you can’t hide a size/option/variation online. So I created a duplicate item and deleted that “travel” size from it and enable it for online sale. The item with the “travel” size is not available for purchase online. So what I need to find out is how can I tell if an item is the former or latter? I can’t just look to see if it has the travel size in it because there are other drinks that don’t have it either.
By online, you’re referring to “Square Online Store”, is that correct, and not a custom website? I’m not very familiar with the settings on Square Online Stores, just to be clear, so I’m not familiar with this duplication method (we mainly help with APIs and SDKs here).
It sounds like if you have two items, one with a “travel” and one without "travel, that you would need to enable some extra logic to find out what you’re looking for. It sounds like you could use two different categories to distinguish the two items (one called “Mugs” and the other “Mugs Online” or something to that effect). Then, in the Catalog API, you can search for items with that specific category_id so you know if it’s an online version or not. Alternatively, if you give the “travel” mug a specific identifier (like a sku) that would be different, you could also search explicitly for that.
Yes, the Square Online/Webly store. If you’re “not familiar with this duplication method”, do you know another method for doing what I want to do? Or is there somebody else that can help me do what I want to do? The category method might work. The SKUs are applied at the variation level, not the item level, so I would still have to loop through all the variations to see if the “travel” variation is applied. Like I said above, while that would technically work, that increase complexity a ton!
Since you help with API and SDK (that’s all I have been asking for help with), can you tell me why the difference in the outputs? And why getAvailableOnline() doesn’t work?
The available_online (which getAvailableOnline() returns), uses a legacy Square Online field, as mentioned above, so it’s no longer accurate for modern Square Online Stores. I apologize for the confusion on this.
I’m not sure I understand your SKU logic. If you know the SKU of the variation with the “travel”, then you can simply look it up (search by sku) and do whatever you need to do with it. Presumably the sku would only return one single object if you’re not re-using the skus for the different mugs (or whatever other items).
If I’m still following correctly, then basically, to do what you want to do, you need to make the two variations appear distinct so you can find it. You have several options which I’ve shared, but this logic is more on your side, rather than Square’s side, since it’s up to you on how you want to make them distinct.
- Use distinct SKUs so you can search and find whatever particular variation you want
- Use a category that holds “online” vs “in store”
- Use your own database with your own identifier, and link it to Square’s
catalog_object_id. - Give it a distinct name (and search by the name instead of the SKU)
There’s probably a few other options, but just thinking out loud of the possibilities. Ultimately it boils down to making them distinct in some way, or else you’d never be able to tell them apart in the API, as you mentioned.