> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kelviq.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List invoices
> Returns a paginated list of invoices for the authenticated organization, newest first. Optionally filter by subscription or customer.
Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.
## OpenAPI
````yaml /api-reference/openapi.json get /invoices/
openapi: 3.0.0
info:
title: kelviq API
version: 1.0.0
description: >-
API for interacting with kelviq services, derived from Python SDK
documentation.
servers:
- url: https://sandboxapi.kelviq.com/api/v1
description: Sandbox — Test payments
- url: https://api.kelviq.com/api/v1
description: Production — Live payments
security:
- bearerAuth: []
tags:
- name: Products
description: Catalog products.
- name: Product Settings
description: Per-product settings (currency, VPN/Tor/proxy, product URL).
- name: Product Files
description: Product images and downloadable assets.
- name: Features
description: Catalog features that can be granted as plan entitlements.
- name: Plans
description: Catalog plans (CRUD, publish, versions, prices).
- name: Plan Entitlements
description: Feature entitlements attached to a plan.
- name: Plan Files
description: Files attached to plans, and signed download links.
- name: Media
description: Generate presigned S3 upload URLs for product/plan images and files.
- name: Partner
description: Partner integration APIs (organization provisioning, lookup).
- name: Charges
description: >-
One-time payments charged immediately against a customer's default payment
method.
- name: Refunds
description: Full and partial refunds for paid orders.
- name: Transactions
description: >-
Charges, refunds, disputes, and other financial movements for the
authenticated organization.
- name: Payment Methods
description: Saved customer payment methods (cards, etc.).
- name: Orders
description: Completed and resolved orders for the authenticated organization.
- name: Order Events
description: Timeline events for a specific order.
- name: Invoices
description: Invoices generated for orders and subscription billing cycles.
- name: Webhooks
description: Delivery logs for webhook events sent to your configured endpoints.
- name: Checkout Sessions
description: Merchant-side view of checkout sessions created by customers.
- name: Checkout Session Events
description: Timeline events for a specific checkout session.
paths:
/invoices/:
get:
tags:
- Invoices
summary: List invoices
description: >-
Returns a paginated list of invoices for the authenticated organization,
newest first. Optionally filter by subscription or customer.
operationId: listInvoices
parameters:
- name: subscription_id
in: query
required: false
description: Filter by the internal Kelviq subscription ID.
schema:
type: string
format: uuid
- name: customer_id
in: query
required: false
description: Filter by the client-defined unique identifier of the customer.
schema:
type: string
- name: page_size
in: query
required: false
description: Number of results per page. Defaults to 10, maximum 100.
schema:
type: integer
minimum: 1
maximum: 100
- name: page
in: query
required: false
description: Page number to return.
schema:
type: integer
minimum: 1
responses:
'200':
description: A paginated list of invoices.
content:
application/json:
schema:
$ref: '#/components/schemas/InvoiceListResponse'
example:
count: 1
next: null
previous: null
results:
- id: INV-20260801101420-Q7M2P
customer:
customerId: geo-jacob
name: Geo Jacob
email: geojacob@example.com
product:
id: df398021-477b-4e67-972d-c763a2f2ba7b
name: ParityDeals
status: PAID
paidAt: '2026-08-01T10:14:22Z'
amountSubtotal: '40.00'
amountDiscount: '0.00'
amountTax: '0.00'
amountTotal: '40.00'
currency: USD
amountSubtotalUnits: 4000
amountDiscountUnits: 0
amountTaxUnits: 0
amountTotalUnits: 4000
currencySymbol: $
billingAddress:
line1: null
line2: null
city: null
state: null
postalCode: '680121'
country: IN
plan:
name: Premium
identifier: premium1
billingType: SUBSCRIPTION
license: []
subscription:
id: a2951973-aca5-408d-bd9c-1d86827ed463
status: active
amount: '40.00'
currency: usd
interval: month
currencySymbol: $
nextInvoiceDate: '2026-09-01T10:14:22Z'
paymentId: null
paymentLink: >-
https://portal.kelviq.com/acme-inc/pay/aW5fMVJwb1pvU0JzdEN6eW9jUzdpUG1pdGgz
createdOn: '2026-08-01T10:14:20Z'
modifiedOn: '2026-08-01T10:14:22Z'
dueDate: null
attemptCount: 1
nextPaymentAttempt: null
failureDetails: null
customFieldsData: {}
details:
lines:
- name: Premium
description: Premium plan - monthly
quantity: 1
unitPrice: '40.00'
subTotal: '40.00'
amountDue: '0'
appliedBalance: '0'
startingBalance: '0'
endingBalance: '0'
paymentMethod:
paymentMethodType: card
paymentMethodName: visa
last4: '4242'
components:
schemas:
InvoiceListResponse:
type: object
properties:
count:
type: integer
example: 1
next:
type: string
format: uri
nullable: true
example: null
previous:
type: string
format: uri
nullable: true
example: null
results:
type: array
items:
$ref: '#/components/schemas/InvoiceResponse'
InvoiceResponse:
type: object
properties:
id:
type: string
example: INV-20260801101420-Q7M2P
customer:
$ref: '#/components/schemas/OrderCustomer'
product:
$ref: '#/components/schemas/Product'
status:
type: string
enum:
- DRAFT
- OPEN
- PAID
- VOID
- UNCOLLECTIBLE
- PAYMENT_FAILED
example: PAID
paidAt:
type: string
format: date-time
nullable: true
example: '2026-08-01T10:14:22Z'
amountSubtotal:
type: string
description: >-
Decimal amount, serialized as a string (e.g. `"40.00"`), not a JSON
number.
nullable: true
example: '40.00'
amountDiscount:
type: string
description: Decimal amount, serialized as a string, not a JSON number.
example: '0.00'
amountTax:
type: string
description: Decimal amount, serialized as a string, not a JSON number.
nullable: true
example: '0.00'
amountTotal:
type: string
description: Decimal amount, serialized as a string, not a JSON number.
nullable: true
example: '40.00'
currency:
type: string
example: USD
amountSubtotalUnits:
type: integer
format: int64
nullable: true
example: 4000
amountDiscountUnits:
type: integer
format: int64
example: 0
amountTaxUnits:
type: integer
format: int64
nullable: true
example: 0
amountTotalUnits:
type: integer
format: int64
nullable: true
example: 4000
currencySymbol:
type: string
example: $
billingAddress:
$ref: '#/components/schemas/BillingAddress'
plan:
$ref: '#/components/schemas/CatalogPlan'
billingType:
type: string
enum:
- ONE_TIME
- SUBSCRIPTION
nullable: true
example: SUBSCRIPTION
license:
type: array
description: >-
Licenses issued for the invoice's subscription, if the plan includes
licensing. Empty for a one-time-payment invoice.
items:
$ref: '#/components/schemas/SubscriptionLicense'
subscription:
$ref: '#/components/schemas/OrderSubscriptionSummary'
paymentId:
type: string
nullable: true
description: >-
Opaque identifier used to build a payment link for this invoice.
Only set while the invoice is payable (`OPEN` or `PAYMENT_FAILED`,
and not past due).
paymentLink:
type: string
format: uri
nullable: true
description: >-
Hosted portal URL the customer can use to pay this invoice. `null`
unless the invoice is currently payable (mirrors `paymentId`).
example: >-
https://portal.kelviq.com/acme-inc/pay/aW5fMVJwb1pvU0JzdEN6eW9jUzdpUG1pdGgz
createdOn:
type: string
format: date-time
example: '2026-08-01T10:14:20Z'
modifiedOn:
type: string
format: date-time
example: '2026-08-01T10:14:22Z'
dueDate:
type: string
format: date-time
nullable: true
example: null
attemptCount:
type: integer
description: Number of payment attempts made against this invoice.
example: 1
nextPaymentAttempt:
type: string
format: date-time
nullable: true
description: When Stripe will next retry collection, if a retry is scheduled.
example: null
failureDetails:
type: object
nullable: true
description: >-
Details of the most recent failed payment attempt. `null` once the
invoice is paid.
properties:
code:
type: string
nullable: true
example: card_declined
message:
type: string
nullable: true
example: Your card was declined.
paymentMethodType:
type: string
nullable: true
example: card
example: null
customFieldsData:
type: object
additionalProperties: true
example: {}
details:
type: object
description: Line items and balance details for the invoice.
properties:
lines:
type: array
items:
type: object
properties:
name:
type: string
description:
type: string
nullable: true
quantity:
type: integer
unitPrice:
type: string
nullable: true
subTotal:
type: string
amountDue:
type: string
example: '0'
appliedBalance:
type: string
example: '0'
startingBalance:
type: string
example: '0'
endingBalance:
type: string
example: '0'
paymentMethod:
$ref: '#/components/schemas/OrderPaymentMethod'
OrderCustomer:
type: object
properties:
customerId:
type: string
example: testuser
name:
type: string
nullable: true
example: Jane Smith
email:
type: string
format: email
nullable: true
example: jane@example.com
Product:
type: object
description: >-
A product in the catalog. Each product can have multiple plans, images
and files.
properties:
id:
type: string
format: uuid
readOnly: true
example: 0d65f7c0-7e91-4f56-9b32-13a9a6a7c1de
identifier:
type: string
description: >-
Human-readable, URL-safe slug. Auto-generated from `name` if omitted
on create.
example: pro-suite
name:
type: string
example: Pro Suite
description:
type: string
example: Premium tools for growing teams.
taxCode:
type: string
description: Tax code for the product. Must be one of the supported values.
enum:
- saas
- saas_business
- software
- videocontent
- informationservice
- ebook
- digitalgraphic
- videogame
- eservice
- training
example: saas
createdBy:
type: string
readOnly: true
description: Display name of the user who created the product.
example: Jane Smith
modifiedOn:
type: string
format: date-time
readOnly: true
example: '2025-04-12T08:21:14.910Z'
images:
type: array
readOnly: true
items:
$ref: '#/components/schemas/ProductImage'
BillingAddress:
type: object
nullable: true
description: The billing address of the customer.
properties:
country:
type: string
description: The country code (e.g., ISO 3166-1 alpha-2).
example: IN
line1:
type: string
description: Address line 1.
example: 123 Main Street
line2:
type: string
nullable: true
description: Address line 2.
example: Apt 4B
postalCode:
type: string
description: The postal or ZIP code.
example: '560001'
city:
type: string
description: The city name.
example: Bangalore
state:
type: string
description: The state or province.
example: Karnataka
CatalogPlan:
type: object
description: >-
A versioned plan attached to a product. Updates create new versions;
only the published version is `is_latest=true`.
properties:
identifier:
type: string
description: URL-safe slug. Stable across versions.
example: pro-monthly
name:
type: string
example: Pro Monthly
description:
type: string
example: Pro tier billed monthly.
product:
type: string
format: uuid
description: UUID of the parent product.
example: 0d65f7c0-7e91-4f56-9b32-13a9a6a7c1de
metadata:
type: object
additionalProperties: true
example: {}
version:
type: integer
readOnly: true
example: 3
isLatest:
type: boolean
readOnly: true
description: True only for the currently published version.
example: true
modifiedOn:
type: string
format: date-time
readOnly: true
example: '2025-04-12T08:21:14.910Z'
createdOn:
type: string
format: date-time
readOnly: true
example: '2025-03-01T08:21:14.910Z'
details:
type: object
readOnly: true
additionalProperties: true
description: Provider-side identifiers (e.g. `stripeProductId`).
example:
stripeProductId: prod_ABC123
isVisible:
type: boolean
example: true
isImported:
type: boolean
readOnly: true
example: false
countries:
type: array
readOnly: true
items:
type: string
example:
- US
- IN
license:
$ref: '#/components/schemas/LicenseConfig'
links:
type: array
items:
$ref: '#/components/schemas/PlanLink'
files:
type: array
readOnly: true
items:
$ref: '#/components/schemas/PlanFile'
ordering:
type: integer
nullable: true
example: 1
SubscriptionLicense:
type: object
description: An issued license associated with a subscription.
properties:
id:
type: string
format: uuid
nullable: true
example: f81efb90-5f29-4dd1-9c7b-be4085e473de
licenseKey:
type: string
nullable: true
description: The issued license key.
example: 10K-080A3A89-8709-4EB5-80BE-BD37B518CCA1
activatedOn:
type: string
format: date-time
nullable: true
description: When the license was first activated.
example: null
expiresOn:
type: string
format: date-time
nullable: true
description: When the license expires, if applicable.
example: null
activationUsage:
type: integer
nullable: true
description: Number of currently active instances.
example: 0
activationLimit:
type: integer
nullable: true
description: Maximum number of allowed concurrent activations.
example: 2
enabled:
type: boolean
nullable: true
description: Whether the license is enabled.
example: true
OrderSubscriptionSummary:
type: object
description: >-
Summary of the subscription linked to this order. An empty object (`{}`)
when the order has no linked subscription.
properties:
id:
type: string
format: uuid
example: 09d706ca-58f3-4fb2-818f-5b8623d67e6e
status:
type: string
example: active
amount:
type: string
description: >-
Decimal amount, serialized as a string (e.g. `"261.00"`), not a JSON
number.
nullable: true
example: '261.00'
currency:
type: string
nullable: true
example: usd
interval:
type: string
description: Billing interval, e.g. `month` or `year`.
example: month
currencySymbol:
type: string
example: $
nextInvoiceDate:
type: string
format: date-time
nullable: true
example: '2026-08-28T10:46:34Z'
OrderPaymentMethod:
type: object
nullable: true
description: >-
The payment method used for the order's first successful transaction.
`null` if no successful transaction exists yet.
properties:
paymentMethodType:
type: string
example: card
paymentMethodName:
type: string
nullable: true
example: visa
last4:
type: string
nullable: true
example: '4242'
ProductImage:
type: object
description: An image asset attached to a product.
properties:
id:
type: string
format: uuid
readOnly: true
description: Unique identifier for the image.
example: 1f7e1b54-7c6f-4d7e-9a4f-2c9c2d8b9d31
name:
type: string
nullable: true
description: Original filename or display name.
example: hero-banner.png
image:
type: string
readOnly: true
description: Storage key / URL for the image asset.
example: media/.../products///hero-banner.png
ordering:
type: integer
description: Position of the image in the gallery.
example: 0
thumbnail:
type: boolean
description: If `true`, this image is used as the product thumbnail.
example: true
enabled:
type: boolean
description: If `true`, the image is shown publicly.
example: true
LicenseConfig:
type: object
description: License configuration for a plan (used when issuing license keys).
properties:
enabled:
type: boolean
example: true
activationLimit:
type: integer
minimum: 1
example: 3
activationLimitEnabled:
type: boolean
example: true
durationUnit:
type: string
enum:
- DAY
- MONTH
- YEAR
example: YEAR
durationValue:
type: integer
minimum: 1
example: 1
hasExpiry:
type: boolean
example: true
PlanLink:
type: object
properties:
name:
type: string
example: Product page
url:
type: string
format: uri
example: https://example.com/product
PlanFile:
type: object
properties:
id:
type: string
format: uuid
readOnly: true
example: bf9f0fe0-c9c0-436d-8811-e412d0365470
name:
type: string
example: custom-pricinig.png
file:
type: string
format: uri
readOnly: true
example: >-
https://cdn.kelviq.com/media/organizations/8/plan/1ad723d2-40eb-4bf0-b924-557e6697e788/53c28d460fed421a81f6c6e90114ff4f/custom-pricinig.png
ordering:
type: integer
example: 0
enabled:
type: boolean
example: true
downloadUrl:
type: string
format: uri
readOnly: true
description: >-
URL clients can hit to download the file. Will redirect to a
forced-download URL.
example: >-
https://api.kelviq.com/api/v1/catalog/plans/10-july/file/bf9f0fe0-c9c0-436d-8811-e412d0365470/download/
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
The Server API Key obtained from the kelviq application. Pass as a
Bearer token in the Authorization header. Example: 'Authorization:
Bearer __YOUR_API_KEY__'
````