How to list an offer assigned to a product with one request

Via POST /sale/product-offers you can list with one request:

  • an active offer assigned to a product, which already exists in our database. Provide in your request EAN code (or product ID), price and quantity. You can retrieve product data via GET /sale/products?ean={ean}

    Click to view sample request:
      curl -X POST
      ‘https://api.allegro.pl/sale/product-offers’
      -H 'Authorization: Bearer {token}'
      -H 'Accept: application/vnd.allegro.beta.v2+json'
      -H 'Accept-Language: en-US'
      -H 'Content-Type: application/vnd.allegro.beta.v2+json'
      -d ‘{
      "product": {
        "id": "5902719471797"           -- EAN or product ID
      },
      "sellingMode": {
        "price": {
          "amount": "220.85",           
          "currency": "PLN"
        }
      },
      "stock": {
        "available": 10                 
      }
    }’

    If in response you receive information about missing required parameters, provide them in product object. You can check parameter ID with its value via GET /sale/{categoryID}/parameters.
    Click to view sample request:
      curl -X POST
      ‘https://api.allegro.pl/sale/product-offers’
      -H 'Authorization: Bearer {token}'
      -H 'Accept: application/vnd.allegro.beta.v2+json'
      -H 'Accept-Language: en-US'
      -H 'Content-Type: application/vnd.allegro.beta.v2+json'
      -d ‘{
      "product": {
        "id": "d26b023c-d52c-44f9-b61a-321eb202792b",
        "parameters": [
          {
            "id": "202293",
            "valuesIds": [
              "202293_211441"
            ]
          }
        ]
      },
      "sellingMode": {
        "price": {
          "amount": "220.85",
          "currency": "PLN"
        }
      },
      "stock": {
        "available": 1
      }
    }
    ’

  • an active offer assigned to a product, which is not in our database. Provide in your request (in product object), product data which describe your product. Also provide price and quantity information. We describe this process in detail further in this guide.

    Click to view sample request:
     curl -X POST
        ‘https://api.allegro.pl/sale/product-offers’
        -H 'Authorization: Bearer {token}'
        -H 'Accept: application/vnd.allegro.beta.v2+json'
        -H ‘Accept-Language: en-US’
        -H 'Content-Type: application/vnd.allegro.beta.v2+json'
        -d ‘{
        "product": {                        -- product data
                "name": "Test product",
                "category":{
                        "id":"89060"
                },
            "parameters":[
                {
                        "name": "EAN",
                        "values": [
                                    "0744861045021"
                        ]
                    },
                    {
                        "id": "237218",
                        "values": [
                                    "Test value"
                        ]
                    }
            ],
            "images":[   
                    "https://...first-image-address.jpeg"
            ]
      },
        "sellingMode": {
                "price": {
                    "amount": "220.85",         
                    "currency": "PLN"
                }
        },
         "stock": {
                "available": 10                 
        }
    }’

If, based on the data provided, we recognize that the product is in our database, we will take its data and include it in your offer:

  • category and parameters,
  • images,
  • product description (if you will not add your own),
  • EAN code,
  • compatibilityList section,
  • TecDoc specification.

You don’t need to perform a separate publication command to activate an offer. You don’t have to provide other data needed to list an offer, if you want them to be complemented with default values. The default values and their possible sources are presented in the table below. You can find more information, how to construct your request, if you want to provide different data than default values.

Field Value
Publication status Offer will be activated immediately
Selling mode Buy now
Unit type Unit (pieces)
Location Data from Allegro account settings (your address)
Invoice VAT
Handling Time 24 hours
Duration Until all available items will sold out
Delivery price list If you have only one delivery price list, we will assign it to the offer. In other cases - we will use the delivery price list with name default. If you don’t have a delivery price list with this name, we will return 422 status.
Implied warranty and Return policy If you have only one option for this fields, we will assign it to the offer. In other cases, we will use variant with name default. If you don’t have a variant with this name, we will return 422 status. This applies only to company accounts, for regular accounts we will not provide any value here.


In the future, when you use this resource, we will fill out your offers with the most recent data from our product catalog. If you don’t provide your own values, different from those in the product, you won’t need to copy or accept changes in your offers after we update the catalog. It will also allow us to automatically complete the parameters that we currently require when editing the offer.

How does integration with an asynchronous API work

Due to the longer time of some operations e.g. change of the offer publication status we have introduced the asynchronous API pattern for the /sale/product-offers resources. The diagram below presents how it works:

async_api

You will receive one of three statuses in response to a valid request to the sale/product-offers/:

  • 200 OK - we will implement the changes immediately. Only occurs with the PATCH method,

  • 201 Created - we will create an offer immediately. Only occurs with the POST method,

  • 202 Accepted - we will perform the task asynchronously due to the longer duration of the operation. Occurs with the POST and PATCH methods.


Along with the 202 Accepted status, we will return the Location header in which you will find a link to the new resource. Use the GET method on it to check the task status. In response, you will receive one of two statuses:

  • 202 Accepted - the operation has not been completed yet. Repeat the previous request,

  • 303 See Other - the operation is finished. In the Location header, we will return a link to the new resource - /sale/product-offers/{offerId}. Use the GET method on it and in the response you will receive the current offer data.

Offer publication in asynchronous API

async_api_publication

When you receive 201 Created status - we will return offer data in response. We will create it synchronously.


Sample request:

  curl -X POST
  ‘https://api.allegro.pl/sale/product-offers’
  -H 'Authorization: Bearer {token}'
  -H 'Accept: application/vnd.allegro.beta.v2+json'
  -H 'Content-Type: application/vnd.allegro.beta.v2+json'
  -d ‘{
    "product": {
      "id": "5902719471797"          
    },
    "sellingMode": {
      "price": {
        "amount": "220.85",    
        "currency": "PLN"
      }
    },
    "stock": {
      "available": 10               
    },
     "publication": {
      "status": "INACTIVE"
    }
  }’


