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

# Manage Product Offers

> Record, correct, list, and delete where a product is sold -- its in-store and online offers and their promotions -- the programmatic equivalent of the dashboard's product Offers page.

Programmatic equivalent of the dashboard's `products/<gtin>/offers/` page.

## When to use

* A brand owner needs to record which physical stores and which websites sell a product,
  at what price and with what availability.
* An offer on file is out of date (a price, a status, a stock level) and needs correcting.

## Auth

`X-API-Key` header or OAuth token. Writing an offer takes the **Manage offers**
(`MANAGE_OFFERS`) permission on the organization, which a member with the Editor, Manager
or Owner role holds, and so does an API key with the Editor or Manager role. A read-only
key is refused. Every refusal answers `404`, not `403`, so the API never confirms that
another organization or its offers exist.

## Find the store first

An offer names one store by id. Look it up; never create one from this workflow.

```
GET /retailers/api/v1/retailers?search=<name>              # this organization's and shared retailers
GET /retailers/api/v1/retailers/{retailer_id}/stores       # physical stores
GET /retailers/api/v1/retailers/{retailer_id}/storefronts  # websites
```

A shared (Closient-curated) retailer's stores are open to every organization. Another
organization's private retailer is not: an offer at one of its stores answers `404`.

## Flow

```
GET    /retailers/api/v1/organizations/{organization_id}/in-store-offers?scope=on_products
POST   /retailers/api/v1/organizations/{organization_id}/in-store-offers
GET    /retailers/api/v1/in-store-offers/{offer_id}
PUT    /retailers/api/v1/in-store-offers/{offer_id}
DELETE /retailers/api/v1/in-store-offers/{offer_id}
```

Online offers use the same shapes under `online-offers`.

* **List** -- paginated. The default lists the offers this organization submitted;
  `scope=on_products` adds the ones other organizations submitted on its products.
* **Create** -- the body names the product with `product_id` and the store with
  `physical_store_id` (in-store) or `online_store_id` (online); fields are listed in the
  OpenAPI document at `/retailers/api/v1/openapi.json`. A new offer starts `active`; the
  `(product_id, store_id, sku)` triple must be unique (`422` otherwise). Creation is
  rate-limited per organization (`429` with `retry_after`).
* **Update** -- `PUT` with the fields to change; the body also accepts `status`. Only the
  organization that submitted an offer may update it.
* **Delete** -- the submitting organization may delete an offer, and so may the
  organization that owns the product while the offer is another organization's unverified
  submission: a brand can remove such an offer on its product, but never rewrite it. Once
  Closient has verified an offer, only its submitter can delete it.
* **Read back** -- every write returns the saved offer; `GET` it again to confirm.

## Promotions

A promotion hangs off one offer and follows that offer's permission:

```
GET    /retailers/api/v1/in-store-offers/{offer_id}/promotions
POST   /retailers/api/v1/in-store-promotions
GET    /retailers/api/v1/in-store-promotions/{promotion_id}
PUT    /retailers/api/v1/in-store-promotions/{promotion_id}
DELETE /retailers/api/v1/in-store-promotions/{promotion_id}
```

Online promotions use the same shapes under `online-offers` and `online-promotions`.

## Notes

Returns `404` for a read-only key, another organization's offer or private store, or a
product or store that does not exist; `422` for an invalid value. An offer on a product
another organization owns is stored but hidden from public surfaces until Closient
verifies it. The fields an organization writes on an offer are defined once on the model
(`EDITABLE_FIELDS`).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.