Purchase order invoices

Purchase Orders PRO

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

Every invoice is linked to a purchase order (po_id) and every invoice item is linked to one of the purchase order's items (po_item_id): a line item, a fee or a shipping cost. The invoices of a purchase order are also listed in its invoices property (see Purchase Orders PRO properties).

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

Invoice properties

Attribute	Type	Description
`id`	integer	Unique identifier for the resource. read-only
`name`	string	The invoice name.
`document_number`	string	The document number of the invoice.
`po_id`	integer	The ID of the purchase order linked to the invoice. mandatory
`date_created`	date-time	The date the invoice was created, in the site's timezone.
`date_created_gmt`	date-time	The date the invoice was created, as GMT. read-only
`total`	string	The invoice total, including taxes. read-only
`files`	array	IDs of the media library attachments linked to the invoice. When sent, they replace the current files.
`items`	array	Invoice items. See Invoice - Items properties mandatory
`author_id`	integer	ID of the user that will be set as the invoice author. Only when updating an invoice. write-only

Currently, the invoice responses don't include the name, and they return date_created and date_created_gmt as null.

Invoice - Items properties

Attribute	Type	Description
`id`	integer	Invoice item ID. Send it to update an existing item. Items sent without `id` are added to the invoice. read-only
`name`	string	Product name. read-only
`po_item_id`	integer	ID of the purchase order item (line item, fee or shipping cost) that is being invoiced. Required when adding an item.
`type`	string	Type of the purchase order item to add. Options: `line_item` (default; `product` and `invoice_item` are accepted as aliases), `fee` and `shipping`. write-only
`quantity`	number	Invoiced quantity. Required (and greater than `0`) when adding any item, including fees and shipping costs.
`qty`	number	Alias of `quantity`, used by the admin UI. write-only
`product_id`	integer	Product ID. Send it as `null` to remove the item from the invoice.
`variation_id`	integer	Variation ID, if applicable.
`subtotal`	string	Item subtotal, excluding tax. read-only
`subtotal_tax`	string	Item subtotal tax. read-only
`total`	string	Item total, excluding tax. read-only
`total_tax`	string	Item total tax. read-only
`taxes`	object	Item taxes: the `subtotal` and `total` amounts, keyed by tax rate ID. read-only
`delete`	boolean	Set to `true` to remove the item from the invoice. write-only

Only the product items are listed in items. The fees and shipping costs added to the invoice are included in its total, but they aren't returned in the response.

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

Create an invoice

This API helps you to create a new invoice 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. The item prices and taxes are taken from the purchase order items.

HTTP request

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

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

JSON response example

{
    "id": 2161,
    "document_number": "INV-0001",
    "files": [],
    "total": "31.20",
    "items": [
        {
            "id": 350,
            "name": "Woo Single #1",
            "product_id": "93",
            "variation_id": "0",
            "po_item_id": "337",
            "quantity": "2",
            "subtotal": "6",
            "subtotal_tax": "1.2",
            "total": "6",
            "total_tax": "1.2",
            "taxes": {
                "subtotal": {
                    "1": "1.2"
                },
                "total": {
                    "1": "1.2"
                }
            }
        },
        {
            "id": 351,
            "name": "Ship Your Idea 2 - Black",
            "product_id": "22",
            "variation_id": "23",
            "po_item_id": "338",
            "quantity": "1",
            "subtotal": "20",
            "subtotal_tax": "4",
            "total": "20",
            "total_tax": "4",
            "taxes": {
                "subtotal": {
                    "1": "4"
                },
                "total": {
                    "1": "4"
                }
            }
        }
    ],
    "po_id": 2156,
    "date_created": null,
    "date_created_gmt": null,
    "_links": {
        "self": [
            {
                "href": "https://example.com/wp-json/wc/v3/atum/invoice/2161"
            }
        ],
        "collection": [
            {
                "href": "https://example.com/wp-json/wc/v3/atum/invoice"
            }
        ]
    }
}

Retrieve an invoice

This API lets you retrieve and view a specific invoice.

HTTP request

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

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

JSON response example

{
    "id": 2161,
    "document_number": "INV-0001",
    "files": [],
    "total": "31.20",
    "items": [
        {
            "id": 350,
            "name": "Woo Single #1",
            "product_id": "93",
            "variation_id": "0",
            "po_item_id": "337",
            "quantity": "2",
            "subtotal": "6",
            "subtotal_tax": "1.2",
            "total": "6",
            "total_tax": "1.2",
            "taxes": {
                "subtotal": {
                    "1": "1.2"
                },
                "total": {
                    "1": "1.2"
                }
            }
        },
        {
            "id": 351,
            "name": "Ship Your Idea 2 - Black",
            "product_id": "22",
            "variation_id": "23",
            "po_item_id": "338",
            "quantity": "1",
            "subtotal": "20",
            "subtotal_tax": "4",
            "total": "20",
            "total_tax": "4",
            "taxes": {
                "subtotal": {
                    "1": "4"
                },
                "total": {
                    "1": "4"
                }
            }
        }
    ],
    "po_id": 2156,
    "date_created": null,
    "date_created_gmt": null,
    "_links": {
        "self": [
            {
                "href": "https://example.com/wp-json/wc/v3/atum/invoice/2161"
            }
        ],
        "collection": [
            {
                "href": "https://example.com/wp-json/wc/v3/atum/invoice"
            }
        ]
    }
}

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 invoices

