Pushing a Sales Item Invoice through the API

One of the more common requests that we receive are centered around pushing data through the API and more specifically pushing invoices, the most common one being:

Do you have any examples of creating an invoice through the API? I wold like to use this example as a reference point for performing similar operations in my application.

So we have heeded that request and written a short and precise example/tutorial on doing just that in 3 simple steps. And gone a step further in writing up a page that will walk you through the common errors and the troubleshooting process for these errors.

What are we trying to do? THE SCENARIO

The scenario here is that we have a customer in our system who would like to buy 500 piñatas. In our program we need to create an invoice for this sale and push it into AccountRight via the API. We have broken down the process to achieving this into stages outlined below.

STEP 1: Setup

Assumptions

We will work under the assumptions that we already have the following in place and working

• The correct headers.
• Completed the OAuth2 process.
• You can make a successful get requests to the Invoices endpoint.

STEP 2: Creating Invoice

Scenario

So here is that scenario we briefly touched on earlier. So we have a customer, we will call him Thomas Dexter. Now Thomas Dexter has a big gathering coming up this weekend and he would like to make few purchases. He calls us, gives us his details and orders 500 piñatas. We need to raise an invoice for this sale.

JSON

The API takes in data in JSON format, so we need to write up a JSON payload with the details for the sale, that we will send to the invoice item endpoint.

Here is the JSON

{
    "Number": "SJ009392",
    "Date": "2015-09-25T19: 00: 59.043",
    "Customer": {
        "UID": "dd2088e1-92aa-42c5-9203-7060393839a3"
           },
   "PromisedDate" : "2013-09-30T19:00:59.043",
    "Lines": [
        {
            "Type" : "Transaction",
            "Description" : "Spider pinatas",
            "ShipQuantity": 500,
            "Total":10000,
            "Item": {
                "UID": "4e094c77-4c93-4bee-b75e-6cb23213bf7b"
            },
            "TaxCode": {
                "UID": "3bd2fbea-54d7-4115-8030-b84360048465"
              
            },
            "RowVersion": ""
        }
    ],
"ShipToAddress" : "Cash Sales",
"Terms" : {
"PaymentIsDue" : "DayOfMonthAfterEOM",
"DiscountDate" : 1,
"BalanceDueDate" : 30,
"DiscountForEarlyPayment" : 5,
"MonthlyChargeForLatePayment" : 0
    },
"IsTaxInclusive" : true,
"Freight" : 0,
"FreightTaxCode" : {
"UID" : "38a37ae8-565c-46f8-ad4a-2a87069607f8",
"Code" : "GST",
"URI" : "{domain}/{cf_guid}/GeneralLedger/TaxCode/38a37ae8-565c-46f8-ad4a-2a87069607f8"
},
}

STEP 3: POST

You will send your JSON using the http POST method to the /{guid}/Sale/Invoice/Item endpoint.

The URL that you would POST to would look something like this:

Working locally: http://localhost:8080/accountright/CF_GUID/Sale/Invoice/Item Working on the cloud: https://api.myob.com/accountright/CF_GUID/Sale/Invoice/Item

So you would have:

• Your headers
• Your payload (JSON)
• The url of the endpoint you are going to send it to which in our case is https://api.myob.com/accountright/CF_GUID/Sale/Invoice/Item

Once we have the above sorted we would then look to do this programmatically. Using the .Net SDK we are able to do this very easily. The code snippet in the section below emphasizes the simplicity of working with the SDK to push invoices through the API.

Simple POST Create New Invoice using .Net SDK Sample Program

The code below is a simple VB.net method which uses the SDK to push an invoice through the API. We have hard coded the invoice details in an effort to maintain simplicity. In order to get this up and running you need to use the sample program.

One of the many ways to get this working is as follows:

Ensure that you have replaced the necessary fields with your valid details. i.e.the, CUSTOMER_UID, TAX_CODE, FREIGHT_TAX_CODE with an existing customers' UID.

• Get the sample program up and running ensure the myob SDK nuget package is installed.
• Navigate to the InvoiceForm and add the method below in the InvoiceForm
• Call method using a control such a button or link. See results in your Companyfile

The code below can be placed anywhere as long as the correct namespaces have been imported. The method is called and it creates an invoice, the details are hard-coded for illustrative purposes.

Private Sub create_new_invoice()
 
'Create new invoice of type sale/item
        Dim invoiceItemSvc = New Sale.ItemInvoiceService(myConfiguration, Nothing, myOAuthKeyService)
        Dim ItemInvoice = New Version2.Sale.ItemInvoice()
        Dim customerLnk = New Version2.Contact.CustomerLink()
        Dim customerGuid As New Guid("CUSTOMER_UID") 'Ensure UID is of existing customer
 
'Add selected customer to invoice, add invoice number and date
        customerLnk.UID = customerGuid
        ItemInvoice.Customer = customerLnk
        ItemInvoice.Number = "SJ003392" 'Must Be Unique
        ItemInvoice.Date = "2015-09-25T19: 00: 59.043"
 
'Create list of invoice lines
        Dim Lines = New List(Of Version2.Sale.ItemInvoiceLine)
 
'Add line details
        Dim line = New Version2.Sale.ItemInvoiceLine
        line.Type = Version2.Sale.InvoiceLineType.Transaction
        line.ShipQuantity = 2
        line.Total = 51213135
 
'Add item to invoice using the item Guid
        Dim itemGuid As New System.Guid("YOUR_ITEM's GUID")
        Dim itemLnk = New Version2.Inventory.ItemLink
        itemLnk.UID = itemGuid
       line.Item = itemLnk
 
'Specify tax code using tax code Guid
        Dim taxcodelnk = New Version2.GeneralLedger.TaxCodeLink
        Dim taxCodeGuid As New System.Guid("YOUR_TAX_CODE_GUID")
        taxcodelnk.UID = taxCodeGuid
        line.TaxCode = taxcodelnk
 
'Add all line details to list of invoice line 
        Lines.Add(line)
 
'Add invoice lines to invoice     
        ItemInvoice.Lines = Lines
 
'Push new invoice details through to cf using insert method from the invoiceItemSvc
        invoiceItemSvc.Insert(myCompanyFile, ItemInvoice, myCredentials, AddressOf onSaveComplete, AddressOf OnError)
 
End Sub
  

The same logic is used for creating a ""Service Invoice" via the SDK making only minor changes to the "Services" and "Contracts" you use, fields such a "Ship Quantity" and "Total" can be omitted in that situation.
We have also taken into account other ways you could do this without using the SDK with PHP and VB.net

Common Pitfalls and How to Avoid them.

The first couple of times that you create new data and push it through the API you will probably be faced with a few errors here and there. Initially we had planned on highlighting the common pitfalls specifically related to creating an invoice, however, we have found that these issues are more or less universal issues that you may face when executing the POST method through the API.