Bulk Operation (Tracked)
POST/api/shopify/:integrationInstance/products/bulk-tracked
Start a tracked bulk operation on Shopify products. Returns a tracked_job_log_id for progress polling.
This endpoint currently requires session authentication; Personal Access Token scope support is in progress.
Same validation as /products/bulk but dispatches a background job. Poll /products/bulk-progress/:id for status.
Authentication: Requires Bearer token.
Actions: map, unmap, create, remap, archive, unarchive, delete, revenue
Field mappings for the create action
options.field_mappings controls how Shopify values are copied onto the SKU products created by this operation, for this request only — it is never saved to the integration. Each entry pairs a Shopify source field with a SKU target field; call GET /api/shopify/mappings/available-fields for the valid values. Entries naming an unknown field are ignored. Omit options.field_mappings to use the mappings already saved on the integration.
Revenue line mapping (revenue action)
Maps every product in the selection to one revenue financial line type, so future orders book those items as revenue lines instead of product lines (for example shipping insurance, package protection or service fees). No SKU products are created. Pass options.financial_line_type_id (required for this action) with the id of a revenue-classified financial line type, or null to clear the revenue mapping. Products already on that type, or with no revenue mapping to clear, are counted as skipped. A non-revenue type returns 422. Orders already imported are not changed.
Request
Responses
- 200
- 401
- 403
- 404
- 422
- 429
OK
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Not found — no record with the given identifier (or the route does not exist). Verify the ID before retrying.
Validation failed — the body is a field → messages map (Laravel shape) or the platform envelope with a stable machine-readable code. Fix the payload and resubmit.
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.