Overview

This method allows you to create an invoice on Komet Sales with its corresponding product items. 

Request

https://api.kometsales.com/api/invoice.create

  • Method: POST
  • Content-Type: application/json

Input Parameters:

  • authenticationToken (required)(string:50): Komet Sales security token.
  • customerId (required: if customerCode is not given)(integer:20): customer ID. You can obtain this value from the customer.list API method.
  • customerCode (required: if customerId is not given) (string:20): customer Code.
  • customerDescription (required: if customerId is not given) (string:200): customer name.
  • carrierId (required: if carrierCode is not given)(integer:20): carrier ID. You can obtain this value from the carrier.list API method.
  • carrierCode (required: if carrierId is not given) (string:20): carrier code.
  • carrierDescription (required: if carrierId is not given) (string:200): carrier name.
  • shipDate (required) (date): Shipping date (date format YYYY-MM-DD).
  • poNumber (optional)(string:20) : customer PO #.
  • reference (optional)(string:20): reference or way bill number.
  • warehouseInstructions (optional)(string:200): instructions for warehouse.
  • invoiceNotes (optional)(string:200): notes to print on the invoice.
  • returnAvailableBoxes (optional)(boolean: 1 or 0): default 0. If it's 1, the response will include the number of boxes available for each given item.
  • statusDraft (optional)(boolean: 1 or 0): default 0. If it's 1, the order will be left as Draft instead of Pending Approval. This value must be given as 1 if you want to use the invoice.checkout API method once the order is finalized within your site.
  • locationId (optional)(integer:20): location Komet Sales internal ID. You can obtain this value from the location.list API method. This only applies for companies in Multi Location mode. 
  • locationCode (optional)(string:10): location code. You can obtain this value from the location.list API method. This only applies for companies in Multi Location mode. 
  • autoConfirm (optional)(boolean): "True" if you want the system automatically confirm the order. By default is False. 
  • createCarrierIfNotExists (optional)(boolean): "True" if you want the system to create the carrier if it doesn't exist, in this case, you should send carrierCode and carrierDescription parameters with valid values.  By default is False. 
  • useUnknownCustomerIfNotExists (optional)(boolean): "False" if you don't want the system to use the "Unknown" customer in the case that it doesn't exist, in this case, the system will return an error message if the customer sent as parameter doesn't exist. By default is True. 
  • additionalCharges (optional): array of additional charges associated to the order. 
    • code (required)(string: 10): code of the additional charge. If it's doesn't exist in the system, it will be created automatically. 
    • name (optional)(string: 50): name of the additional charge. This field is important if code sent doesn't exist. 
    • value (required)(decimal: 10,3): amount of the additional charge. 
  • items: array of item lines that will be added to the invoice.
    • orderItemId (required: if productCode is not given)(integer:20): ID of the Komet Sales internal inventory item. This field is required if productCode is not given. This value can be obtained from the inventory.list API method.
    • productCode (required: if orderItemId is not given)(string:20): product code of the Komet Sales inventory item. This field is required if orderItemId is not given. You can obtain this value from the product.list API method.
    • boxTypeCode (required: if orderItemId is not given)(string:3): box type code of the Komet Sales inventory item. This field is required if orderItemId is not given. You can obtain this value from the boxtype.list API method.
    • unitsPerBox (required: if orderItemId is not given)(integer:10): units per box.
    • unitType (required: if orderItemId is not given)(string:5): stem or bunch are the unique valid values.
    • boxes (required)(integer:10): number of boxes.
    • price (required) (decimal:10,2): unit price.
    • markCode (optional)(string:20): item mark code.
    • productAlias (optional)(string:50): product description alias.
    • notes (optional)(string:200): item notes.

You can use either customerId or the customerCode and customerName but you cannot use both parameters at the same time. We recommend you to use the customerId which can be obtained from the customer.list API method.

You can use either carrierId or carrierCode and carrierName but you cannot use both parameters at the same time. We recommend you to use the carrierId which can be obtained from the carrier.list API method.

Sample 1
{
  "authenticationToken": "token_info_goes_here",
  "customerId": 99999,
  "carrierId": 423, 
  "shipDate": "2014-04-10",
  "poNumber": "PO9999",
  "reference" : "R99999", 
  "warehouseInstructions": "Text for instructions", 
  "invoiceNotes": "Text for label instructions",
  "additionalCharges": [
    {
      "code": "BT",
      "name": "Balance Transfer",
      "value": 10
    }
  ],
  "items": 
   [
    {
      "orderItemId": 9999999,   
      "boxes": 5, 
      "price": 2.50,
      "markCode": "text for mark code", 
      "productAlias" : "text for product alias", 
      "notes": "text for notes"
    }
 ]
}
Sample 2
{
  "authenticationToken": "token_info_goes_here",
  "customerCode": "ANG",
  "customerDescription": "Ang Flowers LLC", 
  "carrierCode": "AR",
  "carrierDescription": "Armellini",
  "poNumber": "2728", 
  "reference": "This is a reference",
  "shipDate": "2014-09-10",
  "warehouseInstructions": "This is where the instructions to the warehouse go.",
  "invoiceNotes": "Invoice notes go here",
  "returnAvailableBoxes":1
  "items": 
   [
     {
      "productCode": "RSAS60",    
      "boxes": 10,
      "price":0.30,
      "boxTypeCode": "HB",
      "unitsPerBox": 6,
      "unitType": "Bunch"
     }
  ]
 }

Response

Output:

  • status (integer:1): transaction status. 1 for success or 0 for failure.
  • message (string:500): description of the status of the transaction.
  • invoiceId (integer:20): invoice ID.
  • invoiceNumber (integer:10): invoice number.
  • items (array)
    • status: (integer:1): transaction status. 1 for success or 0 for failure.
    • orderItemId (integer:10)(if orderItemId was given).
    • productCode (string:20)(if productCode was given).
    • availableBoxes (integer:10): number of boxes that are available if returnAvailableBoxes is given.
    • invoiceItemId (array): array of the product line IDs that were added to the order. When an orderItemId is given, the system will add only 1 item to the invoice. However, when the productCode is given, the system may add more than 1 line to order and for that reason, the system may return a few IDs.
Sample 1
{
  "status": "1",
  "message": "success",
  "invoiceId": 111111111,
  "invoiceNumber": 85443,
  "items": [
    {
        "status": 1,
        "orderItemId": 9999999,
        "invoiceItemId": [
            3427615
         ]
    }
   ]
 }
Sample 2
 {
  "status": "0",
  "message": "Item is not available",
  "invoiceId": 111111111,
  "invoiceNumber": 85443,
   "items": [
    {
        "availableBoxes": 9,
        "productCode": "RSAS60",
        "status": 1,
        "invoiceItemId": [
            3427612,
            3427613,
            3427614
        ]
    }
   ]   
 }

Multicurrency Option Enabled

If the customer for who you are creating an invoice has a different currency, you should enter prices in your customer's currency and the system will generate the invoice in your company's currency, based on the exchange rate set up at the time of the transaction.