Create Shipment

POST /api/3pl/{company}/order

Create a shipment from the option selected in /rates. Send the same address and inventory, plus the selected courier_id and payment transaction hash.

curl "https://www.dyli.io/api/3pl/$DYLI_3PL_COMPANY/order" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "x-api-key: $DYLI_3PL_API_KEY" \
  -d '{
    "address": {
      "name": "Jamie Doe",
      "email": "jamie@example.com",
      "phone": "+1 212 555 0100",
      "address_line_1": "123 Main Street",
      "address_line_2": "Suite 4",
      "city": "New York",
      "state": "NY",
      "postal_code": "10001",
      "country_alpha2": "US"
    },
    "certs": [
      { "cert": "12345678", "value": 250 },
      { "cert": "87654321", "value": 175 }
    ],
    "courierId": "courier-service-id",
    "txHash": "0x...",
    "paymentChain": "base",
    "includeDdp": false,
    "insurance": true
  }'

For sealed inventory, replace certs with products using the same shape documented in Shipping Rates.

Additional Fields

Name	Required	Description
courierId	Yes	courier_id returned by the selected rate.
txHash	Yes	Payment transaction hash. DYLI also uses it to prevent duplicate shipments and as a backup tracking key.
paymentChain	No	Network containing the USDC payment. Defaults to abstract. See Payments for supported values.
tax_id	No	Recipient tax id for destinations that require it. Aliases: taxId, consignee_tax_id.
test	No	Use true for an integration test. Test orders do not require live graded inventory and do not reduce inventory. See Testing.

Created Shipment

{
  "success": true,
  "shipment_id": "ESUS123456789",
  "label_url": "https://...",
  "tracking_url": "https://...",
  "courier": "UPS Ground",
  "tracking_key": "0x...",
  "test": false,
  "inventoryAdjusted": true,
  "inventoryCheckError": null,
  "inventoryError": null,
  "summary": {
    "slabCount": 2,
    "sealedCount": 0,
    "gradedCount": 2,
    "totalValue": "425.00",
    "usedBox": "7 x 5 x 2",
    "parcelCount": 1,
    "destination": "123 Main Street, NY, US"
  }
}

Save both shipment_id and tracking_key.

Pending Shipment

202 means DYLI accepted the shipment, but the carrier is still creating it. Check /status with tracking_key.

{
  "success": true,
  "pending": true,
  "shipment_id": "0x...",
  "tracking_key": "0x...",
  "easyship_shipment_id": null,
  "retryable": true,
  "retryAfterSeconds": 30,
  "message": "Shipment is pending Easyship creation. Use shipment_id or tracking_key with /api/3pl/{company}/status."
}

You can safely retry with the same txHash. If the shipment was already created, DYLI returns the existing shipment instead of creating another one. A transaction hash cannot be shared across company accounts.

DYLI reduces inventory only after the shipment is created. If inventoryAdjusted is false, check inventoryError and contact DYLI before changing inventory yourself.

For customer shipments, DYLI checks the requested quantities against your company's live on-hand inventory before queueing or creating a carrier shipment. Staging inventory does not count. Insufficient stock returns 409; if the stock check cannot be completed, the request fails without creating a shipment. A shipping quote does not reserve stock.