Billing operations

With GET /billing/billing-entries you will retrieve list of billing operations and balance of the authorized user.

By default, you will retrieve list of 100 billing entries, where the first result is the newest. You can adjust the list to your needs using the following parameters:

  • limit - define a number of returned billing entries, max value is 100,

  • offset - define an index of first returned billing entry.

e.g. GET /billing/billing-entries?limit=50&offset=25 will return 50 billing entries from defined point.

You can also use filters:

  • date of the billing operation - you can filter billing entries date using parameters:

    • occurredAt.gte (minimum date and time when the billing operation occured in ISO 8601 format),

    • occurredAt.lte (maximum date and time when the billing operation occured in ISO 8601 format),

e.g. GET /billing/billing-entries?occurredAt.gte=2019-07-10T11:06:50.935Z&occurredAt.lte=2019-07-15T11:06:50.935Z,

  • type of the billing operation - check, which type.id is associated with name.id (name of the operation) - detailed list of available billing entries types you can retrieve by GET /billing/billing-types. Pass type.id as a parameter value to get the results you are interested in, e.g. GET /billing/billing-entries?type.id=SUC will return all results that relate to sales commision,

  • offer id - e.g. GET /billing/billing-entries?offer.id=8566354406 - will return all billing operations associated with the passed offer.


Sample request:

  curl -X GET
  https://api.allegro.pl/billing/billing-entries?occurredAt.gte=2019-10-10T00:00:00.000Z&occurredAt.lte=2019-10-10T23:59:59.000Z
  -H ‘Authorization: Bearer {token}’ /
  -H ‘Accept: application/vnd.allegro.public.v1+json’ /
  -H ‘Content-Type: application/vnd.allegro.public.v1+json’

