> ## Documentation Index > Fetch the complete documentation index at: https://studio.assembly.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # List invoices > Returns a paginated list of invoices for the portal. Supports filtering by client, company, and subscription. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/invoices openapi: 3.0.0 info: contact: {} title: Assembly API version: 0.0.1 servers: - url: https://api.assembly.com security: [] paths: /v1/invoices: get: tags: - Invoices summary: List invoices description: |- Returns a paginated list of invoices for the portal. Supports filtering by client, company, and subscription. operationId: list-invoices parameters: - description: Filter by client ID in: query name: clientId schema: type: string - description: Filter by company ID (mutually exclusive with clientId) in: query name: companyId schema: type: string - description: Include company-level invoices in the results in: query name: includeCompanyInvoices schema: type: boolean - description: Filter by subscription ID in: query name: subscriptionId schema: type: string - description: Maximum number of records to return in: query name: limit schema: type: integer - description: Pagination cursor returned by a previous request in: query name: nextToken schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/invoice.GetInvoiceResponse' description: OK '400': content: application/json: schema: $ref: '#/components/schemas/dispatcher.Error' description: Invalid query or pagination parameters '401': content: application/json: schema: $ref: '#/components/schemas/dispatcher.Error' description: Missing or invalid API key '500': content: application/json: schema: $ref: '#/components/schemas/dispatcher.Error' description: Unexpected server error security: - APIKeyHeader: [] components: schemas: invoice.GetInvoiceResponse: properties: data: description: Invoices is the page of invoices matching the query. items: $ref: '#/components/schemas/invoice.Invoice' nullable: true type: array nextToken: description: base64 encoded JSON representing a NextToken type: string type: object dispatcher.Error: properties: code: type: string data: {} message: type: string type: object invoice.Invoice: properties: address: allOf: - $ref: '#/components/schemas/invoice.PaymentsAddress' description: Address stores the selected billing address from custom fields amountPaid: description: >- AmountPaid is the amount paid so far in the smallest currency unit (e.g. cents). type: integer attachmentKeys: description: AttachmentKeys are the storage keys of the invoice attachments. items: type: string type: array attachmentUrls: description: >- AttachmentUrls are presigned download URLs for the invoice attachments. items: type: string type: array billingReason: description: >- BillingReason describes why the invoice was created (e.g. manual, subscription cycle). example: manual type: string clientId: description: ClientID is the ID of the client the invoice is billed to. example: client_a1b2c3d4e5f6 type: string collectionMethod: description: CollectionMethod controls how the invoice is collected. enum: - sendInvoice - chargeAutomatically - paymentLink example: sendInvoice type: string companyId: description: CompanyID is the ID of the company the invoice is billed to. example: company_a1b2c3d4e5f6 type: string createdAt: type: string creatorId: type: string currency: description: >- Currency is the ISO 4217 currency code the invoice is denominated in. example: usd type: string data: type: string daysUntilDue: description: >- DaysUntilDue is the number of days from issuance until the invoice is due. example: 14 type: integer dueDate: description: DueDate is the RFC 3339 timestamp by which the invoice must be paid. example: '2024-03-01T00:00:00Z' format: date-time nullable: true type: string entityType: description: ObjectType is the internal entity type discriminator. type: string fileKey: description: FileKey is the storage key of the invoice PDF. type: string fileUrl: description: FileUrl is the presigned download URL for the invoice PDF. type: string id: type: string identityId: type: string interval: description: >- Property copied from subscription when creating invoice We need this value when we have to show line items descriptions (Format "Item (at US$621.00 / month)") on invoice details for subscriptions invoices. We can fetch this directly from subscription at that time, but we delete subscriptions when we delete the recipient (client/company). For deleted recipients we still show invoices which were paid in the past. So we need to store this value here to show line items descriptions for invoices even if subscriptions are deleted. type: string invoiceCreationStatus: enum: - ephemeral - pending - created type: string latestRefundStatus: description: >- LatestRefundStatus is the status of the most recent refund issued against the invoice, when any. enum: - pending - succeeded - failed example: succeeded type: string lineItems: description: LineItems are the priced line items that make up the invoice. items: $ref: '#/components/schemas/line_item.LineItem' type: array memo: description: Memo is an optional note shown to the recipient on the invoice. example: Thanks for your business type: string number: description: Number is the human-readable invoice number. example: INV-0001 type: string object: type: string origin: allOf: - $ref: '#/components/schemas/invoice.Origin' description: Origin indicates how the invoice was created. enum: - internal - payment_link - product_store example: internal paidManually: type: boolean payment: description: represents the successful payments only items: $ref: '#/components/schemas/payment.Payment' type: array paymentMethodPreferences: description: >- field is only used for platform api and should not be used anywhere else on FE/BE items: $ref: '#/components/schemas/payment.PaymentMethodPreference' type: array paymentPreferences: allOf: - $ref: '#/components/schemas/payment.PaymentPreferences' description: fields is used for BE/FE only paymentSourceId: type: string paymentSuccessDate: description: >- PaymentSuccessDate is the RFC 3339 timestamp at which payment succeeded; absent until paid. example: '2024-02-20T14:05:00Z' format: date-time type: string portalId: description: PortalID is the ID of the portal the invoice belongs to. type: string previousAttributes: additionalProperties: true type: object quickBooksData: $ref: '#/components/schemas/invoice.QuickBooksData' receiptKey: type: string receiptNumber: description: >- ReceiptNumber is the human-readable receipt number, set once the invoice is paid. example: REC-0001 type: string receiptUrl: description: ReceiptUrl is the presigned download URL for the receipt PDF. type: string recipientId: description: 'Deprecated: use ClientID and CompanyID instead' example: client_a1b2c3d4e5f6 type: string ref: type: string sentDate: description: >- SentDate is the RFC 3339 timestamp at which the invoice was sent to the recipient. example: '2024-02-15T09:00:00Z' format: date-time nullable: true type: string sourcePaymentLinkId: description: >- SourcePaymentLinkId is the ID of the payment link that produced this invoice, when applicable. example: plink_a1b2c3d4e5f6 type: string status: description: Status is the current lifecycle state of the invoice. enum: - draft - open - void - paid - processing example: open type: string subscription: allOf: - $ref: '#/components/schemas/subscription.Subscription' description: >- Subscription is populated from search results when subscriptionId is present (not persisted) subscriptionId: description: >- SubscriptionID is the ID of the subscription that generated this invoice, when applicable. example: sub_a1b2c3d4e5f6 type: string taxAmount: description: >- TaxAmount is the computed tax in the smallest currency unit (e.g. cents). example: 1275 type: integer taxPercentage: description: >- TaxPercentage is the tax rate applied to the invoice, expressed as a percentage. example: 8.5 nullable: true type: number templateId: description: >- TemplateID is the ID of the invoice template the invoice was created from, when applicable. example: itmpl_a1b2c3d4e5f6 type: string total: description: >- Total is the invoice total in the smallest currency unit (e.g. cents). example: 15000 type: integer updatedAt: type: string type: object invoice.PaymentsAddress: properties: addressLine1: description: AddressLine1 is the first line of the billing street address. example: 548 Market St type: string addressLine2: description: AddressLine2 is the second line of the billing street address. example: Suite 100 type: string city: description: City is the billing city. example: San Francisco type: string country: description: Country is the billing country. example: United States type: string fullAddress: description: FullAddress is the formatted, single-line billing address. example: 548 Market St, San Francisco, CA 94105 type: string postalCode: description: PostalCode is the billing postal or ZIP code. example: '94105' type: string region: description: Region is the billing state, province, or region. example: California type: string type: object line_item.LineItem: properties: amount: description: >- Amount is the per-unit charge in the smallest currency unit (e.g. cents) for a one-off line item. Required, together with description, when priceId is absent. example: 5000 type: integer description: description: >- Description is the human-readable description of a one-off line item. Required, together with amount, when priceId is absent. example: Onboarding setup fee type: string id: type: string priceId: description: >- PriceId is the ID of the price this line item bills for. Either priceId or amount with description must be provided. example: price_1a2b3c type: string priceInterval: description: >- PriceInterval is the recurring interval of the referenced price, when the line item bills a recurring price. example: month type: string productId: description: >- ProductId is the ID of the product this line item bills for; absent for one-off charges. example: prod_1a2b3c type: string quantity: description: Quantity is the number of units billed for this line item. Required. example: 2 maximum: 1000000 minimum: 1 type: number type: type: string type: object invoice.Origin: enum: - internal - payment_link - product_store type: string x-enum-varnames: - OriginInternal - OriginPaymentLink - OriginProductStore payment.Payment: properties: amount: description: >- Amount is the payment amount in the smallest currency unit (e.g. cents). example: 10000 type: integer brand: description: Brand is the card brand or bank descriptor of the payment method. example: Visa type: string chargedAt: description: >- ChargedAt is the RFC 3339 timestamp at which the payment was charged. example: '2024-02-20T14:05:00Z' format: date-time type: string createdAt: type: string creatorId: type: string data: type: string declineCode: description: >- DeclineCode is the lower-camel-cased decline reason returned when a payment fails. example: insufficientFunds type: string entityType: description: ObjectType is the internal entity type discriminator for the record. example: PAYMENT type: string fee: allOf: - $ref: '#/components/schemas/payment.Fee' description: Fee is the full transaction-fee breakdown for the payment. feeAmount: allOf: - $ref: '#/components/schemas/payment.FeeAmountExternal' description: >- FeeAmount is the client-facing split of the transaction fee between platform and client. nullable: true id: type: string identityId: type: string intentId: description: >- IntentId is the Stripe payment intent identifier associated with the payment. example: pi_3OabcdEFghIJklmn type: string invoiceId: description: InvoiceId is the ID of the invoice this payment was made against. example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string last4Digits: description: >- Last4Digits is the last four digits of the card or bank account used. example: '4242' type: string message: description: >- Message is a human-readable status or decline message for the payment. example: The card has insufficient funds to complete the purchase. type: string object: type: string paymentMethod: description: PaymentMethod is the type of payment method used for the payment. enum: - bankAccount - creditCard example: creditCard type: string portalId: description: PortalId is the ID of the portal that owns the payment. example: a1b2c3d4 type: string previousAttributes: additionalProperties: true type: object ref: type: string status: description: Status is the current state of the payment. enum: - pending - processing - succeeded - failed - refunded example: succeeded type: string stripeChargeId: description: StripeChargeId is the Stripe charge identifier backing this payment. example: ch_3OabcdEFghIJklmn type: string updatedAt: type: string type: object payment.PaymentMethodPreference: properties: feePaidByClient: description: >- FeesPaidByClient reports whether the transaction fee for this method is charged to the client. example: true type: boolean type: description: Type is the payment method type this preference applies to. enum: - bankAccount - creditCard example: creditCard type: string type: object payment.PaymentPreferences: properties: absorbTransactionFee: description: >- AbsorbTransactionFee lists the payment method types for which the internal user absorbs the transaction fee. items: enum: - bankAccount - creditCard type: string type: array paymentMethodTypes: description: >- PaymentMethodTypes lists the payment method types accepted for the portal. items: enum: - bankAccount - creditCard type: string type: array type: object invoice.QuickBooksData: properties: invoiceId: type: string paymentId: type: string type: object subscription.Subscription: properties: additionalFields: additionalProperties: true description: >- StripeObject would hold field from stripe's subscription or subscription schedule object type: object cancelledAt: description: >- CancelledAt is the RFC 3339 timestamp at which the subscription was cancelled; absent while active. example: '2024-02-20T14:05:00Z' format: date-time type: string clientId: description: ClientID is the ID of the client user the subscription bills. example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 type: string collectionMethod: description: >- CollectionMethod determines how the subscription's invoices are collected. enum: - sendInvoice - chargeAutomatically example: sendInvoice type: string companyId: description: CompanyID is the ID of the company the subscription bills. example: f0e1d2c3-b4a5-6789-0123-456789abcdef type: string createdAt: type: string creatorId: type: string currency: description: >- Currency is the ISO 4217 currency code the subscription is billed in. example: usd type: string data: type: string daysUntilDue: description: >- DaysUntilDue is the number of days a recipient has to pay an invoice when collected by sending an invoice. example: 30 type: integer fields: $ref: '#/components/schemas/billing.SubscriptionFields' filteredListIndexPkey: description: '{client_id}/INBOX_NOTIFICATION' type: string forcePaused: description: >- ForcePaused indicates the subscription was paused because the workspace plan lapsed. example: false type: boolean id: type: string identityId: type: string interval: allOf: - $ref: '#/components/schemas/billingutils.BillingPeriodType' description: Interval is the billing period the subscription recurs on. example: monthly intervalCount: description: IntervalCount is the number of intervals between each billing cycle. example: 1 type: integer lineItems: description: LineItems are the products and ad-hoc charges billed on each cycle. items: $ref: '#/components/schemas/line_item.LineItem' type: array memo: description: >- Memo is an optional note shown to the recipient on generated invoices. example: Monthly retainer type: string object: type: string paymentMethodPreferences: description: >- field is only used for platform api and should not be used anywhere else on FE/BE items: $ref: '#/components/schemas/payment.PaymentMethodPreference' type: array paymentSourceId: description: >- PaymentSourceId is the ID of the saved payment source charged for automatically-collected subscriptions. example: card_1a2b3c type: string previousAttributes: additionalProperties: true type: object recipientId: description: >- RecipientID is the ID of the client or company the subscription bills. Deprecated: use ClientID and CompanyID instead example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 type: string ref: type: string status: description: >- Status is the current lifecycle status of the subscription, mirrored from Stripe. example: active type: string taxPercentage: description: >- TaxPercentage is the tax rate applied to the subscription, as a percentage. example: 8.25 nullable: true type: number templateId: description: >- TemplateID is the ID of the subscription template the subscription was created from, when applicable. example: a7c3e9f1-2b4d-4e6a-8c0f-1d2e3f4a5b6c type: string updatedAt: type: string type: object payment.Fee: properties: absorbedAmount: description: >- AbsorbedAmount is what the internal user paid, in the smallest currency unit; equals TotalAmount when IsFeeAbsorbed is true. example: 0 type: integer chargedAmount: description: >- ChargedAmount is what the client paid, in the smallest currency unit; 0 when IsFeeAbsorbed is true. example: 150 type: integer isFeeAbsorbed: description: >- IsFeeAbsorbed reports whether the internal user absorbed the transaction fee instead of passing it to the client. example: false type: boolean items: description: >- Items is the list of individual fee components that make up the total. items: $ref: '#/components/schemas/payment.FeeItem' type: array totalAmount: description: >- TotalAmount is the total transaction fee (internal user plus client), in the smallest currency unit. example: 150 type: integer type: object payment.FeeAmountExternal: properties: paidByClient: description: >- PaidByClient is the portion of the transaction fee charged to the client, in the smallest currency unit (e.g. cents). example: 150 type: integer paidByPlatform: description: >- PaidByPlatform is the portion of the transaction fee absorbed by the internal user, in the smallest currency unit (e.g. cents). example: 0 type: integer type: object billing.SubscriptionFields: properties: absorbTransactionFees: type: boolean address: allOf: - $ref: '#/components/schemas/invoice.PaymentsAddress' description: Address stores the selected billing address from custom fields allowPaymentViaACH: type: boolean allowPaymentViaCC: type: boolean attachment: type: string cancelledAt: type: string clientUserId: type: string collectionMethod: type: string companyId: type: string currency: type: string daysUntilDue: type: integer forcePaused: description: >- ForcePaused indicates this subscription was paused due to workspace plan lapse type: boolean interval: type: string lineItems: items: $ref: '#/components/schemas/fields_models.LineItem' type: array memo: type: string paymentPreferences: allOf: - $ref: '#/components/schemas/payment.PaymentPreferences' description: new property to hold payment preferenced for the subscription prorate: type: boolean purchaseFields: allOf: - $ref: '#/components/schemas/billing.PurchaseFields' description: >- Used to store a confirmation token to automatically pay the first invoice of a subscription created from a purchase reactivatedBy: description: not set by the front-end type: string resetBillingCycle: type: boolean scheduleEndDate: type: integer scheduleIterations: type: integer scheduleStartDate: type: integer taxPercentage: type: number type: object billingutils.BillingPeriodType: enum: - day - week - month - quarterly - biannually - year - semiannually type: string x-enum-varnames: - BillingPeriodTypeDay - BillingPeriodTypeWeek - BillingPeriodTypeMonth - BillingPeriodTypeQuarter - BillingPeriodTypeBiannual - BillingPeriodTypeYear - BillingPeriodTypeSemiAnnually payment.FeeItem: properties: amount: description: >- Amount is the fee component value in the smallest currency unit (e.g. cents). example: 150 type: integer type: description: Type identifies which fee component this line item represents. enum: - achFixed - achPercentage - ccFixed - ccPercentage - ccInternationalPercentage - ccConversionPercentage - recurringPercentage - storePercentage - invoicePercentage - achThresholdExceededPercentage example: ccPercentage type: string type: object fields_models.LineItem: properties: description: type: string id: type: string priceId: type: string productId: type: string quantity: type: number rate: type: number type: object billing.PurchaseFields: properties: origin: $ref: '#/components/schemas/invoice.Origin' type: object securitySchemes: APIKeyHeader: in: header name: X-API-KEY type: apiKey ````