• Germanized
  • REST API

Shipments

Use this endpoint to query and/or manage shipments. You might want to create shipments to an order or update a shipment’s tracking number.

List shipments

GET: /wp-json/wc/v3/shipments/
context string

Scope under which the request is made; determines fields present in response. Options: view, edit Default is view

page integer

Current page of the collection. Default is 1

per_page integer

Maximum number of items to be returned in result set. Default is 10

search string

Limit results to those matching a string.

offset integer

Offset the result set by a specific number of items.

order string

Order sort attribute ascending or descending. Options: asc, desc Default is desc

orderby string

Sort collection by object attribute. Options: country, status, tracking_id, date_created, order_id, weight Default is date_created

order_id integer

Limit result set to shipments belonging to a certain order id.

status string

Limit result set to shipments having a certain status. Options: draft, processing, shipped, delivered, requested

type string

Limit result set to shipments of a certain type. Options: simple, return Default is simple

Example

This is an example request which retrieves shipments associated with a certain order.

curl https://example.com/wp-json/wc/v3/shipments/?order_id=<order_id>

Manage shipments

Retrieve, update or delete a shipment.

GET|POST|PUT|PATCH|DELETE: /wp-json/wc/v3/shipments/<id>

Properties

id integer readonly

Shipment ID.

shipment_number string readonly

Shipment number.

order_id string

Shipment order id.

order_number string readonly

Shipment order number.

status string

Shipment status. Options: draft, processing, shipped, delivered, requested

tracking_id string

Shipment tracking id.

tracking_url string readonly

Shipment tracking url.

shipping_provider string

Shipment shipping provider.

date_created date-time readonly

The date the shipment was created, in the site’s timezone.

date_created_gmt date-time readonly

The date the shipment was created, as GMT.

date_sent date-time readonly

The date the shipment was sent, in the site’s timezone.

date_sent_gmt date-time readonly

The date the shipment was sent, as GMT.

est_delivery_date date-time

The estimated delivery date of the shipment, in the site’s timezone.

est_delivery_date_gmt date-time

The estimated delivery date of the shipment, as GMT.

type string

Shipment type, e.g. simple or return. Options: simple, return

is_customer_requested boolean

Return shipment is requested by customer.

Return sender address.

weight string

Shipment weight.

content_weight string readonly

Shipment content weight.

content_dimensions object readonly

Shipment content dimensions.

weight_unit string

Shipment weight unit. Default is kg

packaging_id integer

Shipment packaging id.

packaging_weight string

Shipment packaging weight.

total string

Shipment total.

subtotal string

Shipment subtotal.

additional_total string

Shipment additional total.

version string

Shipment version.

shipping_method string

Shipment shipping method.

dimensions object

Shipment dimensions.

package_dimensions object readonly

Shipment package dimensions.

dimension_unit string

Shipment dimension unit. Default is cm

address object

Shipping address.

meta_data array

Meta data.

items array

Shipment items.

sender_address properties
first_name string

First name.

last_name string

Last name.

company string

Company name.

address_1 string

Address line 1.

address_2 string

Address line 2.

city string

City name.

state string

ISO code or name of the state, province or district.

postcode string

Postal code.

country string

Country code in ISO 3166-1 alpha-2 format.

customs_reference_number string

Customs reference number.

content_dimensions properties
length string readonly

Shipment content length.

width string readonly

Shipment content width.

height string readonly

Shipment content height.

dimensions properties
length string

Item length.

width string

Item width.

height string

Item height.

package_dimensions properties
length string readonly

Shipment package length.

width string readonly

Shipment package width.

height string readonly

Shipment package height.

address properties
first_name string

First name.

last_name string

Last name.

company string

Company name.

address_1 string

Address line 1.

address_2 string

Address line 2.

city string

City name.

state string

ISO code or name of the state, province or district.

postcode string

Postal code.

country string

Country code in ISO 3166-1 alpha-2 format.

customs_reference_number string

Customs reference number.

meta_data properties
id integer readonly

Meta ID.

key string

Meta key.

value mixed

Meta value.

items properties
id integer readonly

Item ID.

name mixed

Item name.

order_item_id integer

Order Item ID.

product_id mixed

Product ID.

quantity integer

Quantity.

weight string

Item weight.

sku string

Item SKU.

total string

Item total.

subtotal string

Item subtotal.

hs_code string

Item HS Code.

customs_description string

Item customs description.

manufacture_country string

Item country of manufacture in ISO 3166-1 alpha-2 format.

dimensions object

Item dimensions.

attributes object

Item attributes.

meta_data array

Shipment item meta data.

attributes properties
key string

Attribute key.

value string

Attribute value.

label string

Attribute label.

order_item_meta_id integer

Order item meta id.

Create a shipment

Create a shipment to an order and pass a custom tracking number. By default (e.g. not provided during request) items and shipment data is determined based on the underlying order. You may of course pass custom data too.

curl -L -X POST 'https://example.com/wp-json/wc/v3/shipments' \
-H 'Authorization: Basic your_key' \
-H 'Content-Type: application/json' \
-d '{
    "tracking_id": "123456",
    "order_id": "3780"
}'

Create a label

You may want to create/download a label for a certain shipment. By default, e.g. passing no arguments to the request, the default label configuration (based on your packaging chosen for the shipment) will be used. You might explicitly pass certain arguments on a per shipping provider level but you’ll need to find out about the services available and IDs yourself by looking at the manual label creation (XHR) request via your Browser tools.

curl -L -X POST 'http://example.com/wp-json/wc/v3/shipments/690/label' \
-H 'Authorization: Basic your_key'
Retrieve a label

You may retrieve a label for a certain shipment which contains the actual label as base64 encoded file.

curl -L 'http://example.com/wp-json/wc/v3/shipments/690/label' \
-H 'Authorization: Basic your_key'