Quick Start Guide

---

Order Integration Methods

Order Webhook

An order webhook is a great way to automatically have Miva push order data (in JSON format) to any external endpoint. When using a webhook the entire order object will be sent. You cannot leverage ondemandcolumns to pick and choose which data will be sent. You also cannot customize the JSON format of the object.

The most common way to consume a Miva Order Webhook will be to create a custom endpoint which Miva will send data to as either a POST or GET request. Your system will parse the JSON object and save it into its system.

Webhooks can be triggered on any available order trigger including Order Create or order update.

Note

To properly handle orders created in the admin it’s important ensure that any webhook has a condition which checks for an Order Complete state. This is best done by checking if there is at least 1 payment record. You’ll need to leverage Miva’s Order Workflow Wait Until True settings which will attempt check the order every X minutes until the condition is met (in this case, the order has a payment record). This way the webhook is not sent for orders created in the admin until the order is completed and has been paid.

Pull Orders By Date Range

Pulling orders by date range is a great way to query new orders from Miva. Miva keeps track of the data/time the order was place and using the OrderList_Load_Query function and a Filter you can send a request to miva and pass in the unix timestamp form the last time you queried orders.

{
    "Miva_Request_Timestamp": "1535646272",
    "Store_code": "beta",
    "Function": "OrderList_Load_Query",
    "Count": "0",
    "Offset": "0",
    "Filter": [
        {
            "name": "search",
            "value": [
                {
                    "field": "orderdate",
                    "operator": "GE",
                    "value": "1218067200"
                }
            ]
        },
        {
            "name": "ondemandcolumns",
            "value": [
                "payment_module",
                "cust_pw_email",
                "cust_login",
                "ship_method",
                "customer",
                "items",
                "charges",
                "coupons",
                "discounts",
                "payments",
                "notes",
                "CustomField_Values:customfields:*",
                "payment_data"
            ]
        }
    ]
}

What you don’t get by using this method is orders which have been updated after they have been downloaded. If you need updated orders as well, you need to take advantage of Miva Order Workflows.

Query By Last Order Update

As of 10.03.00 Miva now tracks a Order Last Updated timestamp. Learn More. Using this value its possible to query Miva to get both new and updated orders since the last time the request was made.

Pull Orders By Order Number

Its also possible to query Miva orders by order numbers. However there is one big caveat here.

Note

Miva’s Orders are not guaranteed to be sequential and orders numbers are skipped.

An order number in Miva gets assigned to a basket once a customer has submitted their Bill To / Ship To information. If they abandoned the cart after that point, the order number is also abandoned.

Also, if one customer gets past the bill/ship step but then decides to leave checkout and continue shopping for the next 10 minutes, there will be 10 minutes of orders number ahead of it.

A common way to ensure no orders are skipped when querying by order number is to create intentional order number overlap at each pull. For example, if the last order number downloaded was 1045, then on the next query you would want all orders from 1046 and above. However to avoid missing orders you would actually query back 20 or 30 orders to 1020. The busier the store the larger range you’ll want to query back.

{
    "Miva_Request_Timestamp": "1535646272",
    "Store_code": "beta",
    "Function": "OrderList_Load_Query",
    "Count": "0",
    "Offset": "0",
    "Filter": [
        {
            "name": "search",
            "value": [
                {
                    "field": "id",
                    "operator": "GE",
                    "value": "200098"
                }
            ]
        },
        {
            "name": "ondemandcolumns",
            "value": ["payment_module", "cust_pw_email", "cust_login", "ship_method", "customer", "items", "charges", "coupons", "discounts", "payments", "notes", "CustomField_Values:customfields:*", "payment_data"]
        }
    ]
}

Order Acknowledgement

Setting up an Order Workflow with Order Queues allows Miva to keep track of all new and updated orders for you. Each time you pull orders, you will be pulling orders from a specific queue which only contains new orders and updated orders since the last time you queried orders.

The Workflow in Miva handles the heavy lifting so that when a new order gets created or an order gets updated, it automatically gets put into the correct queue to be downloaded then next time you query for orders in that queue.

When using an Order Workflow with an Order Acknowledgement, Orders are left in the “New and Updated Orders” queue until and separate order acknowledgement request is received. This two way communication ensures that there are no orders lost in transit should there be any problems downloading or receiving the orders into the external system

No Order Acknowledgement

This process is similar as above except the main difference is that there is not a second request which needs to be made to Miva to Acknowledge that the order was received. Instead the Order download immediately removes each order from the “New and Updated Orders” queue into the “Order Received” queue.

Order Data Architecture

Below is a diagram of the Miva Order Data Architecture