How can we identify the ONLINE items

Questions
1

We are building the Square menu sync system that merchant clients are able to imported items from their Square account to our system. There is an important feature that lots of merchants want to have: import the either only ONLINE items or POS items from Square.

Some merchants want only to import the ONLINE items, which are shown on their Square online store, to our system while some want to import POS item only. Currently, although we cannot find any official documentation for it, we found the field ecom_visibility in the response of retrieve catalog API. We will regard it as an online item if it’s ecom_visibility is not UNINDEXED However, as reported from our tester, this field doesn’t describe the identification of a Square item. If the item was put into Square online store and later got removed, its ecom_visibility won’t be reset to
UNINDEXED.

In summary, we have 2 questions about the online item.

  1. does Square provide an official way to help developer to identify the ONLINE item?
  2. if Square doesn’t, can we use the ecom_visibility to locate its source? Does the mechanism I mentioned above of changing ecom_visibility value have a bug?

Looking forward to your reply, lots of merchant clients are waiting for it.

2

You are correct. Those fields aren’t documented and we don’t recommend using them at this time. You can use the available_online boolean to determine if its available or not online. Otherwise the items will be available on the POS if they’re enabled for the location the sellers logged into. For that you’ll use the present_at_all_locations boolean and absent_at_location_ids array to determine where it’s available. :slightly_smiling_face:

3

Thanks for the reply. We checked the data again but found the available_online may not be a good indicator, for example, the following item: Spring Special Lattes - Iced is shown on the Square online store: Jaho Coffee Online Order | Jaho Coffee Roaster

And we use the API to get the item details:

Item id: HTYV2ME2KOFCANVFVEJAPZTL

Request:

curl https://connect.squareup.com/v2/catalog/object/HTYV2ME2KOFCANVFVEJAPZTL?include_related_objects=false \
  -H 'Square-Version: 2023-01-19' \
  -H 'Authorization: Bearer xxxxxxxxxxx' \
  -H 'Content-Type: application/json'

Response:

