API: Bulk Updates

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

1
{
2
  "_brand_id": "uuid",
3
  "_items": [{ "product_id": "uuid", "patch": { "attributes": { "weight_kg": 1.5 } } }],
4
  "_idempotency_key": "optional-string"
5
}

Response

1
{
2
  "id": "uuid",
3
  "status": "queued",
4
  "total_items": 1,
5
  "processed_items": 0,
6
  "success_items": 0,
7
  "error_items": 0,
8
  "created_at": "2026-01-15T12:00:00Z"
9
}

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

1
{
2
  "_brand_id": "uuid",
3
  "_job_id": "uuid"
4
}

Response

1
{
2
  "id": "uuid",
3
  "status": "processing",
4
  "total_items": 50,
5
  "processed_items": 30,
6
  "success_items": 28,
7
  "error_items": 2,
8
  "started_at": "2026-01-15T12:01:00Z",
9
  "completed_at": null
10
}

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

1
{
2
  "_brand_id": "uuid",
3
  "_limit": 20,
4
  "_offset": 0
5
}

Response

1
[
2
  {
3
    "id": "uuid",
4
    "status": "completed",
5
    "total_items": 50,
6
    "success_items": 50,
7
    "error_items": 0,
8
    "created_at": "2026-01-15T12:00:00Z",
9
    "completed_at": "2026-01-15T12:05:00Z"
10
  }
11
]

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

1
{
2
  "_brand_id": "uuid",
3
  "_job_id": "uuid",
4
  "_limit": 50,
5
  "_offset": 0
6
}

Response

1
[
2
  {
3
    "id": "uuid",
4
    "product_id": "uuid",
5
    "status": "success",
6
    "error_message": null,
7
    "validation_warnings": [],
8
    "attempt_count": 1
9
  },
10
  {
11
    "id": "uuid",
12
    "product_id": "uuid",
13
    "status": "error",
14
    "error_message": "Invalid attribute value for weight_kg",
15
    "validation_warnings": [],
16
    "attempt_count": 3
17
  }
18
]

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.