NAV
PHP cURL

Introduction

Order Desk provides an API for programatic access to your store’s data.The Order Desk API is a RESTful API that accepts and returns JSON. You can use the API to pull order status, add orders, add shipments, and retrieve inventory items.

API Usage and Availability

While we endeavor to ensure that the API has 100% uptime, the API access should not be assumed. It’s best to connect to the Order Desk API in a background process on your end and not through a customer-facing interface. For example, don’t import orders into Order Desk and then wait for a response as part of your shopping cart’s order flow. A better method would be to import orders into your order system and then set up a cron job on your end to attempt to import these orders into the Order Desk API in an asynchronous process.

PHP Client

If you are developing in PHP, we have a helper client available.

Authentication

In order to connect to the Order Desk API, go to the Store Settings and click on the API tab to create an API Key. You’ll be presented with an API Key and Store ID. You’ll need to add both of these details as headers to each request that you make to the API along with the correct content-type request.

Required Headers

Name Value
ORDERDESK-STORE-ID your store id
ORDERDESK-API-KEY your api key
Content-Type application/json

Querying the Testing Endpoint

Make sure the connection is successful and return the system time

GET
https://app.orderdesk.me/api/v2/test
<?php
include "order-desk-api-client.php";
$od = new OrderDeskApiClient($storeid, $apikey);
$result = $od->get("test");
echo "<pre>" . print_r($result, 1) . "</pre>";
?>
curl "https://app.orderdesk.me/api/v2/test"
  -H "ORDERDESK-STORE-ID: storeid"
  -H "ORDERDESK-API-KEY: apikey"
  -H "Content-Type: application/json"

Response:

{
  "status": "success",
  "message": "Connection Successful",
  "current_date_time": "2015-04-14 22:00:10"
}

Returned Fields

Attribute Value
status success
message Connection Successful
current_date_time System time in UTC

Orders

Order Properties

{
  "id": "26211",
  "email": "test@orderdesk.me",
  "shipping_method": "FedEx Home Delivery",
  "quantity_total": 1,
  "weight_total": 1,
  "product_total": 10,
  "shipping_total": 11.17,
  "handling_total": 0.5,
  "tax_total": 1.2,
  "discount_total": 1.7,
  "order_total": 21.17,
  "cc_number_masked": "xxxxxxxxxxxx4242",
  "cc_exp": "02\/2016",
  "processor_response": "Authorize.net Transaction ID: 2221864944",
  "payment_type": "Visa",
  "payment_status": "Approved",
  "processor_balance": 21.17,
  "customer_id": "5487542",
  "email_count": "3",
  "ip_address": "254.565.44.15",
  "tag_color": "",
  "source_name": "Order Desk",
  "source_id": "412218073",
  "fulfillment_name": "",
  "fulfillment_id": "",
  "tag_name": "success",
  "folder_id": 1,
  "date_added": "2014-10-08 12:10:00",
  "date_updated": "2014-10-09 23:13:47",
  "shipping": {
    "first_name": "Jimmy",
    "last_name": "Dean",
    "company": "",
    "address1": "800 Emmet St",
    "address2": "",
    "address3": "",
    "address4": "",
    "city": "Nashville",
    "state": "TN",
    "postal_code": "55555",
    "country": "US",
    "phone": ""
  },
  "customer": {
    "first_name": "Bingo",
    "last_name": "Little",
    "company": "",
    "address1": "900 Lord Business Ave",
    "address2": "",
    "city": "Knoxville",
    "state": "TN",
    "postal_code": "77777",
    "country": "US",
    "phone": ""
  },
  "return_address": {
    "title": "Acme",
    "name": "Doug Jones",
    "company": "Acme Manufacturing",
    "address1": "817 E Maple Ln",
    "address2": "",
    "city": "Knoxville",
    "state": "TN",
    "postal_code": "55555",
    "country": "US",
    "phone": ""
  },
  "checkout_data": {
    "Gift Message": "Happy Birthday"
  },
  "order_metadata": {
    "fraud_protection_score": 0
  },
  "discount_list": [
    {
      "name": "Discount",
      "code": "MN234DX78",
      "amount": "1.70"
    }
  ],
  "order_notes": [
    {
      "date_added": "2014-10-09 23:12:05",
      "username": "Customer Service Rep",
      "content": "Customer called to change shipping address"
    }
  ],
  "order_items": [
    {
      "id": "42286",
      "name": "Crazy Glue",
      "price": "10",
      "quantity": 1,
      "weight": 1,
      "code": "crzyg-554",
      "delivery_type": "ship",
      "category_code": "DEFAULT",
      "variation_list": {
        "Size": "Small",
        "Color": "Black"
      },
      "metadata": {
        "image": "image_url_here"
      }
    }
  ],
  "order_shipments": [
    {
      "id": "369",
      "order_id": "26211",
      "store_id": "11",
      "tracking_number": "1Z132456789",
      "carrier_code": "",
      "shipment_method": "",
      "weight": "0",
      "cost": "0",
      "status": "",
      "tracking_url": "",
      "label_format": "",
      "label_image": "",
      "order_items": "",
      "print_status": "1",
      "cart_shipment_id": "",
      "date_shipped": "2014-10-09",
      "date_added": "2014-10-09 23:08:49"
    }
  ]
}

Every order is returned as a JSON collection.

Order Properties

Attribute Description
id Order Desk’s internal ID # read-only
source_id Your order ID. If blank, Order Desk’s internal ID will be used read-only
source_name Pick from Available Source Names. Defaults to Order Desk
source_id The original ID # of the order. If nothing entered, Order Desk’s internal ID number will be used
email Customer’s email address
shipping_method Name of shipping method selected
quantity_total The total number of all the items in the order read-only
weight_total The total weight of all the items in the order read-only
product_total The total price of all the items in the order read-only
shipping_total The total price of shipping in the order
handling_total The total price of handling in the order
tax_total The total price of tax in the order
discount_total The total price of all the discounts in the order stored as a positive number read-only
order_total The total calculated price of the entire order read-only
cc_number Obfuscated credit card number. Enter only the last four digits
cc_exp Credit card expiration in format MM/YYYY
processor_response Gateway transaction ID in format <gateway_name>: <transaction_id>
payment_type Visa, MasterCard, PayPal, etc.
payment_status Available options: Approved, Authorized, Captured, Fully Refunded, Partially Refunded, Pending, Rejected, or Voided. Default is Captured
processor_balance The amount that the was charged at the processor. This amount will be decremented when refunds are made. By default it will be set the same as order_total
customer_id The customer ID field from the originating shopping cart
email_count The number of orders that match this email address read-only
ip_address The customer’s IP address
tag_color Not In Use
tag_name Not In Use
fulfillment_name Once the order has been sent for fulfillment, the name of the fulfillment method is entered here
fulfillment_id The internal ID of the fulfillment service will be saved here for some services
folder_id The ID number of the folder in which the order is stored. If nothing is entered when adding an order, the folder will be the first folder in the list
date_added The order date stored in UTC
date_updated The date that the order was last updated in UTC
checkout_data Array with a list of extra order details in key => value format. Used when it may need to be manually edited in Order Desk.
order_metadata Array with a list of extra (hidden) order details in key => value format
shipping Array with shipping address details. If nothing is entered, the customer array will be copied to the shipping array. A first and last name combination or a company name must be entered to be a valid order.
customer Array with customer address details. If nothing is entered, the shipping array will be copied to the customer array. A first and last name combination or a company name must be entered to be a valid order.
return_address Array with return address details. Not required.
discount_list Array with a list of discounts. See discount properties for reference.
order_notes Array with a list of order notes. See order note properties for reference.
order_shipments Array with a list of order shipments. See order shipments properties for reference.

Order Item Properties

See Reference Here

Address Properties

A valid order requires either the first and last name OR the company name to be entered.

Attribute Description
first_name First Name
last_name Last Name
company Company
address1 Street Address 1
address2 Street Address 2
address3 Street Address 3 (not available for customer address)
address4 Street Address 4 (not available for customer address)
city City
state State or Region
postal_code Zip or Postal Code
country Country (either country code or full country name)
phone Phone Number

Return Address Properties

If the order has a custom return address, it will be entered here. This can be set via rule or set when the order is inserted via the API.

Attribute Description
title The Title of the Return Address
name Shipping Name
company Company
address1 Street Address 1
address2 Street Address 2
city City
state State or Region
postal_code Zip or Postal Code
country Country (either country code or full country name)
phone Phone Number

Discount Properties

Attribute Description
name Name of discount
code Code used for discount optional
amount The discount amount. Discounts should be stored as positive numbers.

Order Note Properties

There is a 2000 character max for all notes, including date and username metadata so keep your notes under 1800 characters to avoid data loss.

Attribute Description
date_added Date that the note was added in UTC
username Name of the person who wrote the note
content Note content

Get a Single Order

HTTP Request

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

The order_id field refers to Order Desk’s internal ID.

<?php
include "order-desk-api-client.php";
$od = new OrderDeskApiClient($storeid, $apikey);
$result = $od->get("orders/736745");
echo "<pre>" . print_r($result, 1) . "</pre>";
?>
curl "https://app.orderdesk.me/api/v2/orders/736745"
  -H "ORDERDESK-STORE-ID: storeid"
  -H "ORDERDESK-API-KEY: apikey"
  -H "Content-Type: application/json"

Response

{
  "status": "success",
  "message": "Execution took 0.0208 seconds",
  "order": {
    "id": "925086",
    "email": "myemail@server.com",
    "shipping_method": "",
    "quantity_total": 1,
    "weight_total": 2.375,
    "product_total": 19,
    "shipping_total": 0,
    "handling_total": 0,
    "tax_total": 0,
    "discount_total": 0,
    "order_total": 19,
    "cc_number_masked": "xxxxxxxxxxxx4242",
    "cc_exp": "02/2016",
    "processor_response": "Authorize.net Transaction ID:2231994036",
    "payment_type": "Visa",
    "payment_status": "Approved",
    "processor_balance": 19,
    "customer_id": "8173875",
    "email_count": "3",
    "ip_address": "181.16.150.12",
    "tag_color": "",
    "source_name": "FoxyCart",
    "source_id": "648714418",
    "fulfillment_name": "",
    "fulfillment_id": "",
    "tag_name": "",
    "folder_id": 64,
    "date_added": "2015-04-15 12:12:10",
    "date_updated": "2015-04-15 15:32:04",
    "shipping":
    {
      "first_name": "Jimmy",
      "last_name": "Dean",
      "company": "",
      "address1": "800 Emmet St",
      "address2": "",
      "address3": "",
      "address4": "",
      "city": "Nashville",
      "state": "TN",
      "postal_code": "55555",
      "country": "US",
      "phone": "208-555-5555"
    },
    "customer":
    {
      "first_name": "Bingo",
      "last_name": "Little",
      "company": "",
      "address1": "900 Lord Business Ave",
      "address2": "",
      "city": "Knoxville",
      "state": "TN",
      "postal_code": "77777",
      "country": "US",
      "phone": "208-555-5555"
    },
    "return_address": {
      "title": "Acme",
      "name": "Doug Jones",
      "company": "Acme Manufacturing",
      "address1": "817 E Maple Ln",
      "address2": "",
      "city": "Knoxville",
      "state": "TN",
      "postal_code": "55555",
      "country": "US",
      "phone": ""
    },
    "checkout_data": {
      "Order Notes": "Please leave by back door"
    },
    "order_metadata": {
      "fraud_protection_score": 0
    },
    "discount_list": [],
    "order_notes": [],
    "order_items": [
      {
        "id": "1670028",
        "name": "Subscription Product",
        "price": 19,
        "quantity": 1,
        "weight": 2.375,
        "code": "126478",
        "delivery_type": "ship",
        "category_code": "DEFAULT",
        "variation_list": [],
        "metadata": {
          "image": "http://img1.wikia.nocookie.net/__cb20130318151721/epicrapbattlesofhistory/images/6/6d/Rick-astley.jpg"
        }
      }
    ],
    "order_shipments": []
  }
}

Get Multiple Orders

HTTP Request

GET
https://app.orderdesk.me/api/v2/orders
<?php
include "order-desk-api-client.php";
$od = new OrderDeskApiClient($storeid, $apikey);
$args = array(
  "source_name" => "FoxyCart",
  "search_start_date" => "2015-04-15 12:05:06",
  "order_by" => "shipping_last_name",
);
$result = $od->get("orders", $args);
echo "<pre>" . print_r($result, 1) . "</pre>";
?>
curl "https://app.orderdesk.me/api/v2/orders"
  -H "ORDERDESK-STORE-ID: storeid"
  -H "ORDERDESK-API-KEY: apikey"
  -H "Content-Type: application/json"
  -d "source_name=FoxyCart&search_start_date=2015-04-15%2012:05:06&order_by=shipping_last_name"

Response

