Top

Credit Notes

List credit notes
GET /creditnotes
List credit notes with pagination.
Get credit note
GET /creditnotes/:creditnote_id
Get details of a credit note.
Create a credit note
POST /creditnotes
Create a credit note for a customer.
Update credit note
PUT /creditnotes/:creditnote_id
Update an existing credit note.
Delete credit note
DELETE /creditnotes/:creditnote_id
Delete a credit note.
Convert to open
POST /creditnotes/:creditnote_id/status/open
Change an existing credit note status to open. Voided credit note can't be changed to open.
Void credit note
POST /creditnotes/:creditnote_id/status/void
Mark an existing credit note as void.
Email credit note
POST /creditnotes/:creditnote_id/email
Email a credit note to the customer.
Email history
GET /creditnotes/:creditnote_id/emailhistory
Get email history of a credit note.
Get email content
GET /creditnotes/:creditnote_id/email
Get email content of a credit note.
Update billing address
PUT /creditnotes/:creditnote_id/address/billing
Updates the billing address for an existing credit note alone. You can set this address as default billing address for your customer by specifying 'is_update_customer' node as true.
Update shipping address
PUT /creditnotes/:creditnote_id/address/shipping
Updates the shipping address for an existing credit note alone. You can set this address as default shipping address for your customer by specifying 'is_update_customer' node as true.
List credit note template
GET /creditnotes/templates
Get all credit note pdf templates.
Update credit note template
PUT /creditnotes/:creditnote_id/templates/:template_id
Update the pdf template associated with the credit note.

List credit notes

GET  /creditnotes

List credit notes with pagination.

Parameters

creditnote_number string
[100]
Search credit notes by credit note number.
Variants: creditnote_number_startswith and creditnote_number_contains
date string
[yyyy-mm-dd]
Search credit notes by credit note date.
Variants: date_start, date_end, date_before and date_after
status string Search credit notes by credit note status. Allowed statuses are draft,open,closed and void.
Allowed Values: open, closed and void
total double Search credit notes by credit note total amount.
Variants: total_less_than, total_less_equals, total_greater_than and total_greater_equals
reference_number string
[100]
Search credit notes by credit note reference number.
Variants: reference_number_startswith and reference_number_contains
customer_name string
[100]
Search credit notes by customer name.
Variants: customer_name_startswith and customer_name_contains
item_name string
[100]
Search credit notes by item name.
Variants: item_name_startswith and item_name_contains
item_description string
[100]
Search credit notes by credit note item description.
Variants: item_description_startswith and item_description_contains
customer_id string Search credit notes by customer id.
line_item_id string Search credit notes by credit note line item id.
item_id string Search credit notes by item id.
tax_id string Search credit notes by tax id.
filter_by string Filter credit notes by statuses.
Allowed Values: Status.All, Status.Open, Status.Draft, Status.Closed and Status.Void
search_text string
[100]
Search credit notes by credit note number or customer name or credit note reference number.
sort_column string Sort credit notes by following columns customer_name, creditnote_number, balance, total, date and created_time.
Allowed Values: customer_name, creditnote_number, balance, total, date and created_time

Sample Response

Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "success",
  "creditnotes": [
    {
      "creditnote_id": "982000000567148",
      "creditnote_number": "CN-00002",
      "status": "open",
      "reference_number": "QRT-13457",
      "date": "2013-11-19",
      "total": 147.60,
      "balance": 137.37,
      "customer_id": "982000000567001",
      "customer_name": "Bowman & Co",
      "currency_id": "982000000000190",
      "currency_code": "USD",
      "created_time": "2013-11-18T02:34:00-0800",
      "last_modified_time": "2013-11-18T02:37:17-0800",
      "is_emailed": false
    },
    {
      "creditnote_id": "982000000567134",
      "creditnote_number": "CN-00001",
      "status": "open",
      "reference_number": "QRT-13456",
      "date": "2013-11-18",
      "total": 171.47,
      "balance": 102.12,
      "customer_id": "982000000567001",
      "customer_name": "Bowman & Co",
      "currency_id": "982000000000190",
      "currency_code": "USD",
      "created_time": "2013-11-18T02:33:10-0800",
      "last_modified_time": "2013-11-18T22:43:25-0800",
      "is_emailed": true
    }
  ],
  "page_context": {
    "page": 1,
    "per_page": 200,
    "has_more_page": false,
    "report_name": "Credit Notes",
    "applied_filter": "Status.All",
    "sort_column": "created_time",
    "sort_order": "D"
  }
}

Get credit note

GET  /creditnotes/:creditnote_id

Get details of a credit note.

Parameters

print boolean Export credit note pdf with default print option.
Allowed Values: true, false, on and off
accept string You can get credit note details as json/pdf/html. Default format is html.
Allowed Values: json, pdf and html

Sample Response

Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "success",
  "creditnote": {
    "creditnote_id": "982000000567134",
    "creditnote_number": "CN-00001",
    "date": "2013-11-18",
    "status": "open",
    "reference_number": "QRT-13456",
    "customer_id": "982000000567001",
    "customer_name": "Bowman & Co",
    "contact_persons": [
      "982000000567003",
      "982000000567005"
    ],
    "currency_id": "982000000000190",
    "currency_code": "USD",
    "exchange_rate": 1.00,
    "price_precision": 2,
    "template_id": "982000000010011",
    "template_name": "Service - Professional",
    "is_emailed": true,
    "line_items": [
      {
        "item_id": "982000000030049",
        "line_item_id": "982000000567142",
        "name": "Hard Drive",
        "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.",
        "item_order": 1,
        "quantity": 1.00,
        "unit": "",
        "bcy_rate": 120.00,
        "rate": 120.00,
        "tax_id": "982000000557028",
        "tax_name": "VAT",
        "item_total": 120.00
      },
      {
        "item_id": "982000000030051",
        "line_item_id": "982000000567144",
        "name": "Premium Plan - Web hosting",
        "description": "10 GB Space, 300 GB Transfer 100 Email Accounts 10 MySQL Databases",
        "item_order": 2,
        "quantity": 1.00,
        "unit": "",
        "bcy_rate": 33.00,
        "rate": 33.00,
        "tax_id": "982000000566007",
        "tax_name": "Sales Tax",
        "item_total": 33.00
      }
    ],
    "sub_total": 153.00,
    "total": 171.47,
    "total_credits_used": 12.20,
    "total_refunded_amount": 57.15,
    "balance": 102.12,
    "taxes": [
      {
        "tax_name": "VAT (12.5%)",
        "tax_amount": 15.00
      },
      {
        "tax_name": "Sales Tax (10.5%)",
        "tax_amount": 3.47
      }
    ],
    "notes": "",
    "terms": "",
    "billing_address": {
      "address": "4141 Hacienda Drive",
      "city": "Pleasanton",
      "state": "CA",
      "zip": "94588",
      "country": "USA",
      "fax": "+1-925-924-9600"
    },
    "shipping_address": {
      "address": "Suite 125, McMillan Avenue",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94134",
      "country": "USA",
      "fax": "+1-925-924-9600"
    },
    "created_time": "2013-11-18T02:33:10-0800",
    "last_modified_time": "2013-11-18T22:43:25-0800"
  }
}

Create a credit note

POST  /creditnotes

Create a credit note for a customer.

Parameters

invoice_id string Create a credit note and apply it to an invoice.
ignore_auto_number_generation boolean Ignore auto number generation for this credit note only. On enabling this option credit note number is mandatory.

Request attributes

customer_id* string ID of the customer the credit note has to be created.
contact_persons array Contact person(s) for whom credit note has to be sent.
creditnote_number string
[50]
Mandatory if auto number generation is disabled.
reference_number string
[50]
Reference number for the refund recorded.
template_id string ID of the pdf template associated with the credit note.
date string
[yyyy-mm-dd]
The date the credit note is created.
exchange_rate double Exchange rate of the currency.
line_items array Line items of a credit note.
item_id string ID of the item.
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 double Quantity of the line item.
tax_id string ID of the tax or tax group applied to the line item.
notes string
[5000]
Notes for the customer for the credit note.
terms string
[10000]
Terms and conditions.

Sample Request

