Orders API

Object name

 Orders

Overview

URL	https://unify.webgility.com/api/api/orders
Methods Supported	POST
Description	Allows you to post orders to an Accounting System

Object Description

Orders is a collection of sale transactions of products or services from a seller to a buyer at agreed price and quantity.

Request Format

As request parameter, the details of order(s) that need to be posted to an Accounting System should be sent in JSON format.

Field	Type	Description	Required?
OrderId	string	Unique identifier for order for the purposes of API call	Yes
OrderDate	datetime	Date the order was placed	Yes
Customer	reference type	Customer Information. See below for the layout of customer details	Some fields are mandatory. See below for details
BillingAddress	reference type	Address associated with the payment. See below for the layout of billing address	Some fields are mandatory. See below for details
ShippingAddress	reference type	Address for the shipment. See below for the layout of shipping address	Node is mandatory though all fields are optional
OrderItems	reference type	Order line items. See below for the layout of items	Some fields are mandatory. See below for details
ShipmentStatus	string	UNSHIPPED, PARTIALLY_SHIPPED, SHIPPED. Optional. Will be used in future for additional transaction options.	No
ShipmentMethod	string	Shipment Method selected for delivery of items	No
ShipmentCarrier	string	Shipping carrier selected for delivery of items	No
ShippingCharges	double	Total shipping charges will be recorded against a specific shipping item as specified by end-user.	No
ShipmentCost	double	Optional. Will be used in future to record shipping expenses	No
TotalDiscounts	double	Total discount will be recorded against a specific discount item as specified by end-user	No
TotalTax	double	Total taxes will be recorded against a specific tax item item as specified by end-user	No
TotalAmount	string	Total charges of the sale transaction	Yes
PaymentStatus	string	PENDING, PAID	Yes
PaymentMethod	string	Payment method for the order. CHECK, CREDITCARD, PAYPAL, OTHER. Optional. Will be used in future for additional transaction options.	Yes
PaymentNotes	string	Optional. String containing details of payment such as payment id, last 4 of card, card type, etc.	No
Notes	string	Optional Order Notes	No
Currency	string	USD. Default is USD and no other currencies supported currently.	No

The Customer field: Customer gives details of the customer and has following properties:

Field Name	Type	Description	Required
FirstName	string	First name of customer (max length = 255)	Yes
LastName	string	Last Name of customer (max length = 255)	Yes
CompanyName	string	Name of customer organisation (max length = 500)	No
EmailAddress	string	Email address of contact person (umlauts not supported) (max length = 500)	No

The BillingAddress field: BillingAddress is an optional field and gives the details of billing address of the customer. It has following properties:

Field Name	Type	Description	Required
FirstName	string	First name for billing address	Yes
LastName	string	Last name for billing address	Yes
AddressLine1	string	AddressLine1	No
AddressLine2	string	AddressLine2	No
AddressLine3	string	AddressLine3	No
AddressLine4	string	AddressLine4	No
City	string	City	No
Region	string	Region	No
PostalCode	string	PostalCode	No
Country	string	Country	No

The ShippingAddress field: ShippingAddress is an optional field and gives the details of shipping address of the customer. It has following properties:

Field Name	Type	Description	Required
FirstName	string	First name for shipping address	No
LastName	string	Last name for shipping address	No
AddressLine1	string	AddressLine1	No
AddressLine2	string	AddressLine2	No
AddressLine3	string	AddressLine3	No
AddressLine4	string	AddressLine4	No
City	string	City	No
Region	string	Region	No
PostalCode	string	PostalCode	No
Country	string	Country	No

The OrderItems field: OrderItems lists details of all the line items for the order. It is an array of items, each with the following properties:

Field Name	Type	Description	Required
SKU	string	Stock Keeping Unit - identifier for the Item	No
Name	string	Item name	Yes
Description	string	Item description	Yes
UnitPrice	double	Unit sale price of the item	Yes
UnitCost	double	Unit purchase price of the item. Optional. Used when creating a new item in Accounting System.	No
Quantity	double	Quantity of the item sold	Yes
Taxable	boolean	Indicates whether the item is Taxable or not	Yes

Response Format

API response returns the details of accounting transaction for all the orders in a JSON formatted string. The provided response fields are:

Field Name	Type	Description
OrderId	string	Unique identifier for order
Transactions	reference type	Details of transactions that are created in Accounting System. See below for the layout of Transactions
Customer	reference type	Details of customer(s) sent in POST request. See below for the layout of Customers
Items	reference type	Details of items sent in POST request. See below for the layout of Items
ResponseAt	datetime	UTC timestamp when the response is sent by the server

The Transactions field: Transactions lists all the transactions that are created in Accounting System and has following properties:

Field Name	Type	Description
TransactionId	string	Unique identifier for the transaction created
TransactionNumber	integer	Number/Code identifying the transaction
Type	string	Type of transaction created in the Accounting System. Valid values: Invoice, SalesReceipt, Payment, CreditMemo
UpdatedAt	datetime	UTC timestamp of last update to transaction
CreatedAt	datetime	UTC timestamp of created date of transaction

