Bulk edit prices - PlatformDTC

Scope: read_products + write_products. Base URL: https://api.platformdtc.com/api/v1/agent/v1.

1. Read products with their variants

curl -s "https://api.platformdtc.com/api/v1/agent/v1/products?status=active&include=variants&fields=id,title,variants&limit=250" \
  -H "Authorization: Bearer sq_agt_…" | jq '.data.data[].variants[] | {id, price, compare_at_price}'

Follow meta.next_page_info (or the Link: …; rel="next" header) until has_next_page is false. A 5,000-product catalog is 20 requests. Narrow the read with vendor, product_type, tag, collection_id, query or ids; see Products.

2. Update up to 250 variants in one call

curl -s -X POST https://api.platformdtc.com/api/v1/agent/v1/products/variants/bulk_update \
  -H "Authorization: Bearer sq_agt_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: price-sale-2026-10-01-chunk-1" \
  -d '{
    "variants": [
      { "id": "01J9…", "price": "24.99", "compare_at_price": "29.99" },
      { "id": "01JA…", "price": "19.00", "compare_at_price": null }
    ]
  }'

{
  "success": true,
  "data": {
    "results": [
      { "id": "01J9…", "status": "updated",
        "variant": { "id": "01J9…", "price": "24.99", "compare_at_price": "29.99", "sku": "SERUM-30" },
        "error": null },
      { "id": "01JA…", "status": "failed", "variant": null,
        "error": { "code": "validation", "message": "Compare-at price needs to be higher than price" } }
    ],
    "updated_count": 1,
    "failed_count": 1
  }
}

Each variant is written in its own transaction with the same rules as PATCH /products/variants/{variant_id}. A failed variant never rolls back the others, so the response is 200 with per-variant results. Always read results[].
Fields: price, compare_at_price (null ends a sale), sku, title, inventory_quantity, inventory_tracked, inventory_policy. Send only what changes.
Money is a decimal string in major units. At most two decimals.
1 to 250 variants, each id once. Otherwise the whole request is rejected with 400 and nothing is written.
Idempotency-Key is required. Retrying with the same key and body (after a timeout or a 429) returns the first response and writes nothing twice. The same key with a different body returns 409.
One products/update webhook is sent per product touched, and the storefront refreshes once.
The whole call counts as one request against your rate limit.

Product-level fields (status, tags, title) are updated with PUT /products/{id}.

3. Pace with the rate-limit headers

Every response carries X-PlatformDTC-Api-Call-Limit: 12/120. Slow down as used approaches limit, and on 429 wait Retry-After seconds. See Rate limits.

async function call(url, init) {
  for (;;) {
    const res = await fetch(url, init);
    if (res.status !== 429) return res;
    const wait = Number(res.headers.get("Retry-After") || "1");
    await new Promise((r) => setTimeout(r, wait * 1000));
  }
}

​1. Read products with their variants

​2. Update up to 250 variants in one call

​3. Pace with the rate-limit headers

1. Read products with their variants

2. Update up to 250 variants in one call

3. Pace with the rate-limit headers