Invoice Receipts API¶

Structured invoice and receipt endpoints for financial system integration and AWS bill cross-referencing. Supports filtering, sorting, and CSV/JSON exports.

Base URL: https://api.vell.ai/api/v1 Authentication: Bearer token Prefix: /invoice-receipts

Endpoints¶

List Invoices¶

GET /invoice-receipts

Parameter	Type	Required	Default	Description
`type`	string	No	—	Billing type: `subscription`, `token_pack`, `marketplace_usage`, `free_trial`, `demo`
`status`	string	No	—	Invoice status filter
`start_date`	date	No	—	Start of date range
`end_date`	date	No	—	End of date range
`sort`	string	No	`created_at`	Sort by: `created_at`, `billing_type`, `total_amount`
`dir`	string	No	`desc`	Sort direction: `asc` or `desc`
`per_page`	integer	No	`50`	Items per page (max: 200)

Response:

{
  "data": [
    {
      "invoice_number": "INV-2026-0042",
      "billing_type": "subscription",
      "status": "paid",
      "total_amount": 99.00,
      "currency": "USD",
      "created_at": "2026-02-01T00:00:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 50,
    "total": 12,
    "last_page": 1
  },
  "filters_applied": {
    "type": null,
    "status": null,
    "start_date": null,
    "end_date": null,
    "sort": "created_at",
    "dir": "desc"
  }
}

Get Single Invoice¶

GET /invoice-receipts/{invoiceNumber}

Parameter	Type	Location	Description
`invoiceNumber`	string	path	Invoice number (e.g., `INV-2026-0042`)

Invoice Summary¶

GET /invoice-receipts/summary

Parameter	Type	Required	Description
`start_date`	date	No	Start of date range
`end_date`	date	No	End of date range

Returns aggregated invoice data across billing types.

Export CSV¶

GET /invoice-receipts/export/csv

Parameter	Type	Required	Default	Description
`type`	string	No	—	Billing type filter
`status`	string	No	—	Status filter
`start_date`	date	No	—	Start date
`end_date`	date	No	—	End date
`sort`	string	No	`created_at`	Sort column
`dir`	string	No	`desc`	Sort direction
`line_items`	boolean	No	`true`	Include line item details

Returns a CSV file download.

Export JSON¶

GET /invoice-receipts/export/json

Same parameters as CSV export. Returns a JSON file download.

Generate Marketplace Invoice¶

POST /invoice-receipts/generate-marketplace

Generate an invoice for AWS Marketplace usage for a given period.

Parameter	Type	Required	Default	Description
`period_start`	date	No	Start of current month	Billing period start
`period_end`	date	No	End of current month	Billing period end

Marketplace customers only

This endpoint requires the user to have a marketplace_customer_id. Returns 403 otherwise.

Response (201):

{
  "message": "Marketplace usage invoice generated",
  "data": {}
}

Backfill Invoices¶

POST /invoice-receipts/backfill

Create invoice records from existing orders that don't have corresponding invoices.

Parameter	Type	Required	Default	Description
`limit`	integer	No	`50`	Max invoices to create (max: 200)

Response:

{
  "message": "8 invoice(s) backfilled from existing orders",
  "count": 8,
  "invoice_numbers": ["INV-2026-0035", "INV-2026-0036"]
}

Use Cases¶

Financial System Integration¶

List all invoices for a period: GET /invoice-receipts?start_date=2026-01-01&end_date=2026-01-31
Export as CSV for import into accounting software: GET /invoice-receipts/export/csv
Or export as JSON for API-based integration: GET /invoice-receipts/export/json

AWS Marketplace Cost Reconciliation¶

Generate marketplace usage invoice: POST /invoice-receipts/generate-marketplace
Compare with your AWS billing console
Use GET /invoice-receipts/summary for aggregate totals

Backfill Missing Records¶

If invoices were not generated for historical orders:

Run backfill: POST /invoice-receipts/backfill with limit: 200
Review the generated invoice numbers
Export the complete history: GET /invoice-receipts/export/csv