Click to view sample response:
{

 HTTP/1.1 201 Created
  {
    "id": "9531382307’",
    "name": "Sample product",
    "product": {
        "id": null,
        "publication": {
            "status": "NOT_LISTED"
        }
    },
    "afterSalesServices": {
        "impliedWarranty": {
            "id": "f86078a6-9f42-4b76-9696-1e5c0646a60a"
        },
        "returnPolicy": {
            "id": "47101223-7236-4201-9779-316e6d10af2a"
        },
        "warranty": null
    },
    "payments": {
        "invoice": "NO_INVOICE"
    },
    "sellingMode": {
        "format": "BUY_NOW",
        "price": {
            "amount": 50,
            "currency": "PLN"
        },
        "startingPrice": null,
        "minimalPrice": null
    },
    "stock": {
        "available": 1,
        "unit": "UNIT"
    },
    "location": {
        "countryCode": "PL",
        "province": "WIELKOPOLSKIE",
        "city": "Poznań",
        "postCode": "66-166"
    },
    "delivery": {
        "shippingRates": {
            "id": "17221a3c-f4cf-4e47-953a-8e125013b014"
        },
        "handlingTime": "PT336H",
        "additionalInfo": ""
    },
    "publication": {
        "duration": null,
        "status": "INACTIVE",
        "endedBy": null,
        "endingAt": null,
        "startingAt": null,
        "republish": false
    },
    "description": {
        "sections": [
            {
                "items": [
                    {
                        "type": "TEXT",
                        "content": "<p>test</p>"
                    }
                ]
            }
        ]
    },
    "validation": {
        "errors": [],
        "warnings": [],
        "validatedAt": "2020-11-06T15:39:53.898Z"
    },
    "createdAt": "2020-10-01T05:44:23Z",
    "updatedAt": "2020-11-06T15:39:55.574Z",
    "images": [
        "https://a.allegroimg..pl/original/116421/ece7111d4b8fbbc4662ab92f84ce"
    ],
    "external": null,
    "category": {
        "id": "79419"
    },
    "tax": {
        "percentage": null
    },
    "sizeTable": null
  }

If in the response to a valid request using POST /sale/product-offers, you will receive 202 Accepted status, we will return offer data in current state - not including the processing changes.


Sample request:

  curl -X POST
  ‘https://api.allegro.pl/sale/product-offers’
  -H 'Authorization: Bearer {token}'
  -H 'Accept: application/vnd.allegro.beta.v2+json'
  -H 'Content-Type: application/vnd.allegro.beta.v2+json'
  -d ‘{
  "product": {
    "id": "5902719471797"
  },
  "sellingMode": {
    "price": {
      "amount": "220.85",
      "currency": "PLN"
    }
  },
  "stock": {
    "available": 10
  }
 }’


Click to view sample response:
{

 HTTP/1.1 202 Accepted
 location: https://api.allegro.pl/sale/product-offers/9531382307/operations/eadb2e97-9850-4c51-bd27-68888b6d7d5d
 retry-after: 5
 {
    "id": "9531382307’",
    "name": "Sample product",
    "product": {
        "id": 5902719471797,
        "publication": {
            "status": "NOT_LISTED"
        }
    },
    "afterSalesServices": {
        "impliedWarranty": {
            "id": "f86078a6-9f42-4b76-9696-1e5c0646a60a"
        },
        "returnPolicy": {
            "id": "47101223-7236-4201-9779-316e6d10af2a"
        },
        "warranty": null
    },
    "payments": {
        "invoice": "NO_INVOICE"
    },
    "sellingMode": {
        "format": "BUY_NOW",
        "price": {
            "amount": 50,
            "currency": "PLN"
        },
        "startingPrice": null,
        "minimalPrice": null
    },
    "stock": {
        "available": 1,
        "unit": "UNIT"
    },
    "location": {
        "countryCode": "PL",
        "province": "WIELKOPOLSKIE",
        "city": "Poznań",
        "postCode": "66-166"
    },
    "delivery": {
        "shippingRates": {
            "id": "17221a3c-f4cf-4e47-953a-8e125013b014"
        },
        "handlingTime": "PT336H",
        "additionalInfo": ""
    },
    "publication": {
        "duration": null,
        "status": "INACTIVE",
        "endedBy": null,
        "endingAt": null,
        "startingAt": null,
        "republish": false
    },
    "description": {
        "sections": [
            {
                "items": [
                    {
                        "type": "TEXT",
                        "content": "<p>test</p>"
                    }
                ]
            }
        ]
    },
    "validation": {
        "errors": [],
        "warnings": [],
        "validatedAt": "2020-11-06T15:39:53.898Z"
    },
    "createdAt": "2020-10-01T05:44:23Z",
    "updatedAt": "2020-11-06T15:39:55.574Z",
    "images": [
      "https://a.allegroimgpl/original/116421/ece7111d4b8fbbc4662ab92f84ce"
    ],
    "external": null,
    "category": {
        "id": "79419"
    },
    "tax": {
        "percentage": null
    },
    "sizeTable": null
}


Use the address received in the Location header to check the publication status, to check the status of your request. In the retry-after header, we return information on how many seconds you need to wait until you can send a request again.

Use the GET method on the received address in the Location header. Until the operation is completed, in response we will return status 202 Accepted.


Sample request:

  curl -X GET
  ‘https://api.allegro.pl/sale/product-offers/9531382307/operations/eadb2e97-9850-4c51-bd27-68888b6d7d5d’
  -H 'Authorization: Bearer {token}'
  -H 'Accept: application/vnd.allegro.beta.v2+json'
  -H 'Content-Type: application/vnd.allegro.beta.v2+json'


Sample response

{

 HTTP/1.1 202 Accepted
 location: https://api.allegro.pl/sale/product-offers/9531382307/operations/eadb2e97-9850-4c51-bd27-68888b6d7d5d
 retry-after: 5
  {
  "offer": {
    "id": "9531382307"
  },
  "operation": {
    "id": "ef5dd966-d370-44f7-bb30-3631e3511536",
    "status": "IN_PROGRESS",
    "startedAt": "2019-05-29T12:00:00Z"
  }
 }


When we finished processing the operation, we will return HTTP status 303 See Other in the response to GET /sale/product-offers/{offerId}/operations/{operationId}. In the location header, you will receive a link to offer data.


Sample request:

  curl -X GET
  ‘https://api.allegro.pl/sale/product-offers/9531382307/operations/eadb2e97-9850-4c51-bd27-68888b6d7d5d’
  -H 'Authorization: Bearer {token}'
  -H 'Accept: application/vnd.allegro.beta.v2+json'
  -H 'Content-Type: application/vnd.allegro.beta.v2+json'


Sample response:

  HTTP/1.1: 303 See other
  location: https://api.allegro.pl/sale/product-offers/9531382307


Możesz teraz skorzystać z metody GET oraz otrzymanego odnośnika w nagłówku Location, aby uzyskać aktualne dane oferty. Utworzysz dzięki temu żądanie w następującej formie: GET /sale/product-offers/{offerId}.


Przykładowy request:

  curl -X GET
  ‘https://api.allegro.pl/sale/product-offers/9531382307
  -H 'Authorization: Bearer {token}'
  -H 'Accept: application/vnd.allegro.beta.v2+json'
  -H 'Content-Type: application/vnd.allegro.beta.v2+json'


Click to view sample response:
{

 {
    "id": "9531382307’",
    "name": "Sample product",
    "product": {
        "id": 5902719471797,
        "publication": {
            "status": "NOT_LISTED"
        }
    },
    "afterSalesServices": {
        "impliedWarranty": {
            "id": "f86078a6-9f42-4b76-9696-1e5c0646a60a"
        },
        "returnPolicy": {
            "id": "47101223-7236-4201-9779-316e6d10af2a"
        },
        "warranty": null
    },
    "payments": {
        "invoice": "NO_INVOICE"
    },
    "sellingMode": {
        "format": "BUY_NOW",
        "price": {
            "amount": 50,
            "currency": "PLN"
        },
        "startingPrice": null,
        "minimalPrice": null
    },
    "stock": {
        "available": 1,
        "unit": "UNIT"
    },
    "location": {
        "countryCode": "PL",
        "province": "WIELKOPOLSKIE",
        "city": "Poznań",
        "postCode": "66-166"
    },
    "delivery": {
        "shippingRates": {
            "id": "17221a3c-f4cf-4e47-953a-8e125013b014"
        },
        "handlingTime": "PT336H",
        "additionalInfo": ""
    },
    "publication": {
        "duration": null,
        "status": "ACTIVE",
        "endedBy": null,
        "endingAt": null,
        "startingAt": null,
        "republish": false
    },
    "description": {
        "sections": [
            {
                "items": [
                    {
                        "type": "TEXT",
                        "content": "<p>test</p>"
                    }
                ]
            }
        ]
    },
    "validation": {
        "errors": [],
        "warnings": [],
        "validatedAt": "2020-11-06T15:39:53.898Z"
    },
    "createdAt": "2020-10-01T05:44:23Z",
    "updatedAt": "2020-11-06T15:39:55.574Z",
    "images": [
      "https://a.allegroimg/original/116421/ece7111d4b8fbbc4662ab92f84ce"
    ],
    "external": null,
    "category": {
        "id": "79419"
    },
    "tax": {
        "percentage": null
    },
    "sizeTable": null
 }

How to provide your own values

The request structure is divided into two parts:

  • product - where you provide

    • EAN code or product ID, if you want to assign product, which is in our database, to an offer,

    • product data, if you want to assign product, which is not in our database, to an offer.

  • offer - data that determines the conditions in a specific offer, e.g. price, quantity, location, invoice information, etc. You can overwrite default offer values and add new ones. You can find a description of how to do further in this guide.

How to set your own title

We will automatically set offer title based on product name. If you want to set your own offer title, extend your request with name field:

  ...
  "name": "My own title"
  ...    

Click to view sample request:
curl -X POST
‘https://api.allegro.pl/sale/product-offers’
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.beta.v2+json'
-H 'Accept-Language: en-US'
-H 'Content-Type: application/vnd.allegro.beta.v2+json'
-d ‘{
  "product": {
    "id": "5902719471797"
  },
  "name": "My own title",
  "parameters": [
        {
            "id": "11323",
            "valuesIds": [
                "11323_2"
            ]
        }
    ],
  "sellingMode": {
    "price": {
      "amount": "220.85",
      "currency": "PLN"
    }
  },
  "stock": {
    "available": 1
  }
}’

How to set offer parameters

Offer parameters are related to individual offer, e.g. condition, expiration date, but not with the specific product feature. You must use two resources to check which ones are offer parameters and which are product:

You can receive offer parameters by subtracting product parameters from all parameters. In the future we will introduce a new field in GET /sale/categories/{categoryID}/parameters, which will indicate whether the parameter is product ones. Thanks to this, there will be no need to call two separate resources.

If you want to set, e.g. product condition in the offer as used, extend your request with the following structure:

  ...
    "parameters": [
        {
            "id": "11323",
            "valuesIds": [
                "11323_2"
            ]
        }
    ]
  ...    

You can use parameter names and their values instead of identifiers:

  ...
    "parameters": [
            "name": "Condition",
         {
           "values": [
                "Used"
            ]
        }
    ]
  ...    

Click to view sample request:
curl -X POST
‘https://api.allegro.pl/sale/product-offers’
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.beta.v2+json'
-H 'Accept-Language: en-US'
-H 'Content-Type: application/vnd.allegro.beta.v2+json'
-d ‘{
  "product": {
    "id": "5902719471797"
  },
  "name": "My own title",
  "parameters": [
        {
            "id": "11323",
            "valuesIds": [
                "11323_2"
            ]
        }
    ],
  "sellingMode": {
    "price": {
      "amount": "220.85",
      "currency": "PLN"
    }
  },
  "stock": {
    "available": 1
  }
}’

How to set the duration of the offer

If you want to set a duration of offer other than until all items are sold out, extend your request with the publication.duration field and select one of the available offer duration values:

  ...
  "publication": {
    "duration": “P30D”
    ...
  },
  ...  

The available values ​​are:

  • null (until all items are sold out),
  • P3D (3 days),
  • P5D (5 days),
  • P7D (7 days),
  • P10D (10 days),
  • P20D (20 days),
  • P30D (30 days).

You can also set the duration time in hours, e.g. P72H (3 days).

Kliknij, żeby zobaczyć przykładowy request:

 curl -X POST
 ‘https://api.allegro.pl/sale/product-offers’
 -H 'Authorization: Bearer {token}'
 -H 'Accept: application/vnd.allegro.beta.v2+json'
 -H 'Content-Type: application/vnd.allegro.beta.v2+json'
 -d ‘{
   "product": {
     "id": "5902719471797"
   },
   "name": "My own title",
   "parameters": [
         {
             "id": "11323",
             "valuesIds": [
                 "11323_2"
             ]
         }
     ],
   "sellingMode": {
     "price": {
       "amount": "220.85",
       "currency": "PLN"
     }
   },
   "stock": {
     "available": 1
   },
   "publication": {
     "duration": “P30D”
   }
 }’

How to assign a selected delivery price list

You can set any delivery price list. For example - if you have delivery price list named “small dimensions” and you want to assign it to your offer, just extend your request with additional field with the price list:

  • name:

      ...
      "delivery": {
        "shippingRates": {
            "name": "small dimensions"
        }
      },
      ...    

  • or delivery price list ID:

      ...
      "delivery": {
        "shippingRates": {
            "id": "c446793c-33f0-407f-b0ed-1aeec6090a7a"
        }
      }
      ...    

Name and IDs of delivery price list can be retrieved via GET /sale/shipping-rates.

Click to view sample request:
curl -X POST
‘https://api.allegro.pl/sale/product-offers’
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.beta.v2+json'
-H 'Accept-Language: en-US'
-H 'Content-Type: application/vnd.allegro.beta.v2+json'
-d ‘{
  "product": {
    "id": "5902719471797"
  },
  "name": "My own title",
  "parameters": [
        {
            "id": "11323",
            "valuesIds": [
                "11323_2"
            ]
        }
    ],
    "delivery": {
        "shippingRates": {
                "id": "c446793c-33f0-407f-b0ed-1aeec6090a7a"
    }
  },
  "sellingMode": {
    "price": {
      "amount": "220.85",
      "currency": "PLN"
    }
  },
  "stock": {
    "available": 1
  }
}’

How to set a different shipping time

Set value in ISO 8601 format in handlingTime field in delivery section to list an offer with a specific handling time. For example - if you want to set handling time to 2 days, you can do it in the following way:

  ...
  "delivery": {
    "handlingTime": "PT48H"
  }
  ...    

Click to view sample request:
curl -X POST
‘https://api.allegro.pl/sale/product-offers’
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.beta.v2+json'
-H 'Accept-Language: en-US'
-H 'Content-Type: application/vnd.allegro.beta.v2+json'
-d ‘{
  "product": {
    "id": "5902719471797"
  },
  "name": "My own title",
  "parameters": [
        {
            "id": "11323",
            "valuesIds": [
                "11323_2"
            ]
        }
    ],
    "delivery": {
        "shippingRates": {
            "id": "862347c4-b2b0-42d4-b84a-1db01509a69d"
    },
        "handlingTime": "PT48H"
  },
  "sellingMode": {
    "price": {
      "amount": "220.85",
      "currency": "PLN"
    }
  },
  "stock": {
    "available": 1
  }
}’

How to add additional delivery information

Extend your request with a delivery section with additionalInfo field to include additional delivery information in your offer:

  ...
  "delivery": {
        "additionalInfo": "Additional delivery information"
   }
  ...     

Click to view sample request:
curl -X POST
‘https://api.allegro.pl/sale/product-offers’
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.beta.v2+json'
-H 'Accept-Language: en-US'
-H 'Content-Type: application/vnd.allegro.beta.v2+json'
-d ‘{
  "product": {
    "id": "5902719471797"
  },
  "name": "My own title",
  "parameters": [
        {
            "id": "11323",
            "valuesIds": [
                "11323_2"
            ]
        }
    ],
    "delivery": {
        "shippingRates": {
            "id": "862347c4-b2b0-42d4-b84a-1db01509a69d"
        },
        "handlingTime": "PT48H",
        "additionalInfo": "Additional delivery information"
  },
  "sellingMode": {
    "price": {
      "amount": "220.85",
      "currency": "PLN"
    }
  },
      "afterSalesServices": {
          "impliedWarranty": {
                  "name": "toys"
        }
    },
  "stock": {
    "available": 1
  }
}’

How to set specific implied warranties

If you want to set different implied warranties than default, use their name or ID For example - if you have implied warranty named toys, whose ID is 913174eb-35ed-48df-b3b9-b9eb66b1b7a4 and you want to use it in your offer, you should extend your request with additional field, in which you will provide their:

  • name:

      ...
      "impliedWarranty": {
        "name": "toys"
      }
      ...    

  • or ID:

      ...
      "impliedWarranty": {
        "id": "913174eb-35ed-48df-b3b9-b9eb66b1b7a4"
      }
      ...    

Name and IDs of implied warranties list can be retrieved via GET /after-sales-service-conditions/implied-warranties.

Click to view sample request:
curl -X POST
‘https://api.allegro.pl/sale/product-offers’
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.beta.v2+json'
-H 'Accept-Language: en-US'
-H 'Content-Type: application/vnd.allegro.beta.v2+json'
-d ‘{
  "product": {
    "id": "5902719471797"
  },
  "name": "My own title",
  "parameters": [
        {
            "id": "11323",
            "valuesIds": [
                "11323_2"
            ]
        }
    ],
    "delivery": {
        "shippingRates": {
            "id": "862347c4-b2b0-42d4-b84a-1db01509a69d"
        },
        "handlingTime": "PT48H",
        "additionalInfo": "Additional delivery information"
  },
  "sellingMode": {
    "price": {
      "amount": "220.85",
      "currency": "PLN"
    }
  },
      "afterSalesServices": {
          "impliedWarranty": {
                  "name": "toys"
        }
    },
  "stock": {
    "available": 1
  }
}’

How to set a specific return policy

If you want to set different return policy than default, use their name or ID. For example - if you have return policy named 30 days, whose ID is a375a08e-86ee-48a4-baf7-fabe01fe2631 and you want to use it in your offer, you should extend your request with additional field, in which you will provide their:

  • name:
      ...
      "returnPolicy": {
        "name": "30 days"
      }
      ...    
  • or ID:
      ...
      "returnPolicy": {
        "id": "a375a08e-86ee-48a4-baf7-fabe01fe2631"
      }
      ...    

Name and IDs of return policies list can be retrieved via GET /after-sales-service-conditions/return-policies.

Click to view sample request:
curl -X POST
‘https://api.allegro.pl/sale/product-offers’
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.beta.v2+json'
-H 'Accept-Language: en-US'
-H 'Content-Type: application/vnd.allegro.beta.v2+json'
-d ‘{
  "product": {
    "id": "5902719471797"
  },
  "name": "My own title",
  "parameters": [
        {
            "id": "11323",
            "valuesIds": [
                "11323_2"
            ]
        }
    ],
    "delivery": {
        "shippingRates": {
            "id": "862347c4-b2b0-42d4-b84a-1db01509a69d"
        },
        "handlingTime": "PT48H",
        "additionalInfo": "Additional delivery information"
  },
  "sellingMode": {
    "price": {
      "amount": "220.85",
      "currency": "PLN"
    }
  },
      "afterSalesServices": {
        "impliedWarranty": {
            "name": "toys"
        },
        "returnPolicy": {
            "name": "30 days"
        }
    },
  "stock": {
    "available": 1
  }
}’

How to add size table

Extend your request with a sizeTable section to include a size table in your offer. You should provide in your request:

  • name of size table:
  ...
  "sizeTable": {
    "name": “Sample size table”
  }
  ...
  • ID of size table:
  ...
  "sizeTable": {
    "id": “5727b598-6608-4bd3-b198-f165b011bb69”
  }
  ...

You can retrieve names and IDs of size tables via GET /sale/size-tables.

Click to view sample request:
curl -X POST
‘https://api.allegro.pl/sale/product-offers’
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.beta.v2+json'
-H 'Accept-Language: en-US'
-H 'Content-Type: application/vnd.allegro.beta.v2+json'
-d ‘{
  "product": {
    "id": "5902719471797"
  },
  "name": "My own title",
  "parameters": [
        {
            "id": "11323",
            "valuesIds": [
                "11323_2"
            ]
        }
    ],
    "delivery": {
      "shippingRates": {
          "id": "862347c4-b2b0-42d4-b84a-1db01509a69d"
        },
      "handlingTime": "PT48H",
    "additionalInfo": "Additional delivery information"
  },
  "sellingMode": {
    "price": {
      "amount": "220.85",
      "currency": "PLN"
    }
  },
      "afterSalesServices": {
        "impliedWarranty": {
            "name": "toys"
        },
        "returnPolicy": {
      "name": "30 days"
  }
    },
    "location": {
      "countryCode": "PL",
      "province": "LUBUSKIE",
      "city": "Gorzów Wielkopolski",
      "postCode": "66-400"
   },
  "stock": {
    "available": 1
  },
  "sizeTable": {
    "name": Sample size table”
  }
}’

How to set a specific shipping location

You can set a specific shipping location, if the address is different from the address in your account settings - provide appropriate values as following:

  ...
  "location": {
    "countryCode": "PL",
    "province": "LUBUSKIE",
    "city": "Gorzów Wielkopolski",
    "postCode": "66-400"
   }
  ...    

You can find a list of available values in field location.province in our documentation.

Click to view sample request:
curl -X POST
‘https://api.allegro.pl/sale/product-offers’
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.beta.v2+json'
-H 'Accept-Language: en-US'
-H 'Content-Type: application/vnd.allegro.beta.v2+json'
-d ‘{
  "product": {
    "id": "5902719471797"
  },
  "name": "My own title",
  "parameters": [
        {
            "id": "11323",
            "valuesIds": [
                "11323_2"
            ]
        }
    ],
    "delivery": {
        "shippingRates": {
            "id": "862347c4-b2b0-42d4-b84a-1db01509a69d"
        },
        "handlingTime": "PT48H",
        "additionalInfo": "Additional delivery information"
  },
  "sellingMode": {
    "price": {
      "amount": "220.85",
      "currency": "PLN"
    }
  },
      "afterSalesServices": {
        "impliedWarranty": {
            "name": "toys"
        },
        "returnPolicy": {
            "name": "30 days"
    }
    },
    "location": {
        "countryCode": "PL",
        "province": "LUBUSKIE",
        "city": "Gorzów Wielkopolski",
        "postCode": "66-400"
   },
  "stock": {
    "available": 1
  }
}’

How to set different invoice value

If you don’t issue a VAT invoice, or you issue another form of an invoice, you can set it using the payments.invoice field:

  ...
  "payments": {
    "invoice": "NO_INVOICE"
  }
  ...    

You can find a list of available values in field payments.invoice in our documentation.

Click to view sample request:
curl -X POST
‘https://api.allegro.pl/sale/product-offers’
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.beta.v2+json'
-H 'Accept-Language: en-US'
-H 'Content-Type: application/vnd.allegro.beta.v2+json'
-d ‘{
    "product": {
        "id": "5902719471797"
    },
    "name": "My own title",
    "parameters": [{
        "id": "11323",
        "valuesIds": [
            "11323_2"
        ]
    }],
    "delivery": {
        "shippingRates": {
            "id": "862347c4-b2b0-42d4-b84a-1db01509a69d"
        },
        "handlingTime": "PT48H",
        "additionalInfo": "Additional delivery information"
    },
    "sellingMode": {
        "price": {
            "amount": "220.85",
            "currency": "PLN"
        }
    },
    "afterSalesServices": {
        "impliedWarranty": {
            "name": "toys"
        },
        "returnPolicy": {
            "name": "30 days"
        }
    },
    "location": {
        "countryCode": "PL",
        "province": "LUBUSKIE",
        "city": "Gorzów Wielkopolski",
        "postCode": "66-400"
    },
    "payments": {
        "invoice": "NO_INVOICE"
    },
    "stock": {
        "available": 1
    }
}’

How to set the VAT invoice rate

If the offer includes the option of issuing a VAT invoice, you can also specify the VAT rate in tax.percentage field. You can use only VAT rates specified by Polish law (0%, 5%, 8%, 23%). The format of the value is 0.00:

  ...
  "tax": {
    "percentage": “23.00”
  },
  ...  

Kliknij, żeby zobaczyć przykładowy request:
curl -X POST
‘https://api.allegro.pl/sale/product-offers’
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.beta.v2+json'
-H 'Content-Type: application/vnd.allegro.beta.v2+json'
-d ‘{
    "product": {
        "id": "5902719471797"
    },
    "name": "My own title",
    "parameters": [{
        "id": "11323",
        "valuesIds": [
            "11323_2"
        ]
    }],
    "delivery": {
        "shippingRates": {
            "id": "862347c4-b2b0-42d4-b84a-1db01509a69d"
        },
        "handlingTime": "PT48H",
        "additionalInfo": "Additional delivery information"
    },
    "sellingMode": {
        "price": {
            "amount": "220.85",
            "currency": "PLN"
        }
    },
    "afterSalesServices": {
        "impliedWarranty": {
            "name": "toys"
        },
        "returnPolicy": {
            "name": "30 days"
        }
    },
    "location": {
        "countryCode": "PL",
        "province": "LUBUSKIE",
        "city": "Gorzów Wielkopolski",
        "postCode": "66-400"
    },
  "tax": {
    "percentage": “23.00”
  },
    "publication": {
        "status": "ACTIVE"
  },
    "stock": {
        "available": 1
    }
}’

How to create an offer draft

If you don’t want to activate the offer, extend your request with the publication section with the status field. Use “INACTIVE” value:

  ...
  "publication": {
    "status": "INACTIVE"
  }
  ...    

Click to view sample request:
curl -X POST
‘https://api.allegro.pl/sale/product-offers’
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.beta.v2+json'
-H 'Accept-Language: en-US'
-H 'Content-Type: application/vnd.allegro.beta.v2+json’
-d ‘{
    "product": {
        "id": "5902719471797"
    },
    "name": "My own title",
    "parameters": [{
        "id": "11323",
        "valuesIds": [
            "11323_2"
        ]
    }],
    "delivery": {
        "shippingRates": {
            "id": "862347c4-b2b0-42d4-b84a-1db01509a69d"
        },
        "handlingTime": "PT48H",
        "additionalInfo": "Additional delivery information"
    },
    "sellingMode": {
        "price": {
            "amount": "220.85",
            "currency": "PLN"
        }
    },
    "afterSalesServices": {
        "impliedWarranty": {
            "name": "toys"
        },
        "returnPolicy": {
            "name": "30 days"
        }
    },
    "location": {
        "countryCode": "PL",
        "province": "LUBUSKIE",
        "city": "Gorzów Wielkopolski",
        "postCode": "66-400"
    },
    "payments": {
        "invoice": "NO_INVOICE"
    },
    "publication": {
        "status": "INACTIVE"
  },
    "stock": {
        "available": 1
    }
}’

How to add your own images

We will automatically add product photos to the offer. You can also add your own images, which present a specific copy of the product. Extend your request with additional field images:

  ...
  "images": [
    "https://...image-address.jpeg",
    "https://...image-address.jpeg"
  ]
  ...    

Images may be uploaded from external servers, you don’t have to send them to Allegro server first.. Number of photos is limited depending on the account type::

  • 16 for company account,,
  • 10 for regular account.

Click to view sample request:
curl -X POST
‘https://api.allegro.pl/sale/product-offers’
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.beta.v2+json'
-H 'Accept-Language: en-US'
-H 'Content-Type: application/vnd.allegro.beta.v2+json'
-d ‘{
    "product": {
        "id": "5902719471797"
    },
    "name": "My own title",
    "parameters": [{
        "id": "11323",
        "valuesIds": [
            "11323_2"
        ]
    }],
    "delivery": {
        "shippingRates": {
            "id": "862347c4-b2b0-42d4-b84a-1db01509a69d"
        },
        "handlingTime": "PT48H",
        "additionalInfo": "Additional delivery information"
    },
    "sellingMode": {
        "price": {
            "amount": "220.85",
            "currency": "PLN"
        }
    },
    "afterSalesServices": {
        "impliedWarranty": {
            "name": "toys"
        },
        "returnPolicy": {
            "name": "30 days"
        }
    },
    "location": {
        "countryCode": "PL",
        "province": "LUBUSKIE",
        "city": "Gorzów Wielkopolski",
        "postCode": "66-400"
    },
    "payments": {
        "invoice": "NO_INVOICE"
    },
    "publication": {
        "status": "INACTIVE"
  },
  "images": [
    "https://...image-address.jpeg",
    "https://...image-address2.jpeg"
  ],
    "stock": {
        "available": 1
    }
}’

How to add offer description

You can add your own description to the offer. If you will not, we will automatically assign a description from the product you indicated in the request.

Extend your request with additional field description:

  ...
  "description": {
        "sections": [
            {
                "items": [
                    {
                        "type": "TEXT",
                        "content": "<p>Sample description</p>"
                    }
                ]
            }
        ]
    }
  ...    

You can find information on how to prepare a description correctly in our guide.

Click to view sample request:
curl -X POST
‘https://api.allegro.pl/sale/product-offers’
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.beta.v2+json'
-H 'Accept-Language: en-US'
-H 'Content-Type: application/vnd.allegro.beta.v2+json'
-d ‘{
    "product": {
        "id": "5902719471797"
    },
    "name": "My own title",
    "parameters": [{
        "id": "11323",
        "valuesIds": [
            "11323_2"
        ]
    }],
    "delivery": {
        "shippingRates": {
            "id": "862347c4-b2b0-42d4-b84a-1db01509a69d"
        },
        "handlingTime": "PT48H",
        "additionalInfo": "Additional delivery information"
    },
    "sellingMode": {
        "price": {
            "amount": "220.85",
            "currency": "PLN"
        }
    },
    "afterSalesServices": {
        "impliedWarranty": {
            "name": "toys"
        },
        "returnPolicy": {
            "name": "30 days"
        }
    },
    "location": {
        "countryCode": "PL",
        "province": "LUBUSKIE",
        "city": "Gorzów Wielkopolski",
        "postCode": "66-400"
    },
    "payments": {
        "invoice": "NO_INVOICE"
    },
    "publication": {
        "status": "INACTIVE"
    },
    "images": [
        "https://...image-address.jpeg",
        "https://...image-address2.jpeg"
    ],
    "description": {
        "sections": [{
            "items": [{
                "type": "TEXT",
                "content": "<p>Sample description</p>"
            }]
        }]
    },
    "stock": {
        "available": 1
    }
}’

How to add signature

If you want to add your own item signature to your offer, extend your request with external.id field:

  ...
  "external": {
        "id": "5AA43-2020"
   }
  ...    

Click to view sample request:
curl -X POST
‘https://api.allegro.pl/sale/product-offers’
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.beta.v2+json'
-H 'Accept-Language: en-US'
-H 'Content-Type: application/vnd.allegro.beta.v2+json'
-d ‘{
    "product": {
        "id": "5902719471797"
    },
    "name": "My own title",
    "parameters": [{
        "id": "11323",
        "valuesIds": [
            "11323_2"
        ]
    }],
    "delivery": {
        "shippingRates": {
            "id": "862347c4-b2b0-42d4-b84a-1db01509a69d"
        },
        "handlingTime": "PT48H",
        "additionalInfo": "Additional delivery information"
    },
    "sellingMode": {
        "price": {
            "amount": "220.85",
            "currency": "PLN"
        }
    },
    "afterSalesServices": {
        "impliedWarranty": {
            "name": "toys"
        },
        "returnPolicy": {
            "name": "30 days"
        }
    },
    "location": {
        "countryCode": "PL",
        "province": "LUBUSKIE",
        "city": "Gorzów Wielkopolski",
        "postCode": "66-400"
    },
    "payments": {
        "invoice": "NO_INVOICE"
    },
    "publication": {
        "status": "INACTIVE"
    },
    "images": [
        "https://...image-address.jpeg",
        "https://...image-address2.jpeg"
    ],
    "description": {
        "sections": [{
            "items": [{
                "type": "TEXT",
                "content": "<p>Sample description</p>"
            }]
        }]
    },
    "stock": {
        "available": 1
    },
    "external": {
        "id": "5AA43-2020"
   }
}’

How to list an offer assigned to a product that is not in our database

If you can’t find a product in our database, you can list an offer, but you need to provide product data. Provided data will be used to submit product proposal. We will verify it - accepted details of provided product will be available to be assigned to an offer. Some data is accepted automatically, some manually - which may take some time.

To propose a product, you need the following data:

  • suggested product name
  • category
  • parameters and their values
  • photos
  • (optional) product description

Provide category and parameters

If you want to add a product in a selected category - use GET /sale/categories/{categoryId}/product-parameters to check required parameters. You can find more details about this resource in our guide. The *required field gives you information whether the parameter is required.

You can use names instead of parameters IDs. For parameters: - dictionary type - you can also provide name in the values field, - range type - you can provide two values in values field which will match “from” and “to”.

Below you can find various ways to provie parameters and their values:

 "product": {
  "category":{
         "id":"258020"
      },
  "parameters": [
      {
            "name": "Manufacturer Code",
            "values": [
                    "test 1587459230"
            ]
        },
        {
            "id": "202749",
            "values": [
                    "5.9"
            ]
        },
        {
            "id": "202869",
            "values": [
                    "512 GB"
            ]
        },
        {
            "id": "202829",
            "valuesIds": [
                    "202829_8374"
            ]
        },
        {
		"name": "Battery Capacity",
		"values": [
		         0, 100
		]
	   }
     ...
  ]
  ...    

The structure of the request at this stage may be as follows:

Click to view sample request:
curl -X POST
https://api.allegro.pl/sale/product-offers
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.beta.v2+json'
-H 'Accept-Language: en-US'
-H 'Content-Type: application/vnd.allegro.beta.v2+json'
-d ‘{
    "product": {
        "name":"Produkt testowy",
            "category":{
                    "id":"258020"
            },
              "parameters":[
            {
                "id": "224017",
                "values": [
                    "test 1587459230"
                ]
            },
            {
                "id": "202749",
                "values": [
                    "5.9"
                ]
            },
            {
                "id": "202869",
                "values": [
                    "512 GB"
                ]
            },
            {
                "id": "202829",
                "valuesIds": [
                    "202829_1"
                ]
            },
            {
                "id": "202685",
                "valuesIds": [
                    "202685_212929"
                ]
            },
            {
                "id": "127448",
                "valuesIds": [
                    "127448_2"
                ]
            },
            {
                "id": "202865",
                "valuesIds": [
                    "202865_214109"
                ]
            },
            {
                "id": "4388",
                "valuesIds": [
                    "4388_1"
                ]
            },
            {
                "id": "202717",
                "values": [
                    100
                ]
            },
            {
                "id": "219",
                "values": [
                    "Bluetooth"
                ]
            },
            {
                "id": "202821",
                "values": [
                    "Dual SIM"
                ]
            }
        ],
    },
    "sellingMode": {
        "price": {
            "amount": "220.85",
            "currency": "PLN"
        }
    },
    "stock": {
        "available": 1
    }
}’

Provide EAN as a parameter

Provide EAN as a parameter in the parameters section:

 "product": {
  "parameters": [
     {
         "name": "EAN",
         "values": [
             "0744861045021",
             "0744861045022"
         ]
     },
     ...
  ]
  ...    

The structure of the request at this stage may be as follows:

Use GET /sale/categories/{categoryId} to check value in productEANRequired field - it indicates whether EAN is required, when adding a product. productEANRequired.

Click to view sample request:
curl -X POST
‘https://api.allegro.pl/sale/product-offers’
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.beta.v2+json'
-H 'Accept-Language: en-US'
-H 'Content-Type: application/vnd.allegro.beta.v2+json'
-d ‘{
  "product": {
    "name":"Test product",
    "category":{
        "id":"258020"
     },
          "parameters":[{
                "name": "EAN",
                "values": [
                    "0744861045021"
                ]
            },
            {
                "id": "224017",
                "values": [
                    "test 1587459230"
                ]
            },
            {
                "id": "202749",
                "values": [
                    "5.9"
                ]
            },
            {
                "id": "202869",
                "values": [
                    "512 GB"
                ]
            },
            {
                "id": "202829",
                "valuesIds": [
                    "202829_1"
                ]
            },
            {
                "id": "202685",
                "valuesIds": [
                    "202685_212929"
                ]
            },
            {
                "id": "127448",
                "valuesIds": [
                    "127448_2"
                ]
            },
            {
                "id": "202865",
                "valuesIds": [
                    "202865_214109"
                ]
            },
            {
                "id": "4388",
                "valuesIds": [
                    "4388_1"
                ]
            },
            {
                "id": "202717",
                "values": [
                    100
                ]
            },
            {
                "id": "219",
                "values": [
                    "Bluetooth"
                ]
            },
            {
                "id": "202821",
                "values": [
                    "Dual SIM"
                ]
            }
        ]
},
  "sellingMode": {
    "price": {
      "amount": "220.85",
      "currency": "PLN"
    }
  },
  "stock": {
    "available": 1
  }
}’

Upload photos of the product

In the images section, add images that present the product. Images may be uploaded from external servers:

 "product": {
  ...
   "images": [
    "https://...image-address.jpeg",
    "https://...image-address2.jpeg"
   ]
  ...    

Number of photos is limited depending on the account type:

  • 16 for company account,
  • 10 for regular account.

Product photos must meet the same rules as offer photos.

The structure of the request at this stage may be as follows:

Click to view sample request:
curl -X POST
‘https://api.allegro.pl/sale/product-offers’
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.beta.v2+json'
-H 'Accept-Language: en-US'
-H 'Content-Type: application/vnd.allegro.beta.v2+json'
-d ‘{
    "product": {
        "name":"Test product",
            "category":{
                    "id":"258020"
            },
      "parameters":[{
                "name": "EAN",
                "values": [
                    "0744861045021"
                ]
            },
            {
                "id": "224017",
                "values": [
                    "test 1587459230"
                ]
            },
            {
                "id": "202749",
                "values": [
                    "5.9"
                ]
            },
            {
                "id": "202869",
                "values": [
                    "512 GB"
                ]
            },
            {
                "id": "202829",
                "valuesIds": [
                    "202829_1"
                ]
            },
            {
                "id": "202685",
                "valuesIds": [
                    "202685_212929"
                ]
            },
            {
                "id": "127448",
                "valuesIds": [
                    "127448_2"
                ]
            },
            {
                "id": "202865",
                "valuesIds": [
                    "202865_214109"
                ]
            },
            {
                "id": "4388",
                "valuesIds": [
                    "4388_1"
                ]
            },
            {
                "id": "202717",
                "values": [
                    100
                ]
            },
            {
                "id": "219",
                "values": [
                    "Bluetooth"
                ]
            },
            {
                "id": "202821",
                "values": [
                    "Dual SIM"
                ]
            }
        ],
        "images": [
            "https://...image-address.jpeg",
            "https://...image-address2.jpeg"
        ]
    },
    "sellingMode": {
        "price": {
            "amount": "220.85",
            "currency": "PLN"
        }
    },
    "stock": {
        "available": 1
    }
}'

Complete the remaining data to list an offer

To list an offer you need to complement your request with:

Click to view sample request:
curl -X POST
‘https://api.allegro.pl/sale/product-offers’
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.beta.v2+json'
-H 'Accept-Language: en-US'
-H 'Content-Type: application/vnd.allegro.beta.v2+json'
-d ‘{
   "product":{
      "name":"Test product",
      "category":{
         "id":"258020"
      },
      "parameters":[{
                "name": "EAN",
                "values": [
                    "0744861045021"
                ]
            },
            {
                "id": "224017",
                "values": [
                    "test 1587459230"
                ]
            },
            {
                "id": "202749",
                "values": [
                    "5.9"
                ]
            },
            {
                "id": "202869",
                "values": [
                    "512 GB"
                ]
            },
            {
                "id": "202829",
                "valuesIds": [
                    "202829_1"
                ]
            },
            {
                "id": "202685",
                "valuesIds": [
                    "202685_212929"
                ]
            },
            {
                "id": "127448",
                "valuesIds": [
                    "127448_2"
                ]
            },
            {
                "id": "202865",
                "valuesIds": [
                    "202865_214109"
                ]
            },
            {
                "id": "4388",
                "valuesIds": [
                    "4388_1"
                ]
            },
            {
                "id": "202717",
                "values": [
                    100
                ]
            },
            {
                "id": "219",
                "values": [
                    "Bluetooth"
                ]
            },
            {
                "id": "202821",
                "values": [
                    "Dual SIM"
                ]
            }
        ],
      "images":[   
    "https://...image-address.jpeg",
    "https://...image-address2.jpeg"
   ]
   },
"parameters":[                                                     
      {
         "id":"11323",
         "valuesIds":[
            "11323_2"
         ]
      }
   ],
   "images": ["https://test-address.com/image.jpg"],
   "sellingMode":{
      "price":{
         "amount":"12.43",
         "currency":"PLN"
      }
   },
   "stock":{
      "available": 10
   }
}

Click to view sample response:
 {
    "id": "7678581025",                                         -- offer ID
    "name": "Produkt testowy",                                  -- offer name
    "product": {
        "id": "2f771572-8302-4c09-b304-391f039e3195",           -- product ID
        "publication": {
            "status": "PROPOSED"                                -- product publication status.
                                                                Available values are: PROPOSED (we created new
                                                                product proposal and assigned it to an offer),
                                                                LISTED (we identified the product in our
                                                                database and assigned it to an offer),
                                                                NOT_LISTED (we didn’t create a new product
                                                                proposal and didn’t assign any product from our
                                                                database to an offer, but we listed an offer
                                                                itself)
        }
    },
    "afterSalesServices": {                                     -- offer terms                      
        "impliedWarranty": {                                    -- information on complaints
            "id": "1377b0a6-b397-4e1e-b57c-4234bd84d036"
        },
        "returnPolicy": {                                       -- information on return policy
            "id": "e261d4ed-ced7-4c10-82cd-13aa26192895"
        },
        "warranty": null                                        -- information on warranty
    },
    "payments": {
        "invoice": "VAT"                                        -- information about an invoice
    },
    "sellingMode": {                        
        "format": "BUY_NOW",                                    -- sales format
        "price": {                                              
            "amount": 12.43,                                    -- offer price
            "currency": "PLN"   
        },
        "startingPrice": null,
        "minimalPrice": null
    },
    "stock": {
        "available": 10,                                        -- number of available items
        "unit": "UNIT"
    },
    "location": {                                               -- parcel dispatch location
        "countryCode": "PL",
        "province": "WIELKOPOLSKIE",
        "city": "Poznań",
        "postCode": "60-166"
    },
    "delivery": {                                               -- information about delivery
        "shippingRates": {
            "id": "0ef455de-fc6e-4d6e-a7c8-c22aecf0b914"        -- shipping rate ID
        },
        "handlingTime": "PT24H",                                
        "additionalInfo": null                                  
    },
    "publication": {
        "duration": null,                                       
        "status": "ACTIVE",                                     
        "endedBy": null,
        "endingAt": null,
        "startingAt": null,
        "republish": false
    },
    "description": null,                                        
    "validation": {                                             
        "errors": [],
        "warnings": [],
        "validatedAt": "2020-09-22T11:44:17.995Z"
    },
    "createdAt": "2020-09-22T11:44:17Z",                        -- offer creation date
    "updatedAt": "2020-09-22T11:44:17.995Z",                    -- last offer update
    "images": [                                                 
        "https://a.allegroimg.pl/original/11d57d/542133b14781a17f11041d8a5ca4",
        "https://a.allegroimg.pl/original/111c5f/03c9534448d98d63bd6810a54512"
    ],
    "external": null,
    "sizeTable": {
      "id": “5727b598-6608-4bd3-b198-f165b011bb69”
    },
    "tax": {
      "percentage": “23.00”
    }                                            
}

How to edit an offer

Owing to PATCH /sale/product-offers/{offer-id} you can easily edit your offer - you can change any field of the offer, and at the same time, you don’t have to pass its entire model.

You can independently edit any field in the offer, including:

  • photos,
  • parameters,
  • location,
  • price,
  • description of the offer.
information

Note! You cannot change the product assigned to the offer (product.id field). If you pass any value or null in the product.id field - it will be ignored.

We provided the same facilities as when creating offers by POST /sale/product-offers resource, therefore PATCH /sale/product-offers/{offer-id} allows you to:

  • change the offer status without having to use a separate publication command,
  • add images to the offer directly from external server,
  • use the names of the terms of offers instead of identifiers (delivery price lists, terms of returns and complaints).

Editing an offer in the asynchronous API

async_api_edit

You will receive one of two statuses in response to a valid request to the PATCH sale/product-offers/{offerId}:

  • 200 OK - when the request relates to modification of the offer’s attributes that do not involve long-running operations. We will implement the changes immediately,

  • 202 Accepted - when the request relates to long-running operations e.g. change of the offer publication status. We will perform the change asynchronously.

When you receive status 200 OK - we will return offer data with requested changes.


Sample request:

  curl -X PATCH
  ‘https://api.allegro.pl/sale/product-offers/9531382307’
  -H 'Authorization: Bearer {token}'
  -H 'Accept: application/vnd.allegro.beta.v2+json'
  -H 'Content-Type: application/vnd.allegro.beta.v2+json'
  -d ’{
  "sellingMode": {
     "price": {
       "amount": "50",
       "currency": "PLN"
    }
  }    
  }’

Click to view sample response:
  HTTP/1.1 200 OK
  {
    "id": "9531382307’",
    "name": "Sample product",
    "product": {
        "id": null,
        "publication": {
            "status": "NOT_LISTED"
        }
    },
    "afterSalesServices": {
        "impliedWarranty": {
            "id": "f86078a6-9f42-4b76-9696-1e5c0646a60a"
        },
        "returnPolicy": {
            "id": "47101223-7236-4201-9779-316e6d10af2a"
        },
        "warranty": null
    },
    "payments": {
        "invoice": "NO_INVOICE"
    },
    "sellingMode": {
        "format": "BUY_NOW",
        "price": {
            "amount": 50,
            "currency": "PLN"
        },
        "startingPrice": null,
        "minimalPrice": null
    },
    "stock": {
        "available": 1,
        "unit": "UNIT"
    },
    "location": {
        "countryCode": "PL",
        "province": "WIELKOPOLSKIE",
        "city": "Poznań",
        "postCode": "66-166"
    },
    "delivery": {
        "shippingRates": {
            "id": "17221a3c-f4cf-4e47-953a-8e125013b014"
        },
        "handlingTime": "PT336H",
        "additionalInfo": ""
    },
    "publication": {
        "duration": null,
        "status": "ACTIVE",
        "endedBy": null,
        "endingAt": null,
        "startingAt": null,
        "republish": false
    },
    "description": {
        "sections": [
            {
                "items": [
                    {
                        "type": "TEXT",
                        "content": "<p>test</p>"
                    }
                ]
            }
        ]
    },
    "validation": {
        "errors": [],
        "warnings": [],
        "validatedAt": "2020-11-06T15:39:53.898Z"
    },
    "createdAt": "2020-10-01T05:44:23Z",
    "updatedAt": "2020-11-06T15:39:55.574Z",
    "images": [
        "https://a.allegroimg..pl/original/116421/ece7111d4b8fbbc4662ab92f84ce"
    ],
    "external": null,
    "category": {
        "id": "79419"
    },
    "tax": {
        "percentage": null
    },
    "sizeTable": null
 }

If you receive status 202 Accepted, we will return offer data with its current state - without changes. Changes in the offer will be performed asynchronously.

Use the address received in the Location header to check the task completion status. In the retry-after header, we return information on how many seconds you need to wait until you can send a request again.


Sample request:

  curl -X PATCH
  ‘https://api.allegro.pl/sale/product-offers/9531382307’
  -H 'Authorization: Bearer {token}'
  -H 'Accept: application/vnd.allegro.beta.v2+json'
  -H 'Content-Type: application/vnd.allegro.beta.v2+json'
  -d ’{
    "publication": {
         "status": "ACTIVE"
     }
  }’

Click to view sample response:
  HTTP/1.1 202 Accepted
  location: ‘https://api.allegro.pl/sale/product-offers/9531382307/sale/operations/ef5dd966-d370-44f7-bb30-3631e3511536’
  retry-after: 5
  {
    "id": "9531382307’",
    "name": "Sample product",
    "product": {
        "id": null,
        "publication": {
            "status": "NOT_LISTED"
        }
    },
    "afterSalesServices": {
        "impliedWarranty": {
            "id": "f86078a6-9f42-4b76-9696-1e5c0646a60a"
        },
        "returnPolicy": {
            "id": "47101223-7236-4201-9779-316e6d10af2a"
        },
        "warranty": null
    },
    "payments": {
        "invoice": "NO_INVOICE"
    },
    "sellingMode": {
        "format": "BUY_NOW",
        "price": {
            "amount": 50,
            "currency": "PLN"
        },
        "startingPrice": null,
        "minimalPrice": null
    },
    "stock": {
        "available": 1,
        "unit": "UNIT"
    },
    "location": {
        "countryCode": "PL",
        "province": "WIELKOPOLSKIE",
        "city": "Poznań",
        "postCode": "66-166"
    },
    "delivery": {
        "shippingRates": {
            "id": "17221a3c-f4cf-4e47-953a-8e125013b014"
        },
        "handlingTime": "PT336H",
        "additionalInfo": ""
    },
    "publication": {
        "duration": null,
        "status": "ENDED",
        "endedBy": "USER",
        "endingAt": null,
        "startingAt": null,
        "republish": false
    },
    "description": {
        "sections": [
            {
                "items": [
                    {
                        "type": "TEXT",
                        "content": "<p>test</p>"
                    }
                ]
            }
        ]
    },
    "validation": {
        "errors": [],
        "warnings": [],
        "validatedAt": "2020-11-06T15:39:53.898Z"
    },
    "createdAt": "2020-10-01T05:44:23Z",
    "updatedAt": "2020-11-06T15:42:06.315Z",
    "images": [
        "https://a.allegroimg.pl/original/116421/ece7111d4b8fbbc4662ab92f84ce"
    ],
    "external": null,
    "category": {
        "id": "79419"
    },
    "tax": {
        "percentage": null
    },
    "sizeTable": null
 }

Use the GET method on the address received in the Location header to check the task completion status. Until the operation is completed, in response to this request, we will return status 202 Accepted.

Sample request:

  curl -X GET
  ‘https://api.allegro.pl/sale/product-offers/9531382307/operations/ef5dd966-d370-44f7-bb30-3631e3511536’
  -H 'Authorization: Bearer {token}'
  -H 'Accept: application/vnd.allegro.beta.v2+json'
  -H 'Content-Type: application/vnd.allegro.beta.v2+json'

Sample response:

HTTP/1.1 202 Accepted
location: https://api.allegro.pl/sale/product-offers/9531382307/operations/ef5dd966-d370-44f7-bb30-3631e3511536
retry-after: 5
 {
  "offer": {
    "id": "9531382307"
  },
  "operation": {
    "id": "ef5dd966-d370-44f7-bb30-3631e3511536",
    "status": "IN_PROGRESS",
    "startedAt": "2019-05-29T12:00:00Z"
  }
}

When we finish processing the operation, we will return HTTP status 303 See Other in the response to GET /sale/product-offers/{offerId}/operations/{operationId}. In the Location header, you will receive a link to the offer data.


Sample request:

  curl -X GET
  ‘https://api.allegro.pl/sale/product-offers/9531382307/operations/ef5dd966-d370-44f7-bb30-3631e3511536’
  -H 'Authorization: Bearer {token}'
  -H 'Accept: application/vnd.allegro.beta.v2+json'
  -H 'Content-Type: application/vnd.allegro.beta.v2+json'

Sample response:

  HTTP/1.1 303 See Other
  location: https://api.allegro.pl/sale/product-offers/9531382307

Now you can use the GET method on this link to retrieve the current offer data.


Sample request:

  curl -X GET
  ‘https://api.allegro.pl/sale/product-offers/9531382307’
  -H 'Authorization: Bearer {token}'
  -H 'Accept: application/vnd.allegro.beta.v2+json'
  -H 'Content-Type: application/vnd.allegro.beta.v2+json

Click to view sample response:
'{
    "id": "9531382307",
    "name": "Sample product",
    "product": {
        "id": "21a0e252-aa3f-4666-9278-b0417743790f",
        "publication": {
            "status": "LISTED"
        }
    },
    "afterSalesServices": {
        "impliedWarranty": {
            "id": "ad2a9867-71b1-499b-8211-0048536992c5"
        },
        "returnPolicy": {
            "id": "b20a9525-f431-495f-96a8-45af3255374f"
        },
        "warranty": {
            "id": "74cf0d61-590d-4235-8229-8f0d7e7c54e3"
        }
    },
    "payments": {
        "invoice": "VAT"
    },
    "sellingMode": {
        "format": "BUY_NOW",
        "price": {
            "amount": 50,
            "currency": "PLN"
        },
        "startingPrice": null,
        "minimalPrice": null
    },
    "stock": {
        "available": 2,
        "unit": "UNIT"
    },
    "location": {
        "countryCode": "PL",
        "province": "WIELKOPOLSKIE",
        "city": "Poznań",
        "postCode": "60-130"
    },
    "delivery": {
        "shippingRates": {
            "id": "04624cf1-558f-4356-bf2b-1fa34a091ca3"
        },
        "handlingTime": "PT168H",
        "additionalInfo": ""
    },
    "publication": {
        "duration": "PT240H",
        "status": "ACTIVE",
        "endedBy": null,
        "endingAt": "2020-10-04T12:13:20Z",
        "startingAt": null,
        "republish": false
    },
    "description": {
        "sections": [
            {
                "items": [
                    {
                        "type": "TEXT",
                        "content": "<p>testowy opis</p>"
                    }
                ]
            },
            {
                "items": [
                    {
                        "type": "TEXT",
                        "content": "<p>testowy opis</p>"
                    }
                ]
            }
        ]
    },
    "validation": {
        "errors": [],
        "warnings": [],
        "validatedAt": "2020-09-28T08:22:34.223Z"
    },
    "createdAt": "2020-07-24T13:50:33Z",
    "updatedAt": "2020-09-28T08:22:35.851Z",
    "images": [
        "https://c.allegroimg.com/original/0587c4/1a7a1b46438da3de2cf8a328791a",
        "https://c.allegroimg.com/original/0587c4/1a7a1b46438da3de2cf8a328791b"
    ],
    "external": null,
    "category": {
        "id": "260395"
    },
    "sizeTable": {
      "id": “5727b598-6608-4bd3-b198-f165b011bb69”
    },
    "tax": null
}'

Editing offer fields

Use PATCH /sale/product-offers/{offer-id} and pass in the request payload only those fields that you want to change. We will leave the current value in the remaining fields. Resource is compliant with RFC7396.

Here are some sample requests:

  • change price:

Sample request:

curl -X PATCH
‘https://api.allegro.pl/sale/product-offers/9531382307’
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.beta.v2+json'
-H 'Content-Type: application/vnd.allegro.beta.v2+json'
-d ’{
"sellingMode": {
   "price": {
     "amount": "50",
     “currency”: “PLN”
  }
}    
}’

  • change location:

Sample request:

curl -X PATCH
‘https://api.allegro.pl/sale/product-offers/9531382307’
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.beta.v2+json'
-H 'Content-Type: application/vnd.allegro.beta.v2+json'
-d ‘{
      "location": {
    	"countryCode": "PL",
     	"province": "WIELKOPOLSKIE",
     	"city": "Poznań",
     	"postCode": "60-166"
  }
}’

  • change stock:

Sample request:

curl -X PATCH
‘https://api.allegro.pl/sale/product-offers/9531382307’
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.beta.v2+json'
-H 'Content-Type: application/vnd.allegro.beta.v2+json'
-d ‘{
   "stock": {
       "available": 2,
       "unit": "UNIT"
   }
}’

information

Note! For arrays such as images and offer description, we are on an all-or-nothing basis (in compliance with the guidelines in RFC7396). This means that, for example, if you want to add new photos to the offer, but at the same time you want to keep those that were added previously - you have to add both new photos and those that were already in the images array.

Sample request:

curl -X PATCH
‘https://api.allegro.pl/sale/product-offers/9531382307’
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.beta.v2+json'
-H 'Content-Type: application/vnd.allegro.beta.v2+json'
-d ‘{
   "images": [
       "https://c.allegroimg.com/original/0587c4/1a7a1b46438da3de2cf8a328791a",
       "https://c.allegroimg.com/original/0587c4/1a7a1b46438da3de2cf8a328791b"
   ]
}’

Click to view sample response:
'{
    "id": "9531382307",
    "name": "Książka",
    "product": {
        "id": "21a0e252-aa3f-4666-9278-b0417743790f",
        "publication": {
            "status": "LISTED"
        }
    },
    "afterSalesServices": {
        "impliedWarranty": {
            "id": "ad2a9867-71b1-499b-8211-0048536992c5"
        },
        "returnPolicy": {
            "id": "b20a9525-f431-495f-96a8-45af3255374f"
        },
        "warranty": {
            "id": "74cf0d61-590d-4235-8229-8f0d7e7c54e3"
        }
    },
    "payments": {
        "invoice": "VAT"
    },
    "sellingMode": {
        "format": "BUY_NOW",
        "price": {
            "amount": 50,
            "currency": "PLN"
        },
        "startingPrice": null,
        "minimalPrice": null
    },
    "stock": {
        "available": 2,
        "unit": "UNIT"
    },
    "location": {
        "countryCode": "PL",
        "province": "WIELKOPOLSKIE",
        "city": "Poznań",
        "postCode": "60-130"
    },
    "delivery": {
        "shippingRates": {
            "id": "04624cf1-558f-4356-bf2b-1fa34a091ca3"
        },
        "handlingTime": "PT168H",
        "additionalInfo": ""
    },
    "publication": {
        "duration": "PT240H",
        "status": "ACTIVE",
        "endedBy": null,
        "endingAt": "2020-10-04T12:13:20Z",
        "startingAt": null,
        "republish": false
    },
    "description": {
        "sections": [
            {
                "items": [
                    {
                        "type": "TEXT",
                        "content": "<p>test description</p>"
                    }
                ]
            },
            {
                "items": [
                    {
                        "type": "TEXT",
                        "content": "<p>test description</p>"
                    }
                ]
            }
        ]
    },
    "validation": {
        "errors": [],
        "warnings": [],
        "validatedAt": "2020-09-28T08:22:34.223Z"
    },
    "createdAt": "2020-07-24T13:50:33Z",
    "updatedAt": "2020-09-28T08:22:35.851Z",
    "images": [
        "https://c.allegroimg.com/original/0587c4/1a7a1b46438da3de2cf8a328791a",
        "https://c.allegroimg.com/original/0587c4/1a7a1b46438da3de2cf8a328791b"
    ],
    "external": null,
    "category": {
        "id": "260395"
    },
    "sizeTable": {
      "id": “5727b598-6608-4bd3-b198-f165b011bb69”
    },
    "tax": null
}'


If you want to delete the value in the selected field (unless field is required) - pass null value.

Sample request:

curl -X PATCH
‘https://api.allegro.pl/sale/product-offers/9531382307’
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.beta.v2+json'
-H 'Content-Type: application/vnd.allegro.beta.v2+json'
-d ‘{
      "warranty": {
            "id": null
     }
}’

Offer status change

Owing to PATCH /sale/product-offers/{offer-id} you can also change the offer status - as a separate operation or in one operation, with the offer edition. You do not need to use the additional resource to publish an offer. All you need to do is to pass appropriate value in the field publication.status:

  • ACTIVE - to activate the offer,
  • ENDED - to end the offer.

Sample request:

curl -X PATCH
‘https://api.allegro.pl/sale/product-offers/9531382307’
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.beta.v2+json'
-H 'Content-Type: application/vnd.allegro.beta.v2+json'
-d ’{
  "sellingMode": {
     "price": {
      "amount": "101",
      "currency": "PLN"
    }
  },
  "publication": {
        "status": "ENDED"
    }
}’

When the offer has ended due to out of stock (stock dropped to 0 as a result of sale), and the status value is ENDED, then if you will change the offer using PATCH /sale/product-offers/{offer-id} and pass stock greater than 0 (stock > 0) - the offer will be activated again.

information

Note! If you include the value ENDED in the status field in the request payload, we will end the offer, even if editing other fields fails.

If an offer is INACTIVE status, and if you want to activate this offer, you need to pass the ACTIVE value in the field publication.status.

Sample request:

curl -X PATCH
‘https://api.allegro.pl/sale/product-offers/9531382307’
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.beta.v2+json'
-H 'Content-Type: application/vnd.allegro.beta.v2+json'
-d ‘{
  "publication": {
        "status": "ACTIVE"
    }
}’