Listing offers through Allegro REST API

Offer model

1. Prepare a draft

Use POST /sale/offers to create offer drafts. The draft does not have to be a complete ready-to-publish offer. You can finish it up later. You can complete the draft with more information by using PUT/sale/offers/{offerId}. Use the drafts to::

  • store the offer data on our servers,

  • prepare an offer preview.


2. List an offer

You can activate a complete draft (with an INACTIVE status) if no errors are displayed in the “validation” section. The offer is validated every time you edit it. If you send changes that contain:

  • incorrect data, identifier, etc. – status 422 will be returned,
  • logic errors that block the listing process, e.g. missing reserve price in the case of an auction – a proper error message will be displayed in the “validation” section.

If there are no errors, you can publish the draft on Allegro.pl. To activate the draft, perform ACTIVATE on PUT /sale/offer-publication-commands/{commandId}. Until your offer is published on Allegro, it will have an ACTIVATING status. The same status is applied to offers with a scheduled listing date.


3. Check an offer status

Once the offer is listed, its status will be changed to ACTIVE. The exact listing date is displayed in the scheduledAt field, use the GET /sale/offer-publication-commands/{commandId}/tasks command to bring it up. Use the same method to close an offer by performing the END command.

List an offer in a few steps

Note! All requests must be executed with an OAuth 2.0 token

Add the following elements:

Offer terms - Describe terms of the returns policy, complaints policy and warranty information. The policy of returns and complaints is required for company accounts. If you change the offer terms, these changes will be instantly visible in offers to which you assigned them.

Size tables - buyers can find size information always in the same format and section of the offer page. You can create Size tables in the Tabele rozmiarów tab, in My Allegro.

1. Required data

Use supportive methods to retrieve the ID of elements, which you can later transfer and build a new offer, e.g.:

Delivery settings

Retrieve it via: GET /sale/delivery-settings.

Sample request:

  curl -X GET
  https://api.allegro.pl/sale/delivery-settings
  -H 'Authorization: Bearer {token}'
  -H 'Accept: application/vnd.allegro.public.v1+json'
  -H 'Content-Type: application/vnd.allegro.public.v1+json'
Sample response:
  {
  	"freeDelivery": {
    	"amount": 4.04,				-- minimum total order
        "currency": "PLN"           amount required for free delivery
   	},
   	"joinPolicy": {
    	"strategy": "MAX"			-- policy of calculating delivery costs
    },
	"customCost": {
    	"allowed": true				-- whether the custom delivery cost
                                    should be available
   },
   "updatedAt": "2019-08-21T10:13:40.036Z"
  }

You can edit delivery settings via the PUT /sale/delivery-settings. You will find more information about new resources in our documentation.

Shipping price list

Use GET /sale/delivery-methods to retrieve IDs and names of delivery options offered by Allegro. Use them to create a new shipping price list.

Sample request

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

Click to view sample response:
{

  "deliveryMethods": [
    {
        "id": "7203cb90-864c-4cda-bf08-dc883f0c78ad",   -- general shipping method ID
        "name": "Przesyłka kurierska",                  -- general shipping method name
        "paymentPolicy": "IN_ADVANCE",                  -- payment policy, two values are
                                                        supported: IN_ADVANCE and
                                                        CASH_ON_DELIVERY
        "allegroEndorsed": false,                       -- Allegro signed delivery, this field
                                                        allows you to distinguish similar
                                                        delivery methods with various restrictions,
                                                        e.g. Allegro Paczkomaty 24/7 InPost from Paczkomaty 24/7
        "shippingRatesConstraints": {
            "allowed": true,                            -- if delivery method can be used
                                                        when adding or modifying shipping rates
            "maxQuantityPerPackage": {                  -- rules for the quantity per parcel
                "max": 999999
            },
            "firstItemRate": {                          -- rules for the shipping cost
                                                        for the first item in the parcel
                "min": "0.00",
                "max": "100000000.00",
                "currency": "PLN"
            },
            "nextItemRate": {                           -- rules for the shipping cost
                                                        of another item in the parcel
                "min": "0.00",
                "max": "100000000.00",
                "currency": "PLN"
            },
            "shippingTime": {                           -- rules for the shipping time
                "default": {
                    "from": "PT24H",
                    "to": "PT48H"
                },
                "customizable": true                    -- if custom shipping time can be set
                                                        when adding or modifying shipping rates
            }
        }
    }, {
        "id": "aa1d05e0-943b-47cb-a759-9d8c16707129",
        "name": "Allegro Przesyłka polecona",
        "paymentPolicy": "IN_ADVANCE",
        "allegroEndorsed": true,
        "shippingRatesConstraints": {
            "allowed": true,
            "maxQuantityPerPackage": {
                "max": 999999
            },
            "firstItemRate": {
                "min": "0.00",
                "max": "5.90",
                "currency": "PLN"
            },
            "nextItemRate": {
                "min": "0.00",
                "max": "0.00",
                "currency": "PLN"
            },
            "shippingTime": {
                "default": {
                    "from": "PT96H",
                    "to": "PT120H"
                },
                "customizable": false
            }
        }
    },
    ...
    {
        "id": "845efe05-0c96-47c3-a8cb-aa4699c158ce",
        "name": "Przesyłka kurierska pobranie",
        "paymentPolicy": "CASH_ON_DELIVERY",
        "allegroEndorsed": false,
        "shippingRatesConstraints": {
            "allowed": true,
            "maxQuantityPerPackage": {
                "max": 999999
            },
            "firstItemRate": {
                "min": "0.00",
                "max": "100000000.00",
                "currency": "PLN"
            },
            "nextItemRate": {
                "min": "0.00",
                "max": "100000000.00",
                "currency": "PLN"
            },
            "shippingTime": {
                "default": {
                    "from": "PT24H",
                    "to": "PT48H"
                },
                "customizable": true
            }
        }
    }
    ]
}

If you have an offer without a shipping rate assigned , you can use GET /sale/offers/{offerId}/shipping-rates, to get delivery methods used in that offer.

Sample request

  curl -X GET \
  'https://api.allegro.pl/sale/offers/8151913057/shipping-rates' \
   -H 'Accept: application/vnd.allegro.beta.v1+json’
Sample response:
  {
    "rates": [
        {
            "deliveryMethod": {
                "id": "845efe05-0c96-47c3-a8cb-aa4699c158ce"	-- shipping method ID
            },
            "maxQuantityPerPackage": 1,							-- quantity per parcel
            "firstItemRate": {									-- shipping cost
                "amount": "11.00",
                "currency": "PLN"
            },
            "nextItemRate": {									-- shipping price of
                                                                another item in the parcel
                "amount": "0.00",
                "currency": "PLN"
            },
            "shippingTime": {                                   --  shipping time
                "from": "PT72H",
                "to": "PT120H"
            }
        }
    ]
 }

Now use POST /sale/shipping-rates/ to create a shipping price list. Use the shipping price list ID when creating an offer.

Note! You can have up to 250 shipping price lists saved to your account.

Click to view sample request:
curl -X POST \
  https://api.allegro.pl/sale/shipping-rates \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: {token}' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' \
  -d '{
    "name": "Nowy cennik dostawy",                              -- required, shipping price list name
    "rates": [
        {
            "deliveryMethod": {
                "id": "845efe05-0c96-47c3-a8cb-aa4699c158ce"    -- required, shipping method ID
            },
            "maxQuantityPerPackage": 10,                        -- required, quantity per parcel
            "firstItemRate": {                                  -- required, shipping cost
                "amount": "12.58",
                "currency": "PLN"
            },
            "nextItemRate": {                                   -- required, price for another
                                                                item in the parcel
                "amount": "12.58",
                "currency": "PLN"
            },
            "shippingTime": {                                   -- hipping time; it can be set only
                                                                for some delivery methods (e.g. "845efe05-0c96-47c3-a8cb-aa4699c158ce"),
                                                                and if it is not set, the default shipping time
                                                                for the delivery method will be used.
                "from": "PT72H",                                a multiple of 24,
                "to": "PT120H"                                  according to ISO 8601
                "from": "PT72H",
                "to": "PT120H"
            }
        },
        {
            "deliveryMethod": {
                "id": "2488f7b7-5d1c-4d65-b85c-4cbcf253fd93"
            },
            "maxQuantityPerPackage": 1,
            "firstItemRate": {
                "amount": "7.99",
                "currency": "PLN"
            },
            "nextItemRate": {
                "amount": "0.00",
                "currency": "PLN"
            }
        }
    ]
}'
Click to view sample response:
{
 "id": "73491425-dea3-420b-b2bb-680310d764e4",
    "name": "Nowy cennik dostawy",
    "rates": [
        {
            "deliveryMethod": {
                "id": "845efe05-0c96-47c3-a8cb-aa4699c158ce"
            },
            "maxQuantityPerPackage": 10,
            "firstItemRate": {
                "amount": "12.58",
                "currency": "PLN"
            },
            "nextItemRate": {
                "amount": "12.58",
                "currency": "PLN"
            },
            "shippingTime": {
                "from": "PT72H",
                "to": "PT120H"
            }
        },
        {
            "deliveryMethod": {
                "id": "2488f7b7-5d1c-4d65-b85c-4cbcf253fd93"
            },
            "maxQuantityPerPackage": 1,
            "firstItemRate": {
                "amount": "7.99",
                "currency": "PLN"
            },
            "nextItemRate": {
                "amount": "0.00",
                "currency": "PLN"
            },
            "shippingTime": null
        }
    ],
    "lastModified": "2018-04-03T13:46:54.722Z"
}

You can retrieve your existing price lists via GET /sale/shipping-rates. Use the shipping price list ID to list a new offer.

Sample request:

  curl -X GET \
  'https://api.allegro.pl/sale/shipping-rates' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: Bearer {token}'
  {
	"shippingRates":[
		{
			"id": "fde5853c-01ce-4991-a4b3-994c1a4a408e",	-- shipping price list ID
			"name": "Cennik dostawy dla elektroniki"		-- shipping price list name
		},
		{
			"id": "64d7218b-cb3b-448a-9cdd-760a1eb76eb8",
			"name": "Cennik dostawy dla małego AGD"
		},
		{
			"id": "41b8e54f-dddd-4e48-ab17-dd941ade2116",
			"name": "Cennik dostawy dla promocji świątecznej"
		}
	]
  }
