maintain-inventory-for-a-product-bundle.json

{
  "docs": "Use this task to automatically sync inventory for a simple product bundle – no theme modifications required. When configured with unique SKUs for the bundle and its components, and with quantities needed from each component for each bundle unit, this task keeps the bundle inventory set to the greatest possible value, given the quantities of its components. It also appropriately subtracts from component inventory whenever the bundle is ordered, and appropriately raises component inventory when a bundle order is refunded and restocked.\n\nUsage:\n\n* Run this task manually to sync the bundle's inventory with that of the component product that has the least inventory in stock.\n* This task will run automatically whenever the bundle product is ordered, and whenever the bundle product is refunded in such a way that it is restocked.\n\nRequirements:\n\n* This task only considers inventory from the default location configured in the shop.\n* Configure this task with a unique SKU for the bundle product. The bundle product SKU must not be re-used by any other products.\n* This task can sync inventory across multiple product variants sharing the same component SKU. But, if a single SKU is used for multiple variants in the same store, all such variants must start with and maintain equal inventory levels.\n* Use the right-hand side of the \"Component product SKUs and quantities per bundle\" option to control how many units of each component SKU is required for each single bundle unit. If your bundle requires one wrench and two sprockets, for example, make sure to add \"1\" and \"2\" on the right-hand side, each number associated with the right SKU.\n\nNotes:\n\n* Whenever this task runs, any inventory updates to the bundle product will be overwritten. For the purposes of this task, the bundle's inventory is exclusively derived from the inventory of its components. (This also means that this task does not support \"nested\" bundles, in which a bundle component product is itself a bundle managed by another copy of this task.)\n* Feel free to manually adjust inventory for component products, keeping in mind that components with shared SKUs must be kept equal to each other. The bundle product's inventory will be synced appropriately.\n* Use the \"Inventory buffer quantity\" option to artificially keep the bundle product's inventory lower than the actual available quantity.\n- Fulfillment order moves (i.e. between locations) containing the bundle product SKU will be ignored by this task.",
  "halt_action_run_sequence_on_error": false,
  "name": "Maintain inventory for a product bundle",
  "online_store_javascript": null,
  "options": {
    "bundle_product_sku__required": "BUNDLE",
    "component_product_skus_and_quantities_per_bundle__keyval_number_required": {
      "BUNDLE-A": 1,
      "BUNDLE-B": 2,
      "BUNDLE-C": 3
    },
    "inventory_buffer_quantity__number": "1"
  },
  "order_status_javascript": null,
  "perform_action_runs_in_sequence": false,
  "script": "{% assign bundle_sku = options.bundle_product_sku__required %}\n{% assign component_skus_and_quantities = options.component_product_skus_and_quantities_per_bundle__keyval_number_required %}\n{% assign inventory_buffer_quantity = options.inventory_buffer_quantity__number %}\n\n{% assign component_skus = component_skus_and_quantities | keys %}\n{% assign all_skus = array | push: bundle_sku | concat: component_skus %}\n\n{% assign variants_by_sku = hash %}\n\n{% assign primary_location = shop.locations[shop.primary_location_id] %}\n{% assign primary_location_id_string = shop.primary_location_id | append: \"\" %}\n\n{% log\n  task_config: \"for this event run\",\n  bundle_sku: bundle_sku,\n  component_skus_and_quantities: component_skus_and_quantities,\n  inventory_buffer_quantity: inventory_buffer_quantity,\n  primary_location: primary_location\n%}\n\n{% assign do_full_sync = false %}\n{% assign do_component_adjustment = false %}\n{% assign component_adjustment_bundle_quantity = nil %}\n\n{% if event.topic == \"mechanic/user/trigger\" %}\n  {% assign do_full_sync = true %}\n{% endif %}\n\n{% if event.topic == \"shopify/orders/create\" %}\n  {% comment %}\n    -- when new orders are created, only send along bundle line items that are assigned to the primary location\n  {% endcomment %}\n\n  {% capture query %}\n    query {\n      order(id: {{ order.admin_graphql_api_id | json }}) {\n        fulfillmentOrders(\n          first: 10\n          query: \"assigned_location_id:{{ shop.primary_location_id }}\"\n        ) {\n          nodes {\n            lineItems(first: 100) {\n              nodes {\n                sku\n                totalQuantity\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          \"order\": {\n            \"fulfillmentOrders\": {\n              \"nodes\": [\n                {\n                  \"lineItems\": {\n                    \"nodes\": [\n                      {\n                        \"sku\": {{ bundle_sku | json }},\n                        \"totalQuantity\": 1\n                      }\n                    ]\n                  }\n                }\n              ]\n            }\n          }\n        }\n      }\n    {% endcapture %}\n\n    {% assign result = result_json | parse_json %}\n  {% endif %}\n\n  {% assign bundle_quantity = 0 %}\n\n  {% for fulfillment_order in result.data.order.fulfillmentOrders.nodes %}\n    {% for line_item in fulfillment_order.lineItems.nodes %}\n      {% if line_item.sku == bundle_sku %}\n        {% assign bundle_quantity = bundle_quantity | plus: line_item.totalQuantity %}\n      {% endif %}\n    {% endfor %}\n  {% endfor %}\n\n  {% if bundle_quantity != 0 %}\n    {% assign do_component_adjustment = true %}\n    {% assign component_adjustment_bundle_quantity = bundle_quantity | times: -1 %}\n\n  {% else %}\n    {% log \"None of the fulfillment orders on this order were assigned to the primary location; skipping.\" %}\n  {% endif %}\n{% endif %}\n\n{% if event.topic == \"shopify/refunds/create\" %}\n  {% comment %}\n    -- when refunds are created, only send along bundle line items that are restocked to the primary location\n  {% endcomment %}\n\n  {% capture query %}\n    query {\n      refund(id: {{ refund.admin_graphql_api_id | json }}) {\n        refundLineItems(first: 100) {\n          nodes {\n            lineItem {\n              sku\n            }\n            location {\n              legacyResourceId\n            }\n            quantity\n            restocked\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          \"refund\": {\n            \"refundLineItems\": {\n              \"nodes\": [\n                {\n                  \"lineItem\": {\n                    \"sku\": {{ bundle_sku | json }}\n                  },\n                  \"location\": {\n                    \"legacyResourceId\": {{ shop.primary_location_id | json }}\n                  },\n                  \"quantity\": 1,\n                  \"restocked\": true\n                }\n              ]\n            }\n          }\n        }\n      }\n    {% endcapture %}\n\n    {% assign result = result_json | parse_json %}\n  {% endif %}\n\n  {% assign bundle_restock_quantity = 0 %}\n\n  {% for refund_line_item in result.data.refund.refundLineItems.nodes %}\n    {% if refund_line_item.lineItem.sku == bundle_sku\n      and refund_line_item.location.legacyResourceId == primary_location_id_string\n      and refund_line_item.restocked\n    %}\n      {% assign bundle_restock_quantity = bundle_restock_quantity | plus: refund_line_item.quantity %}\n    {% endif %}\n  {% endfor %}\n\n  {% if bundle_restock_quantity != 0 %}\n    {% assign do_component_adjustment = true %}\n    {% assign component_adjustment_bundle_quantity = bundle_restock_quantity %}\n\n  {% else %}\n    {% log \"None of the line items on this refund were restocked to the primary location; skipping.\" %}\n  {% endif %}\n{% endif %}\n\n{% if event.topic contains \"shopify/inventory_levels/\" %}\n  {% comment %}\n    -- only respond to inventory level events at the primary location\n  {% endcomment %}\n\n  {% if inventory_level.location_id != shop.primary_location_id %}\n    {% log \"This inventory level change was for an item not at the primary location; skipping.\" %}\n    {% break %}\n  {% endif %}\n\n  {% capture query %}\n    query {\n      inventoryLevel(id: {{ inventory_level.admin_graphql_api_id | json }}) {\n        item {\n          variant {\n            sku\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            \"item\": {\n              \"variant\": {\n                \"sku\": {{ component_skus.first | json }}\n              }\n            }\n          }\n        }\n      }\n    {% endcapture %}\n\n    {% assign result = result_json | parse_json %}\n  {% endif %}\n\n  {% assign updated_sku = result.data.inventoryLevel.item.variant.sku %}\n\n  {% if all_skus contains updated_sku %}\n    {% assign do_full_sync = true %}\n\n  {% else %}\n    {% log \"The inventory level change did not include one of the SKUs configured in this task; skipping.\" %}\n  {% endif %}\n{% endif %}\n\n{% if do_component_adjustment or do_full_sync %}\n  {% comment %}\n    -- get available inventory of the bundle and component(s) at the primary location\n  {% endcomment %}\n\n  {% assign query_components = array %}\n\n  {% for sku in all_skus %}\n    {% assign query_components[query_components.size] = sku | json | prepend: \"sku:\" %}\n  {% endfor %}\n\n  {% for n in (0..500) %}\n    {% assign cursor = nil %}\n\n    {% capture query %}\n      query {\n        productVariants(\n          first: 150\n          query: {{ query_components | join: \" OR \" | json }}\n          after: {{ cursor | json }}\n        ) {\n          pageInfo {\n            hasNextPage\n            endCursor\n          }\n          nodes {\n            sku\n            inventoryItem {\n              id\n              inventoryLevel(locationId: {{ primary_location.admin_graphql_api_id | json }}) {\n                id\n                quantities(names: \"available\") {\n                  name\n                  quantity\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            \"productVariants\": {\n              \"nodes\": [\n                {\n                  \"sku\": {{ bundle_sku | json }},\n                  \"inventoryItem\": {\n                    \"id\": \"gid://shopify/InventoryItem/1234567890\",\n                    \"inventoryLevel\": {\n                      \"id\": \"gid://shopify/InventoryLevel/1234567890?x=bundle&sku={{ bundle_sku }}&inventory_item_id=1234567890\",\n                      \"quantities\": [\n                        {\n                          \"name\": \"available\",\n                          \"quantity\": 2\n                        }\n                      ]\n                    }\n                  }\n                },\n                {% for component_sku in component_skus %}\n                  {\n                    \"sku\": {{ component_sku | json }},\n                    \"inventoryItem\": {\n                      \"id\": \"gid://shopify/InventoryItem/2345678901\",\n                      \"inventoryLevel\": {\n                        \"id\": \"gid://shopify/InventoryLevel/2345678901?x=component&sku={{ component_sku }}&inventory_item_id=2345678901\",\n                        \"quantities\": [\n                          {\n                            \"name\": \"available\",\n                            \"quantity\": 1\n                          }\n                        ]\n                      }\n                    }\n                  }\n                  {% unless forloop.last %},{% endunless %}\n                {% endfor %}\n              ]\n            }\n          }\n        }\n      {% endcapture %}\n\n      {% assign result = result_json | parse_json %}\n    {% endif %}\n\n    {% for variant in result.data.productVariants.nodes %}\n      {% assign variants_by_sku[variant.sku]\n        = variants_by_sku[variant.sku]\n        | default: array\n        | push: variant\n      %}\n    {% endfor %}\n\n    {% if result.data.productVariants.pageInfo.hasNextPage %}\n      {% assign cursor = result.data.productVariants.pageInfo.endCursor %}\n    {% else %}\n      {% break %}\n    {% endif %}\n  {% endfor %}\n\n  {% if variants_by_sku[bundle_sku].size != 1 %}\n    {% error\n      message: \"Did not find exactly one variant for the provided bundle SKU. This task does not support re-use of the bundle SKU across multiple variants.\",\n      bundle_sku: bundle_sku,\n      bundle_variants: variants_by_sku[bundle_sku]\n    %}\n  {% endif %}\n\n  {% for component_sku in component_skus %}\n    {% if variants_by_sku[component_sku] == blank %}\n      {% error\n        message: \"Didn't find any variants for a component SKU. Each component SKU must have at least one variant.\",\n        component_sku: component_sku\n      %}\n    {% endif %}\n  {% endfor %}\n\n  {% log bundle_and_component_quantities_before_adjustment: variants_by_sku %}\n{% endif %}\n\n{% if do_component_adjustment %}\n  {% comment %}\n    -- an order was created or a refund with restock occurred which contained the bundle, adjust the inventory of the components\n  {% endcomment %}\n\n  {% assign inventory_adjustments = array %}\n\n  {% for keyval in variants_by_sku %}\n    {% assign sku = keyval[0] %}\n    {% assign variants = keyval[1] %}\n    {% assign expected_inventory_quantity = variants[0].inventoryItem.inventoryLevel.quantities.first.quantity %}\n\n    {% for variant in variants %}\n      {% if variant.inventoryItem.inventoryLevel.quantities.first.quantity != expected_inventory_quantity %}\n        {% error\n          message: \"Expected all variants for a single SKU to have matching inventory levels, but they did not - can't continue. Please manually sync inventory for all variants sharing this SKU, and try again.\",\n          sku: sku,\n          variants: variants\n        %}\n      {% endif %}\n\n      {% assign variant_delta = component_adjustment_bundle_quantity | times: component_skus_and_quantities[variant.sku] %}\n\n      {% if variant_delta != 0 %}\n        {% assign inventory_adjustment = hash %}\n        {% assign inventory_adjustment[\"inventoryItemId\"] = variant.inventoryItem.id %}\n        {% assign inventory_adjustment[\"locationId\"] = primary_location.admin_graphql_api_id %}\n        {% assign inventory_adjustment[\"delta\"] = variant_delta %}\n        {% assign inventory_adjustments = inventory_adjustments | push: inventory_adjustment %}\n      {% endif %}\n    {% endfor %}\n  {% endfor %}\n\n  {% if inventory_adjustments != blank %}\n    {% action \"shopify\" %}\n      mutation {\n        inventoryAdjustQuantities(\n          input: {\n            reason: \"correction\"\n            name: \"available\"\n            changes: {{ inventory_adjustments | graphql_arguments }}\n          }\n        ) {\n          inventoryAdjustmentGroup {\n            reason\n            changes(quantityNames: [\"available\"]) {\n              name\n              delta\n              item {\n                id\n                sku\n              }\n              location {\n                name\n              }\n            }\n          }\n          userErrors {\n            code\n            field\n            message\n          }\n        }\n      }\n    {% endaction %}\n  {% endif %}\n{% endif %}\n\n{% if do_full_sync %}\n  {% comment %}\n    Initialize some variables:\n    * minimum_inventory_component_variant: the single component variant that, when its bundle quantity\n        multiplier is factored in, represents the smallest number of bundles that can be constructed\n        with the variant inventory on hand. (for example, given 3 widgets per bundle, if we find a widget\n        variant with an inventory of 5 and another one with inventory 6, the *first* one is the minimum\n        inventory component variant, because it pulls down the max number of bundles from 2 to 1.)\n    * minimum_inventory_component_variant_bundle_quantity: the number of bundles that can be safely\n        constructed, given the smallest proportionate inventory value found across all component variants.\n    * bundle_variant: the bundle variant (remember, we only support one - no SKU sharing for bundles). we'll\n        use this variant to perform any inventory updates needed to the bundle itself.\n  {% endcomment %}\n\n  {% assign minimum_inventory_component_variant = nil %}\n  {% assign minimum_inventory_component_variant_bundle_quantity = nil %}\n  {% assign bundle_variant = nil %}\n\n  {% for pair in variants_by_sku %}\n    {% assign sku = pair[0] %}\n    {% assign variants = pair[1] %}\n    {% assign expected_inventory_quantity = variants[0].inventoryItem.inventoryLevel.quantities.first.quantity %}\n\n    {% for variant in variants %}\n      {% if variant.inventoryItem.inventoryLevel.quantities.first.quantity != expected_inventory_quantity %}\n        {% assign error_message = \"Expected all \" | append: sku | append: \" variants to have an inventory quantity of \" | append: expected_inventory_quantity | append: \", but not every variant is at this level. Ensure every variant is in sync, and try again.\" %}\n        {% error error_message %}\n      {% endif %}\n\n      {% if variant.sku == bundle_sku %}\n        {% assign bundle_variant = variant %}\n\n      {% elsif component_skus contains variant.sku %}\n        {% assign variant_bundle_quantity\n          = variant.inventoryItem.inventoryLevel.quantities.first.quantity\n          | times: 1.0\n          | divided_by: component_skus_and_quantities[variant.sku]\n        %}\n\n        {% if minimum_inventory_component_variant == nil or minimum_inventory_component_variant_bundle_quantity > variant_bundle_quantity %}\n          {% assign minimum_inventory_component_variant = variant %}\n          {% assign minimum_inventory_component_variant_bundle_quantity = variant_bundle_quantity %}\n        {% endif %}\n      {% endif %}\n    {% endfor %}\n  {% endfor %}\n\n  {% assign bundle_delta\n    = minimum_inventory_component_variant_bundle_quantity\n    | floor\n    | minus: bundle_variant.inventoryItem.inventoryLevel.quantities.first.quantity\n  %}\n\n  {% if inventory_buffer_quantity != blank %}\n    {% assign bundle_delta = bundle_delta | minus: inventory_buffer_quantity %}\n  {% endif %}\n\n  {% log\n    bundle_variant: bundle_variant,\n    minimum_inventory_component_variant_sku: minimum_inventory_component_variant.sku,\n    minimum_inventory_component_variant_quantity: minimum_inventory_component_variant.inventoryItem.inventoryLevel.quantities.first.quantity, minimum_inventory_component_variant_bundle_quantity: minimum_inventory_component_variant_bundle_quantity,\n    inventory_buffer_quantity: inventory_buffer_quantity,\n    available_delta: bundle_delta\n  %}\n\n  {% if bundle_delta == 0 %}\n    {% log \"Lowest quantity component SKU had an inventory that was appropriate for the bundle's current inventory. No change needed.\" %}\n\n  {% else %}\n    {% action \"shopify\" %}\n      mutation {\n        inventoryAdjustQuantities(\n          input: {\n            reason: \"correction\"\n            name: \"available\"\n            changes: [\n              {\n                inventoryItemId: {{ bundle_variant.inventoryItem.id | json }}\n                locationId: {{ primary_location.admin_graphql_api_id | json }}\n                delta: {{ bundle_delta }}\n              }\n            ]\n          }\n        ) {\n          inventoryAdjustmentGroup {\n            reason\n            changes(quantityNames: [\"available\"]) {\n              name\n              delta\n              item {\n                id\n                sku\n              }\n              location {\n                name\n              }\n            }\n          }\n          userErrors {\n            code\n            field\n            message\n          }\n        }\n      }\n    {% endaction %}\n  {% endif %}\n{% endif %}\n",
  "subscriptions": [
    "shopify/orders/create",
    "shopify/refunds/create",
    "shopify/inventory_levels/update",
    "mechanic/user/trigger"
  ],
  "subscriptions_template": "shopify/orders/create\nshopify/refunds/create\nshopify/inventory_levels/update\nmechanic/user/trigger",
  "tags": [
    "Bundle",
    "Inventory",
    "Products",
    "SKU",
    "Sync"
  ]
}