Revision History

2019 2.0.0

Added new resources to export data to a directory on disk. Data that can exported includes products, invoices, etc ... The data exported reflects every record in the database and will take the form of zip-compressed json files for easy parsing. Please refer to the API docs for implementation details.

Example POST /api/data_export/run/ request for exporting all products and invoices to the default folder:

<data_export>
    <settings>
        <items>
            <product>
                <export>true</export>
            </product>
            </invoice>
                <export>true</export>
            </invoice>
        </items>
    </settings>
</data_export>

Added optional quantity discount values to POST and PUT operations on Invoices and Orders.

e.g.

<lineitem>
    <!-- ... -->
    <quantity_discount>[bool]</quantity_discount><!-- Optional. Works with sells/..quantity_discount fields -->
    <!-- ... -->
    <sells><!-- Optional. Mutually exclusive with sell_price. Should be sent when the line has predetermined base and tax inclusive prices already.
                For example, a lineitem with externally applied taxes or a line item with a None pricing calculation. -->
        <base>[decimal]</base> <!-- Optional -->
        <sell_tax_inclusive>[decimal]</sell_tax_inclusive> <!-- Optional -->
        <sell_quantity_discount>[decimal]</sell_quantity_discount> <!-- Optional -->
        <sell_tax_inclusive_quantity_discount>[decimal]</sell_tax_inclusive_quantity_discount> <!-- Optional -->
    </sells>
</lineitem>

2018 3.0.3

Added <manufacturer_part_number>[str]</manufacturer_part_number> and <manufacturer_pricing_option_code>[str]</manufacturer_pricing_option_code> to products. These fields are added to record a product’s additional manufacturer information.

e.g.

<product uri="/products/X/" id="X">
    <!-- Existing fields -->

    <manufacturer_part_number>[str]</manufacturer_part_number>
    <manufacturer_pricing_option_code>[str]</manufacturer_pricing_option_code>
</product>

These fields will also be rendered on corresponding document lineitems such as invoices, orders, purchase_orders.

2018 3.0.0

Deprecated <manual/> flag for order and invoice line items.

Added <price_calculations>[enum: AUTO | MANUAL | NONE | AUTO_NONE]</price_calculations> as a replacement.

  • Defaults to AUTO.
  • AUTO indicates pricing is calculated using the latest values from the product card and any associated discounts or sales.
  • MANUAL indicates that a user entered price has been set and no price calculations are to be performed.
  • NONE indicates that no price calculations are to be performed.
  • AUTO_NONE indicates that pricing should be calculated, but the resulting price calculation state is NONE (i.e. no more recalculations on future edits).

e.g.

<lineitem>
    <!-- ... -->
    <price_calculations>AUTO</price_calculations>
    <!-- ... -->
</lineitem>

Added finish end point for orders and invoices.

2016 1.3.0

New field active have been added to tax exemptions. Listing of tax exemptions now also includes etags.

Added supports for creating/updating/deleting of tax exemptions.

Added support for creating gift cards.

Added back order related fields, new discount fields to invoices workflows

Back order quantities, sells, and new discount fields can now be specified during POST operations.

<lineitem>
    <quantity_backordered>0.000</quantity_backordered> <!-- New field -->
    <sells>
        <base>[decimal]</base> <!-- Optional -->
        <sell_tax_inclusive>[decimal]</sell_tax_inclusive> <!-- Optional -->
    </sells>
    <discount>
        <percent>20.00</percent> <!-- Cannot be sent together with the other 3 fields. -->
        <value>10.00</value> <!-- Existing. Cannot be sent together with the other 3 fields. Same meaning as before, it will be tax_exclusive or tax_inclusive based on the doc's tax setting. -->
        <tax_exclusive_value>10.00</tax_exclusive_value> <!-- New. Cannot be sent together with percent or value -->
        <tax_inclusive_value>12.00</tax_inclusive_value> <!-- New. Cannot be sent together with percent or value -->
    </discount>
</lineitem>

New fields rendered:

<lineitem>
    <quantity_backordered>0.000</quantity_backordered> <!-- New field -->
    <discount> <!-- Will render all 4 fields from now on -->
        <percent>10.00</percent> <!-- Existing. This will naturally be Null if there're values in the other 3 fields. -->
        <value/> <!-- Existing. Same meaning as before: will be tax_exclusive or tax_inclusive based on the doc's tax setting. -->
        <tax_exclusive_value/> <!-- New -->
        <tax_inclusive_value/> <!-- New -->
    </discount>
</lineitem>

Total cost, profit, back order totals and remaining balance are now available on the invoice.