To check details of a particular shipping price list use GET /sale/shipping-rates/{shippingRatesId}.

Sample request:

  curl -X GET \
  https://api.allegro.pl/sale/shipping-rates/fde5853c-01ce-4991-a4b3-994c1a4a408e\
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: Bearer {token}'
Click to view sample response:
{

    "id": "ed1645ab-0895-4010-bd85-bb5d92ab0d83",               -- shipping price list ID
    "name": "Cennik dostawy test API 1",                        -- shipping price list name
    "rates": [
        {
            "deliveryMethod": {
                "id": "9081532b-5ad3-467d-80bc-9252982e9dd8"    -- shipping method ID
            },
            "maxQuantityPerPackage": 1,                         -- quantity per parcel
            "firstItemRate": {                                  -- shipping cost
                "amount": "10.95",
                "currency": "PLN"
            },
            "nextItemRate": {                                   -- shipping price of
                                                                another item in the parcel
                "amount": "0.00",
                "currency": "PLN"
            },
            "shippingTime": {                                   -- shipping time,
                "from": "PT72H",                                a multiple of 24,
                "to": "PT120H"                                  according to ISO 8601
            }
        },
        {
            "deliveryMethod": {
                "id": "574d1c9e-9903-4626-903f-f72441d520d5"
            },
            "maxQuantityPerPackage": 1,
            "firstItemRate": {
                "amount": "8.60",
                "currency": "PLN"
            },
            "nextItemRate": {
                "amount": "0.00",
                "currency": "PLN"
            },
            "shippingTime": null
        }
    ],
    "lastModified": "2018-08-08T08:24:56.086Z"                  -- last update of
                                                                the shipping price list
}

Read this article to learn how to manage shipping price lists linked to a seller account and offers..

Offer terms

Returns policy

How to add returns policy information

Use POST /after-sales-service-conditions/return-policies to a add new returns policy. In the request structure provide:

  • name - required, returns policy name,
  • availability.range - required, buyer’s ability to withdraw from the agreement:
    • FULL - is possible,
    • RESTRICTED - not possible or restricted under selected condition,
  • availability.restrictionCause.name - required, if you chose RESTRICTED in the availability.range. You can find a list of available values with a description below. You can select one value only:
value The consumer cannot withdraw from an agreement without providing a reason when:
SEALED_MEDIA the buyer has removed the sealed packaging of a sound or video recording or computer software (provision of the Act).
SEALED_ITEM_NO_RETURN_DUE_HEALTH_OR_HYGIENE the buyer has removed the sealed packaging of an item that cannot be returned once the packaging has been removed for health or hygiene-related reasons (provision of the Act).
CUSTOM_ITEM buys a non-prefabricated product manufactured in accordance with their specification or to meet their individual needs (provision of the Act).
SHORT_SHELF_LIFE buys a perishable item or an item that has a short use by date (provision of the Act).
INSEPARABLY_LINKED where the delivered item due to its characteristics, was inseparably linked with other items (provision of the Act).
ALCOHOL buys an alcoholic beverage, which may only be delivered after a lapse of 30 days and whose value depends on market fluctuations that are beyond the seller’s control (provision of the Act).
PRESS buys daily papers, periodicals or magazines (provision of the Act).
FULLY_IMPLEMENTED_SERVICE the service offered was performed in full upon explicit consent of the buyer, who was advised of the loss of the right to withdraw from the agreement (provision of the Act.
MEDICINAL_PRODUCT buys a medicinal product within the meaning of the pharmaceutical law – issued without a doctor’s prescription (provision of the Act).
BOOKED_SERVICE buys accommodation services for purposes other than residential, transport of things, car lease, catering, leisure, entertainment, sports or cultural events, if the agreement specifies the date or period of such service performance (provision of the Act).
NOT_RECORDED_DIGITAL_CONTENT digital content delivered to the customer, not saved on durable media, if the service has commenced at the consumer’s express consent before the expiry of the deadline for withdrawing from the agreement, and after the seller has advised them of the loss of the right to withdraw from the agreement (provision of the Act).
  • withdrawalPeriod - required, if you choose FULL in the availability.range field. Specify the period when withdrawal is possible in ISO 8601 format. You can only provide days as value, e.g. “P14D”,
  • returnCost.coveredBy - required, if you choose FULL in the availability.range field. Defines who covers the cost of the return shipment. Available values are SELLER or BUYER,
  • address - required, address for returns,
  • description - not required, additional information. You can use HTML tags: <p>, <b>, <ul>, <ol>, <li>. Other tags will be ignored.

Click to view sample request:
  curl -X POST \
  'https://api.allegro.pl/after-sales-service-conditions/return-policies' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json'
  -d ‘{
    "name": "Główne warunki zwrotu",            -- required, return policy
                                                name
    "availability": {                           -- required, option to
                                                withdraw/terminate the
                                                agreement
        "range": "RESTRICTED",
        "restrictionCause": {
            "name": "NOT_RECORDED_DIGITAL_CONTENT"
        }
    },
    "withdrawalPeriod": "P30D",                 -- required, time period when
                                                withdrawal is possible
    "returnCost": {
        "coveredBy": "BUYER"                    -- required, who covers
                                                the cost of return shipment
    },
    "address": {                                -- required, address for
                                                returns
        "name": "Testowa",
        "street": "100",
        "postCode": "61-132",
        "city": "Poznań",
        "countryCode": "PL"
    },
    "description":                              -- not required, additional
                                                information
    "<p>Can I return the product / withdraw from the contract?
    <b> Yes, if you bought the product as a consumer</b></p>
    <p> How much time do I have to return the product?
    30 days after receiving the parcel</p>"
  }’
Click to view sample response:
 {
    "id": "a1552d88-2536-4fb3-8aea-7394266a4ea4",
    "seller": {
        "id": "6273997540"
    },
    "name": "Main return policy",
    "availability": {
        "range": "RESTRICTED",
        "restrictionCause": {
            "name": "NOT_RECORDED_DIGITAL_CONTENT",
            "description": "The consumer may not withdraw from an agreement without giving a reason when digital content delivered to the customer, which is not saved on a durable media, if the service has commenced at the consumer’s express consent before the expiry of the deadline for withdrawing from the agreement, and after the seller has advised them of the loss of the right to withdraw from the agreement (<a href=\"https://allegro.pl/pomoc/faq/tresci-cyfrowe-eyD2m0RA3Im\" target=\"_blank\">provision of the Act</a>)"
        }
    },
    "withdrawalPeriod": "P30D",
    "returnCost": {
        "coveredBy": "BUYER"
    },
    "attachment": {                                     -- statutory model withdrawal
                                                        agreement is automatically added
                                                        to each request
        "id": "d7be84bc-5408-42d2-8d0d-acf3ea02feba",
        "name": "Przykładowy formularz odstąpienia od umów.pdf",
        "url": "https://after-sales.allegrostatic.com/after-sales-service-d2/d7be84bc-5408-42d2-8d0d-acf3ea02feba"
    },
    "address": {
        "name": "Testowa",
        "street": "100",
        "postCode": "61-132",
        "city": "Poznań",
        "countryCode": "PL"
    },
    "description": "<p>Can I return the product / withdraw from the contract?
    <b> Yes, if you bought the product as a consumer</b></p>
    <p> How much time do I have to return the product?
    30 days after receiving the parcel</p>"
}

How to retrieve return policies assigned to the account

Via GET /after-sales-service-conditions/return-policies you can retrieve returns policies assigned to your account. In the response you will receive a list of 60 returns policies, which contains identifiers and the names of the returns policies. You can adjust the list using filters:

  • limit - the number of results in the response. The default and the maximum value is 60,
  • offset - index of the first returned result.

If you want to retrieve details of the returns policy, provide their ID via GET /after-sales-service-conditions/return-policies/{returnPolicyId}.

Sample request:

  curl -X GET \
  'https://api.allegro.pl/after-sales-service-conditions/return-policies/bbbc9778-54f1-4dff-a9d4-c9067554390d' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' \
Click to view sample response:
 {
    "id": "a26da092-0e33-4b71-8a4a-e42592bad96a",
    "seller": {
        "id": "6279469754"
    },
    "name": "test2",
    "availability": {
        "range": "RESTRICTED",
        "restrictionCause": {
            "name": "SEALED_ITEM_NO_RETURN_DUE_HEALTH_OR_HYGIENE",
            "description": "The consumer cannot withdraw from an agreement without providing a reason when the buyer has removed sealed packaging of an item which cannot be returned once the packaging has been removed for health-related or hygiene-related reasons(<a href=\"https://allegro.pl/pomoc/faq/przedmioty-dostarczane-w-zapieczetowanym-opakowaniu-EYy4Vzom2uG\" target=\"_blank\">provision of the Act</a>)."
        }
    },
    "withdrawalPeriod": "P1D",
    "returnCost": {
        "coveredBy": "SELLER"
    },
    "attachment": {
        "id": "d7be84bc-5408-42d2-8d0d-acf3ea02feba",
        "name": "Przykładowy formularz odstąpienia od umów.pdf",
        "url": "https://after-sales.allegrostatic.com/after-sales-service-d2/d7be84bc-5408-42d2-8d0d-acf3ea02feba"
    },
    "address": {
        "name": "test",
        "street": "test",
        "postCode": "11-111",
        "city": "testowo",
        "countryCode": "PL"
    },
    "description": "<p>Can I return the product / withdraw from the contract? <b> Yes, if you bought the product as a consumer&#xa0;</b></p><p> How much time do I have to return the product? <b> 30 days after receiving the parcel</p>"
}

How to update returns policy information

To update returns policy information:

Click to view sample request:
 curl -X PUT \
'https://api.allegro.pl/after-sales-service-conditions/return-policies/bbbc9778-54f1-4dff-a9d4-c9067554390d' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' \
  -d ‘{
    "id": "bbbc9778-54f1-4dff-a9d4-c9067554390d",
    "seller": {
        "id": "6275799754"
    },
    "name": "Main return policy",
    "availability": {
        "range": "FULL",
        "restrictionCause": null
    },
    "withdrawalPeriod": "P30D",
    "returnCost": {
        "coveredBy": "SELLER"
    },
    "attachment": {                                     -- statutory model withdrawal
                                                        agreement is automatically added
                                                        to each request. You can’t change
                                                        this field.
        "id": "d7be84bc-5408-42d2-8d0d-acf3ea02feba",
        "name": "Przykładowy formularz odstąpienia od umów.pdf",
        "url": "https://after-sales.allegrostatic.com/after-sales-service-d2/d7be84bc-5408-42d2-8x0d-acf3ea02feba"
    },
    "address": {
        "name": "dluga ",
        "street": "100",
        "postCode": "61-132",
        "city": "Poznań",
        "countryCode": "PL"
    },
    "description": "<p>Czy mogę dokonać zwrotu produktu / odstąpić od umowy?
    <b>Tak, jeżeli kupiłeś produkt jako konsument&#xa0;</b></p>
    <p>Ile mam czasu na zwrot produktu? <b>30 dni od dnia otrzymania przesyłki</b></p>"
}’

