manage-product-market-access-by-location-stock-status.json

{
  "docs": "This task runs on inventory level changes, checking the stock status across all variants for that specific product and location, and if they are all out of stock it will unpublish the product from the market's publication, thus denying the product from online sale in that market. On the flipside, it will publish a product to the location's market publications if any of its variants are in stock at that location.\n\nThe task may also be run manually to query for all active products in the shop, and process each of them for each configured location. Optionally, enter tags for products that should be ignored completely by this task.\n\nConfigure the task with the location names on the left and the paired market names on the right. Multiple market names for a location should be entered on separate lines. Market names may be shared between locations, and only a single location needs to be in stock for a product to be published to that market.\n\n**Note**: In this task, a product is considered in stock at a location if ANY of the variants stocked at that location:\n\n- have inventory tracking disabled **OR**\n- have overselling enabled **OR**\n- have > 0 \"available\" inventory\n\nThe logic checks for inventory tracking and overselling can each be ignored through their respective task options; meaning the task will skip the variants which meet that criteria.",
  "halt_action_run_sequence_on_error": false,
  "name": "Manage product market access by location stock status",
  "online_store_javascript": null,
  "options": {
    "locations_and_market_names__keyval_multiline_required": null,
    "ignore_products_with_any_of_these_tags__array": null,
    "ignore_variants_that_do_not_track_inventory__boolean": false,
    "ignore_variants_that_are_configured_for_overselling__boolean": false
  },
  "order_status_javascript": null,
  "perform_action_runs_in_sequence": false,
  "preview_event_definitions": [
    {
      "description": "Sample inventory level update",
      "event_attributes": {
        "topic": "shopify/inventory_levels/update",
        "data": {
          "admin_graphql_api_id": "gid://shopify/InventoryLevel/987654321?inventory_item_id=1234567890",
          "available": 0,
          "inventory_item_id": 1234567890,
          "location_id": 987654321
        }
      }
    }
  ],
  "script": "{% comment %}\n  -- using a keyval with multiline configuration field allows location names to be mapped to multiple markets\n{% endcomment %}\n\n{% assign locations_and_market_names = options.locations_and_market_names__keyval_multiline_required %}\n{% assign ignore_products_with_any_of_these_tags = options.ignore_products_with_any_of_these_tags__array %}\n{% assign ignore_variants_that_do_not_track_inventory = options.ignore_variants_that_do_not_track_inventory__boolean %}\n{% assign ignore_variants_that_are_configured_for_overselling = options.ignore_variants_that_are_configured_for_overselling__boolean %}\n\n{% if event.preview %}\n  {% assign locations_and_market_names = hash %}\n  {% assign locations_and_market_names[\"Warehouse\"] = \"International\" %}\n{% endif %}\n\n{% assign location_names = locations_and_market_names | keys %}\n{% assign market_names\n  = locations_and_market_names\n  | values\n  | join: newline\n  | split: newline\n  | uniq\n%}\n\n{% assign location_names_and_ids = hash %}\n{% assign inventory_level_inputs = array %}\n\n{% comment %}\n  -- check to make sure all of the location names configured in the task match locations in this shop\n  -- Shopify supports 1000 locations (as of June 2023), so searching by name filter instead of paginating\n{% endcomment %}\n\n{% for location_name in location_names %}\n  {% capture query %}\n    query {\n      locations(\n        first: 1\n        query: {{ location_name | json | prepend: \"name:\" | json }}\n      ) {\n        nodes {\n          id\n          name\n        }\n      }\n    }\n  {% endcapture %}\n\n  {% assign result = query | shopify %}\n\n  {% if event.preview %}\n    {% capture result_json %}\n      {\n        \"data\": {\n          \"locations\": {\n            \"nodes\": [\n              {\n                \"id\": \"gid://shopify/Location/1234567890\"\n              }\n            ]\n          }\n        }\n      }\n    {% endcapture %}\n\n    {% assign result = result_json | parse_json %}\n  {% endif %}\n\n  {% comment %}\n    -- using \"echo\" __error instead of log so that an error indicator shows in the event run log but the task still continues processing\n  {% endcomment %}\n\n  {% if result.data.locations == blank %}\n    {% action \"echo\"\n      __error: \"Configured location name does not match a location in this shop.\",\n      location_name: location_name\n    %}\n    {% continue %}\n  {% endif %}\n\n  {% assign location_id = result.data.locations.nodes.first.id %}\n  {% assign location_names_and_ids[location_name] = location_id %}\n\n  {% comment %}\n    -- save inventory level inputs for bulk querying so that only the locations configured in this task are returned\n    -- have to set alias for the inventoryLevel field because GraphQL requires field name uniqueness within each returned node\n  {% endcomment %}\n\n  {% capture inventory_level_input %}\n    {{ location_id | replace: \"gid://shopify/Location/\", \"location_\" }}: inventoryLevel(locationId: {{ location_id | json }}) {\n      location {\n        name\n      }\n      quantities(names: \"available\") {\n        quantity\n      }\n    }\n  {% endcapture %}\n\n  {% assign inventory_level_inputs = inventory_level_inputs | push: inventory_level_input %}\n{% endfor %}\n\n{% comment %}\n  -- Shopify only supports 50 markets (as of June 2023) and has no query filters for them, so have to retrieve them all\n  -- each market has only a single catalog and publication, so we can map market names to publication IDs in a hash for quicker lookup\n{% endcomment %}\n\n{% assign market_names_and_publication_ids = hash %}\n\n{% capture query %}\n  query {\n    markets(first: 50) {\n      nodes {\n        name\n        catalogs(first: 1) {\n          nodes {\n            publication {\n              id\n            }\n          }\n        }\n      }\n    }\n  }\n{% endcapture %}\n\n{% assign result = query | shopify %}\n\n{% if event.preview %}\n  {% capture result_json %}\n    {\n      \"data\": {\n        \"markets\": {\n          \"nodes\": [\n            {\n              \"name\": \"International\",\n              \"catalogs\": {\n                \"nodes\": [\n                  {\n                    \"publication\": {\n                      \"id\": \"gid://shopify/Publication/1234567890\"\n                    }\n                  }\n                ]\n              }\n            }\n          ]\n        }\n      }\n    }\n  {% endcapture %}\n\n  {% assign result = result_json | parse_json %}\n{% endif %}\n\n{% assign published_inputs = array %}\n\n{% for market in result.data.markets.nodes %}\n  {% assign publication_id = market.catalogs.nodes.first.publication.id %}\n  {% assign market_names_and_publication_ids[market.name] = publication_id %}\n\n  {% comment %}\n    -- save published inputs for checking to see which publications a product is currently published to\n    -- have to set alias for the publishedOnPublication field because GraphQL requires field name uniqueness within each returned node\n  {% endcomment %}\n\n  {% capture published_input -%}\n    published_{{ publication_id | remove: \"gid://shopify/Publication/\" }}: publishedOnPublication(publicationId: {{ publication_id | json }})\n  {%- endcapture %}\n\n  {% assign published_inputs = published_inputs | push: published_input %}\n{% endfor %}\n\n{% comment %}\n  -- check to make sure all of the market names configured in the task match markets in this shop\n  -- using \"echo\" __error instead of log or error tags so that an error indicator shows in the event run log but the task still continues processing\n{% endcomment %}\n\n{% for market_name in market_names %}\n  {% if market_names_and_publication_ids[market_name] == blank %}\n    {% action \"echo\"\n      __error: \"Configured market name does not match a market in this shop.\",\n      market_name: market_name\n    %}\n  {% endif %}\n{% endfor %}\n\n{% comment %}\n  -- setting a variable that can be overriden on inventory level update to only check the relevant location\n{% endcomment %}\n\n{% assign location_names_to_process = location_names %}\n\n{% if event.topic == \"shopify/inventory_levels/update\" %}\n  {% comment %}\n    -- use the inventory level and location IDs from this event webhook to query available inventory for ALL of the product's variants at this location\n    -- Shopify supports 100 variants per product (as of June 2023)\n  {% endcomment %}\n\n  {% capture query %}\n    query {\n      inventoryLevel(id: {{ inventory_level.admin_graphql_api_id | json }}) {\n        location {\n          name\n        }\n        item {\n          variant {\n            product {\n              id\n              title\n              status\n              tags\n              {{ published_inputs | join: newline }}\n              variants(first: 100) {\n                nodes {\n                  inventoryPolicy\n                  inventoryItem {\n                    tracked\n                    inventoryLevel(locationId: {{ inventory_level.location_id | prepend: \"gid://shopify/Location/\" | json }}) {\n                      quantities(names: \"available\") {\n                        quantity\n                      }\n                    }\n                  }\n                }\n              }\n            }\n          }\n        }\n      }\n    }\n  {% endcapture %}\n\n  {% assign result = query | shopify %}\n\n  {% if event.preview %}\n    {% capture result_json %}\n      {\n        \"data\": {\n          \"inventoryLevel\": {\n            \"location\": {\n              \"name\": \"Warehouse\"\n            },\n            \"item\": {\n              \"variant\": {\n                \"product\": {\n                  \"id\": \"gid://shopify/Product/1234567890\",\n                  \"title\": \"Widget\",\n                  \"status\": \"ACTIVE\",\n                  \"published_1234567890\": true,\n                  \"variants\": {\n                    \"nodes\": [\n                      {\n                        \"inventoryPolicy\": \"DENY\",\n                        \"inventoryItem\": {\n                          \"tracked\": true,\n                          \"inventoryLevel\": {\n                            \"quantities\": [\n                              {\n                                \"quantity\": 0\n                              }\n                            ]\n                          }\n                        }\n                      }\n                    ]\n                  }\n                }\n              }\n            }\n          }\n        }\n      }\n    {% endcapture %}\n\n    {% assign result = result_json | parse_json %}\n  {% endif %}\n\n  {% assign location_name = result.data.inventoryLevel.location.name %}\n  {% assign product = result.data.inventoryLevel.item.variant.product %}\n\n  {% comment %}\n    -- stop processing if this product has any of the configured ignore tags\n  {% endcomment %}\n\n  {% assign has_ignore_tag = nil %}\n\n  {% for ignore_tag in ignore_products_with_any_of_these_tags %}\n    {% if product.tags contains ignore_tag %}\n      {% assign has_ignore_tag = true %}\n      {% break %}\n    {% endif %}\n  {% endfor %}\n\n  {% if has_ignore_tag %}\n    {% log\n      message: \"Product has one of the configured ignore tags and will be skipped.\",\n      product: product\n    %}\n    {% break %}\n  {% endif %}\n\n  {% comment %}\n    -- stop processing if this location isn't configured in the task or if the product is not active\n  {% endcomment %}\n\n  {% unless location_names contains location_name and product.status == \"ACTIVE\" %}\n    {% break %}\n  {% endunless %}\n\n  {% comment %}\n    -- make sure the products processing loop only checks this specific product and location\n  {% endcomment %}\n\n  {% assign products = array | push: product %}\n  {% assign location_names_to_process = array | push: location_name %}\n\n{% elsif event.topic == \"mechanic/user/trigger\" %}\n  {% comment %}\n    -- use bulk operation to query all active products, and their variants and paired inventory items in the shop\n    -- only query for inventory levels of locations configured in task, using inputs captured earlier\n    -- NOTE: bulk operation queries require edges and ids for each node, and __typename should be included for filtering returned data\n  {% endcomment %}\n\n  {% assign search_query = \"status:active\" %}\n\n  {% for ignore_tag in ignore_products_with_any_of_these_tags %}\n    {% assign search_query\n      = ignore_tag\n      | json\n      | prepend: \" tag_not:\"\n      | prepend: search_query\n    %}\n  {% endfor %}\n\n  {% capture bulk_operation_query %}\n    query {\n      products(\n        query: {{ search_query | json }}\n      ) {\n        edges {\n          node {\n            __typename\n            id\n            title\n            {{ published_inputs | join: newline }}\n            variants {\n              edges {\n                node {\n                  __typename\n                  id\n                  inventoryPolicy\n                  inventoryItem {\n                    tracked\n                    {{ inventory_level_inputs | join: newline }}\n                  }\n                }\n              }\n            }\n          }\n        }\n      }\n    }\n  {% endcapture %}\n\n  {% action \"shopify\" %}\n    mutation {\n      bulkOperationRunQuery(\n        query: {{ bulk_operation_query | json }}\n      ) {\n        bulkOperation {\n          id\n          status\n        }\n        userErrors {\n          field\n          message\n        }\n      }\n    }\n  {% endaction %}\n\n  {% break %}\n\n{% elsif event.topic == \"mechanic/shopify/bulk_operation\" %}\n  {% if event.preview %}\n    {% capture jsonl_string %}\n      {\"__typename\":\"Product\",\"id\":\"gid://shopify/Product/1234567890\",\"title\":\"Widget\",\"published_1234567890\":true}\n      {\"__typename\":\"ProductVariant\",\"inventoryPolicy\": \"DENY\",\"inventoryItem\":{\"tracked\":true,\"location_1234567890\":{\"location\":{\"name\":\"International\"},\"quantities\":[{\"quantity\":0}]}},\"__parentId\":\"gid://shopify/Product/1234567890\"}\n    {% endcapture %}\n\n    {% assign bulkOperation = hash %}\n    {% assign bulkOperation[\"objects\"] = jsonl_string | parse_jsonl %}\n  {% endif %}\n\n  {% assign products = bulkOperation.objects | where: \"__typename\", \"Product\" %}\n  {% assign bulk_variants = bulkOperation.objects | where: \"__typename\", \"ProductVariant\" %}\n{% endif %}\n\n{% comment %}\n  -- this loop will process all products returned by the bulk operation OR the single product which had an inventory level event\n{% endcomment %}\n\n{% for product in products %}\n  {% comment %}\n    -- variants array depends on how this task run was initiated\n  {% endcomment %}\n\n  {% if event.topic == \"shopify/inventory_levels/update\" %}\n    {% assign variants = product.variants.nodes %}\n\n  {% elsif event.topic == \"mechanic/shopify/bulk_operation\" %}\n    {% assign variants = bulk_variants | where: \"__parentId\", product.id %}\n  {% endif %}\n\n  {% assign publication_ids_that_should_be_published = array %}\n  {% assign publication_ids_that_should_be_unpublished = array %}\n\n  {% for location_name in location_names_to_process %}\n    {% assign location_id = location_names_and_ids[location_name] %}\n    {% assign location_alias = location_id | replace: \"gid://shopify/Location/\", \"location_\" %}\n    {% assign location_market_names = locations_and_market_names[location_name] | split: newline %}\n\n    {% comment %}\n      -- a product is considered in stock at a location IF\n        a) ANY of the variants stocked at that location have inventory tracking disabled ~OR~\n        b) ANY of the variants stocked at that location have overselling enabled ~OR~\n        c) ANY of the variants stocked at that location have > 0 \"available\" inventory\n      -- checks for a) and b) can each be disabled through task options; meaning the task will skip variants which meet that criteria\n    {% endcomment %}\n\n    {% assign location_in_stock = nil %}\n\n    {% for variant in variants %}\n      {% comment %}\n        -- on bulk runs, only proceed with inventory check if the variant is stocked at this location\n      {% endcomment %}\n\n      {% if event.topic == \"mechanic/shopify/bulk_operation\" and variant.inventoryItem[location_alias] == blank  %}\n        {% continue %}\n      {% endif %}\n\n      {% unless variant.inventoryItem.tracked %}\n        {% comment %}\n          -- variants that do not track inventory are considered in stock, unless the option to ignore them is checked\n        {% endcomment %}\n\n        {% if ignore_variants_that_do_not_track_inventory %}\n          {% continue %}\n\n        {% else %}\n          {% assign location_in_stock = true %}\n          {% break %}\n        {% endif %}\n      {% endunless %}\n\n      {% if variant.inventoryPolicy == \"CONTINUE\" %}\n        {% comment %}\n          -- variants set for overselling are considered in stock, unless the option to ignore them is checked\n        {% endcomment %}\n\n        {% if ignore_variants_that_are_configured_for_overselling %}\n          {% continue %}\n\n        {% else %}\n          {% assign location_in_stock = true %}\n          {% break %}\n        {% endif %}\n      {% endif %}\n\n      {% comment %}\n        -- variant \"available\" quantity depends on how this task run was initiated\n      {% endcomment %}\n\n      {% if event.topic == \"shopify/inventory_levels/update\" %}\n        {% assign variant_available = variant.inventoryItem.inventoryLevel.quantities.first.quantity %}\n\n      {% elsif event.topic == \"mechanic/shopify/bulk_operation\" %}\n        {% assign variant_available = variant.inventoryItem[location_alias].quantities.first.quantity %}\n      {% endif %}\n\n      {% if variant_available > 0 %}\n        {% assign location_in_stock = true %}\n        {% break %}\n      {% endif %}\n    {% endfor %}\n\n    {% comment %}\n      -- for each location market, add the paired publication ID to appropriate un/publish array based on location stock status\n    {% endcomment %}\n\n    {% for location_market_name in location_market_names %}\n      {% assign publication_id = market_names_and_publication_ids[location_market_name] %}\n\n      {% if location_in_stock %}\n        {% assign publication_ids_that_should_be_published = publication_ids_that_should_be_published | push: publication_id %}\n      {% else %}\n        {% assign publication_ids_that_should_be_unpublished = publication_ids_that_should_be_unpublished | push: publication_id %}\n      {% endif %}\n    {% endfor %}\n  {% endfor %}\n\n  {% comment %}\n    -- create publish inputs for each qualifying publication ID where the product isn't already published\n  {% endcomment %}\n\n  {% assign publish_inputs = array %}\n\n  {% for publication_id in publication_ids_that_should_be_published %}\n    {% assign published_alias = publication_id | replace: \"gid://shopify/Publication/\", \"published_\" %}\n\n    {% unless product[published_alias] %}\n      {% assign publish_input = hash %}\n      {% assign publish_input[\"publicationId\"] = publication_id %}\n      {% assign publish_inputs = publish_inputs | push: publish_input %}\n    {% endunless %}\n  {% endfor %}\n\n  {% comment %}\n    -- create unpublish inputs for each qualifying publication ID where the product isn't already unpublished AND the publication ID does not appear in the \"should be published array\" (to account for locations that share a market)\n  {% endcomment %}\n\n  {% assign unpublish_inputs = array %}\n\n  {% for publication_id in publication_ids_that_should_be_unpublished %}\n    {% assign published_alias = publication_id | replace: \"gid://shopify/Publication/\", \"published_\" %}\n\n    {% unless publication_ids_that_should_be_published contains publication_id %}\n      {% if product[published_alias] %}\n        {% assign unpublish_input = hash %}\n        {% assign unpublish_input[\"publicationId\"] = publication_id %}\n        {% assign unpublish_inputs = unpublish_inputs | push: unpublish_input %}\n      {% endif %}\n    {% endunless %}\n  {% endfor %}\n\n  {% comment %}\n    -- \"ALLOW\" or \"DENY\" a product access to/from markets by un/publishing it from the associated market publications\n  {% endcomment %}\n\n  {% if publish_inputs != blank %}\n    {% action \"shopify\" %}\n      mutation {\n        publishablePublish(\n          id: {{ product.id | json }}\n          input: {{ publish_inputs | uniq | graphql_arguments }}\n        ) {\n          publishable {\n            ... on Product {\n              title\n            }\n          }\n          userErrors {\n            field\n            message\n          }\n        }\n      }\n    {% endaction %}\n  {% endif %}\n\n  {% if unpublish_inputs != blank %}\n    {% action \"shopify\" %}\n      mutation {\n        publishableUnpublish(\n          id: {{ product.id | json }}\n          input: {{ unpublish_inputs | uniq | graphql_arguments }}\n        ) {\n          publishable {\n            ... on Product {\n              title\n            }\n          }\n          userErrors {\n            field\n            message\n          }\n        }\n      }\n    {% endaction %}\n  {% endif %}\n{% endfor %}\n",
  "subscriptions": [
    "shopify/inventory_levels/update",
    "mechanic/user/trigger",
    "mechanic/shopify/bulk_operation"
  ],
  "subscriptions_template": "shopify/inventory_levels/update\nmechanic/user/trigger\nmechanic/shopify/bulk_operation",
  "tags": [
    "Bulk",
    "In stock",
    "Markets",
    "Out of Stock",
    "Products",
    "Publish",
    "Unpublish"
  ]
}