Skip to main content

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.

/order independently enforces the address character requirements and the maximum lengths of 70 characters for line 1 and 50 for line 2 documented in Validate Address, even if an integration skips the address-validation endpoint.

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​

NameRequiredDescription
courierIdYescourier_id returned by the selected rate.
txHashYesPayment transaction hash. DYLI also uses it to prevent duplicate shipments and as a backup tracking key.
paymentChainNoNetwork containing the USDC payment. Send base explicitly for Base payments. See Payments for supported values.
tax_idNoRecipient tax id for destinations that require it. Aliases: taxId, consignee_tax_id.
testNoDefaults to false. Use true to simulate an integration test in DYLI without creating a shipment, label or inventory change. 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 being created. 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 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.