Multi-variant offers in REST API

Via multi-variant feature you can combine offers of the same product, but in different variants, into a multi-variant offer, e.g. shoes of different size and color. You can work with multi-variant offers via resources:


Moreover, we have updated the resources below by adding information about multi-variant support:

We have added the variantsAllowed field in the options array to sale/categories/{categoryId}/parameters. It informs whether a particular parameter can be used to create an multi-variant offer.

information Note! Before you combine offers using the REST API multi-variant feature read this guide to combining offers as well as best practice. Remember that you can combine only active offers.

Check category

First, check if you can use multi-variant in a given category.

Retrieve information on a particular category via GET /sale/categories/{categoryId}.

If you want to create a multi-variant offer using the color/pattern parameter, check the variantsByColorPatternAllowed, located in the options array.

information Note! If you use GET /sale/categories without providing any category, you will retrieve IDs of main Allegro categories. Use the identifiers to get to the lowest tier category. Remember – an offer can be listed in the lowest tier category if the category is marked “leaf”: true.


Sample request:

curl -X GET \
    'https://api.allegro.pl/sale/categories/{categoryId}
    -H 'Accept: application/vnd.allegro.public.v1+json’ \
    -H ‘Accept-Language: pl' \                                            
    -H 'Authorization: Bearer {token}'


Click to view sample response:
{
    "id": "87913",                                – category ID
    "name": "T-shirty",                           – category name
    "parent": {                                   – parent category ID;
                                                     in the case of main categories it is null

"id": "1455" }, "leaf": true, – information whether the category is of the lowest tier; two values are supported: false (it is not) and true (it is)
"options": { "variantsByColorPatternAllowed": true, – information whether this category supports combining by color/pattern in multi-variant offers "advertisement": false,
"advertisementPriceOptional": false
} }

Check parameters

Use GET /sale/categories/{categoryId}/parameters to retrieve parameters you can use to create multi-variant offers..

Use this resource to retrieve the lists of parameters that are supported by the category you indicated. If you want to create a multi-variant offer, check the variantsAllowed located in the options array. Additionally if in the field ‘variantsEqual’ value is ‘true’ all variants of the offer must have the same values in these parameters.

Sample request:

curl -X GET \
    'https://api.allegro.pl/sale/categories/{categoryId}/parameters
    -H 'Accept: application/vnd.allegro.public.v1+json’ \                                           
    -H 'Authorization: Bearer {token}'