<invoice uri="/invoices/1/" id="1" full_render="true">
  <totals>
    <cost>200.00</cost>
    <subtotal>450.00</subtotal>
    <profit>250.00</profit>
    <tax>50.00</tax>
    <total>500.00</total>
    <owing>500.00</owing>
    <paid>0.00</paid>
    <total_backordered>500.00</total_backordered><!-- The sum of tax inclusive backordered amounts. -->
    <remaining_balance>1000.00</remaining_balance><!-- The tax inclusive remain balance including back orders. -->
  </totals>
</invoice>

New sells and discount fields can now be specified during POST, PUT operations.

<lineitem>
    <sells>
        <base>[decimal]</base> <!-- Optional -->
        <sell_tax_inclusive>[decimal]</sell_tax_inclusive> <!-- Optional -->
    </sells>
    <discount>
        <percent>20.00</percent> <!-- Cannot be sent together with the other 3 fields. -->
        <value>10.00</value> <!-- Existing. Cannot be sent together with the other 3 fields. Same meaning as before, it will be tax_exclusive or tax_inclusive based on the doc's tax setting. -->
        <tax_exclusive_value>10.00</tax_exclusive_value> <!-- New. Cannot be sent together with percent or value -->
        <tax_inclusive_value>12.00</tax_inclusive_value> <!-- New. Cannot be sent together with percent or value -->
    </discount>
</lineitem>

New sell_tax_inclusive_quantity_discount and discount fields rendered.

<lineitem>
    <discount> <!-- Will render all 4 fields from now on -->
        <percent>10.00</percent> <!-- Existing. This will naturally be Null if there're values in the other 3 fields. -->
        <value/> <!-- Existing. Same meaning as before: will be tax_exclusive or tax_inclusive based on the doc's tax setting. -->
        <tax_exclusive_value/> <!-- New -->
        <tax_inclusive_value/> <!-- New -->
    </discount>
    <sells>
        <sell>90.00</sell>
        <base>100.00</base>
        <total>90.00</total>
        <sell_quantity_discount>100.00</sell_quantity_discount>
        <sell_tax_inclusive_quantity_discount>120.000</sell_tax_inclusive_quantity_discount> <!-- New. Quantity discount sell price with tax. -->
        <sell_tax_inclusive>120.000</sell_tax_inclusive>
        <sell_tax_inclusive_total>108.00</sell_tax_inclusive_total>
        <sell_tax_inclusive_discounted>108.00</sell_tax_inclusive_discounted>
    </sells>
</lineitem>

Total cost, profit, paid, and remaining balance are now available on the order.

<order uri="/orders/1/" id="1" full_render="true">
  <totals>
    <cost>1300.00</cost>
    <subtotal>2340.00</subtotal>
    <profit>1040.00</profit>
    <tax>234.00</tax>
    <credit>-1000.00</credit>
    <total>2574.00</total>
    <paid>1000.00</paid>
    <remaining_balance>1574.00</remaining_balance>
  </totals>
</order>

2016 1.0.4

Broken custom field rendering was removed from Orders and Invoices.

2016 1.0.0

Search Resources has been added to tutorials.

The following search resources have been added:

Payments updated to remove copy of parent properties.

<payment uri="/invoices/A/payments/B/" id="B">
    <type>[enum: Cash | Gift Card | Debit Card | Credit Card | Credit Card Manual |  Debit Card Manual | Store Card | Cheque | Loan | Lease | Web Payment | Manual | Credit | Rounding]</type>
    <payment_method>[str]</payment_method>
    <datetime_created>[datetime]</datetime_created>
    <datetime_modified>[datetime]</datetime_modified>
    <exported>[datetime]</exported>
    <posted>[datetime]<posted>
    <flags>
        <exported>[bool]</exported>
        <posted>[bool]</posted>
        <voided>[bool]</voided>
    </flags>
    <number>[str]</number><!-- The number associated to this transaction. Generally this is the ref id from the processor -->
    <source id="[str]"/>
    <amount>[decimal]</amount>
    <tendered>[decimal]</tendered>
    <authcode>[str]</authcode>
    <avs_result>[str]</avs_result>
    <till uri="/api/tills/C/" id="C"/>
    <signature_photo uri="/invoices/A/payments/B/signature_photo/"/>
    <!-- <parent_properties> # Removed -->
</payment>

Invoice resources updated. Localizable language and shipping method are updated to full URI compliance.

<invoice>
    <print_options>
        <localizable_language id="[int]"/> <!-- Updated from language tag -->
    </print_options>
    <shipping_method id="[int]"/> <!-- Updated from shipping_method tag -->
</invoice>

