Skip to content

Add variants

API v2 is in public beta: endpoints and fields can change before general availability. See the changelog

POST/preorders/offers/{id}/products/add_variants

Costs 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

Headers

  • Idempotency-Keystring

    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_idsarray of strings

    Shopify variant gids to attach. Custom selection only. Already-attached variants come back under already_present.

  • shopify_product_idsarray of strings

    Shopify product gids; every variant of each product is attached. Custom selection only.

  • shopify_collection_idstring

    A Shopify collection gid; every product in it is attached, as 'Add from collection' does. Custom selection only.

  • skip_variants_in_market_offersboolean

    true leaves out variants that a market-specific offer owns. Default false.

    Default false
  • skip_preflightboolean

    true adds without blocking on the pre-flight check; any resolve fixes still run. Default false.

    Default false
  • resolveobject

    Fixes to apply for pre-flight issues, each true to apply it. Custom selection only.

    Show 3 child attributesHide child attributes
    • remove_from_conflicting_offersboolean

      Take 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_sellingboolean

      Turn on 'Continue selling when out of stock' for the variants that have it off, after adding.

    • skip_sales_channel_productsboolean

      Leave out the products on sales channels that can't sell preorders.

Returns

  • selectionstring

    Rule that puts variants on the offer: all (every variant in the shop, minus exclusions), collection, custom (variants added by hand) or tags.

    One of allcollectioncustomtags
  • shopify_collection_idnull

    Collection driving the variant list, as gid://shopify/Collection/<id>. Null unless selection is collection.

  • tagsarray of anys

    Product tags; products carrying any of them are on the offer. Empty unless selection is tags.

  • eligible_inventory_policystring

    continue_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 of continue_sellingall
  • excluded_shopify_variant_idsarray of anys

    Variants held back from the rule, as gid://shopify/ProductVariant/<id>.

  • exclusion_tagnull

    Variants of products carrying this tag are held back. Null when none is set.

  • variant_countinteger

    Number of variants on the offer, leaving out variants deleted from the catalog.

  • variants_addedarray of strings

    Variants newly attached, as gid://shopify/ProductVariant/<id>.

  • products_addedarray of anys

    Products whose variants were attached, as gid://shopify/Product/<id>.

  • already_presentarray of strings

    Variants asked for that were already on the offer.

  • deleted_in_shopifyarray of anys

    Variants asked for that Shopify has deleted, so they were not attached.

Errors

404
not_found

The path is valid but nothing with that id exists in this store.

409
conflict

The request is well formed, but the resource's current state does not allow it.

409
job_in_progress

An earlier bulk change on the same resource is still running.

409
idempotency_key_in_progress

An earlier request with the same Idempotency-Key is still running. Wait, then resend the same request with the same key.

422
invalid_params

One or more fields failed the action's schema.

422
preflight_issues

Some variants cannot be added to the offer as requested. The preflight field lists each one and why.

422
quantity_limit_reached

Every targeted variant has reached its preorder quantity limit, so STOQ keeps it from selling.

422
validation_failed

The request failed validation.

502
shopify_error

A Shopify call the operation needs failed after the operation had started.

503
upstream_unavailable

A 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.

POST/preorders/offers/{id}/products/add_variants
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"
    ]
  }'
Response
{
  "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"
  }
}