> ## Documentation Index > Fetch the complete documentation index at: https://docs.stigg.io/llms.txt > Use this file to discover all available pages before exploring further. # Get a list of invoices > Retrieves a cursor-paginated list of a customer's invoices, fetched live from the connected billing provider. Ordered by issue date ascending by default; override with orderBy (issueDate | dueDate | total) and orderDir (ASC | DESC). Optionally narrowed to one contract, an issue-date range, and/or a set of invoice states. Returns an empty list when no billing provider is connected or the customer is not synced. ## OpenAPI ````yaml https://app.stainless.com/api/spec/documented/stigg/openapi.documented.yml get /api/v1/customers/{id}/invoices openapi: 3.0.0 info: title: Stigg API description: Stigg API documentation version: 7.129.2 contact: {} servers: - url: https://api.stigg.io description: Production security: - ApiKeyAuth: [] tags: - name: Customers description: Operations related to customers - name: Subscriptions description: Operations related to subscriptions - name: Coupons description: Operations related to coupons - name: Bulk Import description: Operations related to import of customers and subscriptions - name: Usage description: Operations related to usage & metering - name: Promotional Entitlements description: Operations related to promotional entitlements - name: Products description: Operations related to products - name: Features description: Operations related to features - name: Addons description: Operations related to addons - name: Plans description: Operations related to plans - name: Credit grants description: Operations related to credit grants - name: Credit ledger description: Operations related to credit ledger - name: Custom currencies description: Operations related to custom currencies paths: /api/v1/customers/{id}/invoices: get: tags: - Invoices summary: Get a list of invoices description: >- Retrieves a cursor-paginated list of a customer's invoices, fetched live from the connected billing provider. Ordered by issue date ascending by default; override with orderBy (issueDate | dueDate | total) and orderDir (ASC | DESC). Optionally narrowed to one contract, an issue-date range, and/or a set of invoice states. Returns an empty list when no billing provider is connected or the customer is not synced. operationId: CustomerInvoicesController_getCustomerInvoices parameters: - name: id required: true in: path description: >- External ID of the customer the invoice belongs to: your customer ref when mapped, otherwise the Received customer ID schema: minLength: 1 maxLength: 255 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.@-]*$ type: string - name: limit required: false in: query description: Maximum number of items to return schema: minimum: 1 maximum: 100 default: 20 type: integer - name: after required: false in: query description: Return items that come after this cursor schema: maxLength: 255 type: string - name: before required: false in: query description: Return items that come before this cursor schema: maxLength: 255 type: string - name: contractExternalId required: false in: query description: >- Filter to invoices for this contract only (contract external ID or Received contract ID). Omit for all contracts. schema: maxLength: 255 type: string - name: stateIn required: false in: query description: >- Filter by invoice state. Supports comma-separated values for multiple states schema: maxLength: 255 type: string - name: issuedAfter required: false in: query description: >- Filter to invoices issued on or after this date, inclusive (ISO 8601) schema: format: date-time type: string - name: issuedBefore required: false in: query description: >- Filter to invoices issued on or before this date, inclusive (ISO 8601) schema: format: date-time type: string - name: orderBy required: false in: query description: 'Field to sort by: issueDate (default), dueDate, or total' schema: enum: - issueDate - dueDate - total type: string - name: orderDir required: false in: query description: 'Sort direction: ASC (default) or DESC' schema: enum: - ASC - DESC type: string - name: X-ACCOUNT-ID in: header description: >- Account ID — optional when authenticating with a user JWT (Bearer token); falls back to the user's first membership. Ignored for API-key auth. required: false schema: type: string - name: X-ENVIRONMENT-ID in: header description: >- Environment ID — required when authenticating with a user JWT (Bearer token) on environment-scoped endpoints. Ignored for API-key auth (env is intrinsic to the key). required: false schema: type: string responses: '200': description: A cursor-paginated list of the customer's invoices. content: application/json: schema: $ref: '#/components/schemas/InvoiceListResponseDto' examples: default: value: data: - invoiceId: inv_1a2b3c4d invoiceExternalId: inv_1a2b3c4d invoiceNumber: INV-1024 contractExternalId: contract-acme-2026 customerExternalId: customer-acme state: PAID issueDate: '2026-03-01T00:00:00.000Z' dueDate: '2026-03-31T00:00:00.000Z' paidDate: '2026-03-15T00:00:00.000Z' currency: usd subtotal: 100 tax: 8 discount: 5 total: 103 lineItems: - description: Enterprise Platform — March 2026 quantity: 1 unitPrice: 100 amount: 100 productExternalId: product-revvenu pagination: next: null prev: null '400': description: bad request. content: application/json: schema: $ref: '#/components/schemas/BadInputErrorResponseDto' '401': description: User is not authenticated. content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedErrorResponseDto' '403': description: User is not allowed to access this resource. content: application/json: schema: $ref: '#/components/schemas/ForbiddenErrorResponseDto' '429': description: Too many requests. content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponseDto' x-codeSamples: - lang: JavaScript source: >- import Stigg from '@stigg/typescript'; const client = new Stigg({ apiKey: process.env['STIGG_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const customerListInvoicesResponse of client.v1.customers.listInvoices('id')) { console.log(customerListInvoicesResponse.paidDate); } - lang: Python source: |- import os from stigg import Stigg client = Stigg( api_key=os.environ.get("STIGG_API_KEY"), # This is the default and can be omitted ) page = client.v1.customers.list_invoices( id="id", ) page = page.data[0] print(page.paid_date) - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/stiggio/stigg-go\"\n\t\"github.com/stiggio/stigg-go/option\"\n)\n\nfunc main() {\n\tclient := stigg.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tpage, err := client.V1.Customers.ListInvoices(\n\t\tcontext.TODO(),\n\t\t\"id\",\n\t\tstigg.V1CustomerListInvoicesParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", page)\n}\n" - lang: Java source: |- package io.stigg.example; import io.stigg.client.StiggClient; import io.stigg.client.okhttp.StiggOkHttpClient; import io.stigg.models.v1.customers.CustomerListInvoicesPage; import io.stigg.models.v1.customers.CustomerListInvoicesParams; public final class Main { private Main() {} public static void main(String[] args) { StiggClient client = StiggOkHttpClient.fromEnv(); CustomerListInvoicesPage page = client.v1().customers().listInvoices("id"); } } - lang: Ruby source: |- require "stigg" stigg = Stigg::Client.new(api_key: "My API Key") page = stigg.v1.customers.list_invoices("id") puts(page) - lang: C# source: |- using System; using Stigg.Client; using Stigg.Client.Models.V1.Customers; StiggClient client = new(); CustomerListInvoicesParams parameters = new() { ID = "id" }; var page = await client.V1.Customers.ListInvoices(parameters); await foreach (var item in page.Paginate()) { Console.WriteLine(item); } - lang: CLI source: |- stigg v1:customers list-invoices \ --api-key 'My API Key' \ --id id components: schemas: InvoiceListResponseDto: type: object properties: data: type: array items: type: object properties: invoiceId: type: string maxLength: 255 description: The billing provider (Received) invoice ID invoiceExternalId: type: string maxLength: 255 description: >- External ID for the invoice: the mapped external ID when one exists, otherwise the invoice ID nullable: true invoiceNumber: type: string maxLength: 255 description: >- The invoice document number (or draft number while the invoice is unissued) nullable: true contractExternalId: type: string maxLength: 255 description: >- External ID of the contract the invoice belongs to: your contract ref when mapped, otherwise the Received contract ID nullable: true customerExternalId: type: string maxLength: 255 description: >- External ID of the customer the invoice belongs to: your customer ref when mapped, otherwise the Received customer ID nullable: true state: type: string enum: - OPEN - CANCELED - PAID description: The invoice status (open, paid, or canceled) issueDate: type: string format: date-time description: The date the invoice was issued nullable: true dueDate: type: string format: date-time description: The date payment is due nullable: true paidDate: type: string format: date-time description: >- The date the invoice was reconciled as paid; present once reconciled nullable: true currency: type: string maxLength: 255 description: The ISO-4217 currency code of the invoice nullable: true subtotal: type: number description: The pre-tax subtotal nullable: true tax: type: number description: The total tax amount nullable: true discount: type: number description: The total discount amount nullable: true total: type: number description: The total amount due nullable: true lineItems: type: array items: type: object properties: description: type: string maxLength: 255 description: Human-readable description of the line item nullable: true quantity: type: number description: Quantity billed on this line nullable: true unitPrice: type: number description: Price per unit for this line nullable: true amount: type: number description: Total amount for this line (unit price × quantity) nullable: true productExternalId: type: string maxLength: 255 description: >- External ID of the product this line item relates to, when one is mapped nullable: true required: - description - quantity - unitPrice - amount - productExternalId title: InvoiceLineItem description: A single line item on an invoice. description: The invoice line items required: - invoiceId - invoiceExternalId - invoiceNumber - contractExternalId - customerExternalId - state - issueDate - dueDate - paidDate - currency - subtotal - tax - discount - total - lineItems title: Invoice description: A customer invoice as reported by the connected billing provider. pagination: type: object properties: next: type: string maxLength: 255 description: >- Cursor for fetching the next page of results, or null if no additional pages exist nullable: true prev: type: string maxLength: 255 description: >- Cursor for fetching the previous page of results, or null if at the beginning nullable: true required: - next - prev description: Pagination metadata including cursors for navigating through results required: - data - pagination title: InvoiceListResponse description: A cursor-paginated list of a customer's invoices BadInputErrorResponseDto: type: object properties: message: type: string code: type: string enum: - BadUserInput - DuplicateIntegrationNotAllowed - EntityIsArchivedError - IntegrityViolation - FreePlanCantHaveCompatiblePackageGroupError - SubscriptionMustHaveSinglePlanError - AddonIsCompatibleWithPlan - AddonIsCompatibleWithGroup - DuplicateAddonProvisionedError - ScheduledMigrationAlreadyExistsError - SubscriptionAlreadyOnLatestPlan - EntityIdDifferentFromRefIdError - UnsupportedFeatureType - UnsupportedVendorIdentifier - UnsupportedSubscriptionScheduleType - InvalidEntitlementResetPeriod - IncompatibleSubscriptionAddon - UnPublishedPackage - MeteringNotAvailableForFeatureType - AuthCustomerMismatch - AuthCustomerReadonly - FetchAllCountriesPricesNotAllowed - MemberInvitationError - PlansCircularDependencyError - NoFeatureEntitlementInSubscription - CheckoutIsNotSupported - UnsupportedParameter - PricingModelNotSupportedByBillingIntegration - BillingIntegrationMissing - BillingIntegrationAlreadyExistsError - InvalidMemberDelete - PackageAlreadyPublished - DraftPlanCantBeArchived - DraftAddonCantBeArchived - PlanWithChildCantBeDeleted - PlanCannotBePublishWhenBasePlanIsDraft - PlanCannotBePublishWhenCompatibleAddonIsDraft - PlanIsUsedAsDefaultStartPlan - PlanIsUsedAsDowngradePlan - InvalidAddressError - InvalidQuantity - BillingPeriodMissingError - DowngradeBillingPeriodNotSupportedError - CustomerAlreadyUsesCouponError - CustomerAlreadyHaveCustomerCoupon - SubscriptionAlreadyCanceledOrExpired - TrialMustBeCancelledImmediately - SubscriptionDoesNotHaveBillingPeriod - InvalidCancellationDate - FailedToImportCustomer - FailedToImportSubscriptions - PackagePricingTypeNotSet - InvalidSubscriptionStatus - InvalidArgumentError - EditAllowedOnDraftPackageOnlyError - ResyncAlreadyInProgress - ArchivedCouponCantBeApplied - ImportAlreadyInProgress - AddonHasToHavePriceError - SelectedBillingModelDoesntMatchImportedItemError - CannotArchiveProductError - CannotUnarchiveProductError - CannotDeleteCustomerError - CannotRemovePaymentMethodFromCustomerError - CannotDeleteFeatureError - CannotArchiveFeatureError - InvalidUpdatePriceUnitAmountError - ExperimentAlreadyRunning - ExperimentStatusError - OperationNotAllowedDuringInProgressExperiment - EntitlementsMustBelongToSamePackage - CanNotUpdateEntitlementsFeatureGroup - MeterMustBeAssociatedToMeteredFeature - CannotEditPackageInNonDraftMode - CannotAddOverrideEntitlementToPlan - MissingEntityIdError - NoProductsAvailable - PromotionCodeNotForCustomer - PromotionCodeNotActive - PromotionCodeMaxRedemptionsReached - PromotionCodeMinimumAmountNotReached - PromotionCodeCustomerNotFirstPurchase - AddonWithDraftCannotBeDeletedError - CannotReportUsageForEntitlementWithMeterError - RecalculateEntitlementsError - ImportSubscriptionsBulkError - InvalidMetadataError - CannotUpsertToPackageThatHasDraft - IntegrationValidationError - AwsMarketplaceIntegrationValidationError - AwsMarketplaceIntegrationError - DataExportIntegrationError - HubspotIntegrationError - DuplicateProductValidationError - AmountTooLarge - CustomerHasNoEmailAddress - MergeEnvironmentValidationError - EntitlementLimitExceededError - EntitlementUsageOutOfRangeError - UsageMeasurementDiffOutOfRangeError - AddonQuantityExceedsLimitError - AddonDependencyMissingError - PackageGroupMinItemsError - CannotUpdateUnitTransformationError - SingleSubscriptionCantBeAutoCancellationTargetError - MultiSubscriptionCantBeAutoCancellationSourceError - ChangingPayingCustomerIsNotSupportedError - RequiredSsoAuthenticationError - InvalidDoggoSignatureError - InvalidReceivedSignatureError - CannotDeleteDefaultIntegration - CannotChangeBillingIntegration - FailedToResolveBillingIntegration - WorkflowTriggerNotFound - DeprecatedEstimateSubscriptionError - FeatureConfigurationExceededLimitError - FeatureNotBelongToFeatureGroupError - FeatureGroupMissingFeaturesError - VersionExceedsMaxValueError - CannotUpdateExpireAtForExpiredCreditGrantError - ExpireAtMustBeLaterThanEffectiveAtError - OfferAlreadyExists - DraftAlreadyExists - CreditGrantAlreadyVoided - CreditGrantCannotBeVoided - InvalidTaxId - ObjectAlreadyBeingUsedByAnotherRequestError - TooManySubscriptionsPerCustomer - TooManyCustomCurrencies - StripeError - SchedulingAtEndOfBillingPeriod - ApiKeyExpired - ApiKeyHasExpiry - OveragePriceNotSupportedOnAddon - OveragePriceRequiresUsageLimit - InvalidCreditOverageBillingModel - CreditOveragePriceCurrencyNotFound - InvoicePreviewNotAvailableForDraftContract nullable: true required: - message - code UnauthenticatedErrorResponseDto: type: object properties: message: type: string code: type: string enum: - Unauthenticated nullable: true required: - message - code ForbiddenErrorResponseDto: type: object properties: message: type: string code: type: string enum: - IdentityForbidden - AccessDeniedError - NoFeatureEntitlementError - GovernanceNotEnabled nullable: true required: - message - code TooManyRequestsErrorResponseDto: type: object properties: message: type: string code: type: string enum: - RateLimitExceeded nullable: true required: - message - code securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-KEY description: Server API Key ````