# Invoices

The invoices endpoint url is:

https://skhokho.io/api/v1.0/invoices

# Invoice GET Request

Invoices GET request will fetch a list of invoices associated with the company of the user who is currently authenticated. The structure of the list will be:

[
  {
    "title": "Finish Building the Proof of Concept",
    "description": "This is going to be an amazing project as discussed.",
    "notes": "Please make payment in to ABSA account - 12345678. Branch Code: 345 563.",
    "status": "CREATED",
    "taxPercentage": "15%",
    "recurringMonthly": false,
    "recurringDate": null,
    "dueDate": "2022-11-24",
    "totalBeforeTax": "33402.00",
    "taxAmount": "5010.30",
    "totalAfterTax": "38412.30",
    "client": {
        "id": 17,
        "companyName": "Construction Lorem",
        "companyEmail": "aryastark70@gmail.com",
        "companyPhone": "078432495",
        "companyTaxNumber": "128373747",
        "companyWebsite": "https://skhokho.io",
        "companySize": "Medium Sized",
        "companyIndustry": "Construction",
        "addressLine1": "1 Church Streeet",
        "city": "Johannesburg",
        "state": "Gauteng",
        "country": "South Africa",
        "postalCode": "2122",
        "twitter": "",
        "facebook": "",
        "linkedIn": "",
        "uniqueId": "xxxxxxxxx"
    },
    "items": [
        {
            "id": 1050,
            "title": "Weekly Meeting Costs",
            "price": "3567",
            "quantity": 4,
            "total": "14268.00",
            "uniqueId": "xxxxxxxxx"
        },
        {
            "id": 1051,
            "title": "Monthly Meeting Costs",
            "price": "9567",
            "quantity": 2,
            "total": "19134.00",
            "uniqueId": "xxxxxxxxx"
        }
    ],
    "uniqueId": "xxxxxxxxx"
}
    . . . . . // Other Results
]

When you request invoice records, you also get the client record associated with that invoice and the line items which build up the invoice.

# Invoices POST Request

When you want to create a new invoice record, you can send a POST request to the invoices end-point.

When creating an invoice, you will also need to specify the client associated with that invoice. There are two options for adding a client to the invoice:

Specify a name of an existing client
Supply enough information to create a new client record

# Invoice Payload Example with existing Client Record:

{
  "title": "A new Invoice Title",
  "description": "This is going to be an amazing project as discussed.",
  "notes": "Please make payment in to ABSA account - 12345678. Branch Code: 345 563.",
  "status": "CREATED",
  "taxPercentage": "15%",
  "recurringMonthly": false,
  "recurringDate": null,
  "dueDate": "2022-11-24",
  "client": {
      "companyName": "Existing Client Name",
    }
}

Field	Required/Optional	Json Key	Data Type	Format
Title of Invoice	Required	title	string
Description of Invoice	Optional	description	string
Additional	Optional	notes	string
Status	Required	type	string/**fixed_options
Tax Percentage	Required	taxPercentage	string	10%
Recurring Invoice	Optional	recurringMonthly	boolean	true/false
Recurring Date	Optional	recurringDate	integer	21
Invoice due Date	Required	dueDate	string	YYYY-MM-DD
Client	Required	client	json object	See Client API

# Reccuring Invoice

If you would like to add a recurring invoice, update the following variables from the payload:

{
  "recurringMonthly": true,
  "recurringDate": 23,
}

Change recurring monthly to True, and add an integer to represent which day of the month the invoice should recur.

** Invoice type fixed options

[
  'CREATED',
  'EMAILED',
  'PAID',
  'OVERDUE',
]

# Invoice Payload Example with New Client Record:

{
  "title": "A new Invoice Title",
  "description": "This is going to be an amazing project as discussed.",
  "notes": "Please make payment in to ABSA account - 12345678. Branch Code: 345 563.",
  "status": "CREATED",
  "taxPercentage": "15%",
  "recurringMonthly": false,
  "recurringDate": null,
  "dueDate": "2022-11-24",
  "client": {
    "companyName": "Construction Lorem",
    "companyEmail": "aryastark70@gmail.com",
    "companyPhone": "+27 67 221 8834",
    "companyTaxNumber": "128373747",
    "companyWebsite": "https://skhokho.io",
    "companySize": "Medium Sized",
    "companyIndustry": "Construction",
    "addressLine1": "1 Church Streeet",
    "city": "Johannesburg",
    "state": "Gauteng",
    "country": "South Africa",
    "postalCode": "2122",
    "twitter": "https://twitter.com",
    "facebook": "https://facebook.com",
    "linkedIn": "https://linkedin.com"
    }
}

TIP

See Client API to get the full data structure of the Client Object. Some of the fields are Fixed Options fields with set options to choose from like a drop-down menu.

# Invoice Line Items

The Invoice line items are specified in a separate POST request. A valid invoice must be created before adding line items. Note - new line items can be added to existing invoices.

TIP

To add an invoice line item, the uniqueID of the invoice is required. That can be obtained from the GET request results.

To add line items, the following end-point should be used:

https://skhokho.io/api/v1.0/invoice-items

This end-point only accepts POST requests. POST request Payload:

{
    "uniqueId": "xxxxxxxxx",
    "items": [
        {
            "title": "Weekly Meeting Costs",
            "price": "3567.12",
            "quantity": 4
        },
        {
            "title": "Monthly Meeting Costs",
            "price": "9567.12",
            "quantity": 2
        }
    ]
}

The Payload must contain:

The uniqueId of the Invoice
A list of items. The list can include just one item if required.

The ITEM object structure is:

Field	Required/Optional	Json Key	Data Type	Format
Tile of Item	Required	title	string
Price of Item	Required	price	string	345.12
Quantity of Items	Required	quantity	integer

← Quotes Vendors →