--- title: "List Invoices" method: GET path: "/v1/invoices" tags: ["Invoices"] --- # List Invoices `GET /v1/invoices` List invoices ## Query parameters - `expand` string — Comma-separated list of related objects to expand in the response. - `customer` string, nullable — Filter invoices by customer ID - `starting_after` string, nullable — A cursor for use in pagination. `starting_after` is an invoice ID that defines your place in the list. For instance, if you make a list request and receive 20 invoices, ending with `fin_xyz`, your subsequent call can include `starting_after=fin_xyz` to fetch the next page. - `ending_before` string, nullable — A cursor for use in pagination. `ending_before` is an invoice ID that defines your place in the list. For instance, if you make a list request and receive 20 invoices, starting with `fin_abc`, your subsequent call can include `ending_before=fin_abc` to fetch the previous page. - `limit` integer, nullable — A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. ## Response `200` An envelope wrapping a list of invoice objects. - MultipleInvoicesBodyForInvoice — An envelope wrapping a list of invoice objects. - `invoices` Invoice[], required — The list of invoices. - `invoice_id` string, required — The id of the invoice. - `total` integer, required — The total amount of the invoice in cents. - `amount_due` integer, required — The amount due in cents. - `amount_paid` integer, required — The amount paid in cents. - `payment_intent` union — An expandable field — either a string ID or an expanded PaymentIntent object. - string - PaymentIntent — A PaymentIntent tracks Flex's process of collecting a payment from a customer: the amount to collect, its lifecycle status, and references to the customer, payment method, and resulting charge. A single PaymentIntent may produce several charges over its lifetime (for example after a retry); the most recent is referenced by `latest_charge`. - `payment_intent_id` string, required — The unique identifier for the payment intent. - `amount` integer, required — The amount of the payment intent in cents. - `amount_capturable` integer, nullable — The amount that can be captured from this PaymentIntent. - `amount_received` integer, nullable — The amount that was received in cents. - `application_fee_amount` integer, nullable — The amount of the Flex application fee. - `customer` union — An expandable field — either a string ID or an expanded Customer object. - string - Customer — A Customer object represents a customer of your business. Use it to track payments, store reusable payment methods, and reference the customer on checkout sessions, invoices, and subscriptions. - `customer_id` string, required — The unique identifier for the customer. - `owner_partner_id` string, nullable — The partner that owns this customer. When a customer is shared with you by another partner in your organization, this is that sibling partner; otherwise it is your own partner id. - `first_name` string, required — The customer's first name. - `last_name` string, required — The customer's last name. - `email` string, email, required — The customer's email address. - `phone` string, phone, nullable — The customer's phone number. - `employer` string, nullable — The customer's employer. - `shipping` ShippingAddress — A ShippingAddress represents the postal address a physical order is delivered to. It is referenced by checkout sessions and customers. - … - `metadata` object, nullable — Metadata associated with the customer. - `created_at` string, required — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `test_mode` boolean, required — Whether the customer was created in test mode. - `transfer_data` TransferData — Describes how funds collected by a PaymentIntent are routed to your account. Present only when the payment carries an application fee or an explicit transfer amount. - `amount` integer, nullable — The amount to transfer, in cents. - `destination` string, required — The destination account of the transfer. - `status` 'canceled' | 'processing' | 'requires_action' | 'requires_capture' | 'requires_confirmation' | 'requires_payment_method' | 'succeeded', required — The current lifecycle status of the payment intent. - `latest_charge` union — An expandable field — either a string ID or an expanded Charge object. - string - Charge — A Charge represents a single attempt to move funds for a payment, including its outcome and any 3D Secure, decline, and risk details. A PaymentIntent can have multiple charges over its lifetime (for example after a retry); the most recent is referenced by the PaymentIntent's `latest_charge`. - `charge_id` string, required — Unique identifier for the charge. - `amount` integer, required — Amount intended to be collected by this payment. - `amount_captured` integer, required — Amount in cents captured (can be less than the amount attribute on the charge if a partial capture was made). - `amount_refunded` integer, required — Amount in cents refunded (can be less than the amount attribute on the charge if a partial refund was made). - `application_fee_amount` integer, nullable — The Flex application fee for the charge - `captured` boolean, required — If the charge was created without capturing, this Boolean represents whether it is still uncaptured or has since been captured. - `created_at` string, required — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `customer` union — An expandable field — either a string ID or an expanded Customer object. - … - `invoice` union — An expandable field — either a string ID or an expanded Invoice object. - … - `failure_message` string, nullable — Message to user further explaining reason for charge failure if available. - `disputed` boolean, required — Whether the charge has been disputed. - `paid` boolean, required — true if the charge succeeded, or was successfully authorized for later capture. - `refunded` boolean, required — Whether the charge has been fully refunded. If the charge is only partially refunded, this attribute will still be false. - `refunds` ExpandableForRefund[], nullable — A list of refunds that have been applied to the charge. - … - `payment_intent` ExpandableForPaymentIntent, required — recursive - `status` 'succeeded' | 'pending' | 'failed', required — The outcome of the charge. - `test_mode` boolean, required — Whether the charge was created in test mode. - `transfer_group` string, nullable — A string that identifies the resulting payment as part of a group - `payment_method_id` string, nullable — The ID of the PaymentMethod. - `three_d_secure` ThreeDSecureOutcome — 3D Secure authentication outcome for the charge. - … - `decline_details` DeclineDetails — Decline and risk details captured at the time of a failed or blocked charge. Absent for successful, non-declined charges. - … - `balance_transaction` union — An expandable field — either a string ID or an expanded BalanceTransaction object. - … - `failure_balance_transaction` union — An expandable field — either a string ID or an expanded BalanceTransaction object. - … - `created_at` string, required — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `invoice` union — An expandable field — either a string ID or an expanded Invoice object. - string - Invoice — recursive - `capture_method` 'automatic' | 'automatic_async' | 'manual', required — Controls when funds are captured: automatically once the payment is confirmed, or manually at a later time. - `client_secret` string, nullable — The client secret of the payment intent. - `metadata` object, nullable — The metadata associated with the payment intent. - `payment_method` union — An expandable field — either a string ID or an expanded PaymentMethod object. - string - PaymentMethod — A PaymentMethod object represents a customer's payment instrument (such as a card) that can be used to collect payments. Attach it to a Customer to reuse it across checkout sessions, invoices, and subscriptions. - `payment_method_id` string, required — The ID of the PaymentMethod. - `billing_details` BillingDetails, required — Billing information associated with a PaymentMethod, such as the cardholder's billing address, email, name, and phone number. - … - `customer` union, required — An expandable field — either a string ID or an expanded Customer object. - … - `metadata` object, nullable — Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. - `card` Card, required — A Card object describes the card backing a PaymentMethod, including its brand, funding type, expiration, and the last four digits. - … - `created_at` string, required — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `test_mode` boolean, required — Whether this PaymentMethod is in test mode. - `off_session` boolean, required — Whether this PaymentMethod is valid for off_session (customer not present) purchase flows. - `test_mode` boolean, required — Whether the payment intent is in test mode. - `transfer_group` string, nullable — A string that identifies the resulting payment as part of a group - `payment_card_type` 'primary' | 'secondary' — - `primary`: In a split cart, `Primary` refers to the HSA/FSA eligible card. In a single cart (whether it's HSA/FSA or a fully ineligible cart), `Primary` refers to the only payment card used. - `secondary`: In a split cart and partial authorization payment, `Secondary` refers to the non-eligible or backup credit card used for ineligible items. - `letter_fee_amount` integer, nullable — Letter fee portion of application_fee_amount (waterfall allocation to HSA/FSA) - `transaction_fee` integer, nullable — Transaction fee portion of application_fee_amount (percentage + fixed fee) - `last_payment_error` LastPaymentError — Structured error details from the most recent failed payment attempt on a payment intent. - `type` string, required — The type of error (card, invalid_request, api, etc.) - `code` string, nullable — Machine-readable error code (card_declined, expired_card, etc.) - `decline_code` string, nullable — Card-specific decline code (insufficient_funds, lost_card, etc.) - `message` string, nullable — Human-readable error description. - `payment_method` string, nullable — The Flex payment method ID that failed. - `charge` string, nullable — The id of the latest charge for this invoice. - `customer` union — An expandable field — either a string ID or an expanded Customer object. - string - Customer — A Customer object represents a customer of your business. Use it to track payments, store reusable payment methods, and reference the customer on checkout sessions, invoices, and subscriptions. - `customer_id` string, required — The unique identifier for the customer. - `owner_partner_id` string, nullable — The partner that owns this customer. When a customer is shared with you by another partner in your organization, this is that sibling partner; otherwise it is your own partner id. - `first_name` string, required — The customer's first name. - `last_name` string, required — The customer's last name. - `email` string, email, required — The customer's email address. - `phone` string, phone, nullable — The customer's phone number. - `employer` string, nullable — The customer's employer. - `shipping` ShippingAddress — A ShippingAddress represents the postal address a physical order is delivered to. It is referenced by checkout sessions and customers. - `shipping_address_id` string, required — Unique identifier for the shipping address. - `line1` string, nullable — The first line of the street address (e.g., street number and name). - `line2` string, nullable — The second line of the street address (e.g., apartment, suite, or unit). - `city` string, nullable — City, district, suburb, town, or village. - `state` string, nullable — State, county, province, or region. - `postal_code` string, nullable — ZIP or postal code. - `country` string, nullable — Two-letter country code (ISO 3166-1 alpha-2, e.g., `US`). - `metadata` object, nullable — Metadata associated with the customer. - `created_at` string, required — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `test_mode` boolean, required — Whether the customer was created in test mode. - `period_end` string — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `period_start` string — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `subscription` union — An expandable field — either a string ID or an expanded Subscription object. - string - Subscription — A Subscription represents a recurring billing arrangement that charges a customer at a fixed interval. It tracks the items being billed, the current billing period, its lifecycle status, and the invoices it generates each cycle. - `subscription_id` string, required — Unique identifier for the object. - `created_at` string, required — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `items` V1SubscriptionItem[], required — The items the customer is subscribed to. - `subscription_item_id` string, required — Unique identifier for the subscription item. - `price` union, required — An expandable field — either a string ID or an expanded Price object. - string - Price — Prices define the unit cost and (optional) billing cycle for both recurring and one-time purchases of products. Prices belong to a given product. Different physical goods or levels of service should be represented by products, and pricing options should be represented by prices. - … - `quantity` integer, required — The number of units of the price the customer is subscribed to. - `created_at` string, required — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `updated_at` string — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `test_mode` boolean, required — Whether the subscription item exists in test mode. - `latest_invoice` union — An expandable field — either a string ID or an expanded Invoice object. - string - Invoice — recursive - `customer` union — An expandable field — either a string ID or an expanded Customer object. - string - Customer — A Customer object represents a customer of your business. Use it to track payments, store reusable payment methods, and reference the customer on checkout sessions, invoices, and subscriptions. - `customer_id` string, required — The unique identifier for the customer. - `owner_partner_id` string, nullable — The partner that owns this customer. When a customer is shared with you by another partner in your organization, this is that sibling partner; otherwise it is your own partner id. - `first_name` string, required — The customer's first name. - `last_name` string, required — The customer's last name. - `email` string, email, required — The customer's email address. - `phone` string, phone, nullable — The customer's phone number. - `employer` string, nullable — The customer's employer. - `shipping` ShippingAddress — A ShippingAddress represents the postal address a physical order is delivered to. It is referenced by checkout sessions and customers. - … - `metadata` object, nullable — Metadata associated with the customer. - `created_at` string, required — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `test_mode` boolean, required — Whether the customer was created in test mode. - `status` 'incomplete' | 'incomplete_expired' | 'trialing' | 'active' | 'past_due' | 'canceled' | 'unpaid' | 'paused', required — The current lifecycle status of the subscription. - `cancel_at_period_end` boolean, required — If the subscription has been canceled with the at_period_end flag set to true, cancel_at_period_end on the subscription will be true. You can use this attribute to determine whether a subscription that has a status of active is scheduled to be canceled at the end of the current period. - `current_period_end` string — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `current_period_start` string — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `metadata` object, nullable — A set of key/value pairs that you can attach to a subscription object. - `test_mode` boolean, required — Whether the subscription is in test mode. - `client_secret` SubscriptionClientSecret — Client secrets used to confirm the subscription's first payment or payment-method setup from your frontend. Present only while the subscription is being activated. - `setup_secret` string, nullable — Client secret of the SetupIntent used to collect and save a payment method for the subscription (for example, during a trial with no immediate charge). `null` when no setup is required. Do not log or store it; expose only to the customer over TLS. - `payment_secret` string, nullable — Client secret of the PaymentIntent used to confirm the subscription's first payment from your frontend. `null` when no immediate payment is required. Do not log or store it; expose only to the customer over TLS. - `proration_behavior` 'always_invoice' | 'create_prorations' | 'none' — How proration is handled when the subscription changes mid-billing-cycle. - `trial_start` string — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `trial_end` string — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `cancel_at` string — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `canceled_at` string — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `default_payment_method` union — An expandable field — either a string ID or an expanded PaymentMethod object. - string - PaymentMethod — A PaymentMethod object represents a customer's payment instrument (such as a card) that can be used to collect payments. Attach it to a Customer to reuse it across checkout sessions, invoices, and subscriptions. - `payment_method_id` string, required — The ID of the PaymentMethod. - `billing_details` BillingDetails, required — Billing information associated with a PaymentMethod, such as the cardholder's billing address, email, name, and phone number. - … - `customer` union, required — An expandable field — either a string ID or an expanded Customer object. - … - `metadata` object, nullable — Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. - `card` Card, required — A Card object describes the card backing a PaymentMethod, including its brand, funding type, expiration, and the last four digits. - … - `created_at` string, required — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `test_mode` boolean, required — Whether this PaymentMethod is in test mode. - `off_session` boolean, required — Whether this PaymentMethod is valid for off_session (customer not present) purchase flows. - `discounts` Discount[], nullable — The discounts applied to the subscription. Only present when `expand=discounts` is requested; omitted from the response otherwise. Usually 0–1 elements (Flex applies at most one coupon per subscription today), but modeled as an array for Stripe parity and future multi-discount support. Full `Discount` objects rather than `Expandable`: unlike the other expandable fields, `discounts` is populated only on `expand=discounts` and is always hydrated, so it never serializes as a bare ID. (The nested `source.coupon` inside each discount is still an `Expandable`, honoring `expand=discounts,coupons`.) - `discount_id` string, required — The ID of the discount. - `checkout_session` string, nullable — The checkout session that the discount was applied to. - `customer` string, nullable — The customer that the discount was applied to. - `subscription` string, nullable — The subscription that the discount was applied to. - `invoice` string, nullable — The invoice that the discount was applied to. - `source` DiscountSource, required — The source of a discount (coupon or promotion code). - `coupon` union, required — An expandable field — either a string ID or an expanded V1Coupon object. - … - `type` 'coupon' | 'promotion_code', required — The type of discount source. - `promo_code` string, nullable — The promo code applied to create the discount. - `test_mode` boolean, required — Whether the discount was applied in test mode - `end` string — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `start` string, required — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `paid_at` string — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `status` 'draft' | 'open' | 'void' | 'paid' | 'uncollectible', required — The lifecycle status of the invoice. - `collection_method` 'charge_automatically' | 'send_invoice', required — How payment for the invoice is collected: automatically from the customer's saved payment method, or by emailing them an invoice to pay. - `test_mode` boolean, required — Whether or not the invoice was created in test mode. - `metadata` object, nullable — Metadata associated with the invoice. - `created_at` string, required — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). ## Other responses - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `409` — Conflict - `422` — Validation Error - `429` — Too Many Requests --- [API](https://skmtc.dev/withflex/apis/flex-api.md) · [All operations](https://skmtc.dev/withflex/apis/flex-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/withflex/flex-api/revisions/b1560fc2f199/schema)