Top

Purchase Order

List purchase orders
GET /purchaseorders
List all purchase orders.
Get a purchase order
GET /purchaseorders/:purchaseorder_id
Get the details of a purchase order.
Create a purchase order
POST /purchaseorders
Create a purchase order for your vendor.
Update a purchase order
PUT /purchaseorders/:purchase_order_id
Update an existing purchase order.
Delete purchase order
DELETE /purchaseorders/:purchaseorder_id
Delete an existing purchase order.
Mark a purchase order as open
POST /purchaseorders/:purchaseorder_id/status/open
Mark a draft purchase order as open.
Mark as billed
POST /purchaseorders/:purchaseorder_id/status/billed
Mark a purchase order as billed.
Cancel a purchase order
POST /purchaseorders/:purchaseorder_id/status/cancelled
Mark a purchase order as cancelled.
Email a purchase order
POST /purchaseorders/:purchaseorder_id/email
Email a purchase order to the vendor. Input json string is not mandatory. If input json string is empty, mail will be send with default mail content.
Get purchase order email content
GET /purchaseorders/:purchaseorder_id/email
Get the email content of a purchase order.
Update billing address
PUT /purchaseorders/:purchaseorder_id/address/billing
Updates the billing address for this purchase order alone.
List purchase order templates
GET /purchaseorders/templates
Get all purchase order pdf templates.
Update purchase order template
PUT /purchaseorders/:purchaseorder_id/templates/:template_id
Update the pdf template associated with the purchase order.

List purchase orders

GET  /purchaseorders

List all purchase orders.

Parameters

purchaseorder_number string [100] Search purchase order by purchase order number.
Variants: purchaseorder_number.startswith and purchaseorder_number.contains
reference_number string [100] Search purchase order by reference number.
Variants: reference_number.startswith and reference_number.contains
date string
[yyyy-mm-dd]
Search purchase order by purchase order date.
Variants: date.start, date.end, date.before and date.after
status string Search purchase order by purchase order status.
Allowed Values: draft, open, billed and cancelled
item_description string
[100]
Search purchase order by purchase order item description.
Variants: item_description.startswith and item_description.contains
vendor_name string [100] Search purchase order by vendor name.
Variants: vendor_name.startswith and vendor_name.contains
total double Search purchase order by purchase order total.
Variants: total.start, total.end, total.less_than, total.less_equals, total.greater_than and total.greater_equals
vendor_id string Search purchase order by vendor id.
last_modified_time string
[100]
Search purchase order by last modified time.
item_id string Search purchase order by item id.
filter_by string Filter purchase order by any status.
Allowed Values: Status.All, Status.Draft, Status.Open, Status.Billed and Status.Cancelled
search_text string
[100]
Search purchase order by purchase order number or reference number or vendor name.
sort_column string Sort purchase orders.
Allowed Values: vendor_name, purchaseorder_number, date, delivery_date, total and created_time

Sample Response

Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "success",
  "purchaseorders": [
    {
      "purchaseorder_id": "460000000074007",
      "vendor_id": "460000000026049",
      "vendor_name": "Bowman and Co",
      "status": "draft",
      "purchaseorder_number": "PO-00001",
      "reference_number": "ER/0034",
      "date": "2014-02-10",
      "delivery_date": "2014-02-10",
      "currency_id": "460000000000097",
      "currency_code": "USD",
      "price_precision": 2,
      "total": 112.00,
      "created_time": "2014-02-10T10:23:05+0530",
      "last_modified_time": "2014-02-10T21:43:45+0530"
    }
  ],
  "page_context": {
    "page": 1,
    "per_page": 200,
    "has_more_page": false,
    "report_name": "Purchase Orders",
    "applied_filter": "Status.All",
    "sort_column": "created_time",
    "sort_order": "D"
  }
}

Get a purchase order

GET  /purchaseorders/:purchaseorder_id

Get the details of a purchase order.

Parameters

