---
title: "Get subscription invoices"
method: GET
path: "/subscriptions/invoices"
tags: ["Subscriptions"]
---

# Get subscription invoices

`GET /subscriptions/invoices`

## Request

- Base URL: `https://api.smokeball.com`
- URL: `https://api.smokeball.com/subscriptions/invoices`
- Auth: API key in header `x-api-key` and API key in header `Authorization`

Retrieves invoices for the account.
            
Invoices are returned sorted by creation date with the most recent invoices appearing first.

## Query parameters

- `Offset` integer
- `Limit` integer
- `From` string, date-time
- `To` string, date-time
- `SubscriptionId` string

## Response `200`

When request is successful. Returns a paged collection of 'SubscriptionInvoice' objects.

- SubscriptionInvoicePagedCollection
  - `id` string, nullable
  - `href` string, nullable
  - `relation` string, nullable
  - `method` string, nullable
  - `self` Link
    - `id` string, nullable
    - `href` string, nullable
    - `relation` string, nullable
    - `method` string, nullable
  - `value` SubscriptionInvoice[], nullable
    - `id` string, nullable: The unique identifier of the invoice.
    - `number` string, nullable: The human-readable invoice number (e.g. ABC-001).
    - `status` string: The invoice status. Possible values: Draft, Open, Paid, Unpaid, Void, Closed
    - `description` string, nullable: The invoice description.
    - `total` integer: The total amount for the invoice.
    - `subTotal` integer: The payment subtotal amount.
    - `tax` integer: The payment tax amount.
    - `preTaxCredit` integer: Total pre-tax credits applied to this payment.
    - `lineItems` SubscriptionInvoiceLineItem[], nullable: The line items associated to the invoice.
      - `product` Link
        - `id` string, nullable
        - `href` string, nullable
        - `relation` string, nullable
        - `method` string, nullable
      - `description` string, nullable: Description of this line item.
      - `interval` string: Billing interval associated to this line item. Possible values: None, Daily, Weekly, Monthly, Yearly.
      - `amount` integer: The amount charged for this line item.
      - `tax` integer: The tax amount in this line item.
      - `preTaxCredit` integer: Any credit amount on this line item.
      - `quantity` integer, nullable: The number of users for this line item.
      - `periodStart` string, date-time, nullable: The start of the billing period for this line item.
      - `periodEnd` string, date-time, nullable: The end of the billing period for this line item.
    - `createdDate` string, date-time: The created date of the invoice.
  - `offset` integer, nullable
  - `limit` integer, nullable
  - `size` integer
  - `first` Link
    - `id` string, nullable
    - `href` string, nullable
    - `relation` string, nullable
    - `method` string, nullable
  - `previous` Link
    - `id` string, nullable
    - `href` string, nullable
    - `relation` string, nullable
    - `method` string, nullable
  - `next` Link
    - `id` string, nullable
    - `href` string, nullable
    - `relation` string, nullable
    - `method` string, nullable
  - `last` Link
    - `id` string, nullable
    - `href` string, nullable
    - `relation` string, nullable
    - `method` string, nullable

## Other responses

- `404`: When a subscription id filter is supplied and that subscription does not exist.
- `500`: When an error occurs while retrieving the subscription invoices.

## Changes

- **2026-10-28** `2fe552c5d11d`: 2 info
  - added the optional property `value/items/lineItems/items/periodEnd` to the response with the `200` status
  - added the optional property `value/items/lineItems/items/periodStart` to the response with the `200` status

[Operation history](https://skmtc.dev/smokeball/apis/smokeball-api/changes/subscriptions/invoices/get.md)

---

[API](https://skmtc.dev/smokeball/apis/smokeball-api.md) - [All operations](https://skmtc.dev/smokeball/apis/smokeball-api/llms.txt) - [OpenAPI document](https://skmtc.dev/smokeball/apis/smokeball-api/revisions/6e350cf667d4?raw)