Invoice an order#

This guide walks through invoicing the items of an order: determining which items are ready to be invoiced, creating the invoice with invoiceItems, then retrieving the invoice details and PDF.

Overview#

Check the order's actions for the INVOICE action to find the invoiceable item IDs
Create the invoice with invoiceItems
Fetch the invoice details with the invoice query

Step 1 — Find the invoiceable items#

The order's actions array tells you which items are ready to be invoiced. Look for the entry with action INVOICE — its ids are the order item IDs to put on the invoice.

query getOrderActions($id: String!) {
  order(id: $id) {
    id
    actions {
      action
      ids
    }
  }
}

{ "id": "72fca344-2a6f-4c3e-b4ca-029920b2522a" }

Example response:

{
  "order": {
    "id": "72fca344-2a6f-4c3e-b4ca-029920b2522a",
    "actions": [
      {
        "action": "INVOICE",
        "ids": [
          "5a6b7c8d-9e0f-1234-5678-9abcdef01234",
          "6b7c8d9e-0f1a-2345-6789-0abcdef12345",
          "7c8d9e0f-1a2b-3456-789a-bcdef0123456"
        ]
      }
    ]
  }
}

ℹ

Tip:

When an order is configured for invoicing after shipment, items only become invoiceable once they are shipped. An empty actions array (or no INVOICE entry) means there is nothing to invoice right now.

Step 2 — Create the invoice#

Put the items on an invoice. All items must belong to orders of the same customer; items from multiple orders of the same customer can be combined on one invoice.

Input: InvoiceItemsInput!

Name	Type	Required	Description
`items`	[String!]!	Required	The order item IDs to add on the invoice.
`invoice_id`	String	Optional	Specify an ID to use as the invoice ID — when omitted, one is generated.

Returns: InvoiceItemsPayload

Name	Type	Required	Description
`invoice`	Invoice▾	Optional	The created invoice

mutation InvoiceItems($input: InvoiceItemsInput!) {
  invoiceItems(input: $input) {
    invoice {
      id
      number
      total
      currency
    }
  }
}

{
  "input": {
    "items": [
      "5a6b7c8d-9e0f-1234-5678-9abcdef01234",
      "6b7c8d9e-0f1a-2345-6789-0abcdef12345",
      "7c8d9e0f-1a2b-3456-789a-bcdef0123456"
    ]
  }
}

Save the returned invoice.id to fetch the full invoice in the next step.

Step 3 — Fetch the invoice#

Retrieve the full invoice, including the lines, VAT breakdown, payment status, and the PDF URL.

query getInvoice($id: String!) {
  invoice(id: $id) {
    id
    number
    created_at
    currency
    subtotal
    total
    total_ex_vat
    is_including_vat
    pdf_url
    addressee {
      country_code
      contact {
        id
      }
      organisation {
        id
      }
    }
    billing_address {
      address_line_1
      locality
      postal_code
      country_code
    }
    lines {
      label
      debit {
        quantity
        total
      }
      credit {
        quantity
        total
      }
    }
    vat {
      rate
      amount
    }
    reimbursement {
      status
    }
    orders {
      id
      number
    }
  }
}

{ "id": "8d9e0f1a-2b3c-4567-89ab-cdef01234567" }

ℹ

Tip:

pdf_url is only available after the invoice PDF has been generated. Generation can take a moment after creating the invoice — poll the invoice query until pdf_url is non-null if you need the document immediately.

Notes#

Items can only be invoiced once. After a successful invoiceItems call, the items disappear from the order's INVOICE action.
Money values (total, subtotal, total_ex_vat) are integers in cents — e.g. 2499 means € 24,99.
An invoice can span multiple orders of the same customer — pass item IDs from several orders in a single invoiceItems call to combine them. The orders field on the invoice lists all orders involved.
For crediting invoiced items after a cancellation or return, see Cancel order items and Return order items — After this flow refund the payment and invoice the cancelled/returned items to create a credit invoice.
The payment status of the invoice is available under reimbursement.
See Authentication for how to pass your API key.