<invoice>
    <print_options>
        <localizable_language uri="/setup/localizable_languages/X/" id="X" full_rendered="true"> <!-- Updated from language tag -->
            <!-- See GET /setup/localizable_languages/X/ response for details. -->
        </localizable_language>
    </print_options>
    <shipping_method uri="/setup/shipping_methods/X/" id="X"> <!-- Updated from shipping_method tag -->
        <!-- See GET /setup/shipping_methods/X/ response for details. -->
    </shipping_method>
    <status>[str]</status> <!-- Updated from invoice_status tag -->
</invoice>

Taxes are also being rendered differently.

<lineitem>
    <!-- New -->
    <taxes>
        <tax id="1"><!-- Always 5 tax elements with ids 1-5 -->
            <exempt>[bool]</exempt>
        </tax>
        [...]
    </taxes>
</lineitem>

<lineitem>
    <tax_exemption uri="/setup/tax_exemptions/X/" id="X"/> <!-- New -->
    <manual>[bool]</manual> <!-- New -->
    <taxes> <!-- Updated -->
        <tax id="1"><!-- Always 5 tax elements with ids 1-5 -->
            <exempt>[bool]</exempt>
            <total>[decimal]</total>
        </tax>
        [...]
    </taxes>
</lineitem>

Orders API resources have been added. These resources include create/read/update support orders and order line items.

Inventory reserve/release support added for order lineitems. Orders can also be cancelled at any time.

Full read support has been added for order payments.

Web Payment creation support has been added to payments.

Support for creating invoices directly from orders has been added. Invoices created from an order source will have the contents of the order copied over to the newly created invoice.

The syntax for specifying a source is as follows:

<invoice>
    [...]
    <source>
        <!-- one of: -->
        <order id="[int]"/>
        <quote id="[int]"/>
        <sro id="[int]"/>
    </source>
    [...]
</invoice>

The syntax requires the user to specify the type of the source (order, quote, or SRO), along with its corresponding row ID. The following is a sample request payload for creating an invoice from an order with ID 5.

<invoice>
    <source>
        <order id="5"/>
    </source>
</invoice>

An excerpt of the response returned by this request is as follows:

<invoice>
    [...]
    <source>
        <id>O-5</id>
        <order uri="/orders/5/" id="5"/>
    </source>
    [...]
</invoice>

It should be noted that creating an invoice from a source order will initialize the invoice’s attributes to those of the order; however, creating an invoice from a quote or SRO will only set the ‘source’ value of the invoice to the specified source, with the invoice’s other attributes remaining unchanged.

Purchase Orders can now be created from an order. A new tag <source> in the request can be used to create a purchase order from the specified order or to modify the source of the purchase order.

Request has <source> tag:

<purchase_order>
        [...]
        <source> <!-- Optional -->
                <order id="[int]">
                        <lineitems>  <!-- Optional, only available when creating a Purchase Order from an Order.  Choose specific lines from the order to create the Purchase Order. -->
                                <lineitem id="[int]"/>
                        </lineitems>
                </order>
        </source>
        [...]
</purchase_order>

Response now has <source> tag:

<purchase_order>
   [...]
        <source> <!-- Optional -->
                <order uri="/orders/[int]/" id="[int]"/>
        </source>
        [...]
</purchase_order>

The supplier id in <po_supplier><supplier id=”[int]”/></po_supplier> is now optional and not required in POST /purchase_orders/.

The POST /api/purchase_orders/(d+)/receive/ resource have been updated. You can now reserve inventory for linked orders when you receive inventory for the purchase order. Request:

<receive>
    <inventory>
        <!-- Existing fields. -->
        <reserve_on_linked_orders>[boolean]</reserve_on_linked_orders>
    </inventory>
    [...]
</receive>

Response:

<response>
    <!-- Existing fields. -->
<orders>
        <!-- All orders that have had quantity reserved on them in this request. -->
        <order uri="/orders/X/" id="X"/>
        [...]
    </orders>
</response>

The POST /api/purchase_orders/(d+)/unreceive/ resource have been updated. You can now unreserve inventory for linked orders when you unreceive inventory for the purchase order. Request:

<unreceive>
    <inventory>
        <!-- Existing fields. -->
        <unreserve_on_linked_orders>[boolean]</unreserve_on_linked_orders>
    </inventory>
    [...]
</unreceive>

Response:

<response>
    <!-- Existing fields. -->
<orders>
        <!-- All orders that have had quantity unreserved on them in this request. -->
        <order uri="/orders/X/" id="X"/>
        [...]
    </orders>
</response>

