Update Shipment

This endpoint is used to update a draft shipment. If a shipment is already confirmed, then the endpoint will return a 400 error.

  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.

The shipment_id is used as a path parameter to identify the shipment. Alternatively the merchant provided 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
required
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

Bad Request

patch/shipments/{shipment_id}
Request samples
application/json
{
  • "entity_type": "FORWARD",
  • "merchant": "YOUR_MERCHANT_ID",
  • "references": {
    },
  • "carrier_account": {
    },
  • "payment": {
    },
  • "collection": {
    },
  • "delivery": {
    },
  • "pickup": {
    },
  • "dropoff": {
    },
  • "items": [
    ],
  • "parcels": [
    ],
  • "freight": {
    },
  • "customs": {
    },
  • "custom_attributes": {
    },
  • "order_date": "2022-01-01T09:00:00.000+1:00",
  • "order_type": "HOME_DELIVERY",
  • "language": "en"
}
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"
}