---
title: "List catalog variance batches"
method: GET
path: "/catalog/variance-batches"
tags: ["catalog"]
---

# List catalog variance batches

`GET /catalog/variance-batches`

Returns Catalog Variance Manager batches for the given company. Omit export_status to return both draft and exported batches; pass export_status=draft or export_status=exported to narrow to one state. The costbatch_payload in each result matches the Pyxis /costbatch format exactly, for both draft and exported batches.

Sort order: draft batches are ordered by costbatch_payload.start_datetime (newest first) — this is the same start_date value used internally, exposed on the response only inside costbatch_payload. Exported batches are ordered by exported_at (newest first). When export_status is omitted, results are ordered by exported_at for exported batches and costbatch_payload.start_datetime for draft batches, newest first, and draft batches are always included regardless of any exported_after*/exported_before* filter — those only ever narrow exported batches. In every case, id is used as a secondary sort key, so ordering is fully deterministic — identical requests return tied batches in the same order, and paginating through a stable result set returns each batch exactly once.

## Query parameters

- `ottimate_company_id` integer, required
- `batch_number` integer
- `export_status` 'draft' | 'exported'
- `exported_after` string, date-time
- `exported_after_utc` string, date-time
- `exported_before` string, date-time
- `exported_before_utc` string, date-time
- `page` integer
- `limit` integer

## Headers

- `Authorization` string, required
- `X-Api-Key` string, required
- `X-API-Version` string

## Response `200`

Successful response with paginated batch list

- CatalogVarianceBatchListResponse — Paginated list of catalog variance batches (draft and/or exported).
  - `version` string — The API version of the response.
  - `count` integer — Total number of results
  - `page` integer — Current page number
  - `limit` integer — Number of results per page
  - `results` CatalogVarianceBatchObject[]
    - `id` string, required — Unique batch identifier (prefixed with ctb_)
    - `ottimate_company_id` integer, required — Company ID this batch belongs to
    - `batch_number` integer, required — Sequential batch number within the company
    - `export_status` 'draft' | 'exported', required — 'draft' when exported_at is null, 'exported' once exported_at is set
    - `exported_at` string, date-time, nullable — Timestamp when the batch was exported. Null for draft batches.
    - `exported_at_utc` string, date-time, nullable — UTC equivalent of exported_at. ISO 8601 with Z suffix, e.g. "2025-05-20T15:17:35.652584Z". Null for draft batches.
    - `costbatch_payload` CostBatchPayload, required — Costbatch payload in the same shape as the Pyxis /costbatch endpoint.
      - `description` string — Human-readable batch description, e.g. 'Catalog Batch 42'
      - `zone` string — Geographical zone for this batch
      - `import_def_id` integer — Pyxis import definition ID from the company token. Defaults to 0 if no Pyxis token is configured.
      - `external_batch_number` string — String representation of the batch number
      - `start_datetime` string, date-time — Start date for this batch's price updates
      - `catalog_items` CatalogItemPayload[] — List of catalog items with updated costs

## Other responses

- `400` — Bad request - Invalid parameters or request format
- `403` — Forbidden - Access denied or insufficient permissions

---

[API](https://skmtc.dev/ottimate/apis/api-reference.md) · [All operations](https://skmtc.dev/ottimate/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ottimate/api-reference/revisions/ba91ff4c6969/schema)