Orders

Orders are what the platform ships from the orders page: the ones imported from your connected shops and marketplaces (Amazon, eBay, Shopify, WooCommerce, …) and the ones your own system pushes through the API. Both kinds are read from the same list.

Push orders

POST /orders — rate limit 30 / min

Sends up to 100 orders per call from your own system (ERP, shop, WMS). The orders appear in the platform under Import orders → Orders from API, exactly as if they had been imported from a CSV file, and are shipped from there by your operators. The endpoint carries the same data as the CSV import and applies the same defaults.

Use this endpoint when the people who ship work on the platform’s orders page. If your system creates the shipment itself and needs the label back, use POST /shipments instead.

Request body

Order object

Example

{
  "saveToAddressBook": false,
  "orders": [
    {
      "orderNumber": "ERP-1002",
      "orderDate": "2026-09-20",
      "recipient": {
        "name": "Giulia Russo",
        "address": { "street": "Via Appia 10", "city": "Roma", "province": "RM", "postalCode": "00183", "countryCode": "IT" },
        "phone": "+39 333 1234567",
        "email": "giulia@example.com",
        "reference": "CLI-77"
      },
      "senderReference": "MAG-A",
      "parcels": 1,
      "weight": { "value": 1.2, "units": "KG" },
      "cod": { "amount": 49.90 },
      "total": 49.90,
      "contentDescription": "Abbigliamento",
      "notes": "Citofonare Russo",
      "items": [
        { "sku": "TS-001", "quantity": 2, "unitPrice": 19.95 },
        { "sku": "BAG-9", "quantity": 1, "name": "Tote bag" }
      ]
    },
    {
      "orderNumber": "ERP-1001",
      "recipient": {
        "name": "Marco Verdi",
        "address": { "street": "Corso Italia 5", "city": "Milano", "province": "Milano", "postalCode": "20122" }
      }
    }
  ]
}

{
  "created": [
    {
      "id": 5120,
      "storeOrderId": "ERP-1002",
      "orderNumber": "ERP-1002",
      "reference": null,
      "storeId": null,
      "sourceId": 99,
      "marketplaceId": null,
      "recipient": { "address": { "city": "Roma", "province": "RM", "countryCode": "IT" } },
      "senderReference": "MAG-A",
      "parcels": 1,
      "weight": { "value": 1.2, "units": "KG" },
      "cod": { "amount": 49.9, "currency": "EUR" },
      "insurance": null,
      "total": 49.9,
      "subtotal": null,
      "shippingCost": null,
      "contentDescription": "Abbigliamento",
      "sku": null,
      "tags": [],
      "paymentStatus": null,
      "paymentGateway": null,
      "fulfillmentStatus": null,
      "isPrime": false,
      "isBusiness": false,
      "shipped": false,
      "confirmed": false,
      "archived": false,
      "trackingNumber": null,
      "hasError": false,
      "group": null,
      "itemsCount": 3,
      "firstItem": { "sku": "TS-001", "name": "Cotton T-shirt", "quantity": 2, "imageUrl": null },
      "orderDate": "2026-09-20T00:00:00+02:00",
      "latestShipDate": null,
      "createdAt": "2026-09-28T09:12:44+02:00"
    }
  ],
  "skipped": [
    { "index": 1, "orderNumber": "ERP-1001", "id": 5087 }
  ]
}

Response

201 Created when at least one order was created, 200 OK when every order in the call had already been sent.

Rules

• Only recipient.name, recipient.address.street, city and postalCode are required. Everything else takes the CSV import defaults: country IT, 1 parcel, 1 kg, today’s date, the company name as senderReference.
• The batch is validated as a whole: one invalid order rejects the entire call with 422 validation_failed, and nothing is saved. The keys of error.details name the order by its position: orders.1.recipient.address.postalCode.
• Two orders with the same orderNumber in the same call are a validation error.
• The batch is saved in one transaction: either all the valid orders are created or none is. You never have to work out which half of a batch went through.
• The recipient you send is stored and printed on the label, but is not returned by the API: created[].recipient holds only the destination.

Idempotency

orderNumber makes the call repeatable. An order number already sent by your account is not imported a second time: it is listed in skipped with the id of the existing order and the rest of the batch is processed normally. A call that timed out can simply be retried with the same payload.

List orders

GET /orders — paginated

curl "https://<subdomain>.spedisci.online/api/2026-09/orders?toShip=true&sort=-latestShipDate&per_page=100" \
  -H "Authorization: Bearer <access_token>" \
  -H "Accept: application/json"

Order object

{
  "id": 5120,
  "storeOrderId": "403-1111",
  "orderNumber": "403-1111",
  "reference": null,
  "storeId": 3,
  "sourceId": 4,
  "marketplaceId": "APJ6JRA9NG5V4",
  "recipient": { "address": { "city": "Milano", "province": "MI", "countryCode": "IT" } },
  "senderReference": "MAG-A",
  "parcels": 1,
  "weight": { "value": 1.5, "units": "KG" },
  "cod": null,
  "insurance": null,
  "total": 59.9,
  "subtotal": 49.9,
  "shippingCost": 10,
  "contentDescription": "Abbigliamento",
  "sku": "TS-001",
  "tags": ["urgent"],
  "paymentStatus": "paid",
  "paymentGateway": "amazon",
  "fulfillmentStatus": null,
  "isPrime": true,
  "isBusiness": false,
  "shipped": false,
  "confirmed": true,
  "archived": false,
  "trackingNumber": null,
  "hasError": false,
  "group": null,
  "itemsCount": 3,
  "firstItem": { "sku": "TS-001", "name": "Cotton T-shirt", "quantity": 2, "imageUrl": "https://..." },
  "orderDate": "2026-10-12T10:15:00+02:00",
  "latestShipDate": "2026-10-14T00:00:00+02:00",
  "createdAt": "2026-10-12T10:20:03+02:00"
}

Order detail

GET /orders/{id}

The Order object plus:

{
  "id": 5120,
  "...": "...",
  "items": [
    { "id": 90011, "itemId": "12345678", "sku": "TS-001", "asin": "B000000001", "name": "Cotton T-shirt", "quantity": 2, "unitPrice": 19.95, "total": 39.9, "imageUrl": "https://...", "variants": null }
  ],
  "packs": [
    { "number": 1, "weight": { "value": 1.5, "units": "KG" }, "dimensions": { "length": 30, "width": 20, "height": 10, "units": "CM" } }
  ],
  "shipments": [
    { "id": 4454058, "trackingNumber": "DEMO05407027", "status": { "code": 3, "key": "in_transit", "label": "In transito" }, "manifestId": 88213, "cost": { "amount": 7.0, "currency": "EUR" }, "createdAt": "2026-10-13T10:26:54+02:00" }
  ]
}

404 not_found when the order does not exist or belongs to another client.

Orders summary

GET /orders/summary?storeId=&from=&to=

Counters of the orders, overall and per shop. Without from / to every order is counted.

{
  "total": 412,
  "toShip": 37,
  "withError": 2,
  "shipped": 360,
  "archived": 15,
  "prime": 9,
  "stores": [
    { "storeId": 3, "sourceId": 4, "total": 300, "toShip": 30, "withError": 2, "shipped": 260, "archived": 10, "prime": 9 },
    { "storeId": null, "sourceId": 99, "total": 112, "toShip": 7, "withError": 0, "shipped": 100, "archived": 5, "prime": 0 }
  ]
}