The Vendor Invoice API allows you to list, create, show, and update vendor invoices for production orders.
GET all invoices
Returns vendor invoices for the current organisation.
$ curl https://api.uphance.com/vendor_invoices \
-H "Authorization: Bearer ACCESS_TOKEN"
Optional parameters:
- by_q (string) — search by vendor invoice number, production order number, or vendor name.
- by_invoice_state[] (array) — filter by state. One or more of open, overdue, closed, all. Defaults to ["open", "overdue"]. Pass all to include open + overdue; add closed to include every state. Any invalid value falls back to the default.
- by_production_order_id (integer) — return only invoices belonging to this production order.
- page (integer) — page number (default 1).
- per_page (integer) — results per page (default 100).
Invoice states are derived from the amount still outstanding (amount − payments − credits) and the due date:
- open — outstanding > 0 and not yet past the due date (or no due date).
- overdue — outstanding > 0 and the due date has passed.
- closed — nothing outstanding.
Example Response:-
{
"vendor_invoices": [
{
"id": 556,
"created_at": "2025-04-10T13:53:32.000-05:00",
"updated_at": "2025-04-10T13:53:32.000-05:00",
"vendor_invoice_number": "23456",
"invoice_date": "2025-04-09T00:00:00.000-05:00",
"due_date": "2025-04-24T00:00:00.000-05:00",
"amount": "462.0",
"items_total": "462.0",
"items_tax": "0.0",
"subtotal": "462.0",
"total_tax": "0.0",
"grand_total": "462.0",
"total_quantity": 14,
"shipping_cost": "0.0",
"shipping_tax": "0.0",
"reference": null,
"organisation_id": 35802,
"production_order_id": 22038,
"company_id": null,
"vendor_name": "&CO WOMAN",
"currency": "EUR",
"order_number": 907,
"invoice_number": "23456",
"parent_type": "ProductionOrder",
"parent_id": 22038,
"tax_calc_method": "SUB_TOTAL",
"tax_level": "0.0",
"tax_rate_id": null,
"as_charge": false,
"freeform_description": "",
"freeform_amount": null,
"freeform_currency": "",
"organisation_company_id": null,
"total": "462.0",
"amount_due": "462.0",
"amount_outstanding": "462.0",
"payments_amount": "0.0",
"total_credited": "0.0",
"delivery_name": null,
"line_items": [
{
"id": 1776,
"product_id": 110609,
"product_name": "( UN ) - DONE KNIT",
"product_identifier": "( UN ) - DONE KNIT",
"variation_id": 233040,
"color": "White",
"unit_tax": "0.0",
"tax_level": "0.0",
"unit_price": "33.0",
"original_price": "33.0",
"weight": "2.0",
"weight_unit": "lb",
"percentage_discount": "0.0",
"bundle_line_item": false,
"comments": null,
"product_brand": "Adine Undone",
"season": "Rainy",
"country_of_origin": "ID",
"intrastat_code": "",
"line_quantities": [
{
"id": 9077,
"size": "XS",
"quantity": 1,
"sku_number": "( UN ) - DONE KNIT-W-XS",
"sku_id": 1204809,
"upc_number": "1020012012",
"is_backorder": false
},
{
"id": 9078,
"size": "S",
"quantity": 2,
"sku_number": "( UN ) - DONE KNIT-W-S",
"sku_id": 1204810,
"upc_number": "1020012014",
"is_backorder": false
},
{
"id": 9079,
"size": "M",
"quantity": 2,
"sku_number": "( UN ) - DONE KNIT-W-M",
"sku_id": 1204811,
"upc_number": "1020012022",
"is_backorder": false
},
{
"id": 9080,
"size": "L",
"quantity": 2,
"sku_number": "( UN ) - DONE KNIT-W-L",
"sku_id": 1204812,
"upc_number": "1020012023",
"is_backorder": false
},
{
"id": 9081,
"size": "XL",
"quantity": 3,
"sku_number": "( UN ) - DONE KNIT-W-XL",
"sku_id": 1204813,
"upc_number": "1020012024",
"is_backorder": false
},
{
"id": 9082,
"size": "XXL",
"quantity": 4,
"sku_number": "( UN ) - DONE KNIT-W-XXL",
"sku_id": 1204814,
"upc_number": "1020012025",
"is_backorder": false
}
]
}
],
"attachments": [
{
"id": 1234,
"name": "Invoice 556",
"file_name": "invoice_556.pdf",
"url": "https://example.com/attachments/invoice_556.pdf"
}
],
"custom_fields": [
{
"name": "Packaging",
"field_type": "number",
"value": 0.0
},
{
"name": "Compliance fee",
"field_type": "number",
"value": 0.0
}
]
}
]
}
Retrieve a vendor invoice
Returns a single invoice under the vendor_invoice root key. Responds 404 if the
invoice does not belong to the current organisation.
$ curl https://api.uphance.com/vendor_invoices/1024 \
-H "Authorization: Bearer ACCESS_TOKEN"
Create a vendor invoice
A vendor invoice is created from either a production order or one of its
deliveries. Provide exactly one of production_order_id or delivery_id. The referenced production order must be confirmed.
POST https://api.uphance.com/vendor_invoices
Example Request Body:
{
"vendor_invoice": {
"production_order_id": "22216",
"vendor_invoice_number": "VI-1001",
"invoice_date": "2026-05-19",
"due_date": "2026-06-18",
"file_attachments_attributes": [
{
"name": "Supplier PDF",
"file": "multipart-file-upload"
}
]
}
}
Creatable Fields
- production_order_id (integer) — source production order. Required unless delivery_id is given.
- delivery_id (integer) — source delivery. Required unless production_order_id is given.
- vendor_invoice_number (string, required) — Supplier invoice number.
- invoice_date (date) — invoice date.
- due_date (date) — payment due date.
- file_attachments_attributes (array) — attachments (name, file / file_cache). Send as multipart/form-data when uploading binary files.
Responses:
- 201 Created — invoice created (returned under vendor_invoice).
- 422 Unprocessable Entity — validation errors, e.g. { "errors": ["Vendor invoice number can't be blank"] }, or { "error": "production_order_id or delivery_id is required" }.
- 404 Not Found — the production order/delivery is not in the current organisation, or the production order is not confirmed.
Update a vendor invoice
PUT https://api.uphance.com/vendor_invoices
Example Request Body:
{
"vendor_invoice": {
"shipping_cost": 2.0,
"vendor_invoice_number": "VI-1201",
"invoice_date": "2026-05-25",
"due_date": "2026-06-30",
"line_items_attributes": {
"id": 1790,
"line_quantities_attributes": {
"id": 9144,
"quantity": 2
}
}
"file_attachments_attributes": [
{
"id": 1234,
"name": "Supplier PDF",
"file": "multipart-file-upload"
}
]
}
}
Updatable fields:
vendor_invoice_number, invoice_date, due_date,
shipping_cost, file_attachments_attributes, and
line_items_attributes.
Responses: 200 OK with the updated invoice, or 422 with { "errors": [...] }.