Get Customer Invoices

About

The customerInvoices query retrieves a paginated list of invoices belonging to the authenticated customer's orders. This is a read-only API — customers can only view their own invoices. Use this query to:

• Display invoice history in the customer's account dashboard
• Show invoice list with state, totals, and dates
• Filter invoices by order ID or payment state
• Implement pagination for customers with many invoices
• Build invoice tracking interfaces

Invoices are automatically scoped to the authenticated customer via the order relationship.

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
first	Int	❌ No	Number of items to return (forward pagination). Max: 100.
after	String	❌ No	Cursor for forward pagination. Use endCursor from previous response.
last	Int	❌ No	Number of items for backward pagination. Max: 100.
before	String	❌ No	Cursor for backward pagination. Use startCursor from previous response.
orderId	Int	❌ No	Filter invoices by order ID.
state	String	❌ No	Filter by invoice state: pending, pending_payment, paid, overdue, refunded.

Possible Returns

Field	Type	Description
edges	[CustomerInvoiceEdge!]	Array of invoice edges with cursor and node.
edges.cursor	String!	Cursor for this edge, used in pagination.
edges.node	CustomerInvoice!	The customer invoice object.
edges.node._id	Int!	Numeric invoice ID.
edges.node.incrementId	String!	Human-readable invoice number (e.g. INV-001).
edges.node.state	String!	Invoice state: pending, pending_payment, paid, overdue, refunded.
edges.node.totalQty	Int!	Total quantity of items in the invoice.
edges.node.emailSent	Boolean	Whether the invoice email was sent.
edges.node.grandTotal	Float!	Grand total.
edges.node.baseGrandTotal	Float!	Base grand total.
edges.node.subTotal	Float!	Sub total.
edges.node.baseSubTotal	Float!	Base sub total.
edges.node.shippingAmount	Float	Shipping amount.
edges.node.baseShippingAmount	Float	Base shipping amount.
edges.node.taxAmount	Float	Tax amount.
edges.node.baseTaxAmount	Float	Base tax amount.
edges.node.discountAmount	Float	Discount amount.
edges.node.baseDiscountAmount	Float	Base discount amount.
edges.node.shippingTaxAmount	Float	Shipping tax amount.
edges.node.baseShippingTaxAmount	Float	Base shipping tax amount.
edges.node.subTotalInclTax	Float	Sub total including tax.
edges.node.baseSubTotalInclTax	Float	Base sub total including tax.
edges.node.shippingAmountInclTax	Float	Shipping amount including tax.
edges.node.baseShippingAmountInclTax	Float	Base shipping amount including tax.
edges.node.baseCurrencyCode	String!	Base currency code (e.g. USD).
edges.node.channelCurrencyCode	String	Channel currency code.
edges.node.orderCurrencyCode	String!	Order currency code.
edges.node.transactionId	String	Payment transaction ID.
edges.node.reminders	Int	Number of reminders sent.
edges.node.nextReminderAt	DateTime	Next reminder scheduled date.
edges.node.createdAt	DateTime!	Invoice creation timestamp.
edges.node.updatedAt	DateTime!	Invoice last update timestamp.
pageInfo	PageInfo!	Pagination metadata.
pageInfo.hasNextPage	Boolean!	Whether more pages exist forward.
pageInfo.hasPreviousPage	Boolean!	Whether more pages exist backward.
pageInfo.startCursor	String	Cursor for first item in page.
pageInfo.endCursor	String	Cursor for last item in page.
totalCount	Int!	Total invoices matching filters.

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

Use Cases

1. Invoice History Dashboard

Fetch all customer invoices to display in the account dashboard with pagination.

2. Order-Specific Invoices

Filter by orderId to show all invoices associated with a specific order.

3. Paid Invoices

Filter by state: "paid" to show confirmed payment history.

4. Pending Payments

Filter by state: "pending" or state: "pending_payment" to show outstanding invoices.

Best Practices

1. Use Pagination — Always implement pagination for better performance
2. Show State — Display the invoice state prominently so customers can track payment status
3. Filter by Order — Use orderId filter when showing invoices within an order detail page
4. Cache Results — Cache invoice lists for better performance
5. Handle Empty States — Provide helpful UI when the customer has no invoices

Error Handling

Unauthenticated Request

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

Related Resources

• Get Single Customer Invoice — Query individual invoice details
• Get Customer Orders — Query customer orders
• Get Customer Profile — Query customer profile
• Pagination Guide — Cursor pagination documentation