Add variants
API v2 is in public beta: endpoints and fields can change before general availability. See the changelog
/preorders/offers/{id}/products/add_variantsCosts 2 rate-limit points · Rate limits
Attach products and variants to a preorder offer, or re-run a collection, tag or all-products selection.
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.
Also searched asadd variantsattach variantsadd products to offerlink variantsinclude variantsadd collection to offeradd all products
Path parameters
idstringRequiredThe offer's ID, from
GET /preorders/offers.
Headers
Idempotency-KeystringA 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 (422idempotency_key_reused); a retry while the first is still running gets 409idempotency_key_in_progress. Keys are per store. Server errors and rate limits are not kept, so their retry runs.
Request body
shopify_variant_idsarray of stringsShopify variant gids to attach. Custom selection only. Already-attached variants come back under already_present.
shopify_product_idsarray of stringsShopify product gids; every variant of each product is attached. Custom selection only.
shopify_collection_idstringA Shopify collection gid; every product in it is attached, as 'Add from collection' does. Custom selection only.
skip_variants_in_market_offersbooleantrue leaves out variants that a market-specific offer owns. Default false.
Defaultfalseskip_preflightbooleantrue adds without blocking on the pre-flight check; any resolve fixes still run. Default false.
DefaultfalseresolveobjectFixes to apply for pre-flight issues, each true to apply it. Custom selection only.
Show 3 child attributesHide child attributes
remove_from_conflicting_offersbooleanTake the variants off the other offers that have them first. A choice, not a rule: a variant can stay on several offers, and nothing moves unless this is true. Set it only after the merchant asked to move them or said yes when asked; naming the target offer is not a yes.
enable_continue_sellingbooleanTurn on 'Continue selling when out of stock' for the variants that have it off, after adding.
skip_sales_channel_productsbooleanLeave out the products on sales channels that can't sell preorders.
Returns
selectionstringRule that puts variants on the offer: all (every variant in the shop, minus exclusions), collection, custom (variants added by hand) or tags.
One ofallcollectioncustomtagsshopify_collection_idnullCollection driving the variant list, as gid://shopify/Collection/<id>. Null unless selection is collection.
tagsarray of anysProduct tags; products carrying any of them are on the offer. Empty unless selection is tags.
eligible_inventory_policystringcontinue_selling: STOQ turns Continue selling on for the rule's out-of-stock variants so all take preorders. all: only variants that already have Continue selling on take preorders.
One ofcontinue_sellingallexcluded_shopify_variant_idsarray of anysVariants held back from the rule, as gid://shopify/ProductVariant/<id>.
exclusion_tagnullVariants of products carrying this tag are held back. Null when none is set.
variant_countintegerNumber of variants on the offer, leaving out variants deleted from the catalog.
variants_addedarray of stringsVariants newly attached, as gid://shopify/ProductVariant/<id>.
products_addedarray of anysProducts whose variants were attached, as gid://shopify/Product/<id>.
already_presentarray of stringsVariants asked for that were already on the offer.
deleted_in_shopifyarray of anysVariants asked for that Shopify has deleted, so they were not attached.
Errors
not_foundThe path is valid but nothing with that id exists in this store.
conflictThe request is well formed, but the resource's current state does not allow it.
job_in_progressAn earlier bulk change on the same resource is still running.
idempotency_key_in_progressAn earlier request with the same Idempotency-Key is still running. Wait, then resend the same request with the same key.
invalid_paramsOne or more fields failed the action's schema.
preflight_issuesSome variants cannot be added to the offer as requested. The preflight field lists each one and why.
quantity_limit_reachedEvery targeted variant has reached its preorder quantity limit, so STOQ keeps it from selling.
validation_failedThe request failed validation.
shopify_errorA Shopify call the operation needs failed after the operation had started.
upstream_unavailableA service the answer depends on did not respond in time.
Any request can also fail with auth_invalid (401) or rate_limited (429).
Every error has the same shape: see Errors and the list of error codes.
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"
]
}'const res = await fetch("https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/products/add_variants", {
method: "POST",
headers: {
"X-Auth-Token": process.env.STOQ_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"shopify_variant_ids": [
"gid://shopify/ProductVariant/47284734423096",
"gid://shopify/ProductVariant/47284734455864",
"gid://shopify/ProductVariant/47284734488632"
]
}),
});
const data = await res.json();import os
import requests
res = requests.post(
"https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/products/add_variants",
headers={"X-Auth-Token": os.environ["STOQ_API_KEY"]},
json={
"shopify_variant_ids": [
"gid://shopify/ProductVariant/47284734423096",
"gid://shopify/ProductVariant/47284734455864",
"gid://shopify/ProductVariant/47284734488632"
]
},
)
data = res.json()require "net/http"
require "json"
uri = URI("https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/products/add_variants")
req = Net::HTTP::Post.new(uri, "X-Auth-Token" => ENV["STOQ_API_KEY"], "Content-Type" => "application/json")
req.body = {
shopify_variant_ids: [
"gid://shopify/ProductVariant/47284734423096",
"gid://shopify/ProductVariant/47284734455864",
"gid://shopify/ProductVariant/47284734488632"
]
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body){
"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"
}
}{
"selection": "all",
"shopify_collection_id": "string",
"tags": [
null
],
"eligible_inventory_policy": "continue_selling",
"excluded_shopify_variant_ids": [
null
],
"exclusion_tag": null,
"variant_count": 1,
"variants_added": [
"string"
],
"products_added": [
"string"
],
"already_present": [
null
],
"deleted_in_shopify": [
"string"
],
"job": {
"job_id": "string",
"status": "string",
"status_url": "string"
},
"resolved": {
"removed_from_conflicting_offers": [
{
"shopify_variant_id": "string",
"offer_ids": [
"string"
]
}
],
"continue_selling_enabled": {
"shopify_variant_ids": [
"string"
],
"job": {
"job_id": "string",
"status": "string",
"status_url": "string"
}
},
"skipped_for_sales_channels": [
{
"shopify_variant_id": "string",
"shopify_product_id": "string"
}
]
}
}{
"errors": [
"Invalid API key"
],
"code": "auth_invalid",
"details": [
{
"code": "auth_invalid",
"message": "Invalid API key",
"path": null,
"value": null,
"expected": null
}
]
}{
"errors": [
"Offer not found"
],
"code": "not_found",
"details": [
{
"code": "not_found",
"message": "Offer not found",
"path": null,
"value": null,
"expected": null
}
]
}{
"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
}
]
}{
"errors": [
"name is required"
],
"code": "validation_failed",
"details": [
{
"code": "validation_failed",
"message": "name is required",
"path": null,
"value": null,
"expected": null
}
]
}{
"errors": [
"Rate limit exceeded"
],
"code": "rate_limited",
"details": [
{
"code": "rate_limited",
"message": "Rate limit exceeded",
"path": null,
"value": null,
"expected": null
}
]
}