Purchase order deliveries

Purchase Orders PRO

The purchase order deliveries API allows you to create, view, update, and delete individual, or a batch, of purchase order deliveries, and to add the delivered items to stock. It's available when the Purchase Orders PRO add-on is active.

Every delivery is linked to a purchase order (po_id) and every delivery item is linked to one of the purchase order's line items (po_item_id). The deliveries of a purchase order are also listed in its deliveries property (see Purchase Orders PRO properties).

The deliveries endpoints aren't nested under the purchase orders ones: they live at /wp-json/wc/v3/atum/delivery. To get the deliveries of a specific purchase order, use the parent parameter when listing them.

Delivery properties

Attribute	Type	Description
`id`	integer	Unique identifier for the resource. read-only
`name`	string	The delivery name. If not set, it's named automatically (`Delivery 1`, `Delivery 2`...).
`document_number`	string	The document number of the delivery note.
`po_id`	integer	The ID of the purchase order linked to the delivery. mandatory
`date_created`	date-time	The date the delivery was created, in the site's timezone.
`date_created_gmt`	date-time	The date the delivery was created, as GMT. read-only
`total`	string	The delivery total. read-only
`files`	array	IDs of the media library attachments linked to the delivery. When sent, they replace the current files.
`items`	array	Delivery items. See Delivery - Items properties mandatory
`author_id`	integer	ID of the user that will be set as the delivery author. Only when updating a delivery. write-only

Delivery - Items properties

Attribute	Type	Description
`id`	integer	Delivery item ID. Send it to update an existing item. Items sent without `id` are added to the delivery. read-only
`name`	string	Product name. read-only
`product_id`	integer	Product ID. Send it as `null` to remove the item from the delivery.
`variation_id`	integer	Variation ID, if applicable.
`po_item_id`	integer	ID of the purchase order line item that is being delivered. Required when adding an item.
`quantity`	number	Delivered quantity. Required (and greater than `0`) when adding an item.
`delivered`	number	Alias of `quantity`, used by the admin UI. write-only
`stock_changed`	string	Whether the item was already added to stock. Options: `yes` and `no`. When updating an item, send `true` to add its quantity to the product's stock, or `false` to remove it from the stock. Changing the quantity of an item that was already added to stock also changes the product's stock by the difference.
`returned_qty`	number	Quantity of the item that was returned.
`type`	string	Type of the item to add. Options: `product` (default) and `inventory` (for Multi-Inventory items). write-only
`inventory_id`	integer	Inventory ID. Only for the Multi-Inventory delivery items. Multi-Inventory
`delete`	boolean	Set to `true` to remove the item from the delivery. write-only

The item values that are stored as item meta (product_id, variation_id, po_item_id, quantity, stock_changed, returned_qty and inventory_id) are returned as strings.

Create a delivery

This API helps you to create a new delivery for a purchase order. The po_id and at least one valid item (with its po_item_id and a quantity greater than 0) are required. Creating a delivery doesn't change the stock: use the Add delivery items to stock endpoint, or update the items' stock_changed, for that.

HTTP request

POST/wp-json/wc/v3/atum/delivery

curl -X POST https://example.com/wp-json/wc/v3/atum/delivery \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "po_id": 2156,
  "name": "Delivery #1",
  "document_number": "DN-0001",
  "items": [
    {
      "po_item_id": 337,
      "quantity": 2
    },
    {
      "po_item_id": 338,
      "quantity": 1
    }
  ]
}'

JSON response example

{
    "id": 2160,
    "name": "Delivery #1",
    "date_created": "2019-11-15T10:21:00",
    "document_number": "DN-0001",
    "files": [],
    "total": "0.00",
    "items": [
        {
            "id": 345,
            "name": "Woo Single #1",
            "product_id": "93",
            "variation_id": "0",
            "po_item_id": "337",
            "quantity": "2",
            "stock_changed": "no",
            "returned_qty": "0"
        },
        {
            "id": 346,
            "name": "Ship Your Idea 2 - Black",
            "product_id": "22",
            "variation_id": "23",
            "po_item_id": "338",
            "quantity": "1",
            "stock_changed": "no",
            "returned_qty": "0"
        }
    ],
    "po_id": 2156,
    "date_created_gmt": "2019-11-15T09:21:00",
    "_links": {
        "self": [
            {
                "href": "https://example.com/wp-json/wc/v3/atum/delivery/2160"
            }
        ],
        "collection": [
            {
                "href": "https://example.com/wp-json/wc/v3/atum/delivery"
            }
        ]
    }
}

Retrieve a delivery

This API lets you retrieve and view a specific delivery.

HTTP request

GET/wp-json/wc/v3/atum/delivery/<id>

