Parcels

Shipments can be split into two or more parcels, that get tracked by the shipping carrier. For cross-border shipments, you can fill in a customs form. The related documentation is automatically generated and attached to the parcel.

The parcel object

A parcel object is returned as part of the response body of each successful create, list, retrieve or update API call. The following table contains the list of all its fields along with their type, description and example values.
Object fields:
weight
float
The parcel weight, used to automatically calculate the tax rates from the available carrier accounts.
Example:
1000
unit_of_weight
string
The unit of weight. Can be one of 'gr' or 'oz'.
Example:
gr
eel_pfc
string
When shipping outside the US, you need to provide either an Exemption and Exclusion Legend (EEL) code or a Proof of Filing Citation (PFC). Which you need is based on the value of the goods being shipped. Value can be one of "EEL" o "PFC".
Example:
EEL
contents_type
string
The type of item you are sending. Can be one of 'merchandise', 'gift', 'documents', 'returned_goods', 'sample' or 'other'.
Example:
merchandise
contents_explanation
string
If you specify 'other' in the 'contents_type' attribute, you must supply a brief description in this attribute.
Example:
customs_certify
boolean
Indicates if the provided information is accurate
Example:
false
customs_signer
string
This is the name of the person who is certifying that the information provided on the customs form is accurate. Use a name of the person in your organization who is responsible for this.
Example:
John Doe
non_delivery_option
string
In case the shipment cannot be delivered, this option tells the carrier what you want to happen to the parcel. You can pass either 'return' or 'abandon'. The value defaults to 'return'. If you pass 'abandon', you will not receive the parcel back if it cannot be delivered.
Example:
return
restriction_type
string
Describes if your parcel requires any special treatment or quarantine when entering the country. Can be one of 'none', 'other', 'quarantine' or 'sanitary_phytosanitary_inspection'.
Example:
none
restriction_comments
string
If you specify 'other' in the restriction type, you must supply a brief description of what is required.
Example:
customs_info_required
boolean
Indicates if the parcel requires customs info to get the shipping rates.
Example:
false
shipping_label_url
string
The shipping label url, ready to be downloaded and printed.
Example:
https://bucket.s3-us-west-2.amazonaws.com/files/postage_label/20180101/123.pdf
shipping_label_file_type
string
The shipping label file type. One of 'application/pdf', 'application/zpl', 'application/epl2' or 'image/png'.
Example:
application/pdf
shipping_label_size
string
The shipping label size.
Example:
4x7
shipping_label_resolution
string
The shipping label resolution.
Example:
200
tracking_number
string
The tracking number associated to this parcel.
Example:
1Z4V2A000000000000
tracking_status
string
The tracking status for this parcel, automatically updated in real time by the shipping carrier.
Example:
delivered
tracking_status_detail
string
Additional information about the tracking status, automatically updated in real time by the shipping carrier.
Example:
arrived_at_destination
tracking_status_updated_at
datetime
Time at which the parcel's tracking status was last updated.
Example:
2018-01-01T12:00:00.000Z
tracking_details
string
The parcel's full tracking history, automatically updated in real time by the shipping carrier.
Example:
carrier_weight_oz
string
The weight of the parcel as measured by the carrier in ounces (if available)
Example:
42.32
signed_by
string
The name of the person who signed for the parcel (if available)
Example:
John Smith
id
integer
Unique identifier for the resource.
Example:
1234
created_at
datetime
Time at which the resource was created.
Example:
2018-01-01T12:00:00.000Z
updated_at
datetime
Time at which the resource was last updated.
Example:
2018-01-01T12:00:00.000Z
reference
string
A string that you can use to add your own identifier to the resource. This can be useful for intergrating the resource to an external system, like an ERP, a marketing tool or a CRM.
Example:
ANYREFEFERNCE
metadata
object
Set of key-value pairs that you can attach to the resource. This can be useful for storing additional information about the resource in a structured format.
Example:
{"foo":"bar"}
relationship (N:1)
The associated shipment.

Create a parcel

To create a new parcel, send a POST request to the /api/parcels endpoint, passing the resource arguments in the request body. The following table contains the list of all the possible arguments, along with their type, description and examples values. All the arguments marked as required must be present in the request.
Arguments:
weight
optional
The parcel weight, used to automatically calculate the tax rates from the available carrier accounts.
Example:
1000
unit_of_weight
optional
The unit of weight. Can be one of 'gr' or 'oz'.
Example:
gr
eel_pfc
optional
When shipping outside the US, you need to provide either an Exemption and Exclusion Legend (EEL) code or a Proof of Filing Citation (PFC). Which you need is based on the value of the goods being shipped. Value can be one of "EEL" o "PFC".
Example:
EEL
contents_type
optional
The type of item you are sending. Can be one of 'merchandise', 'gift', 'documents', 'returned_goods', 'sample' or 'other'.
Example:
merchandise
contents_explanation
optional
If you specify 'other' in the 'contents_type' attribute, you must supply a brief description in this attribute.
Example:
customs_certify
optional
Indicates if the provided information is accurate
Example:
false
customs_signer
optional
This is the name of the person who is certifying that the information provided on the customs form is accurate. Use a name of the person in your organization who is responsible for this.
Example:
John Doe
non_delivery_option
optional
In case the shipment cannot be delivered, this option tells the carrier what you want to happen to the parcel. You can pass either 'return' or 'abandon'. The value defaults to 'return'. If you pass 'abandon', you will not receive the parcel back if it cannot be delivered.
Example:
return
restriction_type
optional
Describes if your parcel requires any special treatment or quarantine when entering the country. Can be one of 'none', 'other', 'quarantine' or 'sanitary_phytosanitary_inspection'.
Example:
none
restriction_comments
optional
If you specify 'other' in the restriction type, you must supply a brief description of what is required.
Example:
customs_info_required
optional, default 'false'
Indicates if the parcel requires customs info to get the shipping rates.
Example:
false
reference
optional
A string that you can use to add your own identifier to the resource. This can be useful for intergrating the resource to an external system, like an ERP, a marketing tool or a CRM.
Example:
ANYREFEFERNCE
metadata
optional
Set of key-value pairs that you can attach to the resource. This can be useful for storing additional information about the resource in a structured format.
Example:
#
required
The associated shipment.
Example request:
POST /api/parcels HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "type": "parcels",
    "relationships": {
      "shipment": {
        "data": {
          "type": "shipments",
          "id": "1234"
        }
      }
    }
  }
}
Example response: 201 Created
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "1234",
    "type": "parcels",
    "links": {
      "self": "https://your-brand.commercelayer.io/api/parcels/1234"
    },
    "attributes": {
      "weight": "1000",
      "unit_of_weight": "gr",
      "eel_pfc": "EEL",
      "contents_type": "merchandise",
      "contents_explanation": "",
      "customs_certify": "false",
      "customs_signer": "John Doe",
      "non_delivery_option": "return",
      "restriction_type": "none",
      "restriction_comments": "",
      "customs_info_required": "false",
      "shipping_label_url": "https://bucket.s3-us-west-2.amazonaws.com/files/postage_label/20180101/123.pdf",
      "shipping_label_file_type": "application/pdf",
      "shipping_label_size": "4x7",
      "shipping_label_resolution": "200",
      "tracking_number": "1Z4V2A000000000000",
      "tracking_status": "delivered",
      "tracking_status_detail": "arrived_at_destination",
      "tracking_status_updated_at": "2018-01-01T12:00:00.000Z",
      "tracking_details": "",
      "carrier_weight_oz": "42.32",
      "signed_by": "John Smith",
      "id": "1234",
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": "ANYREFEFERNCE",
      "metadata": {
        "foo": "bar"
      }
    },
    "relationships": {
      "shipment": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/parcels/1234/relationships/shipment",
          "related": "https://your-brand.commercelayer.io/api/parcels/1234/shipment"
        }
      }
    },
    "meta": {
      "mode": "test"
    }
  }
}

List all parcels

To fetch a collection of parcels, send a GET request to the /api/parcels endpoint.

