Invoices
List Invoices
Retrieve a paginated list of invoices with optional filtering and sorting
GET
/
invoices
curl "https://api.alguna.io/invoices?page=1&limit=25" \
-H "Authorization: Bearer YOUR_API_KEY"
curl -G "https://api.alguna.io/invoices" \
-H "Authorization: Bearer YOUR_API_KEY" \
--data-urlencode 'page=1' \
--data-urlencode 'limit=10' \
--data-urlencode 'filters=[{"field":"status","operator":"in","value":"issued,paid"},{"field":"due_date","operator":"gte","value":"2024-01-01T00:00:00Z"}]' \
--data-urlencode 'sort=due_date:desc'
const invoices = await alguna.invoices.list({
page: 1,
limit: 25,
filters: [
{ field: "status", operator: "in", value: "issued,paid" },
{ field: "due_date", operator: "gte", value: "2024-01-01T00:00:00Z" }
],
sort: "due_date:desc"
});
{
"items": [
{
"id": "ZVzWRFnt",
"accountId": "aBsZxlLh",
"currency": "USD",
"description": "Platform subscription",
"billingPeriodStart": "2024-02-01T00:00:00Z",
"billingPeriodEnd": "2024-02-29T23:59:59Z",
"status": "upcoming",
"total": "200.00",
"billingPeriod": "Feb 01, 24 - Feb 29, 24",
"createdAt": "2024-01-24T16:36:52.78883Z",
"updatedAt": "2024-01-26T19:30:37.734294Z"
},
{
"id": "jqsKFrxO",
"accountId": "JXvYcskd",
"currency": "USD",
"description": "Monthly seats",
"billingPeriodStart": "2024-02-01T00:00:00Z",
"billingPeriodEnd": "2024-02-29T23:59:59Z",
"status": "upcoming",
"total": "500.00",
"billingPeriod": "Feb 01, 24 - Feb 29, 24",
"createdAt": "2024-01-24T16:25:48.027798Z",
"updatedAt": "2024-01-26T19:30:38.083477Z"
}]
}
Retrieves a paginated list of all invoices. You can filter and sort the results using query parameters.
Query Parameters
integer
default:"1"
The page number to retrieve (1-indexed).
integer
default:"10"
The number of invoices to return per page. Must be one of:
5, 10, 25, 50, or 100. Values exceeding 100 are capped automatically.string
A JSON-encoded array of filter objects. Each filter object has the following properties:
Show Filter Object
Show Filter Object
string
required
The field to filter on. Supported fields:
| Field | Operators | Description |
|---|---|---|
status | eq, in | Invoice status (e.g. draft, upcoming, issued, paid, void) |
account_id | eq | The account ID associated with the invoice |
subscription_id | eq | The subscription ID associated with the invoice |
autopay | eq | Whether the invoice is set to auto-pay (true or false) |
invoicing_date | eq, gte, lte | The invoicing date (ISO 8601 format) |
issue_date | eq, gte, lte | The issue date (ISO 8601 format) |
due_date | eq, gte, lte | The due date (ISO 8601 format) |
paid_date | eq, gte, lte | The paid date (ISO 8601 format) |
tag_ids | in | Tag IDs associated with the invoice |
string
required
The comparison operator.
| Operator | Description |
|---|---|
eq | Exact match |
in | Matches any value in a comma-separated list |
gte | Greater than or equal to (date fields) |
lte | Less than or equal to (date fields) |
string
required
The value to match against. For the
in operator, use comma-separated values. For date operators, use ISO 8601 format.string
Sort specification in
field:order format. Order is either asc (ascending) or desc (descending).Sortable fields: invoicing_date, issue_date, due_date, paid_date, account_name, status.curl "https://api.alguna.io/invoices?page=1&limit=25" \
-H "Authorization: Bearer YOUR_API_KEY"
curl -G "https://api.alguna.io/invoices" \
-H "Authorization: Bearer YOUR_API_KEY" \
--data-urlencode 'page=1' \
--data-urlencode 'limit=10' \
--data-urlencode 'filters=[{"field":"status","operator":"in","value":"issued,paid"},{"field":"due_date","operator":"gte","value":"2024-01-01T00:00:00Z"}]' \
--data-urlencode 'sort=due_date:desc'
const invoices = await alguna.invoices.list({
page: 1,
limit: 25,
filters: [
{ field: "status", operator: "in", value: "issued,paid" },
{ field: "due_date", operator: "gte", value: "2024-01-01T00:00:00Z" }
],
sort: "due_date:desc"
});
Response
{
"items": [
{
"id": "ZVzWRFnt",
"accountId": "aBsZxlLh",
"currency": "USD",
"description": "Platform subscription",
"billingPeriodStart": "2024-02-01T00:00:00Z",
"billingPeriodEnd": "2024-02-29T23:59:59Z",
"status": "upcoming",
"total": "200.00",
"billingPeriod": "Feb 01, 24 - Feb 29, 24",
"createdAt": "2024-01-24T16:36:52.78883Z",
"updatedAt": "2024-01-26T19:30:37.734294Z"
},
{
"id": "jqsKFrxO",
"accountId": "JXvYcskd",
"currency": "USD",
"description": "Monthly seats",
"billingPeriodStart": "2024-02-01T00:00:00Z",
"billingPeriodEnd": "2024-02-29T23:59:59Z",
"status": "upcoming",
"total": "500.00",
"billingPeriod": "Feb 01, 24 - Feb 29, 24",
"createdAt": "2024-01-24T16:25:48.027798Z",
"updatedAt": "2024-01-26T19:30:38.083477Z"
}]
}
array
List of invoice objects.
Show Invoice Object
Show Invoice Object
string
The Alguna ID of the invoice.
string
The Alguna ID of the account associated with the invoice.
string
The ISO 4217 currency in which the invoice is billed.
string
The description or memo for the invoice.
string
The start date of the billing period for the invoice (RFC 3339 timestamp).
string
The end date of the billing period for the invoice (RFC 3339 timestamp).
string
The status of the invoice. For more info on invoice statuses see the invoice status guide.
string
The total amount of the invoice as a decimal string e.g., “200.00”.
string
The formatted billing period for the invoice.
datetime
The date and time at which the invoice was created.
datetime
The date and time at which the invoice was last updated.
integer
Total number of pages available based on the current limit.
integer
The number of items per page used for this request.
⌘I
curl "https://api.alguna.io/invoices?page=1&limit=25" \
-H "Authorization: Bearer YOUR_API_KEY"
curl -G "https://api.alguna.io/invoices" \
-H "Authorization: Bearer YOUR_API_KEY" \
--data-urlencode 'page=1' \
--data-urlencode 'limit=10' \
--data-urlencode 'filters=[{"field":"status","operator":"in","value":"issued,paid"},{"field":"due_date","operator":"gte","value":"2024-01-01T00:00:00Z"}]' \
--data-urlencode 'sort=due_date:desc'
const invoices = await alguna.invoices.list({
page: 1,
limit: 25,
filters: [
{ field: "status", operator: "in", value: "issued,paid" },
{ field: "due_date", operator: "gte", value: "2024-01-01T00:00:00Z" }
],
sort: "due_date:desc"
});
{
"items": [
{
"id": "ZVzWRFnt",
"accountId": "aBsZxlLh",
"currency": "USD",
"description": "Platform subscription",
"billingPeriodStart": "2024-02-01T00:00:00Z",
"billingPeriodEnd": "2024-02-29T23:59:59Z",
"status": "upcoming",
"total": "200.00",
"billingPeriod": "Feb 01, 24 - Feb 29, 24",
"createdAt": "2024-01-24T16:36:52.78883Z",
"updatedAt": "2024-01-26T19:30:37.734294Z"
},
{
"id": "jqsKFrxO",
"accountId": "JXvYcskd",
"currency": "USD",
"description": "Monthly seats",
"billingPeriodStart": "2024-02-01T00:00:00Z",
"billingPeriodEnd": "2024-02-29T23:59:59Z",
"status": "upcoming",
"total": "500.00",
"billingPeriod": "Feb 01, 24 - Feb 29, 24",
"createdAt": "2024-01-24T16:25:48.027798Z",
"updatedAt": "2024-01-26T19:30:38.083477Z"
}]
}