curl https://example.com/wp-json/wc/v3/atum/delivery/2160 \
	-u consumer_key:consumer_secret

JSON response example

{
    "id": 2160,
    "name": "Delivery #1",
    "date_created": "2019-11-15T10:21:00",
    "document_number": "DN-0001",
    "files": [],
    "total": "0.00",
    "items": [
        {
            "id": 345,
            "name": "Woo Single #1",
            "product_id": "93",
            "variation_id": "0",
            "po_item_id": "337",
            "quantity": "2",
            "stock_changed": "no",
            "returned_qty": "0"
        },
        {
            "id": 346,
            "name": "Ship Your Idea 2 - Black",
            "product_id": "22",
            "variation_id": "23",
            "po_item_id": "338",
            "quantity": "1",
            "stock_changed": "no",
            "returned_qty": "0"
        }
    ],
    "po_id": 2156,
    "date_created_gmt": "2019-11-15T09:21:00",
    "_links": {
        "self": [
            {
                "href": "https://example.com/wp-json/wc/v3/atum/delivery/2160"
            }
        ],
        "collection": [
            {
                "href": "https://example.com/wp-json/wc/v3/atum/delivery"
            }
        ]
    }
}

Available parameters

Parameter	Type	Description
`context`	string	Scope under which the request is made; determines fields present in response. Options: `view` and `edit`. Default is `view`.
`dp`	integer	Number of decimal points to use in each resource. Default is the store's number of decimals.

List all deliveries

This API helps you to view all the deliveries.

HTTP request

GET/wp-json/wc/v3/atum/delivery

curl https://example.com/wp-json/wc/v3/atum/delivery?parent=2156 \
	-u consumer_key:consumer_secret

JSON response example

[
    {
        "id": 2160,
        "name": "Delivery #1",
        "date_created": "2019-11-15T10:21:00",
        "document_number": "DN-0001",
        "files": [],
        "total": "0.00",
        "items": [
            {
                "id": 345,
                "name": "Woo Single #1",
                "product_id": "93",
                "variation_id": "0",
                "po_item_id": "337",
                "quantity": "2",
                "stock_changed": "no",
                "returned_qty": "0"
            },
            {
                "id": 346,
                "name": "Ship Your Idea 2 - Black",
                "product_id": "22",
                "variation_id": "23",
                "po_item_id": "338",
                "quantity": "1",
                "stock_changed": "no",
                "returned_qty": "0"
            }
        ],
        "po_id": 2156,
        "date_created_gmt": "2019-11-15T09:21:00",
        "_links": {
            "self": [
                {
                    "href": "https://example.com/wp-json/wc/v3/atum/delivery/2160"
                }
            ],
            "collection": [
                {
                    "href": "https://example.com/wp-json/wc/v3/atum/delivery"
                }
            ]
        }
    }
]

Available parameters

