Newsletter
Retrieve Offers
  • Home
  • Retrieve Offers

Introduction

offer.jpg

Last update :

Toolbox / Tips

The Offers Catalog Retrieval API (GET /offers) allows sellers to access their offer data across Octopia sales channels. It returns consolidated offer information including price, condition, availability, and performance metrics. It supports both baseline offer data and advanced sales channel feedback (via the expand parameter), such as visibility status, Buy Box eligibility, and competing offers.

This endpoint is essential for sellers who need to:

  • Monitor and synchronize their live offer catalog

  • Verify visibility and integration on sales channels

  • Adjust pricing and delivery strategies based on real-time competition

It is the primary read-only interface for accessing seller-side catalog state — complementing the Offer Submission API, which handles offer creation, updates and delete.

Key States & Attributes

Field

Description

Business Logic

Parameter for filter

sellerId

ID of the seller

ID to recognise the seller

Mandatory

salesChannelId

Target sales channel

Required in every request

Mandatory

offerId

Composite identifier: sellerId_product_condition_channel

Used to uniquely identify the offer on Octopia system

offerIds filter available for one or several offers

sellerExternalReference

Seller-side unique ID

Used for uniquely identify the offer with the seller unique ID

sellerExternalReferences filter available for one or several offers

gtin

Product GTIN or EAN

Commun ID of the product

gtins filter available to retrieve the offers on this GTIN

productReference

Product ID generated on Octopia

ID of the product used in Octopia system

condition

Offer condition (New, Refurbished, Used…)

Used to identify an offer on a specific condition

offerState

Offer status: Active or Inactive

Indicates whether the offer is enabled for publication

offerStates filter available to retrieve all offers in this state

integrationPrice

Price integrated by seller (including taxes)

Used to track official submitted price

facialPrice

Price displayed on the sales channel

May differ from integration price if rounded, converted, or adjusted

deliveryOffers

Delivery options per supply mode

Includes preparation time, costs, and delivery estimates

comments, offerCompetition

Cdiscount-specific attributes

Not available on other channels

salesChannelAcceptanceStatus

Status on non-Cdiscount channels

Indicates whether the offer was accepted or rejected by the channel

Sales Channel Feedback

When using expand=salesChannelFeedback, the following additional insights are available:

Field

Description

isOnline

Whether the offer is actually visible on the sales channel

bestOfferDetails

Buy Box status, price, delivery, update timestamp

offerQuality

Qualiscore rating and reasons (A–E)

productInformation

Review counts, product page info

sellerGrade

Seller rating and review counts

competingOffers

List of competitive offers with full details

Seller Workflow

Below is the typical sequence when using this endpoint to audit or monitor offers:

offers-retrieval.png

Data Availability Period

  • Data is fetched from both internal referentials and the sales channel APIs.

  • Sales channel feedback (expand) fields may be updated with some delay. Each node in salesChannelFeedback includes an updatedAt timestamp to reflect its freshness.

  • Offers are paginated with a maximum limit of 1000 items per page.

 Retrieve Offers

Prerequisites

  • API key and sellerId header are required.

  • You must provide the salesChannelId query parameter.

  • Pagination is enabled with limit (max 1000 per page).

This endpoint retrieves the seller’s offers from the Octopia offer catalog for a given sales channel. It returns product, price, stock, condition, and other key offer attributes.

The endpoint is filterable and supports smart field selection (fields) and expanded information (expand) for advanced insights. It is the primary tool for viewing your live or inactive offers across marketplaces.

Functional Rules

  • If both fields and expand are provided, expand is ignored.

  • Default fields always returned:

    • offerId, sellerExternalReference, offerState, createdAt, updatedAt

  • Optional filters include:

    • offerIds, gtins, offerStates, sellerExternalReferences, updatedAtMin

  • Optional selectors:

    • fields – fetch only specified fields (e.g. condition, facialPrice.price)

    • expand – (Cdiscount only) adds salesChannelFeedback with extra visibility, ranking and competition data

Endpoint to use

Important notes

  • Use fields to reduce payload size for large catalogs.

  • Use expand=salesChannelFeedback to retrieve real-time visibility status, buy box position, ratings, and performance metrics (Cdiscount only).

  • Use updatedAtMin to sync only recent changes from your catalog.

Retrieve visibility & Sales Channel Feedback

Prerequisites

  • salesChannelId=CDISFR is required (only supported for Cdiscount).

  • Add expand=salesChannelFeedback to the query.

  • Use sellerExternalReferences, offerIds, or limit to filter the offers.