{
      "customer_id": "982000000567001",
      "contact_persons": [
        "982000000567003",
        "982000000567005"
      ],
      "creditnote_number": "CN-00001",
      "reference_number": "QRT-13456",
      "template_id": "982000000010011",
      "date": "2013-11-18",
      "exchange_rate": 1.00,
      "line_items": [
        {
          "item_id": "982000000030049",
          "name": "Hard Drive",
          "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.",
          "unit": "",
          "rate": 120.00,
          "quantity": 1.00,
          "tax_id": "982000000557028"
        },
        {
          "item_id": "982000000030051",
          "name": "Premium Plan - Web hosting",
          "description": "10 GB Space, 300 GB Transfer 100 Email Accounts 10 MySQL Databases",
          "unit": "",
          "rate": 33.00,
          "quantity": 1.00,
          "tax_id": "982000000566007"
        }
      ],
      "notes": "",
      "terms": ""
    }

Sample Response

Status: 201 Created
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "The credit note has been created.",
  "creditnote": {
    "creditnote_id": "982000000567134",
    "creditnote_number": "CN-00001",
    "date": "2013-11-18",
    "status": "open",
    "reference_number": "QRT-13456",
    "customer_id": "982000000567001",
    "customer_name": "Bowman & Co",
    "contact_persons": [
      "982000000567003",
      "982000000567005"
    ],
    "currency_id": "982000000000190",
    "currency_code": "USD",
    "exchange_rate": 1.00,
    "price_precision": 2,
    "template_id": "982000000010011",
    "template_name": "Service - Professional",
    "is_emailed": true,
    "line_items": [
      {
        "item_id": "982000000030049",
        "line_item_id": "982000000567142",
        "name": "Hard Drive",
        "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.",
        "item_order": 1,
        "quantity": 1.00,
        "unit": "",
        "bcy_rate": 120.00,
        "rate": 120.00,
        "tax_id": "982000000557028",
        "tax_name": "VAT",
        "item_total": 120.00
      },
      {
        "item_id": "982000000030051",
        "line_item_id": "982000000567144",
        "name": "Premium Plan - Web hosting",
        "description": "10 GB Space, 300 GB Transfer 100 Email Accounts 10 MySQL Databases",
        "item_order": 2,
        "quantity": 1.00,
        "unit": "",
        "bcy_rate": 33.00,
        "rate": 33.00,
        "tax_id": "982000000566007",
        "tax_name": "Sales Tax",
        "item_total": 33.00
      }
    ],
    "sub_total": 153.00,
    "total": 171.47,
    "total_credits_used": 12.20,
    "total_refunded_amount": 57.15,
    "balance": 102.12,
    "taxes": [
      {
        "tax_name": "VAT (12.5%)",
        "tax_amount": 15.00
      },
      {
        "tax_name": "Sales Tax (10.5%)",
        "tax_amount": 3.47
      }
    ],
    "notes": "",
    "terms": "",
    "billing_address": {
      "address": "4141 Hacienda Drive",
      "city": "Pleasanton",
      "state": "CA",
      "zip": "94588",
      "country": "USA",
      "fax": "+1-925-924-9600"
    },
    "shipping_address": {
      "address": "Suite 125, McMillan Avenue",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94134",
      "country": "USA",
      "fax": "+1-925-924-9600"
    },
    "created_time": "2013-11-18T02:33:10-0800",
    "last_modified_time": "2013-11-18T22:43:25-0800"
  }
}

Update credit note

PUT  /creditnotes/:creditnote_id

Update an existing credit note.

Parameters

ignore_auto_number_generation boolean Allow editing of credit note number.

Request attributes

customer_id* string ID of the customer the credit note has to be created.
contact_persons array Contact person(s) for whom credit note has to be sent.
creditnote_number string
[50]
Mandatory if auto number generation is disabled.
reference_number string
[50]
Reference number for the refund recorded.
template_id string ID of the pdf template associated with the credit note.
date string
[yyyy-mm-dd]
The date the credit note is created.
exchange_rate double Exchange rate of the currency.
line_items array Line items of a credit note.
item_id string ID of the item.
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.
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 double Quantity of the line item.
tax_id string ID of the tax or tax group applied to the line item.
notes string
[5000]
Notes for the customer for the credit note.
terms string
[10000]
Terms and conditions.

Sample Request