{
  "status": "success",
  "message": "Execution took 0.0208 seconds",
  "total_records": 1,
  "records_returned": 1,
  "offset": 0,
  "limit": 50,
  "orders": [
    {
      "id": "925086",
      "email": "myemail@server.com",
      "shipping_method": "",
      "quantity_total": 1,
      "weight_total": 2.375,
      "product_total": 19,
      "shipping_total": 0,
      "handling_total": 0,
      "tax_total": 0,
      "discount_total": 0,
      "order_total": 19,
      "cc_number_masked": "xxxxxxxxxxxx4242",
      "cc_exp": "02/2016",
      "processor_response": "Authorize.net Transaction ID:2231994036",
      "payment_type": "Visa",
      "payment_status": "Approved",
      "processor_balance": 19,
      "customer_id": "8173875",
      "email_count": "3",
      "ip_address": "181.16.150.12",
      "tag_color": "",
      "source_name": "FoxyCart",
      "source_id": "648714418",
      "fulfillment_name": "",
      "fulfillment_id": "",
      "tag_name": "",
      "folder_id": 64,
      "date_added": "2015-04-15 12:12:10",
      "date_updated": "2015-04-15 15:32:04",
      "shipping": {
        "first_name": "Jimmy",
        "last_name": "Dean",
        "company": "",
        "address1": "800 Emmet St",
        "address2": "",
        "address3": "",
        "address4": "",
        "city": "Nashville",
        "state": "TN",
        "postal_code": "55555",
        "country": "US",
        "phone": "208-555-5555"
      },
      "customer": {
        "first_name": "Bingo",
        "last_name": "Little",
        "company": "",
        "address1": "900 Lord Business Ave",
        "address2": "",
        "city": "Knoxville",
        "state": "TN",
        "postal_code": "77777",
        "country": "US",
        "phone": "208-555-5555"
      },
      "return_address": {
        "title": "Acme",
        "name": "Doug Jones",
        "company": "Acme Manufacturing",
        "address1": "817 E Maple Ln",
        "address2": "",
        "city": "Knoxville",
        "state": "TN",
        "postal_code": "55555",
        "country": "US",
        "phone": ""
      },
      "checkout_data": {
        "Order Notes": "Please leave by back door"
      },
      "order_metadata": {
        "fraud_protection_score": 0
      },
      "discount_list": [],
      "order_notes": [],
      "order_items": [
      {
        "id": "1670028",
        "name": "Subscription Product",
        "price": 19,
        "quantity": 1,
        "weight": 2.375,
        "code": "126478",
        "delivery_type": "ship",
        "category_code": "DEFAULT",
        "variation_list": [],
        "metadata": {
          "image": "http://img1.wikia.nocookie.net/__cb20130318151721/epicrapbattlesofhistory/images/6/6d/Rick-astley.jpg"
      }
    }
  ]
}

Query Parameters

To search for a specific order, you can filter your request with the folowing fields in your querystring.

Parameter Description
folder_id Search for orders from a particular folder. For multiple folders, enter multiple ID’s separated by a comma: 1004,1009,1010
source_id The source id
source_name The source name
search_start_date Start date from when an order was added. Search in local store time.
search_end_date End date from when an order was added. Search in local store time.
modified_start_date Start date from when an order was modified. Search in local store time.
modified_end_date End date from when an order was modified. Search in local store time.
email Search for orders with a particular email address
customer_id Search for orders with a particular customer ID
customer_first_name Search the customer first name field
customer_last_name Search the customer first name field
customer_company Search the customer company field
customer_address1 Search the customer address1 field
shipping_first_name Search the shipping first name field
shipping_last_name Search the shipping first name field
shipping_company Search the shipping company field
shipping_address1 Search the shipping address1 field
customer_phone Search the customer phone field
shipping_phone Search the shipping phone field
order_by Order the query by an order field. Defaults to date_added
order ASC or DESC, defaults to DESC
limit How many orders to return, defaults to 50, limit of 500
offset The number of records to offset

Create an Order

HTTP Request

POST
https://app.orderdesk.me/api/v2/orders

You must include some order_items and at least one of the following fields: customer_first_name, customer_last_name, customer_company, shipping_first_name, shipping_last_name, shipping_company.

Update An Order

You must pass the entire order as any parts left out will be updated as blank. Order items may be passed in as well. If an id field is passed with the order_item it will be updated. Otherwise it will be added. Shipments may not be modified with this process.

HTTP Request

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

Delete an Order

HTTP Request

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

The order_id field refers to Order Desk’s internal ID.

<?php
include "order-desk-api-client.php";
$od = new OrderDeskApiClient($storeid, $apikey);
$result = $od->delete("orders/736745");
echo "<pre>" . print_r($result, 1) . "</pre>";
?>
curl "https://app.orderdesk.me/api/v2/orders/736745"
  -H "ORDERDESK-STORE-ID: storeid"
  -H "ORDERDESK-API-KEY: apikey"
  -H "Content-Type: application/json"
  -X DELETE

Create an Order History Item

Passing the source_name is not required.

HTTP Request

POST
https://app.orderdesk.me/api/v2/orders/<order_id>/order-history
<?php
include "order-desk-api-client.php";
$od = new OrderDeskApiClient($storeid, $apikey);
$args = array(
  "note" => "My New Note",
  "source_name" => "API",
);
$result = $od->post("orders/736745/order-history", $args);
echo "<pre>" . print_r($result, 1) . "</pre>";
?>
curl "https://app.orderdesk.me/api/v2/orders/736745/order-history"
  -H "ORDERDESK-STORE-ID: storeid"
  -H "ORDERDESK-API-KEY: apikey"
  -H "Content-Type: application/json"
  -X POST
  -d '{"note": "My New Note", "source_name": "API"}'

Response

{
  "status": "success",
  "execution_time": "0.1524 seconds",
  "total_records": 1,
  "order": {
  ...
    "order_history": [
      {
        "source_name": "API",
        "note": "My New Note",
        "date_added": "2015-10-28 23:14:30"
      }
    ]
  }
}

Order Items

Order Item Properties

Attribute Description
id Order Desk’s Internal ID # for the order item read-only
name Item name
price Item price, defaults to 0.00
quantity Item quantity, integer format, defaults to 1
weight Item weight, decimal format
code Item SKU or product code
delivery_type Avaliable options are ship, noship, download, or future. Defaults to ship
category_code Further details about the type of item, freeform text
variation_list Array with a list of variations in key => value format. Ex: ['Size': 'Large', 'Color': 'Red']
metadata Array with a list of extra (hidden) order details in key => value format

Get All Order Items

Get the all the items for an order.

HTTP Request

GET
https://app.orderdesk.me/api/v2/orders/<order_id>/order-items
<?php
include "order-desk-api-client.php";
$od = new OrderDeskApiClient($storeid, $apikey);
$result = $od->get("orders/736745/order-items");
echo "<pre>" . print_r($result, 1) . "</pre>";
?>
curl "https://app.orderdesk.me/api/v2/orders/736745/order-items"
  -H "ORDERDESK-STORE-ID: storeid"
  -H "ORDERDESK-API-KEY: apikey"
  -H "Content-Type: application/json"

Response

{
  "status": "success",
  "execution_time": "0.1505 seconds",
  "total_records": 1,
  "order_items": [
    {
      "id": "47986",
      "name": "Black Shirt",
      "price": 5.5,
      "quantity": 1,
      "weight": 0,
      "code": "",
      "delivery_type": "ship",
      "category_code": "freeshipping",
      "fulfillment_method": "",
      "variation_list": {
        "Size": "Large"
      },
      "metadata": []
    },
    {
      "id": "47987",
      "name": "Green Shirt",
      "price": 2.5,
      "quantity": 1,
      "weight": 0,
      "code": "",
      "delivery_type": "ship",
      "category_code": "freeshipping",
      "fulfillment_method": "",
      "variation_list": {
        "Size": "Large"
      },
      "metadata": []
    }
  ]
}

Get Single Order Item

Get a single items for an order.

HTTP Request

GET
https://app.orderdesk.me/api/v2/order/<order_id>/order-items/<order_item_id>
<?php
include "order-desk-api-client.php";
$od = new OrderDeskApiClient($storeid, $apikey);
$result = $od->get("orders/736745/order-items/47986");
echo "<pre>" . print_r($result, 1) . "</pre>";
?>
curl "https://app.orderdesk.me/api/v2/orders/736745/order-items/47986"
  -H "ORDERDESK-STORE-ID: storeid"
  -H "ORDERDESK-API-KEY: apikey"
  -H "Content-Type: application/json"

Response

{
  "status": "success",
  "execution_time": "0.1505 seconds",
  "order_item": {
    "id": "47986",
    "name": "Black Shirt",
    "price": 5.5,
    "quantity": 1,
    "weight": 0,
    "code": "",
    "delivery_type": "ship",
    "category_code": "freeshipping",
    "fulfillment_method": "",
    "variation_list": {
      "Size": "Large"
    },
    "metadata": []
  }
}

Create Order Item

Add a new order item to an existing order. Pass in json for an order_item object.

HTTP Request

POST
https://app.orderdesk.me/api/v2/orders/<order_id>/order-items

The order_id field refers to Order Desk’s internal ID.

<?php
include "order-desk-api-client.php";
$od = new OrderDeskApiClient($storeid, $apikey);
$args = array(
  "name" => "Second Widget",
  "code" => "widget2",
  "price" => 12.99,
  "variation_list" => array(
    "Size" => "Large",
  ),
);
$result = $od->post("orders/104837/order-items", $args);
echo "<pre>" . print_r($result, 1) . "</pre>";
?>
curl "https://app.orderdesk.me/api/v2/orders/104837/order-items"
  -H "ORDERDESK-STORE-ID: storeid"
  -H "ORDERDESK-API-KEY: apikey"
  -H "Content-Type: application/json"
  -X POST
  -d '{"name": "Second Widget", "code": "widget2", "price": 12.99, "variation_list": ["Size": "Large"]}'


> Response

```json
{
  "status": "success",
  "message": "Order Item Added"
}

Update Order Item

Update an existing order item from an existing order. Pass in json for an order_item object.

HTTP Request

PUT
https://app.orderdesk.me/api/v2/orders/<order_id>/order-items/<id>

The order_id field refers to Order Desk’s internal ID. The id field refers to Order Desk’s internal ID for the item being updated.

<?php
include "order-desk-api-client.php";
$od = new OrderDeskApiClient($storeid, $apikey);
$args = array(
  "name" => "Second Widget",
  "code" => "widget2",
  "price" => 12.99,
  "variation_list" => array(
    "Size" => "Large",
  ),
);
$result = $od->put("orders/104837/order-items/9834738", $args);
echo "<pre>" . print_r($result, 1) . "</pre>";
?>
curl "https://app.orderdesk.me/api/v2/orders/104837/order-items/9834738"
  -H "ORDERDESK-STORE-ID: storeid"
  -H "ORDERDESK-API-KEY: apikey"
  -H "Content-Type: application/json"
  -H "X-HTTP-Method-Override: PUT"
  -X POST
  -d '{"name": "Second Widget", "code": "widget2", "price": 12.99, "variation_list": ["Size": "Large"]}'


> Response

```json
{
  "status": "success",
  "message": "Order Item Updated"
}

Delete Order Item ID

Use the endpoint below to delete an item from an order.

HTTP Request

DELETE
https://app.orderdesk.me/api/v2/orders/<order_id>/order-items/<id>

The order_id field refers to Order Desk’s internal ID. The id field refers to Order Desk’s internal ID for the item being deleted.

<?php
include "order-desk-api-client.php";
$od = new OrderDeskApiClient($storeid, $apikey);
$result = $od->delete("orders/183749/order-items/736745");
echo "<pre>" . print_r($result, 1) . "</pre>";
?>
curl "https://app.orderdesk.me/api/v2/orders/183749/order-items/736745"
  -H "ORDERDESK-STORE-ID: storeid"
  -H "ORDERDESK-API-KEY: apikey"
  -H "Content-Type: application/json"
  -X DELETE

Shipments

Shipment Properties

Field Name Description
tracking_number The carrier’s assigned tracking number. Use n/a if no tracking number is applicable.
carrier_code Code like USPS or FedEx if available.
shipment_method Name of shipping service, example: First Class International
weight Final weight of shipment
cost Your cost to send shipment
status The shipment’s current status - used by EasyPost webhook
tracking_url If not entered, we will try to guess it based on tracking number format and carrier code

Get All Order Shipments

Get the all the shipments for an order.

HTTP Request

GET
https://app.orderdesk.me/api/v2/order/<order_id>/shipments
<?php
include "order-desk-api-client.php";
$od = new OrderDeskApiClient($storeid, $apikey);
$result = $od->get("orders/29491/shipments");
echo "<pre>" . print_r($result, 1) . "</pre>";
?>
curl "https://app.orderdesk.me/api/v2/orders/29491/shipments"
  -H "ORDERDESK-STORE-ID: storeid"
  -H "ORDERDESK-API-KEY: apikey"
  -H "Content-Type: application/json"

Response

{
  "status": "success",
  "execution_time": "0.1290 seconds",
  "total_records": 1,
  "shipments": [
    {
      "id": "437",
      "order_id": "29491",
      "store_id": "11",
      "tracking_number": "1Z2398479234",
      "carrier_code": "UPS",
      "shipment_method": "Ground",
      "weight": "3.55",
      "cost": "",
      "status": "",
      "tracking_url": "http://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=1Z2398479234",
      "label_format": "",
      "label_image": "",
      "print_status": "0",
      "order_items": "",
      "cart_shipment_id": "",
      "label_shipment_id": "",
      "date_shipped": "2015-06-29",
      "date_added": "2015-06-29 19:02:50"
    }
  ]
}

Get Single Order Shipment

Get a single shipment for an order.

HTTP Request

GET
https://app.orderdesk.me/api/v2/order/<order_id>/shipments/<shipment_id>
<?php
include "order-desk-api-client.php";
$od = new OrderDeskApiClient($storeid, $apikey);
$result = $od->get("orders/29491/shipments/437");
echo "<pre>" . print_r($result, 1) . "</pre>";
?>
curl "https://app.orderdesk.me/api/v2/orders/29491/shipments/437"
  -H "ORDERDESK-STORE-ID: storeid"
  -H "ORDERDESK-API-KEY: apikey"
  -H "Content-Type: application/json"

Response

{
  "status": "success",
  "execution_time": "0.1472 seconds",
  "shipment": {
    "id": "437",
    "order_id": "29491",
    "store_id": "11",
    "tracking_number": "1Z2398479234",
    "carrier_code": "UPS",
    "shipment_method": "Ground",
    "weight": "3.55",
    "cost": "",
    "status": "",
    "tracking_url": "http://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=1Z2398479234",
    "label_format": "",
    "label_image": "",
    "print_status": "0",
    "order_items": "",
    "cart_shipment_id": "",
    "label_shipment_id": "",
    "date_shipped": "2015-06-29",
    "date_added": "2015-06-29 19:02:50"
  }
}

Create Shipment

HTTP Request

POST
https://app.orderdesk.me/api/v2/orders/<order_id>/shipments
<?php
include "order-desk-api-client.php";
$od = new OrderDeskApiClient($storeid, $apikey);
$args = array(
  "tracking_number" => "1Z2398479234",
  "carrier_code" => "UPS",
  "shipment_method" => "Ground",
);
$result = $od->post("orders/29491/shipments", $args);
echo "<pre>" . print_r($result, 1) . "</pre>";
?>
curl "https://app.orderdesk.me/api/v2/orders/29491"
  -H "ORDERDESK-STORE-ID: storeid"
  -H "ORDERDESK-API-KEY: apikey"
  -H "Content-Type: application/json"
  -X POST
  -d '{"tracking_number": "1Z2398479234"}'

Response If Added

{
  "status": "success",
  "message": "Shipment Added",
  "execution_time": "0.1454 seconds"
}

Response If Could Not Be Added Because of Existing Shipment

{
  "status": "error",
  "message": "Shipment Not Added",
  "execution_time": "0.1442 seconds"
}

Delete Shipment

Use the endpoint below to delete a shipment from an order.

HTTP Request

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

The order_id field refers to Order Desk’s internal ID. The id field refers to Order Desk’s internal ID for the shipment being deleted.

<?php
include "order-desk-api-client.php";
$od = new OrderDeskApiClient($storeid, $apikey);
$result = $od->delete("orders/2154/shipments/736745");
echo "<pre>" . print_r($result, 1) . "</pre>";
?>
curl "https://app.orderdesk.me/api/v2/orders/2154/shipments/736745"
  -H "ORDERDESK-STORE-ID: storeid"
  -H "ORDERDESK-API-KEY: apikey"
  -H "Content-Type: application/json"
  -X DELETE

Response

{
  "status": "success",
  "message": "Shipment 736745 Deleted",
  "execution_time": "0.1610 seconds"
}

Inventory Items

Inventory Item Properties

A valid inventory item includes a name and code (sku).

Attribute Description
name The name of the product
code The product’s unique sku
price The item price (decimal)
cost The item cost (decimal)
weight The shipping weight of the item
stock The number of avilable units
metadata An array with special information about the inventory item. Used by some integations.
location The warehouse or fulfillment method responsible for this item
update_source The name of the last system to update the item’s details
date_added The date the item was added to Order Desk read-only
date_updated The date the item was updated in Order Desk read-only

Get All Inventory Items

Get the all the store’s inventory items.

HTTP Request

GET
https://app.orderdesk.me/api/v2/inventory-items
<?php
include "order-desk-api-client.php";
$od = new OrderDeskApiClient($storeid, $apikey);
$result = $od->get("inventory-items");
echo "<pre>" . print_r($result, 1) . "</pre>";
?>
curl "https://app.orderdesk.me/api/v2/inventory-items"
  -H "ORDERDESK-STORE-ID: storeid"
  -H "ORDERDESK-API-KEY: apikey"
  -H "Content-Type: application/json"

Response:

{
  "status": "success",
  "execution_time": "0.6651 seconds",
  "records_returned": 5,
  "total_records": "5",
  "inventory_items": [
    {
      "id": 2510,
      "name": "Three Wolf T-Shirt, X-Large / Black",
      "code": "3wolf-11",
      "price": 10,
      "cost": 8,
      "weight": 0.8,
      "stock": 48,
      "update_source": "Shopify",
      "location": "",
      "date_added": "2014-08-09 09:06:53",
      "date_updated": "2014-08-09 09:06:53"
    },
    {
      "id": 2511,
      "name": "Three Wolf T-Shirt, X-Large / Yellow",
      "code": "3wolf-12",
      "price": 10,
      "cost": 8,
      "weight": 0.8,
      "stock": 51,
      "update_source": "Shopify",
      "location": "",
      "date_added": "2014-08-09 09:06:53",
      "date_updated": "2014-08-09 09:06:53"
    },
    {
      "id": 2509,
      "name": "Three Wolf T-Shirt, X-Large / Blue",
      "code": "3wolf-10",
      "price": 10,
      "cost": 8,
      "weight": 0.8,
      "stock": 88,
      "update_source": "Shopify",
      "location": "",
      "date_added": "2014-08-09 09:06:53",
      "date_updated": "2014-08-09 09:06:53"
    },
    {
      "id": 2500,
      "name": "Three Wolf T-Shirt, Large / Black",
      "code": "3wolf-8",
      "price": 10,
      "cost": 8,
      "weight": 0.8,
      "stock": 99,
      "update_source": "Shopify",
      "location": "",
      "date_added": "2014-08-09 09:06:53",
      "date_updated": "2014-08-09 09:06:53"
    },
    {
      "id": 2515,
      "name": "White iPhone, White iPhone",
      "code": "whiteiphone",
      "price": 10,
      "cost": 8,
      "weight": 0.8,
      "stock": 108,
      "update_source": "Shopify",
      "location": "",
      "date_added": "2014-08-09 09:06:53",
      "date_updated": "2014-08-09 09:06:53"
    }
  ]
}

Get A Single Inventory Item

HTTP Request

GET
https://app.orderdesk.me/api/v2/inventory-items/<id>
<?php
include "order-desk-api-client.php";
$od = new OrderDeskApiClient($storeid, $apikey);
$result = $od->get("inventory-items");
echo "<pre>" . print_r($result, 1) . "</pre>";
?>
curl "https://app.orderdesk.me/api/v2/inventory-items/2510"
  -H "ORDERDESK-STORE-ID: storeid"
  -H "ORDERDESK-API-KEY: apikey"
  -H "Content-Type: application/json"

Response:

{
  "status": "success",
  "execution_time": "0.0767 seconds",
  "records_returned": 1,
  "inventory_item": {
    "id": 2510,
    "name": "Three Wolf T-Shirt, X-Large / Black",
    "code": "3wolf-11",
    "price": 10,
    "cost": 8,
    "weight": 0.8,
    "stock": 48,
    "update_source": "Shopify",
    "location": "",
    "date_added": "2014-08-09 09:06:53",
    "date_updated": "2014-08-09 09:06:53"
  }
}

Update Inventory Item

All fields should be passed through. Any empty fields will be set to blank on the record.

HTTP Request

PUT
https://app.orderdesk.me/api/v2/inventory-items/<id>
<?php
include "order-desk-api-client.php";
$od = new OrderDeskApiClient($storeid, $apikey);
$args = array(
  "name" => "Three Wolves T-Shirt",
  "code" => "3wolf-11",
  "price" => 11.00,
  "stock" => 52,
);
$result = $od->put("inventory-items", $args);
echo "<pre>" . print_r($result, 1) . "</pre>";
?>
curl "https://app.orderdesk.me/api/v2/inventory-items/2510"
  -H "ORDERDESK-STORE-ID: storeid"
  -H "ORDERDESK-API-KEY: apikey"
  -H "Content-Type: application/json"
  -H "X-HTTP-Method-Override: PUT"
  -X POST
  -d '{"name": "Three Wolves T-Shirt", "code" => "3wolf-11", "price" => 11.00, "stock" => 52}'

Response:

{
  "status": "success",
  "message": "Inventory Item Updated",
  "execution_time": "0.1420 seconds"
}

Create Inventory Item

HTTP Request

POST
https://app.orderdesk.me/api/v2/inventory-items
<?php
include "order-desk-api-client.php";
$od = new OrderDeskApiClient($storeid, $apikey);
$args = array(
  "name" => "Three Wolves T-Shirt",
  "code" => "3wolf-XX",
  "price" => 11.00,
  "stock" => 52,
);
$result = $od->post("inventory-items", $args);
echo "<pre>" . print_r($result, 1) . "</pre>";
?>
curl "https://app.orderdesk.me/api/v2/inventory-items"
  -H "ORDERDESK-STORE-ID: storeid"
  -H "ORDERDESK-API-KEY: apikey"
  -H "Content-Type: application/json"
  -X POST
  -d '{"name": "Three Wolves T-Shirt", "code" => "3wolf-XX", "price" => 11.00, "stock" => 52}'

Response:

{
  "status": "success",
  "message": "Inventory Item Added",
  "execution_time": "0.1761 seconds"
}

Delete an Inventory Item

HTTP Request

DELETE
https://app.orderdesk.me/api/v2/inventory-item/<id>
<?php
include "order-desk-api-client.php";
$od = new OrderDeskApiClient($storeid, $apikey);
$result = $od->delete("inventory-items/2509");
echo "<pre>" . print_r($result, 1) . "</pre>";
?>
curl "https://app.orderdesk.me/api/v2/inventory-items/2509"
  -H "ORDERDESK-STORE-ID: storeid"
  -H "ORDERDESK-API-KEY: apikey"
  -H "Content-Type: application/json"
  -X DELETE

Response:

{
  "status": "success",
  "message": "Inventory Item 2509 Deleted",
  "execution_time": "0.0836 seconds"
}

Move Orders

Move orders to a new folder. This can target one order or multiple orders.

HTTP Request

POST
https://app.orderdesk.me/api/v2/move-orders

Folder ID Method

<?php
include "order-desk-api-client.php";
$od = new OrderDeskApiClient($storeid, $apikey);
$args = array(
  "order_id_list" => array(29491, 29490),
  "destination_folder_id" => 9384,
);
$result = $od->post("move-orders", $args);
echo "<pre>" . print_r($result, 1) . "</pre>";
?>
curl "https://app.orderdesk.me/api/v2/move-orders"
  -H "ORDERDESK-STORE-ID: storeid"
  -H "ORDERDESK-API-KEY: apikey"
  -H "Content-Type: application/json"
  -X POST
  -d '{"order_id_list": [29491, 29490], "destination_folder_id": 9384}'

Folder Name Method

<?php
include "order-desk-api-client.php";
$od = new OrderDeskApiClient($storeid, $apikey);
$args = array(
  "order_id_list" => array(29491, 29490),
  "destination_folder_name" => "Prepared",
);
$result = $od->post("move-orders", $args);
echo "<pre>" . print_r($result, 1) . "</pre>";
?>
curl "https://app.orderdesk.me/api/v2/move-orders"
  -H "ORDERDESK-STORE-ID: storeid"
  -H "ORDERDESK-API-KEY: apikey"
  -H "Content-Type: application/json"
  -X POST
  -d '{"order_id_list": [29491, 29490], "destination_folder_name": "Prepared"}'

Response

{
  "status": "success",
  "message": "2 Orders Moved",
  "execution_time": "0.1396 seconds",
  "results": [
    {
      "order_id": 29491,
      "message": "Order Moved to Prepared Folder",
      "original_folder_id": 6587
    },
    {
      "order_id": 29490,
      "message": "Order Moved to Prepared Folder",
      "original_folder_id": 6587
    }
  ]
}
Field Name Type Description
order_id_list Array This should be an array of Order Desk’s internal ID’s
destination_folder_id Integer This is the folder ID to which the orders should be moved
destination_folder_name String This is the name of the folder to which the orders should be moved. It must match exactly.

Please note that either destination_folder_id or destination_folder_name should be used, but not both.

Store Settings

Get the store settings and folder list. This is particularly helpful if you are looking for details about a store’s folder structure and need to fetch ID #’s.

GET
https://app.orderdesk.me/api/v2/store
<?php
include "order-desk-api-client.php";
$od = new OrderDeskApiClient($storeid, $apikey);
$result = $od->get("store");
echo "<pre>" . print_r($result, 1) . "</pre>";
?>
curl "https://app.orderdesk.me/api/v2/store"
  -H "ORDERDESK-STORE-ID: storeid"
  -H "ORDERDESK-API-KEY: apikey"
  -H "Content-Type: application/json"

Response:

{
  "status": "success",
  "execution_time": "0.1419 seconds",
  "store": {
    "id": "11",
    "name": "Test Store",
    "settings": {
      "app_version": "2.0",
      "locale_code": "en_US",
      "timezone": "America/Los_Angeles",
      "store_country": "US",
      "store_email": "email@myserver.com",
      "admin_email": "email@myserver.com",
      "normalize_capitalization": "1",
      "normalize_phone_numbers": "0",
      "date_format": "Y-m-d H:i:s",
      "short_date_format": "Y-m-d",
      "orders_per_page": 50,
      "report_frequency": "",
      "dashboard_report_type": "daily",
      "store_url": "http://yoursite.com",
      "custom_css": "",
      "security_po_box_warn": "",
      "security_different_address_warn": "",
      "security_different_country_warn": "",
      "security_quantity_warn": 0,
      "limit_address_field_char_length": 0,
      "country_name_format": "0",
      "all_orders_name": "All Orders",
      "api_key": "yourapikey",
      "all_orders_column_view": [],
      "shipping_methods": [],
      "default_checkout_data_fields": [],
      "smtp_port": "25",
      "smtp_host": "",
      "smtp_username": "",
      "smtp_password": "",
      "smtp_encryption": "",
      "smtp_headers": "",
      "auto_update_stock_count": "",
      "auto_create_inventory_items": "",
      "normalizeCapitalization": 1
    },
    "folders": {
      "21654": "New",
      "21655": "Prepared",
      "21656": "Closed",
      "21657": "Canceled"
    }
  }
}

References

Available Source Names