Newsletter
Offer integration (JSON)
  • Home
  • Offer integration (JSON)

Introduction

offer.jpg

Last update :

NOW AVAILABLE for Cdiscount

Toolbox / Tips

The Offer integration API enables sellers to batch manage their offer catalog on Octopia by creating and processing offer packages. These packages allow sellers to perform bulk create and update full offer (Upsert), update partially the offers (Update), or delete (Delete) operations for offers on a specific sales channel.

This API is critical in the broader offer lifecycle for synchronizing seller catalogs across multiple marketplaces, controlling offer visibility, adjusting stock and prices, and removing outdated listings.

A package-centric flow ensures operational safety: sellers can prepare and review packages before submitting them for integration. After submission, packages are processed, and sellers can retrieve integration results (successes, rejections, duplications) during 3 days.

Key States & Attributes

Field

Description

Business Rules

packageType

Defines the operation type: Upsert, Update, or Delete

A package can only have one type. Each type has specific field requirements.

packageState

Workflow status: WaitingForCompletion, Ready, IntegrationPending, Integrated, Rejected

Only WaitingForCompletion allows uploading offer requests. Once set to Ready, no further uploads are allowed. IntegrationPending, Integrated, Rejected are the results of package integration.

sellerExternalReference

Seller-defined unique identifier for the offer (per product, condition, channel)

Required in all package types. Used as the anchor for updates/deletes.

product.gtin / product.reference

Product identifier (GTIN / EAN) and internal reference

Required in Upsert. Cannot be modified in Update.

price / taxes

Price of the offer and applicable taxes

Required in Upsert. If updated, full tax list must be provided.

quantity

Inventory count

Required in Upsert. Shared across channels if the product and condition match.

deliveryModes & preparationTime

Delivery options and preparation time before shipping

Full delivery list must be sent in Update. If modifying deliveryModes, preparationTime becomes mandatory.

resultCode & integrationStatus

Outcome of each offer request (e.g., created, rejected, duplicated)

Retrieved via results endpoint after integration.

Seller Workflow

image-20250917-145558.png

Data Availability Period

  • Results are available after the package is submitted and for 3 days after being fully processed.

  • Only basic syntax validation is done during upload. Business validation (e.g., reference existence, field logic) happens during integration.

  • Large packages (max 50000 offers) may take longer to process; result availability depends on package size.

Create a Package

Prerequisites

  • Mandatory headers:

    • sellerId — ID of the seller

    • salesChannelId — Target sales channel

  • Optional header:

    • Accept-Language — en-US (default), fr-FR, es-ES

This endpoint creates a new offer package that will group offer requests of a specific type (Upsert, Update, or Delete).

The created package will be in WaitingForCompletion state, allowing uploads of offer requests.

Each package is limited to:

  • A single sales channel

  • A single package type

Creating a package is the first step in preparing batch requests to your offer catalog.

  • You must specify a valid packageType:

    • Upsert – create or update an existing offer

    • Update – partial update of an existing offer

    • Delete – remove an existing offer

  • The returned Content-Location header contains the packageId.

  • You cannot reuse or modify a package’s packageType after creation.

  • The Accept-Language will define the offer requests results message localization when your package will be treated. You can choose from French (fr-FR), English (en-US) and Spanish (es-ES).

Endpoint to use

Request body:

{
  "packageType": "Upsert"
}

Important notes

  • Package ID is returned via Content-Location header, not in the response body.

  • All uploads must match the declared package type.

  • You can create multiple packages concurrently, as long as each respects the channel and type constraints.

  • Packages are available during 6 hours if not completed (status ‘Ready’)

Retrieve existing Packages by Filter

This endpoint lists all previously created offer packages. You can filter them by processing state (e.g., WaitingForCompletion, Integrated) and by salesChannelId.

This is especially useful for monitoring progress or reusing packages that are still editable.

Functional Rules

  • Supports filtering by:

    • state – current status of the package

    • salesChannelId – to target a specific channel

  • Pagination supported via limit query param.

  • Use Cursor for cursor-based pagination.

  • Response includes package metadata and status, plus optional result messages.

Endpoint to use

Important notes

  • Only packages in WaitingForCompletion can be modified.

  • Integrated or Rejected packages are immutable, but can be audited via results.

  • Each response includes up to limit results and may include Link headers for pagination.

Retrieve a Package by ID

Prerequisites

  • Path parameter: packageId

This endpoint retrieves all information about a specific package by its ID, including its state, submission date, type, and (if applicable) processing results.

Useful to determine if a package is still modifiable, or to confirm it has been processed.

Functional Rules

  • Use this to verify if your package can still receive uploads or the results if it has been submitted.

  • State transitions are:

    • WaitingForCompletion → available for uploads

    • IntegrationPending, Integrated or Rejected → when completed

Endpoint to use

Aucun endpoint trouvé avec l'operationId « get-offer-package-packageId ».

Important notes

  • This call is necessary before uploading offers, to ensure the package is in the correct state.

  • If status is Integrated, check results via the /offer-requests-results endpoint.

  • If status is Rejected, a result message will explain the reason.

Upload Offer Requests in a Package

Prerequisites

  • Path: packageId (must be in WaitingForCompletion)

This endpoint lets sellers upload one or more offer requests to the specified package.

These can be created in batches and uploaded multiple times until submission.

Only JSON validation occurs at this stage. Full business validation happens upon submission.

Functional Rules

  • Maximum 100 offer requests per upload

  • Up to 50,000 requests per package

  • Uploads only allowed in WaitingForCompletion state

  • Rules depend on package type:

