Requesting Orders - Quick Start Guide
- Order Webhook
- Pull Orders By Date Range
- Pull Orders By Order Number
- Order Workflow & Order Acknowledgement
- Order Workflow with No Order Acknowledgement
- Miva Order Data Architecture
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.
Authenticated endpoints are not currently supported at this time.
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.
Example:
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.
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 to/ ship to 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.
Example:
Order Workflow + 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
Order Workflow with 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.
Miva Order Data Architecture
Below is a diagram of the Miva Order Data Architecture