print boolean Print the exported pdf.
accept string [100] Get the details of a particular purchase order in formats such as json/ pdf/ html. Default format is json.
Allowed Values: json, pdf and html

Sample Response

Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "success",
  "purchaseorder": {
    "purchaseorder_id": "460000000074007",
    "purchaseorder_number": "PO-00001",
    "date": "2014-02-10",
    "expected_delivery_date": "",
    "reference_number": "ER/0034",
    "status": "draft",
    "vendor_id": "460000000026049",
    "vendor_name": "Bowman and Co",
    "contact_persons": [
      "460000000026051"
    ],
    "currency_id": "460000000000097",
    "currency_code": "USD",
    "currency_symbol": "$",
    "exchange_rate": 1.00,
    "delivery_date": "2014-02-10",
    "is_emailed": false,
    "is_inclusive_tax": "false",
    "line_items": [
      {
        "item_id": "460000000027009",
        "line_item_id": "460000000074009",
        "account_id": "460000000074003",
        "name": "Hard Drive",
        "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.",
        "item_order": 0,
        "bcy_rate": 112.00,
        "rate": 112.00,
        "quantity": 1.00,
        "unit": "Nos",
        "item_total": 112.00
      }
    ],
    "sub_total": 112.00,
    "total": 112.00,
    "price_precision": 2,
    "billing_address": {
      "address": "4900 Hopyard Rd, Suite 310",
      "city": "Pleasanton",
      "state": "CA",
      "zip": "94588",
      "country": "USA",
      "fax": "+1-925-924-9600"
    },
    "notes": "Please deliver as soon as possible.",
    "terms": "Thanks for your business.",
    "ship_via": "",
    "attention": "John Smith",
    "delivery_address": {
      "zip": "78759",
      "phone": "",
      "address": "9390 Research Blvd,Bldg II, Suite 440",
      "delivery_org_address_id": "",
      "state": "Texas",
      "country": "U.S.A",
      "city": "Austin"
    },
    "custom_fields": [
      {
        "index": 1,
        "show_on_pdf": false,
        "value": "Normal",
        "label": "Priority"
      }
    ],
    "attachment_name": "7.png",
    "can_send_in_mail": true,
    "template_id": "460000000011003",
    "template_name": "Standard Template",
    "created_time": "2014-02-10T10:23:05+0530",
    "last_modified_time": "2014-02-10T21:43:45+0530"
  }
}

Create a purchase order

POST  /purchaseorders

Create a purchase order for your vendor.

Parameters

attachment file Allowed Extensions: gif, png, jpeg, jpg, bmp, pdf, xls, xlsx, doc and docx
ignore_auto_number_generation boolean Ignore auto purchase order number generation for this purchase order. This mandates the purchase order number.

Request attributes

vendor_id* string ID of the vendor the purchase order has to be created.
contact_persons array Array of contact person(s) for whom purchase order has to be sent.
purchaseorder_number string
[50]
Mandatory if auto number generation is disabled.
reference_number string
[50]
Reference number of purchase order.
template_id string ID of the pdf template associated with the purchase order.
date string
[yyyy-mm-dd]
The date the purchase order is created.
due_date string
[yyyy-mm-dd]
Delivery date of purchase order.
exchange_rate double Exchange rate of the currency.
is_inclusive_tax
(Not applicable for US edition)
boolean Used to specify whether the line item rates are inclusive or exclusive of tax.
vat_treatment
(UK Edition only)
string (Optional) VAT treatment for the purchase order. VAT treatment denotes the location of the vendor, if the vendor resides in UK then the VAT treatment is uk. If the vendor is in an EU country & if he is VAT registered then his VAT treatment is eu_vat_registered, if he resides in EU & if he is not VAT registered then his VAT treatment is eu_vat_not_registered and if he resides outside the EU then his VAT treatment is non_eu.
line_items* array Line items of purchase order.
line_item_id string ID of the line item. Mandatory if the existing line item has to be updated. If empty, a new line item will be created.
item_id string ID of the item.
account_id string ID of the account, the line item is associated with.
name string
[100]
Name of the line item.
description string
[2000]
Description of the line item.
unit string
[100]
Unit of the line item e.g. kgs, Nos.
rate double Rate of the line item.
quantity string
[100]
Quantity of the line item.
acquisition_vat_id
(UK Edition only)
string (Optional) This is the ID of the tax applied in case this is an EU - goods purchase and acquisition VAT needs to be reported.
reverse_charge_vat_id
(UK Edition only)
string (Optional) This is the ID of the tax applied in case this is a non UK - service purchase and reverse charge VAT needs to be reported.
custom_fields array Custom fields for purchase order.
notes string
[2000]
Delivery note for vendor.
ship_via string
[500]
Shipment Preference
delivery_address hash Delivery address of purchase order.
organization_address_id string ID of organization address.
attention string
[100]
Delivery contact person.

Sample Request

{
      "vendor_id": "460000000026049",
      "contact_persons": [
        "460000000026051"
      ],
      "purchaseorder_number": "PO-00001",
      "reference_number": "ER/0034",
      "template_id": "460000000011003",
      "date": "2014-02-10",
      "due_date": "",
      "exchange_rate": 1.00,
      "is_inclusive_tax": "false",
      "line_items": [
        {
          "line_item_id": "460000000074009",
          "item_id": "460000000027009",
          "account_id": "460000000074003",
          "name": "Hard Drive",
          "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.",
          "unit": "Nos",
          "rate": 112.00,
          "quantity": 1.00,
          "item_order": 0
        }
      ],
      "custom_fields": [
        {
          "index": 1,
          "value": "Normal"
        }
      ],
      "notes": "Please deliver as soon as possible.",
      "notes_default": "",
      "terms": "Thanks for your business.",
      "terms_default": "",
      "ship_via": "",
      "delivery_address": {
        "organization_address_id": "",
        "attention": ""
      }
    }

Sample Response

Status: 201 Created
Content Type: application/json;charset=UTF-8
{
      "code": 0,
      "message": "Purchase Order added successfully.",
      "purchaseorder": {
        "purchaseorder_id": "460000000074007",
        "purchaseorder_number": "PO-00001",
        "date": "2014-02-10",
        "expected_delivery_date": "",
        "reference_number": "ER/0034",
        "status": "draft",
        "vendor_id": "460000000026049",
        "vendor_name": "Bowman and Co",
        "contact_persons": [
          "460000000026051"
        ],
        "currency_id": "460000000000097",
        "currency_code": "USD",
        "currency_symbol": "$",
        "exchange_rate": 1.00,
        "delivery_date": "2014-02-10",
        "is_emailed": false,
        "is_inclusive_tax": "false",
        "line_items": [
          {
            "item_id": "460000000027009",
            "line_item_id": "460000000074009",
            "account_id": "460000000074003",
            "name": "Hard Drive",
            "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.",
            "item_order": 0,
            "bcy_rate": 112.00,
            "rate": 112.00,
            "quantity": 1.00,
            "unit": "Nos",
            "item_total": 112.00
          }
        ],
        "sub_total": 112.00,
        "total": 112.00,
        "price_precision": 2,
        "billing_address": {
          "address": "4900 Hopyard Rd, Suite 310",
          "city": "Pleasanton",
          "state": "CA",
          "zip": "94588",
          "country": "USA",
          "fax": "+1-925-924-9600"
        },
        "notes": "Please deliver as soon as possible.",
        "terms": "Thanks for your business.",
        "ship_via": "",
        "attention": "John Smith",
        "delivery_address": {
          "zip": "78759",
          "phone": "",
          "address": "9390 Research Blvd,Bldg II, Suite 440",
          "delivery_org_address_id": "",
          "state": "Texas",
          "country": "U.S.A",
          "city": "Austin"
        },
        "custom_fields": [
          {
            "index": 1,
            "show_on_pdf": false,
            "value": "Normal",
            "label": "Priority"
          }
        ],
        "attachment_name": "7.png",
        "can_send_in_mail": true,
        "template_id": "460000000011003",
        "template_name": "Standard Template",
        "created_time": "2014-02-10T10:23:05+0530",
        "last_modified_time": "2014-02-10T21:43:45+0530"
      }
    }

Update a purchase order

PUT  /purchaseorders/:purchase_order_id

Update an existing purchase order.

Parameters

attachment file Allowed Extensions: gif, png, jpeg, jpg, bmp, pdf, xls, xlsx, doc and docx
ignore_auto_number_generation boolean Ignore auto purchase order number generation for this purchase order. This mandates the purchase order number.

Request attributes

vendor_id* string ID of the vendor the purchase order has to be created.
contact_persons array Array of contact person(s) for whom purchase order has to be sent.
purchaseorder_number string
[50]
Mandatory if auto number generation is disabled.
reference_number string
[50]
Reference number of purchase order.
template_id string ID of the pdf template associated with the purchase order.
date string
[yyyy-mm-dd]
The date the purchase order is created.
due_date string
[yyyy-mm-dd]
Delivery date of purchase order.
exchange_rate double Exchange rate of the currency.
is_inclusive_tax
(Not applicable for US edition)
boolean Used to specify whether the line item rates are inclusive or exclusive of tax.
vat_treatment
(UK Edition only)
string (Optional) VAT treatment for the purchase order. VAT treatment denotes the location of the vendor, if the vendor resides in UK then the VAT treatment is uk. If the vendor is in an EU country & if he is VAT registered then his VAT treatment is eu_vat_registered, if he resides in EU & if he is not VAT registered then his VAT treatment is eu_vat_not_registered and if he resides outside the EU then his VAT treatment is non_eu.
line_items* array Line items of purchase order.
line_item_id string ID of the line item. Mandatory if the existing line item has to be updated. If empty, a new line item will be created.
item_id string ID of the item.
account_id string ID of the account, the line item is associated with.
name string
[100]
Name of the line item.
description string
[2000]
Description of the line item.
unit string
[100]
Unit of the line item e.g. kgs, Nos.
rate double Rate of the line item.
quantity string
[100]
Quantity of the line item.
acquisition_vat_id
(UK Edition only)
string (Optional) This is the ID of the tax applied in case this is an EU - goods purchase and acquisition VAT needs to be reported.
reverse_charge_vat_id
(UK Edition only)
string (Optional) This is the ID of the tax applied in case this is a non UK - service purchase and reverse charge VAT needs to be reported.
custom_fields array Custom fields for purchase order.
notes string
[2000]
Delivery note for vendor.
ship_via string
[500]
Shipment Preference
delivery_address hash Delivery address of purchase order.
organization_address_id string ID of organization address.
attention string
[100]
Delivery contact person.

Sample Request

{
      "vendor_id": "460000000026049",
      "contact_persons": [
        "460000000026051"
      ],
      "purchaseorder_number": "PO-00001",
      "reference_number": "ER/0034",
      "template_id": "460000000011003",
      "date": "2014-02-10",
      "due_date": "",
      "exchange_rate": 1.00,
      "is_inclusive_tax": "false",
      "line_items": [
        {
          "line_item_id": "460000000074009",
          "item_id": "460000000027009",
          "account_id": "460000000074003",
          "name": "Hard Drive",
          "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.",
          "unit": "Nos",
          "rate": 112.00,
          "quantity": 1.00,
          "item_order": 0
        }
      ],
      "custom_fields": [
        {
          "index": 1,
          "value": "Normal"
        }
      ],
      "notes": "Please deliver as soon as possible.",
      "notes_default": "",
      "terms": "Thanks for your business.",
      "terms_default": "",
      "ship_via": "",
      "delivery_address": {
        "organization_address_id": "",
        "attention": ""
      }
    }

Sample Response

