> For the complete documentation index, see [llms.txt](https://docs.violet.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.violet.io/prism/webhooks/events/offer-webhooks.md).

# Offers

The offer webhook events, when each one fires, and how OFFER\_REMOVED differs from OFFER\_DELETED.

Offer webhooks tell your app when an offer changes: when it becomes available to you, when its data changes, when you lose access to it, and when it is permanently deleted. Use them to keep your catalog current without re-syncing it.

Sync events such as `PRODUCT_SYNC_STARTED` and `PRODUCT_SYNC_COMPLETED` mark catalog-wide operations. Offer webhooks fire per offer, as each one changes. Each event is a separate [webhook subscription](https://docs.violet.io/prism/webhooks/managing-webhooks.md).

## Events at a glance

| Event                                        | Fires when                                  | Offer still exists in Violet? |
| -------------------------------------------- | ------------------------------------------- | ----------------------------- |
| [`OFFER_ADDED`](#offer_added)                | An offer becomes available to your app      | Yes                           |
| [`OFFER_UPDATED`](#offer_updated)            | A published offer changes                   | Yes                           |
| [`OFFER_REMOVED`](#offer_removed)            | An offer is no longer available to your app | Yes                           |
| [`OFFER_DELETED`](#offer_deleted)            | An offer is permanently deleted from Violet | No                            |
| [`OFFER_CREATED`](#offer_created-deprecated) | Deprecated. Use `OFFER_ADDED`               | n/a                           |

{% hint style="info" %}
**`OFFER_REMOVED` is not `OFFER_DELETED`.** `OFFER_REMOVED` means the offer left *your catalog*. It still exists in Violet and can come back. `OFFER_DELETED` means the offer left *Violet* for good. Neither is a bulk event: both are sent once per offer. See [Removed versus deleted](#removed-versus-deleted).
{% endhint %}

## Offer status

Every offer webhook carries the full [Offer](https://docs.violet.io/prism/catalog/offers.md). Two fields describe where the offer is in its lifecycle.

**`publishing_status`** says whether the offer is published to the catalog. Offer webhooks fire for published offers.

| Value           | Meaning                                                                 |
| --------------- | ----------------------------------------------------------------------- |
| `PUBLISHED`     | The offer is published and discoverable                                 |
| `NOT_PUBLISHED` | The offer is not published and is not discoverable through Offer Search |

**`status`** says whether the offer can be bought and where it is in its lifecycle.

| Value                  | Meaning                                                                                                                 |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `AVAILABLE`            | In stock and can be purchased                                                                                           |
| `UNAVAILABLE`          | Out of stock or unavailable on the merchant's platform                                                                  |
| `DISABLED_AVAILABLE`   | The merchant was disabled while the offer was available                                                                 |
| `DISABLED_UNAVAILABLE` | The merchant was disabled while the offer was unavailable                                                               |
| `ARCHIVED`             | The product was deleted on the merchant's platform. Violet keeps the offer as a snapshot for a while before deleting it |
| `FOR_DELETION`         | The offer is queued for permanent deletion from Violet                                                                  |

See [What statuses can be associated with an Offer?](https://docs.violet.io/prism/catalog/offers.md#what-statuses-can-be-associated-with-an-offer) for how to act on each one.

## Available events

### OFFER\_ADDED

An offer has become available to your app.

**Fires when:**

* A new offer is published as soon as it is created
* An existing offer moves to `PUBLISHED`
* A merchant first connects to your app and already has published offers

**What to do:** Fetch the current offer, then add it to your catalog and search index. If you removed it earlier, restore it. Fetching matters because a delayed `OFFER_ADDED` can arrive after the offer has been removed again. Check availability and inventory before showing it to shoppers. This is your primary signal for new offers.

### OFFER\_UPDATED

A published offer has changed.

**Fires when** any offer data changes, including price, inventory, description, images, SKUs, variants, and attributes. It is also sent alongside `OFFER_REMOVED` when an offer is unpublished or marked for deletion, so you can receive both for the same change.

**What to do:** Treat the event as a signal to refresh. Fetch the current offer with [Get Offer by ID](https://docs.violet.io/api-reference/catalog/offers/get-offer-by-id.md) and update your copy from that response, not from the payload. Failed deliveries are retried for up to 24 hours, so an older update can arrive after a newer one and restore an outdated price or inventory level. A product can also send several updates in quick succession, so queue or debounce them and fetch once.

### OFFER\_REMOVED

An offer is no longer available to your app. **Nothing is deleted.** The offer keeps its ID and its data in Violet.

**Fires when:**

| Cause                                  | Details                                                                                                                                     |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| The offer is unpublished               | `publishing_status` changes from `PUBLISHED` to `NOT_PUBLISHED`, for one offer or for all of a merchant's offers. Sent with `OFFER_UPDATED` |
| The offer is marked for deletion       | `status` changes to `FOR_DELETION` while the offer is published. Sent with `OFFER_UPDATED`                                                  |
| The offer has no active SKUs left      | Violet archives the offer                                                                                                                   |
| The merchant disconnects from your app | One event per published offer, sent to the disconnected app only. Sent alongside `MERCHANT_DISCONNECTED`                                    |

**What to do:** Withdraw the offer from your catalog and search results, but keep your record of it. If the offer becomes available to your app again, you receive `OFFER_ADDED`. An offer marked for deletion is the exception: it is on its way to `OFFER_DELETED`.

**Does not fire for** an offer going out of stock or a price change. Those arrive as `OFFER_UPDATED`.

{% hint style="warning" %}
**Act on the event, not on the payload fields.** The payload is the offer as it stands when the event fires. When a merchant disconnects, the offer itself has not changed, only your access to it, so it can still show `publishing_status: PUBLISHED`.
{% endhint %}

### OFFER\_DELETED

An offer has been permanently deleted from Violet. It no longer exists, and the payload is its last state, with a `status` of `FOR_DELETION`.

**Fires when** Violet permanently deletes an offer record, for example when it:

* Cleans up offers that were marked for deletion
* Deletes a product and its offers
* Purges a merchant's catalog

Violet carries these operations out itself. Merchants and channels cannot delete offers, and there is no public API for it, so this event is rare.

**Sent once per offer, and only for published offers.** If Violet deletes 100 published offers, you receive 100 `OFFER_DELETED` webhooks. There is no batch payload. An offer that is not `PUBLISHED` when it is deleted sends nothing, for example one that was unpublished earlier and already sent `OFFER_REMOVED`.

**What to do:** Delete your record of the offer. Make your handler safe to run for an offer you have already removed, and for one you never saw an `OFFER_REMOVED` for.

### OFFER\_CREATED (deprecated)

`OFFER_CREATED` is deprecated and is no longer emitted for new offers. Use `OFFER_ADDED` instead, which also covers existing offers that become available to your app.

## Removed versus deleted

Both events mean an offer is gone, which is why they get confused. They answer different questions.

|                           | `OFFER_REMOVED`                                                                                   | `OFFER_DELETED`                        |
| ------------------------- | ------------------------------------------------------------------------------------------------- | -------------------------------------- |
| Question it answers       | Should this offer still be in my catalog?                                                         | Does this offer still exist in Violet? |
| What happened             | You lost access to the offer                                                                      | The offer was permanently deleted      |
| Offer in Violet afterward | Still exists, with the same ID                                                                    | Gone                                   |
| Can it come back?         | Often. You receive `OFFER_ADDED` if it becomes available again. Not if it was marked for deletion | No                                     |
| Caused by                 | Unpublishing, marking for deletion, losing the last active SKU, a merchant disconnecting          | Violet permanently deleting the offer  |
| How often                 | Common. Merchants drive most of it                                                                | Rare. Only Violet triggers it          |
| What to do                | Withdraw the offer from your catalog and search. Keep your record                                 | Delete your record                     |

{% hint style="info" %}
**Neither event is a bulk event.** Each is sent once per offer, with the same payload shape. Large operations simply send many of them: a merchant disconnecting sends `OFFER_REMOVED` for every published offer, and a catalog purge sends `OFFER_DELETED` for every published offer. Process them as a stream.
{% endhint %}

### What you receive, by scenario

| What happens                                                    | Events you receive                                                    |
| --------------------------------------------------------------- | --------------------------------------------------------------------- |
| A merchant unpublishes an offer from your channel               | `OFFER_UPDATED` and `OFFER_REMOVED`                                   |
| A merchant publishes it again                                   | `OFFER_UPDATED` and `OFFER_ADDED`                                     |
| A merchant disconnects from your app                            | `MERCHANT_DISCONNECTED`, and `OFFER_REMOVED` for each published offer |
| An offer is marked for deletion                                 | `OFFER_UPDATED` and `OFFER_REMOVED` (published offers only)           |
| Violet permanently deletes a published offer                    | `OFFER_DELETED`                                                       |
| Violet permanently deletes an offer that is no longer published | None                                                                  |

The last row is why `OFFER_DELETED` should not be your only cleanup signal. If an offer was unpublished before Violet deleted it, you already received `OFFER_REMOVED` and you will not receive `OFFER_DELETED`. Treat `OFFER_REMOVED` as the moment you stop showing an offer, and `OFFER_DELETED` as a cleanup signal for records you chose to keep.

## Handling offer events

| Event           | Recommended handling                                                                                           |
| --------------- | -------------------------------------------------------------------------------------------------------------- |
| `OFFER_ADDED`   | Fetch the current offer, then add it to your catalog and search index, or restore it if you removed it earlier |
| `OFFER_UPDATED` | Fetch the current offer and update your copy: price, inventory, and availability                               |
| `OFFER_REMOVED` | Hide the offer from your catalog and search. Keep the record                                                   |
| `OFFER_DELETED` | Delete your record of the offer                                                                                |

Best practices:

1. **Use `OFFER_ADDED`, not `OFFER_CREATED`.** `OFFER_CREATED` is deprecated.
2. **Treat removal as reversible.** Hide the offer on `OFFER_REMOVED` and delete your data only on `OFFER_DELETED`. A removed offer can be republished, or a merchant can reconnect, and you receive `OFFER_ADDED` again.
3. **Make handlers idempotent.** Use `X-Violet-Event-Id` to ignore events you have already processed.
4. **Expect bursts.** A merchant disconnecting or unpublishing many products sends one `OFFER_REMOVED` per offer. Acknowledge each webhook quickly and do the work in a queue.
5. **Don't write from the payload alone.** Failed deliveries are retried for up to 24 hours (see [Failing Webhooks](https://docs.violet.io/prism/webhooks/handling-webhooks.md#failing-webhooks)), so an older `OFFER_ADDED` or `OFFER_UPDATED` can arrive after a newer event. Fetch the current offer and write that. Debounce `OFFER_UPDATED` so a burst of updates costs one fetch.
6. **Verify before you display.** On `OFFER_ADDED`, check the offer's availability and inventory before showing it to shoppers.
7. **Sync incrementally.** Use offer webhooks for incremental catalog updates instead of full catalog refreshes.

## Event sequences

Offer events often arrive alongside [sync](https://docs.violet.io/prism/webhooks/events/sync-webhooks.md) and [merchant](https://docs.violet.io/prism/webhooks/events/merchant-webhooks.md) events.

| Scenario               | Events, in order                                                                                                                                                                            |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Merchant onboarding    | `MERCHANT_CONNECTED`, `PRODUCT_SYNC_STARTED`, `OFFER_ADDED` for each product, `PRODUCT_SYNC_COMPLETED`                                                                                      |
| Scheduled product sync | `PRODUCT_SYNC_STARTED`, then `OFFER_UPDATED` for changed products, `OFFER_ADDED` for new products, and `OFFER_REMOVED` for offers no longer available to you, then `PRODUCT_SYNC_COMPLETED` |
| Merchant disabled      | `MERCHANT_DISABLED`, then `OFFER_UPDATED` for each of the merchant's offers, which move to `DISABLED_AVAILABLE` or `DISABLED_UNAVAILABLE`                                                   |
| Merchant re-enabled    | `MERCHANT_ENABLED`, `PRODUCT_SYNC_STARTED`, `OFFER_UPDATED` for each offer as it returns to `AVAILABLE`, `PRODUCT_SYNC_COMPLETED`                                                           |
| Merchant disconnected  | `MERCHANT_DISCONNECTED` and `OFFER_REMOVED` for each published offer                                                                                                                        |
| Single product change  | `OFFER_UPDATED` only. No sync events fire between scheduled syncs                                                                                                                           |

Use the sync events to tell catalog-wide operations apart from individual product changes.

## Webhook headers

Offer webhooks include the [default webhook headers](https://docs.violet.io/prism/webhooks/managing-webhook-headers.md). The ones you will use most:

| Header               | Value                                               |
| -------------------- | --------------------------------------------------- |
| `X-Violet-Entity-Id` | The Violet offer ID                                 |
| `X-Violet-Topic`     | The event, such as `OFFER_ADDED` or `OFFER_UPDATED` |
| `X-Violet-Event-Id`  | A unique ID for the event, for idempotency          |

## Related documentation

* [Offers](https://docs.violet.io/prism/catalog/offers.md): the Offer data model and its statuses
* [Catalog](https://docs.violet.io/prism/catalog.md): how Violet's catalog works
* [Handling Webhooks](https://docs.violet.io/prism/webhooks/handling-webhooks.md): process webhook events reliably
* [Simulating Webhook Events](https://docs.violet.io/prism/webhooks/simulating-webhook-events.md): test your offer handlers
* [Publication-Scoped Catalog Sync](https://docs.violet.io/ecom-platforms/shopify/sales-channel/catalog-sync.md): publish and unpublish behavior for Shopify sales channels


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.violet.io/prism/webhooks/events/offer-webhooks.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
