> ## Documentation Index > Fetch the complete documentation index at: https://docs.salesbricks.com/llms.txt > Use this file to discover all available pages before exploring further. # List all subscription invoices > Returns a paginated list of invoices associated with the given subscription. Use this to show invoice history and billing status per subscription, display a timeline of past/current invoices, and let users download or inspect previous and current charges. ## OpenAPI ````yaml https://api.salesbricks.com/api/v2/openapi.yaml get /subscriptions/{subscription_id}/invoices openapi: 3.0.3 info: title: Salesbricks REST API version: 2.0.0 description: API reference for external integrations servers: - url: https://api.salesbricks.com/api/v2 description: Production - url: https://api.staging.salesbricks.com/api/v2 description: Staging security: - ApiKeyAuth: [] tags: - name: Subscriptions description: >- Operations related to subscription management, including creation, updates, and retrieving subscription details. Subscriptions can be upgraded to add / remove add-ons by using the POST /subscriptions/{subscription_id}/upgrade endpoint and can be recasted for replacing the current agreement using the POST /subscriptions/{subscription_id}/recast endpoint - name: Subscription Milestones description: >- Operations for listing and completing milestone bricks — bricks billed when the work they cover is delivered rather than on the subscription's schedule. Completing one either raises a standalone invoice immediately or bills on the subscription's next scheduled invoice. - name: Customers description: >- Operations related to customer management, including creation, updates, and managing customer person objects. - name: Invoices description: Operations related to subscription's invoicing details. - name: Plans description: >- Operations related to listing and getting plan details including bricks in the plan. - name: Payment Methods description: Operations related to subscription's payment method. paths: /subscriptions/{subscription_id}/invoices: get: tags: - Invoices summary: List all subscription invoices description: >- Returns a paginated list of invoices associated with the given subscription. Use this to show invoice history and billing status per subscription, display a timeline of past/current invoices, and let users download or inspect previous and current charges. operationId: listSubscriptionInvoices parameters: - name: limit required: false in: query description: Number of results to return per page. schema: type: integer - name: offset required: false in: query description: The initial index from which to return the results. schema: type: integer - in: query name: ordering schema: type: string enum: - '-amount' - '-created_at' - '-due_at' - amount - created_at - due_at description: Order results by field (prefix with '-' for descending order) - in: query name: scope schema: type: string enum: - all - current - due - past description: >- Filter invoices: `past` / `current` by billing period (`starts_at` vs today); `due` by invoice status (unpaid: outstanding, due, past due, partially paid, unpaid); `all` for no extra filter. - in: path name: subscription_id schema: type: string pattern: ^([a-zA-Z\d\-]+)$ required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedInvoiceList' description: '' components: schemas: PaginatedInvoiceList: type: object required: - count - results properties: count: type: integer example: 123 next: type: string nullable: true format: uri example: http://api.example.org/accounts/?offset=400&limit=100 previous: type: string nullable: true format: uri example: http://api.example.org/accounts/?offset=200&limit=100 results: type: array items: $ref: '#/components/schemas/Invoice' Invoice: type: object properties: invoice_id: type: string format: uuid description: >- Unique identifier for the invoice. If the id is null, this is an estimate subscription_id: type: string format: uuid description: >- ID of the subscription this invoice belongs to. Null for standalone (one-off) invoices. customer_id: type: string format: uuid description: >- ID of the end customer this invoice is for — the company that consumes the subscription. Never collect or charge payment methods against this id: on a partner-billed invoice the paying party is a different company, and `billed_company_id` is always the id to collect against. billed_company_id: type: string format: uuid description: >- ID of the company actually billed for this invoice — the party whose Stripe customer `POST /invoices/{invoice_id}/pay` charges. Equal to `customer_id` unless the invoice is partner-billed, in which case it is the partner's company. Collect and list payment methods against this id, never `customer_id`. Always present and never null, including on the renewal estimate returned by `GET /subscriptions/{subscription_id}/invoices/next`, which resolves the company its renewal would bill. customer_name: type: string description: Name of the customer who will pay this invoice invoice_number: type: string description: >- Short form identifier for the invoice. If the invoice_number is null, this is an estimate time_zone: type: string description: Invoice timezone due_at: type: string format: date-time description: The date on which this invoice is expected to be paid by. bill_at: type: string format: date-time description: >- The date on which this invoice will be issued and potentially charged. issued_at: type: string format: date-time description: The date on which this invoice was issued. status: type: string description: > Current status of the invoice. One of: - `MUTED` — Invoice will not be sent. Muted invoices come from migration cut-overs or from muting invoices in the product settings. - `SCHEDULED` — Scheduled to be issued on a future date. - `OUTSTANDING` — Issued and awaiting payment. - `DUE` — Payment is due. - `PAST_DUE` — Payment is past its due date. - `PAID` — Fully paid. - `PARTIALLY_PAID` — Partially paid, with a remaining balance. - `ADJUSTED` — Adjusted after issuance. - `CREDITED` — Settled by applying credit. - `UNPAID` — Unpaid. - `PAUSED` — Collection is paused. - `VOIDED` — Voided and no longer collectible. fully_paid_at: type: string format: date-time description: The date on which this invoice was fully paid. grand_total: type: integer description: >- Total amount due for this invoice. Invoices that have not been generated yet (e.g. `SCHEDULED`) report the total expected at the time they were created. That figure does NOT include usage metered since — a usage invoice whose meters have not been priced reports 0. Pass `?calculate_expected_usage=true` to re-price against the order and include estimated usage instead; it is slower, so it is off by default on list endpoints. remaining_amount: type: integer description: Remaining amount for this invoice. currency: type: string description: The currency in which the invoice is denominated (e.g., USD, EUR). is_renewal_estimate: type: boolean description: >- This is an estimate for a renewal that has not yet closed, but is expected to. payment_url: type: string format: uri nullable: true description: >- Link to the page where your customer pays this invoice online, the same link the invoice PDF carries. Safe to send to your customer: it needs no token and does not expire. Null when you have no Stripe account that can take payments connected, when the invoice has not been issued yet (`SCHEDULED` or `DRAFT`), and on a renewal estimate. Not to be confused with `POST /invoices/{invoice_id}/pay`, which charges a saved payment method directly. payments: type: array items: $ref: '#/components/schemas/Payment' description: All payments made against this invoice, newest first. attachments: type: array items: {} description: >- Current attachments for this invoice as a flat array. Each item includes 'target' field indicating invoice or subscription level. Sorted by unified order. line_items: type: array items: $ref: '#/components/schemas/InvoiceLineItemOutput' description: Line item breakdown for this invoice metadata: description: Optional metadata stored against the invoice. purchase_order: allOf: - $ref: '#/components/schemas/PurchaseOrderOutput' nullable: true description: >- Purchase order shown on this invoice: the invoice's own purchase order when it has one, otherwise the subscription's. Matches the PO printed on the invoice PDF. Null when neither carries one. required: - bill_at - billed_company_id - currency - customer_id - due_at - fully_paid_at - grand_total - invoice_id - invoice_number - is_renewal_estimate - issued_at - payment_url - remaining_amount - status - subscription_id Payment: type: object properties: payment_id: type: string format: uuid readOnly: true description: Unique identifier for the payment invoice_number: type: string nullable: true readOnly: true description: >- The invoice number this payment was made against, snapshotted from the invoice version current when the payment was recorded — it does not change when the invoice is later regenerated, so it may differ from the invoice's top-level `invoice_number`. Falls back to the invoice's current number when no version is linked. Join payments to invoices by ID, not by number. invoice_version_id: type: string format: uuid readOnly: true nullable: true description: >- Identifier of the invoice version this payment was made against — the version current when the payment was recorded. Null only when the invoice has no versions (it was never generated). paid_amount: type: integer readOnly: true nullable: true description: The amount paid paid_at: type: string format: date-time readOnly: true nullable: true description: the date at which this payment was paid currency: type: string readOnly: true description: The currency in which the payment is denominated (e.g., USD, EUR) error: type: string readOnly: true nullable: true description: Any errors that occured during this payment processing required: - currency - error - invoice_number - invoice_version_id - paid_amount - paid_at - payment_id InvoiceLineItemOutput: type: object properties: brick_name: type: string description: Name of the brick brick_id: type: string nullable: true description: Unique identifier of the brick brick_code: type: string nullable: true description: >- The internal SKU code you set on the brick. Unlike `brick_id` it stays the same across environments and when a brick is recreated, so use it to map bricks to your own features. Null when the brick has no code. quantity: oneOf: - type: integer - type: number format: double description: Quantity of units. Fractional quantities are returned as a decimal readOnly: true tax: type: integer description: Tax amount in minor currency units grand_total: type: integer description: Grand total in minor currency units starts_at: type: string format: date-time nullable: true description: Start of the period this line item covers ends_at: type: string format: date-time nullable: true description: End of the period this line item covers required: - brick_code - brick_id - brick_name - ends_at - grand_total - quantity - starts_at - tax PurchaseOrderOutput: type: object description: A purchase order provided by the buyer. properties: code: type: string nullable: true description: Internal identifier of the Purchase Order provided by Buyer required: - code securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-SALESBRICKS-KEY description: API key for authentication ```` ## Related topics - [List all customer invoices](/api-reference/invoices/list-all-customer-invoices.md) - [List all subscription milestones](/api-reference/subscription-milestones/list-all-subscription-milestones.md) - [List all invoice versions](/api-reference/invoice-versions/list-all-invoice-versions.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.