Get Offer by ID

Retrieve a specific Offer given its offer_id.

This endpoint supports collections and metadata. Use the include query param.

Get Offer by ID

get

Path parameters

offer_idinteger · int64Required

Query parameters

base_currencystringOptionalDefault: USD

exchange_ratenumber · doubleOptional

includestring · enumOptional

Comma-separated list of extra data to be included.

Possible values:

Header parameters

X-Violet-TokenstringRequired

X-Violet-App-SecretstringRequired

X-Violet-App-Idinteger · int32Required

X-Violet-Api-FeaturesstringOptional

Responses

200

successful operation

application/json

A merchant's product listing synced from an external commerce platform. An Offer is the top-level catalog entity and contains one or more SKUs (purchasable variations), Variants (product option dimensions like Size or Color), and Albums (grouped media/images). Hierarchy: Offer → SKU → VariantValues. Use the SKU ID when placing orders. All monetary values are in the smallest currency unit (e.g. cents for USD).

idinteger · int64Read-onlyRequired

Unique ID of the Offer.

product_idstringOptionalDeprecated

The parent/container product ID. Note: this is a legacy property and is now considered deprecated.

external_idstringRequired

The ID of the product in the merchants external store.

external_urlstring · nullableOptional

The URL to the product page in the merchants store. Note: if the value for visible is false this URL will likely result in a 404.

namestringRequired

Name of the offer as defined by the source merchant.

Example: Blue Running Sneakers

descriptionstring · max: 65000 · nullableOptional

Description of the offer. Note: this value may contain HTML elements.

sourcestring · enumRead-onlyRequired

Commerce platform the offer was sourced from.

Possible values:

sellerstring · nullableRead-onlyRequired

Name of the merchant selling product.

Example: Foot Locker

vendorstring · nullableRead-onlyOptional

Name of the source vendor or brand.

Example: Nike

merchant_idinteger · int32Required

ID of the merchant who sourced this Offer.

availablebooleanRead-onlyRequired

Is the product currently available for purchase in the merchants system.

visiblebooleanRead-onlyRequired

Is the product visible or hidden in the merchants storefront. Note: a product can be hidden while still being available for purchase.

min_priceinteger · int32Read-onlyRequired

Minimum price the Offer sells for in cents. This is the lowest of the SKU sale prices (e.g. 2999 = $29.99).

Example: 2999

max_priceinteger · int32Read-onlyRequired

Maximum price the Offer sells for in cents. This is the highest of the SKU sale prices (e.g. 5999 = $59.99).

Example: 5999

currencystring · min: 3 · max: 3Required

ISO 4217 currency code for the Offer. By default this value will be the merchants currency but can be changed by the API user using a base_currency parameter.

Example: USD

external_currencystring · min: 3 · max: 3 · nullableRead-onlyOptional

ISO 4217 currency code representing the merchants default currency in their external commerce platform.

Example: USD

source_category_namestring · nullableRead-onlyOptional

Original category name from the merchants external commerce platform.

typestring · enumRead-onlyRequired

Type of product. PHYSICAL products require shipping; DIGITAL products do not. Offers with a type of BUNDLED cannot be purchased through the API at this time due to ecom platform limitations.

Possible values:

statusstring · enumRead-onlyRequired

Current status of the Offer.

Possible values:

publishing_statusstring · enumRead-onlyRequired

Whether this Offer has been published to the Violet catalog and is discoverable via the Search API. An Offer can be NOT_PUBLISHED if the merchant has not yet completed onboarding or has chosen to hide it from the catalog.

Possible values:

date_createdstring · date-timeRead-onlyRequired

Date of offer creation in ISO 8601 format.

date_last_modifiedstring · date-timeRead-onlyRequired

Date of last offer update in ISO 8601 format.

date_last_consolidatedstring · date-time · nullableRead-onlyOptional

Date of last consolidation in ISO 8601 format. Consolidation is the process of querying the merchants store to see if this product still exists. This date is jittered for performance reasons and can be in the future.

three_d_enabledboolean · nullableOptional

Is the product 3D Enabled

Default: false

three_d_resourcestring · nullableOptional

3D Resource Object

commission_ratenumber · double · nullableRead-onlyOptional

The commission rate the merchant has agreed to share with the app on sales of this Offer, expressed as a decimal (e.g. 0.15 = 15%).

Example: 0.15

currency_symbolstring · nullableOptional

Symbol representing the desired currency

presented_currencystring · min: 3 · max: 3 · nullableRead-onlyOptional

ISO 4217 currency code representing the currency that prices are displayed in to the end user. May differ from currency if currency conversion is active.

Example: USD

default_image_urlstring · nullableOptional

The default image for this Offer. Only present on responses from the Search API. In other cases this value will be on the album's primary media object.

subscription_statusstring · enum · nullableRead-onlyOptional

Indicates whether the current app is subscribed to this Offer. Subscribed offers can be purchased through the API and will appear in the app's catalog.

Possible values:

external_dataobject · nullableOptional

The raw external product data from the external commerce platform. This data is not pre-processed by Violet and is only provided for reference when using using the Violet Relay API.

tagsstring[]Optional

403

insufficient permissions

application/json

404

offer not found

application/json

get

/catalog/offers/{offer_id}

HTTPcURLJavaScriptPython

