Skip to content

Bulk set offer policy

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

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

Costs 2 rate-limit points · Rate limits

Flip the Shopify inventory policy on variants attached to a preorder offer (CONTINUE or DENY). Pass the explicit shopify_variant_ids for a partial change; omitting shopify_variant_ids applies the policy to EVERY attached variant, so only omit it when the merchant asked for all of them.

Returns 202 with a job; Shopify is updated in batches, so poll job.status_url until it is completed. shopify_variant_ids are Shopify variant gids; ones not on this offer are skipped and returned in skipped_shopify_variant_ids, and the call fails with 422 if none are. With CONTINUE, variants at their quantity limit are left out, as the dashboard's 'Skip variants that have reached their quantity limit' (checked by default) does; skip_quantity_limited: false includes them.

Also searched asflip inventory policytoggle continue selling on variantsset inventory policy for variantsenable oversell on these variantsdisable oversell on these variants

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

  • policystringRequired

    CONTINUE keeps selling the variants when out of stock; DENY stops.

    One of CONTINUEDENY
  • shopify_variant_idsarray of strings

    Which attached variants to flip: Shopify variant gids. Variants not attached to this offer are skipped. Omitting this applies the policy to EVERY attached variant, so only omit it when the merchant asked for all of them.

  • skip_quantity_limitedboolean

    CONTINUE only: leave out variants that have reached their quantity limit. Default true, as the dashboard checkbox.

    Default true

Returns

  • policystring

    Inventory policy being set: CONTINUE keeps selling when out of stock; DENY stops.

    One of CONTINUEDENY
  • variant_countinteger

    Variants whose inventory policy is being changed.

  • skipped_shopify_variant_idsarray of strings

    Variants asked for that are not on the offer, as sent. They are left alone.

  • jobobject

    Background job updating Shopify; poll status_url until it is completed.

    Show 3 child attributesHide child attributes
    • job_idstring

      Job ID.

    • statusstring

      Job status when the response was sent, queued.

    • status_urlstring

      Path to poll for the job's progress.

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
quantity_limit_reached

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

422
validation_failed

The action refused the request for a reason that is not a single bad field.

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/bulk_toggle_inventory_policy
curl -X POST "https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/products/bulk_toggle_inventory_policy" \
  -H "X-Auth-Token: $STOQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "policy": "CONTINUE",
    "shopify_variant_ids": [
      "gid://shopify/ProductVariant/44712349876501",
      "gid://shopify/ProductVariant/44712349909269"
    ]
  }'
Response
{
  "policy": "CONTINUE",
  "variant_count": 1,
  "skipped_shopify_variant_ids": [
    "gid://shopify/ProductVariant/44712349909269"
  ],
  "job": {
    "job_id": "7f3e9a12-4c6b-4d81-b2e0-5a9c1d8e6f34",
    "status": "queued",
    "status_url": "/api/v2/external/preorders/product_variants/jobs/7f3e9a12-4c6b-4d81-b2e0-5a9c1d8e6f34"
  }
}