Skip to content

Bulk changes

Run one change over many rows in a single call.

Updated

POST /bulk runs one operation over up to 50 rows in a single call and a single transaction, answering each item’s outcome. It counts once against your rate limit, whatever its items.

It takes accessor, the operation’s name, and items, each that operation’s complete arguments, with each row named as an object ({ "product": { "id": "..." } } or { "product": { "slug": "..." } }). An entry’s or a review’s item names its product too ({ "product": { "id": "..." }, "entry": { "id": "..." } }):

curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/bulk' \
  -H "Authorization: Bearer $SHERPO_TOKEN" \
  -H 'Idempotency-Key: publish-autumn-launch' \
  -H 'Content-Type: application/json' \
  -d '{
  "accessor": "publishProduct",
  "items": [
    {
      "product": {
        "id": "6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42"
      }
    },
    {
      "product": {
        "slug": "ink-and-wash"
      }
    }
  ]
}'
const answer = await sherpo('POST', '/v1/stores/STORE_ID/bulk', {
  body: {
    "accessor": "publishProduct",
    "items": [
      {
        "product": {
          "id": "6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42"
        }
      },
      {
        "product": {
          "slug": "ink-and-wash"
        }
      }
    ]
  },
  key: 'publish-autumn-launch',
});

Answers 200, abridged:

{
  "results": [
    {
      "outcome": "done"
    },
    {
      "outcome": "refused",
      "error": {
        "code": "conflict",
        "detail": {
          "field": "status",
          "current": "published"
        }
      }
    }
  ]
}

Operations

Bulk runs these operations, each named as in its reference page:

  • Products: publishProduct, unpublishProduct, discontinueProduct, reinstateProduct, unlistProduct, relistProduct, deleteProduct.
  • Entries: publishEntry, unpublishEntry, deleteEntry.
  • Pages: publishPage, unpublishPage, deletePage.
  • Files: deleteAsset.
  • Discounts: archiveDiscount, restoreDiscount, deleteDiscount.
  • Reviews: hideReview, unhideReview.
  • Licenses: recordLicense, disableLicense, enableLicense.

The call needs the scope of the operation it runs (see scopes): without it the whole call answers 403 with the reason scope, and no item runs.

Outcomes

The call answers 200 with results, one per item in order: { "outcome": "done" }, or { "outcome": "refused", "error": { "code", "detail" } }, where code is the error’s code and detail what the problem would carry as context. An item refused for what it names (a row not found, a state that clashes) never fails the call, and never turns it into a 401 or 429: the call answers 200 even when every item was refused. A malformed call (an unknown accessor, more than 50 items) answers 422 invalid.

A bulk call takes an Idempotency-Key. Since it lands with its refused items, a repeat answers the same refusals; see idempotency.

Type to search…

↑↓ navigate↵ selectEsc close