Offer integration (XML)

Newsletter

Introduction

Last update : 04 Feb 2026

Toolbox / Tips

Download the Postman collection
Download the YAML / See full technical documentation
Don’t forget to check the authentication documentation

The Offer Integration XML API allows sellers to submit offers in bulk via a downloadable ZIP package containing structured XML files (specifically offers.xml). This legacy mechanism is inherited from the former SOAP API ecosystem and is still available for compatibility and migration purposes.

This flow is particularly suited to:

Mass-updating stock and pricing offers
Using pre-validated XML structures
Supporting seller-side tools already generating XML ZIPs (e.g., for Cdiscount)

Workflow Summary

Product matching
First, sellers must ensure the products they want to submit offers for already exist. If not, product creation must occur prior to offer submission.
Prepare ZIP package
The package must follow a strict file and folder structure:
- Content/ folder containing the main file: offers.xml
- _rels/ and [Content_Types].xml (ZIP metadata) must be present
- There are two types of packages:
  - Full: containing complete information about the offer (Download an example of a “Full” package here)
  - Stock & Price: containing only stock and price information (Download an example of a “Stock & Price” package here)
- Check out the complete required fields list for offers packages
Write the offers.xml
This file contains all the offer data (product EAN, stock, price, VAT, delivery info…). Specific fields are required depending on the sales channel (Cdiscount or Octopia).
Host and submit
The final ZIP package must be made publicly available via a URL (e.g., S3, HTTP), and this URL is submitted via the API.
Track status
Once submitted, a packageId is returned. This can be used to query integration logs, track errors, and review which offers were successfully integrated.

Supported Package Types

Cdiscount
- Supports both “Full” and “Light” packages
- Sales channel ID is optional
- Supports optional commercial data (e.g., PriceMustBeAligned, sales pricing)
- PurgeAndReplace is allowed
Octopia
- Only “Full” packages are accepted
- SalesChannelId is mandatory
- PurgeAndReplace is ignored if included
- Must include PublicationPool SalesChannelId="XXX" (Download an example of a “Sales Channel” package here)

Required Fields in Offers

SellerProductId, ProductEan, ProductCondition, Price, VAT, Stock, Comment, DeliveryMode, PreparationTime, ShippingCharges, AdditionalShippingCharges
Check out the complete required fields list for offers packages

Seller Workflow

In this section we will look at how to manage the following cases and ensure maximum control of your orders:

Submit an Offer Package via XML ZIP
Add a Commercial Operation
Check the Status of a Submitted Package

Submit an Offer Package via XML ZIP

Prerequisites

Products must already exist in the system, identified by ProductEan.
Your XML package must follow the required structure and naming rules (see below).
The ZIP file must be publicly hosted (via HTTPS or similar).
If you are targeting Octopia channels, SalesChannelId is mandatory.

This endpoint allows sellers to submit a ZIP package containing structured offer data (offers.xml) to the API. The ZIP must follow a specific internal structure and must be accessible via a public link.

This is commonly used for:

Mass offer updates (price, stock, preparation time)
Initial offer creation across channels
Legacy system compatibility (migrating from SOAP flows)

Download sample package here:

ZIP Structure Required

Package_SalesChannels.zip
├── [Content_Types].xml
├── _rels/
│   └── .rels
└── Content/
    └── offers.xml

Good to know

Check out the complete required fields list for offers packages
Use the Octopia XML Package Tester to validate the correct structure of your package

Endpoint to use

Submits an zip package to update your offers (stock, prices, delivery costs...).

Example of zip package

Full package
Full package (With Sales Channel filter)
Stock & Price (Only for Cdiscount sale channel)

More information here

Parameters - Headers

Name In Type Description

Name	In	Type	Description
SellerId*	header	`string`	Octopia Seller Identifier. Example : 98979

SellerId*

header

string

Octopia Seller Identifier.

Example : 98979

Authorization

SellerId (header)

Content-Type

Request body

Url to the package zip file.

application/json

"foo://example.com/there"

Response codes

200 - Success

application/json

23144356

400 - Bad Request

application/problem+json

{
  "type": "https://tools.ietf.org/html/rfc7231",
  "title": "One or more validation errors occurred",
  "status": 400,
  "traceId": "dbb935dd-9884-4513-b22f-38e443632edb",
  "errors": {
    "MyField": [
      "The field is required"
    ]
  }
}

401 - Unauthorized

application/problem+json

{
  "type": "https://tools.ietf.org/html/rfc7235",
  "status": 401,
  "title": "Unauthorized",
  "instance": "/path-example",
  "traceId": "00-9055d0e39a4a5554866eee202737812f-8e3fb58dea31a710-00"
}

403 - Forbidden

application/problem+json

