Nook API

Many of the core concepts of Nook will be familiar to anyone who has worked with accounting software such as Xero. But one core difference stems from the fact that Nook also offers a shared ledger where both supplier and customer can collaborate and manage the lifecycle of orders, invoices and credit notes.

Below we will introduce the Nook nomenclature and flows

Types

• Order
• Invoice
• CreditNote
• OverPayment
• PrePayment

Together these types are classed as trades which share a number of common attributes such as customer, supplier, line items, total, ...

Versioning

Both orders and invoices can be versioned in Nook. You can make changes (see draft changes below) and we will update the order or invoice but keep a copy of the previous version, as well as track who and when each new version was created.

In the case of invoices if the total value of the invoice decreases then Nook will automatically create a credit note to cover the difference. You cannot increase the total value of an invoice. But you can change, references, due dates.

Changes to the account codes, tax rates or tracking categories are also possible without needing to update the version

Over and Prepayments

You can not directly create these objects. If you wish to pay an Order this will create a prepayment object.

In a scenario where an invoice is overpaid you can create an overpayment that other invoices can be allocated.

Perspective

Each type can be viewed from one of two perspectives

• Customer
• Supplier

Both the customer and the supplier will have visibility of common attributes such as total, invoice number. But each perspective also has attributes only it can view and update such as tax_rate, account and subtotals. Importantly this means while both perspectives see the same total, they are not required to set the same tax rate and therefore can have different subtotals.

States

States define what actions are available to both customer and supplier and if an invoice is visible to one or both perspectives. All trades must start as drafts and can be created by either customer (Purchase) or supplier (Sale), so the starting states are

• DraftPurchaseInvoice
• DraftSaleInvoice
• DraftPurchaseOrder
• DraftSaleOrder
• DraftPurchaseCreditNote
• DraftSaleCreditNote

eventually these trades become

• Invoice
• Order
• CreditNote

Any subsequent major changes that impact both perspectives require a change request. Minor changes such as tax rate, account, or tracking category do not require a change request.

The state can be broken down into four parts

• is it a draft - Optional[Draft]
• perspective - Optional[Purchase, Sale]
• change request - Optional[ChangeRequest]
• type - [Invoice, Order, CreditNote, OverPayment, PrePayment]

There are currently a few exceptions, e.g. cancelled which results from cancelling and order and void which results from voiding and invoice.

Only trades that in the states Invoice, Order, CreditNote can be paid (or in the case of credit notes allocated to a payment with invoices).

See Figure 1 & 2 to see more of the permitted states and the transitions between them

Actions

Actions move trades from one state to another. For example drafts can be either deleted or submitted. The primary actions are

• Submit
• Accept
• DraftChange
• Reject
• Void

See Figure 1 & 2 to see actions

Single sided ledger vs shared ledger

Uniquely Nook offers a shared ledger. By default, all trades are configured to use the singled sided ledger. However, if both supplier and customer are verified and connected on Nook then they can also use the shared ledger. This can be enabled in on a per company basis in the network section.

Single sided ledger

In this case all trades created will not be visible to the other perspective and will not be pushed to their accounting ledger. If the other party is also using Nook then they will need to create a separate trade to represent the same invoice, order or credit note. If you still share invoices by PDF and email then this is the flow to use.

In the single sided case all request states will be bypassed and where configured Nook will send out PDF documents to the other perspective.

Shared ledger

In this case all trades that are not drafts will be visible to both supplier and customer. After submitting any type of trade the other perspective must accept it. For example a DraftSaleInvoice created by the supplier will move to SaleInvoiceRequest when submitted and the customer must accept this before it becomes an Invoice that can be paid.

If you are still emailing PDFs to the customer then be careful of using the shared ledger as the customer could upload the PDF and create a duplicate.

Network

The Nook network servers the same role as Xero Contacts, of Quickbooks Suppliers and Customers. However, it also goes further, we identify companies on a global company registry. So where two companies trade with the same third company we can identify that on the network, whether that third company is also using Nook or not, see Figure 3. Companies have one of four states

Verified

this means they have completed Nooks know your business complaince checks and verified their bank accounts

Registered

the company has signed up to Nook but not completed the verification process. You will not see these companies on the network until they complete verification, but if a user is a member of one of these companies they will see them in the manage companies page. These companies cannot use the API

Known

In the web application this appears as Identified. These companies have been identified on a global company registry but they are not using Nook. This helps Nook provide the necessary information to meet our compliance requirements for payments.

Unknown

In the web application this appears as Imported. These companies have typically been created on accounting software and imported but not yet identified. They may also represent individuals or sole traders who are not currently part of the network.

_ Figure 1: life cycle of orders and invoices. The diagram shows the actions that update states. Green action indicate flows for the shared ledger where the customer or supplier must approve new invoices and order, and changes. In this example we also show the versioning that takes place for orders and invoices. Each time a change takes place or we issue the order to invoice the version updates

_ Figure 2: life cycle of a credit note

_ Figure 3: the left hand side the typical database model where company A and B both share company C as a contact. On the right is the Nook network which is a directed graph. Company A can access global information from the company C node, it can also access private information about C from the edge of the graph where A is the parent