{
      "customer_id": "982000000567001",
      "contact_persons": [
        "982000000567003",
        "982000000567005"
      ],
      "creditnote_number": "CN-00001",
      "reference_number": "QRT-13456",
      "template_id": "982000000010011",
      "date": "2013-11-18",
      "exchange_rate": 1.00,
      "line_items": [
        {
          "item_id": "982000000030049",
          "line_item_id": "982000000567142",
          "account_id": "",
          "name": "Hard Drive",
          "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.",
          "unit": "",
          "rate": 120.00,
          "quantity": 1.00,
          "tax_id": "982000000557028"
        },
        {
          "item_id": "982000000030051",
          "line_item_id": "982000000567144",
          "account_id": "",
          "name": "Premium Plan - Web hosting",
          "description": "10 GB Space, 300 GB Transfer 100 Email Accounts 10 MySQL Databases",
          "unit": "",
          "rate": 33.00,
          "quantity": 1.00,
          "tax_id": "982000000566007"
        }
      ],
      "notes": "",
      "terms": ""
    }

Sample Response

Status: 200 OK
Content Type: application/json;charset=UTF-8
{
      "code": 0,
      "message": "The credit note has been updated.",
      "creditnote": {
        "creditnote_id": "982000000567134",
        "creditnote_number": "CN-00001",
        "date": "2013-11-18",
        "status": "open",
        "reference_number": "QRT-13456",
        "customer_id": "982000000567001",
        "customer_name": "Bowman & Co",
        "contact_persons": [
          "982000000567003",
          "982000000567005"
        ],
        "currency_id": "982000000000190",
        "currency_code": "USD",
        "exchange_rate": 1.00,
        "price_precision": 2,
        "template_id": "982000000010011",
        "template_name": "Service - Professional",
        "is_emailed": false,
        "line_items": [
          {
            "item_id": "982000000030049",
            "line_item_id": "982000000567142",
            "name": "Hard Drive",
            "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.",
            "item_order": 1,
            "quantity": 1.00,
            "unit": "",
            "bcy_rate": 120.00,
            "rate": 120.00,
            "tax_id": "982000000557028",
            "tax_name": "VAT",
            "item_total": 120.00
          },
          {
            "item_id": "982000000030051",
            "line_item_id": "982000000567144",
            "name": "Premium Plan - Web hosting",
            "description": "10 GB Space, 300 GB Transfer 100 Email Accounts 10 MySQL Databases",
            "item_order": 2,
            "quantity": 1.00,
            "unit": "",
            "bcy_rate": 33.00,
            "rate": 33.00,
            "tax_id": "982000000566007",
            "tax_name": "Sales Tax",
            "item_total": 33.00
          }
        ],
        "sub_total": 153.00,
        "total": 171.47,
        "total_credits_used": 12.20,
        "total_refunded_amount": 57.15,
        "balance": 102.12,
        "taxes": [
          {
            "tax_name": "VAT (12.5%)",
            "tax_amount": 15.00
          },
          {
            "tax_name": "Sales Tax (10.5%)",
            "tax_amount": 3.47
          }
        ],
        "notes": "",
        "terms": "",
        "billing_address": {
          "address": "4141 Hacienda Drive",
          "city": "Pleasanton",
          "state": "CA",
          "zip": "94588",
          "country": "USA",
          "fax": "+1-925-924-9600"
        },
        "shipping_address": {
          "address": "Suite 125, McMillan Avenue",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94134",
          "country": "USA",
          "fax": "+1-925-924-9600"
        },
        "created_time": "2013-11-18T02:33:10-0800",
        "last_modified_time": "2013-11-18T02:37:17-0800"
      }
    }

Delete credit note

DELETE  /creditnotes/:creditnote_id

Delete a credit note.

Sample Response

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

Convert to open

POST  /creditnotes/:creditnote_id/status/open

Change an existing credit note status to open. Voided credit note can't be changed to open.

Sample Response

Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "The status of the credit note has been changed to open."
}

Void credit note

POST  /creditnotes/:creditnote_id/status/void

Mark an existing credit note as void.

Sample Response

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

Email credit note

POST  /creditnotes/:creditnote_id/email

Email a credit note to the customer.

Parameters

customer_id string ID of the customer.

multipart/form-data

attachments file The files to be attached with the email.

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.
subject* string
[1000]
Subject of the email to be sent.
body* string
[5000]
Message body of the email to be sent.