GET /v1/catalog/offers/{offer_id} HTTP/1.1
Host: sandbox-api.violet.io
X-Violet-Token: text
X-Violet-App-Secret: text
X-Violet-App-Id: 1
Accept: */*

{
  "id": 1,
  "external_id": "text",
  "external_url": "text",
  "name": "Blue Running Sneakers",
  "description": "text",
  "source": "OTHER",
  "seller": "Foot Locker",
  "vendor": "Nike",
  "merchant_id": 1,
  "available": true,
  "visible": true,
  "min_price": 2999,
  "max_price": 5999,
  "currency": "USD",
  "external_currency": "USD",
  "source_category_name": "text",
  "metadata": [
    {
      "version": 1,
      "type": "STRING",
      "external_type": "text",
      "key": "text",
      "value": {},
      "external_id": "text",
      "source": "INTERNAL"
    }
  ],
  "variants": [
    {
      "id": 1,
      "external_id": "text",
      "name": "text",
      "visual": true,
      "values": [
        {
          "id": 1,
          "product_variant_value_id": "text",
          "external_id": "text",
          "name": "text",
          "sku_ids": [
            1
          ],
          "display_order": 1
        }
      ],
      "display_order": 1
    }
  ],
  "skus": [
    {
      "id": 1,
      "offer_id": 1,
      "merchant_id": 1,
      "external_id": "text",
      "name": "text",
      "asin": "text",
      "gtin": "text",
      "upc": "text",
      "ean": "text",
      "isbn": "text",
      "in_stock": true,
      "qty_available": 1,
      "inventory_tracked": true,
      "sale_price": 2999,
      "retail_price": 3999,
      "currency": "USD",
      "external_currency": "USD",
      "presented_currency": "USD",
      "taxable": true,
      "tax_type": "DEFAULT",
      "albums": [
        {
          "id": 1,
          "parent_id": 1,
          "type": "OFFER",
          "name": "text",
          "media": [
            {
              "id": 1,
              "album_id": 1,
              "external_id": "text",
              "cloud_id": "text",
              "url": "text",
              "source_url": "text",
              "type": "IMAGE",
              "display_order": 1,
              "alt_text": "text",
              "primary": true
            }
          ],
          "primary_media": {
            "id": 1,
            "album_id": 1,
            "external_id": "text",
            "cloud_id": "text",
            "url": "text",
            "source_url": "text",
            "type": "IMAGE",
            "display_order": 1,
            "alt_text": "text",
            "primary": true
          }
        }
      ],
      "variant_values": [
        {
          "variant": "text",
          "value": "text"
        }
      ],
      "type": "PHYSICAL",
      "status": "UNAVAILABLE",
      "date_created": "2026-06-09T20:56:29.739Z",
      "date_last_modified": "2026-06-09T20:56:29.739Z",
      "sku_dimensions": {
        "sku_id": 1,
        "weight": 1,
        "height": 1,
        "width": 1,
        "length": 1,
        "type": "SKU"
      },
      "shipping_dimensions": {
        "sku_id": 1,
        "weight": 1,
        "height": 1,
        "width": 1,
        "length": 1,
        "type": "SKU"
      },
      "trade_compliance": {
        "harmonized_system_code": "6109.10.00",
        "country_code_of_origin": "US",
        "province_code_of_origin": "CA"
      },
      "metadata": [
        {
          "version": 1,
          "type": "STRING",
          "external_type": "text",
          "key": "text",
          "value": {},
          "external_id": "text",
          "source": "INTERNAL"
        }
      ],
      "display_order": 1
    }
  ],
  "albums": [
    {
      "id": 1,
      "parent_id": 1,
      "type": "OFFER",
      "name": "text",
      "media": [
        {
          "id": 1,
          "album_id": 1,
          "external_id": "text",
          "cloud_id": "text",
          "url": "text",
          "source_url": "text",
          "type": "IMAGE",
          "display_order": 1,
          "alt_text": "text",
          "primary": true
        }
      ],
      "primary_media": {
        "id": 1,
        "album_id": 1,
        "external_id": "text",
        "cloud_id": "text",
        "url": "text",
        "source_url": "text",
        "type": "IMAGE",
        "display_order": 1,
        "alt_text": "text",
        "primary": true
      }
    }
  ],
  "type": "PHYSICAL",
  "status": "UNAVAILABLE",
  "publishing_status": "NOT_PUBLISHED",
  "date_created": "2026-06-09T20:56:29.739Z",
  "date_last_modified": "2026-06-09T20:56:29.739Z",
  "date_last_consolidated": "2026-06-09T20:56:29.739Z",
  "three_d_enabled": false,
  "three_d_resource": "text",
  "commission_rate": 0.15,
  "currency_symbol": "text",
  "presented_currency": "USD",
  "default_image_url": "text",
  "subscription_status": "NOT_SUBSCRIBED",
  "external_data": {},
  "collections": [
    {
      "id": 1,
      "external_id": "text",
      "merchant_id": 1,
      "parent_id": 1,
      "name": "text",
      "handle": "text",
      "description": "text",
      "status": "INACTIVE",
      "type": "CUSTOM",
      "media": {
        "source_url": "text",
        "alt": "text",
        "height": 1,
        "width": 1,
        "date_created": "2026-06-09T20:56:29.739Z"
      },
      "date_created": "2026-06-09T20:56:29.739Z",
      "date_last_modified": "2026-06-09T20:56:29.739Z"
    }
  ],
  "shipping": {
    "message": "text",
    "methods": [
      {
        "external_id": "text",
        "name": "text",
        "price": {
          "amount": 1,
          "currency": "USD"
        },
        "regions": {
          "countries": [
            "US"
          ]
        },
        "conditions": [
          {
            "price": {
              "amount": 1,
              "currency": "USD"
            },
            "weight": {
              "value": 1,
              "unit": "INCHES"
            },
            "type": "TOTAL_PRICE",
            "operator": "LESS_THAN_OR_EQUAL_TO"
          }
        ]
      }
    ]
  },
  "tags": [
    "text"
  ]
}