Order resource

Pulling order data from ZEST to push into an ERP is a very common use of the Data API. This section documents the Order resource & a number of other related resources.

The Order resource stores the main data about the order: who placed it, where it should be delivered, when, the totals etc. However it is important to understand its relationship with other resources in order to get the complete picture of the order:

  • Orderlines - what was ordered - what product, quantity and subtotals.
  • OrderlineDiscounts - discount information relating to specific orderlines, or the order itself.
  • OrderlineTax - additional tax information relating to tax applied to an orderline
  • Shipments - tracking an order shipment - who it was shipped with, tracking number, link etc
  • ShipmentLines - what orderlines were included in a shipment

Webhook - push notifications

Make sure you also check out webhooks which allow you to subscribe to various events relating to orders - particularly the NewOrder webhook. If subscribed, ZEST will send a push notification to your app every time a new order is created, saving your app from having to frequently poll for new orders.

Order fields

  • order_number - the unique key for this resource, a number assigned to the order
  • username - what Customer placed the order. If it was an anonymous customer, the checkout process automatically creates them a customer record.
  • email - customer email address
  • phone_day - the customer's specified phone number
  • status - the order status
  • order_date - a timestamp for when the order was placed
  • update_date - date the order was last updated
  • payment_method - which payment method was chosen / used
  • po_number - if payment method was purchase order, a purchase order supplied by the customer
  • order_id - the order reference number provided to the payment provider. E.g. this should be shown in the payment providers statement and can be used to match up payments to orders placed on the website.
  • coupon_code - any coupon code that was applied against the order
  • comments - comments (or gift note on some websites) provided by the customer
  • delivery_date if the website provides a field for a customer to request a delivery date, it will be stored in this field
  • currency_code - currency the order was processed in (if the website has multicurrency enabled)
  • archived - is the order been archived? Marking the order as archived, will remove it from the pending orders list in the ZEST administration tool.
  • deleted - mark the order as deleted.
  • integrated - this is a useful field for your app to flag that you have synced it. Future GETs to this resource can specify ?integrated=0 to pull ones not marked as having been synchronised.
  • Primary (billing) customer details / address fields:
    • b_company - company name
    • b_fname - first name
    • b_lname - last name
    • b_address1 - address 1
    • b_address2 - address 2
    • b_address3 - address 3
    • b_city - city
    • b_state - state
    • b_zip - postcode
    • b_country - country code
  • Shipping customer data / address fields (if different):
    • company - company name
    • fname - first name
    • lname - last name
    • address1 - address 1
    • address2 - address 2
    • address3 - address 3
    • city - city
    • state - state
    • zip - postcode
    • country - country code
  • Shipping & Totals
    • nitems - total number of items in the order
    • shipmode - what shipping method was chosen (as relates to a Shipping resource entry).
    • shipping - total shipping cost
    • salestax - total tax cost
    • total_cost - formatted total cost value (with currency symbols etc)
    • total_numeric - the total cost of the order (as a float)
    • total_converted_default_currency - if the website offers multiple currencies, this field will store the total cost of the order as a float, converted into the website's default currency at the current exchange rate.

Example - Syncing orders to an ERP system

Generally if you are wanting to sync an order to an ERP system, the first & easiest approach is to subscribe to the NewOrder webhook. While that incoming push notification does contain some order data in its JSON payload, you often will want to pull the full order data including relevant related resources using the following resource specification:

GET /API/V3/Order+Orderline+OrderlineTax+OrderlineDiscounts/ORD000123

... assuming an order_number of ORD000123. This will pull generally all the order data needed to generate an invoice or some other entry in the system you are syncing the order to.

Once you have processed that order, you should update the order in ZEST to set the integrated field to true:

PUT /API/V3/Order/ORD000123
<ResultSet>
    <Order>
        <order_number>ORD000123</order_number>
        <integrated>true</integrated>
    </Order>
</ResultSet>

This allows us to introduce a level of fault tolerance in case for some reason the attempt to sync a record failed (e.g. the destination API may have been offline temporarily or some other reason) - should we want to retrieve any unsynchronised orders at a later date.

Updated order email notifications

The Order resource has been extended to provide the ability to automatically send an email to the customer to notify them of an updated order status. To make this happy, simply add a querystring to your POST request setting send_email=true.

E.g.

POST /API/V3/Order?send_email=true
<ResultSet>
    <Order>
        <order_number>ORD000123</order_number>
        <status>Back Order</status>
    </Order>
</ResultSet>

Example - creating shipments & sending shipment notifcations

If you need to create a shipment to process an order in ZEST, you can do so by POSTing to the Shipments resource documented below.

For example:

POST /API/V3/Shipments+ShipmentLines
<ResultSet>
    <Shipment>
        <order_number>ORD0000027</order_number>
        <courier>Post haste</courier>
        <tracking_link>http://www.posthaste.co.nz</tracking_link>
        <tracking_number>988000088</tracking_number>
        <date>2013-10-02 17:05:32</date>
        <notes>
            Thanks for your order Peter :). Enjoy the watch!
        </notes>
        <ship_all>1</ship_all>
        <send_email>1</send_email>
        <archive>1</archive>
    </Shipment>
</ResultSet>

This will send a notification update to the email address on the order with a default subject of Shipment for your order <order_number>. If you want to override this, you can specify email_to and email_subject nodes as documented below.

Related resources

Order data is stored across a number of resources, so understanding the various resources and how they relate to each other is important to being able to effectively work with this area.

The main resources related to an order include:

Orderlines 1:M

Every order will have one or more orderlines - storing the products that were ordered, how many etc.

The main fields for an orderline include:

  • code - primary key - a unique string, of the format <order_number>-<increment>. So the first orderline for ORD00123 will be ORD00123-1.
  • order_number - the key for the Order this line relates to.
  • sku - the Product sku or Variant code relating to what was purchased
  • description - the Product title when the order was placed
  • price - a currency formatted string of the unit price
  • quantity - int - how many were purchased
  • subtotal - a formatted (according to currency) version of the subtotal
  • subtotal_numeric - the orderline subtotal as a float
  • subtotal_converted_default_currency - if the website supports multiple currencies, this will store the total value of the orderline converted to the default currency using the exchange rate at the time the order was placed.
  • total_weight - total weight of the orderline
  • status - each individual Orderline can have a status, allowing orders to be partially shipped.
  • options - if the product supported Options at the time of purchase, this field will store in plain text what values the options were set to (for simple options), or the variant description (for advanced options or subproducts)
  • update_date - timestamp for when the orderline was last updated
  • custom_data1 to custom_data4 - these are blank fields that are not used by our software, and exist for 3rd party developers needing to store additional adhoc data against an orderline. Feel free to use them - just be sure they're not being used by another integration.

OrderlineDiscounts 1:M

If any kind of discount was applied to the Order (as a whole), or a particular Orderline, an entry will be made into this resource - one for each situation. This resource allows you to analyse the discounts that were made to understand how the final prices were reached for various Orderlines, or the Order as a whole.

The main fields for this resource are:

  • code - unique key - auto incrementing int.
  • orderline_code - either the code of the Orderline this discount relates to, or a the string TOTAL_COST or ENTIRE_ORDER - indicating a coupon that was applied to the totals of the order (but not affecting individual orderlines).
    • TOTAL_COST means the coupon applied to the entire order, including the shipping cost.
    • ENTIRE_ORDER means the coupon applied to the entire order, but excluding the shipping cost.
  • order_number - the Order entry this relates to.
  • discount_type - what sort of discount was applied. Discount types include:
    • userdb - this means the discount was a result of either the site being configured to apply a 'global member discount' (for all members), or an individual Customer had a discount set against their entry.
    • merchandising - an individual product had a discount applied to it (see the Merchandising resource).
    • coupon - the order had a coupon applied to it which resulted in a discount being applied to specific products in an order (in this case the orderline_code will be pointing at an orderline), or to the totals of the order (in which case the orderline_code would be set to TOTAL_COST or ENTIRE_ORDER - indicating it modified the order itself, not any particular individual orderline).
  • discount_description - a plain text description of the coupon type.
  • discount_amount_numeric - if the discount was a numeric amount, that amount as a float
  • discount_percentage - if the discount was a percentage, the percentage as an int - i.e. 50 = 50% discount.
  • price_original_numeric - the undiscounted price of the product (or order for entire order coupons) as a float
  • price_discounted_numeric - the discounted price of the product (or order for entire order coupons) as a float
  • Amounts converted to the default currency of the website at the time of the order (if the website supported multiple currencies):
    • discount_amount_converted_default_currency - if the discount was a numeric the discount amount when converted to the default website currency. price_original_converted_default_currency - the undisounted product (or order for entire order coupons) price converted to the default website currency.
    • price_discounted_converted_default_currency - the discounted price of the product (or order for entire order coupons) converted to the default website currency.

OrderlineTax 1:M

This resource stores data relating to what tax was applied to an order, and how it was calculated.

Relevant fields include:

  • code - unique key - auto incrementing int.
  • order_number - the order_number for the Order this entry relates to.
  • tax_code - what tax area or tax code was used to determine what rate to use (configured under Preferences > Tax/GST in the ZEST administration tool).
  • rate - what tax rate was applied to the order as - a percentage as a string - eg. 15%
  • price - the numeric amount of tax that was applied to the order, as a float - e.g. 4.95
  • tax_incl - did the orderlines / subtotal already include tax?
  • tax_shipping - was the shipping cost included in the tax calculation?

Shipments 1:M

This resource is used to track the shipping of an order. When an order is processed, ZEST allows you to create a shipment to record data about what was shipped (stored in ShipmentLines), what provider, tracking numbers etc.

An Order may have one or more Shipments related to it (to cover partial shipments).

If you integrating a shipping provider into ZEST so that orders automatically are processed when the shipment is received, you will be wanting to create Shipment and ShipmentLines entries, as well as updating the order itself. The interface in the ZEST order processing tools looks like this:

image

Relevant fields include:

  • code - unique key - auto incrementing int.
  • order_number - the order_number for the Order this entry relates to.
  • date - a timestamp of when the shipment was created / sent.
  • courier - the name of the shipping provider.
  • tracking_number - the tracking number provided by the shipping provider / courier service.
  • tracking_link - the tracking link provided by the shipping provider / courier service.
  • send_email - should we send an email to the customer notifying them of the update to the order?
  • email_to - what address we should send the email to.
  • email_subject - a subject line for the email notification
  • notes - a note to send with the shipment email if notifying the customer.
  • ship_all - should we automatically mark all orderlines in this order as shipped?
  • archive - should we automatically archive the order so it is removed from the "pending orders" list?

The send_email, email_to, email_subject are only used when POSTing a shipment. So these nodes will be black in any GET request to the resource reading shipment data.

ShipmentLines 1:M

Each Shipment can have one or more lines relating to the actual Orderlines included in the shipment.

Each ShipmentLine will include the following fields:

  • code - unique key - auto incrementing int.
  • shipment_code - the code for the Shipment this line relates to.
  • orderline_code - the code for the Orderline that this bieng shipped.
  • qty - how many of the sku the Orderline was representing are included in the shipment?