Square Dashboard allows creation of inconsistent location settings between Items and Variations

Questions
1

Product Area: Square Dashboard / Catalog Management

Severity: Medium - Causes API errors when updating inventory thresholds

Description:
Square Dashboard allows users to create an inconsistent state where an Item Variation has “Present at all locations” enabled, but its parent Item does not. This configuration is rejected by the Catalog API when attempting to update the variation (e.g., setting inventory alert thresholds), but Square Dashboard does not prevent or warn users from creating this state.

Steps to Reproduce:

  1. Create or edit an Item in Square Dashboard

  2. Set the Item to NOT be present at all future locations

  3. Edit a Variation under that Item

  4. Enable “Present at all future locations” for the Variation

  5. Save changes (Dashboard allows this)

  6. Attempt to update the Variation via API (e.g., PATCH to update inventory_alert_threshold)

Expected Behavior:

  • Square Dashboard should either prevent this configuration, or

  • Display a warning that the variation’s location settings conflict with its parent item

Actual Behavior:

  • Dashboard allows the inconsistent configuration

  • API calls to update the variation fail with error:

{
  "category": "INVALID_REQUEST_ERROR",
  "code": "INVALID_VALUE",
  "detail": "Object '[VARIATION_ID]' of type ITEM_VARIATION is enabled at all future locations, but the referenced object with token '[ITEM_ID]' of type ITEM is not.",
  "field": "item_id"
}

Impact:

  • Third-party integrations cannot update variations with this mismatch

  • No visibility in Dashboard that this issue exists

  • Users must manually audit catalog to find affected items

Suggested Fix:

  1. Validate parent-child location consistency when saving in Dashboard

  2. Add a catalog health check to identify existing mismatches

  3. Improve error message to suggest the fix (enable parent item at all locations OR disable it on variation)

Screenshot 2025-12-12 101235
Screenshot 2025-12-12 101235425×217 9.02 KB

2

:waving_hand: I’m Square Dev AI, here to help answer your question!
Based on the information you’ve provided, the following documentation will help answer your question:

Additional Documentation

Define Item Variations Using Options
Inventory API
Design a Catalog

If this documentation helped you find a solution, please check the box indicating that this reply solves the problem.
Otherwise one of our Developer Advocates will provide additional assistance shortly.

3

What are the steps to make the variation available at all locations in the Dashboard. I’ve been unable to replicate this in production. :slight_smile:

4

Update – Additional Scenario Observed + Practical Workaround

Thanks for the responses so far. While investigating this further on our side, we noticed an additional scenario that can lead to the same inconsistent parent/variation location state.

Additional scenario observed:

When a merchant disables items at a specific location before fully deactivating that location, some items and variations can end up with mismatched location settings. In our case, we previously had two locations. Items were disabled at one location prior to that location being shut down, which appears to have left behind orphaned location flags where variations and parent items no longer matched.

After the location was deactivated, we were left with a significant number of affected catalog objects (266 items and 352 variations) in this inconsistent state. There was no visibility in the Square Dashboard to identify which items were impacted, nor a way to correct them in bulk.

Workaround we implemented (API-side):

We were able to resolve this programmatically using the Catalog API:

  • List all catalog objects (ITEM and ITEM_VARIATION)

  • Identify objects where present_at_all_locations = false

  • Batch update them to restore consistency

Example (simplified):

const response = await squareClient.catalogApi.batchUpsertCatalogObjects({
  idempotency_key: uuid(),
  batches: [{
    objects: itemsToFix.map(obj => ({
      type: obj.type,
      id: obj.id,
      version: obj.version,
      present_at_all_locations: true,
      item_data: obj.item_data // required for ITEM updates
    }))
  }]
});