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 description: If you specify 'other' in the restriction type, you must supply a brief description of what is required. example: '' customs_info_required: type: boolean description: Indicates if the parcel requires customs info to get the shipping rates. example: 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 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 shipping_label_size: type: string description: The shipping label size. example: 4x7 shipping_label_resolution: type: string description: The shipping label resolution. example: '200' tracking_number: type: string description: The tracking number associated to this parcel. example: 1Z4V2A000000000000 tracking_status: type: string description: The tracking status for this parcel, automatically updated in real time by the shipping carrier. example: delivered 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 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' 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 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' signed_by: type: string description: The name of the person who signed for the parcel (if available). example: John Smith incoterm: type: string description: The type of Incoterm (if available). example: EXW delivery_confirmation: type: string description: The type of delivery confirmation option upon delivery. example: SIGNATURE 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 reference_origin: type: string description: Any identifier of the third party system that defines the reference code. example: ANY-EXTERNAL-REFEFERNCE-ORIGIN 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 required: - weight - unit_of_weight 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 required: - shipment - package securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT