Integrating Your Service with the Order Desk API

Why Connect to Order Desk via API?

Order Desk receives about 15 integration requests a month and we unfortunately don’t always have the time or resources to build them. That being said, it might benefit your company to establish its own connection directly to Order Desk to automate and manage your order fulfillment workflow.

When an internal build isn’t feasible for our team, you can connect to us via our API instead! Connecting via API allows your company to have control over the integration you build to Order Desk, with the added bonus of not having to wait for us to allocate development time to you.

If you’d prefer that we build an integration to your company, we outline our process for reviewing integrations requests here in our Life of An Integration Request blog post.

Introduction

The information flow for connecting to Order Desk via API is fairly simple, and there are a few key endpoints and Order Desk rules which can help facilitate and streamline this process. Depending on your goals, you can achieve almost all functionality that you would have if we built an integration to your service.

Many of the concepts revolve around understanding and repeating the same simple process of triggers (events) and webhooks (via rules). Once you become familiar with those concepts, you can apply your knowledge to almost every connection needed between your service and Order Desk.

As you begin this process, it will be valuable to spend a little time getting to know how events and rules work inside Order Desk. Here are some helpful resources to learn a bit more about each of those:

• The Order Desk Rule Builder
• Rules Reference: Events, Filters and Actions
• How to Post Order Information to a Custom Script

If you see anything in the guides about Order Desk that you don’t quite understand, our support team can be reached here to answer any questions. Developer support is outside the scope of our support team (that’s why this requires having your own developer) but our developers tend to be available to answer your (and their) questions relating to our API.

Getting Connected

In order to integrate your cart with our API, you’ll need two things:

• An Order Desk subscription: We have 3 pricing plans, each with its own benefits. Our pricing options are built with businesses of all sizes in mind and if you need time to explore Order Desk, every store includes a 30-day free trial. 🙂

• A developer: To build the integration to our API, you’ll need your own developer.

Once you have an Order Desk store and a developer, you’re ready to get started! You can find our API Docs here.

Sending Orders to Order Desk

Method: POST

Endpoint: **https://app.orderdesk.me/api/v2/orders**

To import an order from your marketplace to Order Desk you’ll need to use the /orders endpoint with the full order payload. Once submitted, the order will be created inside Order Desk. This is the best time to to pass along any information you wish to use with a potential rule as part of the order’s metadata or checkout data. Item specific information can be placed inside the item’s metadata or variation list.

Sending Orders from Order Desk to Your Service

Event: Dependent on requirements

Rule Action Post Order JSON

Full order information can only be sent from Order Desk to the chosen endpoint or service if a rule is set up to do so. This payload will contain all the order and shipment details. Your endpoint needs to return a valid status code for how this has been received.

If the order was successfully received into your system, please provide a 200 response.

If the order failed to input because your system is temporarily unavailable, please produce a 500 status code. We will reattempt these submissions up to 10 times or until we receive a 200 response. At that time, we will stop resubmitting and the request will be marked as permanently failed. It can be retried manually at a later time from the Appointments Page. Please note that any permanent errors inside your system should return a 200 so that we stop retrying.

Shipping Orders

Method: POST

Endpoint: https://app.orderdesk.me/api/v2/orders/<order_id>/shipments

To add a shipment to an order within Order Desk, you’ll need to send the shipment payload to the endpoint that contains the internal (Order Desk) ID of the order to which it should be added.

A successfully imported shipment will trigger the “Shipment Added” event. If your workflow includes rules or actions that run on this event, they will be triggered at this time.

Getting Shipments Back to Your Service

Event: Dependent on requirements

Rule Action Post Order JSON

This process works the same as sending orders to your service. You’ll need to create a rule with the Post Order JSON action to submit the entire order, including shipments, back to the endpoint of your choice.

If the shipment was successfully received by your system, please provide a 200 response.

If the shipment failed because your system is temporarily unavailable, please produce a 500 status code. We will reattempt these submissions up to 10 times or until we receive a 200 response.

As an alternative method, you can set your webhook endpoint url as an order metadata value with the key ship_notify_url and we will send any shipments to that url. You can learn more about that process and see a sample payload here.

Working with Inventory

Method: POST

Endpoint: **https://app.orderdesk.me/api/v2/inventory-items**

The Order Desk API supports creating and updating inventory items. You can also manage inventory items through CSV files, either through email or automated FTP pickup. Inventory management at Order Desk has many paths and, as such, it’s better to look at the resources below to learn how to work with inventory.

• How to Work with Inventory Details
• Store Settings: Inventory
• Inventory, Templates, and Users Video

Making It All Work Together

For Fulfillment Services

If you will be submitting orders from Order Desk to your service for fulfillment and sending shipments back to Order Desk, your workflow might look like this:

1. Your Order Desk store receives orders manually or from a cart integration.
2. You create an event, such as “Order Created” or “Order Imported” which will run the rule to send the newly added order to your custom endpoint.
3. Your custom endpoint has code to accept the order.
   1. Your custom endpoint will use the API to move the order to a folder (e.g. Prepared, In Process, etc.) to show that the order was accepted by your system.
4. Once the order has been fulfilled and has a tracking number ready, you create a shipment using the Order Desk API.
5. Depending on how the order arrived at Order Desk, the shipment information can automatically sync back to the originating cart using integration settings. Alternatively, a rule can be used to send the processed shipments back to the cart.

For Carts & Marketplace Services

If you are sending orders to Order Desk for fulfillment from your service and you need shipment information to be sent back to your service when shipped, your workflow might look like this:

1. You submit an order to the Create Order endpoint using the Order Desk API.
2. Your store will have an event, such as “When Order is Created” with an action that sends the order on to your desired fulfillment service.
3. The fulfillment service will notify Order Desk of shipment and provide us with a tracking number.
4. You’ll set up the Post Order JSON action on the Shipment Added event to submit the full order and shipment to your given endpoint.
5. Your endpoint receives the payload an adds the shipment to your service.

Summary

The Order Desk API in combination with the Order Desk Rules Engine provides a very flexible way to create a form of private integration to Order Desk. This is best suited to those who understand how Order Desk works and want to use their internal resources to interface with Order Desk and its third party connections. As such, it’s advisable for your developer to spend some time in an Order Desk store to be able to grasp the basic concepts and explore the many different possible workflows to support the needs of your service.

Our technical team is available to help with everything in this walkthrough, including guidance when it comes to setting up such a workflow. We can be reached via the general support page here.

FAQ

Why do I need my own developer to integrate my service to Order Desk?

It takes some time (and testing!) to get a connection to our API up and running to each service’s unique specifications. A dedicated developer is necessary to ensure things run smoothly, and although our team will be on hand to answer questions and provide resources, we are unable to create the connection for you. If you’d like to request that we build an integration to you, you can do so here.