Invoices
Create a new invoice
Customers
Invoices
Wallets
Entitlements
Environments
Events
Features
Payments
Integrations
Subscriptions
Tenants
Users
Invoices
Create a new invoice
Create a new invoice with the provided details
POST
/
invoices
curl --request POST \
--url https://api.cloud.flexprice.io/v1/invoices \
--header 'Content-Type: application/json' \
--data '{
"amount_due": 123,
"amount_paid": 123,
"billing_period": "<string>",
"billing_reason": "SUBSCRIPTION_CREATE",
"currency": "<string>",
"customer_id": "<string>",
"description": "<string>",
"due_date": "<string>",
"environment_id": "<string>",
"idempotency_key": "<string>",
"invoice_number": "<string>",
"invoice_status": "DRAFT",
"invoice_type": "SUBSCRIPTION",
"line_items": [
{
"amount": 123,
"display_name": "<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>",
"quantity": 123
}
],
"metadata": {},
"payment_status": "PENDING",
"period_end": "<string>",
"period_start": "<string>",
"subscription_id": "<string>"
}'{
"amount_due": 123,
"amount_paid": 123,
"amount_remaining": 123,
"billing_period": "<string>",
"billing_reason": "<string>",
"billing_sequence": 123,
"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>",
"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>",
"quantity": 123,
"status": "<string>",
"subscription_id": "<string>",
"tenant_id": "<string>",
"updated_at": "<string>",
"updated_by": "<string>"
}
],
"metadata": {},
"paid_at": "<string>",
"payment_status": "PENDING",
"period_end": "<string>",
"period_start": "<string>",
"status": "<string>",
"subscription": {
"active_pause_id": "<string>",
"billing_anchor": "<string>",
"billing_cadence": "RECURRING",
"billing_period": "MONTHLY",
"billing_period_count": 123,
"cancel_at": "<string>",
"cancel_at_period_end": true,
"cancelled_at": "<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>",
"end_date": "<string>",
"environment_id": "<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>",
"environment_id": "<string>",
"id": "<string>",
"invoice_cadence": "ARREAR",
"metadata": {},
"meter_display_name": "<string>",
"meter_id": "<string>",
"plan_display_name": "<string>",
"plan_id": "<string>",
"price_id": "<string>",
"price_type": "USAGE",
"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": {},
"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>"
}
],
"plan": {
"created_at": "<string>",
"created_by": "<string>",
"description": "<string>",
"entitlements": [
{
"created_at": "<string>",
"created_by": "<string>",
"environment_id": "<string>",
"feature": {
"created_at": "<string>",
"created_by": "<string>",
"description": "<string>",
"environment_id": "<string>",
"id": "<string>",
"lookup_key": "<string>",
"metadata": {},
"meter": {
"aggregation": {
"field": "<string>",
"type": "COUNT"
},
"created_at": "2024-03-20T15:04:05Z",
"event_name": "api_request",
"filters": [
{
"key": "<string>",
"values": [
"<string>"
]
}
],
"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>",
"name": "<string>",
"prices": [
{
"amount": 123,
"billing_cadence": "RECURRING",
"billing_model": "FLAT_FEE",
"billing_period": "MONTHLY",
"billing_period_count": 123,
"created_at": "<string>",
"created_by": "<string>",
"currency": "<string>",
"description": "<string>",
"display_amount": "<string>",
"environment_id": "<string>",
"id": "<string>",
"invoice_cadence": "ARREAR",
"lookup_key": "<string>",
"metadata": {},
"meter": {
"aggregation": {
"field": "<string>",
"type": "COUNT"
},
"created_at": "2024-03-20T15:04:05Z",
"event_name": "api_request",
"filters": [
{
"key": "<string>",
"values": [
"<string>"
]
}
],
"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>",
"plan_id": "<string>",
"status": "published",
"tenant_id": "<string>",
"tier_mode": "VOLUME",
"tiers": [
{
"flat_amount": 123,
"unit_amount": 123,
"up_to": 123
}
],
"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>",
"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>",
"tenant_id": "<string>",
"updated_at": "<string>",
"updated_by": "<string>",
"version": 123,
"voided_at": "<string>"
}Body
application/json
Invoice details
Available options:
SUBSCRIPTION_CREATE, SUBSCRIPTION_CYCLE, SUBSCRIPTION_UPDATE, MANUAL Available options:
DRAFT, FINALIZED, VOIDED Available options:
SUBSCRIPTION, ONE_OFF, CREDIT Available options:
PENDING, PROCESSING, SUCCEEDED, FAILED, REFUNDED, PARTIALLY_REFUNDED Response
201
application/json
Created
AddressCity is the city of the customer's address
AddressCountry is the country of the customer's address (ISO 3166-1 alpha-2)
AddressLine1 is the first line of the customer's address
AddressLine2 is the second line of the customer's address
AddressPostalCode is the postal code of the customer's address
AddressState is the state of the customer's address
Email is the email of the customer
EnvironmentID is the environment identifier for the customer
ExternalID is the external identifier for the customer
ID is the unique identifier for the customer
Name is the name of the customer
Available options:
published, deleted, archived Available options:
DRAFT, FINALIZED, VOIDED Available options:
SUBSCRIPTION, ONE_OFF, CREDIT Available options:
PENDING, PROCESSING, SUCCEEDED, FAILED, REFUNDED, PARTIALLY_REFUNDED ActivePauseID references the current active pause configuration This will be null if no pause is active or scheduled
BillingAnchor is the reference point that aligns future billing cycle dates. It sets the day of week for week intervals, the day of month for month and year intervals, and the month of year for year intervals. The timestamp is in UTC format.
Available options:
RECURRING, ONETIME Available options:
MONTHLY, ANNUAL, WEEKLY, DAILY, QUARTERLY, HALF_YEARLY BillingPeriodCount is the total number units of the billing period.
CancelAt is the date the subscription will be canceled
CancelAtPeriodEnd is whether the subscription was canceled at the end of the current period
CanceledAt is the date the subscription was canceled
Currency is the currency of the subscription in lowercase 3 digit ISO codes
CurrentPeriodEnd is the end of the current period that the subscription has been invoiced for. At the end of this period, a new invoice will be created.
CurrentPeriodStart is the end of the current period that the subscription has been invoiced for. At the end of this period, a new invoice will be created.
AddressCity is the city of the customer's address
AddressCountry is the country of the customer's address (ISO 3166-1 alpha-2)
AddressLine1 is the first line of the customer's address
AddressLine2 is the second line of the customer's address
AddressPostalCode is the postal code of the customer's address
AddressState is the state of the customer's address
Email is the email of the customer
EnvironmentID is the environment identifier for the customer
ExternalID is the external identifier for the customer
ID is the unique identifier for the customer
Name is the name of the customer
Available options:
published, deleted, archived CustomerID is the identifier for the customer in our system
EndDate is the end date of the subscription
EnvironmentID is the environment identifier for the subscription
ID is the unique identifier for the subscription
Available options:
MONTHLY, ANNUAL, WEEKLY, DAILY, QUARTERLY, HALF_YEARLY Available options:
ARREAR, ADVANCE Available options:
USAGE, FIXED Available options:
published, deleted, archived LookupKey is the key used to lookup the subscription in our system
Available options:
none, active, scheduled, completed, cancelled EnvironmentID is the environment identifier for the pause
ID is the unique identifier for the subscription pause
OriginalPeriodEnd is the end of the billing period when the pause was created
OriginalPeriodStart is the start of the billing period when the pause was created
PauseEnd is when the pause will end (null for indefinite)
Available options:
immediate, scheduled, period_end PauseStart is when the pause actually started
Available options:
none, active, scheduled, completed, cancelled Reason is the reason for pausing
Available options:
immediate, scheduled, auto ResumedAt is when the pause was actually ended (if manually resumed)
Available options:
published, deleted, archived SubscriptionID is the identifier for the subscription
Available options:
published, deleted, archived Available options:
metered, boolean, static Available options:
metered, boolean, static Available options:
published, deleted, archived Available options:
published, deleted, archived Available options:
MONTHLY, ANNUAL, WEEKLY, DAILY, QUARTERLY, HALF_YEARLY Amount stored in main currency units (e.g., dollars, not cents) For USD: 12.50 means $12.50
Available options:
RECURRING, ONETIME Available options:
FLAT_FEE, PACKAGE, TIERED Available options:
MONTHLY, ANNUAL, WEEKLY, DAILY, QUARTERLY, HALF_YEARLY BillingPeriodCount is the count of the billing period ex 1, 3, 6, 12
Currency 3 digit ISO currency code in lowercase ex usd, eur, gbp
Description of the price
DisplayAmount is the formatted amount with currency symbol For USD: $12.50
EnvironmentID is the environment identifier for the price
ID uuid identifier for the price
Available options:
ARREAR, ADVANCE LookupKey used for looking up the price in the database
Example:
"2024-03-20T15:04:05Z"
Example:
"api_request"
Example:
"550e8400-e29b-41d4-a716-446655440000"
Example:
"API Usage Meter"
Available options:
BILLING_PERIOD, NEVER Example:
"published"
Example:
"tenant123"
Example:
"2024-03-20T15:04:05Z"
MeterID is the id of the meter for usage based pricing
PlanID is the id of the plan for plan based pricing
Available options:
published, deleted, archived Available options:
VOLUME, SLAB FlatAmount is the flat amount for the given tier and it is applied on top of the unit amount*quantity. It solves cases in banking like 2.7% + 5c
UnitAmount is the amount per unit for the given tier
Upto is the quantity up to which this tier applies. It is null for the last tier
TrialPeriod is the number of days for the trial period Note: This is only applicable for recurring prices (BILLING_CADENCE_RECURRING)
Available options:
USAGE, FIXED Available options:
published, deleted, archived PlanID is the identifier for the plan in our system
StartDate is the start date of the subscription
Available options:
published, deleted, archived Available options:
active, paused, cancelled, incomplete, incomplete_expired, past_due, trialing, unpaid TrialEnd is the end date of the trial period
TrialStart is the start date of the trial period
Version is used for optimistic locking
curl --request POST \
--url https://api.cloud.flexprice.io/v1/invoices \
--header 'Content-Type: application/json' \
--data '{
"amount_due": 123,
"amount_paid": 123,
"billing_period": "<string>",
"billing_reason": "SUBSCRIPTION_CREATE",
"currency": "<string>",
"customer_id": "<string>",
"description": "<string>",
"due_date": "<string>",
"environment_id": "<string>",
"idempotency_key": "<string>",
"invoice_number": "<string>",
"invoice_status": "DRAFT",
"invoice_type": "SUBSCRIPTION",
"line_items": [
{
"amount": 123,
"display_name": "<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>",
"quantity": 123
}
],
"metadata": {},
"payment_status": "PENDING",
"period_end": "<string>",
"period_start": "<string>",
"subscription_id": "<string>"
}'{
"amount_due": 123,
"amount_paid": 123,
"amount_remaining": 123,
"billing_period": "<string>",
"billing_reason": "<string>",
"billing_sequence": 123,
"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>",
"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>",
"quantity": 123,
"status": "<string>",
"subscription_id": "<string>",
"tenant_id": "<string>",
"updated_at": "<string>",
"updated_by": "<string>"
}
],
"metadata": {},
"paid_at": "<string>",
"payment_status": "PENDING",
"period_end": "<string>",
"period_start": "<string>",
"status": "<string>",
"subscription": {
"active_pause_id": "<string>",
"billing_anchor": "<string>",
"billing_cadence": "RECURRING",
"billing_period": "MONTHLY",
"billing_period_count": 123,
"cancel_at": "<string>",
"cancel_at_period_end": true,
"cancelled_at": "<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>",
"end_date": "<string>",
"environment_id": "<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>",
"environment_id": "<string>",
"id": "<string>",
"invoice_cadence": "ARREAR",
"metadata": {},
"meter_display_name": "<string>",
"meter_id": "<string>",
"plan_display_name": "<string>",
"plan_id": "<string>",
"price_id": "<string>",
"price_type": "USAGE",
"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": {},
"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>"
}
],
"plan": {
"created_at": "<string>",
"created_by": "<string>",
"description": "<string>",
"entitlements": [
{
"created_at": "<string>",
"created_by": "<string>",
"environment_id": "<string>",
"feature": {
"created_at": "<string>",
"created_by": "<string>",
"description": "<string>",
"environment_id": "<string>",
"id": "<string>",
"lookup_key": "<string>",
"metadata": {},
"meter": {
"aggregation": {
"field": "<string>",
"type": "COUNT"
},
"created_at": "2024-03-20T15:04:05Z",
"event_name": "api_request",
"filters": [
{
"key": "<string>",
"values": [
"<string>"
]
}
],
"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>",
"name": "<string>",
"prices": [
{
"amount": 123,
"billing_cadence": "RECURRING",
"billing_model": "FLAT_FEE",
"billing_period": "MONTHLY",
"billing_period_count": 123,
"created_at": "<string>",
"created_by": "<string>",
"currency": "<string>",
"description": "<string>",
"display_amount": "<string>",
"environment_id": "<string>",
"id": "<string>",
"invoice_cadence": "ARREAR",
"lookup_key": "<string>",
"metadata": {},
"meter": {
"aggregation": {
"field": "<string>",
"type": "COUNT"
},
"created_at": "2024-03-20T15:04:05Z",
"event_name": "api_request",
"filters": [
{
"key": "<string>",
"values": [
"<string>"
]
}
],
"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>",
"plan_id": "<string>",
"status": "published",
"tenant_id": "<string>",
"tier_mode": "VOLUME",
"tiers": [
{
"flat_amount": 123,
"unit_amount": 123,
"up_to": 123
}
],
"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>",
"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>",
"tenant_id": "<string>",
"updated_at": "<string>",
"updated_by": "<string>",
"version": 123,
"voided_at": "<string>"
}