Offers

What is an Offer?

An Offer represents a merchant's specific listing of a product in Violet's catalog. It contains the merchant's pricing, availability, descriptions, media, and purchasable variations (SKUs). When browsing products from a merchant, you're viewing their Offers.

Data Model Hierarchy

Merchant
   └── Offer (merchant's product listing)
         └── SKU (specific purchasable variant)

• Merchant: The seller providing products

• Offer: A merchant's listing with their pricing, descriptions, and media

• SKU: Individual purchasable variants within the Offer (e.g., size/color combinations)

A single Merchant can have many Offers, and each Offer can contain multiple SKUs.

Key Offer Properties

Property	Type	Description
id	integer	Violet's unique Offer identifier
external_id	string	The merchant's own product identifier
merchant_id	integer	The merchant selling this Offer
name	string	Product name
description	string	Plain text description
html_description	string	HTML-formatted description
min_price	integer	Lowest SKU price in minor units (cents)
max_price	integer	Highest SKU price in minor units
currency	string	ISO 4217 currency code
available	boolean	Whether any SKUs are in stock
visible	boolean	Whether the Offer is visible to customers
source	enum	Origin platform (e.g., SHOPIFY, AMAZON, OTHER)
seller	string	Seller name
vendor	string	Product vendor/brand
external_url	string	Link to the product on the merchant's site

Offer Status

Offers have two independent status dimensions that control their lifecycle:

Status

The operational state of the Offer:

Status	Description
AVAILABLE	Active and operational
DISABLED	Temporarily disabled by merchant or system
ARCHIVED	Removed from active catalog
FOR_DELETION	Marked for permanent deletion

Publishing Status

Controls visibility to apps and webhook delivery:

Status	Description
PUBLISHED	Visible to subscribed apps, triggers webhooks
NOT_PUBLISHED	Hidden from apps, no webhook notifications

An Offer must be both available=true AND publishing_status=PUBLISHED to appear in app catalogs.

Variants and SKUs

Offers support product variants through two related concepts:

Variants

Define the available options for a product:

{
  "variants": [
    { "name": "Size", "values": ["Small", "Medium", "Large"] },
    { "name": "Color", "values": ["Red", "Blue", "Green"] }
  ]
}

SKUs

Represent specific purchasable combinations of variants, each with its own inventory and pricing:

{
  "skus": [
    {
      "id": 12345,
      "name": "T-Shirt - Small - Red",
      "sale_price": 2500,
      "in_stock": true,
      "variant_values": [
        { "name": "Size", "value": "Small" },
        { "name": "Color", "value": "Red" }
      ]
    }
  ]
}

Media and Albums

Offers include media organized into albums:

• Albums: Collections of images and videos for the Offer

• Primary Image: The main product image displayed in listings

• SKU-level Media: Individual SKUs can have their own images

Pricing

• Prices are stored in minor units (cents for USD)

• min_price and max_price represent the price range across all SKUs

• Individual SKU prices are available on each SKU object

• Currency conversion is available by passing your desired currency

Common Use Cases

Retrieving an Offer

Use GET /catalog/offers/{offer_id} to fetch complete Offer details including SKUs, variants, and media.

Listing Merchant Offers

Use GET /catalog/offers/merchants/{merchant_id} to retrieve paginated Offers from a specific merchant.

Searching Offers

Use POST /catalog/offers/search to search across Offers with filters for price, availability, category, and more.

Offer Search returns eventually consistent data and is not real-time consistent. Use Offer Search for discovery, then use non-search Offer endpoints for real-time Offer data.

Webhooks

When Offers change, webhooks notify subscribed apps:

Event	Trigger
OFFER_ADDED	Offer becomes published
OFFER_UPDATED	Published Offer is modified
OFFER_REMOVED	Offer is unpublished
OFFER_DELETED	Offer is permanently deleted

Webhooks only fire for Offers with publishing_status=PUBLISHED.

Relationship to Orders

When customers add items to a cart, they're adding specific SKUs from an Offer. The Offer provides the product context (name, description, media) while the SKU determines the exact variant, price, and inventory.

Changes to Offer availability or SKU inventory are automatically communicated to active carts and orders containing those items.

---

Available endpoints:

 GET /v1/catalog/offers/merchants/{merchant_id}
 GET /v1/catalog/offers/merchants/{merchant_id}/count
 GET /v1/catalog/offers/{offer_id}
POST /v1/catalog/offers/search