--- title: "Add products variants to an offer" description: "Attach products and variants to a preorder offer, or re-run a collection, tag or all-products selection." url: https://docs.stoqapp.com/v2-reference/preorders-offers/add-products-variants-to-an-offer/ api: "API v2 reference" method: POST path: "/preorders/offers/{id}/products/add_variants" --- # Add products variants to an offer `POST https://app.stoqapp.com/api/v2/external/preorders/offers/{id}/products/add_variants` Attach products and variants to a preorder offer, or re-run a collection, tag or all-products selection. **Note:** Custom selection: pass shopify_variant_ids, shopify_product_ids (every variant of the product) or shopify_collection_id (every product in the collection), all Shopify gids. Already-attached variants come back under already_present and variants Shopify has deleted under deleted_in_shopify. Collection, tag and all-products selections fill themselves: call with no ids to re-run the selection, as the dashboard's 'Add all products' does. Up to 250 variants attach during the call; above that a job does it; either way poll job.status_url until it is completed. skip_variants_in_market_offers: true leaves out variants that a market-specific offer owns. A custom add first runs the offer Products page's pre-flight check (the store-wide Products tab's 'Add to offer', /preorders/products/add_to_offer, runs none): when other offers already have the variants, 'Continue selling' is off where STOQ won't turn it on, or a sales channel can't sell preorders, nothing is added and it answers 409 with code preflight_issues, the issues under preflight and the resolve keys still needed under unresolved. Pass resolve with the Products tab's fix for each issue type (remove_from_conflicting_offers, enable_continue_selling, skip_sales_channel_products), or skip_preflight: true to add without the check. The answer lists what each fix did per variant under resolved. ## Path parameters - `id` (string, required) ## Headers - `Idempotency-Key` (string): A fresh unique key for every write (a new UUID, say); reuse it only to retry that write. Keys are remembered for 1 hour: the same key and the same request within that hour returns the first result, with `Idempotent-Replayed: true`, without running again; the same key with a different method, path or body is refused (422 `idempotency_key_reused`); a retry while the first is still running gets 409 `idempotency_key_in_progress`. Keys are per store. Server errors and rate limits are not kept, so their retry runs. ## Request body - `shopify_variant_ids` (array of strings) - `shopify_product_ids` (any) - `shopify_collection_id` (any) - `skip_variants_in_market_offers` (any) - `skip_preflight` (any) - `resolve` (any) ## Returns - `selection` (string): e.g. `custom` - `shopify_collection_id` (any) - `tags` (array of anys) - `eligible_inventory_policy` (string): e.g. `all` - `excluded_shopify_variant_ids` (array of anys) - `exclusion_tag` (any) - `variants_added` (array of strings) - `already_present` (array of strings) - `deleted_in_shopify` (array of anys) - `job` (object) - `job_id` (string): e.g. `73a74948-2b57-4cc3-971f-2b441828c977` - `status_url` (string): e.g. `/api/v2/external/preorders/product_variants/jobs/73a74948…` Rate limit: this call costs 2 points ([rate limits](https://docs.stoqapp.com/docs/rate-limits/)). ## Example request ```sh curl -X POST "https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/products/add_variants" \ -H "X-Auth-Token: $STOQ_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "shopify_variant_ids": [ "gid://shopify/ProductVariant/47284734423096", "gid://shopify/ProductVariant/47284734455864", "gid://shopify/ProductVariant/47284734488632" ] }' ``` ## 200 Success: example response shown. ```json { "selection": "custom", "shopify_collection_id": null, "tags": [], "eligible_inventory_policy": "all", "excluded_shopify_variant_ids": [], "exclusion_tag": null, "variants_added": [ "gid://shopify/ProductVariant/47284734455864", "gid://shopify/ProductVariant/47284734488632" ], "already_present": [ "gid://shopify/ProductVariant/47284734423096" ], "deleted_in_shopify": [], "job": { "job_id": "73a74948-2b57-4cc3-971f-2b441828c977", "status_url": "/api/v2/external/preorders/product_variants/jobs/73a74948-2b57-4cc3-971f-2b441828c977" } } ``` ## 202 Accepted: async/bulk work was queued. Poll the returned job. ```json { "job_id": "job_a1b2c3", "status_url": "/api/v2/external/jobs/job_a1b2c3" } ``` ## 401 Missing or invalid `X-Auth-Token`. ```json { "errors": [ "Invalid API key" ], "code": "auth_invalid", "details": [ { "code": "auth_invalid", "message": "Invalid API key", "path": null, "value": null, "expected": null } ] } ``` ## 404 The resource does not exist for this shop, or the action path is not registered. ```json { "errors": [ "Offer not found" ], "code": "not_found", "details": [ { "code": "not_found", "message": "Offer not found", "path": null, "value": null, "expected": null } ] } ``` ## 409 An earlier request with the same Idempotency-Key is still running. Wait, then resend the same request with the same key. ```json { "errors": [ "A request with this Idempotency-Key is still running" ], "code": "idempotency_key_in_progress", "details": [ { "code": "idempotency_key_in_progress", "message": "A request with this Idempotency-Key is still running", "path": null, "value": null, "expected": null } ] } ``` ## 422 The request failed validation. ```json { "errors": [ "name is required" ], "code": "validation_failed", "details": [ { "code": "validation_failed", "message": "name is required", "path": null, "value": null, "expected": null } ] } ``` ## 429 Rate limited: cost-weighted per token (read 1, write 2; 360 points / 60s). Check `Retry-After`. ```json { "errors": [ "Rate limit exceeded" ], "code": "rate_limited", "details": [ { "code": "rate_limited", "message": "Rate limit exceeded", "path": null, "value": null, "expected": null } ] } ```