Orders
Orders can be accessed through the API via the orders base URL:
$ curl https://app.handshake-app.com/api/v2/orders
- Supported list methods:
GETPOST - Supported detail methods:
GETPUTDELETE
Fields
order.id (readonly string)
The objID of this order, preceded by a hash character, e.g. "#10013". This is not the same as the numeric objID, even though it is obviously directly derived from it. This exists simply for convenience so you have a consistent way of displaying order IDs in your templates.
order.customer (reference to Customer)
The Customer who this order was written for.
order.billTo & order.shipTo (references to Addresses)
The Address objects for billing & shipping respectively.
order.creditCard (reference to CreditCard)
The CreditCard that was selected on this order, or null if none was selected.
order.userGroup (reference to UserGroup)
The UserGroup that this order has been restricted to. This will always be the same as the UserGroup that this order's customer is in.
order.category (reference to OrderCategory)
The OrderCategory that this order is in, which will be one of the categories defined here.
order.lines (collection of SalesOrderLine)
A collection of SalesOrderLine objects for the line items on this order, returned in the order that they appear in the cart view in the iOS app.
Note that when writing order confirmation templates, you should not directly access this property and should instead use the top-level lines template variable, which will have already been filtered down if you're emailing a manufacturer-specific portion of an order rather than the whole thing. This field always returns all the lines on the order and is therefore not always appropriate for email confirmations.
order.lastEdited (readonly datetime)
The most recent mtime of this order or any of the descendant objects, i.e. the most recent modified timestamp of the order itself, any of the lines on the order, the billTo or shipTo addresses, or the creditCard on the order (if there is one). You should treat this time as the most recent time a change was made to this order, useful if you are trying to build batch jobs that fetch only the orders modified since the last time the batch job was run.
order.lastExported (server-only datetime)
The most recent time that this order was exported from the website, or null if the order has never been exported. For the purposes of this field, any of the following actions are considered to be an export:
- Exporting the order to CSV
- Exporting the order headers to CSV
- Printing the order
- Exporting the order to PDF
Note that simply fetching the order via a GET request to the API will not set this field for you. If you want use this field to keep track of which orders you have already pulled from Handshake, you will need to make a PUT request to update this field and set it yourself.
This field can be filtered on (see below) and is especially useful for fetching only the orders that have not already been exported (using the __isnull comparator).
order.status (string)
The current status of this order, which will either be "Confirmed", "Open", or "Hold for confirm".
order.shippingMethod (string)
The shipping method for this order, as selected from the available choices.
order.paymentTerms (string)
The payment terms for this order, as selected from the available choices.
order.total (readonly decimal)
The total amount for this order, calculated as the sum of all the line totals.
order.notes (string)
order.customerPO (string)
order.emailSent (boolean)
order.startShipDate (datetime)
order.cancelDate (datetime)
order.freeShipping (boolean)
order.shipPartial (boolean)
order.signatureURL (readonly string)
A URL where the signature attached to this order can be temporarily retrieved from. This URL only remains active for a short period of time after the order is fetched through the API.
order.photoURLs (readonly list of strings)
A list of URLs where the photos attached to this order can be temporarily retrieved from. These URLs only remain active for a short period of time after the order is fetched through the API.
Filter Parameters
category (string)
Filters orders by category. The filter parameter should be the category's ID rather than its name, e.g.:
# Filter for orders in the category with user-defined ID 'NY_SUMMER'
$ curl https://app.handshake-app.com/api/v2/orders?category=NY_SUMMER
userGroup (string)
Filters order by the user group they're in. Results include orders in that user group or any of its sub-groups.
# Filter for orders in the user group named 'West Coast'
$ curl https://app.handshake-app.com/api/v2/orders?userGroup=West%20Coast
customerID (string)
Filters orders so that only those belonging to the customer with the given ID are returned. Note that the filter is on the string Customer.id property, not the integer Customer.objID property.
# Filter for orders belonging to the customer with ID 'ABC123'
$ curl https://app.handshake-app.com/api/v2/orders?customerID=ABC123
status (string)
Filters orders by their status, which is one of Open, Hold For Confirm, or Confirmed.
# Filter for confirmed orders
$ curl https://app.handshake-app.com/api/v2/orders?status=Confirmed
lastExported (datetime)
Filters orders by their lastExported property, discussed above. Much like the ctime and mtime filters, this filter supports the standard four comparisons:
gt(greater than)gte(greater than or equal)lt(less than)lte(less than or equal)
The lastExported filter also supports the isnull comparison, which should be passed as either true or false to respectively exclude or include orders that have already been exported.
# Fetch orders exported after 2011-10-12 10:39:04pm UTC
$ curl https://app.handshake-app.com/api/v2/orders?lastExported__gte=2011-10-12T22:39:04Z
# Fetch orders that have never been exported
$ curl https://app.handshake-app.com/api/v2/orders?lastExported__isnull=true
Example
{
"meta":{
"limit":100,
"next":null,
"offset":0,
"previous":null,
"total_count":1
},
"objects":[
{
"billTo":{
"btCustomer":"/api/v2/customers/2013",
"city":"New York",
"country":"US",
"fax":"2015487645",
"objID":2014,
"phone":"2125551234",
"postcode":"07875",
"resource_uri":"/api/v2/addresses/2014",
"stCustomer":null,
"state":"NY",
"street":"123 Main St",
"street2":""
},
"cancelDate":null,
"category":"/api/v2/categories/19",
"cdate":"2010-11-23",
"creditCard":{
"customer":"/api/v2/customers/2013",
"cvv":"",
"lastFour":"5553",
"month":"12",
"name":"Mark Twain",
"number":"",
"objID":3216,
"resource_uri":"/api/v2/credit_cards/3216",
"type":"AMEX",
"year":"14"
},
"ctime":"2010-11-24T03:55:46Z",
"customer":{
"billTo":{
"btCustomer":"/api/v2/customers/2013",
"city":"New York",
"country":"US",
"fax":"2015487645",
"objID":2014,
"phone":"2125551234",
"postcode":"07875",
"resource_uri":"/api/v2/addresses/2014",
"stCustomer":null,
"state":"NY",
"street":"123 Main St",
"street2":""
},
"cdate":"2010-10-12",
"contact":"Obie",
"creditCards":[
{
"customer":"/api/v2/customers/2013",
"cvv":"",
"lastFour":"5553",
"month":"12",
"name":"Mark Twain",
"number":"",
"objID":3216,
"resource_uri":"/api/v2/credit_cards/3216",
"type":"AMEX",
"year":"14"
},
{
"customer":"/api/v2/customers/2013",
"cvv":"",
"lastFour":"4477",
"month":"12",
"name":"Obie",
"number":"",
"objID":2026,
"resource_uri":"/api/v2/credit_cards/2026",
"type":"MASTERCARD",
"year":"10"
}
],
"ctime":"2010-10-12T19:19:07Z",
"customerGroup":{
"id":"US",
"manufacturer":null,
"name":"US Retailers",
"objID":946,
"parent":null,
"resource_uri":"/api/v2/categories/946",
"subType":"Customer",
"subcategories":[
]
},
"defaultShipTo":{
"btCustomer":"/api/v2/customers/2013",
"city":"New York",
"country":"US",
"fax":"2015487645",
"objID":2014,
"phone":"2125551234",
"postcode":"07875",
"resource_uri":"/api/v2/addresses/2014",
"stCustomer":null,
"state":"NY",
"street":"123 Main St",
"street2":""
},
"email":"[email protected]",
"entityType":"Customer",
"id":"*2013",
"mtime":"2012-04-12T17:57:40Z",
"name":"Bob Smith",
"objID":2013,
"owner":"[email protected]",
"paymentTerms":"PREPAID",
"resource_uri":"/api/v2/customers/2013",
"shipTos":[
{
"btCustomer":null,
"city":"New York",
"country":"US",
"fax":"",
"objID":994,
"phone":"5555555555",
"postcode":"11211",
"resource_uri":"/api/v2/addresses/994",
"stCustomer":"/api/v2/customers/2013",
"state":"NY",
"street":"154 Grand St",
"street2":""
}
],
"shippingMethod":"UPS",
"userGroup":{
"id":"test",
"manufacturer":null,
"name":"test",
"objID":109180,
"parent":"/api/v2/categories/109039",
"resource_uri":"/api/v2/categories/109180",
"subType":"UserProfile",
"subcategories":[
]
},
"uuid":"a3620f47-9915-4f24-9a1a-474ec3cb8fb2"
},
"customerPO":null,
"entityType":"SalesOrder",
"freeShipping":false,
"lastEdited":"2011-08-22T11:00:25Z",
"lastExported":null,
"lines":[
{
"barcode":"9780375766157",
"cdate":"2010-11-23",
"ctime":"2010-11-24T03:56:17Z",
"description":"Tenor Trombone",
"dimensions":null,
"entityType":"SalesOrderLine",
"isku":"TBN.T",
"item":"/api/v2/items/169",
"manufacturer":"/api/v2/manufacturers/949",
"mtime":"2010-11-24T03:55:33Z",
"notes":"",
"objID":41001,
"order":"/api/v2/orders/41000",
"owner":"[email protected]",
"qty":1,
"resource_uri":"/api/v2/order_lines/41001",
"sku":"TBN.T",
"unitPrice":"1300.00",
"uuid":"c601f9a2-9fb1-465c-ba13-b1bcd7b3e5a2",
"vsku":null
}
],
"mtime":"2011-08-22T11:00:25Z",
"notes":"",
"objID":41000,
"owner":"[email protected]",
"paymentTerms":"PREPAID",
"resource_uri":"/api/v2/orders/41000",
"shipPartial":true,
"shipTo":{
"btCustomer":null,
"city":"New York",
"country":"US",
"fax":"",
"objID":3023,
"phone":"5555555555",
"postcode":"11211",
"resource_uri":"/api/v2/addresses/3023",
"stCustomer":null,
"state":"NY",
"street":"154 Grand St",
"street2":null
},
"shippingMethod":"UPS",
"startShipDate":null,
"status":"Confirmed",
"userGroup":"/api/v2/categories/109039",
"uuid":"b111414a-6cdc-4697-a93c-964edf9530a7"
}
]
}