Get Invoice

Use when loading an invoice for display or editing (e.g. portal or reconciliation). Supports group_by for usage breakdown and force_runtime_recalculation.

GET /v1/invoices/{id}

cURL

curl -X GET "https://api.flexprice.io/v1/invoices/inv_1234567890" \
  -H "Authorization: Bearer YOUR_API_KEY"

200

{
  "id": "inv_1234567890",
  "customer_id": "cust_1234",
  "subscription_id": "sub_5678",
  "invoice_number": "INV-2024-0001",
  "invoice_type": "SUBSCRIPTION",
  "invoice_status": "FINALIZED",
  "payment_status": "PAID",
  "currency": "usd",
  "amount_due": "100.00",
  "amount_paid": "100.00",
  "amount_remaining": "0.00",
  "subtotal": "100.00",
  "total_tax": "0.00",
  "total_discount": "0.00",
  "total": "100.00",
  "total_prepaid_credits_applied": "0.00",
  "due_date": "2024-02-01T00:00:00Z",
  "period_start": "2024-01-01T00:00:00Z",
  "period_end": "2024-01-31T23:59:59Z",
  "billing_period": "MONTHLY",
  "billing_reason": "subscription_cycle",
  "line_items": [
    {
      "id": "li_abcd1234",
      "price_id": "price_xyz",
      "display_name": "API Calls",
      "amount": "100.00",
      "quantity": "1000.00",
      "period_start": "2024-01-01T00:00:00Z",
      "period_end": "2024-01-31T23:59:59Z",
      "prepaid_credits_applied": "0.00",
      "line_item_discount": "0.00",
      "invoice_level_discount": "0.00",
      "usage_breakdown": [
        {
          "cost": "60.00",
          "usage": "600.00",
          "percentage": "60.0",
          "event_count": 600,
          "grouped_by": {
            "source": "api"
          }
        },
        {
          "cost": "40.00",
          "usage": "400.00",
          "percentage": "40.0",
          "event_count": 400,
          "grouped_by": {
            "source": "webhook"
          }
        }
      ]
    }
  ],
  "metadata": {},
  "invoice_pdf_url": "https://invoices.flexprice.io/inv_1234567890.pdf",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-15T00:00:00Z",
  "finalized_at": "2024-01-05T00:00:00Z",
  "paid_at": "2024-01-15T00:00:00Z"
}

Path Parameters

id · string · required

The unique identifier of the invoice to retrieve

Query Parameters

group_by · array

Group usage breakdown by specified fields (e.g., source, feature_id, properties.org_id)

Can be provided multiple times to group by multiple dimensions:

• ?group_by=source
• ?group_by=source&group_by=feature_id
• ?group_by=properties.org_id (for nested properties)

force_runtime_recalculation · boolean · default: "false"

Force recalculation of usage breakdown at runtime instead of using cached values

Response

id · string

Unique identifier for the invoice

customer_id · string

ID of the customer this invoice belongs to

subscription_id · string

ID of the subscription (if applicable)

invoice_number · string

Human-readable invoice number

invoice_type · string

Type of invoice

Values: SUBSCRIPTION, ONE_TIME, CREDIT, PRORATION

invoice_status · string

Current status of the invoice

Values: DRAFT, FINALIZED, VOIDED, UNCOLLECTIBLE

payment_status · string

Payment status

Values: PENDING, PAID, UNPAID, PARTIALLY_PAID, OVERPAID, FAILED

currency · string

Three-letter ISO currency code (e.g., USD, EUR)

amount_due · string

Total amount due

amount_paid · string

Amount already paid

amount_remaining · string

Remaining amount to be paid

subtotal · string

Subtotal before taxes and discounts

total_tax · string

Total tax amount

total_discount · string

Total discount amount

total · string

Final total amount

total_prepaid_credits_applied · string

Total prepaid credits applied to this invoice

due_date · string

Date when payment is due (ISO 8601 format)

period_start · string

Start of billing period (ISO 8601 format)

period_end · string

End of billing period (ISO 8601 format)

billing_period · string

Billing period (MONTHLY, YEARLY, etc.)

billing_reason · string

Reason for invoice creation

line_items · array

Array of line items included in the invoice

Show Line item object

id · string

Unique identifier for the line item

price_id · string

ID of the price associated with this line item

display_name · string

Human-readable name for this line item

amount · string

Monetary amount for this line item

quantity · string

Quantity of units

period_start · string

Start date of the period this line item covers

period_end · string

End date of the period this line item covers

prepaid_credits_applied · string

Amount in invoice currency reduced from this line item due to prepaid credits

line_item_discount · string

Discount applied directly to this line item

invoice_level_discount · string

Invoice-level discount allocated to this line item

usage_breakdown · array

Flexible usage breakdown supporting any grouping (only if group_by is specified)

Show Usage breakdown item

cost · string

Cost attributed to this group

usage · string

Total usage amount from this group

percentage · string

Percentage of total line item cost from this group

event_count · integer

Number of events from this group

grouped_by · object

The grouping field values (e.g., source: api, org_id: org123)

customer · object

Customer information

subscription · object

Subscription information (if applicable)

taxes · array

Tax records applied to this invoice

coupon_applications · array

Coupon applications for this invoice

metadata · object

Custom metadata key-value pairs

invoice_pdf_url · string

URL where customers can download the PDF version of this invoice

created_at · string

Timestamp when invoice was created

updated_at · string

Timestamp when invoice was last updated

finalized_at · string

Timestamp when invoice was finalized

paid_at · string

Timestamp when invoice was paid

cURL

curl -X GET "https://api.flexprice.io/v1/invoices/inv_1234567890" \
  -H "Authorization: Bearer YOUR_API_KEY"

200

{
  "id": "inv_1234567890",
  "customer_id": "cust_1234",
  "subscription_id": "sub_5678",
  "invoice_number": "INV-2024-0001",
  "invoice_type": "SUBSCRIPTION",
  "invoice_status": "FINALIZED",
  "payment_status": "PAID",
  "currency": "usd",
  "amount_due": "100.00",
  "amount_paid": "100.00",
  "amount_remaining": "0.00",
  "subtotal": "100.00",
  "total_tax": "0.00",
  "total_discount": "0.00",
  "total": "100.00",
  "total_prepaid_credits_applied": "0.00",
  "due_date": "2024-02-01T00:00:00Z",
  "period_start": "2024-01-01T00:00:00Z",
  "period_end": "2024-01-31T23:59:59Z",
  "billing_period": "MONTHLY",
  "billing_reason": "subscription_cycle",
  "line_items": [
    {
      "id": "li_abcd1234",
      "price_id": "price_xyz",
      "display_name": "API Calls",
      "amount": "100.00",
      "quantity": "1000.00",
      "period_start": "2024-01-01T00:00:00Z",
      "period_end": "2024-01-31T23:59:59Z",
      "prepaid_credits_applied": "0.00",
      "line_item_discount": "0.00",
      "invoice_level_discount": "0.00",
      "usage_breakdown": [
        {
          "cost": "60.00",
          "usage": "600.00",
          "percentage": "60.0",
          "event_count": 600,
          "grouped_by": {
            "source": "api"
          }
        },
        {
          "cost": "40.00",
          "usage": "400.00",
          "percentage": "40.0",
          "event_count": 400,
          "grouped_by": {
            "source": "webhook"
          }
        }
      ]
    }
  ],
  "metadata": {},
  "invoice_pdf_url": "https://invoices.flexprice.io/inv_1234567890.pdf",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-15T00:00:00Z",
  "finalized_at": "2024-01-05T00:00:00Z",
  "paid_at": "2024-01-15T00:00:00Z"
}