Complaints policies

How to add complaints policy information

Use POST /after-sales-service-conditions/implied-warranties, to add new complaints policy. In the request structure, provide the fields:

  • name - required, complaints policy name,
  • individual.period - required, a time period when complaints policy for non-company customers is valid, specified in ISO 8601 format. You can only provide years as value, e.g. “P2Y”,
  • corporate.period - not required, a time period when complaints policy for company customers is valid, specified in ISO 8601 format. If you do not want to provide it, pass null value,
  • address - required, address for complaints,
  • description - not required, description of the complaints procedure. You can use HTML tags: <p>, <b>, <ul>, <ol>, <li>. Other tags will be ignored.

Click to view sample request:
  curl -X POST \
  'https://api.allegro.pl/after-sales-service-conditions/implied-warranties' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' \
  -d’{
    "name": "Main complaints policy",       -- required, complaints policy name
    "individual": {
        "period": "P1Y"                     -- required, a time period when
                                            complaints policy for non-company
                                            customers is valid
    },
    "corporate": {                          -- not required, a time period when
                                            complaints policy for company
                                            customers is valid
        "period": "P1Y"
    },
    "address": {                            -- required, address for complaints
        "name": "Test",
        "street": "ul. Testowa 7",
        "postCode": "61-135",
        "city": "Poznań",
        "countryCode": "PL"
    },
    "description":                      --  not required, description of
                                        complaints procedure
  “<p> What must a complaint contain? The complaint should include: </p>
  <ul> <li> Your name and address </li> <li> Allegro offer id </li>
  <li> order number </li> <li> item of the complaint </li>
  <li> Your expectations: replacement of the product with a new one,
  repair, reduction of the price or withdrawal from the contract (refund) </li> </ul>”
}’
Click to view sample response:
 {
    "id": "1556c6f7-c6a9-469e-9b3f-8f01eafaedc4",
    "seller": {
        "id": "62799754"
    },
    "name": "Main complaints policy",
    "individual": {
        "period": "P1Y"
    },
    "corporate": {
        "period": "P1Y"
    },
    "address": {
        "name": "test",
        "street": "ul. Testowa 7",
        "postCode": "61-135",
        "city": "Poznań",
        "countryCode": "PL"
    },
    "description": “<p> What must a complaint contain? The complaint should include: </p>
 <ul> <li> Your name and address </li> <li> Allegro offer id </li>
 <li> order number </li> <li> item of the complaint </li>
 <li> Your expectations: replacement of the product with a new one,
 repair, reduction of the price or withdrawal from the contract (refund) </li> </ul>”
 }

How to retrieve complaints policies assigned to the account

Via GET /after-sales-service-conditions/implied-warranties you can retrieve complaints policies assigned to your account. In the response, you will receive a list of 60 complaints policies, which contains identifiers and names of the complaints policies. You can adjust the list to your needs using filters:

  • limit - the number of results in the response. The default and the maximum value is 60,
  • offset - index of the first returned result.

If you want to retrieve details of the complaints policy, provide their ID via GET /after-sales-service-conditions/implied-warranties/{impliedWarrantyId}.

Sample request:

  curl -X GET \
  'https://api.allegro.pl/after-sales-service-conditions/implied-warranties/bbb2458-54f1-4dff-a9d4-c9067554390d' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' \
Click to view sample response:
 {
    "id": bbb2458-54f1-4dff-a9d4-c9067554390d",
    "seller": {
        "id": "627909754"
    },
    "name": "default",
    "individual": {
        "period": "P6Y"
    },
    "corporate": {
        "period": "P6Y"
    },
    "address": {
        "name": "test",
        "street": "ul. Testowa 7",
        "postCode": "61-135",
        "city": "Poznań",
        "countryCode": "PL"
    },
    "description": "<p> What must a complaint contain? The complaint should include: </p>
 <ul> <li> Your name and address </li>
 <li> Allegro offer id </li> <li> order number </li>
 <li> item of the complaint </li> <li> Your expectations: replacement of
 the product with a new one, repair, reduction of the price or withdrawal
 from the contract (refund) </li> </ul>"
 }

How to update complaints policy information

To update complaints policy information:

Click to view sample request:
  curl -X PUT \
  'https://api.allegro.pl/after-sales-service-conditions/implied-warranties/bbbc9778-54f1-4dff-a9d4-c9067554390d' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' \
  -d ‘{
    "id": "1556c6f7-c6a9-469e-9b3f-8f01eafaedc4",
    "seller": {
        "id": "279934754"
    },
    "name": "Main complaints policy",
    "individual": {
        "period": "P1Y"
    },
    "corporate": null,
    "address": {
        "name": "test",
        "street": "ul. Testowa 7",
        "postCode": "61-135",
        "city": "Poznań",
        "countryCode": "PL"
    },
    "description": “<p> What must a complaint contain? The complaint
     should include: </p>
    <ul> <li> Your name and address </li> <li> Allegro offer id </li>
    <li> order number </li> <li> item of the complaint </li>
    <li> Your expectations: replacement of the product with a new one,
    repair, reduction of the price or withdrawal from the contract (refund) </li> </ul>”
}’

Warranties

How to add an attachment to warranty information

Create attachment object via POST /after-sales-service-conditions/attachments. Additionally, specify the name of the .pdf file.

Sample request:

  curl -X POST \
  'https://api.allegro.pl/after-sales-service-conditions/attachments' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' \
  -d’
  {
	“name”: “warranty.pdf” 				-- attachment file name
  }’
Sample response:
  {
    "id": "7c8f40bc-3e50-408b-a66b-48122e05d84e",
    "name": "warranty.pdf",
    "url": null
  }

Now use PUT /after-sales-service-conditions/attachments/{attachmentId} - as attachmentId and provide the id value that you have received a step earlier. Remember to use the address we returned in the location header.

Sample request:

  curl -X PUT \
  'https://upload.allegro.pl/after-sales-service-conditions/attachments/7c8f40bc-3e50-408b-a66b-48122e05d84e' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json'
  -H ‘Content-Type: application/pdf’
  --data-binary "@warranty.pdf"                                -- required, content of the
                                    				       	   attachment file in a binary format
Sample response:
  {
    "id": "7c8f40bc-3e50-408b-a66b-48122e05d84e",
    "name": "warranty.pdf",
    "url": "https://after-sales.allegrostatic.com/after-sales-service-5c/7c8f40bc-3e50-408b-a66b-48122e05d84e"
 }

You can add the object you received to warranty information in the attachment field. The process is presented further in this guide.

How to add warranty information

Use POST /after-sales-service-conditions/warranties to add new warranty. In the request structure, provide:

  • name - required, warranty name,
  • type - required, warranty type, available values are MANUFACTURER (warranty by manufacturer or distributor) or SELLER,
  • individual.period - required, the warranty period for non-company customers in ISO 8601 format. You can only provide months as value, e.g. “P2M”. If you want to indicate a lifetime warranty, leave this field empty and in the field individual.lifetime, provide ‘true’ value,
  • corporate.period - required, warranty period for company customers in ISO 8601. You can only provide months as value, e.g. “P2M”. If you want to indicate a lifetime warranty, leave this space empty and in the field individual.lifetime, provide the ‘true’ value,
  • attachment - not required, attachment to the warranty,
  • description - not required, additional information, e.g. where to look for information, the contact person and method, required documents, etc.

Click to view sample request:
  curl -X POST \
  'https://api.allegro.pl/after-sales-service-conditions/warranties' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' \
  -d ‘{
  "name": "test",                           -- required, warranty name
  "type": "MANUFACTURER",                   -- required warranty type,
  "individual": {
    "period": "P12M",                       -- required, warranty period
    "lifetime": false                       -- not required. If warranty is for a
                                            lifetime information
  },
  "corporate": {                            -- not required, warranty period for
                                            entrepreneurs
    "period": "P12M",
    "lifetime": false
  },
  "attachment": {                           -- not required, attachment
information
    "id": "54702c96-4ccd-4c0e-b4c7-382a71e810b5",
    "name": "warranty.pdf",
    "url": "https://after-sales.allegrostatic.com/after-sales-service-5c/7c8f40bc-3e50-408x-a66b-48122e05d84e"
}
  },
  "description": null                       -- not required, additional information
}’
Click to view sample response:
  {
    "id": "bce9e4ad-4e06-4478-8038-04f3cbed73f4",
    "seller": {
        "id": "6279923754"
    },
    "name": "test",
    "type": "MANUFACTURER",
    "individual": {
        "period": "P12M",
        "lifetime": false
    },
    "corporate": {
        "period": "P12M",
        "lifetime": false
    },
    "attachment": {
        "id": "54702c96-4ccd-4c0e-b4c7-382a71e810b5",
        "name": "warranty.pdf",
        "url": "https://after-sales.allegrostatic.com/after-sales-service-00/54702c96-4ccd-4c0e-b4c7-382a71e810b5"
    },
    "description": null
}

How to retrieve warranties assigned to the account

Via GET /after-sales-service-conditions/warranties you can retrieve returns policies assigned to your account. In the response, you will receive a list of 60 returns policies, which contains the identifier and the name of the return policy. You can adjust the list to your needs using filters:

  • limit - the number of results in the response. The default and the maximum value is 60,
  • offset - index of the first returned result.

If you want to retrieve details of the warranty, provide its ID via GET /after-sales-service-conditions/warranties/{warrantyId}.

