Shipments

Physical goods need a shipping address, and once they are sent you record a shipment: Anikeen ID adds a delivery note to the user's order documents and tells the user.

Ordering physical goods

Pass a shipping address with first_name, last_name, address, postal_code, city and country_iso (optional: company_name, house_number, address_2, state, phone_number, email), or a shipping_address_id:

$order = $user->orders()->create([
    'billing_address_id' => $addressId,
    'shipping_address' => [
        'first_name' => 'Ada', 'last_name' => 'Lovelace',
        'address' => 'Main St', 'house_number' => '1',
        'postal_code' => '10115', 'city' => 'Berlin', 'country_iso' => 'DE',
    ],
    'items' => [
        ['type' => 'physical', 'name' => 'T-shirt', 'unit' => 'piece', 'units' => 1, 'gross_price' => '24.90', 'image_url' => 'https://shop.example.com/img/shirt.png'],
        ['type' => 'physical-reduced', 'name' => 'Artbook', 'unit' => 'piece', 'units' => 1, 'gross_price' => '19.95'],
    ],
]);

The user can change both addresses on the confirmation page (a new billing country recalculates the VAT; items sold at a gross price keep it). Read the shipping address from the order (or the order.completed webhook) before you ship.

Recording a shipment

Once a paid order is sent:

POST /api/v1/orders/{order}/shipments
Authorization: Bearer USER_TOKEN

{
  "carrier": "DHL",
  "tracking_number": "00340434161234567890",
  "tracking_url": "https://www.dhl.de/…?piececode=00340434161234567890"
}

Field
carrier	optional, at most 100 characters
tracking_number	optional, at most 100 characters
tracking_url	optional http(s) URL
note	optional, at most 1000 characters
shipped_at	optional date, not in the future
notify_customer	false if your shop sends its own mail (default: Anikeen ID mails the user)
items	optional: [{order_item_id, units}] for a partial delivery; without it everything physical that is left is shipped

Anikeen ID then

• creates a delivery note (LS-2026-0001) in the user's order documents, with the tracking link,
• mails it to the user (unless notify_customer is false),
• sends order.shipped to your webhook endpoints, with the order's shipments.

Only the app that created the order (or a trusted app) can ship it, and only once it is paid.

Method	Path
GET	/api/v1/orders/{order}/shipments	the order's shipments
POST	/api/v1/orders/{order}/shipments	record a shipment
GET	/api/v1/orders/{order}/shipments/{shipment}	one shipment
GET	/api/v1/orders/{order}/shipments/{shipment}/delivery-note	the delivery note (PDF)

$order = $user->orders()->find($orderId);

$shipment = $order->shipments()->create([
    'carrier' => 'DHL',
    'tracking_number' => '00340434161234567890',
    // 'items' => [['order_item_id' => $itemId, 'units' => 1]],
]);

$shipment->number;          // LS-2026-0001
$shipment->deliveryNote();  // the delivery note as PDF

What is left to ship?

Compare the order's items with its shipments:

$items = $order->orderItems()->toArray();     // id, type, name, units, …
$shipments = $order->shipments()->toArray();  // each with items: [{order_item_id, units}]