> ## Documentation Index
> Fetch the complete documentation index at: https://docs.printools.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Garments and catalogue

> Styles, variants, assets, and the whole-catalogue route.

Use the operations below to work with garments & catalogue. Each link opens an interactive reference page generated from the published OpenAPI specification.

## Import batch IDs

`importBatchId` must be a UUID, such as `11111111-2222-3333-4444-555555555555`, rather than a free-form import label. This applies to garment bulk upsert, variant bulk upsert, and bulk status-and-stock updates. Reuse the batch UUID when updating the status or stock of the same imported batch. Invalid supplied IDs return HTTP `400` with error code `VALIDATION`.

The batch ID is optional for the two upsert operations and required for status-and-stock updates. The downloadable [OpenAPI specification](https://d1zl72794e73i2.cloudfront.net/releases/2026-09-08.api-blackbox/openapi.json) and [Postman collection](https://d1zl72794e73i2.cloudfront.net/releases/2026-09-08.api-blackbox/printools.postman_collection.json) include valid UUID examples.

Status-and-stock updates affect only garments and variants **created by that import batch**. Updating an existing item through an upsert does not move it into the new batch. Check `garmentsUpdated` and `variantsUpdated`: a successful response with both counts at zero means no items were changed.

## Operations

| Operation                                                                                                                                                                      | Method and path                              | Required scopes                     |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------- | ----------------------------------- |
| [List garments, the shop's own items and the supplier catalogue](/api/reference/get_v1_garments)                                                                               | `GET /v1/garments`                           | `garments.read`                     |
| [Create a garment](/api/reference/post_v1_garments)                                                                                                                            | `POST /v1/garments`                          | `garments.write`                    |
| [Filter facets for the garment list](/api/reference/get_v1_garments_facets)                                                                                                    | `GET /v1/garments/facets`                    | `garments.read`                     |
| [Garment assets](/api/reference/get_v1_garments_assets)                                                                                                                        | `GET /v1/garments/assets`                    | `garments.read`                     |
| [One garment](/api/reference/get_v1_garments_garmentId)                                                                                                                        | `GET /v1/garments/{garmentId}`               | `garments.read`                     |
| [Update a garment](/api/reference/patch_v1_garments_garmentId)                                                                                                                 | `PATCH /v1/garments/{garmentId}`             | `garments.write`                    |
| [Delete a garment](/api/reference/delete_v1_garments_garmentId)                                                                                                                | `DELETE /v1/garments/{garmentId}`            | `garments.write`                    |
| [Every variant of one style code](/api/reference/get_v1_garment_variants_styleCode)                                                                                            | `GET /v1/garment-variants/{styleCode}`       | `garments.read`                     |
| [Create a garment variant](/api/reference/post_v1_garment_variants)                                                                                                            | `POST /v1/garment-variants`                  | `garments.write`                    |
| [Update a garment variant](/api/reference/patch_v1_garment_variants_id_variantId)                                                                                              | `PATCH /v1/garment-variants/id/{variantId}`  | `garments.write`                    |
| [Delete a garment variant](/api/reference/delete_v1_garment_variants_id_variantId)                                                                                             | `DELETE /v1/garment-variants/id/{variantId}` | `garments.write`                    |
| [Create a garment asset](/api/reference/post_v1_garment_assets)                                                                                                                | `POST /v1/garment-assets`                    | `garments.write`                    |
| [Update a garment asset](/api/reference/patch_v1_garment_assets_assetId)                                                                                                       | `PATCH /v1/garment-assets/{assetId}`         | `garments.write`                    |
| [Delete a garment asset](/api/reference/delete_v1_garment_assets_assetId)                                                                                                      | `DELETE /v1/garment-assets/{assetId}`        | `garments.write`                    |
| [Create many garments in one call](/api/reference/post_v1_garments_bulk_create)                                                                                                | `POST /v1/garments/bulk/create`              | `garments.write`                    |
| [Upsert a catalogue of garments in one set-based call](/api/reference/post_v1_garments_bulk_upsert)                                                                            | `POST /v1/garments/bulk/upsert`              | `garments.write`                    |
| [Patch every garment matching a target](/api/reference/post_v1_garments_bulk_update)                                                                                           | `POST /v1/garments/bulk/update`              | `garments.write`                    |
| [Delete every garment matching a target](/api/reference/post_v1_garments_bulk_delete)                                                                                          | `POST /v1/garments/bulk/delete`              | `garments.write`                    |
| [Create many garment variants in one call](/api/reference/post_v1_garment_variants_bulk_create)                                                                                | `POST /v1/garment-variants/bulk/create`      | `garments.write`                    |
| [Upsert garment variants in one set-based call](/api/reference/post_v1_garment_variants_bulk_upsert)                                                                           | `POST /v1/garment-variants/bulk/upsert`      | `garments.write`                    |
| [Set status and stock across an import batch](/api/reference/post_v1_garments_bulk_status_and_stock)                                                                           | `POST /v1/garments/bulk/status-and-stock`    | `garments.write`                    |
| [The shop's whole catalogue in one call: their own items and the supplier catalogue, variants inline. Cursor-paged; ?source=manual\|ascolour](/api/reference/get_v1_catalogue) | `GET /v1/catalogue`                          | `garments.read`, `decorations.read` |

See [Authentication](/api/authentication) before your first call. For write retries, see [Writing safely](/api/idempotency).