Status: 200 OK
Content Type: application/json;charset=UTF-8
{
      "code": 0,
      "message": "Purchase Order updated successfully.",
      "purchaseorder": {
        "purchaseorder_id": "460000000074007",
        "purchaseorder_number": "PO-00001",
        "date": "2014-02-10",
        "expected_delivery_date": "",
        "reference_number": "ER/0034",
        "status": "draft",
        "vendor_id": "460000000026049",
        "vendor_name": "Bowman and Co",
        "contact_persons": [
          "460000000026051"
        ],
        "currency_id": "460000000000097",
        "currency_code": "USD",
        "currency_symbol": "$",
        "exchange_rate": 1.00,
        "delivery_date": "2014-02-10",
        "is_emailed": false,
        "is_inclusive_tax": "false",
        "line_items": [
          {
            "item_id": "460000000027009",
            "line_item_id": "460000000074009",
            "account_id": "460000000074003",
            "name": "Hard Drive",
            "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.",
            "item_order": 0,
            "bcy_rate": 112.00,
            "rate": 112.00,
            "quantity": 1.00,
            "unit": "Nos",
            "item_total": 112.00
          }
        ],
        "sub_total": 112.00,
        "total": 112.00,
        "price_precision": 2,
        "billing_address": {
          "address": "4900 Hopyard Rd, Suite 310",
          "city": "Pleasanton",
          "state": "CA",
          "zip": "94588",
          "country": "USA",
          "fax": "+1-925-924-9600"
        },
        "notes": "Please deliver as soon as possible.",
        "terms": "Thanks for your business.",
        "ship_via": "",
        "attention": "John Smith",
        "delivery_address": {
          "zip": "78759",
          "phone": "",
          "address": "9390 Research Blvd,Bldg II, Suite 440",
          "delivery_org_address_id": "",
          "state": "Texas",
          "country": "U.S.A",
          "city": "Austin"
        },
        "custom_fields": [
          {
            "index": 1,
            "show_on_pdf": false,
            "value": "Normal",
            "label": "Priority"
          }
        ],
        "attachment_name": "7.png",
        "can_send_in_mail": true,
        "template_id": "460000000011003",
        "template_name": "Standard Template",
        "created_time": "2014-02-10T10:23:05+0530",
        "last_modified_time": "2014-02-10T21:43:45+0530"
      }
    }

Delete purchase order

DELETE  /purchaseorders/:purchaseorder_id

Delete an existing purchase order.

Sample Response

Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "The purchase order has been deleted."
}

Mark a purchase order as open

POST  /purchaseorders/:purchaseorder_id/status/open

Mark a draft purchase order as open.

Sample Response

Status: 200 OK
Content Type: application/json;charset=UTF-8
{
      "code": 0,
      "message": "The purchase order has been marked as open."
    }

Mark as billed

POST  /purchaseorders/:purchaseorder_id/status/billed

Mark a purchase order as billed.

Sample Response

Status: 200 OK
Content Type: application/json;charset=UTF-8
{
      "code": 0,
      "message": "The purchase order has been marked as billed."
    }

Cancel a purchase order

POST  /purchaseorders/:purchaseorder_id/status/cancelled

Mark a purchase order as cancelled.

Sample Response

Status: 200 OK
Content Type: application/json;charset=UTF-8
{
      "code": 0,
      "message": "The purchase order has been cancelled."
    }

Email a purchase order

POST  /purchaseorders/:purchaseorder_id/email

Email a purchase order to the vendor. Input json string is not mandatory. If input json string is empty, mail will be send with default mail content.

Parameters

attachments file The files to be attached with the email.
send_attachment boolean Send the purchase order attachment a with the email.
file_name string
[100]
Name of the file.

Request attributes

send_from_org_email_id boolean Boolean to trigger the email from the organization's email address.
to_mail_ids* array Array of email address of the recipients.
cc_mail_ids array Array of email address of the recipients to be cced.
body* string
[5000]
Body of the mail.

Sample Request