Click to view sample response:
{
    "parameters": [                             – list of parameters supported
                                                 by the particular category
        {
            "id": "11323",                      – unique parameter ID
            "name": "Stan",                     – parameter name
            "type": "dictionary",
            "required": true,
            "unit": null,
            "options": {
                "variantsAllowed": false,       – information whether the parameter
                                                can be used with the multi-variant
                                                feature.
                "variantsEqual": true           – information whether the paramete is verifying.
            },
            "dictionary": [
                {
                    "id": "11323_1",
                    "value": "Nowy"             – parameter value
                },
                {
                    "id": "11323_2",
                    "value": "Używany"
                },
                {
                    "id": "11323_246510",
                    "value": "Nowy bez metki"
                },
                {
                    "id": "11323_246514",
                    "value": "Nowy z defektem"
                }
            ],
}


If you try to create / modify a multi-variant offer with offers that have different values in the parameters that have “variantsEqual” value: true, then we’ll show you the error:


{
    "errors": [
        {
            "code": "VALIDATION_ERROR",
            "message": "Wszystkie aktywne oferty muszą posiadać identyczne
                        wartości w ramach parametrów: 127995, 128010.",
            "details": null,
            "path": null,
            "userMessage": "Wszystkie aktywne oferty muszą posiadać identyczne
                            wartości w ramach parametrów: 127995, 128010."
        }
    ]
}


information Note! You can’t combine offers which lack the verification parameters values.

Create a multi-variant offer

Use POST /sale/offer-variants to create new multi-variant offer.

Along with parameters marked with “variantsAllowed”: true, you can use the color/pattern parameter with a multi-variant feature owing to the colorPattern field. Use this parameter to combine selected offers into a multi-variant offer, e.g. the same phone, but in various colors.

If you provide the same value in the colorPattern field in particular offers, it means you want to combine these offers by the color/pattern parameter. Below you will find an example, which describes how color/pattern works:

  1. You listed four offers in the same category:

    • Black Samsung Galaxy S8 with 1GB of RAM

    • Black Samsung Galaxy S8 with 2GB of RAM

    • Blue Samsung Galaxy S8 with 1GB of RAM

    • Blue Samsung Galaxy S8 with 2GB of RAM

  2. Each color variant differs with the main picture (thumbnail) - black phones have the same main picture, similarly blue. To combine offers with the same picture, according to the color/pattern parameter, provide the “black” value for black phones and “blue” for blue ones.

  3. The same value for all offers, e.g. “black”, will return error in response, with “Offers must have unique values of parameters” message.


Sample request - how to combine offers by ‘color/pattern’ and ‘RAM’:

Click to view sample request:
curl -X POST 
https://api.allegro.pl/sale/offer-variants -H 'Accept: application/vnd.allegro.public.v1+json’
-H 'Content-type: application/vnd.allegro.public.v1+json'
-H ‘Accept-Language: pl'
-H 'Authorization: Bearer {token}'
-d ‘{ "offers": [ – object with offers you want to combine into multi-variant offer { "id": "7436547561", – offer ID "colorPattern": "blue" – string. max. 50 characters. you set this value, We use it to combine offers by the color/pattern value. }, { "id": "7436547581",
"colorPattern": "blue"
}, { "id": "7436347561", "colorPattern": "black" }, { "id": "7436347561", "colorPattern": "black" } ], "name": "Telefony", – required, name of the multi-variant offer, You set it by yourself. You can use it later as a value of the ‘query’ parameter to get a specific multi-variant offer via GET /sale/offer-variants. "parameters": [ – array of parameters used to combine offers. You can set up to 2 parameters. You can get parameter ID for the selected category via GET /sale/categories/{categoryId}/parameters -
value true in options.variantsAllowed field Indicates that you can use here selected paramete.
{ "id": "202865" – ID of a parameter by which you want to combine offers }, { "id": "color/pattern – use this value if you want to use to combine offers by color/pattern } ] }'


Click to view sample response:
{
    "id": "bc08ceb6-b02f-4d71-b3fb-20e1d444574c",   – ID of a multi-variant offer
    "offers": [                                     – offers, that are included in the
                                                    multi-variant offer
        {
            "id": "7436547561",
            "colorPattern": "blue"
        },
        {
            "id": "7436547581",
            "colorPattern": "blue"
        },
        {
            "id": "7436347561",
            "colorPattern": "black"
        },
        {
            "id": "7436348561",
            "colorPattern": "black"
        }
    ],
    "name": "Telefony",                             – name of the multi-variant offer
    "parameters": [                                 – array of parameters by which
                                                    you create multi-variant offer
        {
            "id": "202865"
        },
        {
            "id": "color/pattern"
        }
    ]
}


Outcome:

oferta


Sample request - how to combine offers by RAM and processor core parameters:

Click to view sample request:
curl -X POST 
https://api.allegro.pl/sale/offer-variants
-H 'Accept: application/vnd.allegro.public.v1+json'
-H 'Content-Type: application/vnd.allegro.public.v1+json'
-H ‘Accept-Language: pl'
-H 'Authorization: Bearer {token}'

-d '{ "offers": [
{ "id": "7440434493"
}, { "id": "7440434632" }, { "id": "7440434772" }, { "id": "7440434909" } ], "name": "Laptops",
"parameters": [
{ "id": "200941"
}, { "id": "4329"
} ] }'


Outcome:

oferta2

In categories where we automatically combine offers

We automatically combine offers in the Fashion category, in the clothing and footwear categories outside the Fashion section, also in Jewelery and Watches category. You can get the full list in Allegro Terms and Conditions. We create these multi-variant offer from offers with identical photos and different values of the size parameter (or different parameter which determinate size).

If you have listed separate offers, e.g. t-shirts in size S, M, L in blue and red color (pt 1), we will create two multi-variant offers combined by color/pattern parameter (pt 2). You can recognize automatically combined multi-variant offers by name - in this case you don’t provide it by yourself - it will be inherited title from one of the offers that is included in the multi-variant offer. The name may change if we combine automatically created multi-variant offer with next offers. You can edit and remove the automatically combined offer. If you remove one, we won’t combine offers again.

Automatycznie połączoną ofertę możesz edytować oraz rozłączać. Jeśli ją rozłączysz, nie połączymy ofert ponownie.

wielowariantowość

Sample structures for multi-variant offers, that we combined automatically:

Click to view sample request:
{
        "id" : "97f4696e-937d-4f73-aafa-6266f85c41e5",      – ID of a multi-variant offer
        "offers" : [                                        – offers, that are included in the
                                                            multi-variant offer
            {
                "id": "1",
}, { "id": "2", }, { "id": "3", }, ], "name" : "t-shirt S blue", – name of the multi-variant offer. In case of automatically combined offers this will be inherited title from one of the offers that is included in the multi-variant offer "parameters": [ { "id": "54" – parameter which define different variants in multi-variant offer. In this it’s size.
} ] } { "id" : "495b4825-7f45-4ea8-826f-f71e795f6daf", "offers" : [ { "id": "4", }, { "id": "5", }, { "id": "6", }, ], "name" : "t-shirt S red", "parameters": [ { "id": "54" } ] }


If you want to create a new multi-variant offer based on automatically combined offers - provide in the request selected or all offer IDs from automatically combined offers (pt 3). New multivariate offer will consist of all offers which automatically created set consisted of.

wielowariantowość2


information Note! Remember, if you create a multi-variant offer, which consists of more than one automatically combined multi-variant offer - provide two parameters that will determine different product variants. One of the id field values must color/pattern.


Click to view sample request:
curl -X POST 
https://api.allegro.pl/sale/offer-variants/ -H 'Accept: application/vnd.allegro.public.v1+json’
-H ‘Accept-Language: pl'
-H 'Authorization: Bearer {token}'
-d '{ "name": "T-shirts", – required, name of the multi-variant-offer "offers": [ { "id": "1", "colorPattern": "blue" – value by which we combine offers by color/pattern parameter }, { "id": "4", "colorPattern": "red" } ], "parameters": [ – when you create multi-variant offer based on automatically combined offers, provide two parameters, one of them must be color/pattern. Based on provided parameters we will create different product variants in multi-variant offer. { "id": "color/pattern"
}, { "id": "54" – size } ]

}'

