Skip to main content

​
What It Does

The Bulk Updates API lets you submit large-scale product attribute changes as a background job. Items are processed in batches with per-item error isolation — a single failing row does not abort the entire job.

​
Typical Flow

  1. Create job — submit a list of product patches via create_bulk_update_job.
  2. Check progress — poll job status via get_bulk_update_job.
  3. Inspect items — retrieve per-item outcomes via list_bulk_update_job_items.

​
Authentication & Permissions

All RPCs require an authenticated session. Mutations require a role with sufficient permissions for the target brand.

​
RPCs

​
create_bulk_update_job

Creates a new bulk update job with one or more product patches. Request 
{
  "_brand_id": "uuid",
  "_items": [
    { "product_id": "uuid", "patch": { "attributes": { "weight_kg": 1.5 } } }
  ],
  "_idempotency_key": "optional-string"
}
Response 
{
  "id": "uuid",
  "status": "queued",
  "total_items": 1,
  "processed_items": 0,
  "success_items": 0,
  "error_items": 0,
  "created_at": "2026-01-15T12:00:00Z"
}
Errors
  • Not authenticated — request has no valid JWT.
  • Forbidden — caller does not have sufficient access.
  • Invalid input — request is malformed or cannot be processed.
Notes
  • Idempotency is supported: submitting the same _idempotency_key twice returns the existing job.
  • Only one job per brand is typically active at a time.

​
get_bulk_update_job

Returns the current state of a single bulk update job. Request 
{
  "_brand_id": "uuid",
  "_job_id": "uuid"
}
Response 
{
  "id": "uuid",
  "status": "processing",
  "total_items": 50,
  "processed_items": 30,
  "success_items": 28,
  "error_items": 2,
  "started_at": "2026-01-15T12:01:00Z",
  "completed_at": null
}
Errors
  • Not authenticated — request has no valid JWT.
  • Forbidden — caller does not have sufficient access.
  • Invalid input — request is malformed or cannot be processed.

​
list_bulk_update_jobs

Lists bulk update jobs for a brand, ordered by creation date (newest first). Request 
{
  "_brand_id": "uuid",
  "_limit": 20,
  "_offset": 0
}
Response 
[
  {
    "id": "uuid",
    "status": "completed",
    "total_items": 50,
    "success_items": 50,
    "error_items": 0,
    "created_at": "2026-01-15T12:00:00Z",
    "completed_at": "2026-01-15T12:05:00Z"
  }
]
Errors
  • Not authenticated — request has no valid JWT.
  • Forbidden — caller does not have sufficient access.
  • Invalid input — request is malformed or cannot be processed.

​
list_bulk_update_job_items

Returns individual item outcomes for a job, with pagination. Request 
{
  "_brand_id": "uuid",
  "_job_id": "uuid",
  "_limit": 50,
  "_offset": 0
}
Response 
[
  {
    "id": "uuid",
    "product_id": "uuid",
    "status": "success",
    "error_message": null,
    "validation_warnings": [],
    "attempt_count": 1
  },
  {
    "id": "uuid",
    "product_id": "uuid",
    "status": "error",
    "error_message": "Invalid attribute value for weight_kg",
    "validation_warnings": [],
    "attempt_count": 3
  }
]
Errors
  • Not authenticated — request has no valid JWT.
  • Forbidden — caller does not have sufficient access.
  • Invalid input — request is malformed or cannot be processed.
Notes
  • Items that fail after 3 attempts are marked as permanently failed.