Sample request:

  curl -X GET \
  'https://api.allegro.pl/after-sales-service-conditions/warranties/bbb2458-54f1-4dff-a9d4-c9067554390d' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' \
Click to view sample response:
  {
    "id": "bbb2458-54f1-4dff-a9d4-c9067554390d",
    "seller": {
        "id": "627120754"
    },
    "name": "default",
    "type": "MANUFACTURER",
    "individual": {
        "period": null,
        "lifetime": true
    },
    "corporate": {
        "period": null,
        "lifetime": true
    },
    "attachment": {
        "id": "564c8680-505c-4d34-a6d3-bd8e4d20b49d",
        "name": "uploaded_file.pdf",
        "url": "https://after-sales.allegrostatic.com/after-sales-service-b5/564c8680-505c-4d34-a6d3-bd8e4d20b49d"
    },
    "description": null,
}

How to update warranty information

To update warranty information:

Click to view sample request:
  curl -X PUT \
  'https://api.allegro.pl/after-sales-service-conditions/warranties/bbbc9712-54f1-4dff-a9d4-c9067554390d' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' \
  -d ‘{
    "id": "62c9bede-82be-4d17-831d-af66270d1ade",
    "seller": {
        "id": "62799754"
    },
    "name": "default",
    "type": "MANUFACTURER",
    "individual": {
        "period": null,
        "lifetime": true
    },
    "corporate": {
        "period": null,
        "lifetime": true
    },
    "attachment": {
        "id": "564c8680-505c-4d34-a6d3-bd8e4d20b49d",
        "name": "uploaded_file.pdf",
        "url": "https://after-sales.allegrostatic.com/after-sales-service-b5/564c8680-505c-4d34-a6d3-bd8e4d20b49d"
    },
    "description": null,
}’

Additional services

Retrieve it via GET /sale/offer-additional-services/groups.

Size tables

Retrieve it via:

More information about Size Tables can be found our news.

Contact details

Retrieve it via GET /sale/offer-contacts.

2. Category and parameters

Use the below resources to retrieve IDs of particular categories and parameters you need to provide:

Category IDs

Use GET /sale/categories?parent.id={categoryId} to retrieve a list of subcategories that belong to the provided category.

Note!

  • If you use GET /sale/categories without providing any category, you will retrieve IDs of main Allegro categories. Use the identifiers to get to the lowest tier category.

  • Remember – an offer can be listed in the lowest tier category if the category is marked “leaf”: true.

  • We highly recommend assigning offers to products. The feature is available in selected categories in which we group offers presenting the same product. You will receive product data only in particular categories The categories are marked with “offersWithProductPublicationEnabled”: true.

Sample request:

  curl -X GET \
    'https://api.allegro.pl/sale/categories?parent.id={categoryId}
    -H 'Accept: application/vnd.allegro.public.v1+json' \
	-H 'Accept-Language: en-US'
    -H 'Authorization: Bearer {token}'
Sample response:
 {
  "categories":[
  {
   "id": "348",        							-- category ID
   "name": "GSM Accessories",     				-- category name
   "parent": {         							-- parent category ID; in the case of main
                                                categories, the value is null
   },
   "leaf": false,        						-- whether the category is
                                                of the lowest tier;
   "options": {        							-- category features
    "advertisement": false,     				-- whether the category
                                                or its subcategory supports classified ads.
    "advertisementPriceOptional": false,  		-- whether a price is optional in
                                                the classified ad category.
    "offersWithProductPublicationEnabled": true, -- whether the category
                                                 supports assigning offers to a product.
	"productCreationEnabled": false,			-- whether the category
                                                supports creating a product.
	"productEANRequired": false  				-- whether the category, when
                                                adding a product, EAN value is required,
	"customParametersEnabled": true             -- whether the category supports
												custom parameters
	}
  }]
 }

Parameters

Retrieve it via: GET /sale/categories/{categoryId}/parameters.

Retrieve the lists of parameters that are supported by the category you indicated. Every time a list of parameters supported by the input category is returned.

Sample request:

  curl -X GET \
    'https://api.allegro.pl/sale/categories/{catId}/parameters
    -H 'Accept: application/vnd.allegro.public.v1+json' \
	-H 'Accept-Language: en-US' \
    -H 'Authorization: Bearer {token}' \
Click to view sample response:
{
    "parameters": [                         -- list of parameters supported
                                               by the particular category
    {
        "id": "11323",                      -- unique parameter ID
        "name": "Condition",                -- parameter name
        "type": “dictionary”,               -- parameter type; supported values: dictionary
                                              (of single or multiple choice, depending on
                                              the value of multipleChoices), integer and float,
                                              string (you can add one or more value)
        "required":true,                    -- information whether a particular parameter
                                               is required; two values are supported:
                                               true (yes) and false (no)
        "unit": null,
        "requiredForProduct": true          -- whether you need to provide value for this
                                            parameter when you create a new product
        "options": {
            "variantsAllowed": false,
            "variantsEqual": false
            "ambiguousValueId": "216917_41" -- identifier for ambiguous value,
                                            e.g. "other"
            "dependsOnParameterId": null    -- values in the dictionary depend on the
                                            parameter referenced by this field.
            "requiredDependsOnValueIds": [  -- values identifier of the
                                            conditioning parameter, which determines
            "202870_1"                      whether a parameter will be require
            ],
            "displayDependsOnValueIds": [   --  set of values identifiers of the
                                            conditioning parameter, which determines
            "202870_1",                     whether a parameter will be visible
            "202870_2"
            ],
            "describesProduct": true,       -- whether the parameter describe product
            "customValuesEnabled": false    -- whether you can add your own value for
                                            a parameter with an ambiguous value
        },
        "dictionary": [
            {
                "id": "11323_1",
                "value": "New",
                "dependsOnValueIds": []
            },
            {
                "id": "11323_2",
                "value": "Used",
                "dependsOnValueIds": []
            }
        ],
        "restrictions": {
        "multipleChoices": false            -- this parameter enables choosing
                                               one or more values; supported values:
                                               true (yes) and false (no)
        }
    },
    {
        "id": "211966",
        "name": "Cutting Height Range Adjustment",
        "type": "float",
        "required": false,
        "unit": null,
        "requiredForProduct": true
        "restrictions": {
            "min": 0,
            "max": 1000,
            "range": true,              -- range parameter; provide
                                        minimum and maximum value
            "precision": 2
            }
        },
    {
        "id": "17448",
        "name": "Weight (with packaging)",
        "type": "float",
        "required":false,
        "restrictions": {
            "min": 5,
            "max": 10,
            "range": true,                  -- range parameter. Sections range min
                                               and max define the minimum and maximum
                                               value of a parameter
            "precision": 3                  -- defines the number of decimals
                                               in this case – three decimal places
        }
    },
    {
        "id": "216917",
        "name": "Included accessories",
        "type": "string",
        "required": false,
        "unit": null,
        "requiredForProduct": false
        "options": {
            "variantsAllowed": false,
            "variantsEqual": false,
            "ambiguousValueId": "216917_41", -- identifier for ambiguous value,
                                            e.g. "other"
            "dependsOnParameterId": null,
            "describesProduct": false,
            "customValuesEnabled": false
        },
        "restrictions": {
            "minLength": 1,
            "maxLength": 40,
            "allowedNumberOfValues": 10     -- information on how many values
                                            you can enter in a given parameter
        }
    }
    ]
}

Note! You should always check and update the parameters, especially the dictionary type parameter, because their values may change in time.

For PUT and POST methods you can only assign a dictionary parameter type by valuesIds array (not value array). Example of correct parameter structure:

  • for dictionary parameter type (one value or more values)

    	{
        	"id": "209878",
        	"valuesIds": [
        	"209878_2",
        	"209878_1"
        	],
        	"values": [],
        	"rangeValue": null
    	}

  • for range parameter type

    	{
        	"id": "212570",
        	"valuesIds": [],
        	"values": [],
        	"rangeValue": {
            	"from": "80",
            	"to": "100"
         	}
    	}

  • for string parameter type

    	{
        	"id": "216325",
        	"valuesIds": [],
        	"values": [
            	"zielony",
            	"żółty",
            	"czerwony"
        	],
        	"rangeValue": null
    	}

Custom parameters

Custom parameters:

  • you will add in customParameters field in the offer model. The parameter will be visible on the offer page.
  • have the same limit as in the sales form on the website - you can add up to 4 custom parameters for which you can provide one value,
  • can’t be duplicates - if parameters with this name already exist in Allegro, we will return an appropriate error. However, you can add custom parameters with the same name to the different offers.

Sample request structure:

   {
   ...
   "parameters": [...],
   "customParameters": [
    {
      "name": "Name of your own parameter",
      "values": [
        "Value of your own parameter"
      ]
    }
   ],
   "description": {...},
   ...}

Sample response structure:

   {
   ...
   "parameters": [...],
   "customParameters": [
    {
      "name": "Name of your own parameter",
      "values": [
        "Value of your own parameter"
      ]
    }
   ],
   "description": {...},
   ...}

Custom parameter values

You can define custom value for parameters with ambiguous value in selected categories. Use this option if you do not find the appropriate parameter value. Ambiguous parameter values are values like “other”, for example ““other” in the “Brand” parameter. You can retrieve its identifier via GET /sale/categories/{categoryId}/parameters field in options section - field ‘ambiguousValueId’.