Upsert

  • All required fields must be provided

  • Creates or updates existing offer if same reference/GTIN/condition exists

  • Multiple conflicting entries with the same reference will be rejected

Update

  • Only updated fields should be included

  • At least one field must be changed

  • deliveryModes must be a full array

  • Multiple conflicting entries with the same reference will be rejected

Delete

  • Only sellerExternalReference required

  • If no match is found → rejected

Endpoint to use

Example Upsert payload:

{
  "product": {
    "gtin": "1234567890000",
    "reference": "AUC1234567890000"
  },
  "condition": "New",
  "sellerExternalReference": "SellerRef001",
  "price": {
    "originPrice": 59.99,
    "price": 49.99,
    "taxes": [
      {"code": "VAT", "value": 0.2}
    ]
  },
  "deliveryModes": [
    {"code": "THD", "cost": 1.99, "additionalCost": 2.99}
  ],
  "preparationTime": 4,
  "quantity": 100
}

Important notes

  • No field-level validation happens yet — only JSON structure is checked.

  • Conflicting duplicate entries are rejected entirely for Upsert and Update.

  • GTIN, condition, and reference fields cannot be updated.

Mark a Package as Ready

Prerequisites

  • Path: packageId

  • Body must set "state": "Ready"

This endpoint submits a package for integration by changing its state to Ready.

No further uploads are possible once submitted.

The package will then be processed asynchronously.

Functional Rules

  • Only applicable to packages in WaitingForCompletion

  • Once marked as Ready:

    • Status will automatically evolve to IntegrationPending

    • Eventually changes to Integrated or Rejected

Endpoint to use

Exemple of Request:

{
  "state": "Ready"
}

Important notes

  • After calling this endpoint, no more uploads are allowed.

  • Use GET /offer-packages/{packageId} to track progress.

  • Integration time depends on volume and system load.

Retrieve Offer Request Results

Prerequisites

  • Path: packageId

  • Optional query: limit (pagination)

Use this endpoint to retrieve integration outcomes for each uploaded offer request.

Each request will have an integrationStatus: Integrated, Rejected, or Duplicated.

Each request will have an resultCode to verify the integration or rejection of the offer. If rejection, an error messageis available.

This is the final step in the offer workflow.

Functional Rules

  • Results are only available after package is processed.

  • Each result includes:

    • sellerExternalReference

    • integrationStatus

    • A list of messages and result codes

Endpoint to use

Important notes

  • Duplicated means multiple conflicting entries were uploaded → all rejected

  • Use resultCode and message to understand validation errors

  • Paginated with Link headers if too many results

FAQ

 What is the difference between Upsert, Update, and Delete packages?

  • Upsert: Create new offers or fully replace existing ones. Requires all mandatory fields.

  • Update: Modify specific fields of an existing offer (e.g. price, stock, delivery). Requires sellerExternalReference and only changed fields.

  • Delete: Remove an offer from a sales channel. Only sellerExternalReference is required.

 What is sellerExternalReference and why is it mandatory?

It’s the seller-side unique ID for an offer (product + condition + sales channel). It:

  • Uniquely identifies the offer.

  • Is used for all operations (upsert, update, delete).

  • Must be consistent across all submissions and systems.

 How are prices handled?

  • Prices are submitted as price (current sale price) and optionally originPrice (strikethrough).

  • All prices must be gross, i.e., include VAT.

  • VAT and other taxes (EcoPart, DEA) must be listed in the taxes array, even if zero.

 Can I update just the price or stock without resending the full offer?

Yes — with Update packages, you can submit only:

{
  "sellerExternalReference": "MyRef001",
  "price": {
    "price": 19.99
  }
}

Or:

{
  "sellerExternalReference": "MyRef001",
  "quantity": 10
}
 What happens if I send multiple offers with the same sellerExternalReference in one package?

  • They are treated as duplicates.

  • All duplicates will be rejected.

  • You must ensure each sellerExternalReference is present only once per package.

 Can I update delivery information only?

Yes, but you must provide the entire list of delivery modes for that offer.

  • You cannot partially update one delivery mode.

  • Always submit all modes and costs you want to keep.

 Can I send offers for multiple sales channels in one package?

No. Each package must:

  • Target a single sales channel (salesChannelId in header).

  • Contain offers of the same packageType.

 How does stock quantity work across channels?

Stock is shared across offers with the same product (GTIN + condition) on different channels.

  • Updating stock in one offer updates it for all channels.

  • To unpublish on a specific channel, use the Delete package.

 How are errors handled in offer submissions?

  • Validation is done in two phases:

    • Upload: Only JSON structure is checked.

    • Submit (PATCH): Business validation (price limits, product link, required fields, etc.)

  • Errors are returned via:

    • GET /offer-packages/{packageId}/offer-requests-results

    • With details: integrationStatus and resultCode + message

 What is the maximum number of offers per package?

  • Per upload: 100 offer requests

  • Per package total: 50,000 offers

 When and how do I submit a package for processing?

Once all offers are uploaded:

PATCH /offer-packages/{packageId}
{
  "state": "Ready"
}

After that, no more uploads are allowed. The package is sent for integration.

 What are the possible states of an offer package?

  • WaitingForCompletion: Open to upload

  • Ready: Submitted, waiting for processing

  • IntegrationPending: Currently being treated

  • Integrated: Successfully processed

  • Rejected: Rejected due to errors

 Can I retrieve the results of my offer submissions?

  • Yes — use:

    GET /offer-packages/{packageId}/offer-requests-results

    You’ll see for each request:

    • sellerExternalReference

    • integrationStatus: Integrated, Rejected, Duplicated

    • results: message and resultCode