How to submit offers to campaigns

Processing offers submitted to campaigns, special programs and Allegro badges

information

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:

information

You must be logged on as a seller to submit the offers.

Submitting offers to campaigns, special programs and Allegro badges

badge

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.

information

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.

information

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

information

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.

information

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:

List of supporting resources used in tutorial: