Functional documentation

Offer feature V2

How to manage your catalog

Offer submission workflow

Offer submission with json

Step by step 

1/ Match the EAN codes

Use the Get product API to verify if the product exists in the product referential. 

If the product already exists, you can directly submit an offer on it. 

If the product does not exist, you will have to create it before submiting an offer on it. 

2/ Create a package 

With POST/offer-packages

This method allows to create an offer package to manage the offer catalog on a dedicated sales channel.

Once the offer package created, the seller will be able to upload offer requests in it that will create, update or delete offers from the catalog according to the package type.

Package types: 

You can use one of the following packages type to manage your offer catalog:

• Upsert: (case sensitive) allows to create new offers or replace an existing one with new information. Requires all the mandatory information of the offer.
• Update: (case sensitive) allows to update partially existing offers. Requires the seller external reference and one or several of the information (field) that you want to update.
• Delete: (case sensitive) allows Allows to delete existing offers. Requires only the seller external reference.

Accept-Language:

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).

Warning: 

• Each package can only target one sales channel.
• Each package can only have one type.

The package id is available into the “Content-Location” in the Headers. 

3/ Check the offer packages information

GET/offer-packages

GET/offer-packages/{packageId}

This method allows to get the existing packages informations and give filter them by status.

Filters:

By state:

• WaitingForCompletion: offer packages open to new offer requests uploads.
• Ready: offer packages ready to be treated.
• IntegrationPending: offer packages currently being treated
• Integrated: offer packages successfully treated
• Rejected: offer packages rejected

By Sales Channel Id:

• salesChannelId: filter all your packages created on the sales channel

By PackageId: 

• packageId: filter on one package with its id

What’s next: 

Your package is on Waiting for completion status? → You can upload your offer requests through the method:

Your package is on Integrated status? → You can check your offer requests results

Your package is on Rejected status? → You can check the reason on the result messages

4/ Upload offer requests in the package 

POST /offer-packages/{packageId}/offer-requests

This method allows to upload offer requests in an existing offer package before sending it to be treated.

You can upload offer requests as many times as you want until you consider your offer package complete.

According to your package types, here are the expected offer request:

• Upsert: Every offer request must contain all the mandatory information of an offer.
  • If no other offer on this sales channel share the same seller external reference, GTIN/EAN code and condition, your offer will be created.
  • Else, the existing offer information will be replaced with the offer request information.

[
  {
    "sellerExternalReference": "SellerRef001",
    "product": {
      "gtin": "1234567890987",
      "reference": "AUC1234567890987"
    },
    "condition": "New",
    "price": {
      "price": 49.99,
      "originPrice": 59.99,
      "taxes": [
        {
          "code": "VAT",
          "value": 0.2
        },
        {
          "code": "EcoTax",
          "value": 1
        },
        {
          "code": "DeaTax",
          "value": 2
        }
      ]
    },
    "deliveryModes": [
      {
        "code": "THD",
        "cost": 2.5,
        "additionalCost": 3.5
      },
      {
        "code": "EHD",
        "cost": 3.5,
        "additionalCost": 4.5
      }
    ],
    "preparationTime": 3,
    "quantity": 20
  }
]

• Update: Only the Seller External Reference and the updated information should be added.
  • If no other offer on this sales channel share the same seller external reference, your offer requests will be rejected. You will have to create the offer thanks to the upsert package type to be able to update then
  • Else, the existing offer will be updated with the information submitted. The offer information submitted can concern at least one information otherwise the offer request will be rejected. You can update one or several information of your offer. For example, you update only the price for one offer and for another offer the price AND the quantity. Every kind of offer information can be updated. The remaining information will stay the same.
  • WARNING:
    – if you wish to update information expressed as array in the offer request, please include the full list of attributes as it will replace the existing arrays
    – if you upload several times the same seller external reference with different offer information in each, the offer request will be rejected for all information because we do not manage duplicated offer information
    – if one or several fields of offer are not correct, the fieds will be ignored. And if none of them are correct, the offer request will be rejected
    – if you update the deliveryModes, the preparetionTime field and value are mandatory in the offer request.
    – The information about the product (Gtin, reference, condition) can not be updated
  • EXAMPLES:
    The examples of offer requests update bellow are just samples of what is possible to update. All the combinaison are possible. Only the recognised field will be updated.

