This endpoint creates a new shipment in Carriyo with a unique shipment ID. The merchant may choose to assign a specific carrier account, if not it is assigned automatically based on the configured routing rules.
The shipment can be created as a draft, in which case the shipment is not submitted to the carrier until it is confirmed. This is useful if the merchant does not have all the information to create a valid shipment upfront. For instance, a draft shipment can be created without a pickup location and when the pickup location is determined the merchant can update and confirm the draft shipment.
If the endpoint is called with the draft
query param set to true
, then Carriyo simply creates the shipment and no further action is carried out on the shipment at this point.
If the draft
query param is not passed or is set to false, then Carriyo treats it as a confirmed shipment - it assigns the carrier, sets the status to "pending", and sends the booking request to the assigned carrier. Carriyo immediately responds to the API client with the status set to pending without waiting for a response from the carrier.
The carrier creates the shipment in its system and returns the tracking number. If the shipment is successfully booked by the carrier, the status of the shipment is updated to "booked". However if the shipment is rejected by the carrier for some reason, its status is updated to "error".
Once the shipment is booked, the label is generated and all of these updates including status and label updates are pushed back to the merchant via webhooks.
{- "entity_type": "FORWARD",
- "merchant": "MERCHANT-ID",
- "references": {
- "partner_order_reference": "new-shipment-1",
- "partner_shipment_reference": "new-shipment-1"
}, - "payment": {
- "payment_mode": "PRE_PAID",
- "total_amount": 100,
- "currency": "USD"
}, - "parcels": [
- {
- "partner_parcel_reference": "parcel-123",
- "weight": {
- "value": 1,
- "unit": "kg"
}, - "dimension": {
- "width": 20,
- "height": 40,
- "depth": 40,
- "unit": "cm"
}
}, - {
- "partner_parcel_reference": "parcel-124",
- "weight": {
- "value": 0.5,
- "unit": "kg"
}, - "dimension": {
- "width": 30,
- "height": 50,
- "depth": 50,
- "unit": "cm"
}
}
], - "items": [
- {
- "description": "Most Adorable Sneakers",
- "quantity": 1,
- "price": {
- "amount": 80,
- "currency": "USD"
}, - "weight": {
- "value": 1,
- "unit": "kg"
}, - "sku": "10001"
}, - {
- "description": "Absolutely Lovely Hat",
- "quantity": 1,
- "price": {
- "amount": 20,
- "currency": "USD"
}, - "cost": {
- "amount": 20,
- "currency": "USD"
}, - "weight": {
- "value": 0.5,
- "unit": "kg"
}, - "sku": "10001"
}
], - "customs": {
- "declared_value": {
- "amount": 100,
- "currency": "USD"
}
}, - "pickup": {
- "contact_name": "Warehouse Manager",
- "contact_phone": "043872701",
- "contact_email": "ops@test.com",
- "address1": "Grand Central Warehouse",
- "city": "Dubai",
- "state": "Dubai",
- "postcode": "",
- "country": "AE"
}, - "dropoff": {
- "contact_name": "Jo Bloggs",
- "contact_phone": "0561111234",
- "contact_email": "jo@test.com",
- "address1": "1, 10th Floor, Tower One",
- "address2": "Dubai Marina",
- "city": "DUBAI",
- "what3words": "///daring.lion.race",
- "postcode": "",
- "country": "AE"
}, - "order_date": "2021-01-01T10:00:00.999+1:00"
}
{- "shipment_id": "KR22VUXEXGKX1",
- "merchant": "MERCHANT-ID",
- "entity_type": "FORWARD",
- "carrier_account": { },
- "references": {
- "partner_order_reference": "test-order-1",
- "partner_shipment_reference": "test-order-1"
}, - "payment": {
- "payment_mode": "PRE_PAID",
- "pending_amount": 0,
- "total_amount": 99,
- "currency": "AED"
}, - "delivery": {
- "delivery_type": "STANDARD",
- "scheduled_from": "2021-07-15T06:00:00.000Z",
- "scheduled_to": "2021-07-15T10:00:00.000Z"
}, - "parcels": [
- {
- "parcel_id": "KR22VUXEXGKX1-1",
- "partner_parcel_reference": "",
- "description": "Parcel 1",
- "weight": {
- "value": 1,
- "unit": "kg"
}, - "dimension": {
- "width": 10,
- "height": 10,
- "depth": 10,
- "unit": "cm"
}
}
], - "items": [
- {
- "description": "Item 1",
- "origin_country": "",
- "quantity": 1,
- "price": {
- "amount": 99,
- "currency": "AED"
}, - "cost": {
- "amount": 20,
- "currency": "USD"
}, - "weight": {
- "value": 1,
- "unit": "kg"
}, - "sku": "SKU 1",
- "dangerous_goods": false
}
], - "customs": {
- "declared_value": {
- "amount": 100,
- "currency": "USD"
}
}, - "pickup": {
- "partner_location_id": "ACCOUNT_bef3862a-b27e-45d4-b077-8e8f4d674849",
- "contact_name": "Customer Service",
- "contact_phone": "+971561234567",
- "contact_email": "crm@mybusiness.com",
- "address1": "DIP Delivery Warehouse",
- "area": "DUBAI-INVESTMENT-PARK-1",
- "city": "DUBAI",
- "state": "DUBAI",
- "country": "AE",
- "coords": [
- 29.373420706419914,
- 47.97881566875099
]
}, - "dropoff": {
- "contact_name": "Jo Bloggs",
- "contact_phone": "+971561234567",
- "contact_email": "jo.bloggs@gmail.com",
- "address1": "1 Financial Centre Road",
- "address2": "Downtown Views, Apartment 101",
- "area": "DOWNTOWN-DUBAI",
- "city": "DUBAI",
- "state": "DUBAI",
- "country": "AE",
- "coords": [
- 29.294045,
- 48.087608
]
}, - "post_shipping_info": {
- "status": "error",
- "key_milestones": { },
- "error_details": [
- {
- "level": "ERROR",
- "trigger": "BOOKING",
- "source": "CARRIYO",
- "type": "VALIDATION",
- "message": "No carrier assigned. Please provide valid carrier and reprocess booking again.",
- "code": "no_carrier_assigned",
- "field": "carrier"
}, - {
- "level": "WARNING",
- "trigger": "BOOKING",
- "source": "CARRIYO",
- "type": "VALIDATION",
- "message": "Contact Email is missing.",
- "code": "email_missing",
- "field": "dropoff.contact_email"
}
]
}, - "creation_date": "2021-07-13T13:16:23.016Z",
- "confirmation_date": "2021-07-13T13:16:23.149Z",
- "update_date": "2021-08-10T17:31:20.218Z",
- "order_date": "2021-07-13T11:42:12.889Z",
- "language": "en"
}