Parameter	Type	Description
`context`	string	Scope under which the request is made; determines fields present in response. Options: `view` and `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 the deliveries whose name matches a string.
`after`	string	Limit response to resources published after a given ISO8601 compliant date.
`before`	string	Limit response to resources published before a given ISO8601 compliant date.
`modified_after`	string	Limit response to resources modified after a given ISO8601 compliant date.
`modified_before`	string	Limit response to resources modified before a given ISO8601 compliant date.
`dates_are_gmt`	boolean	Whether to consider GMT post dates when limiting response by published or modified date. Default is `false`.
`exclude`	array	Ensure result set excludes specific IDs.
`include`	array	Limit result set to specific ids.
`offset`	integer	Offset the result set by a specific number of items.
`order`	string	Order sort attribute ascending or descending. Options: `asc` and `desc`. Default is `desc`.
`orderby`	string	Sort collection by object attribute. Options: `date`, `id`, `include`, `title`, `slug` and `modified`. Default is `date`.
`parent`	array	Limit result set to the deliveries of specific purchase order IDs.
`parent_exclude`	array	Limit result set to all the deliveries except those of specific purchase order IDs.
`status`	array	Limit result set to deliveries which have specific statuses. Options: `any`, `publish` and `trash`. Default is `any`.
`dp`	integer	Number of decimal points to use in each resource. Default is `2`.

Update a delivery

This API lets you make changes to a delivery. Items sent with an id are updated, items sent without it are added from the linked purchase order (they need a po_item_id and a quantity), and items sent with delete set to true are removed.

HTTP request

PUT/wp-json/wc/v3/atum/delivery/<id>

curl -X PUT https://example.com/wp-json/wc/v3/atum/delivery/2160 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "document_number": "DN-0001-B",
  "items": [
    {
      "id": 345,
      "stock_changed": true
    }
  ]
}'

JSON response example

{
    "id": 2160,
    "name": "Delivery #1",
    "date_created": "2019-11-15T10:21:00",
    "document_number": "DN-0001-B",
    "files": [],
    "total": "0.00",
    "items": [
        {
            "id": 345,
            "name": "Woo Single #1",
            "product_id": "93",
            "variation_id": "0",
            "po_item_id": "337",
            "quantity": "2",
            "stock_changed": "yes",
            "returned_qty": "0"
        },
        {
            "id": 346,
            "name": "Ship Your Idea 2 - Black",
            "product_id": "22",
            "variation_id": "23",
            "po_item_id": "338",
            "quantity": "1",
            "stock_changed": "no",
            "returned_qty": "0"
        }
    ],
    "po_id": 2156,
    "date_created_gmt": "2019-11-15T09:21:00",
    "_links": {
        "self": [
            {
                "href": "https://example.com/wp-json/wc/v3/atum/delivery/2160"
            }
        ],
        "collection": [
            {
                "href": "https://example.com/wp-json/wc/v3/atum/delivery"
            }
        ]
    }
}

Add delivery items to stock

This API adds the delivered quantity of the delivery items to the products' stock (the items already added to stock are skipped), the same way as the "Add to stock" button of the delivery in the admin. Afterwards, the linked purchase order's status is changed to atum_added (when all its items are added to stock) or atum_partially_added, and it's returned in the po_status field of the response.

HTTP request

POST/wp-json/wc/v3/atum/delivery/<id>/stock

curl -X POST https://example.com/wp-json/wc/v3/atum/delivery/2160/stock \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "items": [
    {
      "id": 345
    },
    {
      "id": 346
    }
  ]
}'

JSON response example

{
    "id": 2160,
    "name": "Delivery #1",
    "date_created": "2019-11-15T10:21:00",
    "document_number": "DN-0001",
    "files": [],
    "total": "0.00",
    "items": [
        {
            "id": 345,
            "name": "Woo Single #1",
            "product_id": "93",
            "variation_id": "0",
            "po_item_id": "337",
            "quantity": "2",
            "stock_changed": "yes",
            "returned_qty": "0"
        },
        {
            "id": 346,
            "name": "Ship Your Idea 2 - Black",
            "product_id": "22",
            "variation_id": "23",
            "po_item_id": "338",
            "quantity": "1",
            "stock_changed": "yes",
            "returned_qty": "0"
        }
    ],
    "po_id": 2156,
    "date_created_gmt": "2019-11-15T09:21:00",
    "_links": {
        "self": [
            {
                "href": "https://example.com/wp-json/wc/v3/atum/delivery/2160"
            }
        ],
        "collection": [
            {
                "href": "https://example.com/wp-json/wc/v3/atum/delivery"
            }
        ]
    },
    "po_status": "atum_added"
}

Available parameters

Parameter	Type	Description
`items`	array	Delivery items to add to stock. Each item is an object with the delivery item `id`, and its `type` (`product` or `inventory`) and `inventoryId` for the Multi-Inventory items (both are detected automatically if not sent). It also accepts a plain list of delivery item IDs. If omitted, all the delivery items are added to stock.

Delete a delivery

This API helps you delete a delivery. Deliveries don't support trashing, so they are always deleted permanently.

HTTP request

DELETE/wp-json/wc/v3/atum/delivery/<id>

curl -X DELETE https://example.com/wp-json/wc/v3/atum/delivery/2160 \
	-u consumer_key:consumer_secret

JSON response example

{
    "id": 2160,
    "name": "Delivery #1",
    "date_created": "2019-11-15T10:21:00",
    "document_number": "DN-0001",
    "files": [],
    "total": "0.00",
    "items": [
        {
            "id": 345,
            "name": "Woo Single #1",
            "product_id": "93",
            "variation_id": "0",
            "po_item_id": "337",
            "quantity": "2",
            "stock_changed": "no",
            "returned_qty": "0"
        },
        {
            "id": 346,
            "name": "Ship Your Idea 2 - Black",
            "product_id": "22",
            "variation_id": "23",
            "po_item_id": "338",
            "quantity": "1",
            "stock_changed": "no",
            "returned_qty": "0"
        }
    ],
    "po_id": 2156,
    "date_created_gmt": "2019-11-15T09:21:00",
    "_links": {
        "self": [
            {
                "href": "https://example.com/wp-json/wc/v3/atum/delivery/2160"
            }
        ],
        "collection": [
            {
                "href": "https://example.com/wp-json/wc/v3/atum/delivery"
            }
        ]
    }
}

Batch update deliveries

This API helps you to batch create, update and delete multiple deliveries.

Note: By default it's limited to up to 100 objects to be created, updated or deleted.

HTTP request

POST/wp-json/wc/v3/atum/delivery/batch

curl -X POST https://example.com/wp-json/wc/v3/atum/delivery/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "create": [
    {
      "po_id": 2163,
      "name": "Delivery #2",
      "document_number": "DN-0002",
      "items": [
        {
          "po_item_id": 360,
          "quantity": 1
        }
      ]
    }
  ],
  "update": [
    {
      "id": 2160,
      "document_number": "DN-0001-B"
    }
  ],
  "delete": [
    2150
  ]
}'

JSON response example

{
    "create": [
        {
            "id": 2172,
            "name": "Delivery #2",
            "date_created": "2019-11-21T09:12:40",
            "document_number": "DN-0002",
            "files": [],
            "total": "0.00",
            "items": [
                {
                    "id": 353,
                    "name": "Woo Single #2",
                    "product_id": "94",
                    "variation_id": "0",
                    "po_item_id": "360",
                    "quantity": "1",
                    "stock_changed": "no",
                    "returned_qty": "0"
                }
            ],
            "po_id": 2163,
            "date_created_gmt": "2019-11-21T08:12:40",
            "_links": {
                "self": [
                    {
                        "href": "https://example.com/wp-json/wc/v3/atum/delivery/2172"
                    }
                ],
                "collection": [
                    {
                        "href": "https://example.com/wp-json/wc/v3/atum/delivery"
                    }
                ]
            }
        }
    ],
    "update": [
        {
            "id": 2160,
            "name": "Delivery #1",
            "date_created": "2019-11-15T10:21:00",
            "document_number": "DN-0001-B",
            "files": [],
            "total": "0.00",
            "items": [
                {
                    "id": 345,
                    "name": "Woo Single #1",
                    "product_id": "93",
                    "variation_id": "0",
                    "po_item_id": "337",
                    "quantity": "2",
                    "stock_changed": "no",
                    "returned_qty": "0"
                },
                {
                    "id": 346,
                    "name": "Ship Your Idea 2 - Black",
                    "product_id": "22",
                    "variation_id": "23",
                    "po_item_id": "338",
                    "quantity": "1",
                    "stock_changed": "no",
                    "returned_qty": "0"
                }
            ],
            "po_id": 2156,
            "date_created_gmt": "2019-11-15T09:21:00",
            "_links": {
                "self": [
                    {
                        "href": "https://example.com/wp-json/wc/v3/atum/delivery/2160"
                    }
                ],
                "collection": [
                    {
                        "href": "https://example.com/wp-json/wc/v3/atum/delivery"
                    }
                ]
            }
        }
    ],
    "delete": [
        {
            "id": 2150,
            "name": "Delivery #1",
            "date_created": "2019-11-02T11:00:00",
            "document_number": "DN-0098",
            "files": [],
            "total": "0.00",
            "items": [
                {
                    "id": 330,
                    "name": "Woo Single #3",
                    "product_id": "95",
                    "variation_id": "0",
                    "po_item_id": "325",
                    "quantity": "3",
                    "stock_changed": "no",
                    "returned_qty": "0"
                }
            ],
            "po_id": 2140,
            "date_created_gmt": "2019-11-02T10:00:00",
            "_links": {
                "self": [
                    {
                        "href": "https://example.com/wp-json/wc/v3/atum/delivery/2150"
                    }
                ],
                "collection": [
                    {
                        "href": "https://example.com/wp-json/wc/v3/atum/delivery"
                    }
                ]
            }
        }
    ]
}

Purchase order deliveries

Delivery propertiesCopy Anchor Link

Delivery - Items propertiesCopy Anchor Link

Create a deliveryCopy Anchor Link

HTTP requestCopy Anchor Link

Retrieve a deliveryCopy Anchor Link

HTTP requestCopy Anchor Link

Available parametersCopy Anchor Link

List all deliveriesCopy Anchor Link

HTTP requestCopy Anchor Link

Available parametersCopy Anchor Link

Update a deliveryCopy Anchor Link

HTTP requestCopy Anchor Link

Add delivery items to stockCopy Anchor Link

HTTP requestCopy Anchor Link

Available parametersCopy Anchor Link

Delete a deliveryCopy Anchor Link

HTTP requestCopy Anchor Link

Batch update deliveriesCopy Anchor Link

HTTP requestCopy Anchor Link

On this page

Delivery properties

Delivery - Items properties

Create a delivery

HTTP request

Retrieve a delivery

HTTP request

Available parameters

List all deliveries

HTTP request

Available parameters

Update a delivery

HTTP request

Add delivery items to stock

HTTP request

Available parameters

Delete a delivery

HTTP request

Batch update deliveries

HTTP request