{
  "type": "https://tools.ietf.org/html/rfc7231",
  "status": 403,
  "title": "Forbidden",
  "instance": "/path-example",
  "traceId": "00-9055d0e39a4a5554866eee202737812f-8e3fb58dea31a710-00"
}

404 - Not Found

application/problem+json

{
  "type": "https://tools.ietf.org/html/rfc7231",
  "status": 404,
  "title": "Not Found",
  "instance": "/path-example",
  "traceId": "00-9055d0e39a4a5554866eee202737812f-8e3fb58dea31a710-00"
}

500 - Internal Server Error

application/problem+json

{
  "type": "https://tools.ietf.org/html/rfc7231",
  "status": 500,
  "instance": "/path-example",
  "title": "Internal Server Error",
  "traceId": "00-9055d0e39a4a5554866eee202737812f-8e3fb58dea31a710-00"
}

Request body example:

"https://mybox.cdiscount.com/index.php/s/3zXyvdw9Zha8q2r/download"

Important notes

If both Cdiscount and Octopia offers are in the same package, make sure each Offer block is correctly scoped with PublicationPool elements and SalesChannelId.
Octopia requires the presence of SalesChannelId — packages without it will be rejected.
If the ZIP is malformed, or files are missing, the API will return a 400 or reject silently. Always validate the structure.
Use a fresh URL per submission, especially if you overwrite files on a hosting service (e.g. S3).

Add a Commercial Operation

Prerequisites

Your product must already exist and be eligible for offer updates.
You must be targeting the official French sales periods (January–February or June–July).
The package must be a valid ZIP with the required XML structure and sales attributes.

This use case shows how to embed a sales price or comparison price into the offers.xml when uploading offers via ZIP.

There are two types of commercial display:

Sales (Soldes): Activated only during legal sale periods
Comparison Price (StrikedPrice): Shown as a permanent crossed-out price

Sales Activation (Discounted Offers)

To activate a sales price visible during official sale periods:

  SellerProductId="32427220" 
  ProductEan="00806056210006" 
  ProductCondition="6" 
  Type="3"
  DiscountUnit="1"
  SalesReferencePrice="110"
  DiscountValue="20"
  Price="19.95"
  EcoPart="0.10"
  DeaTax="3.14"
  Vat="19.6"
  Stock="10"
  PreparationTime="3"
  Comment="Offer with automatic sale discount"

Explanation of Sales Attributes

Type = 3: Activates commercial operation (sale)
DiscountUnit = 1: Percentage discount
SalesReferencePrice: Original price used to compute the discount
DiscountValue: Discount to apply, in %
Price: Current sale price (will be ignored during sale display — system recalculates using formula)

Calculation logic:

Displayed Sale Price = SalesReferencePrice × ((100 - DiscountValue) / 100)

The sale will be shown if the discount is at least 1%, or 1€ if the original price is under 100€
Example: SalesReferencePrice = 110 and DiscountValue = 20 → Sale price displayed: 88€

Comparison Price (Striked Price)

To display a crossed-out reference price outside official sales periods:

  SellerProductId="32427220" 
  ProductEan="00806056210006" 
  ProductCondition="6"
  Price="19.95"
  StrikedPrice="110"
  Vat="19.6"
  Stock="10"
  PreparationTime="3"
  Comment="Displayed as comparison price on site"/

Important Notes:

StrikedPrice is not validated by Cdiscount — it’s your declared recommended retail price.
Must be strictly higher than current Price.
It appears only outside sales periods, in contexts like:
- Flash Sales
- Commercial operations
- Product pages showing a crossed-out “reference price”

Check the Status of a Submitted Package

Prerequisites

A packageId must be known and already returned by a successful POST.
Package processing can take several minutes; you may need to poll the status.

This endpoint allows you to monitor the result of a submitted offer package. It returns:

Whether the package is still being processed or completed
Integration status for each offer (success, error, warnings)
Messages and logs that may help diagnose issues

This use case is essential to detect:

Offers that failed due to invalid product identifiers
Validation issues (e.g. bad VAT, negative stock)
Misuse of fields like PurgeAndReplace, DeliveryMode, or sales pricing rules

Endpoint to use

Retrieve offer package logs.

Example:

Retrieve a package with its package Id:

/offer-integration-packages/424325363619

Parameters - Headers

Name In Type Description

Name	In	Type	Description
SellerId*	header	`string`	Octopia Seller Identifier. Example : 98979

SellerId*

header

string

Octopia Seller Identifier.

Example : 98979

Parameters - Path

Name In Type Description

Name	In	Type	Description
packageId*	path	`integer`	Format - int64. Package identifier. Example : 424325363619

packageId*

path

integer

Format - int64. Package identifier.

Example : 424325363619

Parameters - Query

Name In Type Description

$limit

query

Name	In	Type	Description
$limit	query	`integer`	Format - int32. Must be written as follows $limit Example : 50
$page	query	`integer`	Format - int32. Must be written as follows $page Example : 1

