Introduction
APIs
- Authentication
- Customers
- Accounts
- Aliases
- Event Schemas
- Usage Meters
- AddOns
- Licenses
- Feature
- (Deprecated) Price Plans
- Price Plan V2
- Settings
- Price Experimentation
- Jobs
- Event Ingestion
- Entitlements
- Event Management
- Metrics
- Credits
- Invoices
- GETList invoices
- GETGet an invoice
- GETList pricing rule logs
- PUTAdd or update miscellaneous charges in Invoice
- PUTAdd or update miscellaneous charges in upcoming Invoice for a account
- POSTCreate a custom invoice for an account
- DELDelete a custom invoice in DRAFT state
- GETList invoices eligible for bill run
- POSTCreate a bill run job request
- GET
- Payments
- Wallet
- InvoiceGroups
- Alerts
- Reports
Create a custom invoice for an account
Create a custom invoice for an account.
curl --request POST \
--url https://api.togai.com/invoices \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"accountId": "ACC001",
"startDate": "2020-06-04T12:00:00.000Z",
"endDate": "2020-07-04T12:00:00.000Z",
"idempotencyKey": "1234567890",
"status": "DRAFT",
"lineItems": [
{
"description": "Payout IMPS",
"valuePerQuantity": 0.001,
"quantity": 32109
}
]
}'
{
"id": "inv.hkgkgyh.ghg",
"sequenceId": "2020-07-2958",
"customerId": "7VcRw9xZDIqsC5E",
"ownerId": "ACC001",
"usageInfo": [
{
"description": "rides - local",
"type": "USAGE_METER_USAGE",
"value": 15,
"units": "USAGE_UNITS"
},
{
"description": "rides - pro",
"type": "USAGE_METER_USAGE",
"value": 5,
"units": "USAGE_UNITS"
}
],
"revenueInfo": {
"description": "Grand Total Amount",
"type": "GRAND_TOTAL_AMOUNT",
"units": "USD",
"value": 881.94,
"lineItems": [
{
"description": "Total Amount",
"type": "TOTAL_AMOUNT",
"units": "USD",
"value": 881.94,
"lineItems": [
{
"description": "Total amount due",
"type": "NET_AMOUNT",
"units": "USD",
"value": 881.94,
"lineItems": [
{
"description": "Sum Total",
"type": "GROSS_AMOUNT",
"units": "USD",
"value": 981.94,
"lineItems": [
{
"description": "Payout_NEFT",
"type": "USAGE_RATE_CARD_AMOUNT",
"units": "USD",
"value": 392.1,
"lineItems": [
{
"description": "Slab 1",
"type": "USAGE_RATE_CARD_SLAB_AMOUNT",
"valuePerQuantity": 0.001,
"quantity": 10000,
"units": "USD",
"value": 10
},
{
"description": "Slab 2",
"type": "USAGE_RATE_CARD_SLAB_AMOUNT",
"valuePerQuantity": 0.001,
"quantity": 10000,
"units": "USD",
"value": 10
}
]
},
{
"description": "Payout IMPS",
"type": "USAGE_RATE_CARD_AMOUNT",
"valuePerQuantity": 0.001,
"quantity": 32109,
"units": "USD",
"value": 589.94,
"lineItems": [
{
"description": "Slab 1",
"type": "USAGE_RATE_CARD_SLAB_AMOUNT",
"valuePerQuantity": 0.001,
"quantity": 10000,
"units": "USD",
"value": 10
},
{
"description": "Slab 2",
"type": "USAGE_RATE_CARD_SLAB_AMOUNT",
"valuePerQuantity": 0.001,
"quantity": 10000,
"units": "USD",
"value": 10
}
]
}
]
}
]
}
]
}
]
},
"invoiceDetails": {
"customer": {
"name": "John Doe",
"primaryEmail": "john@togai.com",
"address": {
"line1": "2281 Broadway Street",
"line2": "G-31",
"postalCode": "29501",
"city": "Florence",
"state": "South Carolina",
"country": "US"
}
},
"account": {
"name": "Togai",
"address": {
"line1": "2281 Broadway Street",
"line2": "G-31",
"postalCode": "29501",
"city": "Florence",
"state": "South Carolina",
"country": "US"
},
"primaryEmail": "john@togai.com",
"invoiceCurrency": "USD"
},
"pricePlanName": "Togai Basic"
},
"totalAmount": 881.94,
"paidAmount": 0,
"invoiceClass": "INVOICE",
"invoiceType": "STANDARD",
"status": "DUE",
"finalizingStatus": "FINALIZED",
"startDate": "2020-07-04T12:00:00.000Z",
"endDate": "2020-08-04T12:00:00.000Z",
"invoiceDate": "2020-08-04T12:00:00.000Z",
"generatedAt": "2020-08-04T12:00:00.000Z",
"updatedAt": "2020-08-04T12:00:00.000Z"
}
Authorizations
Bearer authentication header of the form Bearer <token>
, where <token>
is your auth token.
Body
"ACC001"
"2020-06-04T12:00:00.000Z"
"2020-07-04T12:00:00.000Z"
Status to create an invoice in.
DRAFT
, DUE
, PAID
"DUE"
Custom line item. Either value
or quantity
+ valuePerQuantity
is required.
In case quantity
and valuePerQuantity
are provided, value
is computed as (quantity
X valuePerQuantity
)
ACCOUNT
, INVOICE_GROUP
"1234567890"
This property defines the behaviour of status transition of the invoice.
If true, invoice auto transitions from DRAFT
to DUE
or PAID
at the end of pricing cycle.
If false, the invoice’s state doesn’t automatically advance without an explicit action.
Default: false
This property defines the behaviour of whether or not to use credits to net off with the invoice amount. Default: true
This property defines the behaviour of whether or not to use wallet amount to net off with the invoice amount. Default: true
Response
Structure of invoice
Identifier of invoice
50
Status of the invoice
DRAFT
, DUE
, PAID
, VOID
, UN_COLLECTIBLE
, REFUND_INITIATED
, REFUND_COMPLETED
, MERGED
, PARTIALLY_PAID
Represents the class of entity( INVOICE/ORDER/BILLABLE)
INVOICE
, ORDER
, BILLABLE
Represents the type of entity(STANDARD/AD_HOC/COMPOSITE)
STANDARD
, AD_HOC
, CUSTOM
, COMPOSITE
, STANDARD_ADVANCED
, ADHOC_ADVANCED
Invoice date of the invoice
"2020-07-04T12:00:00.000Z"
Number of days from the invoice date after which an invoice is considered overdue.
Type of the line item
- GRAND_TOTAL_AMOUNT: Sum of all total amount of individual invoices in a grouped(composite) invoice
- TOTAL_AMOUNT: Total revenue of the invoice
- NET_AMOUNT: Net revenue of the invoice ( Gross revenue - Discounts )
- GROSS_AMOUNT: Gross revenue of the invoice
- PRICE_PLAN_AMOUNT: SUB_TOTAL_AMOUNT + true up amount
- SUB_TOTAL_AMOUNT: Sum of all rate card revenues
- TRUE_UP_AMOUNT: Minimum commitment - SUB_TOTAL_AMOUNT (Always positive)
- TOTAL_USAGE: List of all the usage meter usages
- USAGE_METER_USAGE: Usage of an usage meter
- USAGE_RATE_CARD_AMOUNT: Revenue generated from usage rate card
- USAGE_RATE_CARD_SLAB_AMOUNT: Revenue generated from usage rate card slab
- FIXED_FEE_RATE_CARD_AMOUNT: Revenue generated from fixed fee rate card
- CREDIT_GRANT_RATE_CARD_AMOUNT: : Revenue generated from credit grant rate card
- BILLING_ENTITLEMENT_RATE_CARD_AMOUNT: Revenue generated from billing entitlement rate card
- ENTITLEMENT_OVERAGE_RATE_CARD_AMOUNT: : Revenue generated from entitlement overage rate card
- ENTITLEMENT_OVERAGE_RATE_CARD_SLAB_AMOUNT: Revenue generated from entitlement overage rate card slab
- LICENSE_RATE_CARD_AMOUNT: Revenue generated from license rate card
- TOTAL_CREDITS: Sum of all credit amounts
- SUB_CREDITS: Granted credit value
- TOTAL_ADVANCED_FEES: Sum of all advanced fee revenue
- ADVANCED_FIXED_FEE: Revenue generated from advanced fixed fee rate card
- ADVANCED_LICENSE_RATE_CARD_AMOUNT: Revenue generated from advanced license rate card
- ADVANCED_BILLING_ENTITLEMENT_RATE_CARD_AMOUNT: Revenue generated from advanced billing entitlement rate card
- ADVANCED_CREDIT_GRANT_RATE_CARD_AMOUNT: Revenue generated from advanced credit grant rate card
- TOTAL_MISCELLANEOUS_CHARGES: Net revenue of all MISCELLANEOUS_CHARGE
- MISCELLANEOUS_CHARGE: Custom amount added to a DRAFT invoice
- TOTAL_PURCHASE_AMOUNT: Net revenue all rate cards in a purchase plan
- CUSTOM_AMOUNT: Custom amount added a DRAFT invoice
- CUSTOM_TAG: User defined tags given to each rate card
- TOTAL_PRICING_RULE_ADDITION_AMOUNT: Sum of all line items added by applying pricing rules
- PRICING_RULE_ADDITION_AMOUNT: Amount added to invoice as a result of applying a pricing rule
- PRICING_RULE_REVENUE_UPDATE_AMOUNT: Difference in revenue(value) obtained as a result of applying a pricing rule
- PRICING_RULE_USAGE_UPDATE_AMOUNT: Difference in usage(quantity) obtained as a result of applying a pricing rule
- RATE_CONFIG_ADJUSTMENT_AMOUNT: Difference in revenue obtained as a result of applying rate config['minimumRate', 'maximumRate'] at rate card level
TOTAL_USAGE
, USAGE_METER_USAGE
, GRAND_TOTAL_AMOUNT
, TOTAL_AMOUNT
, NET_AMOUNT
, GROSS_AMOUNT
, SUB_TOTAL_AMOUNT
, PRICE_PLAN_AMOUNT
, FIXED_FEE_RATE_CARD_AMOUNT
, CREDIT_GRANT_RATE_CARD_AMOUNT
, BILLING_ENTITLEMENT_RATE_CARD_AMOUNT
, ENTITLEMENT_OVERAGE_RATE_CARD_AMOUNT
, ENTITLEMENT_OVERAGE_RATE_CARD_SLAB_AMOUNT
, LICENSE_RATE_CARD_AMOUNT
, USAGE_CYCLE_AMOUNT
, LICENSE_RATE_CARD_SLAB_AMOUNT
, USAGE_RATE_CARD_AMOUNT
, USAGE_RATE_CARD_SLAB_AMOUNT
, TOTAL_CREDITS
, SUB_CREDITS
, TOTAL_ADVANCED_FEES
, ADVANCED_FIXED_FEE
, ADVANCED_LICENSE_RATE_CARD_AMOUNT
, ADVANCED_BILLING_ENTITLEMENT_RATE_CARD_AMOUNT
, ADVANCED_CREDIT_GRANT_RATE_CARD_AMOUNT
, TOTAL_MISCELLANEOUS_CHARGES
, MISCELLANEOUS_CHARGE
, TRUE_UP_AMOUNT
, TOTAL_PURCHASE_AMOUNT
, CUSTOM_AMOUNT
, CUSTOM_TAG
, TOTAL_PRICING_RULE_ADDITION_AMOUNT
, PRICING_RULE_ADDITION_AMOUNT
, PRICING_RULE_REVENUE_UPDATE_AMOUNT
, PRICING_RULE_USAGE_UPDATE_AMOUNT
, RATE_CONFIG_ADJUSTMENT_AMOUNT
, TOTAL_TAX_AMOUNT
, TAX_AMOUNT
, PROXY_AMOUNT
Type of the line item
- GRAND_TOTAL_AMOUNT: Sum of all total amount of individual invoices in a grouped(composite) invoice
- TOTAL_AMOUNT: Total revenue of the invoice
- NET_AMOUNT: Net revenue of the invoice ( Gross revenue - Discounts )
- GROSS_AMOUNT: Gross revenue of the invoice
- PRICE_PLAN_AMOUNT: SUB_TOTAL_AMOUNT + true up amount
- SUB_TOTAL_AMOUNT: Sum of all rate card revenues
- TRUE_UP_AMOUNT: Minimum commitment - SUB_TOTAL_AMOUNT (Always positive)
- TOTAL_USAGE: List of all the usage meter usages
- USAGE_METER_USAGE: Usage of an usage meter
- USAGE_RATE_CARD_AMOUNT: Revenue generated from usage rate card
- USAGE_RATE_CARD_SLAB_AMOUNT: Revenue generated from usage rate card slab
- FIXED_FEE_RATE_CARD_AMOUNT: Revenue generated from fixed fee rate card
- CREDIT_GRANT_RATE_CARD_AMOUNT: : Revenue generated from credit grant rate card
- BILLING_ENTITLEMENT_RATE_CARD_AMOUNT: Revenue generated from billing entitlement rate card
- ENTITLEMENT_OVERAGE_RATE_CARD_AMOUNT: : Revenue generated from entitlement overage rate card
- ENTITLEMENT_OVERAGE_RATE_CARD_SLAB_AMOUNT: Revenue generated from entitlement overage rate card slab
- LICENSE_RATE_CARD_AMOUNT: Revenue generated from license rate card
- TOTAL_CREDITS: Sum of all credit amounts
- SUB_CREDITS: Granted credit value
- TOTAL_ADVANCED_FEES: Sum of all advanced fee revenue
- ADVANCED_FIXED_FEE: Revenue generated from advanced fixed fee rate card
- ADVANCED_LICENSE_RATE_CARD_AMOUNT: Revenue generated from advanced license rate card
- ADVANCED_BILLING_ENTITLEMENT_RATE_CARD_AMOUNT: Revenue generated from advanced billing entitlement rate card
- ADVANCED_CREDIT_GRANT_RATE_CARD_AMOUNT: Revenue generated from advanced credit grant rate card
- TOTAL_MISCELLANEOUS_CHARGES: Net revenue of all MISCELLANEOUS_CHARGE
- MISCELLANEOUS_CHARGE: Custom amount added to a DRAFT invoice
- TOTAL_PURCHASE_AMOUNT: Net revenue all rate cards in a purchase plan
- CUSTOM_AMOUNT: Custom amount added a DRAFT invoice
- CUSTOM_TAG: User defined tags given to each rate card
- TOTAL_PRICING_RULE_ADDITION_AMOUNT: Sum of all line items added by applying pricing rules
- PRICING_RULE_ADDITION_AMOUNT: Amount added to invoice as a result of applying a pricing rule
- PRICING_RULE_REVENUE_UPDATE_AMOUNT: Difference in revenue(value) obtained as a result of applying a pricing rule
- PRICING_RULE_USAGE_UPDATE_AMOUNT: Difference in usage(quantity) obtained as a result of applying a pricing rule
- RATE_CONFIG_ADJUSTMENT_AMOUNT: Difference in revenue obtained as a result of applying rate config['minimumRate', 'maximumRate'] at rate card level
TOTAL_USAGE
, USAGE_METER_USAGE
, GRAND_TOTAL_AMOUNT
, TOTAL_AMOUNT
, NET_AMOUNT
, GROSS_AMOUNT
, SUB_TOTAL_AMOUNT
, PRICE_PLAN_AMOUNT
, FIXED_FEE_RATE_CARD_AMOUNT
, CREDIT_GRANT_RATE_CARD_AMOUNT
, BILLING_ENTITLEMENT_RATE_CARD_AMOUNT
, ENTITLEMENT_OVERAGE_RATE_CARD_AMOUNT
, ENTITLEMENT_OVERAGE_RATE_CARD_SLAB_AMOUNT
, LICENSE_RATE_CARD_AMOUNT
, USAGE_CYCLE_AMOUNT
, LICENSE_RATE_CARD_SLAB_AMOUNT
, USAGE_RATE_CARD_AMOUNT
, USAGE_RATE_CARD_SLAB_AMOUNT
, TOTAL_CREDITS
, SUB_CREDITS
, TOTAL_ADVANCED_FEES
, ADVANCED_FIXED_FEE
, ADVANCED_LICENSE_RATE_CARD_AMOUNT
, ADVANCED_BILLING_ENTITLEMENT_RATE_CARD_AMOUNT
, ADVANCED_CREDIT_GRANT_RATE_CARD_AMOUNT
, TOTAL_MISCELLANEOUS_CHARGES
, MISCELLANEOUS_CHARGE
, TRUE_UP_AMOUNT
, TOTAL_PURCHASE_AMOUNT
, CUSTOM_AMOUNT
, CUSTOM_TAG
, TOTAL_PRICING_RULE_ADDITION_AMOUNT
, PRICING_RULE_ADDITION_AMOUNT
, PRICING_RULE_REVENUE_UPDATE_AMOUNT
, PRICING_RULE_USAGE_UPDATE_AMOUNT
, RATE_CONFIG_ADJUSTMENT_AMOUNT
, TOTAL_TAX_AMOUNT
, TAX_AMOUNT
, PROXY_AMOUNT
billing address of the customer
Contact number
Address line 1 (eg. Street, PO Box, Company Name)
Address line 2 (eg. apartment, suite, unit or building)
ZIP or postal code
City, district, suburb, town or village
State, county, province or region
Two letter country code ISO-3166-1 Alpha-2
billing address of the customer
Contact number
Address line 1 (eg. Street, PO Box, Company Name)
Address line 2 (eg. apartment, suite, unit or building)
ZIP or postal code
City, district, suburb, town or village
State, county, province or region
Two letter country code ISO-3166-1 Alpha-2
billing address of the customer
Contact number
Address line 1 (eg. Street, PO Box, Company Name)
Address line 2 (eg. apartment, suite, unit or building)
ZIP or postal code
City, district, suburb, town or village
State, county, province or region
Two letter country code ISO-3166-1 Alpha-2
billing address of the customer
Contact number
Address line 1 (eg. Street, PO Box, Company Name)
Address line 2 (eg. apartment, suite, unit or building)
ZIP or postal code
City, district, suburb, town or village
State, county, province or region
Two letter country code ISO-3166-1 Alpha-2
FINALIZING
, FINALIZED
true
Start date of the invoice
"2020-07-04T12:00:00.000Z"
End date of the invoice
"2020-07-04T12:00:00.000Z"
Inclusive end date of the invoice
"2020-07-03T11:59:59.999Z"
Due date of the invoice
"2020-07-04T12:00:00.000Z"
Sequence id of the invoice
Download URL of the pdf file corresponding to the invoice
curl --request POST \
--url https://api.togai.com/invoices \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"accountId": "ACC001",
"startDate": "2020-06-04T12:00:00.000Z",
"endDate": "2020-07-04T12:00:00.000Z",
"idempotencyKey": "1234567890",
"status": "DRAFT",
"lineItems": [
{
"description": "Payout IMPS",
"valuePerQuantity": 0.001,
"quantity": 32109
}
]
}'
{
"id": "inv.hkgkgyh.ghg",
"sequenceId": "2020-07-2958",
"customerId": "7VcRw9xZDIqsC5E",
"ownerId": "ACC001",
"usageInfo": [
{
"description": "rides - local",
"type": "USAGE_METER_USAGE",
"value": 15,
"units": "USAGE_UNITS"
},
{
"description": "rides - pro",
"type": "USAGE_METER_USAGE",
"value": 5,
"units": "USAGE_UNITS"
}
],
"revenueInfo": {
"description": "Grand Total Amount",
"type": "GRAND_TOTAL_AMOUNT",
"units": "USD",
"value": 881.94,
"lineItems": [
{
"description": "Total Amount",
"type": "TOTAL_AMOUNT",
"units": "USD",
"value": 881.94,
"lineItems": [
{
"description": "Total amount due",
"type": "NET_AMOUNT",
"units": "USD",
"value": 881.94,
"lineItems": [
{
"description": "Sum Total",
"type": "GROSS_AMOUNT",
"units": "USD",
"value": 981.94,
"lineItems": [
{
"description": "Payout_NEFT",
"type": "USAGE_RATE_CARD_AMOUNT",
"units": "USD",
"value": 392.1,
"lineItems": [
{
"description": "Slab 1",
"type": "USAGE_RATE_CARD_SLAB_AMOUNT",
"valuePerQuantity": 0.001,
"quantity": 10000,
"units": "USD",
"value": 10
},
{
"description": "Slab 2",
"type": "USAGE_RATE_CARD_SLAB_AMOUNT",
"valuePerQuantity": 0.001,
"quantity": 10000,
"units": "USD",
"value": 10
}
]
},
{
"description": "Payout IMPS",
"type": "USAGE_RATE_CARD_AMOUNT",
"valuePerQuantity": 0.001,
"quantity": 32109,
"units": "USD",
"value": 589.94,
"lineItems": [
{
"description": "Slab 1",
"type": "USAGE_RATE_CARD_SLAB_AMOUNT",
"valuePerQuantity": 0.001,
"quantity": 10000,
"units": "USD",
"value": 10
},
{
"description": "Slab 2",
"type": "USAGE_RATE_CARD_SLAB_AMOUNT",
"valuePerQuantity": 0.001,
"quantity": 10000,
"units": "USD",
"value": 10
}
]
}
]
}
]
}
]
}
]
},
"invoiceDetails": {
"customer": {
"name": "John Doe",
"primaryEmail": "john@togai.com",
"address": {
"line1": "2281 Broadway Street",
"line2": "G-31",
"postalCode": "29501",
"city": "Florence",
"state": "South Carolina",
"country": "US"
}
},
"account": {
"name": "Togai",
"address": {
"line1": "2281 Broadway Street",
"line2": "G-31",
"postalCode": "29501",
"city": "Florence",
"state": "South Carolina",
"country": "US"
},
"primaryEmail": "john@togai.com",
"invoiceCurrency": "USD"
},
"pricePlanName": "Togai Basic"
},
"totalAmount": 881.94,
"paidAmount": 0,
"invoiceClass": "INVOICE",
"invoiceType": "STANDARD",
"status": "DUE",
"finalizingStatus": "FINALIZED",
"startDate": "2020-07-04T12:00:00.000Z",
"endDate": "2020-08-04T12:00:00.000Z",
"invoiceDate": "2020-08-04T12:00:00.000Z",
"generatedAt": "2020-08-04T12:00:00.000Z",
"updatedAt": "2020-08-04T12:00:00.000Z"
}