Add a video to your product sheets | Octopia API documentation

Newsletter

new-feature

Introduction

Sellers can now enrich their product sheets with a YouTube video via the Product Management API. The video is submitted alongside the other product data and is immediately visible on the product page once accepted.

What changed?

A new sellerVideoUrls field has been added to the product submission payload. It accepts a single YouTube video per product.

The video is then exposed on GET /products within a videos[] array, with the following fields:

index — the video slot (always 1 for now)
platform — the hosting platform (youtube)
videoId — the video identifier on YouTube
url — the full watch URL, rebuilt from platform and videoId
updatedAt — the date the video was last set on the product

Key rules to keep in mind:

Only YouTube videos are accepted — the video must exist and be publicly accessible
Only one video per product is supported (index must be 1)
The recommended maximum duration is 5 minutes (not enforced by the API)
Only the video identifier is kept from the submitted URL — extra query parameters (list, t, etc.) are dropped
A video can only be replaced by the product creator or the seller who originally set it; otherwise the submission is ignored and an Unauthorized warning is returned on SellerVideo_1
No removal endpoint exists: submitting an empty value does not delete an existing video
Video rejections are never blocking: a rejected video never prevents the product from being created or updated on its other fields

Example

Submitting a product with a video via POST /products-integration:

Use this API to integrate your products on Octopia

Functional Rules:

Octopia accepts products in English, French and Spanish. The values accepted for the language field are en-US, fr-FR, and es-ES.
Only products with fr-FR language will be available for Cdiscount
This process is asynchronous, check the integration results using the packageId provided in the API response and the API:
- GET /products-integration-reports
If you are creating a standard product:
- Use gtin attribute only
If you are creating a variant product:
- Use GTIN field to determine the public identifier of the product
- Use variantGroupReference field to determine the parent product linking a variant family
If you want to add an associated file on an authorized property, make sure that:
- The file doesn't exceed 1Mo
- The file respect the expected format (pdf/jpg/...etc). You can get this information by consulting the route properties/{reference}
- The file is provided via URL format
If you want to add a video on the product:
- sellerVideoUrls is optional: a payload without it stays valid, and an existing video is never removed
- a single video is accepted per product: index is required and must be 1; a video with a missing or different index is ignored, like a picture outside of its accepted indexes
- only YouTube is accepted
- the accepted url forms are watch?v=, youtu.be/, /shorts/ and /embed/
- the video should not exceed 5 minutes: this is a seller guideline, not checked by the integration
- only the video identifier is kept from the url: any other query parameter (list, t, ...) is dropped
- the url is transmitted as submitted by this API, and restituted as submitted in the integration report
- no removal is exposed: an empty value does not delete a video already set on the product
- the video can be replaced only by the product creator or by the seller who set it; otherwise the submitted video is ignored and an Unauthorized warning is returned on the field SellerVideo_{index} (same rule as sellerPictureUrls)

The number of items cannot be more than the following limit (min: 1 / max: 10 000)

Video rejections are never blocking :

a rejected video never prevents the product from being created or updated on its other fields
the reason is returned as a warning in the integration report (GET /products-integration-reports, warnings field), not in the 400 response of this route
a duplicated video index is reported with the code IncorrectValue on the field sellerVideoUrls_{index}, and the first occurrence is kept
an invalid url is reported with the code InvalidVideoUrl on the field SellerVideo_{index} (see the example of GET /products-integration-reports)

Endpoint full URL: https://api.octopia-io.net/seller/v2/products-integration

Parameters - Headers

Name In Type Description

Name	In	Type	Description
SellerId*	header	`string`	Octopia Seller Identifier. Example : 98979
Accept-Language*	header	`string`	The `Accept-Language` header allows you to precise which language to use for the request. Example : fr-FR

SellerId*

header

string

Octopia Seller Identifier.

Example : 98979

Accept-Language*

header

string

The Accept-Language header allows you to precise which language to use for the request.

Example : fr-FR

Authorization

SellerId (header)

Accept-Language (header)

Content-Type

Request body

{
    "products": [
        {
            "gtin": 1234567890128,
            "sellerProductReference": "AGRA39401",
            "title": "My title",
            "description": "My description",
            "richMarketingDescription": "My marketing description",
            "sellerPictureUrls": [
                {
                    "index": 1,
                    "url": "https://static.education.francetv.fr/media/img/hd/img.gif"
                }
            ],
            "sellerVideoUrls": [
                {
                    "index": 1,
                    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
                }
            ],
            "brand": "My brand",
            "categoryCode": "010201",
            "variantGroupReference": "Ref8210987654321",
            "attributes": [
                {
                    "files": [
                        "https://media.pdf"
                    ],
                    "propertyReference": "24077",
                    "values": [
                        "Electrique"
                    ]
                }
            ]
        }
    ]
}