This API helps you to view all the invoices.

HTTP request

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

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

JSON response example

[
    {
        "id": 2161,
        "document_number": "INV-0001",
        "files": [],
        "total": "31.20",
        "items": [
            {
                "id": 350,
                "name": "Woo Single #1",
                "product_id": "93",
                "variation_id": "0",
                "po_item_id": "337",
                "quantity": "2",
                "subtotal": "6",
                "subtotal_tax": "1.2",
                "total": "6",
                "total_tax": "1.2",
                "taxes": {
                    "subtotal": {
                        "1": "1.2"
                    },
                    "total": {
                        "1": "1.2"
                    }
                }
            },
            {
                "id": 351,
                "name": "Ship Your Idea 2 - Black",
                "product_id": "22",
                "variation_id": "23",
                "po_item_id": "338",
                "quantity": "1",
                "subtotal": "20",
                "subtotal_tax": "4",
                "total": "20",
                "total_tax": "4",
                "taxes": {
                    "subtotal": {
                        "1": "4"
                    },
                    "total": {
                        "1": "4"
                    }
                }
            }
        ],
        "po_id": 2156,
        "date_created": null,
        "date_created_gmt": null,
        "_links": {
            "self": [
                {
                    "href": "https://example.com/wp-json/wc/v3/atum/invoice/2161"
                }
            ],
            "collection": [
                {
                    "href": "https://example.com/wp-json/wc/v3/atum/invoice"
                }
            ]
        }
    }
]

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 invoices 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 invoices of specific purchase order IDs.
`parent_exclude`	array	Limit result set to all the invoices except those of specific purchase order IDs.
`status`	array	Limit result set to invoices 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 an invoice

This API lets you make changes to an invoice. 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/invoice/<id>

curl -X PUT https://example.com/wp-json/wc/v3/atum/invoice/2161 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "document_number": "INV-0001-B",
  "files": [
    2175
  ]
}'

JSON response example

{
    "id": 2161,
    "document_number": "INV-0001-B",
    "files": [
        2175
    ],
    "total": "31.20",
    "items": [
        {
            "id": 350,
            "name": "Woo Single #1",
            "product_id": "93",
            "variation_id": "0",
            "po_item_id": "337",
            "quantity": "2",
            "subtotal": "6",
            "subtotal_tax": "1.2",
            "total": "6",
            "total_tax": "1.2",
            "taxes": {
                "subtotal": {
                    "1": "1.2"
                },
                "total": {
                    "1": "1.2"
                }
            }
        },
        {
            "id": 351,
            "name": "Ship Your Idea 2 - Black",
            "product_id": "22",
            "variation_id": "23",
            "po_item_id": "338",
            "quantity": "1",
            "subtotal": "20",
            "subtotal_tax": "4",
            "total": "20",
            "total_tax": "4",
            "taxes": {
                "subtotal": {
                    "1": "4"
                },
                "total": {
                    "1": "4"
                }
            }
        }
    ],
    "po_id": 2156,
    "date_created": null,
    "date_created_gmt": null,
    "_links": {
        "self": [
            {
                "href": "https://example.com/wp-json/wc/v3/atum/invoice/2161"
            }
        ],
        "collection": [
            {
                "href": "https://example.com/wp-json/wc/v3/atum/invoice"
            }
        ]
    }
}

Delete an invoice

This API helps you delete an invoice. Invoices don't support trashing, so they are always deleted permanently.

HTTP request

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

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

JSON response example

{
    "id": 2161,
    "document_number": "INV-0001",
    "files": [],
    "total": "31.20",
    "items": [
        {
            "id": 350,
            "name": "Woo Single #1",
            "product_id": "93",
            "variation_id": "0",
            "po_item_id": "337",
            "quantity": "2",
            "subtotal": "6",
            "subtotal_tax": "1.2",
            "total": "6",
            "total_tax": "1.2",
            "taxes": {
                "subtotal": {
                    "1": "1.2"
                },
                "total": {
                    "1": "1.2"
                }
            }
        },
        {
            "id": 351,
            "name": "Ship Your Idea 2 - Black",
            "product_id": "22",
            "variation_id": "23",
            "po_item_id": "338",
            "quantity": "1",
            "subtotal": "20",
            "subtotal_tax": "4",
            "total": "20",
            "total_tax": "4",
            "taxes": {
                "subtotal": {
                    "1": "4"
                },
                "total": {
                    "1": "4"
                }
            }
        }
    ],
    "po_id": 2156,
    "date_created": null,
    "date_created_gmt": null,
    "_links": {
        "self": [
            {
                "href": "https://example.com/wp-json/wc/v3/atum/invoice/2161"
            }
        ],
        "collection": [
            {
                "href": "https://example.com/wp-json/wc/v3/atum/invoice"
            }
        ]
    }
}

