Understanding Orders
Published by Steve Davis on March 9, 2016
Last updated on January 14, 2022
The central concept within OrderCloud is not surprisingly the order. This is the object where buyers, sellers, products, payments, and almost everything come together to form a business transaction.
Order Direction
A key feature of the Order resource is the order "direction". The endpoints used to interact with the order resource are the same endpoints you use regardless of which type of user you are: buyer, Marketplace Owner (MPO), or supplier. What changes however is the order direction. A good way to think about order direction is to first think about how an order moves from the entity that submits the order all the way through to the entity that fulfills the order and then think about how direction appears from a specific user's perspective.
Buyer to MPO Order Transaction
The simplest way a transaction can occur in OrderCloud is from a buyer directly to an MPO. In this scenario, the optional supplier entity is not present, and a diagram of the flow can be depicted like this:
Buyer ➔ MPO
From the buyer's perspective, the Order is "Outgoing", and conversely from the MPO's perspective the order is "Incoming".
Order Forwarding Order Transaction
If an order can contain line items with products from many suppliers (product.DefaultSupplierID
) then an order can be forwarded to each supplier. This means that the order flows through the seller, but then immediately goes to each supplier for fulfillment. Now our diagram now looks like this:
Buyer ➔ MPO ➔ Supplier
The flow is essentially the same for the buyer, however now the MPO can see orders coming to them from the buyer by using the "Incoming" order direction, and additionally can see orders going to the supplier by using the "Outgoing" order direction. Both "Incoming" and "Outgoing" orders mean something to the MPO
Buyer to Supplier Order Transaction
As of API 1.0.214 it is possible to submit orders from a buyer directly to a supplier. Now our diagram looks like this:
Buyer ➔ Supplier
The buyer sees a direction of "Outgoing", and the supplier sees a direction of "Incoming" however the MPO is left completely out of the flow. Remember though that the MPO, as the owner of the Marketplace, must have visibility to orders even if they aren't directly involved in the transaction. To support this, we've introduced the order direction "All". The "All" direction, can be used by any entity (buyer, seller, supplier) and will appropriately select the correct direction for that entity. MPOs can and should still use "Incoming"/"Outgoing" if they have marketplaces where orders are forwarded.
Statuses
Throughout a workflow an order undergoes various status changes:
Unsubmitted: Created but has not yet been submitted
Open: Submitted but not yet fulfilled
AwaitingApproval: On hold awaiting approval
Declined: Submitted but has been declined
Completed: Submitted and all the line items on the order have been shipped
Canceled: Order can no longer be submitted
Once an order is canceled, it is effectively DEAD and no further actions can be taken on it
We've made it easy for you by tracking these changes as well as the time the status changes. A status is often time changed by the API automatically under certain conditions (e.g. all the quantities on all the lines are shipped so the platform changes the order status to 'Complete')
Gratuity
Allow the shopper to add a gratuity or tip to the order. This property must be a positive decimal, but is not required. This property could be used to support donations or other choose-your-own-price functionality.
Unsubmitted Order Cleanup
As a means of ensuring top notch performance, OrderCloud routinely removes unsubmitted orders based on a combination of factors that are outlined below. This policy does not apply to orders that have been submitted.
User Type | Has Line Items? | Retention Policy |
---|---|---|
All | No | 24 hours |
Anonymous | Yes | 7 Days |
Profiled | Yes | 90 days from LastUpdated date |
Interactions with other resources
As we mentioned, almost every resource in OrderCloud interacts with the order and it is these relationships and actions between the resources and the order that really give meaning to an order.
Let's highlight some of the most common resources that interact with the order. This is a non-exhaustive list that is meant to give you quick insight into the power of OrderCloud. For more information we recommend diving into the feature documentation or even perusing other features that aren't specifically mentioned here but that also interact with the order.
OrderCloud Resource | Problem it solves |
---|---|
Price Schedules | Define rules for how a product can be ordered (quantities for example) |
Buyer Addresses | Only allow users to select from a list of approved billing/shipping addresses |
Promotions | Deduct some amount from an order if a user's order meets certain requirements |
Payments | Allow a user to pay for an order with a payment method of their choosing |
Approvals | If an order meets some criterea route the order on hold for approval |
Shipments | Break an order up into multiple shipments |
Still have questions?
Ask in our Community Channel