integer

Format - int32. Must be written as follows $limit

Example : 50

$page

query

integer

Format - int32. Must be written as follows $page

Example : 1

Authorization

packageId (in path)

$limit (query)

$page (query)

SellerId (header)

Response codes

200 - Success

application/json

{
  "package_id": 0,
  "integration_state": "CreatedFromExcelFile",
  "number_of_errors": 0,
  "offer_log_paged_list": [
    {
      "log_date": "2022-06-14T10:00:59.0000000+00:00",
      "offer_integration_status": "string",
      "product_ean": "string",
      "seller_product_id": "string",
      "property_list": [
        {
          "log_message": "string",
          "property_code": "string",
          "property_error": "string"
        }
      ]
    }
  ],
  "seller_id": 0,
  "page": 0,
  "count_by_page": 0,
  "total_logs_count": 0
}

400 - Bad Request

application/problem+json

{
  "type": "https://tools.ietf.org/html/rfc7231",
  "title": "One or more validation errors occurred",
  "status": 400,
  "traceId": "dbb935dd-9884-4513-b22f-38e443632edb",
  "errors": {
    "MyField": [
      "The field is required"
    ]
  }
}

401 - Unauthorized

application/problem+json

{
  "type": "https://tools.ietf.org/html/rfc7235",
  "status": 401,
  "title": "Unauthorized",
  "instance": "/path-example",
  "traceId": "00-9055d0e39a4a5554866eee202737812f-8e3fb58dea31a710-00"
}

403 - Forbidden

application/problem+json

{
  "type": "https://tools.ietf.org/html/rfc7231",
  "status": 403,
  "title": "Forbidden",
  "instance": "/path-example",
  "traceId": "00-9055d0e39a4a5554866eee202737812f-8e3fb58dea31a710-00"
}

404 - Not Found

application/problem+json

{
  "type": "https://tools.ietf.org/html/rfc7231",
  "status": 404,
  "title": "Not Found",
  "instance": "/path-example",
  "traceId": "00-9055d0e39a4a5554866eee202737812f-8e3fb58dea31a710-00"
}

500 - Internal Server Error

application/problem+json

{
  "type": "https://tools.ietf.org/html/rfc7231",
  "status": 500,
  "instance": "/path-example",
  "title": "Internal Server Error",
  "traceId": "00-9055d0e39a4a5554866eee202737812f-8e3fb58dea31a710-00"
}

Important notes

Packages are processed asynchronously: wait a few seconds before the first poll, then check every 30–60 seconds.
The response contains both summary status and detailed per-offer results, making it suitable for full reconciliation.
If some offers failed, they must be corrected in your XML and re-submitted as a new package (you cannot patch inside a ZIP).

FAQ

What exactly should my ZIP file contain?

Your ZIP file must follow a strict structure:

/[Content_Types].xml
/_rels/.rels
/Content/offers.xml

You can download a working example here: Sample Package ZIP

Can I submit both Cdiscount and Octopia offers in the same package?

Yes — but you must specify the target SalesChannelId in each block inside the offers.xml. If you’re using Octopia, this is mandatory.

Do I need to upload the ZIP file directly?

No — you must host the ZIP file on a public HTTPS-accessible URL (e.g. Amazon S3, Azure Blob, CDN). The API accepts only a link.

How long does the processing take?

Usually a few seconds to a couple of minutes, depending on size and content. You’ll get a packageId in the response — use it to poll /offer-integration-packages/{packageId} to check status.

What happens if the file is accepted but some offers fail?

The file is parsed entirely, but each offer is validated independently. You’ll see detailed success/failure logs per offer when querying the report.

What are the most common reasons for offer failure?

The ProductEan does not match any known product
Required fields like Stock, VAT, or PreparationTime are missing
PriceMustBeAligned flag conflicts with business rules
The seller has no permission on the specified SalesChannelId
The GTIN is invalid (length or check digit)

What does PurgeAndReplace do?

For Cdiscount, it removes all previous offers before inserting the new ones in the package.

For Octopia: PurgeAndReplace is ignored — it has no effect.

Use with caution as it can erase all offers not present in the package.

Is there a schema or XSD for offers.xml?

No but you can use Octopia XML Package Tester instead

How many offers can I include in one file?

There is no official limit, but performance and timeout issues may arise above 10,000 offers per file. Prefer splitting into smaller batches if needed.

How do I know which SalesChannelId to use?

For Octopia: required — check with your account manager
For Cdiscount: optional — default channel will be used if omitted

Introduction

Workflow Summary

Seller Workflow

Submit an Offer Package via XML ZIP

Parameters - Headers

Request body

Response codes

200 - Success

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

Add a Commercial Operation

Check the Status of a Submitted Package

Parameters - Headers

Parameters - Path

Parameters - Query

Response codes

200 - Success

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

FAQ

Topics