Sample response:

  {
    "billingEntries": [
        {
            "id": "da74ef80-f97a-4b04-a748-4c129cfb94b8",   -- billing entry ID
            "occurredAt": "2019-10-10T10:27:17.412Z",       -- date of billing entry
            "type": {
                "id": "LIS",                                -- three-letter code of the billing type
                "name": "Wystawienie przedmiotu"            -- name of the billing type
            "offer": {
                "id": "6206586563",                         -- offer ID
                "name": "oferta testowa"                    -- offer title
            },
            "value": {
                "amount": "-1.00",
                "currency": "PLN"
            },
            "tax": {
                "percentage": "0",                          -- tax rate
                 "annotation": "EXEMPT"                     -- additional field - returned if the
                                                            billing entry is exempt from tax
                                                            (“EXEMPT”)  or tax is not applicable
                                                            ("NOT_APPLICABLE")
            },
            "balance": {
                "amount": "-737.57",                        -- balance after the operation
                "currency": "PLN"
            }
        }
    ]
  }

Using GET /billing/billing-entries resource you will also get the order number, which we will return in the “order.id” field. Thanks to this, you will be able to identify the order for which the fee was collected in the billing operations history.

information NOTE! We will return the value in the “order.id” field for all billing types in which we show the order number. For the other billing types we will not return the “order” object.

Sample response:

...
{    
    "id": "f2b843f1-8fa3-45a6-98f7-0590cd8d39d2",
    "occurredAt": "2020-09-07T10:47:19.981Z",
    "type": {
        "id": "SUC",
        "name": "Sales commission"
    },
    "offer": {
        "id": "9608631866",
        "name": "oferta testowa"
    },
    "value": {
        "amount": "-10.10",
        "currency": "PLN"
    },
    "tax": {
        "percentage": "23"
    },
    "balance": {
        "amount": "-113.53",
        "currency": "PLN"
    },
    "order" : {
        "id" : "726c25e0-f0f7-11ea-887c-8753d63d8e79"
    }
...
 }

Payment operations

With GET /payments/payment-operations you will retrieve list of payment operations of the authorized user.

By default, you will retrieve list of 100 payment entries, where the first result is the newest. You can adjust the list to your needs using the following parameters:

  • limit - define a number of returned payment operations, max value is 100,

  • offset - define an index of first returned payment operation.

You can also use filters:

  • date of the payment operation - you can filter billing entries date using parameters:

    • occurredAt.gte (minimum date and time when the payment operation occured in ISO 8601 format)

    • occurredAt.lte (maximum date and time when the payment operation occured in ISO 8601 format),

e.g. GET /payments/payment-operations ?occurredAt.gte=2019-07-10T11:06:50.935Z&occurredAt.lte=2019-07-15T11:06:50.935Z,

  • payment id - e.g. GET /payments/payment-operations?payment.id=ca3871d1-ec01-11e9-bc5f-3de157f9f689,

  • buyer’s login - e.g. GET /payments/payment-operations?participant.login=participant. In case of REFUND_INCREASE operation this is the login of the seller, in other cases, of the buyer.

  • group of operation types - e.g. GET /payments/payment-operations?group=INCOME. Allowed values are: INCOME, OUTCOME, REFUND or BLOCKADES,

  • payment operator - e.g. GET /payments/payment-operations?wallet.operator=PAYU,

  • availability for payout - e.g. GET /payments/payment-operations?wallet.type=AVAILABLE will return operations available for payout, value WAITING means it is temporarily suspended for payout.


Sample request:

  curl -X GET
  https://api.allegro.pl/payments/payment-operations?group=INCOME&limit=1
  -H ‘Authorization: Bearer {token}’ /
  -H ‘Accept: application/vnd.allegro.public.v1+json’ /
  -H ‘Content-Type: application/vnd.allegro.public.v1+json’

Sample response:

  {
    "paymentOperations": [
        {
            "type": "CONTRIBUTION",                             -- type of the operation
            "group": "INCOME",                                  -- operation type group
            "wallet": {
                "paymentOperator": "PAYU",                      -- payment operator
                "type": "AVAILABLE",                            -- availability for payout
                "balance": {
                    "amount": "3297.81",                        -- balance after the operation
                    "currency": "PLN"
                }
            },
            "occurredAt": "2019-10-11T08:33:40.650Z",           -- date of the operation
            "value": {
                "amount": "144.00",
                "currency": "PLN"
            },
            "payment": {
                "id": "ca3871d1-ec01-11e9-bc5f-3de157f9f689"    -- payment id
            },
            "participant": {                                    -- buyer’s details
                "id": "44182721",
                "companyName": "Allegro.pl Sp. z o.o.",
                "login": "exampleLogin",
                "firstName": "",
                "lastName": "",
                "address": {
                    "street": "Grunwaldzka 1822",
                    "city": "Poznań",
                    "postCode": "60-166"
                }
            }
        }
    ],
    "count": 1,                                                 -- visible results
    "totalCount": 31                                            -- available results
  }         

Fee calculator

The fee calculator allows sellers to check what fees we charge within a given category or for a specific offer. The fee calculator returns data for an authorized user.

Use POST /pricing/offer-fee-preview to check what fees will be charged for a specific offer. In your request, provide full offer data in the offer structure. You can retrieve the offer data via GET /sale/offers/{offerId}.


Click to view sample request:
curl -X POST 
https://api.allegro.pl/pricing/offer-fee-preview
-H 'Accept: application/vnd.allegro.public.v1+json'
-H 'Content-Type: application/vnd.allegro.public.v1+json'
-H 'Authorization: Bearer {token}'
-H 'Accept-Language: PL'
-d '{ "offer": { "name": "Sample offer", "category": { "id": "79419" }, "product": null, "parameters": [ { "id": "11323", "valuesIds": [ "11323_246514" ], "values": [], "rangeValue": null }, { "id": "223489", "valuesIds": [], "values": [ "Autor" ], "rangeValue": null }, { "id": "223541", "valuesIds": [ "223541_491585" ], "values": [], "rangeValue": null }, { "id": "223545", "valuesIds": [], "values": [ "Sample" ], "rangeValue": null }, { "id": "245669", "valuesIds": [], "values": [ "9780000000057" ], "rangeValue": null }, { "id": "74", "valuesIds": [], "values": [ "2015" ], "rangeValue": null }, { "id": "7773", "valuesIds": [ "7773_2" ], "values": [], "rangeValue": null } ], "customParameters": null, "ean": "9780000000057", "description": { "sections": [ { "items": [ { "type": "TEXT", "content": "<p>Sample description</p>" } ] } ] }, "compatibilityList": null, "tecdocSpecification": null, "images": [ { "url": "https://a.allegroimg.allegrosandbox.pl/original/116421/ece7111d4b8fbbc4662ab92f84ce&#34; } ], "sellingMode": { "format": "BUY_NOW", "price": { "amount": "50", "currency": "PLN" }, "startingPrice": null, "minimalPrice": null, "netPrice": null }, "tax": null, "stock": { "available": 1, "unit": "UNIT" }, "publication": { "duration": null, "status": "ACTIVE", "startingAt": null, "endingAt": null, "endedBy": null, "republish": false }, "delivery": { "shippingRates": { "id": "17221a3c-f4cf-4e47-953a-8e125013b014" }, "handlingTime": "PT336H", "additionalInfo": "", "shipmentDate": null }, "payments": { "invoice": "NO_INVOICE" }, "discounts": null, "afterSalesServices": { "impliedWarranty": { "id": "f86078a6-9f42-4b76-9696-1e5c0646a60a" }, "returnPolicy": { "id": "47101223-7236-4201-9779-316e6d10af2a" }, "warranty": null }, "additionalServices": null, "sizeTable": null, "fundraisingCampaign": null, "promotion": { "emphasized": true, "bold": false, "highlight": false, "departmentPage": false, "emphasizedHighlightBoldPackage": false }, "location": { "countryCode": "PL", "province": "WIELKOPOLSKIE", "city": "Poznań", "postCode": "66-166" }, "external": null, "attachments": [], "contact": null, "validation": { "errors": [], "warnings": [], "validatedAt": "2020-12-04T09:31:07.684Z" }, "createdAt": "2020-10-01T05:44:23.000Z", "updatedAt": "2020-12-04T09:31:08.925Z" } } '


Click to view sample response:
{
    "commissions": [                                      – commission fee
        {
            "name": "Prowizja od sprzedaży",              – name of the commission
            "type": "commissionFee",                      – type of the fee
            "fee": {
"amount": 2.50, – commission amount "currency": "PLN" } }, { "name": "Prowizja od sprzedaży oferty wyróżnionej", "type": "commissionFeatureFee", "fee": { "amount": 200.00, "currency": "PLN" } } ], "quotes": [ – fee { "name": "Wystawienie przedmiotu", – name of the fee "type": "listingFee", – type of the fee "fee": { "amount": 0.15, – fee amount "currency": "PLN" }, "cycleDuration": "PT240H", – information in what cycles we will charge the fee "classifiedsPackage": { "id": null } }, { "name": "Opłata za wyróżnienie", "type": "distinctionFee", "fee": { "amount": 12.00, "currency": "PLN" }, "cycleDuration": "PT240H", "classifiedsPackage": { "id": null } } ] }

Check when a fee is charged

As of August 2017, fees will be charged every 10 days. Therefore, we provide you with a resource that will help you check when a fee is charged.

  • GET /pricing/offer-quotes - is a resource that you can check when a given cycle ends and we charge another fee. You must be logged in as a seller who listed the offers.


Note! You can provide up to 20 offer numbers.


Sample request:

  curl -X GET \
  'https://api.allegro.pl/pricing/offer-quotes?offer.id=7617492560,7794910978' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Accept-Language: PL' \
  -H 'Authorization: Bearer {token}' \

Click to view sample response:
{
    "count": 3,                                         – number of fees
    "quotes": [
        {
            "type": "LISTING",                          – fee type, at present following values
                                                           LISTING,
                                                           BOLD,
                                                           HIGHLIGHT,
                                                           EMPHASIZED,
                                                           EMPHASIZED_HIGHLIGHT_BOLD_PACKAGE,
                                                           DEPARTMENT_PAGE, MIN_PRICE,
                                                           BARGAIN
                                                           INEFFECTIVE_LISTING_FEE
            "name": "Wystawienie",                      – fee name, at present following
                                                        values are available:
                                                           Wystawienie,
                                                           Pogrubienie,
                                                           Podświetlenie,
                                                           Wyróżnienie,
                                                           Pakiet promo,
                                                           Strona działu,
                                                           Cena minimalna,
                                                           Okazja
                                                           Utrzymaniowa
            "nextDate": "2019-01-24T15:41:33.112Z",     – date of charging a listing fee
            "fee": {
                "amount": "0.00",                       – amount to be charged
                "currency": "PLN"                       – currency
            },
            "offer": {                                  – offer subject to payment
                "id": "7617492560"                      – offer ID
            },
            "enabled": true                             – fee status
        },
        {
            "type": "EMPHASIZED",
            "name": "Wyróżnienie",
            "nextDate": "2019-02-01T09:50:05.135Z",
            "fee": {
                "amount": "19.00",
                "currency": "PLN"
            },
            "offer": {
                "id": "7794910978"
            },
            "enabled": true
        },
        {
            "type": "LISTING",
            "name": "Wystawienie",
            "nextDate": "2019-02-01T09:50:05.135Z",
            "fee": {
                "amount": "0.00",
                "currency": "PLN"
            },
            "offer": {
                "id": "7794910978"
            },
            "enabled": true
        }
    ]
}

List of resources

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

List of basic resources used in tutorial:

List of supporting resources used in tutorial: