Getting started

Create an API token and read your stock with one request. It takes about five minutes.

Create a token

1. In Picked, go to Settings → Developers → API tokens. Issuing a token takes the permission to edit processes, which owners, admins and managers have.
2. Give the token a name that says which integration uses it, for example webshop-stock.
3. Tick the ability stock:read and choose Issue token.
4. Copy the token straight away. Picked shows it once and never again.

Keep the token in your integration's secret store, not in its code. The examples on these pages read it from the environment variable PICKED_TOKEN:

export PICKED_TOKEN="paste-your-token-here"

Make your first call

Pick the SKU of a product in your workspace and ask for its stock:

curl "https://picked.nl/api/v1/stock?sku=YOUR-SKU" \
  -H "Authorization: Bearer $PICKED_TOKEN" \
  -H "Accept: application/json"

Picked answers with the product's stock, in total and per warehouse:

{
    "sku": "BEL-ZW-01",
    "quantity": 64,
    "reserved": 6,
    "available": 58,
    "sellable": 52,
    "warehouses": [
        {
            "code": "UTR",
            "quantity": 64,
            "reserved": 6,
            "available": 58,
            "sellable": 52
        }
    ],
    "_links": {
        "self": { "href": "/api/v1/stock?sku=BEL-ZW-01" }
    }
}

sellable is the figure to publish to a webshop or marketplace: stock in selling locations, minus what accepted orders have already claimed. available is everything on hand minus what pickers have reserved. A SKU Picked doesn't know answers 404 with the code not_found.

Find your warehouse ids

Writes such as POST /api/v1/orders and POST /api/v1/receipts name a warehouse by its warehouse_id. List your warehouses to look the ids up; any API token may, whatever its abilities:

curl "https://picked.nl/api/v1/warehouses" \
  -H "Authorization: Bearer $PICKED_TOKEN" \
  -H "Accept: application/json"

{
    "data": [
        {
            "id": 12,
            "code": "UTR",
            "name": "Utrecht"
        }
    ],
    "_links": {
        "self": { "href": "/api/v1/warehouses" }
    }
}

The code is the one stock answers name the warehouse by. The API tokens page shows the same ids, by warehouse name, next to the base URL. GET /api/v1/locations lists your locations the same way, a page at a time, with the location_id that stock changes filter by.

The same call in PHP or JavaScript

PHP, with the curl extension that ships with PHP:

<?php

$curl = curl_init('https://picked.nl/api/v1/stock?sku=' . rawurlencode('YOUR-SKU'));
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('PICKED_TOKEN'),
        'Accept: application/json',
    ],
]);

$body = json_decode((string) curl_exec($curl), true);
$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);

echo $status === 200
    ? "Sellable: {$body['sellable']}\n"
    : "Error {$status}: {$body['code']}\n";

JavaScript, on Node.js 18 or later (save it as stock.mjs and run node stock.mjs):

const response = await fetch('https://picked.nl/api/v1/stock?sku=YOUR-SKU', {
    headers: {
        Authorization: `Bearer ${process.env.PICKED_TOKEN}`,
        Accept: 'application/json',
    },
});
const body = await response.json();

console.log(
    response.ok
        ? `Sellable: ${body.sellable}`
        : `Error ${response.status}: ${body.code}`,
);

Next steps

• Authentication & abilities: which ability each endpoint needs, and how to rotate a token.
• Errors: every error code and what your integration should do with it.
• Rate limits: how many calls you can make, and what to do past the limit.
• API reference: every endpoint with its parameters and responses.