The request and response structure for various documents has been reworked and unified. Below is a list of the changes.

  1. The rendering of ‘pricing_level’ elements within responses has been standardized across multiple documents. The name of the pricing level will now be rendered within a ‘name’ sub-element of the ‘pricing_level’, i.e.:

    <pricing_level index="X">
    <name>Y</name>
</pricing_level>

  2. The ‘sells’ element and its sub-elements within responses have been standardized across multiple documents containing line item information. The ‘sell’ and ‘total’ elements are no longer specific to the tax-inclusion mode; they now contain the same value regardless of whether tax-inclusion is enabled. As such, several other elements have been added to the response to display tax-inclusive information. The new response structure is as follows:

    <sells>
        <sell>[decimal]</sell>
        <base>[decimal]</base>
        <total>[decimal]</total>
        <sell_quantity_discount>[decimal]</sell_quantity_discount>
        <sell_tax_inclusive>[decimal]</sell_tax_inclusive>
        <sell_tax_inclusive_total>[decimal]</sell_tax_inclusive_total>
        <sell_tax_inclusive_discounted>[decimal]</sell_tax_inclusive_discounted>
</sells>
    • The ‘sell’ element contains the current sale price of the the item. Taxes are not included in this value.
    • The ‘base’ element contains the base (unmodified) sale price of the item. Taxes are not included in this value.
    • The ‘total’ element contains the total sale price of the item for the quantity specified in the line item. Taxes are not included in this value.
    • The ‘sell_quantity_discount’ contains the sale price of the item including quantity-based discounts.
    • The ‘sell_tax_inclusive’ element contains the current sale price of the the item, with taxes included.
    • The ‘sell_tax_inclusive_total’ element contains the total sale price of the item for the quantity specified in the line item, with taxes included.
    • The ‘sell_tax_inclusive_discounted’ element contains the sale price of the item, with discounts and taxes included.

    The ‘sell_price’ element was left unchanged. See the reference contract documentation for more information.

  3. The ‘discount’ element rendering in responses has been standardized across multiple documents; it will now contain either a ‘value’ or ‘percent’ sub-element, indicating the type of the discount. For example:

    <discount>
    <value>10</value> <!-- indicates a discount of $10 -->
</discount>

    ...or...

    <discount>
    <percent>50</percent> <!-- indicates a 50% discount -->
</discount>

    When no discount is applicable, then an empty <discount/> element will be rendered.

  4. In order to unify the creation of line items, the ‘lineitem_product’ element was standardized across all documents. As a result, when creating an order line item, the ‘product’ and ‘description’ elements must be within the ‘lineitem_product’ element, i.e.:

    <lineitem>
    <lineitem_product>
        <product id="X"/>
        <description>[str]</description> <!-- optional -->
    </lineitem_product>
</lineitem>

User resources have an extra <pin> tag in :

Their responses have a new <pin> tag which always renders with “****” example

<user uri="/users/1/" id="1" full_render="true">
    [...]
    <pin>********</pin>
    [...]
</user>

New resources:

Used to represent the uri’s of Shipping Methods and Localized Languages in the responses of Invoices and Orders where the Shipping Methods and Localized languages no longer exist.

Invoice line items have a new tag in their <sells> tag:

<sells>
        [...]
        <sell_tax_inclusive_quantity_discount>[decimal]</sell_tax_inclusive_quantity_discount> <!-- sell quantity discount including taxes -->
        [...]
</sells>

The <sell_tax_inclusive_quantity_discount> represents the sell_quantity_discount with tax.

2015 2.3.1

The POST /api/products/ and PUT /api/products/(d+)/ resources have been updated. Added sell_web to the <sells> tag.

<product>
    <sells>
        <sell_web>[decimal]</sell_web>
    </sells>
</product>

2015 2.1.0

The GET /api/customers/(d+)/ resource has been updated. These tags are taken out of the <flags> tag.

<customer>
    <credit_hold>[bool]</credit_hold>
    <new_import>[bool]</new_import>
    <new_update>[bool]</new_update>
</customer>

The GET /api/products/(d+)/ resource has been updated. The category tags are now rendered in full as separate resources.

<product>
    <categories>
        <pos>
            <category uri="/setup/pos_categories/H/" id="H">
                <!-- See GET /setup/pos_categories/X/ for details -->
            </category>
        </pos>
        <web>
            <category uri="/setup/web_categories/I/" id="I">
                <!-- See GET /setup/web_categories/X/ for details -->
            </category>
        </web>
    </categories>
</product>

The GET /api/suppliers/(d+)/ resource has been updated. These tags are taken out of the <flags> tag.

<supplier>
    <new_import>[bool]</new_import>
    <store>[bool]</store>
</supplier>

2015 1.0.0

The Sale Events and Sale Offers resources have been added.