> ## Documentation Index > Fetch the complete documentation index at: https://docs.closient.com/llms.txt > Use this file to discover all available pages before exploring further. # Upsert retailer product listings in bulk > Create or update up to 500 retailer product listings, keyed on (retailer, GTIN), returning a per-row result. Idempotent: rerunning an unchanged feed writes nothing new. Badges and per-property URLs are **synced** to each payload, so a badge the retailer dropped stops rendering on the next run — with one deliberate asymmetry: an empty `urls` list means 'this feed has no URL information' and deactivates nothing, while a non-empty list deactivates the properties it omits. A row whose GTIN has no product is reported as `unknown_gtin` and writes nothing; listings never create products, so per-field provenance is only ever written by the import engine. A row naming a storefront this retailer has no active property for is reported as `invalid` — declare the property with `POST /retailers/{retailer_id}/storefronts` first. `retailer_id` is a `retailers.Retailer`. An organization-private retailer requires OWNER or MANAGER on the organization that owns it; a canonical (Closient-curated) retailer requires a staff account. Returns 200 with a per-row error report even on partial success. Attribute-bound breaches are 422 naming the offending row, because the caller must change what it sends. ## OpenAPI ````yaml /openapi/openapi-retailers.json post /retailers/api/v1/retailers/{retailer_id}/listings/batch openapi: 3.1.0 info: title: Retailers API version: 1.0.0 description: > Manage retailers, in-store offers, and online offers. ## Authentication All endpoints require an API key passed via the `X-API-Key` HTTP header, unless otherwise noted. ``` X-API-Key: csb__ ``` Generate API keys in **Settings > API Keys** in your dashboard, or via the Account API. Session-based (cookie) authentication is also accepted for browser-based access. ## Rate Limits | Tier | Requests / minute | Requests / day | |-------------|-------------------|----------------| | Default | 300 | 10,000 | | Custom | Contact us | Contact us | Rate-limit headers are included on every response so callers can self-throttle without hitting our 429s ("informed governor"): - `RateLimit-Policy` — every active window, e.g. `300;w=60, 10000;w=86400` - `RateLimit-Limit` — quota for the **most-restrictive** currently-active window - `RateLimit-Remaining` — requests left in that window - `RateLimit-Reset` — seconds until that window resets (relative; clock-skew safe) Legacy `X-RateLimit-*` aliases are also emitted for back-compat. `X-RateLimit-Reset` keeps the absolute Unix-timestamp shape to avoid breaking existing consumers. When rate-limited, you receive `429 Too Many Requests` with a `retry_after_seconds` field in the error envelope and a `Retry-After` header. ## Pagination List endpoints return paginated results in this envelope: ```json { "data": [...], "pagination": { "page": 1, "page_size": 25, "total_count": 342, "total_pages": 14, "has_next": true, "has_previous": false } } ``` Use `?page=2&page_size=50` query parameters. Maximum page size is 100. ## Error Responses All errors conform to [RFC 9457 Problem Details](https://www.rfc-editor.org/rfc/rfc9457) with `Content-Type: application/problem+json`: ```json { "type": "https://closient.com/docs/errors/not_found", "title": "Not Found", "status": 404, "detail": "The requested resource was not found.", "error_code": "not_found", "retryable": false, "timestamp": "2026-03-31T12:00:00+00:00" } ``` Common error codes: `unauthorized` (401), `forbidden` (403), `not_found` (404), `validation_error` (422), `rate_limited` (429), `internal_error` (500). termsOfService: https://www.closient.com/terms/ servers: - url: https://www.closient.com security: [] tags: - name: Retailers description: Manage retailers (canonical and org-private). - name: In-store Offers description: Per-store physical offers (aisle, on-hand quantity, pickup). - name: Online Offers description: Per-storefront online offers (URL, delivery, fulfillment). - name: In-store Offer Promotions description: Time-windowed promotional pricing on in-store offers. - name: Online Offer Promotions description: Time-windowed promotional pricing on online offers. - name: Retailer Stores description: >- Physical storefront upsert, reconciled against existing stores by store number, then proximity, then normalised address — a match enriches in place rather than creating a near-duplicate. - name: Retailer Listings description: >- Retailer-scoped product listings (SKU, badges, per-property URLs, extensible attributes) and the web properties those URLs attach to. externalDocs: description: Closient Documentation url: https://docs.closient.com paths: /retailers/api/v1/retailers/{retailer_id}/listings/batch: post: tags: - Retailer Listings summary: Upsert retailer product listings in bulk description: >- Create or update up to 500 retailer product listings, keyed on (retailer, GTIN), returning a per-row result. Idempotent: rerunning an unchanged feed writes nothing new. Badges and per-property URLs are **synced** to each payload, so a badge the retailer dropped stops rendering on the next run — with one deliberate asymmetry: an empty `urls` list means 'this feed has no URL information' and deactivates nothing, while a non-empty list deactivates the properties it omits. A row whose GTIN has no product is reported as `unknown_gtin` and writes nothing; listings never create products, so per-field provenance is only ever written by the import engine. A row naming a storefront this retailer has no active property for is reported as `invalid` — declare the property with `POST /retailers/{retailer_id}/storefronts` first. `retailer_id` is a `retailers.Retailer`. An organization-private retailer requires OWNER or MANAGER on the organization that owns it; a canonical (Closient-curated) retailer requires a staff account. Returns 200 with a per-row error report even on partial success. Attribute-bound breaches are 422 naming the offending row, because the caller must change what it sends. operationId: apps_retailers_api_listings_upsert_listings_batch parameters: - in: path name: retailer_id schema: description: Unique identifier of the retailer these listings belong to. format: shortuuid maxLength: 22 minLength: 22 pattern: ^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$ title: Retailer Id type: string required: true description: Unique identifier of the retailer these listings belong to. requestBody: content: application/json: schema: $ref: '#/components/schemas/ListingBatchIn' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ListingUpsertResultOut' '400': description: Bad Request content: application/problem+json: schema: $ref: '#/components/schemas/ErrorOut' '401': description: Unauthorized content: application/problem+json: schema: $ref: '#/components/schemas/ErrorOut' '403': description: Forbidden content: application/problem+json: schema: $ref: '#/components/schemas/ErrorOut' '404': description: Not Found content: application/problem+json: schema: $ref: '#/components/schemas/ErrorOut' '405': description: Method Not Allowed content: application/problem+json: schema: $ref: '#/components/schemas/ErrorOut' '422': description: Unprocessable Content content: application/problem+json: schema: $ref: '#/components/schemas/ErrorOut' '429': description: Too Many Requests content: application/problem+json: schema: $ref: '#/components/schemas/ErrorOut' security: - APIKeyHeaderAuth: [] - OAuthTokenAuth: [] - CookieGatedSessionAuth: [] components: schemas: ListingBatchIn: description: A batch of listing rows. examples: - dry_run: false rows: - attributes: Category1: Skin Care badges: - label: Clean at Sephora gtin: '00614141000036' sku: '2512345' urls: - store_url: https://www.sephora.com url: https://www.sephora.com/product/example-P123456 source: sephora_catalog properties: rows: description: >- Listing rows, at most 500 per call. Results come back in request order, each carrying its `index`. For a whole retailer catalog use the `retailer-catalog` import job instead — it merges products and listings together under one cross-retailer precedence policy. items: $ref: '#/components/schemas/ListingRowIn' maxItems: 500 minItems: 1 title: Rows type: array source: default: '' description: >- Dataset name recorded on each listing's `source` column, for provenance. maxLength: 100 title: Source type: string dry_run: default: false description: >- Execute everything and roll back. Defaults to false, unlike the store upsert: a listing write is a targeted change the caller named by GTIN, not a reconciliation whose matching decisions want previewing first. title: Dry Run type: boolean required: - rows title: ListingBatchIn type: object ListingUpsertResultOut: description: >- Batch census plus the per-row results. ``created + updated + unknown_gtin + invalid + errors`` equals the number of submitted rows for any 200 response. Per-row failures are reported here rather than aborting the batch; only request-level failures are 4xx. examples: - committed: true created: 1 errors: 0 invalid: 0 rows: - badges: 2 error: '' gtin: '00614141000036' index: 0 listing_id: b2c3d4e5-f678-9012-abcd-ef2345678901 outcome: created urls: 1 submitted_rows: 2 unknown_gtin: 0 updated: 1 properties: committed: description: False when this was a dry run and the transaction was rolled back. title: Committed type: boolean submitted_rows: description: Number of rows in the request. minimum: 0 title: Submitted Rows type: integer created: description: Rows that produced a new listing. minimum: 0 title: Created type: integer updated: description: Rows that refreshed an existing listing. minimum: 0 title: Updated type: integer unknown_gtin: description: Rows whose GTIN has no product. Nothing was written for them. minimum: 0 title: Unknown Gtin type: integer invalid: description: Rows rejected by barcode or storefront validation. minimum: 0 title: Invalid type: integer errors: description: Rows that raised. minimum: 0 title: Errors type: integer rows: description: One result per submitted row, in request order. items: $ref: '#/components/schemas/ListingRowResultOut' title: Rows type: array required: - committed - submitted_rows - created - updated - unknown_gtin - invalid - errors title: ListingUpsertResultOut type: object ErrorOut: description: |- RFC 9457 Problem Details response. All API errors are returned in this format with Content-Type: application/problem+json. examples: - detail: The requested resource was not found. error_code: not_found retryable: false status: 404 timestamp: '2026-03-31T12:00:00+00:00' title: Not Found type: https://closient.com/docs/errors/not_found - detail: Validation error. details: - loc: - body - name msg: Field required type: missing error_code: validation_error retryable: false status: 422 timestamp: '2026-03-31T12:00:00+00:00' title: Validation Error type: https://closient.com/docs/errors/validation_error - detail: Rate limit exceeded. Please try again later. error_code: rate_limited retry_after: 31 retryable: true status: 429 timestamp: '2026-03-31T12:00:00+00:00' title: Rate Limited type: https://closient.com/docs/errors/rate_limited properties: type: description: URI reference identifying the error type. title: Type type: string title: description: Short human-readable summary of the error. title: Title type: string status: description: HTTP status code. title: Status type: integer detail: description: Human-readable explanation of this specific occurrence. title: Detail type: string error_code: description: Machine-readable error code (e.g. not_found, unauthorized). title: Error Code type: string retryable: default: false description: Whether retrying the same request can succeed. title: Retryable type: boolean timestamp: description: ISO 8601 timestamp of when the error occurred. title: Timestamp type: string retry_after: anyOf: - type: integer - type: 'null' description: Seconds to wait before retrying (when applicable). title: Retry After owner_action_required: anyOf: - type: boolean - type: 'null' description: Whether the error requires account owner intervention. title: Owner Action Required details: description: Additional context (validation errors, etc.). title: Details required: - type - title - status - detail - error_code - timestamp title: ErrorOut type: object ListingRowIn: description: One retailer product listing, keyed on GTIN within the path retailer. examples: - attributes: Category1: Skin Care Category2: Moisturizers highlights: - Vegan - Fragrance Free badges: - label: Good For Oily Hair - label: Clean at Sephora gtin: '00614141000036' is_active: true sku: '2512345' source_reference: '2512345' urls: - store_url: https://www.sephora.com url: https://www.sephora.com/product/example-P123456 properties: gtin: description: >- GTIN of the product being listed, digits only. Normalised to GTIN-14 before lookup, so an 8, 12 or 13-digit barcode is accepted as sent. The product must already exist — a listing never creates one, so that per-field provenance is only ever written by the import engine. pattern: ^\d{8,14}$ title: Gtin type: string sku: default: '' description: The retailer's internal SKU for this product. maxLength: 100 title: Sku type: string badges: description: >- Designations the retailer applies to this product. Retailer-scoped and attached to the listing, never to the shared product — a badge is a retailer's marketing claim, not a certification. Repeats of the same derived slug are collapsed rather than rejected, because feeds routinely repeat a badge. Syncing is exact: a badge absent from this payload stops rendering. items: $ref: '#/components/schemas/ListingBadgeIn' title: Badges type: array urls: description: >- One product URL per retailer web property, at most one per storefront. An **empty** list means 'this feed carries no URL information' and deactivates nothing — deliberately not symmetric with a non-empty list, which deactivates the properties it omits. A feed with no URL column (Ulta's PSV) would otherwise switch off every URL another feed supplied. items: $ref: '#/components/schemas/ListingURLItemIn' title: Urls type: array attributes: additionalProperties: true description: >- Retailer-scoped facts with no typed column yet, under their original feed names. A bounded staging area, not a document store: at most 200 keys, keys 1-60 characters, string values up to 8000 characters, lists up to 250 items. Exceeding a bound fails the row loudly — the pressure to promote a recurring key to a real column is the point. title: Attributes type: object is_active: default: true description: False when the retailer has dropped the product. title: Is Active type: boolean source_reference: default: '' description: The retailer's own product identifier in the feed. maxLength: 255 title: Source Reference type: string required: - gtin title: ListingRowIn type: object ListingRowResultOut: description: What happened to one submitted listing row. examples: - badges: 1 error: '' gtin: '00614141000036' index: 0 listing_id: b2c3d4e5-f678-9012-abcd-ef2345678901 outcome: created urls: 1 - badges: 0 error: No product with GTIN 00614141000043. gtin: '00614141000043' index: 1 listing_id: '' outcome: unknown_gtin urls: 0 properties: index: description: Zero-based position of this row in the submitted `rows` array. minimum: 0 title: Index type: integer gtin: description: >- The GTIN for this row, normalised to GTIN-14 where it normalised at all. title: Gtin type: string outcome: description: >- `created` — this retailer had no listing for the product and one was written. `updated` — the existing listing was refreshed; badges and URLs synced to the payload. `unknown_gtin` — no product carries that GTIN, so nothing was written (a listing never creates a product). `invalid` — the barcode failed check-digit validation, or the row named a storefront this retailer has no active property for. `error` — the row raised; see `error`. The rest of the batch still applied. title: Outcome type: string listing_id: default: '' description: Identifier of the written listing. Empty when nothing was written. title: Listing Id type: string badges: default: 0 description: Badges synced onto the listing from this row. minimum: 0 title: Badges type: integer urls: default: 0 description: Per-property URLs synced onto the listing from this row. minimum: 0 title: Urls type: integer error: default: '' description: Failure detail for a non-success outcome. Empty otherwise. title: Error type: string required: - index - gtin - outcome title: ListingRowResultOut type: object ListingBadgeIn: description: One retailer designation as the retailer words it. examples: - description: The retailer's own suitability designation for this product. icon_url: https://www.ulta.com/img/badges/oily-hair.svg label: Good For Oily Hair slug: good-for-oily-hair source_reference: ATTR_OILY properties: label: description: Badge text as the retailer words it. maxLength: 255 minLength: 1 title: Label type: string slug: default: '' description: >- Stable per-retailer key. Derived from `label` when blank, so a retailer rewording 'Good For Oily Hair' to 'Good for oily hair' updates the existing badge instead of creating a second one. Supply one explicitly when the label is only punctuation or emoji, which has no derivable key and is otherwise rejected. maxLength: 255 title: Slug type: string description: default: '' description: What the retailer means by this badge. maxLength: 5000 title: Description type: string icon_url: default: '' description: Retailer-hosted badge artwork, when supplied. maxLength: 1000 title: Icon Url type: string source_reference: default: '' description: The retailer's own identifier for this badge. maxLength: 255 title: Source Reference type: string required: - label title: ListingBadgeIn type: object ListingURLItemIn: description: The product's URL on one of the retailer's web properties. examples: - store_url: https://www.sephora.ca url: https://www.sephora.ca/product/example-P123456 properties: store_url: description: >- Root URL of the storefront this product URL lives on — the property's identity, not a product page. Must already exist as an active storefront for this retailer; declare it with `POST /retailers/{retailer_id}/storefronts` first. Listings never create a storefront implicitly, because at import scale that would fabricate retailer web properties nobody has confirmed exist. maxLength: 500 minLength: 1 title: Store Url type: string url: description: The product's page on that storefront. maxLength: 1000 minLength: 1 title: Url type: string required: - store_url - url title: ListingURLItemIn type: object securitySchemes: APIKeyHeaderAuth: type: apiKey in: header name: X-API-Key OAuthTokenAuth: type: http scheme: bearer CookieGatedSessionAuth: type: apiKey in: cookie name: sessionid ````