Invoice

Invoices represent billing documents issued by a supplier to a buyer, recording the amounts owed for goods or services delivered.

The invoice Object

Field Name	Type	Description
id	uuid	Primary key for the invoice.
user_created	object	User who created the record. Read-only.
date_created	datetime	Timestamp in ISO 8601 when the record was created. Read-only.
user_updated	object	User who last updated the record. Read-only.
date_updated	datetime	Timestamp in ISO 8601 when the record was last updated. Read-only.
status	string	Current status of the invoice (e.g. draft, issued, paid).
invoice_number	string	Human-readable invoice number or reference.
urn	string	Uniform Resource Name uniquely identifying this invoice, for use in EPCIS messages (typically auto created by system).
invoice_issuer	object	Organisation that issued this invoice.

---

Sub-Objects

User Object (user_created, user_updated)

See Users for the full schema.

Organisation Object (invoice_issuer)

See Organisation for the full schema.

---

List Invoices

REST

GET /items/invoice

GraphQL

query {
  invoice {
    id
    status
    invoice_number
    urn
    invoice_issuer {
      id
      organisation_name
    }
  }
}

Query Parameters

Supports all global query parameters.

Returns

An array of up to limit invoice objects. If no items are available, data will be an empty array.

---

Retrieve an Invoice

REST

GET /items/invoice/:id

GraphQL

query {
  invoice_by_id(id: "invoice_id") {
    id
    status
    invoice_number
    urn
    invoice_issuer {
      id
      organisation_name
    }
    user_created {
      id
      first_name
      last_name
    }
    date_created
    user_updated {
      id
      first_name
      last_name
    }
    date_updated
  }
}

Returns

Returns an invoice object if a valid primary key was provided.

---

Create an Invoice

REST

POST /items/invoice

{
  "invoice_number": "INV-2024-001",
  "status": "issued",
  "invoice_issuer": "org-uuid"
}

GraphQL

mutation {
  create_invoice_item(data: {
    invoice_number: "INV-2024-001"
    status: "issued"
    invoice_issuer: "org-uuid"
  }) {
    id
    invoice_number
    status
  }
}

Query Parameters

Supports all global query parameters.

Request Body

A partial invoice object.

Returns

Returns the invoice object for the created record.

---

Update an Invoice

REST

PATCH /items/invoice/:id

{
  "status": "paid"
}

GraphQL

mutation {
  update_invoice_item(id: "invoice_id", data: {
    status: "paid"
  }) {
    id
    status
  }
}

Query Parameters

Supports all global query parameters.

Request Body

A partial invoice object.

Returns

Returns the invoice object for the updated record.

---

Delete an Invoice

REST

DELETE /items/invoice/:id

GraphQL

mutation {
  delete_invoice_item(id: "invoice_id") {
    id
  }
}

Returns

Empty body.