In response you will receive new multi-variant offer, which will include all offers from previously automatically combined multi-variant offers, which are associated with IDs sent in the request (pt 4). We will remove automatically created mutli-variant offers during creating new multi variant-offer.

wielowariantowość2


Click to view sample request:
curl -X POST 
https://api.allegro.pl/sale/offer-variants/ -H 'Accept: application/vnd.allegro.public.v1+json’
-H ‘Accept-Language: pl'
-H 'Authorization: Bearer {token}'
-d '{ "id": "ae9818d7-f747-4900-9d16-adee2664f183", "offers": [ { "id": "1", "colorPattern": "blue" }, { "id": "2", "colorPattern": "blue" }, { "id": "3", "colorPattern": "blue" }, { "id": "4", "colorPattern": "red" }, { "id": "5", "colorPattern": "red" }, { "id": "6", "colorPattern": "red" } ], "name": "T-shirts", "parameters": [ { "id": "54" }, { "id": "color/pattern" } ] }


If you list a new offer, which can be combined according to the color/pattern parameter, but which has a different size, we will automatically add it to the multi-variant offer that you created in point 4.

Handling duplicates

Duplicate is an offer, for which there is another offer, created by the same seller, with identical:

  • first picture,

  • parameters,

  • category.

If you list following offers, which are t-shirts:

  • ID 1, blue S,

  • ID 2, blue L,

  • ID 3, blue S (duplicate),

  • ID 4, red S,

  • ID 5, red M.