Request body

The products to submit

application/json

{
  "products": [
    {
      "gtin": 1234567890128,
      "sellerProductReference": "AGRA39401",
      "title": "My title",
      "description": "My description",
      "richMarketingDescription": "My marketing description",
      "sellerPictureUrls": [
        {
          "index": 1,
          "url": "https://static.education.francetv.fr/media/img/hd/img.gif"
        }
      ],
      "sellerVideoUrls": [
        {
          "index": 1,
          "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
        }
      ],
      "brand": "My brand",
      "categoryCode": "010201",
      "variantGroupReference": "Ref8210987654321",
      "attributes": [
        {
          "files": [
            "https://media.pdf"
          ],
          "propertyReference": "24077",
          "values": [
            "Electrique"
          ]
        }
      ]
    }
  ]
}

Response codes

202 - Accepted

application/json

{
  "packageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

400 - Bad Request

application/problem+json

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

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"
}

406 - Not Acceptable

application/problem+json

{
  "statusCode": 406,
  "title": "NotAcceptable",
  "traceId": "00-6acce9a525266bc5a6ede8e335a616dc-0021a57d87e40fae-00",
  "type": "https://tools.ietf.org/html/rfc7231"
}

415 - Unsupported Media Type

application/problem+json

{
  "type": "https://tools.ietf.org/html/rfc7231",
  "status": 415,
  "title": "Unsupported Media Type",
  "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"
}

{
  "products": [
    {
      "gtin": 3499550358636,
      "sellerProductReference": "REF001",
      "title": "My product",
      "sellerVideoUrls": [
        {
          "index": 1,
          "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
        }
      ]
    }
  ]
}

Once accepted, the video is returned on GET /products:

This route allows you to get a list of products for a given seller.

The products displayed are the marketable products you created and the non-marketable products you modified.

If a product is marketable and you didn't created it, some fields will not be displayed.

For each product, it is indicated whether it is editable or enrichable (you can only modify data that you created or enrich new data).

You can filter with gtin, EN/ES or FR language (if none FR language by default) and categoryReference.

If you filter by gtin and the seller is not the creator, the following fields will be displayed:

reference
label
gtin
language
category
brand

When using the cursor/limit pagination, products are sorted by update date, with the most recently updated products first. It is not possible to sort otherwise.

IMPORTANT NOTES:

The filter isMarketable has been deprecated due to performance reasons.
The pagination by pageIndex/pageSize has been deprecated due to performance reasons. Use the pagination by cursor/limit.

Examples:

Get a list of products by GTIN (10 GTIN max. separated by comma):

/products?gtin=88381883016,8452136259876
Get a list of products based on their categories:

/products?categoryReference=010101,010102
Get a list of products using pagination by cursor:

/products?cursor=NjdjNmE1MzcxNzE5Y2ViOGI4MDc0Y2IxfG5leHQ=&limit=25
Get a list of products with some fields displayed:

/products?fields=label,description

Endpoint full URL: https://api.octopia-io.net/seller/v2/products

Parameters - Headers

Name In Type Description

Name	In	Type	Description
SellerId*	header	`string`	Octopia Seller Identifier. Example : 98979
Accept-Language	header	`string`	The Accept-Language header defines the language of the submission and must be a valid IETF BCP47 tag (default: fr-FR) Example : fr-FR

SellerId*

header

string

Octopia Seller Identifier.

Example : 98979

Accept-Language

header

string

The Accept-Language header defines the language of the submission and must be a valid IETF BCP47 tag (default: fr-FR)

Example : fr-FR

Parameters - Query

Name	In	Type	Description
limit	query	`integer`	The Limit parameter allows you to precised the number of elements should be displayed when using cursor (default: 25 / min: 0 / max: 100) Default : 50 Example : 25
cursor	query	`string`	The Cursor parameter allows you to navigate through paginated results by specifying a position in the dataset for the next retrieval Example : NjdjNmE1MzcxNzE5Y2ViOGI4MDc0Y2IxfG5leHQ=
gtin	query	`integer`	The Gtin parameter allows you to filter the products based on their gtin Example : 88381883016
categoryReference	query	`string`	The CategoryReference parameter allows you to filter the products based on their categories Example : 010201
fields	query	`string`	The Field parameter allows you to precise which fields should be displayed *(default: )** Example : label,description

Authorization

SellerId (header)

Accept-Language (header)

limit (query)

cursor (query)

gtin (query)

categoryReference (query)

fields (query)

Response codes

200 - Success

application/json

{
  "itemsPerPage": 10,
  "items": [
    {
      "reference": "A58BC78",
      "label": "SAMSUNG Galaxy Note 20 256Go Black",
      "gtin": "8806088879093",
      "groupReference": "AZ1234",
      "description": "A stunning array of mystic hues that redefine work and play",
      "language": "fr-FR",
      "richMarketingDescription": {
        "contentType": "text/html",
        "content": "",
        "media": [
          {
            "index": 1,
            "mimeType": "image/jpeg",
            "url": "https://media.octopia-io.net/image.jpg"
          }
        ],
        "updatedAt": "2022-01-01T00:00:00Z"
      },
      "marketingDescription": "he first to merge a pen with a phone, the Note put a whole new world in your pocket",
      "pictures": [
        {
          "index": 1,
          "updatedAt": "2021-03-28T08:32:30.125Z",
          "url": "https://static.education.francetv.fr/media/img/hd/img.gif"
        }
      ],
      "videos": [
        {
          "index": 1,
          "platform": "youtube",
          "videoId": "dQw4w9WgXcQ",
          "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
          "updatedAt": "2021-03-28T08:32:30.125Z"
        }
      ],
      "category": {
        "label": "SMARTPHONE",
        "reference": "070302",
        "referencePath": "07/0703/070302"
      },
      "brand": {
        "name": "Robe en tule",
        "reference": "010d04"
      },
      "attributes": [
        {
          "reference": "39635",
          "label": "Memory",
          "unit": "kg",
          "values": [
            "Electrique"
          ],
          "files": [
            {
              "index": 1,
              "mimeType": "application/pdf",
              "url": "https://media.pdf",
              "updatedAt": "2021-03-28T08:32:30.0000000+00:00"
            }
          ]
        }
      ],
      "variantAttributes": [
        {
          "reference": "39635",
          "label": "Memory",
          "unit": "kg",
          "values": [
            "Electrique"
          ],
          "files": [
            {
              "index": 1,
              "mimeType": "application/pdf",
              "url": "https://media.pdf",
              "updatedAt": "2021-03-28T08:32:30.0000000+00:00"
            }
          ]
        }
      ],
      "completeness": 0,
      "isMarketable": false,
      "isTop": false,
      "origin": "Octopia",
      "status": "Archived",
      "updatedAt": "2021-03-28T08:32:30.125Z",
      "createdAt": "2022-01-14T07:35:19.045Z",
      "expireAt": "2022-01-14T07:35:19.045Z",
      "sellers": [
        {
          "reference": "1234",
          "productReference": "SAMNOTE20_256",
          "isCreator": true,
          "variantGroupReference": "Ref8806088879090"
        }
      ],
      "variantGroupReference": "Ref8806088879090",
      "permissions": {
        "edit": false,
        "enrich": false
      }
    }
  ]
}

Headers:

Name Type Description

Link

string

The Link parameter provides URLs for navigating to the first, previous and next pages in paginated responses by cursor

Example : </products?limit=12&fields=*>; rel="first",</products?cursor=NjdjMmIwYTUxNzE5Y2ViOGI4MDc0YmQ5fHByZXY=&limit=12&fields=*>; rel="prev",</products?cursor=NjdjN2Y2YzUwNDI2ZTBlMjBiOWNhM2UyfG5leHQ=&limit=12&fields=*>; rel="next"

400 - Bad Request

application/problem+json

{
  "detail": "Information about the errors",
  "type": "https://tools.ietf.org/html/rfc7231",
  "status": 400,
  "title": "Bad Request",
  "traceId": "00-9055d0e39a4a5554866eee202737812f-8e3fb58dea31a710-00",
  "errors": {
    "Field": [
      "Any error on specified field"
    ],
    "OtherField": [
      "Any other error on specified field"
    ]
  }
}

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"
}

"videos": [
  {
    "index": 1,
    "platform": "youtube",
    "videoId": "dQw4w9WgXcQ",
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "updatedAt": "2026-11-09T10:00:00Z"
  }
]

Why it matters

Product pages with videos typically generate higher engagement and conversion rates. Sellers who already produce video content for their products can now surface it directly on the marketplace product page, without any manual action in the Seller Portal.