Create Shipment

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.

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
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.000Z", "scheduled_to": "2022-01-01'T'12:00:00.000Z" }

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.000Z", "scheduled_to": "2022-01-01'T'12:00:00.000Z" }

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 in ISO 8601 format. Example: 2020-09-03T17:07:05.000Z

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.999Z"
}
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"
}