Offers with ID 1, 2 and 4, 5 will be automatically combined into multi-variant offers. If you try to create multi-variant offers based on offers with ID: 1, 3 (duplicate) and 4, in response you will receive error status 422.

Update a multi-variant offer

Via GET /sale/offer-variants/{setId} retrieve multi-variant offer to which you want to add new offer. If you don’t know setId, you can retrieve it via GET /sale/offer-variants?query={query}:

  • As a query - name of the multi-variant offer or one of the IDs.


Sample request:

curl -X GET \
    'https://api.allegro.pl/sale/offer-variants/351e65c3-74c0-4644-91c8-eeb4da291d3b
    -H 'Accept: application/vnd.allegro.public.v1+json’ \                                           
    -H 'Authorization: Bearer {token}'


Sample response:

{
    "id": "351e65c3-74c0-4644-91c8-eeb4da291d3b",
    "offers": [
        {
            "id": "8569901198",
            "colorPattern": null
        },
        {
            "id": "8569899104",
            "colorPattern": null
        }
    ],
    "name": "T-shirts",
    "parameters": [
        {
            "id": "54"
        }
    ]
}


Provide the received structure, along with the new offer data, via PUT /sale/offer-variants/{setId}. Remember to pass the ID of the multi-variant offer you want to edit as setId.


Click to view sample request:
curl -X PUT 
'https://api.allegro.pl/sale/offer-variants/351e65c3-74c0-4644-91c8-eeb4da291d3b -H 'Accept: application/vnd.allegro.public.v1+json’
-H 'Authorization: Bearer {token}' -d ‘{ "id": "351e65c3-74c0-4644-91c8-eeb4da291d3b", "offers": [ { "id": "8569901198", "colorPattern": null }, { "id": "8569899104", "colorPattern": null }, { "id": "8569909931", "colorPattern": null } ], "name": "T-shirts", "parameters": [ { "id": "54" } ] }’

In response you will receive an updated multi-variant offer.

Remember! If you add an offer which is included in automatically combined multi-variant offer to your multi-variant offer, we will add all automated combined offers to the edited offer. Below you can find an example of this case.

  1. Via GET /sale/offer-variants/{setID} I retrieve multi-variant offer that I want to edit. In response I receive:

    Click to view sample response:
          {
          "id": "bcf32fe3-5c7a-4b4e-95b0-290287d6f36f",
    "offers": [
    { "id": "8947219936", "colorPattern": "blue" }, { "id": "8947219485", "colorPattern": "blue" }, { "id": "8947220125", "colorPattern": "green" }, { "id": "8947220126", "colorPattern": "green" } ], "name": "test offer",
    "parameters": [ { "id": "54" }, { "id": "color/pattern" } ] }

  2. I provide response from previous point in structure via PUT /sale/offer-variants/{setId}, in addition I add new offer (or offers):

    Click to view sample response:
          {
          "id": "bcf32fe3-5c7a-4b4e-95b0-290287d6f36f",
    "offers": [
    { "id": "8947219936", "colorPattern": "blue" }, { "id": "8947219485", "colorPattern": "blue" }, { "id": "8947220125", "colorPattern": "green" }, { "id": "8947220126", "colorPattern": "green" } { "id": "8947220127",
    "colorPattern": "yellow" } ], "name": "test offer",
    "parameters": [ { "id": "54" }, { "id": "color/pattern" } ] }

  3. In response, I received an updated multi-variant offer. Please note that we have added all offers from automatically created multi-variant offer with which offer 8947220127 was associated.

    Click to view sample response:
          {
          "id": "bcf32fe3-5c7a-4b4e-95b0-290287d6f36f",
    "offers": [
    { "id": "8947219936", "colorPattern": "blue" }, { "id": "8947219485", "colorPattern": "blue" }, { "id": "8947220125", "colorPattern": "green" }, { "id": "8947220126", "colorPattern": "green" } { "id": "8947220127",
    "colorPattern": "yellow" }, { "id": "8947220157",
    "colorPattern": "yellow" }, { "id": "8947220128",
    "colorPattern": "yellow" } ], "name": "test offer",
    "parameters": [ { "id": "54" }, { "id": "color/pattern" } ] }