The Customer field: Customer gives details of all the customers that are sent in POST request to Accounting System and has following properties:

Field Name	Type	Description
CustomerId	string	Identifier of the customer sent in POST request
FirstName	string	First name of customer (max length = 255)
LastName	string	Last Name of customer (max length = 255)
CompanyName	string	Name of customer organisation (max length = 500)
CustomerStatus	string	Customer status. Valid values = MATCHED, CREATED

The Items field: Items gives details of all the items that are sent in POST request to Accounting System and has following properties:

Field Name	Type	Description
SKU	string	SKU of the item sent in POST request that is a unique identifier
Name	string	Name of the item sent in POST request
ItemId	integer	Identifer of the item in Accounting
ItemStatus	string	MATCHED, MAPPED, CREATED

Available API Interaction

Post Orders

The API interaction is used to post one of more orders to an Accounting System.

Request

 POST unify.webgility.com/api/api/orders

Sample Request

 {
  "Orders": {
    "OrderId": "1010",
    "OrderDate": "2014-08-20",
    "Customer": {
      "FirstName": "Dan",
      "LastName": "Scheffler",
      "CompanyName": "ABC Corp.",
      "EmailAddress": "dans@abc.com"
    },
    "BillingAddress": {
      "FirstName": "Webgility",
      "LastName": "Inc",
      "AddressLine1": "2703 Town Center Lane",
      "AddressLine2": "Add2",
      "AddressLine3": "Add3",
      "AddressLine4": "Add4",
      "City": "Sunnyvale",
      "Region": "South",
      "PostalCode": "940862",
      "Country": "US"
    },
    "ShippingAddress": {
      "FirstName": "Dan",
      "LastName": "Scheffler",
      "AddressLine1": "511 Willson Lane",
      "AddressLine2": "Add2",
      "AddressLine3": "Add3",
      "AddressLine4": "AAA",
      "City": "Franklin",
      "Region": "Central",
      "PostalCode": "85061",
      "Country": "US"
    },
    "OrderItems": [
      {
        "SKU": "Book1",
        "Name": "Novel Book 1",
        "Description": "Qwertyuiop",
        "UnitPrice": 10,
        "UnitCost": 5,
        "Quantity": 1,
        "Taxable": false
      },
      {
        "SKU": "Book2",
        "Name": "Tech Book 2",
        "Description": "WE22222",
        "UnitPrice": 10,
        "UnitCost": 5,
        "Quantity": 1,
        "Taxable": false
      }
    ],
    "ShipmentStatus": "Shipped",
    "ShipmentMethod": "FedEx",
    "ShipmentCarrier": "Overnight",
    "ShippingCharges": 10,
    "ShippingCost": 10,
    "TotalDiscounts": 5,
    "TotalTax": 5,
    "TotalAmount": 30,
    "PaymentStatus": "Paid",
    "PaymentMethod": "Check",
    "PaymentNotes": "My Payment",
    "Notes": "My Notes",
    "Currency": "USD"
  }
 }

Sample Response

 HTTP/1.1 200 OK
  
  {
    "Orders": {
       "OrderId": "123",
       "Transactions": {
          "TransactionId": "69",
          "TransactionNumber": "INV-0042",
          "Type": "Invoice",
          "UpdatedAt": "2013-12-26T01:04:21.707",
          "CreatedAt": "2009-05-14T01:44:26.747"
          },
      "Customer": {
         "CustomerId": "1",
         "FirstName": "John",
         "LastName": "Williams",
         "CompanyName": "ABC Pvt Ltd",
         "CustomerStatus": "CREATED"
          },
       "Items": [
         {
          "SKU": "19",
          "Name": "Merino-2011-L",
          "ItemId": "238",
          "ItemStatus": "CREATED"
          },
         {
          "SKU": "20",
          "Name": "Merino-2012",
          "ItemId": "241",
          "ItemStatus": "CREATED"
          }
         ],
      "ResponseAt": "2014-02-28T16:15:14.261",
       }
  } 

Sample PHP Code

 <?php
 $url = 'https://unify.webgility.com/api/api/Orders';
 $Token='ZWNjLndlYmdpbGl0eS5jb218YTQ5NGE2NTYxNjkxZGNhOTEyZGY5MWVjOTViNjg0ZGV8cHJhZ2F0aXIrdGVzdDgxMUB3ZWJnaWxpdHkuY29tfDQxNjUzfDE6';
 $data = '{xxxxxxxxxxxxxxx}'; //JSON string
 $ch = curl_init();
 curl_setopt($ch, CURLOPT_URL,$url);
 curl_setopt($ch, CURLOPT_TIMEOUT, 30000); //timeout after 30 seconds
 curl_setopt($ch, CURLOPT_RETURNTRANSFER,1);
 curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
 curl_setopt($ch, CURLOPT_USERPWD, $Token);
 curl_setopt($ch, CURLOPT_POSTFIELDS,$data);
 curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
 curl_setopt($ch, CURLOPT_HTTPHEADER, array(
 'Content-Type: application/json',
 'Token: ' . $Token
 ));
 $status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);   //get status code
 $result=curl_exec ($ch);
 curl_close ($ch);
 ?>