Get Customer Invoice

About

The customerInvoice query retrieves detailed information for a specific invoice by its IRI identifier. Customers can only access invoices from their own orders — requesting another customer's invoice returns a not found error, preventing enumeration attacks. Use this query to:

• Display detailed invoice information
• Show invoice summary with line items and totals
• Track payment state and transaction details
• View tax, shipping, and discount breakdowns
• Display financial details for a specific invoice

Authentication

This query requires customer authentication:

• Authenticated customers: Provide a valid customer authentication token in the Authorization header. Obtain this token via the Customer Login API.

Authorization: Bearer <accessToken>
X-STOREFRONT-KEY: <storefrontKey>

Arguments

Argument	Type	Required	Description
id	ID!	✅ Yes	The IRI identifier of the customer invoice (e.g. /api/shop/customer-invoices/1).

Possible Returns

Field	Type	Description
_id	Int!	Numeric invoice ID.
incrementId	String!	Human-readable invoice number (e.g. INV-001).
state	String!	Invoice state: pending, pending_payment, paid, overdue, refunded.
totalQty	Int!	Total quantity of items in the invoice.
emailSent	Boolean	Whether the invoice email was sent.
grandTotal	Float!	Grand total.
baseGrandTotal	Float!	Base grand total.
subTotal	Float!	Sub total.
baseSubTotal	Float!	Base sub total.
shippingAmount	Float	Shipping amount.
baseShippingAmount	Float	Base shipping amount.
taxAmount	Float	Tax amount.
baseTaxAmount	Float	Base tax amount.
discountAmount	Float	Discount amount.
baseDiscountAmount	Float	Base discount amount.
shippingTaxAmount	Float	Shipping tax amount.
baseShippingTaxAmount	Float	Base shipping tax amount.
subTotalInclTax	Float	Sub total including tax.
baseSubTotalInclTax	Float	Base sub total including tax.
shippingAmountInclTax	Float	Shipping amount including tax.
baseShippingAmountInclTax	Float	Base shipping amount including tax.
baseCurrencyCode	String!	Base currency code (e.g. USD).
channelCurrencyCode	String	Channel currency code.
orderCurrencyCode	String!	Order currency code.
transactionId	String	Payment transaction ID.
reminders	Int	Number of reminders sent.
nextReminderAt	DateTime	Next reminder scheduled date.
createdAt	DateTime!	Invoice creation timestamp.
updatedAt	DateTime!	Invoice last update timestamp.
downloadUrl	String	URL to download the invoice as PDF.

Error Handling

Invoice Not Found

{
  "errors": [
    {
      "message": "Customer invoice with ID \"999\" not found.",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["customerInvoice"]
    }
  ]
}

Unauthenticated Request

{
  "errors": [
    {
      "message": "Customer is not logged in.",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["customerInvoice"]
    }
  ]
}

Use Cases

• Display detailed invoice page in customer account
• Show full financial breakdown of an invoice
• Track payment state and transaction ID
• View tax and shipping details
• Check if invoice email was sent

Notes

• Customer isolation: Invoices are scoped through the order relationship. A customer can only access invoices from their own orders.
• Read-only: Only query operations are available. Invoices cannot be modified through this API.

Related Resources

• Get All Customer Invoices — Query all customer invoices
• Get Customer Orders — Query customer orders
• Get Customer Profile — Query customer profile