• Delete: Only the offer Seller external reference should be included
  • If no other offer on this sales channel share the same seller external reference, your request offer will be rejected.
  • Else, the existing offer will be deleted from this sales channel offer catalog, and then unpublished from this sales channel..

[
  {
    "sellerExternalReference": "SellerRef001"
  },
  {
    "sellerExternalReference": "SellerRef002"
  }
]

What about your quantity (stock)?

Your stock quantities are mutualised with each sales channel in which you have a corresponding offer for this product and condition. Updating your stock will update it on each of these sales channels.

You can remove an offer from a specific sales channel by deleting it rather than updating its stock quantity to 0.

Warning: 

• Each upload of offer request into the package must not exceed 100 offer requests
• One offer package can only gather a maximum of 50 000 offer requests
• You can only upload offers in packages which status is Waiting for completion
• Only a json surface check is made at this stage. The real offer request control is made when you submit the package

5/ Submit your package

GET /offer-packages/{packageId}

This method allows you to indicate that the offer request upload is complete and the the package can be treated. The Patch method with the packageId and the status “Ready” (case sensitive) is sending the package to the offer integration system.

Warning: 

• You can only update packages that have the status “Waiting for completion”
• Once you declare your package “Ready”, you will no longer be able to upload offer requests. You will need to create another package.

The package is being processed. During the treatment, the statuses of your package will evolve from Ready to IntegrationPending. The lenght of this status can be different depending on the size of the package.

Once treated, the status of the package will be Integrated or Rejected.

6/ Get the offer requests submission results

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

This methods allows you to get the integration results of your offer requests to check if they have been integrated or rejected by the system.

Integration statuses:

• Integrated: your offer request has been created, updated or deleted
• Rejected: your offer request has been rejected, check the results message for more information
• Duplicated: the sellerExternalReference has been find twice or more in the package. We do not treat those offer requests. It means that the information of your offer request is rejected.

How the pagination work ? 

You can use the link header from the response to request additional pages of data. The link header contains URLs that you can use to fetch additional pages of results. 

The link header provides the URL for the previous, next, first, and last page of results:

• The URL for the previous page is followed by rel="prev".
• The URL for the next page is followed by rel="next".

7/ The specificities of some attributes

Mandatory attributes for Upsert offer requests on Octopia : 

Xml (old)	Json
PurgeAndReplace	Replaced by package type : Upsert ; Update ; Delete	N/A
sellerProductId	“sellerExternalReference”:	Mandatory
ProductEan	“product”: { “gtin”: “1234567890987” },	Mandatory
ProductCondition	“condition”:	Mandatory
Price	“price”: {       “price”: 49.99,       “taxes”: [                                  {                     “code”: “VAT”,                     “value”: 0.2                 },                 {                     “code”: “EcoTax”,                     “value”: 1.0                 },                 {                     “code”: “DeaTax”,                     “value”: 2.0                 }       ]     },	Mandatory
Vat
EcoPart
DeaTax
StrikedPrice	“originPrice”:	Optional
Stock	“quantity”:	Mandatory
PreparationTime	“preparationTime”:	Mandatory
DeliveryMode	“deliveryModes”: [       {         “code”: “THD”,         “cost”: 2.5,         “additionalCost”: 3.5       }]	Mandatory Mandatory Mandatory Optionnal
ShippingCharges
AdditionalShippingCharges
Comment	–	Not available on Octopia
PriceMustBeAligned
MinimumPriceForPriceAlignment
IsCDAV