Listing offers through Allegro REST API

Offer model

1. Prepare a draft

First, create a draft by calling the POST /sale/offers. The draft does not have to be a complete offer ready for publishing. 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 data on offers on our servers,

  • prepare an offer preview.


2. List an offer

A complete draft (with INACTIVE status) that displays no errors in the section “validation”. 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 auction – a proper error message will be displayed in the section “validation”.

Then you can publish the draft on Allegro.pl. To activate the draft, perform ACTIVATE on PUT /sale/offer-publication-commands/{commandId} (the offer status will be ACTIVATING until the offer is published on the site. The same status is applied to offers with 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 field scheduledAt of the GET /sale/offer-publication-commands/{commandId}/tasks. Use the same method to close an offer by performing END.

List an offer in a few steps

Note! All requests must be executed with OAuth 2.0 token

Add the following elements:

Offer terms - Describe terms of return policy, complaints policy and warranty information. Policy of return 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 table - Owing to size tables buyer will can find details about sizes always in the same section on the offer page. You can create Size tables in My Allegro in tab Tabele rozmiarów.

1. Required data

Use supportive methods to retrieve ID of elements. You can transfer the IDs later to 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"           amout 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 PUT /sale/delivery-settings. You will find more information about new resources in our documentation.

Shipping price

Use GET /sale/delivery-methods to retrieve IDs and names of shipping methods 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 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"
}

If a seller has shipping price lists, you can retrieve their list via GET /sale/shipping-rates?seller.id={Seller_ID}. Use shipping price list ID to list a new offer.

Sample request:

  curl -X GET \
  'https://api.allegro.pl/sale/shipping-rates?seller.id={Seller_ID}' \
  -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łegro 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

Return policies

How to add return policy information

Use POST /after-sales-service-conditions/return-policies to add new return policy. Provide in the request structure:

  • name - required, return policy name,
  • availability.range - required, buyer’s option to withdraw/terminate the agreement:
    • FULL - is possible,
    • RESTRICTED - not possible or restricted under selected condition,
  • availability.restrictionCause.name - required, if you choose 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 sealed packaging of a sound, video recording or computer software (provision of the Act).
SEALED_ITEM_NO_RETURN_DUE_HEALTH_OR_HYGIENE 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 (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 which has a short use by date (provision of the Act).
INSEPARABLY_LINKED where the objects of the service are items which, after delivery, due to their characteristics, remain 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 entrepreneur’s control (provision of the Act).
PRESS buys daily papers, periodicals or magazines (provision of the Act).
FULLY_IMPLEMENTED_SERVICE the service offered has been performed in full upon explicit consent of the buyer, who was advised before by the seller 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 other than for residential purposes, 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, 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 (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 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?seller.id={seller.id} you can retrieve return policies assigned to your account. In the response you will receive a list of 60 return policies, which contains dentifier and the name of the return policy. You can adjust the list using filters:

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

If you want to retrieve details of the return 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 return policy information

To update return 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 don’t want to provide it, pass null value,
  • address - required, address for complaints,
  • description - not required, description of 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?seller.id={seller.id} you can retrieve complaints policies assigned to your account. In the response you will receive a list of 60 complaints policies, which contains identifier and the name of the complaints policy. You can adjust the list to your needs using filters:

  • limit - number of results in the response. The default and maximum value is 60,
  • offset - index of 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 attachment to warranty information

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

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 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 a warranty information in the attachment field. We described this process 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, 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 the contact 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?seller.id={seller.id} you can retrieve return policies assigned to your account. In the response you will receive a list of 60 return policies, which contains the identifier and the name of the return policy. You can adjust the list to your needs using filters:

  • limit - number of results in the response. The default and maximum value is 60,
  • offset - index of 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?user.id={Seller_ID}.

Size tables

Retrieve it via:

More information about Size Tables you will find our news.

Contact details

Retrieve it via GET /sale/offer-contacts?seller.id={Seller_ID}.

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 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,
	}
  }]
 }

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,
        "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.
        },
        "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,
        "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,
        "options": {
            "variantsAllowed": false,
            "variantsEqual": false,
            "ambiguousValueId": "216917_41", -- identifier for ambiguous value,
                                            e.g. "other"
            "dependsOnParameterId": null
        },
        "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 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 parameter values

You can define custom value for parameters with ambiguous value in selected categories. Use this option if you don’t find the appropriate parameter value. Ambiguous value if for example “other” in the parameter “Brand”. 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,
        "options": {
            "variantsAllowed": false,
            "variantsEqual": false,
            "ambiguousValueId": "129033_13"      	-- identifier for ambiguous value,
                                                    in this case it is “other”
        },
        ...
   }
 

After that, when you creating draft or editing offer, provide 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 photos

Use POST /sale/images to upload photos to our servers and receive suitable links using HTTP and HTTPS protocols (only with a valid certificate) . Important! More information about rules for photos in 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, photo 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 big

  • 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 photo
	}

4. Offer title

We allow maximum 50 characters in the offer title. A list of letters, numbers and special characters that we allow to enter in offert title you can find below.

	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 entity, therefore they take more than one character. For example the & is represented as & so it takes 5 places in the title.

5. Offer content

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

Note

  • 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 - w 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 offer tags to your published offer. However, first check the tags you have saved to your account. Retrieve themviaGET /sale/offer-tags?user.id={sellerId}. 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?user.id={userId}&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?user.id={userId} \
    -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 can 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. It means if you want to remove tags from offers and do not assign any new, call the resource and transfer an empty tags structure in the message 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 – per one from the list:

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

  • Instrukcję gry (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. GOnce 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 during 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 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 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 receive a message - “You cannot create new drafts - your account has exceeded the maximum number 20 000 of drafts.” Delete unnecessary with DELETE /sale/offers/{offerId}.
  • Offer draft is storage for 60 days. After that offer draft will be deleted. If you edit something in 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,
    "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"
    },
    "afterSalesServices": null,
    "additionalServices": null,
    "sizeTable": 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 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
        }
    ],
    "ean": "6901443187416",                         -- not required, EAN code
    "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"
        },
        "startingPrice": null,                      -- starting price, available in AUCTION (auction)
        "minimalPrice": null                        -- reserve price, available in AUCTION (auction)
    },
    "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?seller.id={Seller_ID}.
                                                    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)
    },
    "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?user.id={Seller_ID}
    "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
        }
    ],
    "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"
        },
        "startingPrice": null,
        "minimalPrice": null
    },
    "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"
    },
    "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,
    "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 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; 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,
                                              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 photos?

You can present high resolution photos within your offer. However, such files have a significant size. For this reason, we have introduced a separate resource for photos 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 limit of drafts (offers with the status “INACTIVE”). To solve this problem: