Skip to main content
POST
/
invoices
/
search
List invoices by filter
curl --request POST \
  --url https://api.cloud.flexprice.io/v1/invoices/search \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "amount_due_gt": 123,
  "amount_remaining_gt": 123,
  "customer_id": "<string>",
  "end_time": "<string>",
  "expand": "<string>",
  "external_customer_id": "<string>",
  "filters": [
    {
      "data_type": "string",
      "field": "<string>",
      "operator": "eq",
      "value": {
        "array": [
          "<string>"
        ],
        "boolean": true,
        "date": "<string>",
        "number": 123,
        "string": "<string>"
      }
    }
  ],
  "invoice_ids": [
    "<string>"
  ],
  "invoice_status": [
    "DRAFT"
  ],
  "invoice_type": "SUBSCRIPTION",
  "limit": 500,
  "offset": 1,
  "order": "asc",
  "payment_status": [
    "INITIATED"
  ],
  "skip_line_items": true,
  "sort": [
    {
      "direction": "asc",
      "field": "<string>"
    }
  ],
  "start_time": "<string>",
  "status": "published",
  "subscription_id": "<string>"
}'
{
  "items": [
    {
      "amount_due": 123,
      "amount_paid": 123,
      "amount_remaining": 123,
      "billing_period": "<string>",
      "billing_reason": "<string>",
      "billing_sequence": 123,
      "coupon_applications": [
        {
          "applied_at": "<string>",
          "coupon_association_id": "<string>",
          "coupon_id": "<string>",
          "coupon_snapshot": {},
          "created_at": "<string>",
          "created_by": "<string>",
          "currency": "<string>",
          "discount_percentage": 123,
          "discount_type": "fixed",
          "discounted_amount": 123,
          "environment_id": "<string>",
          "final_price": 123,
          "id": "<string>",
          "invoice_id": "<string>",
          "invoice_line_item_id": "<string>",
          "metadata": {},
          "original_price": 123,
          "status": "published",
          "subscription_id": "<string>",
          "tenant_id": "<string>",
          "updated_at": "<string>",
          "updated_by": "<string>"
        }
      ],
      "created_at": "<string>",
      "created_by": "<string>",
      "currency": "<string>",
      "customer": {
        "address_city": "<string>",
        "address_country": "<string>",
        "address_line1": "<string>",
        "address_line2": "<string>",
        "address_postal_code": "<string>",
        "address_state": "<string>",
        "created_at": "<string>",
        "created_by": "<string>",
        "email": "<string>",
        "environment_id": "<string>",
        "external_id": "<string>",
        "id": "<string>",
        "metadata": {},
        "name": "<string>",
        "status": "published",
        "tenant_id": "<string>",
        "updated_at": "<string>",
        "updated_by": "<string>"
      },
      "customer_id": "<string>",
      "description": "<string>",
      "due_date": "<string>",
      "finalized_at": "<string>",
      "id": "<string>",
      "idempotency_key": "<string>",
      "invoice_number": "<string>",
      "invoice_pdf_url": "<string>",
      "invoice_status": "DRAFT",
      "invoice_type": "SUBSCRIPTION",
      "line_items": [
        {
          "amount": 123,
          "created_at": "<string>",
          "created_by": "<string>",
          "currency": "<string>",
          "customer_id": "<string>",
          "display_name": "<string>",
          "entity_id": "<string>",
          "entity_type": "<string>",
          "id": "<string>",
          "invoice_id": "<string>",
          "metadata": {},
          "meter_display_name": "<string>",
          "meter_id": "<string>",
          "period_end": "<string>",
          "period_start": "<string>",
          "plan_display_name": "<string>",
          "plan_id": "<string>",
          "price_id": "<string>",
          "price_type": "<string>",
          "price_unit": "<string>",
          "price_unit_amount": 123,
          "price_unit_id": "<string>",
          "quantity": 123,
          "status": "<string>",
          "subscription_id": "<string>",
          "tenant_id": "<string>",
          "updated_at": "<string>",
          "updated_by": "<string>",
          "usage_analytics": [
            {
              "cost": "<string>",
              "event_count": 123,
              "percentage": "<string>",
              "source": "<string>",
              "usage": "<string>"
            }
          ],
          "usage_breakdown": [
            {
              "cost": "<string>",
              "event_count": 123,
              "grouped_by": {},
              "percentage": "<string>",
              "usage": "<string>"
            }
          ]
        }
      ],
      "metadata": {},
      "overpaid_amount": 123,
      "paid_at": "<string>",
      "payment_status": "INITIATED",
      "period_end": "<string>",
      "period_start": "<string>",
      "status": "<string>",
      "subscription": {
        "active_pause_id": "<string>",
        "billing_anchor": "<string>",
        "billing_cadence": "RECURRING",
        "billing_cycle": "anniversary",
        "billing_period": "MONTHLY",
        "billing_period_count": 123,
        "cancel_at": "<string>",
        "cancel_at_period_end": true,
        "cancelled_at": "<string>",
        "collection_method": "<string>",
        "commitment_amount": 123,
        "coupon_associations": [
          {
            "coupon": {
              "amount_off": 123,
              "cadence": "once",
              "created_at": "<string>",
              "created_by": "<string>",
              "currency": "<string>",
              "duration_in_periods": 123,
              "environment_id": "<string>",
              "id": "<string>",
              "max_redemptions": 123,
              "metadata": {},
              "name": "<string>",
              "percentage_off": 123,
              "redeem_after": "<string>",
              "redeem_before": "<string>",
              "rules": {},
              "status": "published",
              "tenant_id": "<string>",
              "total_redemptions": 123,
              "type": "fixed",
              "updated_at": "<string>",
              "updated_by": "<string>"
            },
            "coupon_id": "<string>",
            "created_at": "<string>",
            "created_by": "<string>",
            "environment_id": "<string>",
            "id": "<string>",
            "metadata": {},
            "status": "published",
            "subscription_id": "<string>",
            "subscription_line_item_id": "<string>",
            "tenant_id": "<string>",
            "updated_at": "<string>",
            "updated_by": "<string>"
          }
        ],
        "created_at": "<string>",
        "created_by": "<string>",
        "currency": "<string>",
        "current_period_end": "<string>",
        "current_period_start": "<string>",
        "customer": {
          "address_city": "<string>",
          "address_country": "<string>",
          "address_line1": "<string>",
          "address_line2": "<string>",
          "address_postal_code": "<string>",
          "address_state": "<string>",
          "created_at": "<string>",
          "created_by": "<string>",
          "email": "<string>",
          "environment_id": "<string>",
          "external_id": "<string>",
          "id": "<string>",
          "metadata": {},
          "name": "<string>",
          "status": "published",
          "tenant_id": "<string>",
          "updated_at": "<string>",
          "updated_by": "<string>"
        },
        "customer_id": "<string>",
        "customer_timezone": "<string>",
        "end_date": "<string>",
        "environment_id": "<string>",
        "gateway_payment_method_id": "<string>",
        "id": "<string>",
        "latest_invoice": {},
        "line_items": [
          {
            "billing_period": "MONTHLY",
            "created_at": "<string>",
            "created_by": "<string>",
            "currency": "<string>",
            "customer_id": "<string>",
            "display_name": "<string>",
            "end_date": "<string>",
            "entity_id": "<string>",
            "entity_type": "plan",
            "environment_id": "<string>",
            "id": "<string>",
            "invoice_cadence": "ARREAR",
            "metadata": {},
            "meter_display_name": "<string>",
            "meter_id": "<string>",
            "plan_display_name": "<string>",
            "price_id": "<string>",
            "price_type": "USAGE",
            "price_unit": "<string>",
            "price_unit_id": "<string>",
            "quantity": 123,
            "start_date": "<string>",
            "status": "published",
            "subscription_id": "<string>",
            "tenant_id": "<string>",
            "trial_period": 123,
            "updated_at": "<string>",
            "updated_by": "<string>"
          }
        ],
        "lookup_key": "<string>",
        "metadata": {},
        "overage_factor": 123,
        "pause_status": "none",
        "pauses": [
          {
            "created_at": "<string>",
            "created_by": "<string>",
            "environment_id": "<string>",
            "id": "<string>",
            "metadata": {},
            "original_period_end": "<string>",
            "original_period_start": "<string>",
            "pause_end": "<string>",
            "pause_mode": "immediate",
            "pause_start": "<string>",
            "pause_status": "none",
            "reason": "<string>",
            "resume_mode": "immediate",
            "resumed_at": "<string>",
            "status": "published",
            "subscription_id": "<string>",
            "tenant_id": "<string>",
            "updated_at": "<string>",
            "updated_by": "<string>"
          }
        ],
        "payment_behavior": "<string>",
        "plan": {
          "created_at": "<string>",
          "created_by": "<string>",
          "credit_grants": [
            {
              "cadence": "ONETIME",
              "created_at": "<string>",
              "created_by": "<string>",
              "credits": 123,
              "environment_id": "<string>",
              "expiration_duration": 123,
              "expiration_duration_unit": "DAY",
              "expiration_type": "NEVER",
              "id": "<string>",
              "metadata": {},
              "name": "<string>",
              "period": "DAILY",
              "period_count": 123,
              "plan_id": "<string>",
              "priority": 123,
              "scope": "PLAN",
              "status": "published",
              "subscription_id": "<string>",
              "tenant_id": "<string>",
              "updated_at": "<string>",
              "updated_by": "<string>"
            }
          ],
          "description": "<string>",
          "display_order": 123,
          "entitlements": [
            {
              "addon": {
                "created_at": "<string>",
                "created_by": "<string>",
                "description": "<string>",
                "entitlements": [
                  {}
                ],
                "environment_id": "<string>",
                "id": "<string>",
                "lookup_key": "<string>",
                "metadata": {},
                "name": "<string>",
                "prices": [
                  {
                    "amount": 123,
                    "billing_cadence": "RECURRING",
                    "billing_model": "FLAT_FEE",
                    "billing_period": "MONTHLY",
                    "billing_period_count": 123,
                    "conversion_rate": 123,
                    "created_at": "<string>",
                    "created_by": "<string>",
                    "currency": "<string>",
                    "description": "<string>",
                    "display_amount": "<string>",
                    "display_price_unit_amount": "<string>",
                    "end_date": "<string>",
                    "entity_id": "<string>",
                    "entity_type": "PLAN",
                    "environment_id": "<string>",
                    "id": "<string>",
                    "invoice_cadence": "ARREAR",
                    "lookup_key": "<string>",
                    "metadata": {},
                    "meter": {
                      "aggregation": "<any>",
                      "created_at": "<any>",
                      "event_name": "<any>",
                      "filters": "<any>",
                      "id": "<any>",
                      "name": "<any>",
                      "reset_usage": "<any>",
                      "status": "<any>",
                      "tenant_id": "<any>",
                      "updated_at": "<any>"
                    },
                    "meter_id": "<string>",
                    "parent_price_id": "<string>",
                    "plan_id": "<string>",
                    "price_unit": "<string>",
                    "price_unit_amount": 123,
                    "price_unit_id": "<string>",
                    "price_unit_tiers": [
                      "<any>"
                    ],
                    "price_unit_type": "FIAT",
                    "pricing_unit": {
                      "base_currency": "<any>",
                      "code": "<any>",
                      "conversion_rate": "<any>",
                      "created_at": "<any>",
                      "created_by": "<any>",
                      "environment_id": "<any>",
                      "id": "<any>",
                      "name": "<any>",
                      "precision": "<any>",
                      "status": "<any>",
                      "symbol": "<any>",
                      "tenant_id": "<any>",
                      "updated_at": "<any>",
                      "updated_by": "<any>"
                    },
                    "start_date": "<string>",
                    "status": "published",
                    "tenant_id": "<string>",
                    "tier_mode": "VOLUME",
                    "tiers": [
                      "<any>"
                    ],
                    "transform_quantity": {
                      "divide_by": "<any>",
                      "round": "<any>"
                    },
                    "trial_period": 123,
                    "type": "USAGE",
                    "updated_at": "<string>",
                    "updated_by": "<string>"
                  }
                ],
                "status": "published",
                "tenant_id": "<string>",
                "type": "onetime",
                "updated_at": "<string>",
                "updated_by": "<string>"
              },
              "created_at": "<string>",
              "created_by": "<string>",
              "display_order": 123,
              "entity_id": "<string>",
              "entity_type": "PLAN",
              "environment_id": "<string>",
              "feature": {
                "alert_settings": {
                  "alert_enabled": true,
                  "critical": {
                    "condition": "above",
                    "threshold": 123
                  },
                  "warning": {
                    "condition": "above",
                    "threshold": 123
                  }
                },
                "created_at": "<string>",
                "created_by": "<string>",
                "description": "<string>",
                "environment_id": "<string>",
                "id": "<string>",
                "lookup_key": "<string>",
                "metadata": {},
                "meter": {
                  "aggregation": {},
                  "created_at": "2024-03-20T15:04:05Z",
                  "event_name": "api_request",
                  "filters": [
                    "<any>"
                  ],
                  "id": "550e8400-e29b-41d4-a716-446655440000",
                  "name": "API Usage Meter",
                  "reset_usage": "BILLING_PERIOD",
                  "status": "published",
                  "tenant_id": "tenant123",
                  "updated_at": "2024-03-20T15:04:05Z"
                },
                "meter_id": "<string>",
                "name": "<string>",
                "status": "published",
                "tenant_id": "<string>",
                "type": "metered",
                "unit_plural": "<string>",
                "unit_singular": "<string>",
                "updated_at": "<string>",
                "updated_by": "<string>"
              },
              "feature_id": "<string>",
              "feature_type": "metered",
              "id": "<string>",
              "is_enabled": true,
              "is_soft_limit": true,
              "plan": {},
              "plan_id": "<string>",
              "static_value": "<string>",
              "status": "published",
              "tenant_id": "<string>",
              "updated_at": "<string>",
              "updated_by": "<string>",
              "usage_limit": 123,
              "usage_reset_period": "MONTHLY"
            }
          ],
          "environment_id": "<string>",
          "id": "<string>",
          "lookup_key": "<string>",
          "metadata": {},
          "name": "<string>",
          "prices": [
            {
              "amount": 123,
              "billing_cadence": "RECURRING",
              "billing_model": "FLAT_FEE",
              "billing_period": "MONTHLY",
              "billing_period_count": 123,
              "conversion_rate": 123,
              "created_at": "<string>",
              "created_by": "<string>",
              "currency": "<string>",
              "description": "<string>",
              "display_amount": "<string>",
              "display_price_unit_amount": "<string>",
              "end_date": "<string>",
              "entity_id": "<string>",
              "entity_type": "PLAN",
              "environment_id": "<string>",
              "id": "<string>",
              "invoice_cadence": "ARREAR",
              "lookup_key": "<string>",
              "metadata": {},
              "meter": {
                "aggregation": {},
                "created_at": "2024-03-20T15:04:05Z",
                "event_name": "api_request",
                "filters": [
                  "<any>"
                ],
                "id": "550e8400-e29b-41d4-a716-446655440000",
                "name": "API Usage Meter",
                "reset_usage": "BILLING_PERIOD",
                "status": "published",
                "tenant_id": "tenant123",
                "updated_at": "2024-03-20T15:04:05Z"
              },
              "meter_id": "<string>",
              "parent_price_id": "<string>",
              "plan_id": "<string>",
              "price_unit": "<string>",
              "price_unit_amount": 123,
              "price_unit_id": "<string>",
              "price_unit_tiers": [
                {}
              ],
              "price_unit_type": "FIAT",
              "pricing_unit": {
                "base_currency": "<string>",
                "code": "<string>",
                "conversion_rate": 123,
                "created_at": "<string>",
                "created_by": "<string>",
                "environment_id": "<string>",
                "id": "<string>",
                "name": "<string>",
                "precision": 123,
                "status": "published",
                "symbol": "<string>",
                "tenant_id": "<string>",
                "updated_at": "<string>",
                "updated_by": "<string>"
              },
              "start_date": "<string>",
              "status": "published",
              "tenant_id": "<string>",
              "tier_mode": "VOLUME",
              "tiers": [
                {}
              ],
              "transform_quantity": {
                "divide_by": 123,
                "round": "<string>"
              },
              "trial_period": 123,
              "type": "USAGE",
              "updated_at": "<string>",
              "updated_by": "<string>"
            }
          ],
          "status": "published",
          "tenant_id": "<string>",
          "updated_at": "<string>",
          "updated_by": "<string>"
        },
        "plan_id": "<string>",
        "proration_behavior": "create_prorations",
        "schedule": {
          "created_at": "<string>",
          "current_phase_index": 123,
          "end_behavior": "RELEASE",
          "id": "<string>",
          "phases": [
            {
              "commitment_amount": 123,
              "created_at": "<string>",
              "credit_grants": [
                {
                  "cadence": "ONETIME",
                  "created_at": "<string>",
                  "created_by": "<string>",
                  "credits": 123,
                  "environment_id": "<string>",
                  "expiration_duration": 123,
                  "expiration_duration_unit": "DAY",
                  "expiration_type": "NEVER",
                  "id": "<string>",
                  "metadata": {},
                  "name": "<string>",
                  "period": "DAILY",
                  "period_count": 123,
                  "plan_id": "<string>",
                  "priority": 123,
                  "scope": "PLAN",
                  "status": "published",
                  "subscription_id": "<string>",
                  "tenant_id": "<string>",
                  "updated_at": "<string>",
                  "updated_by": "<string>"
                }
              ],
              "end_date": "<string>",
              "id": "<string>",
              "line_items": [
                {
                  "billing_period": "MONTHLY",
                  "created_at": "<string>",
                  "created_by": "<string>",
                  "currency": "<string>",
                  "customer_id": "<string>",
                  "display_name": "<string>",
                  "end_date": "<string>",
                  "entity_id": "<string>",
                  "entity_type": "plan",
                  "environment_id": "<string>",
                  "id": "<string>",
                  "invoice_cadence": "ARREAR",
                  "metadata": {},
                  "meter_display_name": "<string>",
                  "meter_id": "<string>",
                  "plan_display_name": "<string>",
                  "price_id": "<string>",
                  "price_type": "USAGE",
                  "price_unit": "<string>",
                  "price_unit_id": "<string>",
                  "quantity": 123,
                  "start_date": "<string>",
                  "status": "published",
                  "subscription_id": "<string>",
                  "tenant_id": "<string>",
                  "trial_period": 123,
                  "updated_at": "<string>",
                  "updated_by": "<string>"
                }
              ],
              "overage_factor": 123,
              "phase_index": 123,
              "schedule_id": "<string>",
              "start_date": "<string>",
              "updated_at": "<string>"
            }
          ],
          "start_date": "<string>",
          "status": "ACTIVE",
          "subscription_id": "<string>",
          "updated_at": "<string>"
        },
        "start_date": "<string>",
        "status": "published",
        "subscription_status": "active",
        "tenant_id": "<string>",
        "trial_end": "<string>",
        "trial_start": "<string>",
        "updated_at": "<string>",
        "updated_by": "<string>",
        "version": 123
      },
      "subscription_id": "<string>",
      "subtotal": 123,
      "taxes": [
        {
          "applied_at": "<string>",
          "created_at": "<string>",
          "created_by": "<string>",
          "currency": "<string>",
          "entity_id": "<string>",
          "entity_type": "customer",
          "environment_id": "<string>",
          "id": "<string>",
          "idempotency_key": "<string>",
          "metadata": {},
          "status": "published",
          "tax_amount": 123,
          "tax_association_id": "<string>",
          "tax_rate": {
            "code": "<string>",
            "created_at": "<string>",
            "created_by": "<string>",
            "description": "<string>",
            "environment_id": "<string>",
            "fixed_value": 123,
            "id": "<string>",
            "metadata": {},
            "name": "<string>",
            "percentage_value": 123,
            "scope": "INTERNAL",
            "status": "published",
            "tax_rate_status": "ACTIVE",
            "tax_rate_type": "percentage",
            "tenant_id": "<string>",
            "updated_at": "<string>",
            "updated_by": "<string>"
          },
          "tax_rate_id": "<string>",
          "taxable_amount": 123,
          "tenant_id": "<string>",
          "updated_at": "<string>",
          "updated_by": "<string>"
        }
      ],
      "tenant_id": "<string>",
      "total": 123,
      "total_discount": 123,
      "total_tax": 123,
      "updated_at": "<string>",
      "updated_by": "<string>",
      "version": 123,
      "voided_at": "<string>"
    }
  ],
  "pagination": {
    "limit": 123,
    "offset": 123,
    "total": 123
  }
}

Authorizations

​
x-api-key
string
header
required

Enter your API key in the format x-api-key <api-key>*

Body

application/json

Filter

​
amount_due_gt
number

amount_due_gt filters invoices with a total amount due greater than the specified value Useful for finding invoices above a certain threshold or identifying high-value invoices

​
amount_remaining_gt
number

amount_remaining_gt filters invoices with an outstanding balance greater than the specified value Useful for finding invoices that still have significant unpaid amounts

​
customer_id
string

customer_id filters invoices for a specific customer using FlexPrice's internal customer ID This is the ID returned by FlexPrice when creating or retrieving customers

​
end_time
string
​
expand
string
​
external_customer_id
string

external_customer_id filters invoices for a customer using your system's customer identifier This is the ID you provided when creating the customer in FlexPrice

​
filters
object[]
​
invoice_ids
string[]

invoice_ids restricts results to invoices with the specified IDs Use this to retrieve specific invoices when you know their exact identifiers

​
invoice_status
enum<string>[]

invoice_status filters by the current state of invoices in their lifecycle Multiple statuses can be specified to include invoices in any of the listed states

​
invoice_type
enum<string>
Available options:
SUBSCRIPTION,
ONE_OFF,
CREDIT
​
limit
integer
Required range: 1 <= x <= 1000
​
offset
integer
Required range: x >= 0
​
order
enum<string>
Available options:
asc,
desc
​
payment_status
enum<string>[]

payment_status filters by the payment state of invoices Multiple statuses can be specified to include invoices with any of the listed payment states

​
skip_line_items
boolean

SkipLineItems if true, will not include line items in the response

​
sort
object[]
​
start_time
string
​
status
enum<string>
Available options:
published,
deleted,
archived
​
subscription_id
string

subscription_id filters invoices generated for a specific subscription Only returns invoices that were created as part of the specified subscription's billing

Response

OK

​
items
object[]
​
pagination
object
⌘I