Batch update invoices

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

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/invoice/batch

curl -X POST https://example.com/wp-json/wc/v3/atum/invoice/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "create": [
    {
      "po_id": 2163,
      "document_number": "INV-0002",
      "items": [
        {
          "po_item_id": 360,
          "quantity": 1
        }
      ]
    }
  ],
  "update": [
    {
      "id": 2161,
      "document_number": "INV-0001-B"
    }
  ],
  "delete": [
    2152
  ]
}'

JSON response example

{
    "create": [
        {
            "id": 2173,
            "document_number": "INV-0002",
            "files": [],
            "total": "18.15",
            "items": [
                {
                    "id": 355,
                    "name": "Woo Single #2",
                    "product_id": "94",
                    "variation_id": "0",
                    "po_item_id": "360",
                    "quantity": "1",
                    "subtotal": "15",
                    "subtotal_tax": "3.15",
                    "total": "15",
                    "total_tax": "3.15",
                    "taxes": {
                        "subtotal": {
                            "1": "3.15"
                        },
                        "total": {
                            "1": "3.15"
                        }
                    }
                }
            ],
            "po_id": 2163,
            "date_created": null,
            "date_created_gmt": null,
            "_links": {
                "self": [
                    {
                        "href": "https://example.com/wp-json/wc/v3/atum/invoice/2173"
                    }
                ],
                "collection": [
                    {
                        "href": "https://example.com/wp-json/wc/v3/atum/invoice"
                    }
                ]
            }
        }
    ],
    "update": [
        {
            "id": 2161,
            "document_number": "INV-0001-B",
            "files": [],
            "total": "31.20",
            "items": [
                {
                    "id": 350,
                    "name": "Woo Single #1",
                    "product_id": "93",
                    "variation_id": "0",
                    "po_item_id": "337",
                    "quantity": "2",
                    "subtotal": "6",
                    "subtotal_tax": "1.2",
                    "total": "6",
                    "total_tax": "1.2",
                    "taxes": {
                        "subtotal": {
                            "1": "1.2"
                        },
                        "total": {
                            "1": "1.2"
                        }
                    }
                },
                {
                    "id": 351,
                    "name": "Ship Your Idea 2 - Black",
                    "product_id": "22",
                    "variation_id": "23",
                    "po_item_id": "338",
                    "quantity": "1",
                    "subtotal": "20",
                    "subtotal_tax": "4",
                    "total": "20",
                    "total_tax": "4",
                    "taxes": {
                        "subtotal": {
                            "1": "4"
                        },
                        "total": {
                            "1": "4"
                        }
                    }
                }
            ],
            "po_id": 2156,
            "date_created": null,
            "date_created_gmt": null,
            "_links": {
                "self": [
                    {
                        "href": "https://example.com/wp-json/wc/v3/atum/invoice/2161"
                    }
                ],
                "collection": [
                    {
                        "href": "https://example.com/wp-json/wc/v3/atum/invoice"
                    }
                ]
            }
        }
    ],
    "delete": [
        {
            "id": 2152,
            "document_number": "INV-0098",
            "files": [],
            "total": "36.30",
            "items": [
                {
                    "id": 331,
                    "name": "Woo Single #3",
                    "product_id": "95",
                    "variation_id": "0",
                    "po_item_id": "325",
                    "quantity": "3",
                    "subtotal": "30",
                    "subtotal_tax": "6.3",
                    "total": "30",
                    "total_tax": "6.3",
                    "taxes": {
                        "subtotal": {
                            "1": "6.3"
                        },
                        "total": {
                            "1": "6.3"
                        }
                    }
                }
            ],
            "po_id": 2140,
            "date_created": null,
            "date_created_gmt": null,
            "_links": {
                "self": [
                    {
                        "href": "https://example.com/wp-json/wc/v3/atum/invoice/2152"
                    }
                ],
                "collection": [
                    {
                        "href": "https://example.com/wp-json/wc/v3/atum/invoice"
                    }
                ]
            }
        }
    ]
}

Invoice propertiesCopy Anchor Link

Invoice - Items propertiesCopy Anchor Link

Create an invoiceCopy Anchor Link

HTTP requestCopy Anchor Link

Retrieve an invoiceCopy Anchor Link

HTTP requestCopy Anchor Link

Available parametersCopy Anchor Link

List all invoicesCopy Anchor Link

HTTP requestCopy Anchor Link

Available parametersCopy Anchor Link

Update an invoiceCopy Anchor Link

HTTP requestCopy Anchor Link

Delete an invoiceCopy Anchor Link

HTTP requestCopy Anchor Link

Batch update invoicesCopy Anchor Link

HTTP requestCopy Anchor Link

On this page

Invoice properties

Invoice - Items properties

Create an invoice

HTTP request

Retrieve an invoice

HTTP request

Available parameters

List all invoices

HTTP request

Available parameters

Update an invoice

HTTP request

Delete an invoice

HTTP request

Batch update invoices

HTTP request