Confirm Shipment

This endpoint is intended to confirm a draft shipment.

Please Note: The request body is optional when you use this endpoint. You can optionally update the shipment data when confirming the shipment.

  1. This endpoint supports partial updates. You can partially update certain sections of the shipment without updating the rest of the shipment.
  2. Partial updates are applied to top level shipment attributes. For example, if you pass the pickup element in the request, then all the pickup fields in the object will be replaced with the new payload.
  3. The above rule does not apply to custom attributes. Custom attributes can be individually added, updated or removed. To remove a custom attribute, you may pass a null value.

Once the shipment is confirmed, the shipment is set to pending status, a carrier is assigned, and a booking request is sent to the assigned carrier. The endpoint returns the shipment immediately in the pending status, without waiting for a response from the carrier.

If the carrier successfully confirms the booking, the shipment status is updated to booked, along with the tracking number. If the carrier rejects the booking request, the shipment status is set to error.

The merchant is notified of the booking update and the subsequent label generation via webhooks.

The shipment_id is used as a path parameter to identify the shipment. Alternatively the merchant shipment reference (partner_shipment_reference) can also be used instead of the shipment_id.

SecurityOAuth2
Request
path Parameters
shipment_id
required
string
header Parameters
x-api-key
required
string
tenant-id
required
string
Content-Type
required
string
Default: application/json
Request Body schema: application/json
optional
order_type
string

Pass one of the order types you have predefined in Carriyo

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) 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) 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

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>
Responses
200
400

Bad Request

post/shipments/{shipment_id}/confirm
Request samples
application/json
{
  • "order_type": "string",
  • "carrier_account": {
    },
  • "payment": {
    },
  • "collection": {
    },
  • "delivery": {
    },
  • "pickup": {
    },
  • "dropoff": {
    },
  • "items": [
    ],
  • "parcels": [
    ],
  • "freight": {
    },
  • "customs": {
    },
  • "custom_attributes": {
    },
  • "order_date": "2019-08-24T14:15:22Z"
}
Response samples
application/json
{
  • "shipment_id": "XYZABC123",
  • "entity_type": "FORWARD",
  • "merchant": "MY_BRAND",
  • "references": {
    },
  • "carrier_account": {
    },
  • "payment": {
    },
  • "collection": {
    },
  • "delivery": {
    },
  • "pickup": {
    },
  • "dropoff": {
    },
  • "items": [
    ],
  • "freight": {
    },
  • "customs": {
    },
  • "parcels": [
    ],
  • "post_shipping_info": {
    },
  • "custom_attributes": { },
  • "order_date": "2022-01-01T09:00:00.000Z",
  • "order_type": "HOME_DELIVERY",
  • "creation_date": "2022-01-01T09:00:00.000Z",
  • "update_date": "2022-01-01T09:00:00.000Z",
  • "confirmation_date": "2022-01-01T09:00:00.000Z",
  • "estimated_process_date": "2019-08-24T14:15:22Z",
  • "promised_delivery_date": "2022-01-01T09:00:00.000Z",
  • "original_promised_delivery_date": "2022-01-01T09:00:00.000Z",
  • "estimated_shipping_cost": {
    },
  • "language": "en",
  • "return_request_id": "rma_123abcXYZ"
}