Create Shipment

The Create Shipment endpoint allows the creation of a new shipment in Carriyo, generating a unique shipment ID. Merchants can specify a particular carrier account or rely on Carriyo to automatically assign a carrier based on predefined automation rules.

Key Concepts

Forward vs Reverse Shipments

This endpoint supports the creation of both forward and reverse shipments, determined by the entity_type parameter:

  • Forward Shipment: Standard shipment from the merchant to the customer.
  • Reverse Shipment: Return shipment, where the customer sends items back to the merchant.

Draft, Confirmed, and Prebooked Shipments

You can create a shipment as either a draft, confirmed, or prebooked shipment:

  • Draft Shipments:

    • Used to create a shipment in Carriyo for initial visibility before processing is complete. This is useful when shipment details (e.g., parcel information) aren’t yet available.
    • Setting the draft query parameter to true creates the shipment in draft status without booking it with a carrier.
    • Draft shipments remain unbooked until confirmed, and they are not sent to the carrier.

  • Confirmed Shipments:

    • If the draft query parameter is omitted or set to false, Carriyo treats the shipment as confirmed, assigns it to a carrier, and immediately initiates a booking request.
    • Pending Status: If Carriyo’s validations pass and a valid carrier is assigned, the status is set to pending, and Carriyo sends the booking request to the carrier.

      Note: The API will respond with the status pending, without waiting for the carrier's response.

    • Error Status: If Carriyo’s validations fail, the shipment status is set to error, and the response will include specific error details.

  • Prebooked Shipments:

    • If you wish to track a shipment already booked outside Carriyo, create a prebooked shipment by setting the pre_booked parameter to true and providing the carrier’s prebooking information, such as in this example:

      {
  "pre_booked": true,
  "pre_booking_info": {
    "input_carrier": "DHL",
    "carrier_tracking_no": "1234567890"
  }
}

Shipment Booking and Status Updates

Once Carriyo sends the booking request to the carrier:

  • Successful Booking: If the carrier successfully books the shipment, Carriyo updates the shipment status to booked and assigns the carrier tracking number.
  • Booking Error: If the carrier rejects the booking request, the shipment status is updated to error.

After booking, a label is generated, and Carriyo pushes all status updates, including label details, back to the merchant via webhooks.

SecurityOAuth2
Request
query Parameters
draft
boolean

Pass true for draft shipment

header Parameters
x-api-key
required
string
tenant-id
required
string
Content-Type
required
string
Default: application/json
Request Body schema: application/json
required
Any of:
entity_type
string
Default: "FORWARD"
Enum: "FORWARD" "REVERSE"
merchant
required
string

Merchant ID is mandatory to create a shipment

required
object (References Request)

References for a shipment, provided by the merchant.

The partner_order_reference is mandatory but not required to be unique. It is usually the customer facing order number.

The partner_shipment_reference must be unique for every shipment. It is mandatory, but is copied from partner_order_reference if it is not provided.

If a single order has multiple shipments, then they will share the partner_order_reference but have unique partner_shipment_reference.

object (Carrier Account Request)

Carrier account chosen for the shipment. Should contain either the carrier account id or carrier account name. Carrier account id takes precedence if both fields are passed.

object (Payment Request)

Payment details including the total value of the shipment and any pending Cash on Delivery amount.

object (Collection Request)

Collection details chosen for the shipment, such as scheduled collection date.

It can be set using one of the following options

Option 1: Provide the scheduled_from and scheduled_to to choose the scheduled date along with start and end time.

Example: "collection": { "scheduled_from": "2022-01-01'T'10:00:00.000+1:00", "scheduled_to": "2022-01-01'T'12:00:00.000+1:00" }

Option 2: Provide the scheduled_date only to choose the entire day.

Example: "collection": { "scheduled_date": "2022-01-01" }

object (Delivery)

The delivery options chosen for the shipment, including the delivery type and schedule.

It can be set using one of the following options

Option 1: Provide the scheduled_from and scheduled_to to choose the scheduled date along with start and end time.

Example: "delivery": { "delivery_type": "STANDARD", "scheduled_from": "2022-01-01'T'10:00:00.000+1:00", "scheduled_to": "2022-01-01'T'12:00:00.000+1:00" }

Option 2: Provide the scheduled_date only to choose the entire day.

Example: "delivery": { "delivery_type": "STANDARD", "scheduled_date": "2022-01-01" }

Location Request (object) or Free-Form Request (object)

Pickup address for the shipment. You can either pass a free-form address or a predefined location.

For forward shipments, you must pass a predefined pickup location. Carriyo will copy the contact and address fields from the specified location. To specify the location, you can use Carriyo's internal location ID (partner_location_id), or your own location code (partner_location_code) as defined when you created the location in Carriyo.

For reverse shipments, you can pass the customer's pickup address as a free-form pickup address.

Free-Form Request (object) or Location Request (object)

Dropoff address for the shipment. You can either pass a free-form address or a predefined location.

For forward shipments, you can pass the customer's dropoff address as a free-form address.

For reverse shipments, you must pass a predefined dropoff location. Carriyo will copy the contact and address fields from the specified location. To specify the location, you can use Carriyo's internal location ID (partner_location_id), or your own location code (partner_location_code) as defined when you created the location in Carriyo.

Array of objects (Item)

List of individual items or SKUs in a shipment.

Array of objects (Parcel Request)

List of parcels in a B2C shipment.

object (Freight request)

List of packages of type pallet or carton in a B2B shipment.

object (Customs)

Customs declaration details such as total declared value.

object (Custom Attributes)

Custom attributes in the form of a map:

{"attribute1" : ["value1", "value2"], "attribute2" : ["value1", "value2"]}

Please Note: You can only use custom attributes if you are subscribed to this feature.

order_date
string <date-time>

Date-time in ISO 8601 format.

Example: 2020-09-03T17:07:05.000+1:00 represents the date-time in UTC+1 time zone or 2020-09-03T17:07:05.000Z represents date-time in UTC (zulu) time zone

order_type
string

Pass one of the order types you have predefined in Carriyo

language
string

Two letter ISO 639-1 code. Example: en

Responses
200
400
post/shipments
Request samples
application/json
{
  • "entity_type": "FORWARD",
  • "merchant": "MERCHANT-ID",
  • "references": {
    },
  • "payment": {
    },
  • "parcels": [
    ],
  • "items": [
    ],
  • "customs": {
    },
  • "pickup": {
    },
  • "dropoff": {
    },
  • "order_date": "2021-01-01T10:00:00.999+1:00"
}
Response samples
application/json
{
  • "shipment_id": "KR22VUXEXGKX1",
  • "merchant": "MERCHANT-ID",
  • "entity_type": "FORWARD",
  • "carrier_account": { },
  • "references": {
    },
  • "payment": {
    },
  • "delivery": {
    },
  • "parcels": [
    ],
  • "items": [
    ],
  • "customs": {
    },
  • "pickup": {
    },
  • "dropoff": {
    },
  • "post_shipping_info": {
    },
  • "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"
}