{ "openapi": "3.1.0", "info": { "title": "Connected Inventory Merchant API", "version": "1.0.0", "description": "Manage inventory groups and read sync history for one Shopify shop. Advance plan required; API access is currently in early access. Open Connected Inventory in Shopify Admin to check your plan and access, or contact support@notasideproject.com. Requests require a bearer API key and the matching X-Shopify-Shop-Domain header. The default shared allowance is 60 requests per fixed minute per shop, across all keys and paths. Validation failures, polling and idempotent replays count. No remaining-budget header is returned. All IDs and titles in examples are illustrative.", "contact": { "name": "Connected Inventory support", "email": "support@notasideproject.com", "url": "https://intercom.help/connected-inventory/en" } }, "servers": [ { "url": "https://ci-api.notasideproject.com/api/v1" } ], "externalDocs": { "description": "Full API reference", "url": "https://connected-inventory.notasideproject.com/docs/api/v1" }, "tags": [ { "name": "Manual groups", "description": "Connect specific variants that share inventory. A variant can belong to only one manual group." }, { "name": "Bundle groups", "description": "Define a sellable master variant and the component quantities that make up a bundle." }, { "name": "Smart groups", "description": "Read groups generated from matching SKUs. The API calls these auto_groups. Membership is generated by a refresh, rather than written directly." }, { "name": "Activity logs", "description": "Read the shop’s stored activity messages." }, { "name": "Sync history", "description": "Inspect stored inventory sync history and the group results associated with an order." } ], "security": [ { "bearerAuth": [] } ], "paths": { "/manual_groups": { "get": { "operationId": "list-manual-groups", "tags": [ "Manual groups" ], "summary": "List manual groups", "description": "Return group summaries in descending ID order. Fetch a group by ID to read its members.\n\nRequired permission: Read. ", "x-permission": "Read", "parameters": [ { "name": "X-Shopify-Shop-Domain", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The key’s full *.myshopify.com hostname, without a scheme, path or port. Comparison ignores case and surrounding whitespace.", "example": "your-store.myshopify.com" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Default 50, capped at 200. Nonpositive or nonnumeric values fall back to 50." }, { "name": "after", "in": "query", "schema": { "type": "string" }, "description": "Opaque next_cursor from the previous page. Items are ordered by descending ID. Stop when next_cursor is null." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GroupSummary" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "example": { "data": [ { "id": 42, "name": "Everyday totes", "status": "active", "created_at": "2026-10-12T08:00:00Z", "updated_at": "2026-10-12T08:00:00Z", "member_count": 2 } ], "next_cursor": null } } } }, "400": { "description": "shop_domain_required: Send a nonblank X-Shopify-Shop-Domain header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_required": { "value": { "error": { "code": "shop_domain_required", "message": "Send a nonblank X-Shopify-Shop-Domain header." } } } } } } }, "401": { "description": "invalid_key: The bearer key is missing, unknown, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_key": { "value": { "error": { "code": "invalid_key", "message": "The bearer key is missing, unknown, or revoked." } } } } } } }, "402": { "description": "plan_required: The shop needs an active Advance entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "The shop needs an active Advance entitlement." } } } } } } }, "403": { "description": "shop_domain_mismatch: The supplied domain does not match the key’s shop.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_mismatch": { "value": { "error": { "code": "shop_domain_mismatch", "message": "The supplied domain does not match the key’s shop." } } } } } } }, "422": { "description": "validation_failed: Invalid JSON, request fields, group membership, or pagination cursor. Read error.message for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "validation_failed": { "value": { "error": { "code": "validation_failed", "message": "Invalid JSON, request fields, group membership, or pagination cursor. Read error.message for the reason." } } } } } } }, "429": { "description": "rate_limited: The shop’s shared request allowance is exhausted. Wait for Retry-After (60 seconds).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "value": { "error": { "code": "rate_limited", "message": "API rate limit exceeded. Retry after 60 seconds." } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "const": 60 }, "description": "Wait 60 seconds before retrying." }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "503": { "description": "rate_limit_unavailable: The rate limit could not be checked; the action did not run. Retry later. shopify_unavailable: Shopify could not be reached while checking the subscription. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_unavailable": { "value": { "error": { "code": "rate_limit_unavailable", "message": "The rate limit could not be checked; the action did not run. Retry later." } } }, "shopify_unavailable": { "value": { "error": { "code": "shopify_unavailable", "message": "Shopify could not be reached while checking the subscription. Retry later." } } } } } } } } }, "post": { "operationId": "create-manual-groups", "tags": [ "Manual groups" ], "summary": "Create a manual group", "description": "Create a group using the supplied variant metadata. This does not look up or verify the variants in Shopify.\n\nRequired permission: Write. ", "x-permission": "Write", "parameters": [ { "name": "X-Shopify-Shop-Domain", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The key’s full *.myshopify.com hostname, without a scheme, path or port. Comparison ignores case and surrounding whitespace.", "example": "your-store.myshopify.com" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "\\S" }, "description": "Unique per logical create, across both create endpoints for this API key. Retries must use the same key and identical raw JSON bytes." } ], "responses": { "201": { "description": "Created; replays return the original status and body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualGroup" }, "example": { "id": 42, "name": "Everyday totes", "variants": [ { "product_gid": "gid://shopify/Product/100", "variant_gid": "gid://shopify/ProductVariant/1001", "inventory_item_gid": "gid://shopify/InventoryItem/2001", "product_title": "Everyday tote", "variant_title": "Natural" }, { "product_gid": "gid://shopify/Product/101", "variant_gid": "gid://shopify/ProductVariant/1002", "inventory_item_gid": "gid://shopify/InventoryItem/2002", "product_title": "Everyday tote — gift listing", "variant_title": "Natural" } ], "status": "active", "created_at": "2026-10-12T08:00:00Z", "updated_at": "2026-10-12T08:00:00Z" } } } }, "400": { "description": "shop_domain_required: Send a nonblank X-Shopify-Shop-Domain header. idempotency_key_required: Send Idempotency-Key when creating a manual or bundle group.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_required": { "value": { "error": { "code": "shop_domain_required", "message": "Send a nonblank X-Shopify-Shop-Domain header." } } }, "idempotency_key_required": { "value": { "error": { "code": "idempotency_key_required", "message": "Send Idempotency-Key when creating a manual or bundle group." } } } } } } }, "401": { "description": "invalid_key: The bearer key is missing, unknown, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_key": { "value": { "error": { "code": "invalid_key", "message": "The bearer key is missing, unknown, or revoked." } } } } } } }, "402": { "description": "plan_required: The shop needs an active Advance entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "The shop needs an active Advance entitlement." } } } } } } }, "403": { "description": "shop_domain_mismatch: The supplied domain does not match the key’s shop. permission_required: The key lacks Write or Delete permission for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_mismatch": { "value": { "error": { "code": "shop_domain_mismatch", "message": "The supplied domain does not match the key’s shop." } } }, "permission_required": { "value": { "error": { "code": "permission_required", "message": "The key lacks Write or Delete permission for this operation." } } } } } } }, "409": { "description": "idempotency_conflict: This API key already used the Idempotency-Key with different raw request bytes. idempotency_in_progress: A create with this Idempotency-Key is still running. Retry later with the same key and body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_conflict": { "value": { "error": { "code": "idempotency_conflict", "message": "This API key already used the Idempotency-Key with different raw request bytes." } } }, "idempotency_in_progress": { "value": { "error": { "code": "idempotency_in_progress", "message": "A create with this Idempotency-Key is still running. Retry later with the same key and body." } } } } } } }, "422": { "description": "validation_failed: Invalid JSON, request fields, group membership, or pagination cursor. Read error.message for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "validation_failed": { "value": { "error": { "code": "validation_failed", "message": "Invalid JSON, request fields, group membership, or pagination cursor. Read error.message for the reason." } } } } } } }, "429": { "description": "rate_limited: The shop’s shared request allowance is exhausted. Wait for Retry-After (60 seconds).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "value": { "error": { "code": "rate_limited", "message": "API rate limit exceeded. Retry after 60 seconds." } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "const": 60 }, "description": "Wait 60 seconds before retrying." }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "503": { "description": "rate_limit_unavailable: The rate limit could not be checked; the action did not run. Retry later. shopify_unavailable: Shopify could not be reached while checking the subscription. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_unavailable": { "value": { "error": { "code": "rate_limit_unavailable", "message": "The rate limit could not be checked; the action did not run. Retry later." } } }, "shopify_unavailable": { "value": { "error": { "code": "shopify_unavailable", "message": "Shopify could not be reached while checking the subscription. Retry later." } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualInput" }, "example": { "name": "Everyday totes", "variants": [ { "product_gid": "gid://shopify/Product/100", "variant_gid": "gid://shopify/ProductVariant/1001", "inventory_item_gid": "gid://shopify/InventoryItem/2001", "product_title": "Everyday tote", "variant_title": "Natural" }, { "product_gid": "gid://shopify/Product/101", "variant_gid": "gid://shopify/ProductVariant/1002", "inventory_item_gid": "gid://shopify/InventoryItem/2002", "product_title": "Everyday tote — gift listing", "variant_title": "Natural" } ] } } } } } }, "/manual_groups/{id}": { "get": { "operationId": "get-manual-groups", "tags": [ "Manual groups" ], "summary": "Get a manual group", "description": "Return one group and every saved member belonging to the authenticated shop.\n\nRequired permission: Read. ", "x-permission": "Read", "parameters": [ { "name": "X-Shopify-Shop-Domain", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The key’s full *.myshopify.com hostname, without a scheme, path or port. Comparison ignores case and surrounding whitespace.", "example": "your-store.myshopify.com" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Connected Inventory resource ID, not a Shopify ID." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualGroup" }, "example": { "id": 42, "name": "Everyday totes", "variants": [ { "product_gid": "gid://shopify/Product/100", "variant_gid": "gid://shopify/ProductVariant/1001", "inventory_item_gid": "gid://shopify/InventoryItem/2001", "product_title": "Everyday tote", "variant_title": "Natural" }, { "product_gid": "gid://shopify/Product/101", "variant_gid": "gid://shopify/ProductVariant/1002", "inventory_item_gid": "gid://shopify/InventoryItem/2002", "product_title": "Everyday tote — gift listing", "variant_title": "Natural" } ], "status": "active", "created_at": "2026-10-12T08:00:00Z", "updated_at": "2026-10-12T08:00:00Z" } } } }, "400": { "description": "shop_domain_required: Send a nonblank X-Shopify-Shop-Domain header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_required": { "value": { "error": { "code": "shop_domain_required", "message": "Send a nonblank X-Shopify-Shop-Domain header." } } } } } } }, "401": { "description": "invalid_key: The bearer key is missing, unknown, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_key": { "value": { "error": { "code": "invalid_key", "message": "The bearer key is missing, unknown, or revoked." } } } } } } }, "402": { "description": "plan_required: The shop needs an active Advance entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "The shop needs an active Advance entitlement." } } } } } } }, "403": { "description": "shop_domain_mismatch: The supplied domain does not match the key’s shop.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_mismatch": { "value": { "error": { "code": "shop_domain_mismatch", "message": "The supplied domain does not match the key’s shop." } } } } } } }, "404": { "description": "not_found: The resource does not exist in this shop. Another shop’s resource is also reported as not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "value": { "error": { "code": "not_found", "message": "The resource does not exist in this shop. Another shop’s resource is also reported as not found." } } } } } } }, "429": { "description": "rate_limited: The shop’s shared request allowance is exhausted. Wait for Retry-After (60 seconds).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "value": { "error": { "code": "rate_limited", "message": "API rate limit exceeded. Retry after 60 seconds." } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "const": 60 }, "description": "Wait 60 seconds before retrying." }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "503": { "description": "rate_limit_unavailable: The rate limit could not be checked; the action did not run. Retry later. shopify_unavailable: Shopify could not be reached while checking the subscription. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_unavailable": { "value": { "error": { "code": "rate_limit_unavailable", "message": "The rate limit could not be checked; the action did not run. Retry later." } } }, "shopify_unavailable": { "value": { "error": { "code": "shopify_unavailable", "message": "Shopify could not be reached while checking the subscription. Retry later." } } } } } } } } }, "put": { "operationId": "replace-manual-groups", "tags": [ "Manual groups" ], "summary": "Replace a manual group", "description": "Replace the complete group name and membership. Send all desired members; omitted members are removed. This is not a partial update.\n\nRequired permission: Write. ", "x-permission": "Write", "parameters": [ { "name": "X-Shopify-Shop-Domain", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The key’s full *.myshopify.com hostname, without a scheme, path or port. Comparison ignores case and surrounding whitespace.", "example": "your-store.myshopify.com" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Connected Inventory resource ID, not a Shopify ID." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualGroup" }, "example": { "id": 42, "name": "Everyday totes", "variants": [ { "product_gid": "gid://shopify/Product/100", "variant_gid": "gid://shopify/ProductVariant/1001", "inventory_item_gid": "gid://shopify/InventoryItem/2001", "product_title": "Everyday tote", "variant_title": "Natural" }, { "product_gid": "gid://shopify/Product/101", "variant_gid": "gid://shopify/ProductVariant/1002", "inventory_item_gid": "gid://shopify/InventoryItem/2002", "product_title": "Everyday tote — gift listing", "variant_title": "Natural" } ], "status": "active", "created_at": "2026-10-12T08:00:00Z", "updated_at": "2026-10-12T08:00:00Z" } } } }, "400": { "description": "shop_domain_required: Send a nonblank X-Shopify-Shop-Domain header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_required": { "value": { "error": { "code": "shop_domain_required", "message": "Send a nonblank X-Shopify-Shop-Domain header." } } } } } } }, "401": { "description": "invalid_key: The bearer key is missing, unknown, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_key": { "value": { "error": { "code": "invalid_key", "message": "The bearer key is missing, unknown, or revoked." } } } } } } }, "402": { "description": "plan_required: The shop needs an active Advance entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "The shop needs an active Advance entitlement." } } } } } } }, "403": { "description": "shop_domain_mismatch: The supplied domain does not match the key’s shop. permission_required: The key lacks Write or Delete permission for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_mismatch": { "value": { "error": { "code": "shop_domain_mismatch", "message": "The supplied domain does not match the key’s shop." } } }, "permission_required": { "value": { "error": { "code": "permission_required", "message": "The key lacks Write or Delete permission for this operation." } } } } } } }, "404": { "description": "not_found: The resource does not exist in this shop. Another shop’s resource is also reported as not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "value": { "error": { "code": "not_found", "message": "The resource does not exist in this shop. Another shop’s resource is also reported as not found." } } } } } } }, "422": { "description": "validation_failed: Invalid JSON, request fields, group membership, or pagination cursor. Read error.message for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "validation_failed": { "value": { "error": { "code": "validation_failed", "message": "Invalid JSON, request fields, group membership, or pagination cursor. Read error.message for the reason." } } } } } } }, "429": { "description": "rate_limited: The shop’s shared request allowance is exhausted. Wait for Retry-After (60 seconds).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "value": { "error": { "code": "rate_limited", "message": "API rate limit exceeded. Retry after 60 seconds." } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "const": 60 }, "description": "Wait 60 seconds before retrying." }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "503": { "description": "rate_limit_unavailable: The rate limit could not be checked; the action did not run. Retry later. shopify_unavailable: Shopify could not be reached while checking the subscription. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_unavailable": { "value": { "error": { "code": "rate_limit_unavailable", "message": "The rate limit could not be checked; the action did not run. Retry later." } } }, "shopify_unavailable": { "value": { "error": { "code": "shopify_unavailable", "message": "Shopify could not be reached while checking the subscription. Retry later." } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualInput" }, "example": { "name": "Everyday totes", "variants": [ { "product_gid": "gid://shopify/Product/100", "variant_gid": "gid://shopify/ProductVariant/1001", "inventory_item_gid": "gid://shopify/InventoryItem/2001", "product_title": "Everyday tote", "variant_title": "Natural" }, { "product_gid": "gid://shopify/Product/101", "variant_gid": "gid://shopify/ProductVariant/1002", "inventory_item_gid": "gid://shopify/InventoryItem/2002", "product_title": "Everyday tote — gift listing", "variant_title": "Natural" } ] } } } } }, "delete": { "operationId": "delete-manual-groups", "tags": [ "Manual groups" ], "summary": "Delete a manual group", "description": "Delete this group and its membership records. Shopify products and variants are not deleted. There is no response body.\n\nRequired permission: Delete. ", "x-permission": "Delete", "parameters": [ { "name": "X-Shopify-Shop-Domain", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The key’s full *.myshopify.com hostname, without a scheme, path or port. Comparison ignores case and surrounding whitespace.", "example": "your-store.myshopify.com" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Connected Inventory resource ID, not a Shopify ID." } ], "responses": { "204": { "description": "Deleted; no body." }, "400": { "description": "shop_domain_required: Send a nonblank X-Shopify-Shop-Domain header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_required": { "value": { "error": { "code": "shop_domain_required", "message": "Send a nonblank X-Shopify-Shop-Domain header." } } } } } } }, "401": { "description": "invalid_key: The bearer key is missing, unknown, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_key": { "value": { "error": { "code": "invalid_key", "message": "The bearer key is missing, unknown, or revoked." } } } } } } }, "402": { "description": "plan_required: The shop needs an active Advance entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "The shop needs an active Advance entitlement." } } } } } } }, "403": { "description": "shop_domain_mismatch: The supplied domain does not match the key’s shop. permission_required: The key lacks Write or Delete permission for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_mismatch": { "value": { "error": { "code": "shop_domain_mismatch", "message": "The supplied domain does not match the key’s shop." } } }, "permission_required": { "value": { "error": { "code": "permission_required", "message": "The key lacks Write or Delete permission for this operation." } } } } } } }, "404": { "description": "not_found: The resource does not exist in this shop. Another shop’s resource is also reported as not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "value": { "error": { "code": "not_found", "message": "The resource does not exist in this shop. Another shop’s resource is also reported as not found." } } } } } } }, "429": { "description": "rate_limited: The shop’s shared request allowance is exhausted. Wait for Retry-After (60 seconds).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "value": { "error": { "code": "rate_limited", "message": "API rate limit exceeded. Retry after 60 seconds." } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "const": 60 }, "description": "Wait 60 seconds before retrying." }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "503": { "description": "rate_limit_unavailable: The rate limit could not be checked; the action did not run. Retry later. shopify_unavailable: Shopify could not be reached while checking the subscription. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_unavailable": { "value": { "error": { "code": "rate_limit_unavailable", "message": "The rate limit could not be checked; the action did not run. Retry later." } } }, "shopify_unavailable": { "value": { "error": { "code": "shopify_unavailable", "message": "Shopify could not be reached while checking the subscription. Retry later." } } } } } } } } } }, "/manual_groups/status": { "get": { "operationId": "status-manual-groups", "tags": [ "Manual groups" ], "summary": "Read manual-group status", "description": "Read the shop-wide enabled setting for this group type.\n\nRequired permission: Read. ", "x-permission": "Read", "parameters": [ { "name": "X-Shopify-Shop-Domain", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The key’s full *.myshopify.com hostname, without a scheme, path or port. Comparison ignores case and surrounding whitespace.", "example": "your-store.myshopify.com" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Enabled" }, "example": { "enabled": true } } } }, "400": { "description": "shop_domain_required: Send a nonblank X-Shopify-Shop-Domain header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_required": { "value": { "error": { "code": "shop_domain_required", "message": "Send a nonblank X-Shopify-Shop-Domain header." } } } } } } }, "401": { "description": "invalid_key: The bearer key is missing, unknown, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_key": { "value": { "error": { "code": "invalid_key", "message": "The bearer key is missing, unknown, or revoked." } } } } } } }, "402": { "description": "plan_required: The shop needs an active Advance entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "The shop needs an active Advance entitlement." } } } } } } }, "403": { "description": "shop_domain_mismatch: The supplied domain does not match the key’s shop.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_mismatch": { "value": { "error": { "code": "shop_domain_mismatch", "message": "The supplied domain does not match the key’s shop." } } } } } } }, "429": { "description": "rate_limited: The shop’s shared request allowance is exhausted. Wait for Retry-After (60 seconds).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "value": { "error": { "code": "rate_limited", "message": "API rate limit exceeded. Retry after 60 seconds." } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "const": 60 }, "description": "Wait 60 seconds before retrying." }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "503": { "description": "rate_limit_unavailable: The rate limit could not be checked; the action did not run. Retry later. shopify_unavailable: Shopify could not be reached while checking the subscription. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_unavailable": { "value": { "error": { "code": "rate_limit_unavailable", "message": "The rate limit could not be checked; the action did not run. Retry later." } } }, "shopify_unavailable": { "value": { "error": { "code": "shopify_unavailable", "message": "Shopify could not be reached while checking the subscription. Retry later." } } } } } } } } } }, "/manual_groups/enable": { "put": { "operationId": "enable-manual-groups", "tags": [ "Manual groups" ], "summary": "Enable manual groups", "description": "Enable this group type for the shop. Repeating the request leaves the setting enabled. No request body is required.\n\nRequired permission: Write. ", "x-permission": "Write", "parameters": [ { "name": "X-Shopify-Shop-Domain", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The key’s full *.myshopify.com hostname, without a scheme, path or port. Comparison ignores case and surrounding whitespace.", "example": "your-store.myshopify.com" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Enabled" }, "example": { "enabled": true } } } }, "400": { "description": "shop_domain_required: Send a nonblank X-Shopify-Shop-Domain header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_required": { "value": { "error": { "code": "shop_domain_required", "message": "Send a nonblank X-Shopify-Shop-Domain header." } } } } } } }, "401": { "description": "invalid_key: The bearer key is missing, unknown, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_key": { "value": { "error": { "code": "invalid_key", "message": "The bearer key is missing, unknown, or revoked." } } } } } } }, "402": { "description": "plan_required: The shop needs an active Advance entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "The shop needs an active Advance entitlement." } } } } } } }, "403": { "description": "shop_domain_mismatch: The supplied domain does not match the key’s shop. permission_required: The key lacks Write or Delete permission for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_mismatch": { "value": { "error": { "code": "shop_domain_mismatch", "message": "The supplied domain does not match the key’s shop." } } }, "permission_required": { "value": { "error": { "code": "permission_required", "message": "The key lacks Write or Delete permission for this operation." } } } } } } }, "429": { "description": "rate_limited: The shop’s shared request allowance is exhausted. Wait for Retry-After (60 seconds).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "value": { "error": { "code": "rate_limited", "message": "API rate limit exceeded. Retry after 60 seconds." } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "const": 60 }, "description": "Wait 60 seconds before retrying." }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "503": { "description": "rate_limit_unavailable: The rate limit could not be checked; the action did not run. Retry later. shopify_unavailable: Shopify could not be reached while checking the subscription. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_unavailable": { "value": { "error": { "code": "rate_limit_unavailable", "message": "The rate limit could not be checked; the action did not run. Retry later." } } }, "shopify_unavailable": { "value": { "error": { "code": "shopify_unavailable", "message": "Shopify could not be reached while checking the subscription. Retry later." } } } } } } } } } }, "/manual_groups/disable": { "put": { "operationId": "disable-manual-groups", "tags": [ "Manual groups" ], "summary": "Disable manual groups", "description": "Disable this group type for the shop. Existing groups and members are retained. No request body is required.\n\nRequired permission: Delete. ", "x-permission": "Delete", "parameters": [ { "name": "X-Shopify-Shop-Domain", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The key’s full *.myshopify.com hostname, without a scheme, path or port. Comparison ignores case and surrounding whitespace.", "example": "your-store.myshopify.com" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Enabled" }, "example": { "enabled": false } } } }, "400": { "description": "shop_domain_required: Send a nonblank X-Shopify-Shop-Domain header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_required": { "value": { "error": { "code": "shop_domain_required", "message": "Send a nonblank X-Shopify-Shop-Domain header." } } } } } } }, "401": { "description": "invalid_key: The bearer key is missing, unknown, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_key": { "value": { "error": { "code": "invalid_key", "message": "The bearer key is missing, unknown, or revoked." } } } } } } }, "402": { "description": "plan_required: The shop needs an active Advance entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "The shop needs an active Advance entitlement." } } } } } } }, "403": { "description": "shop_domain_mismatch: The supplied domain does not match the key’s shop. permission_required: The key lacks Write or Delete permission for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_mismatch": { "value": { "error": { "code": "shop_domain_mismatch", "message": "The supplied domain does not match the key’s shop." } } }, "permission_required": { "value": { "error": { "code": "permission_required", "message": "The key lacks Write or Delete permission for this operation." } } } } } } }, "429": { "description": "rate_limited: The shop’s shared request allowance is exhausted. Wait for Retry-After (60 seconds).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "value": { "error": { "code": "rate_limited", "message": "API rate limit exceeded. Retry after 60 seconds." } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "const": 60 }, "description": "Wait 60 seconds before retrying." }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "503": { "description": "rate_limit_unavailable: The rate limit could not be checked; the action did not run. Retry later. shopify_unavailable: Shopify could not be reached while checking the subscription. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_unavailable": { "value": { "error": { "code": "rate_limit_unavailable", "message": "The rate limit could not be checked; the action did not run. Retry later." } } }, "shopify_unavailable": { "value": { "error": { "code": "shopify_unavailable", "message": "Shopify could not be reached while checking the subscription. Retry later." } } } } } } } } } }, "/bundle_groups": { "get": { "operationId": "list-bundle-groups", "tags": [ "Bundle groups" ], "summary": "List bundle groups", "description": "Return group summaries in descending ID order. Fetch a group by ID to read its members.\n\nRequired permission: Read. ", "x-permission": "Read", "parameters": [ { "name": "X-Shopify-Shop-Domain", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The key’s full *.myshopify.com hostname, without a scheme, path or port. Comparison ignores case and surrounding whitespace.", "example": "your-store.myshopify.com" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Default 50, capped at 200. Nonpositive or nonnumeric values fall back to 50." }, { "name": "after", "in": "query", "schema": { "type": "string" }, "description": "Opaque next_cursor from the previous page. Items are ordered by descending ID. Stop when next_cursor is null." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GroupSummary" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "example": { "data": [ { "id": 42, "name": "Tote duo", "status": "active", "created_at": "2026-10-12T08:00:00Z", "updated_at": "2026-10-12T08:00:00Z", "member_count": 2 } ], "next_cursor": null } } } }, "400": { "description": "shop_domain_required: Send a nonblank X-Shopify-Shop-Domain header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_required": { "value": { "error": { "code": "shop_domain_required", "message": "Send a nonblank X-Shopify-Shop-Domain header." } } } } } } }, "401": { "description": "invalid_key: The bearer key is missing, unknown, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_key": { "value": { "error": { "code": "invalid_key", "message": "The bearer key is missing, unknown, or revoked." } } } } } } }, "402": { "description": "plan_required: The shop needs an active Advance entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "The shop needs an active Advance entitlement." } } } } } } }, "403": { "description": "shop_domain_mismatch: The supplied domain does not match the key’s shop.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_mismatch": { "value": { "error": { "code": "shop_domain_mismatch", "message": "The supplied domain does not match the key’s shop." } } } } } } }, "422": { "description": "validation_failed: Invalid JSON, request fields, group membership, or pagination cursor. Read error.message for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "validation_failed": { "value": { "error": { "code": "validation_failed", "message": "Invalid JSON, request fields, group membership, or pagination cursor. Read error.message for the reason." } } } } } } }, "429": { "description": "rate_limited: The shop’s shared request allowance is exhausted. Wait for Retry-After (60 seconds).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "value": { "error": { "code": "rate_limited", "message": "API rate limit exceeded. Retry after 60 seconds." } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "const": 60 }, "description": "Wait 60 seconds before retrying." }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "503": { "description": "rate_limit_unavailable: The rate limit could not be checked; the action did not run. Retry later. shopify_unavailable: Shopify could not be reached while checking the subscription. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_unavailable": { "value": { "error": { "code": "rate_limit_unavailable", "message": "The rate limit could not be checked; the action did not run. Retry later." } } }, "shopify_unavailable": { "value": { "error": { "code": "shopify_unavailable", "message": "Shopify could not be reached while checking the subscription. Retry later." } } } } } } } } }, "post": { "operationId": "create-bundle-groups", "tags": [ "Bundle groups" ], "summary": "Create a bundle group", "description": "Create a group using the supplied variant metadata. This does not look up or verify the variants in Shopify.\n\nRequired permission: Write. ", "x-permission": "Write", "parameters": [ { "name": "X-Shopify-Shop-Domain", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The key’s full *.myshopify.com hostname, without a scheme, path or port. Comparison ignores case and surrounding whitespace.", "example": "your-store.myshopify.com" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "\\S" }, "description": "Unique per logical create, across both create endpoints for this API key. Retries must use the same key and identical raw JSON bytes." } ], "responses": { "201": { "description": "Created; replays return the original status and body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleGroup" }, "example": { "id": 42, "name": "Tote duo", "master": { "product_gid": "gid://shopify/Product/101", "variant_gid": "gid://shopify/ProductVariant/1002", "inventory_item_gid": "gid://shopify/InventoryItem/2002", "product_title": "Tote duo", "variant_title": "Default Title" }, "components": [ { "product_gid": "gid://shopify/Product/100", "variant_gid": "gid://shopify/ProductVariant/1001", "inventory_item_gid": "gid://shopify/InventoryItem/2001", "product_title": "Everyday tote", "variant_title": "Natural", "quantity": 2 } ], "status": "active", "created_at": "2026-10-12T08:00:00Z", "updated_at": "2026-10-12T08:00:00Z" } } } }, "400": { "description": "shop_domain_required: Send a nonblank X-Shopify-Shop-Domain header. idempotency_key_required: Send Idempotency-Key when creating a manual or bundle group.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_required": { "value": { "error": { "code": "shop_domain_required", "message": "Send a nonblank X-Shopify-Shop-Domain header." } } }, "idempotency_key_required": { "value": { "error": { "code": "idempotency_key_required", "message": "Send Idempotency-Key when creating a manual or bundle group." } } } } } } }, "401": { "description": "invalid_key: The bearer key is missing, unknown, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_key": { "value": { "error": { "code": "invalid_key", "message": "The bearer key is missing, unknown, or revoked." } } } } } } }, "402": { "description": "plan_required: The shop needs an active Advance entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "The shop needs an active Advance entitlement." } } } } } } }, "403": { "description": "shop_domain_mismatch: The supplied domain does not match the key’s shop. permission_required: The key lacks Write or Delete permission for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_mismatch": { "value": { "error": { "code": "shop_domain_mismatch", "message": "The supplied domain does not match the key’s shop." } } }, "permission_required": { "value": { "error": { "code": "permission_required", "message": "The key lacks Write or Delete permission for this operation." } } } } } } }, "409": { "description": "idempotency_conflict: This API key already used the Idempotency-Key with different raw request bytes. idempotency_in_progress: A create with this Idempotency-Key is still running. Retry later with the same key and body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_conflict": { "value": { "error": { "code": "idempotency_conflict", "message": "This API key already used the Idempotency-Key with different raw request bytes." } } }, "idempotency_in_progress": { "value": { "error": { "code": "idempotency_in_progress", "message": "A create with this Idempotency-Key is still running. Retry later with the same key and body." } } } } } } }, "422": { "description": "validation_failed: Invalid JSON, request fields, group membership, or pagination cursor. Read error.message for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "validation_failed": { "value": { "error": { "code": "validation_failed", "message": "Invalid JSON, request fields, group membership, or pagination cursor. Read error.message for the reason." } } } } } } }, "429": { "description": "rate_limited: The shop’s shared request allowance is exhausted. Wait for Retry-After (60 seconds).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "value": { "error": { "code": "rate_limited", "message": "API rate limit exceeded. Retry after 60 seconds." } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "const": 60 }, "description": "Wait 60 seconds before retrying." }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "503": { "description": "rate_limit_unavailable: The rate limit could not be checked; the action did not run. Retry later. shopify_unavailable: Shopify could not be reached while checking the subscription. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_unavailable": { "value": { "error": { "code": "rate_limit_unavailable", "message": "The rate limit could not be checked; the action did not run. Retry later." } } }, "shopify_unavailable": { "value": { "error": { "code": "shopify_unavailable", "message": "Shopify could not be reached while checking the subscription. Retry later." } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleInput" }, "example": { "name": "Tote duo", "master": { "product_gid": "gid://shopify/Product/101", "variant_gid": "gid://shopify/ProductVariant/1002", "inventory_item_gid": "gid://shopify/InventoryItem/2002", "product_title": "Tote duo", "variant_title": "Default Title" }, "components": [ { "product_gid": "gid://shopify/Product/100", "variant_gid": "gid://shopify/ProductVariant/1001", "inventory_item_gid": "gid://shopify/InventoryItem/2001", "product_title": "Everyday tote", "variant_title": "Natural", "quantity": 2 } ] } } } } } }, "/bundle_groups/{id}": { "get": { "operationId": "get-bundle-groups", "tags": [ "Bundle groups" ], "summary": "Get a bundle group", "description": "Return one group and every saved member belonging to the authenticated shop.\n\nRequired permission: Read. ", "x-permission": "Read", "parameters": [ { "name": "X-Shopify-Shop-Domain", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The key’s full *.myshopify.com hostname, without a scheme, path or port. Comparison ignores case and surrounding whitespace.", "example": "your-store.myshopify.com" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Connected Inventory resource ID, not a Shopify ID." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleGroup" }, "example": { "id": 42, "name": "Tote duo", "master": { "product_gid": "gid://shopify/Product/101", "variant_gid": "gid://shopify/ProductVariant/1002", "inventory_item_gid": "gid://shopify/InventoryItem/2002", "product_title": "Tote duo", "variant_title": "Default Title" }, "components": [ { "product_gid": "gid://shopify/Product/100", "variant_gid": "gid://shopify/ProductVariant/1001", "inventory_item_gid": "gid://shopify/InventoryItem/2001", "product_title": "Everyday tote", "variant_title": "Natural", "quantity": 2 } ], "status": "active", "created_at": "2026-10-12T08:00:00Z", "updated_at": "2026-10-12T08:00:00Z" } } } }, "400": { "description": "shop_domain_required: Send a nonblank X-Shopify-Shop-Domain header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_required": { "value": { "error": { "code": "shop_domain_required", "message": "Send a nonblank X-Shopify-Shop-Domain header." } } } } } } }, "401": { "description": "invalid_key: The bearer key is missing, unknown, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_key": { "value": { "error": { "code": "invalid_key", "message": "The bearer key is missing, unknown, or revoked." } } } } } } }, "402": { "description": "plan_required: The shop needs an active Advance entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "The shop needs an active Advance entitlement." } } } } } } }, "403": { "description": "shop_domain_mismatch: The supplied domain does not match the key’s shop.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_mismatch": { "value": { "error": { "code": "shop_domain_mismatch", "message": "The supplied domain does not match the key’s shop." } } } } } } }, "404": { "description": "not_found: The resource does not exist in this shop. Another shop’s resource is also reported as not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "value": { "error": { "code": "not_found", "message": "The resource does not exist in this shop. Another shop’s resource is also reported as not found." } } } } } } }, "429": { "description": "rate_limited: The shop’s shared request allowance is exhausted. Wait for Retry-After (60 seconds).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "value": { "error": { "code": "rate_limited", "message": "API rate limit exceeded. Retry after 60 seconds." } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "const": 60 }, "description": "Wait 60 seconds before retrying." }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "503": { "description": "rate_limit_unavailable: The rate limit could not be checked; the action did not run. Retry later. shopify_unavailable: Shopify could not be reached while checking the subscription. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_unavailable": { "value": { "error": { "code": "rate_limit_unavailable", "message": "The rate limit could not be checked; the action did not run. Retry later." } } }, "shopify_unavailable": { "value": { "error": { "code": "shopify_unavailable", "message": "Shopify could not be reached while checking the subscription. Retry later." } } } } } } } } }, "put": { "operationId": "replace-bundle-groups", "tags": [ "Bundle groups" ], "summary": "Replace a bundle group", "description": "Replace the complete group name and membership. Send all desired members; omitted members are removed. This is not a partial update.\n\nRequired permission: Write. ", "x-permission": "Write", "parameters": [ { "name": "X-Shopify-Shop-Domain", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The key’s full *.myshopify.com hostname, without a scheme, path or port. Comparison ignores case and surrounding whitespace.", "example": "your-store.myshopify.com" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Connected Inventory resource ID, not a Shopify ID." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleGroup" }, "example": { "id": 42, "name": "Tote duo", "master": { "product_gid": "gid://shopify/Product/101", "variant_gid": "gid://shopify/ProductVariant/1002", "inventory_item_gid": "gid://shopify/InventoryItem/2002", "product_title": "Tote duo", "variant_title": "Default Title" }, "components": [ { "product_gid": "gid://shopify/Product/100", "variant_gid": "gid://shopify/ProductVariant/1001", "inventory_item_gid": "gid://shopify/InventoryItem/2001", "product_title": "Everyday tote", "variant_title": "Natural", "quantity": 2 } ], "status": "active", "created_at": "2026-10-12T08:00:00Z", "updated_at": "2026-10-12T08:00:00Z" } } } }, "400": { "description": "shop_domain_required: Send a nonblank X-Shopify-Shop-Domain header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_required": { "value": { "error": { "code": "shop_domain_required", "message": "Send a nonblank X-Shopify-Shop-Domain header." } } } } } } }, "401": { "description": "invalid_key: The bearer key is missing, unknown, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_key": { "value": { "error": { "code": "invalid_key", "message": "The bearer key is missing, unknown, or revoked." } } } } } } }, "402": { "description": "plan_required: The shop needs an active Advance entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "The shop needs an active Advance entitlement." } } } } } } }, "403": { "description": "shop_domain_mismatch: The supplied domain does not match the key’s shop. permission_required: The key lacks Write or Delete permission for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_mismatch": { "value": { "error": { "code": "shop_domain_mismatch", "message": "The supplied domain does not match the key’s shop." } } }, "permission_required": { "value": { "error": { "code": "permission_required", "message": "The key lacks Write or Delete permission for this operation." } } } } } } }, "404": { "description": "not_found: The resource does not exist in this shop. Another shop’s resource is also reported as not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "value": { "error": { "code": "not_found", "message": "The resource does not exist in this shop. Another shop’s resource is also reported as not found." } } } } } } }, "422": { "description": "validation_failed: Invalid JSON, request fields, group membership, or pagination cursor. Read error.message for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "validation_failed": { "value": { "error": { "code": "validation_failed", "message": "Invalid JSON, request fields, group membership, or pagination cursor. Read error.message for the reason." } } } } } } }, "429": { "description": "rate_limited: The shop’s shared request allowance is exhausted. Wait for Retry-After (60 seconds).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "value": { "error": { "code": "rate_limited", "message": "API rate limit exceeded. Retry after 60 seconds." } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "const": 60 }, "description": "Wait 60 seconds before retrying." }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "503": { "description": "rate_limit_unavailable: The rate limit could not be checked; the action did not run. Retry later. shopify_unavailable: Shopify could not be reached while checking the subscription. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_unavailable": { "value": { "error": { "code": "rate_limit_unavailable", "message": "The rate limit could not be checked; the action did not run. Retry later." } } }, "shopify_unavailable": { "value": { "error": { "code": "shopify_unavailable", "message": "Shopify could not be reached while checking the subscription. Retry later." } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleInput" }, "example": { "name": "Tote duo", "master": { "product_gid": "gid://shopify/Product/101", "variant_gid": "gid://shopify/ProductVariant/1002", "inventory_item_gid": "gid://shopify/InventoryItem/2002", "product_title": "Tote duo", "variant_title": "Default Title" }, "components": [ { "product_gid": "gid://shopify/Product/100", "variant_gid": "gid://shopify/ProductVariant/1001", "inventory_item_gid": "gid://shopify/InventoryItem/2001", "product_title": "Everyday tote", "variant_title": "Natural", "quantity": 2 } ] } } } } }, "delete": { "operationId": "delete-bundle-groups", "tags": [ "Bundle groups" ], "summary": "Delete a bundle group", "description": "Delete this group and its membership records. Shopify products and variants are not deleted. There is no response body.\n\nRequired permission: Delete. ", "x-permission": "Delete", "parameters": [ { "name": "X-Shopify-Shop-Domain", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The key’s full *.myshopify.com hostname, without a scheme, path or port. Comparison ignores case and surrounding whitespace.", "example": "your-store.myshopify.com" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Connected Inventory resource ID, not a Shopify ID." } ], "responses": { "204": { "description": "Deleted; no body." }, "400": { "description": "shop_domain_required: Send a nonblank X-Shopify-Shop-Domain header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_required": { "value": { "error": { "code": "shop_domain_required", "message": "Send a nonblank X-Shopify-Shop-Domain header." } } } } } } }, "401": { "description": "invalid_key: The bearer key is missing, unknown, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_key": { "value": { "error": { "code": "invalid_key", "message": "The bearer key is missing, unknown, or revoked." } } } } } } }, "402": { "description": "plan_required: The shop needs an active Advance entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "The shop needs an active Advance entitlement." } } } } } } }, "403": { "description": "shop_domain_mismatch: The supplied domain does not match the key’s shop. permission_required: The key lacks Write or Delete permission for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_mismatch": { "value": { "error": { "code": "shop_domain_mismatch", "message": "The supplied domain does not match the key’s shop." } } }, "permission_required": { "value": { "error": { "code": "permission_required", "message": "The key lacks Write or Delete permission for this operation." } } } } } } }, "404": { "description": "not_found: The resource does not exist in this shop. Another shop’s resource is also reported as not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "value": { "error": { "code": "not_found", "message": "The resource does not exist in this shop. Another shop’s resource is also reported as not found." } } } } } } }, "429": { "description": "rate_limited: The shop’s shared request allowance is exhausted. Wait for Retry-After (60 seconds).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "value": { "error": { "code": "rate_limited", "message": "API rate limit exceeded. Retry after 60 seconds." } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "const": 60 }, "description": "Wait 60 seconds before retrying." }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "503": { "description": "rate_limit_unavailable: The rate limit could not be checked; the action did not run. Retry later. shopify_unavailable: Shopify could not be reached while checking the subscription. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_unavailable": { "value": { "error": { "code": "rate_limit_unavailable", "message": "The rate limit could not be checked; the action did not run. Retry later." } } }, "shopify_unavailable": { "value": { "error": { "code": "shopify_unavailable", "message": "Shopify could not be reached while checking the subscription. Retry later." } } } } } } } } } }, "/bundle_groups/status": { "get": { "operationId": "status-bundle-groups", "tags": [ "Bundle groups" ], "summary": "Read bundle-group status", "description": "Read the shop-wide enabled setting for this group type.\n\nRequired permission: Read. ", "x-permission": "Read", "parameters": [ { "name": "X-Shopify-Shop-Domain", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The key’s full *.myshopify.com hostname, without a scheme, path or port. Comparison ignores case and surrounding whitespace.", "example": "your-store.myshopify.com" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Enabled" }, "example": { "enabled": true } } } }, "400": { "description": "shop_domain_required: Send a nonblank X-Shopify-Shop-Domain header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_required": { "value": { "error": { "code": "shop_domain_required", "message": "Send a nonblank X-Shopify-Shop-Domain header." } } } } } } }, "401": { "description": "invalid_key: The bearer key is missing, unknown, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_key": { "value": { "error": { "code": "invalid_key", "message": "The bearer key is missing, unknown, or revoked." } } } } } } }, "402": { "description": "plan_required: The shop needs an active Advance entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "The shop needs an active Advance entitlement." } } } } } } }, "403": { "description": "shop_domain_mismatch: The supplied domain does not match the key’s shop.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_mismatch": { "value": { "error": { "code": "shop_domain_mismatch", "message": "The supplied domain does not match the key’s shop." } } } } } } }, "429": { "description": "rate_limited: The shop’s shared request allowance is exhausted. Wait for Retry-After (60 seconds).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "value": { "error": { "code": "rate_limited", "message": "API rate limit exceeded. Retry after 60 seconds." } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "const": 60 }, "description": "Wait 60 seconds before retrying." }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "503": { "description": "rate_limit_unavailable: The rate limit could not be checked; the action did not run. Retry later. shopify_unavailable: Shopify could not be reached while checking the subscription. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_unavailable": { "value": { "error": { "code": "rate_limit_unavailable", "message": "The rate limit could not be checked; the action did not run. Retry later." } } }, "shopify_unavailable": { "value": { "error": { "code": "shopify_unavailable", "message": "Shopify could not be reached while checking the subscription. Retry later." } } } } } } } } } }, "/bundle_groups/enable": { "put": { "operationId": "enable-bundle-groups", "tags": [ "Bundle groups" ], "summary": "Enable bundle groups", "description": "Enable this group type for the shop. Repeating the request leaves the setting enabled. No request body is required.\n\nRequired permission: Write. ", "x-permission": "Write", "parameters": [ { "name": "X-Shopify-Shop-Domain", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The key’s full *.myshopify.com hostname, without a scheme, path or port. Comparison ignores case and surrounding whitespace.", "example": "your-store.myshopify.com" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Enabled" }, "example": { "enabled": true } } } }, "400": { "description": "shop_domain_required: Send a nonblank X-Shopify-Shop-Domain header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_required": { "value": { "error": { "code": "shop_domain_required", "message": "Send a nonblank X-Shopify-Shop-Domain header." } } } } } } }, "401": { "description": "invalid_key: The bearer key is missing, unknown, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_key": { "value": { "error": { "code": "invalid_key", "message": "The bearer key is missing, unknown, or revoked." } } } } } } }, "402": { "description": "plan_required: The shop needs an active Advance entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "The shop needs an active Advance entitlement." } } } } } } }, "403": { "description": "shop_domain_mismatch: The supplied domain does not match the key’s shop. permission_required: The key lacks Write or Delete permission for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_mismatch": { "value": { "error": { "code": "shop_domain_mismatch", "message": "The supplied domain does not match the key’s shop." } } }, "permission_required": { "value": { "error": { "code": "permission_required", "message": "The key lacks Write or Delete permission for this operation." } } } } } } }, "429": { "description": "rate_limited: The shop’s shared request allowance is exhausted. Wait for Retry-After (60 seconds).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "value": { "error": { "code": "rate_limited", "message": "API rate limit exceeded. Retry after 60 seconds." } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "const": 60 }, "description": "Wait 60 seconds before retrying." }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "503": { "description": "rate_limit_unavailable: The rate limit could not be checked; the action did not run. Retry later. shopify_unavailable: Shopify could not be reached while checking the subscription. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_unavailable": { "value": { "error": { "code": "rate_limit_unavailable", "message": "The rate limit could not be checked; the action did not run. Retry later." } } }, "shopify_unavailable": { "value": { "error": { "code": "shopify_unavailable", "message": "Shopify could not be reached while checking the subscription. Retry later." } } } } } } } } } }, "/bundle_groups/disable": { "put": { "operationId": "disable-bundle-groups", "tags": [ "Bundle groups" ], "summary": "Disable bundle groups", "description": "Disable this group type for the shop. Existing groups and members are retained. No request body is required.\n\nRequired permission: Delete. ", "x-permission": "Delete", "parameters": [ { "name": "X-Shopify-Shop-Domain", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The key’s full *.myshopify.com hostname, without a scheme, path or port. Comparison ignores case and surrounding whitespace.", "example": "your-store.myshopify.com" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Enabled" }, "example": { "enabled": false } } } }, "400": { "description": "shop_domain_required: Send a nonblank X-Shopify-Shop-Domain header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_required": { "value": { "error": { "code": "shop_domain_required", "message": "Send a nonblank X-Shopify-Shop-Domain header." } } } } } } }, "401": { "description": "invalid_key: The bearer key is missing, unknown, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_key": { "value": { "error": { "code": "invalid_key", "message": "The bearer key is missing, unknown, or revoked." } } } } } } }, "402": { "description": "plan_required: The shop needs an active Advance entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "The shop needs an active Advance entitlement." } } } } } } }, "403": { "description": "shop_domain_mismatch: The supplied domain does not match the key’s shop. permission_required: The key lacks Write or Delete permission for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_mismatch": { "value": { "error": { "code": "shop_domain_mismatch", "message": "The supplied domain does not match the key’s shop." } } }, "permission_required": { "value": { "error": { "code": "permission_required", "message": "The key lacks Write or Delete permission for this operation." } } } } } } }, "429": { "description": "rate_limited: The shop’s shared request allowance is exhausted. Wait for Retry-After (60 seconds).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "value": { "error": { "code": "rate_limited", "message": "API rate limit exceeded. Retry after 60 seconds." } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "const": 60 }, "description": "Wait 60 seconds before retrying." }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "503": { "description": "rate_limit_unavailable: The rate limit could not be checked; the action did not run. Retry later. shopify_unavailable: Shopify could not be reached while checking the subscription. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_unavailable": { "value": { "error": { "code": "rate_limit_unavailable", "message": "The rate limit could not be checked; the action did not run. Retry later." } } }, "shopify_unavailable": { "value": { "error": { "code": "shopify_unavailable", "message": "Shopify could not be reached while checking the subscription. Retry later." } } } } } } } } } }, "/auto_groups": { "get": { "operationId": "list-auto-groups", "tags": [ "Smart groups" ], "summary": "List smart groups", "description": "Return active smart-group summaries in descending ID order. The list does not include member details.\n\nRequired permission: Read. ", "x-permission": "Read", "parameters": [ { "name": "X-Shopify-Shop-Domain", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The key’s full *.myshopify.com hostname, without a scheme, path or port. Comparison ignores case and surrounding whitespace.", "example": "your-store.myshopify.com" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Default 50, capped at 200. Nonpositive or nonnumeric values fall back to 50." }, { "name": "after", "in": "query", "schema": { "type": "string" }, "description": "Opaque next_cursor from the previous page. Items are ordered by descending ID. Stop when next_cursor is null." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GroupSummary" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "example": { "data": [ { "id": 42, "name": "TOTE-NATURAL", "status": "active", "created_at": "2026-10-12T08:00:00Z", "updated_at": "2026-10-12T08:00:00Z", "member_count": 2 } ], "next_cursor": null } } } }, "400": { "description": "shop_domain_required: Send a nonblank X-Shopify-Shop-Domain header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_required": { "value": { "error": { "code": "shop_domain_required", "message": "Send a nonblank X-Shopify-Shop-Domain header." } } } } } } }, "401": { "description": "invalid_key: The bearer key is missing, unknown, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_key": { "value": { "error": { "code": "invalid_key", "message": "The bearer key is missing, unknown, or revoked." } } } } } } }, "402": { "description": "plan_required: The shop needs an active Advance entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "The shop needs an active Advance entitlement." } } } } } } }, "403": { "description": "shop_domain_mismatch: The supplied domain does not match the key’s shop.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_mismatch": { "value": { "error": { "code": "shop_domain_mismatch", "message": "The supplied domain does not match the key’s shop." } } } } } } }, "422": { "description": "validation_failed: Invalid JSON, request fields, group membership, or pagination cursor. Read error.message for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "validation_failed": { "value": { "error": { "code": "validation_failed", "message": "Invalid JSON, request fields, group membership, or pagination cursor. Read error.message for the reason." } } } } } } }, "429": { "description": "rate_limited: The shop’s shared request allowance is exhausted. Wait for Retry-After (60 seconds).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "value": { "error": { "code": "rate_limited", "message": "API rate limit exceeded. Retry after 60 seconds." } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "const": 60 }, "description": "Wait 60 seconds before retrying." }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "503": { "description": "rate_limit_unavailable: The rate limit could not be checked; the action did not run. Retry later. shopify_unavailable: Shopify could not be reached while checking the subscription. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_unavailable": { "value": { "error": { "code": "rate_limit_unavailable", "message": "The rate limit could not be checked; the action did not run. Retry later." } } }, "shopify_unavailable": { "value": { "error": { "code": "shopify_unavailable", "message": "Shopify could not be reached while checking the subscription. Retry later." } } } } } } } } } }, "/auto_groups/{id}": { "get": { "operationId": "get-auto-groups", "tags": [ "Smart groups" ], "summary": "Get a smart group", "description": "Read an active smart group and all of its saved members. Missing, inactive, and other shops’ groups return not_found.\n\nRequired permission: Read. ", "x-permission": "Read", "parameters": [ { "name": "X-Shopify-Shop-Domain", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The key’s full *.myshopify.com hostname, without a scheme, path or port. Comparison ignores case and surrounding whitespace.", "example": "your-store.myshopify.com" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Connected Inventory resource ID, not a Shopify ID." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualGroup" }, "example": { "id": 42, "name": "TOTE-NATURAL", "variants": [ { "product_gid": "gid://shopify/Product/100", "variant_gid": "gid://shopify/ProductVariant/1001", "inventory_item_gid": "gid://shopify/InventoryItem/2001", "product_title": "Everyday tote", "variant_title": "Natural" }, { "product_gid": "gid://shopify/Product/101", "variant_gid": "gid://shopify/ProductVariant/1002", "inventory_item_gid": "gid://shopify/InventoryItem/2002", "product_title": "Everyday tote — gift listing", "variant_title": "Natural" } ], "status": "active", "created_at": "2026-10-12T08:00:00Z", "updated_at": "2026-10-12T08:00:00Z" } } } }, "400": { "description": "shop_domain_required: Send a nonblank X-Shopify-Shop-Domain header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_required": { "value": { "error": { "code": "shop_domain_required", "message": "Send a nonblank X-Shopify-Shop-Domain header." } } } } } } }, "401": { "description": "invalid_key: The bearer key is missing, unknown, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_key": { "value": { "error": { "code": "invalid_key", "message": "The bearer key is missing, unknown, or revoked." } } } } } } }, "402": { "description": "plan_required: The shop needs an active Advance entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "The shop needs an active Advance entitlement." } } } } } } }, "403": { "description": "shop_domain_mismatch: The supplied domain does not match the key’s shop.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_mismatch": { "value": { "error": { "code": "shop_domain_mismatch", "message": "The supplied domain does not match the key’s shop." } } } } } } }, "404": { "description": "not_found: The resource does not exist in this shop. Another shop’s resource is also reported as not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "value": { "error": { "code": "not_found", "message": "The resource does not exist in this shop. Another shop’s resource is also reported as not found." } } } } } } }, "429": { "description": "rate_limited: The shop’s shared request allowance is exhausted. Wait for Retry-After (60 seconds).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "value": { "error": { "code": "rate_limited", "message": "API rate limit exceeded. Retry after 60 seconds." } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "const": 60 }, "description": "Wait 60 seconds before retrying." }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "503": { "description": "rate_limit_unavailable: The rate limit could not be checked; the action did not run. Retry later. shopify_unavailable: Shopify could not be reached while checking the subscription. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_unavailable": { "value": { "error": { "code": "rate_limit_unavailable", "message": "The rate limit could not be checked; the action did not run. Retry later." } } }, "shopify_unavailable": { "value": { "error": { "code": "shopify_unavailable", "message": "Shopify could not be reached while checking the subscription. Retry later." } } } } } } } } } }, "/auto_groups/status": { "get": { "operationId": "status-auto-groups", "tags": [ "Smart groups" ], "summary": "Read smart-group status", "description": "Read the shop-wide smart-group setting.\n\nRequired permission: Read. ", "x-permission": "Read", "parameters": [ { "name": "X-Shopify-Shop-Domain", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The key’s full *.myshopify.com hostname, without a scheme, path or port. Comparison ignores case and surrounding whitespace.", "example": "your-store.myshopify.com" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Enabled" }, "example": { "enabled": true } } } }, "400": { "description": "shop_domain_required: Send a nonblank X-Shopify-Shop-Domain header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_required": { "value": { "error": { "code": "shop_domain_required", "message": "Send a nonblank X-Shopify-Shop-Domain header." } } } } } } }, "401": { "description": "invalid_key: The bearer key is missing, unknown, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_key": { "value": { "error": { "code": "invalid_key", "message": "The bearer key is missing, unknown, or revoked." } } } } } } }, "402": { "description": "plan_required: The shop needs an active Advance entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "The shop needs an active Advance entitlement." } } } } } } }, "403": { "description": "shop_domain_mismatch: The supplied domain does not match the key’s shop.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_mismatch": { "value": { "error": { "code": "shop_domain_mismatch", "message": "The supplied domain does not match the key’s shop." } } } } } } }, "429": { "description": "rate_limited: The shop’s shared request allowance is exhausted. Wait for Retry-After (60 seconds).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "value": { "error": { "code": "rate_limited", "message": "API rate limit exceeded. Retry after 60 seconds." } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "const": 60 }, "description": "Wait 60 seconds before retrying." }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "503": { "description": "rate_limit_unavailable: The rate limit could not be checked; the action did not run. Retry later. shopify_unavailable: Shopify could not be reached while checking the subscription. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_unavailable": { "value": { "error": { "code": "rate_limit_unavailable", "message": "The rate limit could not be checked; the action did not run. Retry later." } } }, "shopify_unavailable": { "value": { "error": { "code": "shopify_unavailable", "message": "Shopify could not be reached while checking the subscription. Retry later." } } } } } } } } } }, "/auto_groups/enable": { "put": { "operationId": "enable-auto-groups", "tags": [ "Smart groups" ], "summary": "Enable smart groups", "description": "Enable smart groups. Switching from off to on starts at most one refresh in the background. Repeating enable while already enabled does not start another.\n\nRequired permission: Write. The response does not contain a run ID and does not mean the scan is complete. A separate refresh request can return refresh_in_progress until the automatic scan finishes. No request body is required.", "x-permission": "Write", "parameters": [ { "name": "X-Shopify-Shop-Domain", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The key’s full *.myshopify.com hostname, without a scheme, path or port. Comparison ignores case and surrounding whitespace.", "example": "your-store.myshopify.com" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Enabled" }, "example": { "enabled": true } } } }, "400": { "description": "shop_domain_required: Send a nonblank X-Shopify-Shop-Domain header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_required": { "value": { "error": { "code": "shop_domain_required", "message": "Send a nonblank X-Shopify-Shop-Domain header." } } } } } } }, "401": { "description": "invalid_key: The bearer key is missing, unknown, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_key": { "value": { "error": { "code": "invalid_key", "message": "The bearer key is missing, unknown, or revoked." } } } } } } }, "402": { "description": "plan_required: The shop needs an active Advance entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "The shop needs an active Advance entitlement." } } } } } } }, "403": { "description": "shop_domain_mismatch: The supplied domain does not match the key’s shop. permission_required: The key lacks Write or Delete permission for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_mismatch": { "value": { "error": { "code": "shop_domain_mismatch", "message": "The supplied domain does not match the key’s shop." } } }, "permission_required": { "value": { "error": { "code": "permission_required", "message": "The key lacks Write or Delete permission for this operation." } } } } } } }, "429": { "description": "rate_limited: The shop’s shared request allowance is exhausted. Wait for Retry-After (60 seconds).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "value": { "error": { "code": "rate_limited", "message": "API rate limit exceeded. Retry after 60 seconds." } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "const": 60 }, "description": "Wait 60 seconds before retrying." }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "503": { "description": "rate_limit_unavailable: The rate limit could not be checked; the action did not run. Retry later. shopify_unavailable: Shopify could not be reached while checking the subscription. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_unavailable": { "value": { "error": { "code": "rate_limit_unavailable", "message": "The rate limit could not be checked; the action did not run. Retry later." } } }, "shopify_unavailable": { "value": { "error": { "code": "shopify_unavailable", "message": "Shopify could not be reached while checking the subscription. Retry later." } } } } } } } } } }, "/auto_groups/disable": { "put": { "operationId": "disable-auto-groups", "tags": [ "Smart groups" ], "summary": "Disable smart groups", "description": "Disable smart groups and delete the shop’s generated smart groups and their members. Shopify products and variants are not deleted.\n\nRequired permission: Delete. Unlike disabling manual or bundle groups, this removes the generated groups. Enabling smart groups again starts a new scan. No request body is required.", "x-permission": "Delete", "parameters": [ { "name": "X-Shopify-Shop-Domain", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The key’s full *.myshopify.com hostname, without a scheme, path or port. Comparison ignores case and surrounding whitespace.", "example": "your-store.myshopify.com" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Enabled" }, "example": { "enabled": false } } } }, "400": { "description": "shop_domain_required: Send a nonblank X-Shopify-Shop-Domain header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_required": { "value": { "error": { "code": "shop_domain_required", "message": "Send a nonblank X-Shopify-Shop-Domain header." } } } } } } }, "401": { "description": "invalid_key: The bearer key is missing, unknown, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_key": { "value": { "error": { "code": "invalid_key", "message": "The bearer key is missing, unknown, or revoked." } } } } } } }, "402": { "description": "plan_required: The shop needs an active Advance entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "The shop needs an active Advance entitlement." } } } } } } }, "403": { "description": "shop_domain_mismatch: The supplied domain does not match the key’s shop. permission_required: The key lacks Write or Delete permission for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_mismatch": { "value": { "error": { "code": "shop_domain_mismatch", "message": "The supplied domain does not match the key’s shop." } } }, "permission_required": { "value": { "error": { "code": "permission_required", "message": "The key lacks Write or Delete permission for this operation." } } } } } } }, "429": { "description": "rate_limited: The shop’s shared request allowance is exhausted. Wait for Retry-After (60 seconds).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "value": { "error": { "code": "rate_limited", "message": "API rate limit exceeded. Retry after 60 seconds." } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "const": 60 }, "description": "Wait 60 seconds before retrying." }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "503": { "description": "rate_limit_unavailable: The rate limit could not be checked; the action did not run. Retry later. shopify_unavailable: Shopify could not be reached while checking the subscription. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_unavailable": { "value": { "error": { "code": "rate_limit_unavailable", "message": "The rate limit could not be checked; the action did not run. Retry later." } } }, "shopify_unavailable": { "value": { "error": { "code": "shopify_unavailable", "message": "Shopify could not be reached while checking the subscription. Retry later." } } } } } } } } } }, "/auto_groups/refresh": { "post": { "operationId": "refresh-auto-groups", "tags": [ "Smart groups" ], "summary": "Start a smart-group refresh", "description": "Queue a scan to rebuild smart groups. Smart groups must already be enabled. No request body or Idempotency-Key is required.\n\nRequired permission: Write. 202 means accepted, not completed. Poll status_url on the API host using the same headers. Polling counts against the shared rate limit.", "x-permission": "Write", "parameters": [ { "name": "X-Shopify-Shop-Domain", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The key’s full *.myshopify.com hostname, without a scheme, path or port. Comparison ignores case and surrounding whitespace.", "example": "your-store.myshopify.com" } ], "responses": { "202": { "description": "Accepted; poll for completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshTicket" }, "example": { "run_id": 7, "status": "queued", "status_url": "/api/v1/auto_groups/refresh_runs/7" } } } }, "400": { "description": "shop_domain_required: Send a nonblank X-Shopify-Shop-Domain header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_required": { "value": { "error": { "code": "shop_domain_required", "message": "Send a nonblank X-Shopify-Shop-Domain header." } } } } } } }, "401": { "description": "invalid_key: The bearer key is missing, unknown, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_key": { "value": { "error": { "code": "invalid_key", "message": "The bearer key is missing, unknown, or revoked." } } } } } } }, "402": { "description": "plan_required: The shop needs an active Advance entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "The shop needs an active Advance entitlement." } } } } } } }, "403": { "description": "shop_domain_mismatch: The supplied domain does not match the key’s shop. permission_required: The key lacks Write or Delete permission for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_mismatch": { "value": { "error": { "code": "shop_domain_mismatch", "message": "The supplied domain does not match the key’s shop." } } }, "permission_required": { "value": { "error": { "code": "permission_required", "message": "The key lacks Write or Delete permission for this operation." } } } } } } }, "409": { "description": "smart_groups_disabled: Enable smart groups before requesting a refresh. refresh_in_progress: A smart-group refresh is already running. Wait for it to finish before starting another.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "smart_groups_disabled": { "value": { "error": { "code": "smart_groups_disabled", "message": "Enable smart groups before requesting a refresh." } } }, "refresh_in_progress": { "value": { "error": { "code": "refresh_in_progress", "message": "A smart-group refresh is already running. Wait for it to finish before starting another." } } } } } } }, "429": { "description": "rate_limited: The shop’s shared request allowance is exhausted. Wait for Retry-After (60 seconds).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "value": { "error": { "code": "rate_limited", "message": "API rate limit exceeded. Retry after 60 seconds." } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "const": 60 }, "description": "Wait 60 seconds before retrying." }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "503": { "description": "rate_limit_unavailable: The rate limit could not be checked; the action did not run. Retry later. shopify_unavailable: Shopify could not be reached while checking the subscription. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_unavailable": { "value": { "error": { "code": "rate_limit_unavailable", "message": "The rate limit could not be checked; the action did not run. Retry later." } } }, "shopify_unavailable": { "value": { "error": { "code": "shopify_unavailable", "message": "Shopify could not be reached while checking the subscription. Retry later." } } } } } } } } } }, "/auto_groups/refresh_runs/{id}": { "get": { "operationId": "get-refresh-run", "tags": [ "Smart groups" ], "summary": "Get refresh progress", "description": "Read the local run record. queued means waiting; running covers scanning, importing, and promoting. completed means the new groups can be read. failed and canceled are also terminal states.\n\nRequired permission: Read. Stop polling on completed, failed, or canceled. error contains the stored failure or cancellation reason when available. This read does not call Shopify.", "x-permission": "Read", "parameters": [ { "name": "X-Shopify-Shop-Domain", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The key’s full *.myshopify.com hostname, without a scheme, path or port. Comparison ignores case and surrounding whitespace.", "example": "your-store.myshopify.com" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Connected Inventory resource ID, not a Shopify ID." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshRun" }, "example": { "run_id": 7, "status": "completed", "started_at": "2026-10-12T08:00:00Z", "finished_at": "2026-10-12T08:01:00Z", "error": null } } } }, "400": { "description": "shop_domain_required: Send a nonblank X-Shopify-Shop-Domain header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_required": { "value": { "error": { "code": "shop_domain_required", "message": "Send a nonblank X-Shopify-Shop-Domain header." } } } } } } }, "401": { "description": "invalid_key: The bearer key is missing, unknown, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_key": { "value": { "error": { "code": "invalid_key", "message": "The bearer key is missing, unknown, or revoked." } } } } } } }, "402": { "description": "plan_required: The shop needs an active Advance entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "The shop needs an active Advance entitlement." } } } } } } }, "403": { "description": "shop_domain_mismatch: The supplied domain does not match the key’s shop.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_mismatch": { "value": { "error": { "code": "shop_domain_mismatch", "message": "The supplied domain does not match the key’s shop." } } } } } } }, "404": { "description": "not_found: The resource does not exist in this shop. Another shop’s resource is also reported as not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "value": { "error": { "code": "not_found", "message": "The resource does not exist in this shop. Another shop’s resource is also reported as not found." } } } } } } }, "429": { "description": "rate_limited: The shop’s shared request allowance is exhausted. Wait for Retry-After (60 seconds).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "value": { "error": { "code": "rate_limited", "message": "API rate limit exceeded. Retry after 60 seconds." } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "const": 60 }, "description": "Wait 60 seconds before retrying." }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "503": { "description": "rate_limit_unavailable: The rate limit could not be checked; the action did not run. Retry later. shopify_unavailable: Shopify could not be reached while checking the subscription. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_unavailable": { "value": { "error": { "code": "rate_limit_unavailable", "message": "The rate limit could not be checked; the action did not run. Retry later." } } }, "shopify_unavailable": { "value": { "error": { "code": "shopify_unavailable", "message": "Shopify could not be reached while checking the subscription. Retry later." } } } } } } } } } }, "/activity_logs": { "get": { "operationId": "list-activity-logs", "tags": [ "Activity logs" ], "summary": "List activity logs", "description": "Return the shop’s stored activity messages in descending ID order. This is the activity log, not the internal API audit log.\n\nRequired permission: Read. ", "x-permission": "Read", "parameters": [ { "name": "X-Shopify-Shop-Domain", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The key’s full *.myshopify.com hostname, without a scheme, path or port. Comparison ignores case and surrounding whitespace.", "example": "your-store.myshopify.com" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Default 50, capped at 200. Nonpositive or nonnumeric values fall back to 50." }, { "name": "after", "in": "query", "schema": { "type": "string" }, "description": "Opaque next_cursor from the previous page. Items are ordered by descending ID. Stop when next_cursor is null." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityLog" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "example": { "data": [ { "id": 108, "message": "Manual group created", "created_at": "2026-10-12T08:00:00Z" } ], "next_cursor": null } } } }, "400": { "description": "shop_domain_required: Send a nonblank X-Shopify-Shop-Domain header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_required": { "value": { "error": { "code": "shop_domain_required", "message": "Send a nonblank X-Shopify-Shop-Domain header." } } } } } } }, "401": { "description": "invalid_key: The bearer key is missing, unknown, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_key": { "value": { "error": { "code": "invalid_key", "message": "The bearer key is missing, unknown, or revoked." } } } } } } }, "402": { "description": "plan_required: The shop needs an active Advance entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "The shop needs an active Advance entitlement." } } } } } } }, "403": { "description": "shop_domain_mismatch: The supplied domain does not match the key’s shop.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_mismatch": { "value": { "error": { "code": "shop_domain_mismatch", "message": "The supplied domain does not match the key’s shop." } } } } } } }, "422": { "description": "validation_failed: Invalid JSON, request fields, group membership, or pagination cursor. Read error.message for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "validation_failed": { "value": { "error": { "code": "validation_failed", "message": "Invalid JSON, request fields, group membership, or pagination cursor. Read error.message for the reason." } } } } } } }, "429": { "description": "rate_limited: The shop’s shared request allowance is exhausted. Wait for Retry-After (60 seconds).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "value": { "error": { "code": "rate_limited", "message": "API rate limit exceeded. Retry after 60 seconds." } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "const": 60 }, "description": "Wait 60 seconds before retrying." }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "503": { "description": "rate_limit_unavailable: The rate limit could not be checked; the action did not run. Retry later. shopify_unavailable: Shopify could not be reached while checking the subscription. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_unavailable": { "value": { "error": { "code": "rate_limit_unavailable", "message": "The rate limit could not be checked; the action did not run. Retry later." } } }, "shopify_unavailable": { "value": { "error": { "code": "shopify_unavailable", "message": "Shopify could not be reached while checking the subscription. Retry later." } } } } } } } } } }, "/sync_histories": { "get": { "operationId": "list-sync-histories", "tags": [ "Sync history" ], "summary": "List sync history", "description": "Return order sync history summaries in descending ID order. The default and maximum page size are both 50. Fetch a history by its app ID to read child results.\n\nRequired permission: Read. ", "x-permission": "Read", "parameters": [ { "name": "X-Shopify-Shop-Domain", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The key’s full *.myshopify.com hostname, without a scheme, path or port. Comparison ignores case and surrounding whitespace.", "example": "your-store.myshopify.com" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Default 50, capped at 50. Nonpositive or nonnumeric values fall back to 50." }, { "name": "after", "in": "query", "schema": { "type": "string" }, "description": "Opaque next_cursor from the previous page. Items are ordered by descending ID. Stop when next_cursor is null." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SyncHistorySummary" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "example": { "data": [ { "id": 83, "order_id": "6001", "order_name": "#1001", "location_id": "9001", "location_name": "Main warehouse", "topic": "orders/create", "created_at": "2026-10-12T08:00:00Z" } ], "next_cursor": null } } } }, "400": { "description": "shop_domain_required: Send a nonblank X-Shopify-Shop-Domain header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_required": { "value": { "error": { "code": "shop_domain_required", "message": "Send a nonblank X-Shopify-Shop-Domain header." } } } } } } }, "401": { "description": "invalid_key: The bearer key is missing, unknown, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_key": { "value": { "error": { "code": "invalid_key", "message": "The bearer key is missing, unknown, or revoked." } } } } } } }, "402": { "description": "plan_required: The shop needs an active Advance entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "The shop needs an active Advance entitlement." } } } } } } }, "403": { "description": "shop_domain_mismatch: The supplied domain does not match the key’s shop.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_mismatch": { "value": { "error": { "code": "shop_domain_mismatch", "message": "The supplied domain does not match the key’s shop." } } } } } } }, "422": { "description": "validation_failed: Invalid JSON, request fields, group membership, or pagination cursor. Read error.message for the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "validation_failed": { "value": { "error": { "code": "validation_failed", "message": "Invalid JSON, request fields, group membership, or pagination cursor. Read error.message for the reason." } } } } } } }, "429": { "description": "rate_limited: The shop’s shared request allowance is exhausted. Wait for Retry-After (60 seconds).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "value": { "error": { "code": "rate_limited", "message": "API rate limit exceeded. Retry after 60 seconds." } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "const": 60 }, "description": "Wait 60 seconds before retrying." }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "503": { "description": "rate_limit_unavailable: The rate limit could not be checked; the action did not run. Retry later. shopify_unavailable: Shopify could not be reached while checking the subscription. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_unavailable": { "value": { "error": { "code": "rate_limit_unavailable", "message": "The rate limit could not be checked; the action did not run. Retry later." } } }, "shopify_unavailable": { "value": { "error": { "code": "shopify_unavailable", "message": "Shopify could not be reached while checking the subscription. Retry later." } } } } } } } } } }, "/sync_histories/{id}": { "get": { "operationId": "get-sync-history", "tags": [ "Sync history" ], "summary": "Get a sync history", "description": "Return a stored history with auto, manual, and bundle result arrays. The path ID is the Connected Inventory history ID, not the Shopify order ID.\n\nRequired permission: Read. ", "x-permission": "Read", "parameters": [ { "name": "X-Shopify-Shop-Domain", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The key’s full *.myshopify.com hostname, without a scheme, path or port. Comparison ignores case and surrounding whitespace.", "example": "your-store.myshopify.com" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Connected Inventory resource ID, not a Shopify ID." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncHistory" }, "example": { "id": 83, "order_id": "6001", "order_name": "#1001", "location_id": "9001", "location_name": "Main warehouse", "topic": "orders/create", "created_at": "2026-10-12T08:00:00Z", "auto": [], "manual": [ { "status": "finished", "group_name": "Everyday totes", "variant_id": "1001", "product_title": "Everyday tote", "variant_title": "Natural" } ], "bundle": [] } } } }, "400": { "description": "shop_domain_required: Send a nonblank X-Shopify-Shop-Domain header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_required": { "value": { "error": { "code": "shop_domain_required", "message": "Send a nonblank X-Shopify-Shop-Domain header." } } } } } } }, "401": { "description": "invalid_key: The bearer key is missing, unknown, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_key": { "value": { "error": { "code": "invalid_key", "message": "The bearer key is missing, unknown, or revoked." } } } } } } }, "402": { "description": "plan_required: The shop needs an active Advance entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "The shop needs an active Advance entitlement." } } } } } } }, "403": { "description": "shop_domain_mismatch: The supplied domain does not match the key’s shop.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "shop_domain_mismatch": { "value": { "error": { "code": "shop_domain_mismatch", "message": "The supplied domain does not match the key’s shop." } } } } } } }, "404": { "description": "not_found: The resource does not exist in this shop. Another shop’s resource is also reported as not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "value": { "error": { "code": "not_found", "message": "The resource does not exist in this shop. Another shop’s resource is also reported as not found." } } } } } } }, "429": { "description": "rate_limited: The shop’s shared request allowance is exhausted. Wait for Retry-After (60 seconds).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "value": { "error": { "code": "rate_limited", "message": "API rate limit exceeded. Retry after 60 seconds." } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "const": 60 }, "description": "Wait 60 seconds before retrying." }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "503": { "description": "rate_limit_unavailable: The rate limit could not be checked; the action did not run. Retry later. shopify_unavailable: Shopify could not be reached while checking the subscription. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_unavailable": { "value": { "error": { "code": "rate_limit_unavailable", "message": "The rate limit could not be checked; the action did not run. Retry later." } } }, "shopify_unavailable": { "value": { "error": { "code": "shopify_unavailable", "message": "Shopify could not be reached while checking the subscription. Retry later." } } } } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "A civ_ API key created in the app. Keep this secret on your server." } }, "schemas": { "VariantInput": { "type": "object", "required": [ "product_gid", "variant_gid", "inventory_item_gid", "product_title", "variant_title" ], "properties": { "product_gid": { "type": "string", "pattern": "^gid://shopify/Product/[1-9][0-9]*$" }, "variant_gid": { "type": "string", "pattern": "^gid://shopify/ProductVariant/[1-9][0-9]*$" }, "inventory_item_gid": { "type": "string", "pattern": "^gid://shopify/InventoryItem/[1-9][0-9]*$" }, "product_title": { "type": "string", "pattern": "\\S" }, "variant_title": { "type": "string", "pattern": "\\S" } }, "description": "All fields required. Metadata is saved as supplied; the caller must verify Shopify ownership and matching identifiers. Legacy product_id, variant_id and inventory_item_id are rejected.", "not": { "anyOf": [ { "required": [ "product_id" ] }, { "required": [ "variant_id" ] }, { "required": [ "inventory_item_id" ] } ] } }, "ComponentInput": { "allOf": [ { "$ref": "#/components/schemas/VariantInput" }, { "type": "object", "required": [ "quantity" ], "properties": { "quantity": { "type": "integer", "minimum": 1 } } } ] }, "Variant": { "type": "object", "required": [ "product_gid", "variant_gid", "inventory_item_gid", "product_title", "variant_title" ], "properties": { "product_gid": { "type": [ "string", "null" ] }, "variant_gid": { "type": [ "string", "null" ] }, "inventory_item_gid": { "type": [ "string", "null" ] }, "product_title": { "type": [ "string", "null" ] }, "variant_title": { "type": [ "string", "null" ] } } }, "Component": { "type": "object", "required": [ "product_gid", "variant_gid", "inventory_item_gid", "product_title", "variant_title", "quantity" ], "properties": { "product_gid": { "type": [ "string", "null" ] }, "variant_gid": { "type": [ "string", "null" ] }, "inventory_item_gid": { "type": [ "string", "null" ] }, "product_title": { "type": [ "string", "null" ] }, "variant_title": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" } } }, "ManualInput": { "type": "object", "required": [ "name", "variants" ], "properties": { "name": { "type": "string", "pattern": "\\S" }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/VariantInput" }, "minItems": 2, "description": "Distinct variant_gid values. A variant cannot belong to another manual group." } } }, "BundleInput": { "type": "object", "required": [ "name", "master", "components" ], "properties": { "name": { "type": "string", "pattern": "\\S" }, "master": { "$ref": "#/components/schemas/VariantInput" }, "components": { "type": "array", "items": { "$ref": "#/components/schemas/ComponentInput" }, "minItems": 1, "description": "Distinct components; the master cannot also be a component. A master may belong to only one bundle and cannot be a component elsewhere." } } }, "GroupSummary": { "type": "object", "required": [ "id", "name", "status", "created_at", "updated_at", "member_count" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "member_count": { "type": "integer", "minimum": 0 } } }, "ManualGroup": { "type": "object", "required": [ "id", "name", "status", "created_at", "updated_at", "variants" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/Variant" } } } }, "BundleGroup": { "type": "object", "required": [ "id", "name", "status", "created_at", "updated_at", "master", "components" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "master": { "$ref": "#/components/schemas/Variant" }, "components": { "type": "array", "items": { "$ref": "#/components/schemas/Component" } } } }, "Enabled": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" } } }, "RefreshTicket": { "type": "object", "required": [ "run_id", "status", "status_url" ], "properties": { "run_id": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "canceled" ] }, "status_url": { "type": "string", "description": "Relative path on the API host." } } }, "RefreshRun": { "type": "object", "required": [ "run_id", "status", "started_at", "finished_at", "error" ], "properties": { "run_id": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "canceled" ] }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "error": { "type": [ "string", "null" ] } } }, "ActivityLog": { "type": "object", "required": [ "id", "message", "created_at" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "message": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "SyncHistorySummary": { "type": "object", "required": [ "id", "order_id", "order_name", "location_id", "location_name", "topic", "created_at" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "order_id": { "type": [ "string", "null" ] }, "order_name": { "type": [ "string", "null" ] }, "location_id": { "type": [ "string", "null" ] }, "location_name": { "type": [ "string", "null" ] }, "topic": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "SyncResult": { "type": "object", "required": [ "status", "group_name", "variant_id", "product_title", "variant_title" ], "properties": { "status": { "type": [ "string", "null" ] }, "group_name": { "type": [ "string", "null" ] }, "variant_id": { "type": [ "string", "null" ] }, "product_title": { "type": [ "string", "null" ] }, "variant_title": { "type": [ "string", "null" ] } } }, "SyncHistory": { "type": "object", "required": [ "id", "order_id", "order_name", "location_id", "location_name", "topic", "created_at", "auto", "manual", "bundle" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "order_id": { "type": [ "string", "null" ] }, "order_name": { "type": [ "string", "null" ] }, "location_id": { "type": [ "string", "null" ] }, "location_name": { "type": [ "string", "null" ] }, "topic": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "auto": { "type": "array", "items": { "$ref": "#/components/schemas/SyncResult" } }, "manual": { "type": "array", "items": { "$ref": "#/components/schemas/SyncResult" } }, "bundle": { "type": "array", "items": { "$ref": "#/components/schemas/SyncResult" } } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "shop_domain_required", "idempotency_key_required", "invalid_key", "plan_required", "shop_domain_mismatch", "permission_required", "not_found", "idempotency_conflict", "idempotency_in_progress", "smart_groups_disabled", "refresh_in_progress", "validation_failed", "rate_limited", "rate_limit_unavailable", "shopify_unavailable" ] }, "message": { "type": "string" } } } } } } } }