{
  "object": {
    "type": "ITEM",
    "id": "HTYV2ME2KOFCANVFVEJAPZTL",
    "updated_at": "2023-03-02T23:55:02.591Z",
    "created_at": "2022-08-01T00:27:11.891Z",
    "version": 1677801302591,
    "is_deleted": false,
    "present_at_all_locations": true,
    "absent_at_location_ids": [
      "9DXE3H5GP2BXG",
      "Y42RB2MTVM2F8"
    ],
    "item_data": {
      "name": "Spring Special Lattes - Iced",
      "description": "Our baristas' favorite creations for the spring. Bring one with you to the park and watch the world come alive.",
      "is_taxable": true,
      "visibility": "PUBLIC",
      "available_online": false,
      "available_for_pickup": true,
      "available_electronically": false,
      "category_id": "TKUP4LCSBOOJPVNDEQW7OQZB",
      "ordinal": 0,
      "tax_ids": [
        "D5WEG72MUEZD6MMBPNS6FND6"
      ],
      "modifier_list_info": [
        {
          "modifier_list_id": "AETZ2GICSPMYYZOOE234BHRK",
          "min_selected_modifiers": -1,
          "max_selected_modifiers": -1,
          "enabled": true
        },
        {
          "modifier_list_id": "2EIX4QNODTENOFZUQRYOCHPY",
          "min_selected_modifiers": -1,
          "max_selected_modifiers": -1,
          "enabled": true
        },
        {
          "modifier_list_id": "JBKAX2KF2GNM6RQZ35RJ6IUV",
          "min_selected_modifiers": -1,
          "max_selected_modifiers": -1,
          "enabled": true
        }
      ],
      "variations": [
        {
          "type": "ITEM_VARIATION",
          "id": "UXSLKRQICXCWOSS5LGR7EKXE",
          "updated_at": "2022-12-12T21:30:04.673Z",
          "created_at": "2022-08-01T00:27:11.891Z",
          "version": 1670880604673,
          "is_deleted": false,
          "present_at_all_locations": true,
          "absent_at_location_ids": [
            "Y42RB2MTVM2F8",
            "9DXE3H5GP2BXG"
          ],
          "item_variation_data": {
            "item_id": "HTYV2ME2KOFCANVFVEJAPZTL",
            "name": "Iced",
            "ordinal": 1,
            "pricing_type": "FIXED_PRICING",
            "price_money": {
              "amount": 631,
              "currency": "USD"
            },
            "location_overrides": [
              {
                "location_id": "396HQJE1K93PG",
                "track_inventory": false
              },
              {
                "location_id": "3WQT43K77CJF8",
                "track_inventory": false
              },
              {
                "location_id": "5BZMEPGNJ8FQC",
                "track_inventory": false
              },
              {
                "location_id": "7MCQH41Y5H312",
                "track_inventory": false
              },
              {
                "location_id": "88QR6KCSFZJWE",
                "track_inventory": false
              },
              {
                "location_id": "9DXE3H5GP2BXG",
                "track_inventory": false
              },
              {
                "location_id": "E32R67V069VFF",
                "track_inventory": false
              },
              {
                "location_id": "K3RATB32V17N1",
                "track_inventory": false
              },
              {
                "location_id": "KYG4ZQR38SSCN",
                "track_inventory": false
              },
              {
                "location_id": "L3WA2TYHSR32J",
                "track_inventory": false
              },
              {
                "location_id": "L59NJ1CZ367MR",
                "track_inventory": false
              },
              {
                "location_id": "SR331BT08F6BK",
                "track_inventory": false
              },
              {
                "location_id": "Y42RB2MTVM2F8",
                "track_inventory": false
              }
            ],
            "sellable": true,
            "stockable": true
          }
        }
      ],
      "product_type": "REGULAR",
      "skip_modifier_screen": false,
      "ecom_uri": "https://jahocoffee.square.site/product/spring-special-lattes-iced/242",
      "ecom_image_uris": [
        "https://jahocoffee.square.site/uploads/1/3/1/5/131578632/s944915267996823260_p242_i1_w1700.png"
      ],
      "ecom_available": true,
      "ecom_visibility": "VISIBLE",
      "image_ids": [
        "3X6PMTDHQJ26YA4F3GMSRTO7"
      ],
      "pickup_fulfillment_preferences_id": "fprefs_127edy7jnpi0t01iyrb84b3nt",
      "delivery_fulfillment_preferences_id": "fprefs_127itf4a6ypg8gktnv8qxdkal",
      "description_html": "<p>Our baristas&#39; favorite creations for the spring. Bring one with you to the park and watch the world come alive.</p>",
      "description_plaintext": "Our baristas' favorite creations for the spring. Bring one with you to the park and watch the world come alive."
    }
  }
}

As we can see from the response, the online item has the available_online equal to false.

4

Is there any update about it? Thank you in advance.

5

I’m checking with the team on this. :slightly_smiling_face:

1 Like
6

Okay, heard back from the team and available_online isn’t for the Square Online Store. There really isn’t a documented way to know what items are on the sellers online store that we can recommend using at this time. The team is looking to improve this. As you mentioned ecom_visibility is returned in the response. You can read from that at this time however it’s not documented. :slightly_smiling_face:

7

But the ecom_visibility has the issue I mentioned:

If the item was put into Square online store and later got removed, its ecom_visibility won’t be reset to UNINDEXED, it remains the same. Is it a bug?

9

As I mentioned on the above, ss it a bug and do you have a roadmap to fix it?

10

Since this field is undocumented I’m not able to share how its used. Unfortunately, we don’t have a public roadmap for this field and its behavior. The team is looking to improve this. :slightly_smiling_face:

11

I’m having a similar issue here. My customer wants to pull all the items currently on their online store into their own website, instead of a separate square site. Ideally this should be pretty simple using the catalog api to filter by the Online Availability. However every single item returned in the api has available_online: false even though I can see in the account that there are some items marked as Visible online.

I would prefer to not introduce the use of custom attributes for this because it will interrupt the customers workflow of publishing. Sometimes it’s hard to teach an old dog new tricks :slight_smile:

Is there any reliable way to fetch only the items/variations published on the Square site?

1 Like
12

At this time there isn’t a way to identify online store items with the Catalog API. :slightly_smiling_face:

13

Thanks Byran. This seems like pretty lacking functionality for an e-commerce SAAS platform. I’m guessing this is some gap in functionality from the Weebly acquisition for online stores and the integration with existing Square catalog. If there is any way recommend feature prioritization on the API product roadmap, this would be my +1 :slight_smile:

1 Like
14

I’ll be sure to share this with the team. :slightly_smiling_face: