# Invoices API

The Invoices API allows you to programmatically retrieve billing invoices for your Typesense Cloud account. You can list all invoices and fetch detailed information including line items for individual invoices.

# List all invoices

This endpoint returns a paginated list of invoices for your account, excluding each invoice's line items.

curl -X GET --location "https://cloud.typesense.org/api/v1/invoices?page=1&per_page=10" \
    -H "Accept: application/json" \
    -H "X-TYPESENSE-CLOUD-MANAGEMENT-API-KEY: YOUR-API-KEY"

Query Parameters:

Parameter Type Default Description
page integer 1 Page number for pagination
per_page integer 10 Number of invoices per page (maximum 50)

Response:

{
  "page": 1,
  "per_page": 10,
  "total": 25,
  "invoices": [
    {
      "id": "inv_abc123def456",
      "number": 12345,
      "status": "paid",
      "amount_cents": 125000,
      "invoice_date": 1702857600,
      "period_starts_at": 1700179200,
      "period_ends_at": 1702857599,
      "line_items_path": "/api/v1/invoices/inv_abc123def456",
      "invoice_html_url": "https://cloud.typesense.org/invoices/inv_abc123def456",
      "account": {
        "owner_name": "Acme Corp",
        "owner_type": "Team",
        "billing_email": "billing@acme.com",
        "additional_billing_information": "123 Main St\nSan Francisco, CA 94102"
      },
      "payment": {
        "paid_via_card_cents": 100000,
        "paid_via_credits_cents": 25000,
        "credit_balance_snapshot_cents": 475000
      }
    },
    {
      "id": "inv_xyz789ghi012",
      "number": 12344,
      "status": "due",
      "amount_cents": 87500,
      "invoice_date": 1700179200,
      "period_starts_at": 1697500800,
      "period_ends_at": 1700179199,
      "line_items_path": "/api/v1/invoices/inv_xyz789ghi012",
      "invoice_html_url": "https://cloud.typesense.org/invoices/inv_xyz789ghi012",
      "account": {
        "owner_name": "Acme Corp",
        "owner_type": "Team",
        "billing_email": "billing@acme.com",
        "additional_billing_information": "123 Main St\nSan Francisco, CA 94102"
      },
      "payment": {
        "paid_via_card_cents": 0,
        "paid_via_credits_cents": 0,
        "credit_balance_snapshot_cents": 500000
      }
    }
  ]
}

# Get a single invoice

This endpoint retrieves detailed information about a specific invoice, including all line items.

curl -X GET --location "https://cloud.typesense.org/api/v1/invoices/inv_abc123def456" \
    -H "Accept: application/json" \
    -H "X-TYPESENSE-CLOUD-MANAGEMENT-API-KEY: YOUR-API-KEY"

Response:

{
  "id": "inv_abc123def456",
  "number": 12345,
  "status": "paid",
  "amount_cents": 125000,
  "invoice_date": 1702857600,
  "period_starts_at": 1700179200,
  "period_ends_at": 1702857599,
  "line_items_path": "/api/v1/invoices/inv_abc123def456",
  "invoice_html_url": "https://cloud.typesense.org/invoices/inv_abc123def456",
  "account": {
    "owner_name": "Acme Corp",
    "owner_type": "Team",
    "billing_email": "billing@acme.com",
    "additional_billing_information": "123 Main St\nSan Francisco, CA 94102"
  },
  "payment": {
    "paid_via_card_cents": 100000,
    "paid_via_credits_cents": 25000,
    "credit_balance_snapshot_cents": 475000
  },
  "line_items": [
    {
      "description": "Node -- 0197kdlrfsubahw4p -- 4 GB RAM, 2 vCPUs, GPU:No, HiPerfDisk:No, HA:Yes, SDN:3 Regions, LoadBalanced:No, Oregon (per node hour)",
      "unit_price_cents": 2500,
      "quantity": 720,
      "price_cents": 1800000,
      "line_item_type": "node",
      "parameters": {
        "cluster_id": "0197kdlrfsubahw4p",
        "memory_option": "4gb",
        "vcpu_option": "2_vcpus",
        "gpu_option": "no",
        "high_performance_disk_option": "no",
        "high_availability_option": "yes",
        "search_delivery_network_option": "3_regions",
        "load_balancing_option": "no",
        "region": "oregon"
      }
    },
    {
      "description": "Bandwidth -- 0197kdlrfsubahw4p -- 4 GB RAM, 2 vCPUs, GPU:No, HiPerfDisk:No, HA:Yes, SDN:3 Regions, LoadBalanced:No, Oregon (per GB)",
      "unit_price_cents": 120,
      "quantity": 50000000,
      "price_cents": 6000000,
      "line_item_type": "bandwidth",
      "parameters": {
        "cluster_id": "0197kdlrfsubahw4p",
        "memory_option": "4gb",
        "vcpu_option": "2_vcpus",
        "gpu_option": "no",
        "high_performance_disk_option": "no",
        "high_availability_option": "yes",
        "search_delivery_network_option": "3_regions",
        "load_balancing_option": "no",
        "region": "oregon"
      }
    },
    {
      "description": "Typesense Cloud Support - Business Plan - 2025-01-01 00:00:00 UTC to 2025-01-31 23:59:59 UTC",
      "unit_price_cents": 50000,
      "quantity": 1,
      "price_cents": 50000,
      "line_item_type": "support",
      "parameters": {
        "plan_name": "Business",
        "starts_at": 1735689600,
        "ends_at": 1738367999
      }
    },
    {
      "description": "Prepaid Credit Purchase",
      "unit_price_cents": 10000,
      "quantity": 100,
      "price_cents": 1000000,
      "line_item_type": "prepaid_credit_purchase",
      "parameters": {}
    }
  ]
}

# Line Item Fields

Field Type Description
description string Human-readable description of the line item
unit_price_cents integer Unit price in cents
quantity number Quantity (can be fractional for some line items)

For bandwidth line items, the quantity GB transferred with rounding applied. For node line items, the quantity represents node-hours of usage.
price_cents integer Total price for this line item in cents (quantity * unit_price_cents).
line_item_type string Type of line item (see table below).
parameters object Structured metadata specific to the line item type (see table below).

# Line Item Types

Each line item in an invoice has a line_item_type field that indicates what the charge is for. The following table describes each type:

Line Item Type Description Parameters Included
node Cluster node usage charges cluster_id, memory_option, vcpu_option, gpu_option, high_performance_disk_option, high_availability_option, search_delivery_network_option, load_balancing_option, region
bandwidth Bandwidth usage charges cluster_id, memory_option, vcpu_option, gpu_option, high_performance_disk_option, high_availability_option, search_delivery_network_option, load_balancing_option, region
support Support plan subscription charges plan_name, starts_at (Unix timestamp), ends_at (Unix timestamp)
prepaid_credit_purchase Prepaid credit purchases None

# Important Notes

  • The list endpoint returns invoice summaries without line items. Use the individual invoice endpoint to retrieve detailed line items.
  • All monetary amounts are in cents (USD).
  • All timestamps are Unix timestamps (seconds since epoch).
  • Pagination is supported for the list endpoint with a maximum of 50 invoices per page.
Edit page (opens new window)
Last Updated: 10/15/2025, 8:00:43 PM

← Response Codes →