Sample Request

      "send_from_org_email_id": true,
          "to_mail_ids": [
            "willsmith@bowmanfurniture.com"
          ],
          "cc_mail_ids": [
            "peterparker@bowmanfurniture.com"
          ],
          "subject": "Credit Note from Zillium Inc (Credit Note #: CN-00001)",
          "body": ""Dear Customer,           <br><br><br><br>The credit note (CN-00001) is attached with this email.           <br><br><br><br>Credit Note Overview:           <br><br>Credit Note # : CN-00001           <br><br>Date : 06 Aug 2013           <br><br>Amount : $171.47(in USD)     <br><br><br><br>You can get in touch with us via phone or email for any clarifications.           <br><br><br><br>Thanks for your business.<br><br><br>\nRegards<br>\nZillium Inc<br>\n"
    }

Sample Response

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

Email history

GET  /creditnotes/:creditnote_id/emailhistory

Get email history of a credit note.

Sample Response

Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "success",
  "email_history": [
    {
      "mailhistory_id": "982000000570005",
      "from": "johnsmith@zilliuminc.com",
      "to_mail_ids": "willsmith@bowmanfurniture.com",
      "subject": "Credit Note from Zillium Inc (Credit Note #: CN-00001)",
      "date": "2013-11-18",
      "type": 28
    }
  ]
}

Get email content

GET  /creditnotes/:creditnote_id/email

Get email content of a credit note.

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 Customer,           <br><br>The credit note (CN-00001) is attached with this email.           <br><br>Credit Note Overview:           <br>Credit Note # : CN-00001           <br>Date : 18 Nov 2013           <br>Amount : $171.47(in USD)     <br><br>You can get in touch with us via phone or email for any clarifications.           <br><br>Thanks for your business.<br><br><br>Regards<br>Zillium Inc<br>",
    "error_list": [],
    "subject": "Credit Note from Zillium Inc (Credit Note #: CN-00001)",
    "emailtemplates": [
      {
        "selected": true,
        "name": "Default",
        "email_template_id": "982000000010029"
      }
    ],
    "to_contacts": [
      {
        "first_name": "Will",
        "selected": false,
        "phone": "+1-925-921-9201",
        "email": "willsmith@bowmanfurniture.com",
        "last_name": "Smith",
        "salutation": "Mr.",
        "contact_person_id": "982000000567003",
        "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": "982000000567005",
        "mobile": "+1-4054439760"
      }
    ],
    "file_name": "CN-00001.pdf",
    "from_emails": [
      {
        "user_name": "John Smith",
        "selected": true,
        "email": "johnsmith@zilliuminc.com"
      },
      {
        "user_name": "John David",
        "selected": false,
        "email": "johndavid@zilliuminc.com"
      }
    ],
    "customer_id": "982000000567001"
  }
}

Update billing address

PUT  /creditnotes/:creditnote_id/address/billing

Updates the billing address for an existing credit note alone. You can set this address as default billing address for your customer by specifying 'is_update_customer' node as true.

Request attributes

is_update_customer boolean Boolean to update the address for all draft, unpaid invoices and future invoices.

Sample Request

{
          "address": "4900 Hopyard Rd, Suite 310",
          "city": "Pleasanton",
          "state": "CA",
          "zip": "94588",
          "country": "USA",
          "fax": "+1-925-924-9600",
          "is_update_customer": false
    }

Sample Response

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

Update shipping address

PUT  /creditnotes/:creditnote_id/address/shipping

Updates the shipping address for an existing credit note alone. You can set this address as default shipping address for your customer by specifying 'is_update_customer' node as true.

Request attributes

is_update_customer boolean Boolean to update the address for all draft, unpaid invoices and future invoices.

Sample Request

{
          "address": "Suite 125, McMillan Avenue",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94134",
          "country": "USA",
          "fax": "+1-925-924-9600",
          "is_update_customer": false
    }

Sample Response

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

List credit note template

GET  /creditnotes/templates

Get all credit note pdf templates.

Sample Response

Status: 200 OK
Content Type: application/json;charset=UTF-8
{
  "code": 0,
  "message": "success",
  "templates": [
    {
      "template_name": "Fixed Cost - Professional",
      "template_id": "982000000010019",
      "template_type": "professional"
    },
    {
      "template_name": "Product - Professional",
      "template_id": "982000000010003",
      "template_type": "professional"
    },
    {
      "template_name": "Service - Professional",
      "template_id": "982000000010011",
      "template_type": "professional"
    }
  ]
}

Update credit note template

PUT  /creditnotes/:creditnote_id/templates/:template_id

Update the pdf template associated with the credit note.

Sample Response

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