This use case allows sellers to check whether their offers are effectively published, whether they hold the buy box, and how their quality score (Qualiscore) is assessed by the marketplace.

The salesChannelFeedback node returned by the expand parameter includes detailed visibility, quality, loyalty, and promotional data, such as:

  • Whether the offer is online

  • Displayed price and delivery cost

  • Offer ranking (buy box) and reasons if offline

  • Product page stats (URL, reviews, rating)

  • Seller rating on the channel

  • Qualiscore (A–E) and detailed reasons (e.g., delivery time too long)

Functional Rules

  • Works only for salesChannelId=CDISFR.

  • Several timestamps (updatedAt) are included to indicate freshness of each feedback sub-section.

  • If the sales channel does not return specific data → field will be null.

Endpoint to use

Example:

GET /offers?salesChannelId=CDISFR&expand=salesChannelFeedback

Important notes

  • This feature is only available on Cdiscount for now. Support for other channels is planned.

  • Fields in salesChannelFeedback are asynchronous and may be delayed by a few hours.

  • Buy box data is provided in salesChannelFeedback.bestOfferDetails, not in the top-level isBestOffer.

Retrieve Competing Offers

Prerequisites

  • salesChannelId=CDISFR required (only Cdiscount supports competing offer insights).

  • expand=salesChannelFeedback must be added.

  • Filter with sellerExternalReferences, offerIds, or GTINs to target specific offers.

This use case retrieves competing offer data for a given offer — including price, seller rating, and promotional information of other offers on the same product.

This allows the seller to:

  • Monitor pricing pressure

  • Identify Buy Box winners

  • Adjust their own strategy (price or delivery)

Functional Rules

  • The salesChannelFeedback.competingOffers array is only returned when:

    • The expand=salesChannelFeedback is used

    • The sales channel provides such data (currently only Cdiscount)

  • Each competing offer includes:

    • Seller name, price, delivery cost, ratings

    • Loyalty & promotional flags

    • Whether it’s the Buy Box winner

Endpoint to use

Example to competing data only:

GET /offers?salesChannelId=CDISFR&fields=salesChannelFeedback.competingOffers

Important notes

  • If multiple offers match the same product, they will all be returned.

  • Best offer data is separate from your own offer status, and always refers to the channel’s current top performer.

  • You can use this insight to adjust offerCompetition parameters dynamically.

FAQ

 How do I retrieve all my current offers for a given sales channel?

Use GET /offers?salesChannelId=XXXX. Add limit=1000 to retrieve the maximum allowed per page.

 What is the default response if I don’t use any filters?

You’ll receive the first 100 offers (default pagination) with basic fields:
offerId, sellerExternalReference, offerState, createdAt, updatedAt.

 How can I reduce the response payload to only the fields I need?

Use the fields query param. Example:
fields=condition,product,salesChannelFeedback.bestOfferDetails

 What fields are always included, even if I use fields=?

These are always returned:

  • offerId

  • sellerExternalReference

  • offerState

  • createdAt

  • updatedAt

 What’s the difference between integrationPrice and facialPrice?
  • integrationPrice = What you sent in your offer payload (your source of truth)

  • facialPrice = What’s actually shown to customers (can include rounding, FX conversion, channel-specific rules)

 What’s the purpose of the expand=salesChannelFeedback parameter?

It returns detailed channel feedback from Cdiscount:

  • Is the offer online?

  • Is it the Buy Box winner?

  • What’s its offerQuality score?

  • Who are the competing offers?

Only supported for Cdiscount (salesChannelId=CDISFR).

 Can I get Buy Box and competing offer info for other channels?

Not yet. Today, salesChannelFeedback is Cdiscount only, but it’s planned to expand to other channels.

 What happens if I send both fields and expand?

expand will be ignored. You must choose one.

 How fresh is the data in salesChannelFeedback?

Each sub-node (e.g., bestOfferDetails, productInformation, offerQuality) includes an updatedAt field. This indicates when the feedback was last refreshed.

 Can I use this endpoint to check stock or delivery settings?

Yes. Use:

  • deliveryOffers.quantity

  • deliveryOffers.preparationTime

  • deliveryOffers.deliveryModes

 How do I paginate if I have more than 1,000 offers?

Use the Link header to fetch the next page (rel="next"). Cursor-based pagination is used — extract the cursor value from the Link.

 How do I know why my offer is not visible on the sales channel?

Use expand=salesChannelFeedback and check:

  • salesChannelFeedback.isOnline

  • salesChannelFeedback.offlineReason.reason