How to submit offers to campaigns
Processing offers submitted to campaigns, special programs and Allegro badges
To take part in a campaign, you have to meet the requirements, and accept terms and conditions. By using API resources, you agree to comply with and be legally bound by the terms and conditions.
You can submit your offers to be part of a campaign. After verification, we will mark the offers with special badges. For example, if you add an offer to the following campaign:
“Hit” – your offer will be marked with the HIT badge displayed on the list of offers as well as offer page.
“Deal Zone” – your offer will be marked with the Deal badge displayed on the list of offers along with a crossed out price.
“0.5% commission fee” – the offer price will be replaced with the one provided in your application. Moreover, you will be entitled to bonuses arising out of the terms and conditions of the given campaign, e.g. lower success fee.
To learn more about campaigns, read Deal Zone and Commission fee up to 0.5%.
We have introduced resources for processing offers submitted to campaigns, special programs and Allegro badges:
GET /sale/badge-campaigns - retrieve a list of available campaigns,
POST /sale/badges - submit an offer to get a badge,
GET /sale/badge-applications/{applicationId} - retrieve a particular application,
GET /sale/badge-applications - retrieve your applications,
GET /sale/badges - retrieve campaigns and badges assigned to offers.
You must be logged on as a seller to submit the offers.
Submitting offers to campaigns, special programs and Allegro badges
1. List of available campaigns
Use GET /sale/badge-campaigns to retrieve a list of available campaigns.
Sample request:
curl -X GET
‘https://api.allegro.pl/sale/badge-campaigns’
-H ‘Authorization: Bearer {token}’
-H ‘Content-Type: application/vnd.allegro.beta.v1+json’
Sample response:
{
“badgeCampaigns”: [
{
“id”: “BARGAIN”, – campaign ID
“name”: “Strefa okazji”, – campaign name
“type”: “DISCOUNT”, – campaign type; three types are supported
STANDARD – adding a badge (e.g. Hit or New)
displayed on the list of offers
DISCOUNT – we will change the offer price,
and display on the list of offers crossed
out market price you provided in the application
SOURCING – we will change the price, but
no badge will be added; however,
you will be entitled to bonuses arising
out of terms and conditions of
the given campaign, e.g. lower success fee.
“eligibility”: { – is the campaign available for the given user
“eligible”: true,
“refusalReasons”: [] – campaign requirements the user does not meet
},
“application”: { – period for submitting offers
“type”: “ALWAYS”, – duration time; 5 values are supported, i.e.
ALWAYS, SINCE (as of particular day),
UNTIL (until a particular day), WITHIN (period),
NEVER
“from”: null,
“to”: null
},
“publication”: { – badge duration time
“type”: “ALWAYS”, – duration time; 5 values are supported, i.e.
ALWAYS, SINCE (as of particular day),
UNTIL (until a particular day), WITHIN (period),
NEVER
“from”: null,
“to”: null
},
“visibility”: { – time during which the campaign is displayed by
campaign management tools (it is not equal to
the display time of campaign badge).
These ranges help verify how long information
about a particular campaign will
be available on the platform.
“type”: “ALWAYS”, – duration time; 5 values are supported, i.e.
ALWAYS, SINCE (as of particular day),
UNTIL (until a particular day), WITHIN (period),
NEVER
“from”: null,
“to”: null
},
“regulationsLink”: “https://na.allegro.pl/regulamin-kampania-BARGAIN" – link to campaign regulations
},
…
]
}
2. Submit offer to a campaign
Use to POST /sale/badges submit your offer to a particular campaign.
Applications that do not meet campaign requirements will be rejected.
Sample request:
curl -X POST
‘https://api.allegro.pl/sale/badges’
-H ‘Authorization: Bearer {token}’
-H ‘Content-Type: application/vnd.allegro.beta.v1+json’
-d ‘{
“campaign”: {
“id”: “BARGAIN” – required; ID of a campaign you want to
assign to the offer – according to
GET /sale/badge-campaigns
},
“offer”: {
“id”: “6206378062” – required; ID of an offer you want
to add to the campaign
},
“prices”: { – required in the case of DISCOUNT and
SOURCING campaigns; information about
a price to be displayed, and the market price
“market”: { – required in the case of DISCOUNT campaign;
product’s market price that will be crossed
out on the list of offers
“amount”: “200.00”,
“currency”: “PLN”
},
“bargain”: { – required in the case of DISCOUNT and
SOURCING campaigns; promotional price
“amount”: “180.00”,
“currency”: “PLN”
}
},
“purchaseConstraints”: { – optional - constraints on purchases
of this offer while it participates
in the campaign
“limit”: {
“perUser”: {
“maxItems”: 1 – limit of items of the offer that
one user can buy, while offer participates
in the campaign
}
}
}
}’
Sample response:
{
“id”: “8a457b8f-627d-43cf-8806-f06f8d13c306”, – ID of the offer application
“createdAt”: “2019-06-26T10:22:35.225Z”, – application creation data
“updatedAt”: “2019-06-26T10:22:35.225Z”, – recent application update
“campaign”: {
“id”: “BARGAIN” – campaign ID
},
“offer”: {
“id”: “6206378062” – ID of the offer you want to assign
to the campaign
},
“prices”: { – information about a price to be displayed,
and the market price
“bargain”: { – offer’s promotional price
“amount”: “180.00”,
“currency”: “PLN”
},
“market”: { – product’s market price that
will be crossed out on the list of offers
“amount”: “200.00”,
“currency”: “PLN”
}
},
“purchaseConstraints”: { – optional - constraints on purchases
of this offer while it participates
in the campaign
“limit”: {
“perUser”: {
“maxItems”: “1” – limit of items of the offer that
one user can buy, while offer participates
in the campaign
}
}
},
“process”: {
“status”: “REQUESTED”, – application status; three values are supported:
REQUESTED (application is waiting for processing),
PROCESSED (the application has been processed - from
this moment you can check the status assigned to the
offer badge by calling GET sale/badges),
DECLINED (application was rejected)
“rejectionReasons”: [] – reason for rejecting the application
}}
3. Retrieve campaign application
Use GET /sale/badge-applications/{applicationId} to retrieve campaign applications and check their status.
Sample request:
curl -X GET
‘https://api.allegro.pl/sale/badge-applications/8a457b8f-627d-43cf-8806-f06f8d13c306’
-H ‘Authorization: Bearer {token}’
-H ‘Content-Type: application/vnd.allegro.beta.v1+json’
Sample response:
{
“id”: “8a457b8f-627d-43cf-8806-f06f8d13c306”, – ID of the offer application
“createdAt”: “2019-06-26T10:22:35.225Z”, – application creation date
“updatedAt”: “2019-06-26T10:22:35.225Z”, – recent application update
“campaign”: {
“id”: “BARGAIN” – campaign ID
},
“offer”: {
“id”: “6206378062” – ID of the offer you want to assign
to the campaign
},
“prices”: { – information about a price to be displayed,
and the market price
“bargain”: { – offer’s promotional price
“amount”: “180.00”,
“currency”: “PLN”
},
“market”: { – product’s market price that will be
crossed out on the list of offers
“amount”: “200.00”,
“currency”: “USD”
}
“process”: {
“status”: “DECLINED”, – application status; three values are supported:
REQUESTED (application is waiting for processing),
PROCESSED (the application has been processed - from
this moment you can check the status assigned to the
offer badge by calling GET sale/badges),
DECLINED (application was rejected)
“rejectionReasons”: [ – information on rejection reasons
{
“code”: “BB5”, – reason for rejecting the application
“messages”: [
{
“text”: “Currency is not equal to ‘PLN’”
“link”: null
}
]
}
]
}
}
4. Retrieve all campaign applications
Use to GET /sale/badge-applications to retrieve all campaign applications.
When submitting the requests, you need to provide one of the parameters:
- campaign.id - campaign ID,
- offer.id - offer ID.
To adjust the search list to your needs, use the following parameters:
limit to define a number of offers on a list (values from 1 to 50),
offset to define a starting point for retrieving another batch of data (0 by default).
Sample request:
curl -X GET
‘https://api.allegro.pl/sale/badge-applications?campaign.id=BARGAIN’
-H ‘Authorization: Bearer {token}’
-H ‘Content-Type: application/vnd.allegro.beta.v1+json’
Sample response:
{
“badgeApplications”: [ – list of offer application to a particular campaign
{
“id”: “8a457b8f-627d-43cf-8806-f06f8d13c306”,
“createdAt”: “2019-06-26T10:22:35.225Z”,
“updatedAt”: “2019-06-26T10:22:35.225Z”,
“campaign”: {
“id”: “BARGAIN”
},
“offer”: {
“id”: “6206378062”
},
“prices”: {
“bargain”: {
“amount”: “180.00”,
“currency”: “PLN”
},
“market”: {
“amount”: “200.00”,
“currency”: “PLN”
}
},
“process”: {
“status”: “DECLINED”,
“rejectionReasons”: [
{
“code”: “BA1”,
“messages”: [
{
“text”: “Badge already exists”
},
{
“text”: “check terms & conditions”,
“link”: “http://allegro.pl/xyz"
}
]
}
]
}
}
]
}
5. Check badges assigned to offers
Use GET /sale/badges to check badges assigned to offers.
To adjust the search list to your needs, use the following parameters:
limit to define a number of offers on a list (values from 1 to 50),
offset to define a starting point for retrieving another batch of data (0 by default).
You can use this resource to check badges assigned to a particular offer, call GET /sale/badges?offer.id={offerId}.
Sample request:
curl -X GET
‘https://api.allegro.pl/sale/badges’
-H ‘Authorization: Bearer {token}’
-H ‘Content-Type: application/vnd.allegro.beta.v1+json’
Sample response:
{
“badges”: [
{
“offer”: {
“id”: “6206378062”
},
“campaign”: {
“id”: “BARGAIN”,
“name”: “Strefa okazji”
},
“publication”: {
“type”: “ALWAYS”
},
“prices”: { – price information regarding the offered item, returned
only for campaigns requiring the market price to be
provided at the application stage
“market”: {
“amount”: “19.99”,
“currency”: “PLN”
},
"subsidy": {
"sellerPrice": { -- The amount that is expected by the partner
for the sale of the product. The difference between the amount paid
by the customer (targetPrice), and the amount expected by the partner
(sellerPrice) will be funded by Allegro
as part of the Allegro Prices program
"amount": "39.99",
"currency": "PLN"
},
"targetPrice": { -- price visible to the customer at the platform
"amount": "32.99",
"currency": "PLN"
}
}
},
“process”: {
“status”: “ACTIVE”, – badge status; supported values:
IN_VERIFICATION (application is being verified),
WAITING_FOR_PUBLICATION (badge is being published),
ACTIVE (badge is active and displayed),
FINISHED (offer duration expired within campaign;
the administrator closed the offer within the campaign),
DECLINED (badge has been rejected
and will not be published)
“rejectionReasons”: []
}
}
]
}
6. Campaigns on test environment
On the test environment, we have configured the ’SANDBOX_TEST_CAMPAIGN’ campaign, so you can test the process by yourself.
Badge submitted to this campaign with a discount range between 40% - 60% from crossed out price is automatically accepted.
Badge submitted to this campaign with a discount range outside 40% - 60% from crossed out price is automatically declined.
Offers submitted to other campaigns on the test environment will remain on the IN_VERIFICATION (application is being verified) status.
7. Errors and reasons for rejection
List of reasons for rejecting an application.
Error Code | Polish | English |
---|---|---|
BB1 | Konto nie spełnia kryteriów jakościowych. | Account does not meet the quality criteria. |
BB2 | Konto nie jest Kontem Firma. | Account is not a Company account type. |
BB3 | Brak pola campaign.id. | Empty campaign.id field. |
BB4 | Brak pola offer.id. | Empty offer.id field. |
BB5 | Waluta nie jest równa [PLN]. | Currency is not equal to [PLN]. |
BB6 | Jedna z wartości liczbowych nie jest liczbą. | One of the numeric values is not a valid number. |
BB7 | Jedna z wartości liczbowych jest liczbą mniejszą od 1. | One of the numeric values is less than 1. |
BB8 | Zgłoszenie nie istnieje. | Application not found. |
BB9 | Nieprawidłowa wartość parametru [limit]. | Invalid [limit] parameter value. |
BB10 | Nieprawidłowa wartość parametru [offset]. | Invalid [offset] parameter value. |
BB11 | Identyfikator oferty ma nieprawidłową wartość. | Offer id is not valid. |
BB12 | Zgłoszenie już istnieje. | Application already exists. |
BB13 | Zbyt dużo żądań dla tego konta. | Too many requests from this account. |
BA1 | Oznaczenie już istnieje. | Badge already exists. |
BA2 | Cena zniżkowa lub sugerowana cena rynkowa nie są zdefiniowane. | Bargain price or suggested market price are not defined. |
BA3 | Cena zniżkowa i cena rynkowa nie powinny być zdefiniowane. | Bargain price and suggested market price should not be defined. |
BA4 | Oferta nie istnieje. | Offer not found. |
BA5 | Aktualna cena oferty jest wyższa od sugerowanej ceny rynkowej. | Current offer price is higher than suggested market price. |
BA6 | Oferta została zakończona. | Offer has ended. |
BA7 | Konto nie istnieje. | Account not found. |
BA8 | W trakcie przetwarzania konto przestało być Kontem Firma. | Account is no longer a Company account type. |
BA9 | Konto nie jest właścicielem oferty. | This account is not the owner of the offer. |
BA10 | Kampania nie istnieje. | Campaign not found. |
BA11 | Kampania została zakończona. | Campaign has ended. |
BA12 | Cena zniżkowa jest wyższa od aktualnej ceny oferty. | Bargain price is higher than current offer price. |
BA13 | Cena zniżkowa jest równa sugerowanej cenie rynkowej. | Bargain price is the same as suggested market price. |
BA14 | Cena zniżkowa jest taka sama lub wyższa od sugerowanej ceny rynkowej. | Bargain price is the same or higher than suggested market price. |
BA15 | Oznaczenie zostało już zaakceptowane. | Badge has already been accepted. |
BA16 | Zniżka musi wynosić co najmniej 1% w stosunku do sugerowanej ceny rynkowej. | Discount must be greater or equal to 1% to the suggested market price. |
BA17 | Oferta ma za mało sztuk. | Offer has not enough items. |
BA18 | Oferta jest mało atrakcyjna. | Offer is not attractive enough. |
BA19 | Opis lub tytuł nie spełnia wymagań. | Offer’s title or description does not meet requirements. |
BA20 | Miniaturka nie spełnia wymagań. | Offer’s thumbnail does not meet requirements. |
BA21 | Produkt w tej lub niższej cenie jest na innym Twoim koncie. | Product with equal or lower price exists in your another account. |
BA22 | Konto nie spełnia kryteriów - minimum 98% pozytywnych ocen z 3 ostatnich miesięcy. | Account does not meet the criteria - minimum 98% positive rates from last 3 months. |
BA24 | Oferta posiada już inne oznaczenie obniżające cenę. | A discount badge for this offer already exists. |
BA25 | Wymagany kontakt z zespołem Strefy okazji pod adresem [strefaokazji@allegro.pl]. | Contact required with Strefa okazji team at [strefaokazji@allegro.pl]. |
BA26 | Oferta nie spełnia kryteriów danego oznaczenia. | Offer does not meet requirements for this badge. |
BA27 | Brak odpowiedniej metody dostawy. | No suitable delivery method. |
BA28 | Oferta nie spełnia kryteriów udziału w programie. | Offer does not meet requirements for this program. |
BA29 | Proponowana cena zniżkowa oferty jest niepoprawna. Właściwa cena maksymalna znajduje się liście produktów dla tej kampanii. | The proposed bargain price is incorrect. The maximum price is on the list of products for this campaign. |
BA30 | Oferta posiada niepoprawny kod EAN. Właściwy kod EAN znajdziesz na liście produktów dla tej kampanii. | The offer has an incorrect EAN code. You can find the correct EAN code on the list of products for this campaign. |
BA31 | Oferta nie ma uzupełnionego kodu EAN. Właściwy kod EAN znajdziesz na liście produktów dla tej kampanii. | The offer does not have EAN code. You can find the correct EAN code on the list of products for this campaign. |
BA32 | Oferta jest wystawiona w złej kategorii. | Offer was published in wrong category. |
BA33 | Proponowana cena zniżkowa oferty jest niepoprawna. Właściwa cena maksymalna znajduje się liście produktów dla tej kampanii. | The proposed bargain price is incorrect. The maximum price is on the list of products for this campaign. |
BA34 | Zgłoszenie nie zawiera informacji na temat ceny zniżkowej. | The application does not contain information about bargain price. |
BA35 | Oferta tego produktu nie posiada wystarczającej liczby sztuk, która jest określona na liście produktów dla tej kampanii. | The offer of this product does not have required quantity of items which is specified on the list of product for this campaign. |
BA36 | Sugerowana cena rynkowa nie może być zdefiniowana dla kampanii tego typu. | Suggested market price must not be defined in this campaign type. |
BA37 | Nie możemy obliczyć średniej ceny sprzedaży dla tej oferty. Brak wystarczającej liczby zakupów w ofercie. | Average selling price cannot be calculated for this offer. There is insufficient number of purchases. |
BA38 | W tej kampani wymagamy odpowiedniej obniżki w stosunku do średniej ceny sprzedaży oferty. Podana cena zniżkowa w kampanii jest za wysoka. | Given bargain price is too high. Campaign requires corresponding price reduction from offer’s average selling price. |
BA39 | W tej kampani wymagamy odpowiedniej obniżki w stosunku do ceny oferty. Podana cena zniżkowa w kampanii jest za wysoka. | Given bargain price is too high. Campaign requires corresponding price reduction from offer’s base price. |
BA40 | Wprowadzona sugerowana cena rynkowa jest zawyżona. Podana cena nie może być wyższa niż średnia cena sprzedaży oferty. | Given market price is too high. Campaign requires corresponding price reduction from offer’s average selling price. |
BA41 | Wprowadzona sugerowana cena rynkowa jest zawyżona. Podana cena nie może być wyższa niż cena sprzedaży oferty. | Given market price is too high. Campaign requires corresponding price reduction from offer’s base price. |
BA42 | Oferta nie ma oznaczenia [Smart!]. W kampanii mogą brać udział tylko oferty z tym oznaczeniem. | Offer does not meet requirements of [Smart!] program. Only offers meeting [Smart!] criteria can participate in this campaign. |
BA43 | Wartość parametru [Stan] w ofercie jest inna niż [Nowy]. | Offer’s parameter [Condition] is different than [New]. |
BA44 | Konto nie spełnia wymaganych kryteriów jakościowych. | Account does not meet the required quality criteria. |
BA45 | Limit zgłoszeń dla tej oferty został przekroczony. Ponowne zgłoszenie do tej kampanii będzie możliwe za 24 godziny. | The limit of applications for this offer has been exceeded. You can re-apply to this campaign after 24 hours. |
BA46 | Oferta jest wystawiona w kategorii, która nie spełnia kryteriów kampanii. | The offer is listed in a category that does not meet the criteria of the campaign. |
BA47 | Oferta nie spełnia kryteriów kampanii. Została wystawiona więcej niż 6 miesięcy temu. | The offer does not meet the criteria of the campaign. It was listed more than 6 months ago. |
BA48 | Oferta nie spełnia kryteriów kampanii. Oferta nie jest opublikowana. | The offer does not meet the criteria of the campaign. It has not been published. |
BA49 | W tej kampanii wymagamy odpowiedniej obniżki w stosunku do sugerowanej ceny rynkowej oferty. Proponowana obniżka ceny jest za niska. | Given bargain discount is too low. Campaign requires corresponding price reduction from offer’s suggested market price. |
BA50 | W tej kampanii wymagamy odpowiedniej obniżki w stosunku do sugerowanej ceny rynkowej oferty. Proponowana obniżka ceny jest zbyt wysoka. | Given bargain discount is too high. Campaign requires corresponding price reduction from offer’s suggested market price. |
BA51 | Oferta jest zarchiwizowana. | Offer is archived. |
BA52 | Oferta jest nieaktywna. | Offer is inactive. |
BA53 | Liczba sprzedanych sztuk przedmiotów na ofercie przez ostatnie 30 dni jest niewystarczająca. | The number of offer items sold over the last 30 days is insufficient. |
BA54 | Twój produkt znajduje się na liście produktów objętych akcją promocyjną innej aktywnej kampanii. | Your product is included in the promotional campaign list of another active campaign. |
BA57 | Oferta przestała być atrakcyjna cenowo względem cen rynkowych i cen w serwisie Allegro.pl. | The offer price is not attractive enough compared to the market and Allegro Prices. |
BA58 | Wymagane jest powiązanie oferty z produktem. | It is required to link the offer with a product. |
BB0 | Wystąpił błąd podczas przetwarzania zgłoszenia. Prosimy spróbować ponownie później. | Error occurred during application processing. Please try again later. |
8. List of resources
You will find full documentation of resources in the swagger.yaml form file here.
List of basic resources used in tutorial:
- GET /sale/badge-campaigns - retrieve a list of available campaigns
- POST /sale/badges - submit an offer to a particular campaign
- GET /sale/badge-applications/{applicationId} - retrieve campaign application details
List of supporting resources used in tutorial:
- GET /sale/badges - retrieve campaigns and badges assigned to offers
- GET /sale/badge-applications - retrieve all campaign applications