# Retrieve one or more invoices

Returns invoice data for one or more invoice numbers. Repeat the invoiceNumber query parameter for batch retrieval (max 50 per request). All requested invoices must be valid and eligible — if any single invoice is not found or not eligible, the entire request fails.

Endpoint: GET /v1/{countryCode}/invoices
Version: 0.0.1
Security: jwt-authorizer

## Path parameters:

  - `countryCode` (string, required)
    Enum: "au", "nz"

## Query parameters:

  - `invoiceNumber` (array, required)

## Response 200 fields (application/json):

  - `invoices` (array, required)
    List of all requested invoices. Only returned when all invoices were successfully retrieved.

  - `invoices.number` (string, required)
    Unique invoice number.
    Example: "INV-2025-00123"

  - `invoices.type` (string, required)
    The type of invoice document.
    Enum: "CASH_SALE_INVOICE", "CUSTOMER_ORDER_DEPOSIT", "TAX_INVOICE", "CASH_ON_DELIVERY_INVOICE", "CREDIT_NOTE", "CASH_REFUND"

  - `invoices.date` (string)
    Date the invoice was issued.
    Example: "2025-07-15"

  - `invoices.dueDate` (string)
    Payment due date for the invoice.
    Example: "2025-08-15"

  - `invoices.orderedDate` (string)
    Date the order was placed.
    Example: "2025-07-14"

  - `invoices.orderNumber` (string)
    Associated order number.
    Example: "ORD-98765"

  - `invoices.originalNumber` (string)
    Reference to the original invoice (e.g., for credit notes).
    Example: "INV-2025-00100"

  - `invoices.originalType` (string)
    Invoice type of the original document.
    Example: "TAX_INVOICE"

  - `invoices.quoteNumber` (string)
    Associated quote number.
    Example: "QTE-2025-00010"

  - `invoices.jobNumber` (string)
    Associated job number.
    Example: "JOB-001"

  - `invoices.orderStage` (string)
    Current stage of the order.
    Example: "COMPLETE"

  - `invoices.fulfillmentType` (string)
    How the order was or will be fulfilled.
    Enum: "PICKUP", "DELIVERY"

  - `invoices.isSuppressed` (boolean)
    Whether the invoice is suppressed from standard outputs.

  - `invoices.isToolHire` (boolean)
    Whether this invoice relates to a tool hire transaction.

  - `invoices.handlingFeeRate` (number)
    Handling fee rate applied to the invoice.
    Example: 0.02

  - `invoices.purchaseOrderNumber` (string)
    Customer's purchase order reference number.
    Example: "PO-2025-XYZ"

  - `invoices.departmentType` (string)
    Department type associated with the invoice.
    Example: "PLUMBING"

  - `invoices.salesPersonName` (string)
    Name of the salesperson who processed the invoice.
    Example: "Jane Smith"

  - `invoices.salesPersonNumber` (string)
    Identifier of the salesperson.
    Example: "SP-001"

  - `invoices.receivedByName` (string)
    Name of the person who received the order.
    Example: "John Doe"

  - `invoices.customerCardId` (string)
    Customer identity card reference.
    Example: "CID-001"

  - `invoices.reeceId` (string)
    Reece-specific internal identifier for the contact who placed the order.
    Example: "REECE-001"

  - `invoices.comments` (array)
    Free-text comments on the invoice.

  - `invoices.customer` (object)

  - `invoices.customer.number` (string)
    Example: "C001234"

  - `invoices.customer.name` (string)
    Example: "Acme Plumbing"

  - `invoices.customer.abn` (string)
    Australian Business Number.
    Example: "12345678901"

  - `invoices.customer.homeBranchNumber` (string)
    Example: "MEL01"

  - `invoices.customer.homeBranch` (object)

  - `invoices.customer.homeBranch.number` (string)
    Example: "MEL01"

  - `invoices.customer.homeBranch.name` (string)
    Example: "Melbourne CBD"

  - `invoices.customer.homeBranch.phoneNumber` (string)
    Example: "03 9000 0000"

  - `invoices.customer.isGstExempt` (boolean)

  - `invoices.customer.tradeType` (string)
    Example: "TRADE"

  - `invoices.customer.gstRate` (number)
    Example: 0.1

  - `invoices.customer.paymentTermsDays` (integer)
    Number of days allowed for payment.
    Example: 30

  - `invoices.customer.invoiceType` (string)
    Example: "TAX_INVOICE"

  - `invoices.customerContact` (object)

  - `invoices.customerContact.firstName` (string)
    Example: "John"

  - `invoices.customerContact.lastName` (string)
    Example: "Doe"

  - `invoices.customerContact.preferredPhoneNumber` (string)
    Example: "03 9000 0000"

  - `invoices.customerContact.mobilePhoneNumber` (string)
    Example: "0400 000 000"

  - `invoices.customerContact.emailAddress` (string)
    Example: "john.doe@acme.com"

  - `invoices.supplier` (object)

  - `invoices.supplier.id` (integer)
    Example: 1

  - `invoices.supplier.shortName` (string)
    Example: "REECE"

  - `invoices.supplier.name` (string)
    Example: "Reece Pty Ltd"

  - `invoices.supplier.abnPrefix` (string)
    Label prefix for ABN display.
    Example: "ABN"

  - `invoices.supplier.abn` (string)
    Example: "98765432101"

  - `invoices.supplier.acnPrefix` (string)
    Label prefix for ACN display.
    Example: "ACN"

  - `invoices.supplier.acn` (string)
    Example: "123456789"

  - `invoices.supplier.telephoneNumber` (string)
    Example: "03 9000 0000"

  - `invoices.supplier.websiteUrl` (string)
    Example: "https://www.reece.com.au"

  - `invoices.sellingBranch` (object)

  - `invoices.invoiceAddress` (object)

  - `invoices.invoiceAddress.line1` (string)
    Example: "123 Main Street"

  - `invoices.invoiceAddress.line2` (string)
    Example: "Level 2"

  - `invoices.invoiceAddress.suburb` (string)
    Example: "Melbourne"

  - `invoices.invoiceAddress.state` (string)
    Example: "VIC"

  - `invoices.invoiceAddress.postcode` (string)
    Example: "3000"

  - `invoices.deliveryDetails` (object)

  - `invoices.deliveryDetails.type` (string)
    Enum: "BY_SUPPLIER", "BY_COURIER", "CUSTOMER_PICKUP", "BY_REECE"

  - `invoices.deliveryDetails.address` (object)

  - `invoices.deliveryDetails.siteContactName` (string)
    Example: "John Doe"

  - `invoices.deliveryDetails.siteContactPhoneNumber` (string)
    Example: "0400 000 000"

  - `invoices.deliveryDetails.requiredDeliveryDate` (string)
    Example: "2025-07-16"

  - `invoices.deliveryDetails.deliveredDate` (string)
    Example: "2025-07-16"

  - `invoices.totals` (object)

  - `invoices.totals.net` (object)
    An amount with GST breakdown.

  - `invoices.totals.net.excludingGst` (number)
    Example: 450

  - `invoices.totals.net.gst` (number)
    Example: 45

  - `invoices.totals.net.includingGst` (number)
    Example: 495

  - `invoices.totals.document` (object)
    An amount with GST breakdown.

  - `invoices.totals.subtotal` (object)
    An amount with GST breakdown.

  - `invoices.totals.handlingFee` (object)
    An amount with GST breakdown.

  - `invoices.totals.deliveryFee` (object)
    An amount with GST breakdown.

  - `invoices.totals.creditCardSurcharge` (object)

  - `invoices.totals.creditCardSurcharge.cardType` (string)
    Example: "VISA"

  - `invoices.totals.creditCardSurcharge.amount` (object)
    An amount with GST breakdown.

  - `invoices.totals.rounding` (number)
    Example: 0.01

  - `invoices.totals.settlementDiscount` (number)
    Example: 5

  - `invoices.lineItems` (array)
    Line items on the invoice.

  - `invoices.lineItems.number` (integer, required)
    Line number on the invoice.
    Example: 1

  - `invoices.lineItems.lineItemType` (string)
    Type of line item.
    Enum: "KIT_HEADER", "KIT_COMPONENT", "STANDARD"

  - `invoices.lineItems.productNumber` (string, required)
    Product code.
    Example: "P987654"

  - `invoices.lineItems.productDescription` (string)
    Description of the product.
    Example: "Copper Pipe 15mm"

  - `invoices.lineItems.unitOfMeasure` (string)
    Unit of measure for the product.
    Example: "EA"

  - `invoices.lineItems.quantity` (number, required)
    Quantity ordered.
    Example: 10

  - `invoices.lineItems.priceBasis` (integer)
    Pricing basis code.
    Example: 1

  - `invoices.lineItems.priceOrigin` (string,null)
    Pricing origin code indicating the source of the price.
    Example: "BC"

  - `invoices.lineItems.priceOverriddenFlag` (string)
    Indicates whether the price was overridden and by what means.
    Example: "B"

  - `invoices.lineItems.unitPriceExcludingGst` (number)
    Unit price excluding GST.
    Example: 45

  - `invoices.lineItems.lineTotal` (object)
    Total amount for this line (excluding and including GST).

  - `invoices.lineItems.lineTotal.excludingGst` (number)
    Example: 450

  - `invoices.lineItems.lineTotal.gst` (number)
    Example: 45

  - `invoices.lineItems.lineTotal.includingGst` (number)
    Example: 495

  - `invoices.lineItems.isGstExempt` (boolean)
    Whether this line is GST exempt.

  - `invoices.lineItems.unitCost` (number)
    Unit cost of the product.
    Example: 32

  - `invoices.lineItems.branchSupplyingStock` (string)
    Branch that supplied the stock for this line.
    Example: "MEL01"

  - `invoices.lineItems.catalogueNumber` (string)
    Catalogue reference number.
    Example: "CAT-001"

  - `invoices.lineItems.chargeType` (string)
    Charge type code applied to this line.
    Example: "STANDARD"

  - `invoices.lineItems.sourceDocument` (object)

  - `invoices.lineItems.sourceDocument.reference` (string)
    Reference identifier from the source document.
    Example: "ORD-98765"

  - `invoices.lineItems.sourceDocument.type` (string)
    Type of the source document.
    Example: "SALES_ORDER"

  - `invoices.lineItems.sourceDocument.lineNumber` (integer)
    Line number on the source document.
    Example: 1

  - `invoices.lineItems.originalInvoiceNumber` (string)
    Original invoice number this line relates to (e.g., for credits).
    Example: "INV-2025-00100"

  - `invoices.lineItems.kitComponents` (array)
    Kit components for KIT_HEADER line items.

  - `invoices.lineItems.kitComponents.number` (integer)
    Line number of the kit component.
    Example: 2

  - `invoices.lineItems.kitComponents.productNumber` (string)
    Product code of the kit component.
    Example: "P111111"

  - `invoices.lineItems.kitComponents.productDescription` (string)
    Description of the kit component product.
    Example: "Fitting 15mm"

  - `invoices.lineItems.kitComponents.unitOfMeasure` (string)
    Unit of measure.
    Example: "EA"

  - `invoices.lineItems.kitComponents.quantity` (number)
    Quantity of this component.
    Example: 2

  - `invoices.lineItems.kitComponents.unitCost` (number)
    Unit cost of the component.
    Example: 5

  - `invoices.lineItems.kitComponents.priceBasis` (integer)
    Pricing basis code.
    Example: 1

  - `invoices.lineItems.kitComponents.sourceDocument` (object)

  - `invoices.payments` (array)
    Payments applied to this invoice.

  - `invoices.payments.type` (string)
    Example: "CREDIT_CARD"

  - `invoices.payments.typeCode` (string)
    Example: "CC"

  - `invoices.payments.creditCardType` (string)
    Example: "VISA"

  - `invoices.payments.baseAmount` (number)
    Base payment amount (before surcharges).
    Example: 495

  - `invoices.payments.amexSurcharge` (number)

  - `invoices.payments.totalAmount` (number)
    Total payment amount (including surcharges).
    Example: 495

  - `invoices.customerOrderBalance` (object)

  - `invoices.customerOrderBalance.customerOrderNumber` (string)
    Example: "CO-2025-001"

  - `invoices.customerOrderBalance.customerOrderValue` (number)
    Example: 1000

  - `invoices.customerOrderBalance.paymentsReceived` (number)
    Example: 495

  - `invoices.customerOrderBalance.adjustment` (number)

  - `invoices.customerOrderBalance.balanceOwing` (number)
    Example: 505

  - `invoices.customerOrderBalance.balanceOwingFormatted` (string)
    Human-readable formatted balance.
    Example: "$505.00"

  - `invoices.customerOrderBalance.asOf` (string)
    Example: "2025-07-15"

  - `invoices.customFields` (object)

  - `invoices.customFields.costCentre` (string)
    Example: "CC-001"

  - `invoices.transactionRequirements` (array)
    Additional customer transaction requirements.

  - `invoices.transactionRequirements.label` (string)
    Example: "Cost Centre"

  - `invoices.transactionRequirements.value` (string)
    Example: "CC-001"

## Response 400 fields (application/json):

  - `errorCode` (string, required)
    Stable machine-readable error identifier.
    Example: "RESOURCE_NOT_FOUND"

  - `message` (string, required)
    Human-readable error description.
    Example: "The requested invoice was not found."

  - `status` (integer)
    HTTP status code.
    Example: 404

  - `timestamp` (string)
    Example: "2026-06-04T10:15:30Z"

  - `instance` (string)
    The request path that caused the error.
    Example: "/v1/au/invoices/INV-2025-00123"

  - `details` (array, required)

  - `details.field` (string)
    Example: "invoiceNumber"

  - `details.issue` (string)
    Example: "Must not be empty"

## Response 401 fields (application/json):

  - `errorCode` (string, required)
    Stable machine-readable error identifier.
    Example: "RESOURCE_NOT_FOUND"

  - `message` (string, required)
    Human-readable error description.
    Example: "The requested invoice was not found."

  - `status` (integer)
    HTTP status code.
    Example: 404

  - `timestamp` (string)
    Example: "2026-06-04T10:15:30Z"

  - `instance` (string)
    The request path that caused the error.
    Example: "/v1/au/invoices/INV-2025-00123"

  - `details` (array)