{
      "send_from_org_email_id": "true",
      "to_mail_ids": [
        "willsmith@bowmanfurniture.com"
      ],
      "cc_mail_ids": [
        "peterparker@bowmanfurniture.com"
      ],
      "subject": "Purchase Order from Zillium Inc (PO #: PO-00001)",
      "body": "Dear Bowman and Co, <br><br>The purchase order (PO-00001) is attached with this email. <br><br>An overview of the purchase order is available below: <br>Purchase Order # : PO-00001 <br>Date : 10 Feb 2014 <br>Amount : $112.00(in USD) <br><br>Please go through it and confirm the order. We look forward to working with you again<br><br><br><br>Regards<br><br>Zillium Inc<br><br>"
    }

Sample Response

Status: 200 OK
Content Type: application/json;charset=UTF-8
{
      "code": 0,
      "message": "Your purchase order has been sent."
    }

Get purchase order email content

GET  /purchaseorders/:purchaseorder_id/email

Get the email content of a purchase order.

Parameters

email_template_id string Get the email content based on a specific email template. If this param is not inputted, then the content will be based on the email template associated with the customer. If no template is associated with the customer, then default template will be used.

Sample Response

Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "success",
  "data": {
    "body": "Dear Bowman and Co, <br><br>The purchase order (PO-00001) is attached with this email. <br><br>An overview of the purchase order is available below: <br>Purchase Order # : PO-00001 <br>Date : 10 Feb 2014 <br>Amount : $112.00(in USD) <br><br>Please go through it and confirm the order. We look forward to working with you again<br><br><br><br>Regards<br><br>Zillium Inc<br><br>",
    "error_list": [],
    "subject": "Purchase Order from Zillium Inc (PO #: PO-00001)",
    "emailtemplates": [
      {
        "selected": false,
        "name": "Default",
        "email_template_id": "460000000011023"
      }
    ],
    "to_contacts": [
      {
        "first_name": "Will",
        "selected": true,
        "phone": "+1-925-921-9201",
        "email": "willsmith@bowmanfurniture.com",
        "last_name": "Smith",
        "salutation": "Mr.",
        "contact_person_id": "460000000026051",
        "mobile": "+1-4054439562"
      },
      {
        "first_name": "Peter",
        "selected": false,
        "phone": "+1-925-929-7211",
        "email": "peterparker@bowmanfurniture.com",
        "last_name": "Parker",
        "salutation": "Mr.",
        "contact_person_id": "460000000031001",
        "mobile": "+1-4054439760"
      }
    ],
    "attachment_name": "7.png",
    "file_name": "PO-00001.pdf",
    "vendor_id": "460000000026049",
    "from_emails": [
      {
        "user_name": "John Smith",
        "selected": true,
        "email": "johnsmith@zilliuminc.com",
        "is_org_email_id": true
      },
      {
        "user_name": "John David",
        "selected": false,
        "email": "johndavid@zilliuminc.com",
        "is_org_email_id": false
      }
    ]
  }
}

Update billing address

PUT  /purchaseorders/:purchaseorder_id/address/billing

Updates the billing address for this purchase order alone.

Sample Request

{
          "address": "B-1104, 11F, \nHorizon International Tower, \nNo. 6, ZhiChun Road, HaiDian District",
          "city": "Beijing",
          "state": "Beijing",
          "zip": "1000881",
          "country": "China",
          "fax": "+86-10-82637827"
        }

Sample Response

Status: 200 OK
Content Type: application/json;charset=UTF-8
{
      "code": 0,
      "message": "Billing address updated"
    }

List purchase order templates

GET  /purchaseorders/templates

Get all purchase order pdf templates.

Sample Response

Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "success",
  "templates": [
    {
      "template_name": "Standard Template",
      "template_id": "460000000011003",
      "template_type": "standard"
    }
  ]
}

Update purchase order template

PUT  /purchaseorders/:purchaseorder_id/templates/:template_id

Update the pdf template associated with the purchase order.

Sample Response

Status: 200 OK
Content Type: application/json;charset=UTF-8
{
      "code": 0,
      "message": "Purchase Order updated successfully."
    }