{ "openapi": "3.1.0", "info": { "title": "Bundles Pro API", "version": "1.0.0", "license": { "name": "Proprietary" }, "description": "Create and update Shopify product bundles owned by the Bundles Pro app.\n\nShopify only lets the app that created a bundle edit its components, so bundles created in the\nBundles Pro admin and through this API are interchangeable — both run on the app's own token.\n\n**Plan:** requires the Pro plan. Requests from a shop on Free return `403 plan_required`.\n\n**Authentication:** create a key under *API access* in the app and send it as\n`Authorization: Bearer bpro_…`. Keys are scoped to one shop and are read-only or read/write.\n\n**Asynchronous writes:** Shopify builds bundles in the background. Creating a bundle, or changing\nits components, returns `202` with an `operation`; poll `GET /operations/{id}` until its status is\n`COMPLETE` (the bundle's `productId` is then set) or `FAILED`.\n\n**Limits:** 120 requests/minute per key, 30 components per bundle, 250 variants per bundle,\n64 KB request bodies. HTTPS only." }, "servers": [ { "url": "https://bundles.apps.ftwelvelabs.com/api/v1", "description": "Bundles Pro" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Bundles", "description": "Bundles created by Bundles Pro (in the admin or via the API)." }, { "name": "Operations", "description": "Progress of asynchronous bundle creates and component updates." }, { "name": "Sales channels", "description": "Channels a bundle can be published to." } ], "paths": { "/bundles": { "get": { "tags": [ "Bundles" ], "operationId": "listBundles", "summary": "List bundles", "description": "Bundles created by Bundles Pro, newest first. Requires `bundles:read`.", "parameters": [ { "name": "limit", "in": "query", "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "description": "`nextCursor` from the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of bundles.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "bundles", "nextCursor" ], "properties": { "bundles": { "type": "array", "items": { "$ref": "#/components/schemas/BundleSummary" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` for the next page; `null` on the last page." } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Shopify rejected or failed the upstream request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Bundles" ], "operationId": "createBundle", "summary": "Create a bundle", "description": "Starts building a bundle. Returns `202` with an operation to poll. Status, pricing and sales channels are applied when the operation completes. Requires `bundles:write`.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Makes retries safe: a repeated request with the same key returns the original operation (`200`, `replayed: true`) instead of creating a second bundle. Max 255 characters.", "schema": { "type": "string", "maxLength": 255 }, "example": "erp-sync-2026-09-28-kit-42" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleCreate" }, "examples": { "percentOff": { "summary": "Two products, 10% off, published to one channel", "value": { "title": "Snowboard starter kit", "status": "ACTIVE", "pricing": { "strategy": "percent_off", "value": 10 }, "publicationIds": [ "gid://shopify/Publication/123456789" ], "components": [ { "productId": "8123456789", "quantity": 1 }, { "productId": "8123456790", "variantIds": [ "4512345678", "4512345679" ], "quantity": 2 } ] } } } } } }, "responses": { "200": { "description": "Replayed: an operation with this `Idempotency-Key` already exists.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationResult" } } } }, "202": { "description": "Bundle creation started.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "413": { "description": "Request body is larger than 64 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "`Content-Type` must be `application/json`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Shopify rejected or failed the upstream request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bundles/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The bundle's product ID: numeric (`9612796559548`) or a Product GID (`gid://shopify/Product/9612796559548`).", "schema": { "type": "string" }, "example": "9612796559548" } ], "get": { "tags": [ "Bundles" ], "operationId": "getBundle", "summary": "Get a bundle", "description": "Bundle details, components, variant prices and sales channels. Requires `bundles:read`.", "responses": { "200": { "description": "The bundle.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "bundle" ], "properties": { "bundle": { "$ref": "#/components/schemas/Bundle" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Shopify rejected or failed the upstream request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Bundles" ], "operationId": "updateBundle", "summary": "Update a bundle", "description": "Send only the fields to change. Requires `bundles:write`. (`PUT` is accepted with the same semantics.)\n\n- `title`, `status`, `pricing` and `publicationIds` alone apply immediately → `200` with the updated `bundle`.\n- Including `components` replaces all components and runs asynchronously → `202` with an `operation`.\n `publicationIds` still apply immediately; `status` and `pricing` apply when the operation completes.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleUpdate" }, "examples": { "reprice": { "summary": "Set a fixed price and move to draft", "value": { "status": "DRAFT", "pricing": { "strategy": "fixed_price", "value": 199 } } }, "channels": { "summary": "Publish only to Online Store", "value": { "publicationIds": [ "gid://shopify/Publication/123456789" ] } }, "components": { "summary": "Replace components", "value": { "components": [ { "productId": "8123456789", "quantity": 3 } ] } } } } } }, "responses": { "200": { "description": "Updated immediately.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "bundle", "warnings" ], "properties": { "bundle": { "$ref": "#/components/schemas/Bundle" }, "warnings": { "$ref": "#/components/schemas/Warnings" } } } } } }, "202": { "description": "Component update started.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "description": "Request body is larger than 64 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "`Content-Type` must be `application/json`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Shopify rejected or failed the upstream request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/operations/{id}": { "get": { "tags": [ "Operations" ], "operationId": "getOperation", "summary": "Get an operation", "description": "Poll every second or two until `status` is `COMPLETE` or `FAILED`. Only operations started by this shop are visible. Requires `bundles:read`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Operation ID from a create/update response: numeric or a `ProductBundleOperation` GID.", "schema": { "type": "string" }, "example": "gid://shopify/ProductBundleOperation/1234567" } ], "responses": { "200": { "description": "Current operation state.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "operation" ], "properties": { "operation": { "$ref": "#/components/schemas/Operation" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Shopify rejected or failed the upstream request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/channels": { "get": { "tags": [ "Sales channels" ], "operationId": "listChannels", "summary": "List sales channels", "description": "Sales channels installed on the shop (Online Store, Point of Sale, Shop, …). Use their `id`s as `publicationIds`. Markets and B2B catalogs are not included. Requires `bundles:read`.", "responses": { "200": { "description": "Sales channels.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "channels" ], "properties": { "channels": { "type": "array", "items": { "$ref": "#/components/schemas/SalesChannel" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Shopify rejected or failed the upstream request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "bpro__", "description": "API token from *API access* in the Bundles Pro admin. Shown once at creation." } }, "headers": { "RateLimitLimit": { "description": "Requests allowed per window.", "schema": { "type": "integer", "example": 120 } }, "RateLimitRemaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimitReset": { "description": "Unix time (seconds) when the window resets.", "schema": { "type": "integer" } } }, "responses": { "BadRequest": { "description": "Invalid JSON, parameters or IDs (`invalid_json`, `invalid_id`, `invalid_components`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Missing, malformed or revoked token (`unauthorized`), or the app is no longer installed (`app_not_installed`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "The shop isn't on Pro (`plan_required`) or the key lacks the scope (`insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "No such bundle or operation for this shop (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unprocessable": { "description": "Valid JSON that Shopify can't apply: unknown product/variant, too many variants, unknown sales channel (`invalid_bundle`, `product_not_found`, `variant_not_found`, `too_many_variants`, `invalid_publications`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Too many requests (`rate_limited`). Retry after `Retry-After` seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "example": "plan_required" }, "message": { "type": "string", "example": "API access requires the Pro plan" }, "details": { "description": "Extra context, e.g. Shopify user errors." } } } } }, "Warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal notes. Bundles select option values, not individual variants, so a selection like Red/S + Blue/M also includes Red/M and Blue/S; that's reported here." }, "Money": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "22.50" }, "PriceRange": { "type": [ "object", "null" ], "properties": { "min": { "type": "string", "example": "22.5" }, "max": { "type": "string", "example": "45.0" }, "currencyCode": { "type": "string", "example": "USD" } } }, "Pricing": { "type": "object", "required": [ "strategy" ], "description": "How bundle variant prices are set from their components' prices. When discounted, the components' total becomes the compare-at price.", "properties": { "strategy": { "type": "string", "enum": [ "sum", "percent_off", "fixed_price" ], "description": "`sum`: total of component prices × quantities. `percent_off`: that total minus `value`%. `fixed_price`: `value` for every variant." }, "value": { "type": "number", "minimum": 0, "description": "Required for `percent_off` (0–100) and `fixed_price` (shop currency)." } }, "example": { "strategy": "percent_off", "value": 10 } }, "ComponentInput": { "type": "object", "required": [ "productId" ], "properties": { "productId": { "type": "string", "description": "Numeric product ID or Product GID.", "example": "8123456789" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 2000, "default": 1 }, "variantIds": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "Variants of this product to include (numeric or ProductVariant GIDs). Omit to include every variant.", "example": [ "4512345678", "4512345679" ] } } }, "BundleCreate": { "type": "object", "required": [ "title", "components" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 255 }, "status": { "type": "string", "enum": [ "ACTIVE", "DRAFT" ], "default": "DRAFT" }, "pricing": { "$ref": "#/components/schemas/Pricing", "description": "Defaults to `{ \"strategy\": \"sum\" }`." }, "publicationIds": { "type": "array", "items": { "type": "string" }, "description": "Sales channels to publish to (IDs from `GET /channels`). Omit to leave the bundle unpublished." }, "components": { "type": "array", "minItems": 1, "maxItems": 30, "items": { "$ref": "#/components/schemas/ComponentInput" } } } }, "BundleUpdate": { "type": "object", "minProperties": 1, "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 255 }, "status": { "type": "string", "enum": [ "ACTIVE", "DRAFT" ] }, "pricing": { "$ref": "#/components/schemas/Pricing" }, "publicationIds": { "type": "array", "items": { "type": "string" }, "description": "Exact set of sales channels: listed channels are published, all others unpublished. `[]` unpublishes everywhere." }, "components": { "type": "array", "minItems": 1, "maxItems": 30, "items": { "$ref": "#/components/schemas/ComponentInput" }, "description": "Replaces all components (asynchronous)." } } }, "ProductStatus": { "type": "string", "enum": [ "ACTIVE", "DRAFT", "ARCHIVED", "UNLISTED" ] }, "Source": { "type": "string", "enum": [ "ui", "api", "shopify" ], "description": "Where the bundle was created: the Bundles Pro admin, this API, or imported from Shopify." }, "BundleSummary": { "type": "object", "properties": { "id": { "type": "string", "example": "gid://shopify/Product/9612796559548" }, "legacyId": { "type": "string", "example": "9612796559548" }, "title": { "type": "string" }, "status": { "$ref": "#/components/schemas/ProductStatus" }, "image": { "type": [ "string", "null" ], "format": "uri" }, "componentCount": { "type": "integer" }, "priceRange": { "$ref": "#/components/schemas/PriceRange" }, "source": { "$ref": "#/components/schemas/Source" }, "createdAt": { "type": "string", "format": "date-time" } } }, "Component": { "type": "object", "properties": { "productId": { "type": "string", "example": "gid://shopify/Product/8123456789" }, "title": { "type": "string" }, "image": { "type": [ "string", "null" ], "format": "uri" }, "quantity": { "type": "integer" }, "variantIds": { "type": "array", "items": { "type": "string" }, "description": "Included variants (ProductVariant GIDs)." }, "variantsSelected": { "type": "integer", "description": "Number of this product's variants in the bundle." }, "variantsTotal": { "type": "integer", "description": "Number of variants the product has." } } }, "Bundle": { "type": "object", "properties": { "id": { "type": "string", "example": "gid://shopify/Product/9612796559548" }, "legacyId": { "type": "string", "example": "9612796559548" }, "title": { "type": "string" }, "status": { "$ref": "#/components/schemas/ProductStatus" }, "handle": { "type": "string" }, "image": { "type": [ "string", "null" ], "format": "uri" }, "priceRange": { "$ref": "#/components/schemas/PriceRange" }, "pricing": { "$ref": "#/components/schemas/Pricing" }, "source": { "$ref": "#/components/schemas/Source" }, "components": { "type": "array", "items": { "$ref": "#/components/schemas/Component" } }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "price": { "$ref": "#/components/schemas/Money" }, "compareAtPrice": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] } } } }, "publicationIds": { "type": "array", "items": { "type": "string" }, "description": "Publications the bundle is currently on (sales channels, and any market catalogs)." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "Operation": { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "type": "string", "example": "gid://shopify/ProductBundleOperation/1234567" }, "kind": { "type": "string", "enum": [ "create", "update" ] }, "status": { "type": "string", "enum": [ "CREATED", "ACTIVE", "COMPLETE", "FAILED" ], "description": "`CREATED`/`ACTIVE`: in progress. `COMPLETE`: done, `productId` is set. `FAILED`: see `error`." }, "productId": { "type": [ "string", "null" ], "description": "The bundle's Product GID once known." }, "title": { "type": "string" }, "error": { "type": "string", "description": "Why the operation failed." }, "createdAt": { "type": "string", "format": "date-time" } } }, "OperationResult": { "type": "object", "required": [ "operation", "warnings" ], "properties": { "operation": { "$ref": "#/components/schemas/Operation" }, "warnings": { "$ref": "#/components/schemas/Warnings" }, "replayed": { "type": "boolean", "description": "Present and `true` when returned for a repeated `Idempotency-Key`." } } }, "SalesChannel": { "type": "object", "properties": { "id": { "type": "string", "description": "Publication GID; use as a `publicationIds` entry.", "example": "gid://shopify/Publication/123456789" }, "name": { "type": "string", "example": "Online Store" }, "icon": { "type": [ "string", "null" ], "format": "uri" }, "autoPublish": { "type": "boolean", "description": "Whether Shopify publishes new products to this channel automatically." } } } } } }