> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://tieback.io/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://tieback.io/docs/_mcp/server.

# API: Bulk Updates

> Run asynchronous background jobs for large-scale product attribute updates, covering job submission, progress polling, results and failure handling.

> **Programmatic access — early access**
>
> The
>
> **tie*back***
>
> API is available to selected workspaces during early access. Endpoints in production today are
> authenticated with an authenticated session. Standalone API-key access is being onboarded per
> workspace. Contact
>
> **tie*back***
>
> to enable API credentials for your workspace.

## 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**

```json
{
  "_brand_id": "uuid",
  "_items": [{ "product_id": "uuid", "patch": { "attributes": { "weight_kg": 1.5 } } }],
  "_idempotency_key": "optional-string"
}
```

**Response**

```json
{
  "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**

```json
{
  "_brand_id": "uuid",
  "_job_id": "uuid"
}
```

**Response**

```json
{
  "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**

```json
{
  "_brand_id": "uuid",
  "_limit": 20,
  "_offset": 0
}
```

**Response**

```json
[
  {
    "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**

```json
{
  "_brand_id": "uuid",
  "_job_id": "uuid",
  "_limit": 50,
  "_offset": 0
}
```

**Response**

```json
[
  {
    "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.

## Related Docs

* [Bulk Updates](/product-module/bulk-updates)
* [API: Products](/api-reference/api-products)
* [Bulk Editing](/product-module/bulk-editing)
* [API: Credentials](/api-reference/api-credentials)