Example request:
GET /api/parcels HTTP/1.1
Accept: application/vnd.api+json
Example response: 200 OK
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": [
    {
      "id": "1234",
      "type": "parcels",
      "links": {
        "self": "https://your-brand.commercelayer.io/api/parcels/1234"
      },
      "attributes": {
        "weight": "1000",
        "unit_of_weight": "gr",
        "eel_pfc": "EEL",
        "contents_type": "merchandise",
        "contents_explanation": "",
        "customs_certify": "false",
        "customs_signer": "John Doe",
        "non_delivery_option": "return",
        "restriction_type": "none",
        "restriction_comments": "",
        "customs_info_required": "false",
        "shipping_label_url": "https://bucket.s3-us-west-2.amazonaws.com/files/postage_label/20180101/123.pdf",
        "shipping_label_file_type": "application/pdf",
        "shipping_label_size": "4x7",
        "shipping_label_resolution": "200",
        "tracking_number": "1Z4V2A000000000000",
        "tracking_status": "delivered",
        "tracking_status_detail": "arrived_at_destination",
        "tracking_status_updated_at": "2018-01-01T12:00:00.000Z",
        "tracking_details": "",
        "carrier_weight_oz": "42.32",
        "signed_by": "John Smith",
        "id": "1234",
        "created_at": "2018-01-01T12:00:00.000Z",
        "updated_at": "2018-01-01T12:00:00.000Z",
        "reference": "ANYREFEFERNCE",
        "metadata": {
          "foo": "bar"
        }
      },
      "relationships": {
        "shipment": {
          "links": {
            "self": "https://your-brand.commercelayer.io/api/parcels/1234/relationships/shipment",
            "related": "https://your-brand.commercelayer.io/api/parcels/1234/shipment"
          }
        }
      },
      "meta": {
        "mode": "test"
      }
    },
    {
      "other": "... 24 parcels (first page)"
    }
  ],
  "meta": {
    "record_count": 125,
    "page_count": 5
  },
  "links": {
    "first": "/api/parcels?page[number]=1&page[size]=25",
    "prev": "/api/parcels?page[number]=2&page[size]=25",
    "next": "/api/parcels?page[number]=4&page[size]=25",
    "last": "/api/parcels?page[number]=5&page[size]=25"
  }
}
Available filters
idtracking_statustracking_status_updated_atreferenceshipment_ididstracking_status_updated_at_fromtracking_status_updated_at_tocreated_at_fromcreated_at_toupdated_at_fromupdated_at_to
Sortable attributes
tracking_status_updated_atidcreated_atupdated_atreference

Retrieve a parcel

To fetch a single parcel, send a GET request to the /api/parcels/{{id}} endpoint, where {{id}} is the id of the resource that you want to retrieve.
Example request:
GET /api/parcels/1234 HTTP/1.1
Accept: application/vnd.api+json
Example response: 200 OK
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "1234",
    "type": "parcels",
    "links": {
      "self": "https://your-brand.commercelayer.io/api/parcels/1234"
    },
    "attributes": {
      "weight": "1000",
      "unit_of_weight": "gr",
      "eel_pfc": "EEL",
      "contents_type": "merchandise",
      "contents_explanation": "",
      "customs_certify": "false",
      "customs_signer": "John Doe",
      "non_delivery_option": "return",
      "restriction_type": "none",
      "restriction_comments": "",
      "customs_info_required": "false",
      "shipping_label_url": "https://bucket.s3-us-west-2.amazonaws.com/files/postage_label/20180101/123.pdf",
      "shipping_label_file_type": "application/pdf",
      "shipping_label_size": "4x7",
      "shipping_label_resolution": "200",
      "tracking_number": "1Z4V2A000000000000",
      "tracking_status": "delivered",
      "tracking_status_detail": "arrived_at_destination",
      "tracking_status_updated_at": "2018-01-01T12:00:00.000Z",
      "tracking_details": "",
      "carrier_weight_oz": "42.32",
      "signed_by": "John Smith",
      "id": "1234",
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": "ANYREFEFERNCE",
      "metadata": {
        "foo": "bar"
      }
    },
    "relationships": {
      "shipment": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/parcels/1234/relationships/shipment",
          "related": "https://your-brand.commercelayer.io/api/parcels/1234/shipment"
        }
      }
    },
    "meta": {
      "mode": "test"
    }
  }
}

Update a parcel

To update an existing parcel, send a PATCH request to the /api/parcels/{{id}} endpoint, where {{id}} is the id of the resource that you want to update. The following table contains the list of all the possible arguments that you can pass with the request body, along with their type, description and examples values. Please note that all arguments are optional.
Arguments:
weight
optional
The parcel weight, used to automatically calculate the tax rates from the available carrier accounts.
Example:
1000
unit_of_weight
optional
The unit of weight. Can be one of 'gr' or 'oz'.
Example:
gr
eel_pfc
optional
When shipping outside the US, you need to provide either an Exemption and Exclusion Legend (EEL) code or a Proof of Filing Citation (PFC). Which you need is based on the value of the goods being shipped. Value can be one of "EEL" o "PFC".
Example:
EEL
contents_type
optional
The type of item you are sending. Can be one of 'merchandise', 'gift', 'documents', 'returned_goods', 'sample' or 'other'.
Example:
merchandise
contents_explanation
optional
If you specify 'other' in the 'contents_type' attribute, you must supply a brief description in this attribute.
Example:
customs_certify
optional
Indicates if the provided information is accurate
Example:
false
customs_signer
optional
This is the name of the person who is certifying that the information provided on the customs form is accurate. Use a name of the person in your organization who is responsible for this.
Example:
John Doe
non_delivery_option
optional
In case the shipment cannot be delivered, this option tells the carrier what you want to happen to the parcel. You can pass either 'return' or 'abandon'. The value defaults to 'return'. If you pass 'abandon', you will not receive the parcel back if it cannot be delivered.
Example:
return
restriction_type
optional
Describes if your parcel requires any special treatment or quarantine when entering the country. Can be one of 'none', 'other', 'quarantine' or 'sanitary_phytosanitary_inspection'.
Example:
none
restriction_comments
optional
If you specify 'other' in the restriction type, you must supply a brief description of what is required.
Example:
customs_info_required
optional
Indicates if the parcel requires customs info to get the shipping rates.
Example:
false
reference
optional
A string that you can use to add your own identifier to the resource. This can be useful for intergrating the resource to an external system, like an ERP, a marketing tool or a CRM.
Example:
ANYREFEFERNCE
metadata
optional
Set of key-value pairs that you can attach to the resource. This can be useful for storing additional information about the resource in a structured format.
Example:
#
optional
The associated shipment.
Example request:
PATCH /api/parcels/1234 HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "type": "parcels",
    "id": 1234,
    "attributes": {
      "weight": "1000"
    },
    "relationships": {
    }
  }
}
Example response: 200 OK
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "1234",
    "type": "parcels",
    "links": {
      "self": "https://your-brand.commercelayer.io/api/parcels/1234"
    },
    "attributes": {
      "weight": "1000",
      "unit_of_weight": "gr",
      "eel_pfc": "EEL",
      "contents_type": "merchandise",
      "contents_explanation": "",
      "customs_certify": "false",
      "customs_signer": "John Doe",
      "non_delivery_option": "return",
      "restriction_type": "none",
      "restriction_comments": "",
      "customs_info_required": "false",
      "shipping_label_url": "https://bucket.s3-us-west-2.amazonaws.com/files/postage_label/20180101/123.pdf",
      "shipping_label_file_type": "application/pdf",
      "shipping_label_size": "4x7",
      "shipping_label_resolution": "200",
      "tracking_number": "1Z4V2A000000000000",
      "tracking_status": "delivered",
      "tracking_status_detail": "arrived_at_destination",
      "tracking_status_updated_at": "2018-01-01T12:00:00.000Z",
      "tracking_details": "",
      "carrier_weight_oz": "42.32",
      "signed_by": "John Smith",
      "id": "1234",
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": "ANYREFEFERNCE",
      "metadata": {
        "foo": "bar"
      }
    },
    "relationships": {
      "shipment": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/parcels/1234/relationships/shipment",
          "related": "https://your-brand.commercelayer.io/api/parcels/1234/shipment"
        }
      }
    },
    "meta": {
      "mode": "test"
    }
  }
}

Delete a parcel

To delete a parcel, send a DELETE request to the /api/parcels/{{id}} endpoint, where {{id}} is the id of the resource that you want to delete.
Example request:
DELETE /api/parcels/1234 HTTP/1.1
Accept: application/vnd.api+json
Example response: 204 No Content
HTTP/1.1 204 No Content

Get our machine-readable JSON schema that follows the OpenAPI Specification (formerly Swagger).

Get our Postman collection in one click and start making real calls to Commerce Layer API in minutes.

Get in touch with our support team if you have any questions or want to learn more about Commerce Layer.