To add a custom value, check the ambiguousValueId field in selected category via GET /sale/categories/{categoryId}/parameters:

  {
    "parameters": [
      {
        "id": "129033",
        "name": "Brand",
        "type": “dictionary”,
        "required":true,
        "unit": null,
		"requiredForProduct": true
        "options": {
            "variantsAllowed": false,
            "variantsEqual": false,
            "ambiguousValueId": "129033_13"      	-- identifier for ambiguous value,
                                                    in this case it is “other”
		    "dependsOnParameterId": null,
	        "describesProduct": true,
            "customValuesEnabled": true
        },
        ...
   }

After that, when you create a draft or edit an offer, provide the following structure in the parameters section:

 {
    	"id": "129033",     				        -- parameter id
    	"valuesIds": [
     	 "129033_13"               					-- ambiguous value id
    	],
    	"values": [ "Nazwa brakującej marki" ],	    -- value, which you want to provide.
													Complete this field.
    	"rangeValue": null
  }

You can add custom value only in selected categories.

3. Upload images

Use POST /sale/images to upload images to our servers and receive suitable links using HTTP and HTTPS protocols (only with a valid certificate) . Important! More information the about the rules for images in the gallery and description you will find here. You can choose from two options:

  • with a link Note! Remember to enter the domain address, do not use IP address.
      curl -X POST \
        https://upload.allegro.pl/sale/images \
        -H 'Authorization: Bearer {token}' \
        -H 'Accept: application/vnd.allegro.public.v1+json' \
        -H 'Content-Type: application/vnd.allegro.public.v1+json' \
        -d '{
           "url":"https://imgur.com/1aOIvg3E.jpg"       -- required, image link
          }'

  • in a binary format
      curl -X POST \
        'https://upload.allegro.pl/sale/images
        -H 'Authorization: Bearer {token}' \
        -H 'Accept: application/vnd.allegro.public.v1+json' \
        -H 'Content-Type: "image/jpeg", "image/png"' \
        -H 'Accept-Language: pl-PL', (albo en-EN) \
        --data-binary "@file_to_upload.png"				-- required, content of the
                                                           image file in a binary format

Sample response:

  • 401 - unauthorized

  • 413 - image is too large

  • 415 - incorrect image type

  • 201 - image uploaded correctly, response body:

	{
    	"expiresAt":"2018-04-06T16:38:04.930Z",			-- date of file expiration
                                                       (removal from the server).
                                                       We will remove it unless you use
                                                       it in your offer.
    	"location":"https://1.allegroimg.com/original/110843/cd7d40b84968ab8d79ab8a2e47a1"
														-- link to the uploaded image
	}

4. Offer title

We allow maximum of 50 characters in the offer title. These are the letters, numbers, and special characters allowed in offer titles.

	Letters: 'a','b','c','d','e','f','g','h','i','j','k','l','m','n','o','p','q','r','s','t','u','w','v','x','y','z',
	'ä','ö','ü','ø','ò','ß','0','á','č','ě','í','ř','š','ů','ú','ý','ž','œ','æ','à','â','ç','é','è','ê','ë','î',
	'ï','ô','û','ù','ü','ÿ','€','×','ą','ć','ę','ł','ń','ó','ś','ź','ż','µ','⌀',

 	Numbers: '0','1','2','3','4','5','6','7','8','9',

 	Special characters:'!','@','[',']','#','$','%','^','&','*','{','}','(',')','.',',','/','\\','|','?',' ',';','~','²','³',
	'`','\'','’','´','\"','”','"','„','“','″','<','>','_','\t',':','-','=','+','0','…','–','°','°'
Note! Some letters and special characters are converted to entities, therefore they take more than one character. For example the “&” is represented as &amp; and so takes up 5 characters.

5. Offer content

For more information on rules concerning offers please refer to the Seller page.

Note

  • the maximum size of the entire description is 40000 bytes

  • you can use only the following HTML tags:

    • h1 - title

    • h2 - subtitle

    • p - paragraph

    • ul - unordered (bulleted) list

    • ol - ordered list

    • li - list item

    • b - bold

  • you can use only images that are saved in an offer gallery that are saved in the images array.

We recommend drafting the first description using a listing form. Use all types of sections and text formatting options, and retrieve the offer via GET /sale/offers/{offerId}. This is the easiest way to learn how to prepare a correct description.

Structure of an offer description

Sections

The offer description consists of at least one section located in the sections array. The description can have up to 100 sections.

	{
    	"sections": [
        	{ section1 },
        	{ section2 },
         	...
        	]
	}

Description elements (item)

Sections group description elements (item) in a column view:

  • one screen width column

    	{
         	"items" : [
         	{ item1 }
         	]
    	}

  • two columns (50% of screen width)

    	{
         	"items" : [
         	{ item1 }
         	{ item2 }
         	]
    	}

  • You cannot create a section with more columns. structure

Types of content in the description

Text

	{
      "type": "TEXT",
      "content": "<p>opis tekstowy</p>"
	}

You can use the following HTML tags:

  • h1 - title

  • h2 - subtitle

  • p - paragraph

  • ul - unordered (bulleted) list

  • ol - ordered list

  • li - list item

  • b - bold

Key rules:

  1. You must put content in HTML tags. Use only lower case letters in HTML tag.
    Correct

    	{
          "type": "TEXT",
          "content": "<p>opis tekstowy</p>"
    	}
     
    Incorrect
    	{
          "type": "TEXT",
          "content": "opis tekstowy"
    	}
     

  2. You cannot format h1 and h2 tags.
    Correct

    	{
           "type": "TEXT",
           "content": "<h1>Tytuł sekcji</h1>"
        }
     
    Incorrect
    	{
          "type": "TEXT",
          "content": "<h1><b>Tytuł sekcji<b></h1>"
    	}
     

  3. You can use < b > < /b > tags in::

    • < p > < /p > - paragraph
    • < ul > < /ul > - unordered (bulleted) list
    • < ol > < /ol > - ordered list
  4. You can use < p > < /p > tags in:

    • < ul > < /ul > - unordered (bulleted) list
    • < ol > < /ol > - ordered list

How to combine HTML tags:

	<h1>Lorem ipsum dolor sit amet, consectetur adipiscing elit</h1>
    <p><b>Aliquam vitae nisi ac lectus gravida rhoncus</b>. Vivamus egestas, orci quis
    fermentum sollicitudin, leo urna pellentesque quam, ut mattis risus nisl sed dolor.</p>
    <ul>
        <li><b>Nulla eu justo ut velit pellentesque porta.</b></li>
        <li>Pellentesque eget arcu id ligula consequat fermentum at nec velit. Maecenas vitae nunc
        non ante aliquet facilisis nec id leo.</li>
        <li>Sed vitae metus vel lorem iaculis rhoncus.</li> <li>Nullam nec felis felis.</li>
    </ul>
    <ol>
        <li><p><b>In eget vulputate purus</b></p></li>
        <li><p>Integer a pharetra odio.</p></li>
        <li><p>Vestibulum ut vestibulum diam.</p></li>
        <li><p>Phasellus quis tempor ipsum, at tincidunt nibh.</p></li>
        <li><p>Nulla sollicitudin, libero sit amet fermentum iaculis.</p></li>
    </ol>

Images

You can use only images you have previously transferred by calling POST on /sale/images.

	{
    	"type": "IMAGE",
    	"url": "https://d.allegroimg.com/original/0313bd/338d11a74b059fea784beee0084d"
	}

Sample structure of an offer description:

		{
    		"sections": [{
        	"items": [{
            	"type": "TEXT",
            	"content": "<p>tekstowy opis przedmiotu</p>"
        	}]
    	}, {
        	"items": [{
            	"type": "IMAGE",
            	"url": "https://d.allegroimg.com/original/0313bd/338d11a74b059fea784beee0084d"
        	}]
    	}, {
        	"items": [{
            	"type": "TEXT",
            	"content": "<p>tekstowy opis przedmiotu</p>"
        	}, {
            	"type": "IMAGE",
            	"url": "https://f.allegroimg.com/original/037738/bc72c2f24784b50774d7d078c7ef"
        	}]
    	}, {
        	"items": [{
            	"type": "IMAGE",
            	"url": "https://0.allegroimg.com/original/032ac4/9c10035846bb970cf208f6982fc0"
        	}, {
            	"type": "IMAGE",
            	"url": "https://d.allegroimg.com/original/0313bd/338d11a74b059fea784beee0084d"
        	}]
    	}]
	}

6. Additional options

Add tags to an offer

You can assign tags to your published offer. However, first check the tags you have saved to your account. Retrieve themviaGET /sale/offer-tags. By default you will receive 1,000 tags assigned to your account. You can also retrieve a list of tags that is adjusted to your needs owing to the following parameters:

  • offset - define a starting point for retrieving another batch of data (takes values from a scope that is covered by the integer data type). 0 by default.
  • limit - define a number of tags to be returned (takes values from a scope that is covered by the integer data). 1,000 by default.

e.g. GET /sale/offer-tags&offset=0&limit=10 will return a list of 10 tags starting with the first one.

Sample request:

  curl -X GET \
    http://api.allegro.pl/sale/offer-tags \
    -H 'Accept: application/vnd.allegro.public.v1+json' \
    -H 'Authorization: Bearer {token}
Sample response
  {
    "tags": [
        {
            "id": "500fedd3-2140-4225-87d4-a22484222776",   -- tag ID,
            "name": "Komiksy",                              -- tag name,
            "hidden": false                                 -- whether the tag is hidden –
                                                            false (displayed) or true (hidden),
        },
        {
            "id": "d2d2d475-7049-493d-bb95-f4ea59983ecb",
            "name": "Filmy",
            "hidden": false
        },
        {
            "id": "4b876428-d827-492b-a30e-aee3f5be791a",
            "name": "Muzyka",
            "hidden": false
        }
    ]
  }

Once you know which tags you want to use assign selected tags to your offer via POST sale/offers/{offerId}/tags.

Sample request:

  curl -X POST \
    http://api.allegro.pl/sale/offers/{offerId}/tags \
    -H 'Content-Type: application/vnd.allegro.public.v1+json'
    -H 'Accept: application/vnd.allegro.public.v1+json' \
    -H 'Authorization: Bearer {token}' \
    -d '{
    "tags": [
        {
            "id": "500fedd3-2140-4225-87d4-a22484222776"   -- required, tag identifier,
        }
    ]
  }'
Sample response 200 - OK - tags have been assigned successfully
Note! Each time you assign new tags you overwrite the previous ones. This means if you want to remove tags from offers without assigning any new ones, you need to call up the resource and transfer an empty tags structure into it’s body.

	{
 		"tags":[]
 	}

Uploading attachments to offers

You can upload PDF attachments to your offers. We will present them under the offer description in the Additional information section. You can upload up to 7 attachments – one per each section:

  • Guide (MANUAL)

  • Special offer terms (SPECIAL_OFFER_RULES)

  • Competition terms (COMPETITION_RULES)

  • Book excerpt (BOOK_EXCERPT)

  • Manual (USER_MANUAL)

  • Installation manual (INSTALLATION_INSTRUCTIONS)

  • Game manual (GAME_INSTRUCTIONS)

Uploading attachments to offers:

  1. Create an attachment object to receive an attachment ID and URL to send the attachment to,
  2. Use the URL to submit the PDF file you want to upload,
  3. Add the attachment to the offer.

Create the attachment object

