Get Customer Invoices

Retrieve all invoices belonging to the authenticated customer's orders. This is a read-only API — customers can only view their own invoices. Invoices are automatically scoped to the authenticated customer via the order relationship.

Endpoint

GET /api/shop/customer-invoices

Request Headers

Header	Required	Description
Content-Type	Yes	application/json
X-STOREFRONT-KEY	Yes	Your storefront API key
Authorization	Yes	Bearer token (customer login required)

Response Fields (200 OK)

The response is a plain JSON array of invoice objects.

Field	Type	Description
id	integer	Invoice ID
incrementId	string	Human-readable invoice number (e.g. INV-001)
state	string	Invoice state
totalQty	integer	Total quantity of items in the invoice
emailSent	boolean	Whether the invoice email was sent
subTotal	float	Sub total
baseSubTotal	float	Base sub total
grandTotal	float	Grand total
baseGrandTotal	float	Base grand 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	integer	Number of reminders sent
nextReminderAt	string	Next reminder scheduled date
order	string	Associated order IRI (e.g. /api/shop/customer-orders/1)
items	array	Invoice line item IRIs
createdAt	string	ISO 8601 creation timestamp
updatedAt	string	ISO 8601 last update timestamp

Invoice State Values

State	Description
pending	Invoice created, awaiting action
pending_payment	Payment initiated but not yet confirmed
paid	Payment received and confirmed
overdue	Payment past due date
refunded	Invoice has been refunded

Empty Collection

When the customer has no invoices, an empty array is returned:

[]

Error Responses

Unauthenticated (401):

{
  "message": "Customer is not logged in."
}

Use Cases

• Display invoice history in customer account dashboard
• Show invoice list with state, totals, and dates
• Track payment status across orders
• View financial records

Notes

• Read-only API: Only GET operations are available. Invoices cannot be created, updated, or deleted through this API.
• Customer isolation: Invoices are scoped through the order relationship. A customer can never see another customer's invoices.
• Relationships: In REST responses, relationships (order, items) are represented as IRIs (e.g. /api/shop/customer-orders/1).
• Response format: The collection endpoint returns all matching invoices as a flat JSON array.

Related Resources

• Get Single Customer Invoice
• Download Invoice PDF
• Get Customer Orders
• Get Customer Profile