Skip to main content
POST
/
invoices
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

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Payload to create invoice

​
accountId
string
required
Example:

"ACC001"

​
startDate
string<date-time>
required
Example:

"2020-06-04T12:00:00.000Z"

​
endDate
string<date-time>
required
Example:

"2020-07-04T12:00:00.000Z"

​
status
enum<string>
required

Status to create an invoice in.

Available options:
DRAFT,
DUE,
PAID
Example:

"DUE"

​
lineItems
object[]
required
Required array length: 1 - 50 elements
​
ownerType
enum<string>
Available options:
ACCOUNT,
INVOICE_GROUP
​
idempotencyKey
string
Example:

"1234567890"

​
autoAdvance
boolean

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

​
applyCredits
boolean

This property defines the behaviour of whether or not to use credits to net off with the invoice amount. Default: true

​
applyWalletBalance
boolean

This property defines the behaviour of whether or not to use wallet amount to net off with the invoice amount. Default: true

Response

Response for Get invoice requests

Structure of invoice

​
id
string
required

Identifier of invoice

Maximum length: 50
​
status
enum<string>
required

Status of the invoice

Available options:
DRAFT,
DUE,
PAID,
VOID,
UN_COLLECTIBLE,
REFUND_INITIATED,
REFUND_COMPLETED,
MERGED,
PARTIALLY_PAID
​
invoiceClass
enum<string>
required

Represents the class of entity( INVOICE/ORDER/BILLABLE)

Available options:
INVOICE,
ORDER,
BILLABLE
​
invoiceType
enum<string>
required

Represents the type of entity(STANDARD/AD_HOC/COMPOSITE)

Available options:
STANDARD,
AD_HOC,
CUSTOM,
COMPOSITE,
STANDARD_ADVANCED,
ADHOC_ADVANCED
​
invoiceDate
string<date-time>
required

Invoice date of the invoice

Example:

"2020-07-04T12:00:00.000Z"

​
updatedAt
string<date-time>
required
​
totalAmount
number
required
​
paidAmount
number
required
​
netTermDays
integer
required

Number of days from the invoice date after which an invoice is considered overdue.

​
customerId
string
​
ownerId
string
​
pricePlanId
string
​
usageInfo
object[]
​
revenueInfo
object
​
invoiceDetails
object
​
finalizingStatus
enum<string>
Available options:
FINALIZING,
FINALIZED
​
autoAdvance
boolean
Example:

true

​
startDate
string<date-time>

Start date of the invoice

Example:

"2020-07-04T12:00:00.000Z"

​
endDate
string<date-time>

End date of the invoice

Example:

"2020-07-04T12:00:00.000Z"

​
endDateInclusive
string<date-time>

Inclusive end date of the invoice

Example:

"2020-07-03T11:59:59.999Z"

​
dueDate
string<date-time>

Due date of the invoice

Example:

"2020-07-04T12:00:00.000Z"

​
generatedAt
string<date-time>
​
metadata
object
​
info
object[]
​
sequenceId
string

Sequence id of the invoice

​
pdfUrl
string

Download URL of the pdf file corresponding to the invoice