Skip to content

Update market settings

API v2 is in public beta: endpoints and fields can change before general availability. See the changelog

PATCH/account/markets

Costs 2 rate-limit points · Rate limits

Update how the store routes stock by market, for back in stock and preorders alike: the market setup, the market-to-location links and whether they are used, market URLs, and the single-market location filter.

Deep partial: absent fields are unchanged. links and preorder_location_filter.shopify_location_ids replace the stored list when present. Market and location ids are checked against Shopify.

Also searched aslink market to inventory locationmarket based locationssell in multiple marketspreorder market setupcount stock at specific locationspreorder location filterfilter preorder locationsuse market urls in alerts

Headers

  • Idempotency-Keystring

    A fresh unique key for every write (a new UUID, say); reuse it only to retry that write. Keys are remembered for 1 hour: the same key and the same request within that hour returns the first result, with Idempotent-Replayed: true, without running again; the same key with a different method, path or body is refused (422 idempotency_key_reused); a retry while the first is still running gets 409 idempotency_key_in_progress. Keys are per store. Server errors and rate limits are not kept, so their retry runs.

Request body

  • market_setup_typestring

    "single_market" or "multiple_markets". Switching to multiple markets turns preorder_location_filter.enabled off, and switching to a single market turns market_locations_enabled off, unless the request sets them too. Switching to multiple markets also turns the back-in-stock location filter off (back_in_stock.locations.filter_enabled). Each is listed in also_changed.

    One of single_marketmultiple_markets
  • market_locations_enabledboolean

    Count stock only at the locations linked to the customer's market (links). Used only with market_setup_type "multiple_markets".

  • market_urls_enabledboolean

    Send customers to their market's URL in alerts.

  • preorder_location_filterobject

    Single-market filter on which locations' stock decides whether the Preorder button shows.

    Show 2 child attributesHide child attributes
    • enabledboolean

      Count stock only at preorder_location_filter.shopify_location_ids when deciding whether to show the Preorder button. For a store with a single market.

    • shopify_location_idsarray of strings

      Shopify location gids (gid://shopify/Location/123) to count stock at. REPLACES the stored list.

  • linksarray of objects

    Every market-to-location link, REPLACING the stored ones: [{ "shopify_market_id": "gid://shopify/Market/123", "shopify_location_id": "gid://shopify/Location/456" }]. Markets come from GET /account/markets, locations from GET /account/locations. [] removes every link.

    Show 2 child attributesHide child attributes
    • shopify_market_idstring
      Example: gid://shopify/Market/12345
    • shopify_location_idstring
      Example: gid://shopify/Location/67890

Returns

  • market_setup_typestring
    Example: multiple_markets
  • market_locations_enabledboolean
    Example: true
  • market_urls_enabledboolean
    Example: false
  • preorder_location_filterobject
    Show 2 child attributesHide child attributes
    • enabledboolean
      Example: false
    • shopify_location_idsarray of anys
  • linksarray of objects
    Show 2 child attributesHide child attributes
    • shopify_market_idstring
      Example: gid://shopify/Market/12345
    • shopify_location_idstring
      Example: gid://shopify/Location/67890
  • also_changedarray of strings

    Settings this write changed on its own because they depend on what you changed (turning one option off can reset another). Absent when nothing else changed.

Errors

404
not_found

The path is valid but nothing with that id exists in this store.

409
conflict

The request is well formed, but the resource's current state does not allow it.

409
idempotency_key_in_progress

An earlier request with the same Idempotency-Key is still running. Wait, then resend the same request with the same key.

422
invalid_params

One or more fields failed the action's schema.

422
validation_failed

The request failed validation.

502
shopify_error

A Shopify call the operation needs failed after the operation had started.

503
upstream_unavailable

A service the answer depends on did not respond in time.

Any request can also fail with auth_invalid (401) or rate_limited (429).

Every error has the same shape: see Errors and the list of error codes.

PATCH/account/markets
curl -X PATCH "https://app.stoqapp.com/api/v2/external/account/markets" \
  -H "X-Auth-Token: $STOQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "market_setup_type": "multiple_markets",
    "market_locations_enabled": true,
    "links": [
      {
        "shopify_market_id": "gid://shopify/Market/12345",
        "shopify_location_id": "gid://shopify/Location/67890"
      }
    ]
  }'
Response
{
  "market_setup_type": "multiple_markets",
  "market_locations_enabled": true,
  "market_urls_enabled": false,
  "preorder_location_filter": {
    "enabled": false,
    "shopify_location_ids": []
  },
  "links": [
    {
      "shopify_market_id": "gid://shopify/Market/12345",
      "shopify_location_id": "gid://shopify/Location/67890"
    }
  ],
  "also_changed": [
    "preorder_location_filter.enabled"
  ]
}