How to create an API token
Want to pull data from Salecare into your own spreadsheet, data warehouse or BI tool such as Power BI? That is what API tokens are for. A token authenticates your tool and lets it fetch data through the API, without signing in and without giving anyone your password. You issue it once and plug it into the integration.
Step 1. Open the API tokens page
In the side menu click Settings, then the API tokens row in the Integrations group. It opens the API tokens page in Settings, with the company's tokens. The page opens for a person with the Integrations (accounts, API tokens) permission. That person sees the tokens of the whole company on it and can revoke any of them. API access is included in the Pro plan and above. On a lower plan the Create token button is disabled, and hovering over the padlock icon beside it shows the plan you need.
Step 2. Issue a new token
Click Create token beside the title of the page. The New token form appears. In the Name field enter a name you will recognise the token by, the name of the tool that will use it, for example. Under Scopes tick what the token may do.
There are four reading scopes, namely margin and aggregates, orders, offers, and commissions with commission refunds. Tick only the scopes the tool needs. A request to an address outside the token's scopes gets the code 403, and a narrow token does less harm if it leaks. The Expires at (optional) field is pre-filled a year ahead. The token stops working at 00:00 on the day you pick, not at its end. Pick another day, or click Clear date beside the field for a token that runs until it is revoked. A second click on Create token saves the token.
A token works with the permissions of the person who created it. The scope list shows only the areas your own role gives access to. If someone narrows your permissions later, the token at once stops returning data from those areas. When an account is removed from the company, the tokens it issued are revoked automatically.
Step 3. Copy the token straight away
The page shows the new token's secret only once, until you leave it. Copy it now with the Copy button and save it somewhere safe, in a password manager for example, because it will not be shown again. The list on the page shows live tokens first, the soonest end at the top, then expired and revoked ones. Next to a token you will later see its name, scopes, status and expiry date, but never the full token. Treat a token like a password and do not paste it into messages or shared documents.
Step 4. Plug the token into your tool
At the foot of the page sits the folded How to read data through the API section. Once opened, it shows a ready request with its headers and the address of every request together with the scope it needs and a description of the data it returns. It also shows the from, to and per_page parameters, what the codes in the responses mean, and the request limits and refusal codes. The token goes into the Authorization header after the word Bearer, because Salecare does not accept it in the request address. In Power BI the token therefore goes into the request header and is saved in the report file. Create a separate token for every tool and every person, and when the file reaches someone outside the company, revoke the token.
The state of an order, the status of an offer on Allegro and how an offer matches a product arrive as fixed text codes, for example awaiting_payment for an order waiting for payment, or ended for an offer that has ended. The offer list includes ended offers too. Every order and every offer names the Allegro account it comes from, and an offer also gives its Allegro offer number and SKU, so you can join the data of several accounts with Allegro's own data. Amounts arrive in grosze as whole numbers, and the response follows JSON:API, so the tool fetches the next page from the address in the links.next field.
Read the figures from the margin address the way that section describes them. The margin_cents field is the order margin after the purchase cost, shipping, commission, other Allegro fees, returns, promotion and ads, not the profit. The operating costs and the account fees arrive in their own fields and are not taken off it, and the API does not return the fixed costs. The profit in the Profit & loss statement will therefore be lower. Commission, other Allegro fees and the return impact arrive as negative numbers, and the purchase cost, shipping, promotion, ads, operating costs and account fees as positive ones. So do not work the margin out again by taking all these fields off the revenue, use the margin_cents field instead. Amounts are gross. When your company is registered for VAT, Salecare shows net amounts on its screens, so use the net_revenue_cents, net_purchase_cost_cents and net_margin_cents fields in your report. The meta.money_basis field says which amounts you see in Salecare, net (net) or gross (gross).
Step 5. Replace or revoke a token
Every issued token is in the list on the page with an "Active", "Expired" or "Revoked" status. When you stop working with a tool, or suspect a token has leaked, click Revoke next to it and confirm with the Revoke token button. The token is rejected immediately, and every integration that used it loses access. You can revoke an expired token too, and the list then shows it as "Revoked".
Before the expiry date, create a new token and replace the old one in the integration, because from 00:00 on that day every request with the old token gets the code 401. Salecare does not remind you that a token is about to expire, so put the date in your own calendar. Tokens also stop working after a move to a plan without API access, or while the account is locked for non-payment, and work again once access is back. A request with the headers from that section gets the code 402 in the meantime.
What next
API tokens are available on the Pro plan and above. Check your plan on the Plan and billing page following the guide "How to manage your plan and invoices". Before you plug in BI, make sure the margin in the data is calculated with your costs. The guide "How to set up costs and margin to see your real Allegro profit" will help, and it also explains how the profit comes out of the margin.