To add the attachment you must first create the attachment object via POST /sale/offer-attachments. Once you create the object, you will have:

  • attachment ID,

  • URL to upload the file to our server.

Sample request:

  curl -X POST \
    https://api.allegro.pl/sale/offer-attachments \
    -H 'Accept: application/vnd.allegro.public.v1+json' \
    -H 'Content-Type: application/vnd.allegro.public.v1+json' \
    -H 'Authorization: Bearer {token}'
    -d '{
    "type": "SPECIAL_OFFER_RULES",                              -- required, attachment type,
                                                                   supported values MANUAL,
                                                                   SPECIAL_OFFER_RULES,
                                                                   COMPETITION_RULES,
                                                                   BOOK_EXCERPT, USER_MANUAL,
                                                                   INSTALLATION_INSTRUCTIONS,
                                                                   GAME_INSTRUCTIONS,
    "file": {
        "name": "abcde.pdf"                                     -- required, name of the file you
                                                                   want to upload,
    }
  }'

Note! You can find the URL address to upload the file to our server in the response header. The URL is unique and one-time. As its format may change over time, you should always use the address from the header. Do not create the address from available elements.

Sample response 201 - created - attachment object has been created successfully
Response header:

	Location: http://upload.allegro.pl/sale/offer-attachments/e9d1bf7c-804e-4faf-9e24-b2d3aa3eda05

Response body:

  {
    "id": "e9d1bf7c-804e-4faf-9e24-b2d3aa3eda05",              -- ID of the attachment draft,
    "type": "SPECIAL_OFFER_RULES",                             -- attachment type,
    "file": {
        "name": "abcde.pdf"                                    -- name of the file you upload,
    }
  }

Uploading PDF files

Now you can upload the attachment to our server. Use the address you received in the header of the response (in the Location field) to the previous call.

Sample request:

  curl -X PUT \
  http://upload.allegro.pl/sale/offer-attachments/{attachmentId} \
    -H 'Accept: application/vnd.allegro.public.v1+json' \
    -H 'Content-Type: application/pdf' \
    -H 'Authorization: Bearer {token}
    --data-binary "@abcde.pdf"                             -- required, content of the file
                                                           with the attachment in a
                                                           biinary form

Sample response:
  {
    "id": "07ee5e36-afc7-41eb-af49-3df5354ef858",          -- ID of the attachment draft,
    "type": "SPECIAL_OFFER_RULES",                         -- rattachment type,
    "file": {
        "name": "abcde.pdf",                               -- name of the file you upload,
        "url": {adres_pliku}                               -- address under which the attachment
                                                           is available.
    }
  }

Adding an attachment to the offer

Use PUT /sale/offers/{offerId} to add the attachment to the offer – provide its ID in the attachments structure.

	"attachments": [
            {
                "id": "07ee5e36-afc7-41eb-af49-3df5354ef858"
            }
        ]

7. Offer draft

Use POST /sale/offers. You must be an authenticated and authorized user. Once the draft offer is created, you can publish it later on the site. You can transfer partial data (at least the title) and then complete the draft via PUT /sale/offers/{offerId}. If you transfer incomplete data, the “validation” field will display:

  • missing information

  • errors in your offer


information
  • You can create up to 20,000 drafts. When you exceed the limit, you will not be able to add new drafts and will receive the following message - “You cannot create new drafts - your account has exceeded the maximum number 20,000 of drafts.” Delete unnecessary with DELETE /sale/offers/{offerId}.
  • The offer draft is stored for 60 days. After that, the offer draft will be deleted. If you edit something in the offer draft, we will extend its validity by 60 days.

Sample request:

  curl -X POST \
    'https://api.allegro.pl/sale/offers'
    -H 'Authorization: Bearer {token}' \
    -H 'Accept: application/vnd.allegro.public.v1+json' \
    -H 'Content-Type: application/vnd.allegro.public.v1+json' \
    -d '{
      "name": "Oferta testowa"                        -- required, offer title
  }

Click to view sample response:
{
    "id": "7276377308",
    "name": "Oferta testowa",
    "category": null,
    "parameters": [],
    "ean": null,
    "description": null,
    "images": null,
    "sellingMode": null,
    "tax": null,
    "stock": null,
    "publication": {
        "republish": null,
        "duration": null,
        "status": "INACTIVE",
        "startingAt": null,                         -- value in response
                                                    always returns null
        "endingAt": null
    },
    "delivery": null,
    "payments": {
        "invoice": "NO_INVOICE"
    },
    "discounts": null,
    "afterSalesServices": null,
    "additionalServices": null,
    "sizeTable": null,
    "fundraisingCampaign": null,
    "promotion": null,
    "location": null,
    "external": null,
    "attachments": [],
    "contact": null,
    "validation": {
        "errors": [
            {
                "code": "VALIDATION_ERROR",
                "message": "Location may not be empty.",
                "details": "",
                "path": "",
                "userMessage": "Location may not be empty."
            },
            {
                "code": "VALIDATION_ERROR",
                "message": "Payments may not be empty.",
                "details": "",
                "path": "",
                "userMessage": "Payments may not be empty."
            },
            {
                "code": "VALIDATION_ERROR",
                "message": "New offer description is required.",
                "details": "",
                "path": "",
                "userMessage": "New offer description is required."
            },
            {
                "code": "VALIDATION_ERROR",
                "message": "You must select at least one selling mode and provide the required prices.",
                "details": "",
                "path": "",
                "userMessage": "You must select at least one selling mode and provide the required prices."
            },
            {
                "code": "VALIDATION_ERROR",
                "message": "Category may not be empty.",
                "details": "",
                "path": "",
                "userMessage": "Category may not be empty."
            },
            {
                "code": "VALIDATION_ERROR",
                "message": "Describe your offer.",
                "details": "",
                "path": "",
                "userMessage": "Describe your offer."
            }
        ],
        "validatedAt": "2018-04-06T09:29:47.544Z"
    },
    "createdAt": "2018-04-06T09:29:47Z",
    "updatedAt": "2018-04-06T09:29:47.544Z"
}

8. Complete offer

Use PUT /sale/offers/{offerId}. You can edit ongoing offers. Complete the drafts and published offers. Call PUT to edit the offers. To publish the offer later, transfer a complete set of information. If you transfer incomplete data, the “validation” field will display:

  • missing information

  • or errors in your offer

NOTE! If you want to update an ongoing offer, retrieve its data via GET /sale/offers/{offerId}. Next, when you update the offer, transfer the same structure you received earlier in the response. Even if you update only one field, you have to send the complete structure of the offer fields.

New offer

Use PUT /sale/offers/{offerId} to complete data in the draft offer. Below we described fields you have to transfer to publish the offer on the site.

Note! Remember to send information about handlingTime with shippingRates ID and sellingMode format.

Click to view sample request:
curl -X PUT \
  'https://api.allegro.pl/sale/offers/{offerId}
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' \
  -d '{
    "id": "7276261934",                             -- offer ID
    "name": "Oferta testowa",                       -- required, title of a retrieved offer
    "product": {
     "id": "634238b1-4385-4de7-9c00-dfa49fce16ab"   -- product ID
    "category": {
        "id": "257150"                              -- required, category of the lowest tier
                                                   that hosts the offer. Use
                                                   GET /sale/categories?parent.id={catId}
                                                   to retrieve category IDs.
    },
    "parameters": [                                 -- required, offer parameters, to check
                                                   parameters supported in a particular category use
                                                   GET /sale/categories/{categoryId}/parameters
        {
            "id": "11323",
            "valuesIds": [
                "11323_1"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "128188",
            "valuesIds": [
                "128188_1"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "127448",
            "valuesIds": [
                "127448_1"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "4386",
            "valuesIds": [
                "4386_1"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "219",
            "valuesIds": [
                "219_2",
                "219_256",
                "219_4"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "225693",                         -- GTIN parameter
            "valuesIds": [],                        (info: http://developer.allegro.pl/en/news/#gtin)
            "values": [
                "6901443187416"
            ],
            "rangeValue": null
        }
    ],
    "ean": "6901443187416",                         -- read only field, EAN/ISBN/ISSN can be set
                                                    only by GTIN parameter
    "description": {                                -- required, offer content
        "sections": [
            {
                "items": [
                    {
                        "type": "TEXT",
                        "content": "<p>Tekstowy opis przedmiotu</p>"
                    },
                    {
                        "type": "IMAGE",
                        "url": "https://e.allegroimg.com/original/01fd60/4ea8d18e4275b0878b7f0562067e"
                    }
                ]
            },
            {
                "items": [
                    {
                        "type": "TEXT",
                        "content": ""<p>Tekstowy opis przedmiotu</p>""
                    }
                ]
            }
        ]
    },
    "images": [                                     -- required image paths; send photos
                                                   via
                                                   POST /sale/images.
                                                   The first photo in the array is also
                                                   the first offer photo (thumbnail).
        {
            "url": "https://e.allegroimg.com/original/01fd60/4ea8d18e4275b0878b7f0562067e"
        },
        {
            "url": "https://e.allegroimg.com/original/018474/c62b54a74120a7983b09d0fa4a4e"
        },
        {
            "url": "https://8.allegroimg.com/original/013a51/4dd0904a4169ad8b0d25a8984b48"
        },
        {
            "url": "https://2.allegroimg.com/original/01b48e/6e777def4a71ba68952358bd2072"
        }
    ],
    "compatibilityList": {                          -- compatibility list,
        "id": "d04e8a0c-40a1-4c53-8902-ffee7261845e-922db1ed6fa1c9731d50ce251007ab400247b0ebb62f1006493f5b6c418bb0fa-2",
        "type": "PRODUCT_BASED"
    },
    "tecdocSpecification": {                        -- TecDoc specification for automotive parts
        "id": "e3725f4b-1b4b-4e39-ad7f-331a2c858a7f"
    },
    "sellingMode": {                                -- required, sales format, three values are
                                                   supported: BUY_NOW (Buy it Now); AUCTION
                                                   (auction); ADVERTISEMENT (classified ad)
        "format": "BUY_NOW",
        "price": {
            "amount": "1499",                       -- required, offer price in the case of
                                                   BUY_NOW (Buy it Now) and ADVERTISEMENT
                                                   (classified ad) formats
            "currency": "PLN"
        },
        "netPrice": {                               -- net price, calculated automatically
            "amount": "1218.70",                    based on the VAT rate
            "currency": "PLN"
        },
        "startingPrice": null,                      -- starting price, available in AUCTION (auction)
        "minimalPrice": null                        -- reserve price, available in AUCTION (auction)
    },
    "tax": {                                        -- VAT rate, you can define it only if the
        "percentage": "23.00"                       "VAT" invoice option is selected in the offer
    },
    "stock": {
        "available": 4,                             -- required, number of available items
                                                   NOTE! Do not fill it out for offers of
                                                   ADVERTISEMENT (classified ad) type;
                                                   however for AUCTION (auction) offers provide 1
        "unit": "UNIT"                              required, three values are supported:
                                                   UNIT (pieces); SET (sets); PAIR (pairs).
                                                   NOTE! Do not fill it out for offers of
                                                   ADVERTISEMENT (classified ad)
    },
    "publication": {
        "republish": true,                      -- not required, automatically republish offers.
                                                   Note! You can automatically republish
                                                   offers or auctions:
                                                   - offers are republished with initial stock,
                                                   regardless of how many items you have sold.
                                                   - auctions are republished only
                                                   if they were not concluded with purchase.
        "duration": null,                       -- required, offer duration, supported values:
                                                   null (until all items are sold out),
                                                   P3D (3 days); P5D (5 days); P7D (7 days);
                                                   P10D (10 days); P20D (20 days);
                                                   you can also provide the time in hours,
                                                   e.g.: P72H (3 days). You cannot provide
                                                   null in offers of AUCTION (auction) type and
                                                   the allowed values are: P1D (1 day); P3D (3 days);
                                                   P5D (5 days); P7D (7 days); P10D (10 days);
                                                   However, the offers of ADVERTISEMENT
                                                   (classified ad) type support the following
                                                   values: null (for an indefinite time – fees
                                                   are charged every 10 days); P10D (10 days);
                                                   P20D (20 days); P30D (30 days)
        "status": "INACTIVE",                   -- offer status, three values are supported:
                                                   ACTIVE (active on the site), INACTIVE (inactive),
                                                   ENDED (ended on the site)
        "startingAt": null,                     -- not required, offer start time, applies to
                                                   scheduled offers
        "endingAt": null,                       -- not required, offer end time
        "endedBy": null                         -- not required, reason of ended, four values are
                                                   supported: USER (ended by user), ADMIN (ended by admin),
                                                   EXPIRATION (available items had sold out
                                                   or offer duration had expired), ERROR (internal problem)
    },
    "delivery": {
        "shippingRates": {
            "id": "4b9ad5b9-7ee9-409b-86f5-578672c13df8"    -- required, shipping price list
                                                    ID number, retrieve via
                                                    GET /sale/shipping-rates.
                                                    In the case of offers of ADVERTISEMENT
                                                    (classified ad) type leave this field
                                                    empty by transferring “delivery”: null
        },
        "handlingTime": "PT168H",               -- required, shipping time; supported
                                                   values: PT0S (immediately), PT24H (24 hours),
                                                   P2D (2 days), P3D (3 days), P4D (4 days),
                                                   P5D (5 days), P7D (7 days), P10D (10 days),
                                                   P14D (14 days), P21D (21 days),
                                                   duration can be also provided in hours,
                                                   e.g. PT72H (3 days). It is not required
                                                   for offers of ADVERTISEMENT (classified ad) type.
        "additionalInfo": "Additional delivery information" -- not required, additional
                                                   information on delivery; you can provide here
                                                   information in a text form to be displayed in
                                                   the “Delivery and payment” section.
        "shipmentDate":"2018-04-01T08:00:00Z"   -- shipping from - e.g. for pre-sale.
                                                   Record of date consistent with ISO8601.
    },
    "payments": {
        "invoice": "VAT"                        -- required, information about an invoice;
                                                   four values are supported: VAT (VAT invoice);
                                                   VAT_MARGIN (VAT invoice margin); WITHOUT_VAT
                                                   (invoice without VAT);
                                                   NO_INVOICE (I don't issue invoices)
    },
    "discounts": {                              -- not required, information about discounts,
       "wholesalePriceList": {                              retrieve a wholesale price list identifier
           "id": "5637592a-0a24-4771-b527-d89b2767d821"     via GET /sale/loyalty/promotions
       }                                                    and filter “promotionType=WHOLESALE_PRICE_LIST”
    },
    "afterSalesServices": {                     -- offer terms; required in the case of
                                                   company accounts. In the case of offers of
                                                   ADVERTISEMENT (classified ad) type this feature
                                                   is unavailable; transfer "afterSalesServices": null
        "impliedWarranty": {
            "id": "b0590fac-9858-4d01-8487-1c6a09c55a68"    -- required in the case of company
                                                               accounts, information on complaints;
                                                               retrieve a particular identifier
                                                               via
                                                GET /after-sales-service-conditions/implied-warranties
        },
        "returnPolicy": {
            "id": "c27c2ddd-f587-44db-b3c8-1f181964ea4d"    -- required in the case of company accounts;
                                                               return policy; retrieve identifiers
                                                               via
                                                GET /after-sales-service-conditions/return-policies
        },
        "warranty": {
            "id": "f8694df6-f020-4a27-ac0a-f4f959969e14"    -- not required, information on
                                                               warranties; retrieve the identifiers
                                                               via
                                                GET via /after-sales-service-conditions/warranties
        }
    },
    "additionalServices": null,                 -- additional services; retrieve identifiers
                                                   of your groups of additional services via
                                                   GET /sale/offer-additional-services/groups.
                                                   The feature is not available to offers
                                                   of ADVERTISEMENT (classified ad) type.;
                                                   transfer "additionalServices": null.
    "sizeTable": null,                          -- size table ID,
                                                   retrieve identifiers via
                                                   GET /sale/size-tables
    "fundraisingCampaign": null,                -- not required, charity organization ID, retrieve
                                                   identifiers via GET /charity/fundraising-campaigns
    "promotion": {                              -- not required, promo options;
                                                   select one value next to each option:
                                                   false (inactive); true (active)
        "emphasized": true,                     -- emphasized
        "bold": false,                          -- bold
        "highlight": false,                     -- highlight
        "departmentPage": false,                -- offer promoted on a category page
        "emphasizedHighlightBoldPackage": false -- promo package: emphasized, highlighting
                                                   and bold
    },
    "location": {                               -- required, for offer with a delivery method
                                                   it is a parcel dispatch location. For offers
                                                   with personal pick-up it is a pick-up location,
                                                   additionally we recommend to use points of service
                                                   (https://developer.allegro.pl/documentation/#tag/Points-of-service)
                                                   Before completing this field, you must first assign a shippingRate and set a sellingMode
        "countryCode": "PL",                    -- required, country code according to
                                                   ISO 3166-1 alpha-2
        "province": "WIELKOPOLSKIE",            -- required in the case of countryCode “PL”,
                                                   province, available values: DOLNOSLASKIE;
                                                   KUJAWSKO_POMORSKIE; LUBELSKIE; LUBUSKIE;
                                                   LODZKIE; MALOPOLSKIE; MAZOWIECKIE; OPOLSKIE;
                                                   PODKARPACKIE; PODLASKIE; POMORSKIE; SLASKIE;
                                                   SWIETOKRZYSKIE; WARMINSKO_MAZURSKIE;
                                                   WIELKOPOLSKIE; ZACHODNIOPOMORSKIE.
                                                   This value is not required in the
                                                   case of other countries.
        "city": "Poznań",                       -- required, city
        "postCode": "60-166"                    -- required for addresses in Poland, postal code
    },
    "external": {                               -- not required, external ID / signature assigned
                "id":"4131asdsad40011"             by the seller, e.g. to link an offer
                },                                 with a product in the seller's warehouse.
                                                   You can provide here a default string of
                                                   characters that will be displayed after
                                                   offer relisting.
    "attachments": [
            {
        "id": "07ee5e36-afc7-41eb-af49-3df5354ef858" -- not required, attachments ID
            }
        ]
    "contact": null,                            -- not required, identifier of contact data
                                                   for sales format ADVERTISEMENT (classified ad);
                                                   retrieve it via
                                                   GET /sale/offer-contacts
    "validation": {
        "errors": [],                           -- information on potential errors; we will
                                                   inform you if you provide e.g. incorrect
                                                   price list ID.
        "validatedAt": "2018-04-06T08:29:37.461Z"   -- date of last offer validation
    },
    "createdAt": "2018-04-06T08:26:32Z",        -- required, offer creation date
    "updatedAt": "2018-04-06T08:29:38.664Z"     -- required, last offer update
}'

Click to view sample response:
{
    "id": "7276377308",
    "name": "Oferta testowa",
    "category": {
        "id": "257150"
    },
    "parameters": [
        {
            "id": "11323",
            "valuesIds": [
                "11323_1"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "128188",
            "valuesIds": [
                "128188_1"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "127448",
            "valuesIds": [
                "127448_1"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "4386",
            "valuesIds": [
                "4386_1"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "219",
            "valuesIds": [
                "219_2",
                "219_256",
                "219_4"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "225693",
            "valuesIds": [],
            "values": [
                "6901443187416"
            ],
            "rangeValue": null
        }
    ],
    "ean": "6901443187416",
    "description": {
        "sections": [
            {
                "items": [
                    {
                        "type": "TEXT",
                        "content": "<p>Tekstowy opis przedmiotu</p>"
                    },
                    {
                        "type": "IMAGE",
                        "url": "https://e.allegroimg.com/original/01fd60/4ea8d18e4275b0878b7f0562067e"
                    }
                ]
            },
            {
                "items": [
                    {
                        "type": "TEXT",
                        "content": "<p>Tekstowy opis przedmiotu</p>"
                    }
                ]
            }
        ]
    },
    "images": [
        {
            "url": "https://e.allegroimg.com/original/01fd60/4ea8d18e4275b0878b7f0562067e"
        },
        {
            "url": "https://e.allegroimg.com/original/018474/c62b54a74120a7983b09d0fa4a4e"
        },
        {
            "url": "https://8.allegroimg.com/original/013a51/4dd0904a4169ad8b0d25a8984b48"
        },
        {
            "url": "https://2.allegroimg.com/original/01b48e/6e777def4a71ba68952358bd2072"
        }
    ],
    "compatibilityList": {
        "id": "d04e8a0c-40a1-4c53-8902-ffee7261845e-922db1ed6fa1c9731d50ce251007ab400247b0ebb62f1006493f5b6c418bb0fa-2",
        "type": "PRODUCT_BASED",
        "items": [
            {
                "text": "ALFA ROMEO 147 (937_) 1.6 16V T.SPARK (937.AXA1A, 937.AXB1A, 937.BXB1A) (AR 32104) 1598ccm 120KM/88kW 2001/01-2010/03, szczegóły: Strona zabudowy: z lewej, z prawej, Oś tylna, System hamulcowy: LUCAS, dla numeru artykułu: 343599, 343598"
            },
        ...
            {
                "text": "SKODA RAPID Spaceback (NH1) 1.2 TSI (CBZB) 1197ccm 105KM/77kW 2012/07-, szczegóły: Strona zabudowy: z prawej, Oś tylna, z lewej, System hamulcowy: LUCAS, dla numeru artykułu: 342966, 342967, dla numeru PR: 1KT"
            }
        ]
    },
    "tecdocSpecification": {
        "id": "e3725f4b-1b4b-4e39-ad7f-331a2c858a7f",
        "items": [
            {
                "name": "Wysokość [mm]",
                "values": [
                    "51"
                ]
            },
            {
                "name": "Materiał",
                "values": [
                    "stal"
                ]
            },
            {
                "name": "średnica [mm]",
                "values": [
                    "38"
                ]
            },
            {
                "name": "Wersja TecDoc",
                "values": [
                    "TecDoc 0619"
                ]
            }
        ]
    },
    "sellingMode": {
        "format": "BUY_NOW",
        "price": {
            "amount": "1499",
            "currency": "PLN"
        },
        "netPrice": {
            "amount": "1218.70",
            "currency": "PLN"
        },
        "startingPrice": null,
        "minimalPrice": null
    },
    "tax": {
        "percentage": "23.00"
    },
    "stock": {
        "available": 4,
        "unit": "UNIT"
    },
    "publication": {
        "republish": true,
        "duration": null,
        "status": "INACTIVE",
        "startingAt": null,
        "endingAt": null
    },
    "delivery": {
        "shippingRates": {
            "id": "4b9ad5b9-7ee9-409b-86f5-578672c13df8"
        },
        "handlingTime": "PT168H",
        "additionalInfo": ""
        "shipmentDate":"2018-04-01T08:00:00Z"
    },
    "payments": {
        "invoice": "VAT"
    },
    "discounts": {
       "wholesalePriceList": {
           "id": "5637592a-0a24-4771-b527-d89b2767d821"
       }
    },
    "afterSalesServices": {
        "impliedWarranty": {
            "id": "b0590fac-9858-4d01-8487-1c6a09c55a68"
        },
        "returnPolicy": {
            "id": "c27c2ddd-f587-44db-b3c8-1f181964ea4d"
        },
        "warranty": {
            "id": "f8694df6-f020-4a27-ac0a-f4f959969e14"
        }
    },
    "additionalServices": null,
    "sizeTable": null,
    "fundraisingCampaign": null,
    "promotion": {
        "emphasized": true,
        "bold": false,
        "highlight": false,
        "departmentPage": false,
        "emphasizedHighlightBoldPackage": false
    },
    "location": {
        "countryCode": "PL",
        "province": "WIELKOPOLSKIE",
        "city": "Poznań",
        "postCode": "60-166"
    },
    "external": {                               -- niewymagany, zewnętrzny ID / sygnatura,
        "id":"4131asdsad40011"                  który nadaje sprzedający, np. aby powiązać ofertę
                },                              z produktem w swoim magazynie. Możesz wprowadzić
                                                tutaj dowolny ciąg znaków - będzie on dostępny
                                                również po wznowieniu oferty.
    "attachments": [],
    "contact": null,
    "validation": {
        "errors": [],
        "validatedAt": "2018-04-06T09:34:40.142Z"
    },
    "createdAt": "2018-04-06T09:29:47Z",
    "updatedAt": "2018-04-06T09:34:40.142Z"
}

List a similar offer

If you have listed an offer and want to list a similar one, retrieve it via GET /sale/offers/{offerId}. Use GET on /sale/offers/{offerId} to retrieve all fields of the particular offer. You must be authenticated and authorized as a seller that listed the offer in question. The whole structure apart from:

  • offer ID

  • last offer validation

  • offer creation date

  • last offer update

  • “publication” section

transfer via POST /sale/offers. Therefore, you will create a new draft offer based on data of the retrieved offer. Once you complete the draft, you can edit the structure retrieved via GET /sale/offers/{offerId}.

9. Publish your offer

Once the offer is complete and properly validated, use PUT /sale/offer-publication-commands/{commandId} to publish the offer on the site. It is an asynchronous method. In commandId provide the value in the UUID (universally unique identifier) format. It is a globally unique identifier that consists of 32 hexadecimal numbers (e.g. 21ae4ed1-eab7-34ea-b605-cf2e22b5eed3). Remember to implement the mechanism for generating UUIDs in your software.
Note! Use this resource to:

  • end particular offers, by providing END in the action field

  • schedule offers, by providing the listing date in the scheduleFor field

  • relist a finished offer - (status ENDED) with ‘ACTIVATE’ value in action filed in PUT /sale/offer-publication-commands/{commandId}. Such an offer will be once again available in Allegro.


Sample request:

  curl -X PUT \
    'https://api.allegro.pl/sale/offer-publication-commands/{commandId}
    -H 'Authorization: Bearer {token}' \
    -H 'Accept: application/vnd.allegro.public.v1+json' \
    -H 'Content-Type: application/vnd.allegro.public.v1+json' \
    -d '{
    "publication": {
        "action": "ACTIVATE",               -- required, two values are supported:
                                               ACTIVATE (offer activation)
                                               and END (offer end)
        "scheduledFor":"2018-03-28T12:00:00.000Z"   -- not required, provide it, if you
                                               want to schedule the publication
                                               for a later date
    },
    "offerCriteria": [
        {
            "offers": [                     -- required; an array of objects with offer
											IDs, maximum of 1000 offers
                {
                    "id": "7276377308"
                }
            ],
            "type": "CONTAINS_OFFERS"       -- required, at present only one
                                               value is supported: CONTAINS_OFFERS
                                               (offers with status to be changed)
        }
    ]
  }
Sample response:
  {
    "id": "3380d97f-0d32-4747-8a17-1da38f9499de",
    "taskCount": {
        "total": 0,
        "success": 0,
        "failed": 0
    }
  }

10. Check offer status

To check the status of a task you ordered in Step 7 (listing or ending an offer) use:

Task list

GET /sale/offer-publication-commands/{commandId}

Use this resource to retrieve information about the offer listing statuses. You will receive a summary with a number of correctly listed offers and errors.
Sample request:

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

Sample response:
  {
    "id": "3380d97f-0d32-4747-8a17-1da38f9499de",
    "taskCount": {
        "total": 1,
        "success": 1,
        "failed": 0
    }
  }

Information about publication

GET /sale/offer-publication-commands/{commandId}/tasks

Use this resource to retrieve information about the offer statuses on the site. The response will contain:

  • IDs of offers you wanted to list on the site

  • offer editing status – whether it was successful

  • date of offer editing order

  • date of order execution – listing or ending an offer

Sample request:

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

Sample response:
  [
    {
            "offer": {
                "id": "7168735300"
            },
            "message": "",                    -- explanation why it failed to list the offer
            "status": "SUCCESS",              -- offer listing status; three values are supported:
                                              SUCCESS (publication was successful,
                                              the offer should be active within 60 minutes);
                                              FAIL (errors have occurred and the offer
                                              is inactive); NEW (offer is being listed,
                                              the action is in progress)
            "scheduledAt": "2018-03-01T11:02:50.005+01:00",
            "finishedAt": "2018-03-01T11:02:51.691+01:00",
            "field": "publication"
      }
    ]

Questions and answers

1. How can I list an auction with the Buy it Now option?

To list such offers, transfer AUCTION in the “format” field and fill out:

  • startingPrice - starting price

  • minimalPrice - reserve price. This field is not required.

2. Why has the draft been introduced?

Drafts allows you to start working on an offer and finish it whenever it suits you, e.g. when you want to provide the final version of the content. However, you can complete the draft immediately, without saving it for later, and list the offer.

3. Why have you introduced a separate resource for images?

You can present high-resolution images within your offer. However, such files have a significant size. For this reason, we have introduced a separate resource for images in order to decrease the request size. As a result, offers are listed faster.

4. Why have you introduced a separate resource for shipping price lists?

As shipping price lists are not linked to an offer, with a separate resource bulk editing of shipping price lists is much faster. Just edit the price list, and the cost will be updated in all offers to which the price list is linked. Therefore, you can react immediately to any changes introduced by the courier companies.

5. How can I schedule an offer?

Set the listing date by calling PUT on /sale/offer-publication-commands/{commandId}. Just provide the listing date in the scheduledFor field.

6. I got a message - “You cannot create new drafts - your account has exceeded the maximum number {maxInactiveOffers} of drafts.” - What should I do?

You received this message because you exceeded the limit of drafts (offers with the status “INACTIVE”). To solve this problem:

7. I receive error 401 Unauthorized with a message “Empty user_name claim” when I try to create an offer draft. What does it mean?

You are using token from client_credentials type of authorization with no user context. To create an offer draft you should use token generated via code or device flow.

8. I receive error 422 when I try to create an offer draft. What does it mean?

Make sure the structure of your request is valid and you properly provide all of the values. You can find a sample request in our guide.

9. When I try to activate offers via PUT /sale/offer-publication-commands/{commandId} I receive zeros in the response. Is this the proper behavior?

Yes, this is because this resource is running asynchronously. Use GET /sale/offer-publication-commands/{commandId}/tasks to check detailed task status.

10. I am providing the completed location field in my request, but in the response I receive null. What am I doing incorrectly?

Make sure that in addition to the correctly completed location field, you also provide values for delivery.shippingRates and sellingMode.

10. I receive error 422 in the response with a message “Description images are not valid”. What does it mean?

Make sure that the image links that you pass in the description section are also provided in the images section.

List of resources

Full documentation of resources in the form of swagger.yaml file you will find here.

List of basic resources used in tutorial:

List of supporting resources used in tutorial: