openapi: 3.1.0
info:
title: Commerce Layer addresses parcels API
version: 7.10.1
contact:
name: API Support
url: https://commercelayer.io
email: support@commercelayer.io
description: Headless Commerce for Global Brands.
servers:
- url: https://{your_organization_slug}.commercelayer.io/api
description: API
- url: https://core.commercelayer.io/users/sign_in
description: Sign in
- url: https://docs.commercelayer.io/api
description: API reference
security:
- bearerAuth: []
tags:
- name: parcels
description: resource type
paths:
/easypost_pickups/{easypostPickupId}/parcels:
get:
operationId: GET/easypostPickupId/parcels
summary: Retrieve the parcels associated to the easypost pickup
description: Retrieve the parcels associated to the easypost pickup
tags:
- parcels
parameters:
- name: easypostPickupId
in: path
schema:
type: string
required: true
description: The resource's id
responses:
'200':
description: The parcels associated to the easypost pickup
/packages/{packageId}/parcels:
get:
operationId: GET/packageId/parcels
summary: Retrieve the parcels associated to the package
description: Retrieve the parcels associated to the package
tags:
- parcels
parameters:
- name: packageId
in: path
schema:
type: string
required: true
description: The resource's id
responses:
'200':
description: The parcels associated to the package
/parcel_line_items/{parcelLineItemId}/parcel:
get:
operationId: GET/parcelLineItemId/parcel
summary: Retrieve the parcel associated to the parcel line item
description: Retrieve the parcel associated to the parcel line item
tags:
- parcels
parameters:
- name: parcelLineItemId
in: path
schema:
type: string
required: true
description: The resource's id
responses:
'200':
description: The parcel associated to the parcel line item
/parcels:
get:
operationId: GET/parcels
summary: List all parcels
description: List all parcels
tags:
- parcels
responses:
'200':
description: A list of parcel objects
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/parcelResponseList'
post:
operationId: POST/parcels
summary: Create a parcel
description: Create a parcel
tags:
- parcels
requestBody:
required: true
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/parcelCreate'
responses:
'201':
description: The created parcel object
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/parcelResponse'
/parcels/{parcelId}:
get:
operationId: GET/parcels/parcelId
summary: Retrieve a parcel
description: Retrieve a parcel
tags:
- parcels
parameters:
- name: parcelId
in: path
schema:
type: string
required: true
description: The resource's id
responses:
'200':
description: The parcel object
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/parcelResponse'
patch:
operationId: PATCH/parcels/parcelId
summary: Update a parcel
description: Update a parcel
tags:
- parcels
parameters:
- name: parcelId
in: path
schema:
type: string
required: true
description: The resource's id
requestBody:
required: true
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/parcelUpdate'
responses:
'200':
description: The updated parcel object
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/parcelResponse'
delete:
operationId: DELETE/parcels/parcelId
summary: Delete a parcel
description: Delete a parcel
tags:
- parcels
parameters:
- name: parcelId
in: path
schema:
type: string
required: true
description: The resource's id
responses:
'204':
description: No content
/pickups/{pickupId}/parcels:
get:
operationId: GET/pickupId/parcels
summary: Retrieve the parcels associated to the pickup
description: Retrieve the parcels associated to the pickup
tags:
- parcels
parameters:
- name: pickupId
in: path
schema:
type: string
required: true
description: The resource's id
responses:
'200':
description: The parcels associated to the pickup
/shipments/{shipmentId}/parcels:
get:
operationId: GET/shipmentId/parcels
summary: Retrieve the parcels associated to the shipment
description: Retrieve the parcels associated to the shipment
tags:
- parcels
parameters:
- name: shipmentId
in: path
schema:
type: string
required: true
description: The resource's id
responses:
'200':
description: The parcels associated to the shipment
components:
schemas:
parcelUpdate:
required:
- data
type: object
properties:
data:
type: object
required:
- type
- id
- attributes
properties:
type:
type: string
description: The resource's type
enum:
- parcels
id:
type: string
description: Unique identifier for the resource (hash).
example: XAyRWNUzyN
attributes:
type: object
properties:
weight:
type: number
description: The parcel weight, used to automatically calculate the tax rates from the available carrier accounts.
example: 1000.0
nullable: false
unit_of_weight:
type: string
description: The unit of weight. One of 'gr', 'oz', or 'lb'.
example: gr
nullable: false
enum:
- gr
- oz
- lb
eel_pfc:
type: string
description: 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
nullable: true
contents_type:
type: string
description: The type of item you are sending.
example: merchandise
nullable: true
contents_explanation:
type: string
description: If you specify 'other' in the 'contents_type' attribute, you must supply a brief description in this attribute.
example: ''
nullable: true
customs_certify:
type: boolean
description: Indicates if the provided information is accurate.
example: false
nullable: false
customs_signer:
type: string
description: 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
nullable: true
non_delivery_option:
type: string
description: 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
nullable: true
restriction_type:
type: string
description: 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
nullable: true
restriction_comments:
type: string
description: If you specify 'other' in the restriction type, you must supply a brief description of what is required.
example: ''
nullable: true
customs_info_required:
type: boolean
description: Indicates if the parcel requires customs info to get the shipping rates.
example: false
nullable: false
shipping_label_url:
type: string
description: 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
nullable: true
shipping_label_file_type:
type: string
description: The shipping label file type. One of 'application/pdf', 'application/zpl', 'application/epl2', or 'image/png'.
example: application/pdf
nullable: true
shipping_label_size:
type: string
description: The shipping label size.
example: 4x7
nullable: true
shipping_label_resolution:
type: string
description: The shipping label resolution.
example: '200'
nullable: true
tracking_number:
type: string
description: The tracking number associated to this parcel.
example: 1Z4V2A000000000000
nullable: true
tracking_status:
type: string
description: The tracking status for this parcel, automatically updated in real time by the shipping carrier.
example: delivered
nullable: true
tracking_status_detail:
type: string
description: Additional information about the tracking status, automatically updated in real time by the shipping carrier.
example: arrived_at_destination
nullable: true
tracking_status_updated_at:
type: string
description: Time at which the parcel's tracking status was last updated.
example: '2018-01-01T12:00:00.000Z'
nullable: true
tracking_details:
type: array
description: The parcel's full tracking history, automatically updated in real time by the shipping carrier.
example:
- object: TrackingDetail
message: Pre-Shipment information received
status: pre_transit
datetime: '2018-02-27T16:02:17Z'
source: DHLExpress
tracking_location:
object: TrackingLocation
nullable: true
items:
type: object
carrier_weight_oz:
type: string
description: The weight of the parcel as measured by the carrier in ounces (if available).
example: '42.32'
nullable: true
signed_by:
type: string
description: The name of the person who signed for the parcel (if available).
example: John Smith
nullable: true
incoterm:
type: string
description: The type of Incoterm (if available).
example: EXW
nullable: true
delivery_confirmation:
type: string
description: The type of delivery confirmation option upon delivery.
example: SIGNATURE
nullable: true
reference:
type: string
description: A string that you can use to add any external identifier to the resource. This can be useful for integrating the resource to an external system, like an ERP, a marketing tool, a CRM, or whatever.
example: ANY-EXTERNAL-REFEFERNCE
nullable: true
reference_origin:
type: string
description: Any identifier of the third party system that defines the reference code.
example: ANY-EXTERNAL-REFEFERNCE-ORIGIN
nullable: true
metadata:
type: object
description: 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
nullable: true
relationships:
type: object
properties:
shipment:
required:
- data
type: object
properties:
data:
type: object
properties:
type:
type: string
description: The resource's type
enum:
- shipments
id:
type: string
description: Unique identifier for the resource (hash).
example: XAyRWNUzyN
package:
required:
- data
type: object
properties:
data:
type: object
properties:
type:
type: string
description: The resource's type
enum:
- packages
id:
type: string
description: Unique identifier for the resource (hash).
example: XAyRWNUzyN
parcelResponse:
type: object
properties:
data:
type: object
properties:
id:
type: string
description: Unique identifier for the resource (hash).
example: XAyRWNUzyN
type:
type: string
description: The resource's type
enum:
- parcels
links:
type: object
properties:
self:
type: string
description: URL
attributes:
$ref: '#/components/schemas/parcel/properties/data/properties/attributes'
relationships:
type: object
properties:
shipment:
type: object
properties:
links:
type: object
properties:
self:
type: string
description: URL
related:
type: string
description: URL
data:
type: object
properties:
type:
type: string
description: The resource's type
enum:
- shipment
id:
type: string
description: The resource ID
package:
type: object
properties:
links:
type: object
properties:
self:
type: string
description: URL
related:
type: string
description: URL
data:
type: object
properties:
type:
type: string
description: The resource's type
enum:
- package
id:
type: string
description: The resource ID
parcel_line_items:
type: object
properties:
links:
type: object
properties:
self:
type: string
description: URL
related:
type: string
description: URL
data:
type: object
properties:
type:
type: string
description: The resource's type
enum:
- parcel_line_items
id:
type: string
description: The resource ID
attachments:
type: object
properties:
links:
type: object
properties:
self:
type: string
description: URL
related:
type: string
description: URL
data:
type: object
properties:
type:
type: string
description: The resource's type
enum:
- attachments
id:
type: string
description: The resource ID
events:
type: object
properties:
links:
type: object
properties:
self:
type: string
description: URL
related:
type: string
description: URL
data:
type: object
properties:
type:
type: string
description: The resource's type
enum:
- events
id:
type: string
description: The resource ID
event_stores:
type: object
properties:
links:
type: object
properties:
self:
type: string
description: URL
related:
type: string
description: URL
data:
type: object
properties:
type:
type: string
description: The resource's type
enum:
- event_stores
id:
type: string
description: The resource ID
parcel:
properties:
data:
properties:
attributes:
type: object
properties:
number:
type: string
description: Unique identifier for the parcel.
example: '#1234/S/001/P/001'
nullable: true
weight:
type: number
description: The parcel weight, used to automatically calculate the tax rates from the available carrier accounts.
example: 1000.0
nullable: false
unit_of_weight:
type: string
description: The unit of weight. One of 'gr', 'oz', or 'lb'.
example: gr
nullable: false
enum:
- gr
- oz
- lb
eel_pfc:
type: string
description: 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
nullable: true
contents_type:
type: string
description: The type of item you are sending.
example: merchandise
nullable: true
contents_explanation:
type: string
description: If you specify 'other' in the 'contents_type' attribute, you must supply a brief description in this attribute.
example: ''
nullable: true
customs_certify:
type: boolean
description: Indicates if the provided information is accurate.
example: false
nullable: true
customs_signer:
type: string
description: 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
nullable: true
non_delivery_option:
type: string
description: 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
nullable: true
restriction_type:
type: string
description: 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
nullable: true
restriction_comments:
type: string
description: If you specify 'other' in the restriction type, you must supply a brief description of what is required.
example: ''
nullable: true
customs_info_required:
type: boolean
description: Indicates if the parcel requires customs info to get the shipping rates.
example: false
nullable: true
shipping_label_url:
type: string
description: 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
nullable: true
shipping_label_file_type:
type: string
description: The shipping label file type. One of 'application/pdf', 'application/zpl', 'application/epl2', or 'image/png'.
example: application/pdf
nullable: true
shipping_label_size:
type: string
description: The shipping label size.
example: 4x7
nullable: true
shipping_label_resolution:
type: string
description: The shipping label resolution.
example: '200'
nullable: true
tracking_number:
type: string
description: The tracking number associated to this parcel.
example: 1Z4V2A000000000000
nullable: true
tracking_status:
type: string
description: The tracking status for this parcel, automatically updated in real time by the shipping carrier.
example: delivered
nullable: true
tracking_status_detail:
type: string
description: Additional information about the tracking status, automatically updated in real time by the shipping carrier.
example: arrived_at_destination
nullable: true
tracking_status_updated_at:
type: string
description: Time at which the parcel's tracking status was last updated.
example: '2018-01-01T12:00:00.000Z'
nullable: true
tracking_details:
type: array
description: The parcel's full tracking history, automatically updated in real time by the shipping carrier.
example:
- object: TrackingDetail
message: Pre-Shipment information received
status: pre_transit
datetime: '2018-02-27T16:02:17Z'
source: DHLExpress
tracking_location:
object: TrackingLocation
nullable: true
items:
type: object
carrier_weight_oz:
type: string
description: The weight of the parcel as measured by the carrier in ounces (if available).
example: '42.32'
nullable: true
signed_by:
type: string
description: The name of the person who signed for the parcel (if available).
example: John Smith
nullable: true
incoterm:
type: string
description: The type of Incoterm (if available).
example: EXW
nullable: true
delivery_confirmation:
type: string
description: The type of delivery confirmation option upon delivery.
example: SIGNATURE
nullable: true
created_at:
type: string
description: Time at which the resource was created.
example: '2018-01-01T12:00:00.000Z'
nullable: false
updated_at:
type: string
description: Time at which the resource was last updated.
example: '2018-01-01T12:00:00.000Z'
nullable: false
reference:
type: string
description: A string that you can use to add any external identifier to the resource. This can be useful for integrating the resource to an external system, like an ERP, a marketing tool, a CRM, or whatever.
example: ANY-EXTERNAL-REFEFERNCE
nullable: true
reference_origin:
type: string
description: Any identifier of the third party system that defines the reference code.
example: ANY-EXTERNAL-REFEFERNCE-ORIGIN
nullable: true
metadata:
type: object
description: 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
nullable: true
parcelResponseList:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/parcelResponse/properties/data'
parcelCreate:
required:
- data
type: object
properties:
data:
type: object
required:
- type
- attributes
properties:
type:
type: string
description: The resource's type
enum:
- parcels
attributes:
type: object
properties:
weight:
type: number
description: The parcel weight, used to automatically calculate the tax rates from the available carrier accounts.
example: 1000.0
unit_of_weight:
type: string
description: The unit of weight. One of 'gr', 'oz', or 'lb'.
example: gr
enum:
- gr
- oz
- lb
eel_pfc:
type: string
description: 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:
type: string
description: The type of item you are sending.
example: merchandise
contents_explanation:
type: string
description: If you specify 'other' in the 'contents_type' attribute, you must supply a brief description in this attribute.
example: ''
customs_certify:
type: boolean
description: Indicates if the provided information is accurate.
example: false
customs_signer:
type: string
description: 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:
type: string
description: 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:
type: string
description: 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:
type: string
descript
# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/commerce-layer/refs/heads/main/openapi/commerce-layer-parcels-api-openapi.yml