Retrieve a multi-variant offer

Use GET /sale/offer-variants to retrieve multi-variant offers you created using current account. You can also download an multi-variant offers list that meets your needs by specify parameters:

  • limit - set the number of multi-variant offers to be returned in the response (takes values from 10 - 50),

  • offset - indicate the place from which you want to download another portion of data,

  • query - name of the multi-variant offer or one of the IDs, which is included in the multi-variant offer.

e.g. GET /sale/offer-variants?limit=50&offset=50 - will return a list of 50 multi-variant offers from the given point.


Sample request:

curl -X GET \
    'https://api.allegro.pl/sale/offer-variants
    -H 'Accept: application/vnd.allegro.public.v1+json’ \                                           
    -H 'Authorization: Bearer {token}'


Sample response:

{
    "count": 2,                                                  -- number of multi-variant offers
                                                                    saved to the account.
    "offerVariants": [
        {
            "id": "ac3ed08b-966a-47ce-9886-f5dc790b59f8",        -- multi-variant offer UUID.
            "name": "Bicycles"                                   -- name of a multi-variant offer
        },
        {
            "id": "b6d83e16-b9d2-45a7-a20e-4b6971cbb0e2",
            "name": "Red shirts"
        }
    ]
}

Remove a multi-variant offer

You can remove multi-variant offer via DELETE /sale/offer-variants/{setId}. If you remove one, we won’t combine offers again.

FAQ

1. Can I add offers from one multi-variant offer I created to another?

No, in this case you will receive an error that indicates that offers are already in another multi-variant set. You can add one or more offers that are part of an automatically created multi-variant offer.

2. How can I add offers from multi-variant offer I created to another multi-variant set - also created by me?

In this case use DELETE /sale/offer-variants/{setId} to separate offers from selected multi-variant offer. In the next step use PUT sale/offer-variants/{setId} to add these offers to another multi-variant offer.

3. Can I create a multi-variant offer before the offers are combined automatically?

Yes, provided that processing data about new offers was completed, before you send the request combining these offers. Otherwise, you will receive an error with the information that we are still processing offers from which you want to create multi-variant offer.

4. Can I create a multi-variant offer before activating the offers?

No, you will receive an error with the information offers which you provided can’t be found. Offers must be in ACTIVE status.

5. I did not save the ID of the multi-variant offer. How can I find it?

You can retrieve it via GET /sale/offer-variants?query={query}. As a query - name of the multi-variant offer or one of the IDs, which is included in the multi-variant offer.

6. What happens if I end offer that was included in the multi-variant offer and then activate it again?

Offer will be included again in the multi-variant offer.

7. In the response to GET /sale/offer-variants/{id} sometimes I receive ended offers and sometimes not. Why?

We do not return ended offers for multi-variant offers in categories managed automatically - a full list can be found here. In other categories, multi-variant offers are managed manually and we return ended offers for them.

List of resources

You will find full documentation of resources in the swagger.yaml form file here.

List of basic resources used in tutorial:

List of supporting resources used in tutorial: