Quickstart

1. Create a sandbox key

Open Integrations in the tenant administration, create a test API key, and store it securely right away. The complete key is displayed only once.

export EASYPICK_API_KEY='ep_test_PUBLIC_ID_SECRET'
export EASYPICK_API_URL='https://sandbox-api.easypick.cz/v1'

2. Select a box

curl --fail-with-body \
  --header "Authorization: Bearer $EASYPICK_API_KEY" \
  "$EASYPICK_API_URL/boxes"

The response only contains active boxes belonging to your tenant:

{
  "items": [
    {
      "id": "box_01k3example",
      "name": "Prague 1 Box",
      "location_name": "Main entrance",
      "address": "Dlouha 1, Prague"
    }
  ]
}

3. Reserve a compartment

external_order_id also acts as the idempotency key. Repeating the same request for the same box returns the original shipment and PIN.

curl --fail-with-body \
  --request POST \
  --header "Authorization: Bearer $EASYPICK_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "box_id": "box_01k3example",
    "external_order_id": "ORDER-2026-1042",
    "customer_name": "Jane Smith"
  }' \
  "$EASYPICK_API_URL/shipments"

A new reservation returns HTTP 201:

{
  "id": "shipment_01k3example",
  "external_order_id": "ORDER-2026-1042",
  "attempt_number": 1,
  "retry_of_shipment_id": null,
  "box_id": "box_01k3example",
  "compartment_code": "A2",
  "customer_name": "Jane Smith",
  "status": "reserved",
  "compartment_state": "reserved",
  "pickup_enabled": false,
  "reservation_expires_at": "2026-08-03T10:00:00Z",
  "loaded_at": null,
  "pickup_available_at": null,
  "pickup_expires_at": null,
  "picked_up_at": null,
  "updated_at": "2026-08-02T10:00:00Z",
  "pickup_pin": "418205"
}

4. Simulate loading

The sandbox can advance a shipment deterministically without a physical box:

curl --fail-with-body \
  --request POST \
  --header "Authorization: Bearer $EASYPICK_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"event":"loaded"}' \
  "$EASYPICK_API_URL/sandbox/shipments/shipment_01k3example/events"

Continue with picked_up and door_available. See Sandbox for all supported transitions.

PHP 8.2+

<?php
$response = file_get_contents(
    getenv('EASYPICK_API_URL') . '/boxes',
    false,
    stream_context_create(['http' => ['header' => [
        'Authorization: Bearer ' . getenv('EASYPICK_API_KEY'),
        'Accept: application/json',
    ]]])
);
$boxes = json_decode($response, true, flags: JSON_THROW_ON_ERROR);

Node.js 20+

const response = await fetch(`${process.env.EASYPICK_API_URL}/boxes`, {
  headers: { Authorization: `Bearer ${process.env.EASYPICK_API_KEY}` },
});
if (!response.ok) throw new Error(await response.text());
const { items: boxes } = await response.json();