The Whiplash API.

Using the Whiplash API you can create an application to do any task you would normally do on WhiplashMerch.com. For example, you could use the API to get a list of all orders that have been shipped recently, change order addresses before they've gone out, create new orders and more.

The Whiplash API is implemented as JSON or XML over HTTP using all four verbs (GET/POST/PUT/DELETE). Each resource, like Order, Item, etc., has its own URL and is manipulated in isolation. An authentification token is required for all calls, which is available on your preferences page.

Testing Environment

We provide a testing server at http://testing.whiplashmerch.com, as well as a shared Sandbox customer account with an authentification key of Hc2BHTn3bcrwyPooyYTP

API Libraries

There are a number of libraries allowing you to easily connect to the Whiplash API.

Orders

Receive a list of Orders

Available Parameters
  • limit - The number of orders returned. Default is 50, maximum is 250
  • status - Show orders matching the specified status
  • offset/page - Page to show (defaults to 1)
  • order_by - Order (defaults to 'updated_at DESC, created_at DESC')
  • since_id — Restrict results to after the specified ID
  • created_at_min — Show orders created after date (format: 2008-01-01 03:00)
  • created_at_max — Show orders created before date (format: 2008-01-01 03:00)
  • updated_at_min — Show orders last updated after date (format: 2008-01-01 03:00)
  • updated_at_max — Show orders last updated before date (format: 2008-01-01 03:00)
GET https://www.whiplashmerch.com/api/orders.json?limit=1&status=100
   HTTP/1.1 200 OK[]
   [
      {  
         "billed":false,
         "created_at":"2013-06-06T15:55:30-04:00",
         "days_in_transit":1,
         "email":"billmurray@gmail.com",
         "gift":false,
         "id":97782,
         "originator_notified":false,
         "pack_fee_actual":null,
         "packaging_fee_actual":null,
         "pick_fee_actual":null,
         "public_note":null,
         "req_ship_method_price":"3.31",
         "req_ship_method_text":"Media Mail (LP's and CD's only)",
         "ship_3rdparty_cost":"0.0",
         "ship_actual_cost":null,
         "ship_method":null,
         "ship_notes":null,
         "shipped_on":null,
         "shipping_address_1":"1800 Hemlock St.",
         "shipping_address_2":null,
         "shipping_city":"Beverley Hills",
         "shipping_company":null,
         "shipping_country":"United States",
         "shipping_country_iso2":"US",
         "shipping_name":"Bill Murray",
         "shipping_phone":"",
         "shipping_state":"California",
         "shipping_zip":"90210",
         "status":100,
         "total_fee_actual":null,
         "tracking_sent":false,
         "updated_at":"2013-06-06T15:55:30-04:00",
         "tracking":[],
         "originator_id":"170741375",
         "provider":"api",
         "insure": false,
         "require_signature": false,
         "insurance_value": "21.98",
         "order_items":[
            {
            "available":true,
            "created_at":"2013-06-06T15:55:31-04:00",
            "description":"Modest Mouse Sad Sappy Sucker, LP",
            "id":202109,
            "item_id":2638,
            "order_id":97782,
            "package_id":90104,
            "packaging":false,
            "packed":0,
            "picked":0,
            "price":"21.98",
            "quantity":1,
            "sku":"78956113118",
            "updated_at":"2013-06-06T15:55:32-04:00",
            "originator_id":"288618017",
            "provider":"api"
            }
         ]
      }
   ]
   

Receive a single Order

By Whiplash ID

GET https://www.whiplashmerch.com/api/orders/97782
   HTTP/1.1 200 OK[]
   {  
      "billed":false,
      "created_at":"2013-06-06T15:55:30-04:00",
      "days_in_transit":1,
      "email":"billmurray@gmail.com",
      "gift":false,
      "id":97782,
      "originator_notified":false,
      "pack_fee_actual":null,
      "packaging_fee_actual":null,
      "pick_fee_actual":null,
      "public_note":null,
      "req_ship_method_price":"3.31",
      "req_ship_method_text":"Media Mail (LP's and CD's only)",
      "ship_3rdparty_cost":"0.0",
      "ship_actual_cost":null,
      "ship_method":null,
      "ship_notes":null,
      "shipped_on":null,
      "shipping_address_1":"1800 Hemlock St.",
      "shipping_address_2":null,
      "shipping_city":"Beverley Hills",
      "shipping_company":null,
      "shipping_country":"United States",
      "shipping_country_iso2":"US",
      "shipping_name":"Bill Murray",
      "shipping_phone":"",
      "shipping_state":"California",
      "shipping_zip":"90210",
      "status":100,
      "total_fee_actual":null,
      "tracking_sent":false,
      "updated_at":"2013-06-06T15:55:30-04:00",
      "tracking":[],
      "originator_id":"170741375",
      "provider":"api",
      "insure": false,
      "require_signature": false,
      "insurance_value": "21.98",
      "order_items":[
         {
         "available":true,
         "created_at":"2013-06-06T15:55:31-04:00",
         "description":"Modest Mouse Sad Sappy Sucker, LP",
         "id":202109,
         "item_id":2638,
         "order_id":97782,
         "package_id":90104,
         "packaging":false,
         "packed":0,
         "picked":0,
         "price":"21.98",
         "quantity":1,
         "sku":"78956113118",
         "updated_at":"2013-06-06T15:55:32-04:00",
         "originator_id":"288618017",
         "provider":"api"
         }
      ]
   }
   

Create an Order

Example request

POST https://www.whiplashmerch.com/api/orders
curl -v -H 'X-API-VERSION: 1' -H 'X-API-KEY: XXXXXXXXXXXX' -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '{"req_ship_method_text":"UPS Ground","shipping_address_1":"123 Some Street","shipping_state":"CA","ship_notes":"Deliver to hot tub in back","shipping_company":"Awesome, Inc","req_ship_method_price":"10.50","shipping_country":"US","shipping_zip":"90210","originator_id":"123456","shipping_city":"Beverly Hills","shipping_name":"Joe Smith","insure":true,"require_signature":true,"insurance_value":"500.00",order_items":[{"price":"23.12","quantity":20,"packaging":false,"originator_id":"654321","description":null,"item_id":136015}],"gift":false,"shipping_phone":"123-456-7890","email":"joe@awesomeinc.com","shipping_address_2":"Apt 2"}' https://www.whiplashmerch.com/api/orders

Example response

   HTTP/1.1 200 OK[]
   {
      "billed"=>false,
      "created_at"=>"2013-07-09T12:06:12-04:00",
      "days_in_transit"=>1,
      "email"=>"joe@awesomeinc.com",
      "gift"=>false,
      "id"=>88705,
      "originator_notified"=>false,
      "pack_fee_actual"=>nil,
      "packaging_fee_actual"=>nil,
      "pick_fee_actual"=>nil,
      "public_note"=>nil,
      "req_ship_method_price"=>"10.5",
      "req_ship_method_text"=>"UPS Ground",
      "ship_3rdparty_cost"=>"0.0",
      "ship_actual_cost"=>nil,
      "ship_method"=>nil,
      "ship_notes"=>"Deliver to hot tub in back",
      "shipped_on"=>nil,
      "shipping_address_1"=>"123 Some Street",
      "shipping_address_2"=>"Apt 2",
      "shipping_city"=>"Beverly Hills",
      "shipping_company"=>"Awesome, Inc",
      "shipping_country"=>"United States",
      "shipping_country_iso2"=>"US",
      "shipping_name"=>"Joe Smith",
      "shipping_phone"=>"123-456-7890",
      "shipping_state"=>"CA",
      "shipping_zip"=>"90210",
      "status"=>80,
      "total_fee_actual"=>nil,
      "tracking_sent"=>false,
      "updated_at"=>"2013-07-09T12:06:13-04:00",
      "tracking"=>[],
      "originator_id"=>"123456",
      "provider"=>"api",
      "insure": true,
      "require_signature": true,
      "insurance_value": "500.00",
      "order_items"=> [
        { "available"=>false,
          "created_at"=>"2013-07-09T12:06:12-04:00",
          "description"=>"Blue Panda S, Playful Panda shirt, river blue",
          "id"=>181904,
          "item_id"=>136015,
          "order_id"=>88705,
          "originator_id"=>"654321",
          "package_id"=>80615,
          "packaging"=>false,
          "packed"=>0,
          "picked"=>0,
          "price"=>"23.12",
          "quantity"=>20,
          "sku"=>"00002",
          "updated_at"=>"2013-07-09T12:06:13-04:00",
          "provider"=>"api"
        }
      ]
    }
   

Update an Order

Change an Order’s shipping_company, shipping_address_1, shipping_address_2, shipping_city, shipping_state, shipping_zip, shipping_country, shipping_country_iso2, shipping_phone, email, ship_notes, shipping_name, req_ship_method_text, req_ship_method_price, public_note, gift, originator_id, originator_attributes, insure, require_signature, req_insurance_value, order_orig, days_in_transit (the only attributes modifiable through the API)

PUT https://www.whiplashmerch.com/api/orders/44545
All successful update requests return a status of 204.

Cancel an Order

PUT https://www.whiplashmerch.com/api/orders/44545/cancel
All successful cancel requests return a status of 204.

Pause an Order

PUT https://www.whiplashmerch.com/api/orders/44545/pause
All successful pause requests return a status of 204.

Release (Unpause) an Order

PUT https://www.whiplashmerch.com/api/orders/44545/release
All successful release requests return a status of 204.

Using Originator ID

Orders received via an e-commerce platform or our API also store the incoming ID as the originator_id. You can find and update using this ID as well.

GET https://www.whiplashmerch.com/api/orders/originator/170741375
   HTTP/1.1 200 OK[]
   {  
      "billed":false,
      "created_at":"2013-06-06T15:55:30-04:00",
      "days_in_transit":1,
      "email":"billmurray@gmail.com",
      "gift":false,
      "id":97782,
      "originator_notified":false,
      "pack_fee_actual":null,
      "packaging_fee_actual":null,
      "pick_fee_actual":null,
      "public_note":null,
      "req_ship_method_price":"3.31",
      "req_ship_method_text":"Media Mail (LP's and CD's only)",
      "ship_3rdparty_cost":"0.0",
      "ship_actual_cost":null,
      "ship_method":null,
      "ship_notes":null,
      "shipped_on":null,
      "shipping_address_1":"1800 Hemlock St.",
      "shipping_address_2":null,
      "shipping_city":"Beverley Hills",
      "shipping_company":null,
      "shipping_country":"United States",
      "shipping_country_iso2":"US",
      "shipping_name":"Bill Murray",
      "shipping_phone":"",
      "shipping_state":"California",
      "shipping_zip":"90210",
      "status":100,
      "total_fee_actual":null,
      "tracking_sent":false,
      "updated_at":"2013-06-06T15:55:30-04:00",
      "tracking":[],
      "originator_id":"170741375",
      "provider":"api",
      "insure": false,
      "require_signature": false,
      "insurance_value": "21.98",
      "order_items":[
         {
         "available":true,
         "created_at":"2013-06-06T15:55:31-04:00",
         "description":"Modest Mouse Sad Sappy Sucker, LP",
         "id":202109,
         "item_id":2638,
         "order_id":97782,
         "package_id":90104,
         "packaging":false,
         "packed":0,
         "picked":0,
         "price":"21.98",
         "quantity":1,
         "sku":"78956113118",
         "updated_at":"2013-06-06T15:55:32-04:00",
         "originator_id":"288618017",
         "provider":"api"
         }
      ]
   }
   

PUT https://www.whiplashmerch.com/api/orders/originator/170741375
All successful update requests return a status of 204.

Order Statuses

All orders will have one of the following statuses:

  • 35: quote
  • 40: cancelled
  • 45: closed by originator
  • 50: unpaid
  • 80: items unavailable
  • 90: paused
  • 95: unassignable
  • 100: processing
  • 120: printed
  • 150: picked
  • 160: packed
  • 300: shipped
  • 400: returned undeliverable
  • 410: replacement requested
  • 430: exchanged
  • 450: refund requested

Shipping Methods

All orders will have one of the following Shipping Methods:

  • 0: Whiplash Pick Up
  • 100: USPS Priority Mail International
  • 101: USPS First Class Mail International
  • 102: USPS Express Mail International
  • 103: USPS Priority Mail
  • 104: USPS First Class Mail
  • 105: USPS Media Mail
  • 106: USPS Parcel Select
  • 109: USPS Express Mail
  • 200: UPS Ground
  • 201: UPS Second Day Air
  • 202: UPS Three-Day Select
  • 203: UPS Next Day Air
  • 204: UPS Next Day Air Saver
  • 205: UPS Next Day Air Early A.M.
  • 206: UPS Second Day Air A.M.
  • 207: UPS Worldwide Expedited
  • 208: UPS Worldwide Express
  • 209: UPS Worldwide Express Plus
  • 211: UPS Worldwide Saver
  • 220: UPSMailInnovations Expedited Mail Innovations
  • 221: UPSMailInnovations Priority Mail Innovations
  • 300: FedEx FedEx Ground
  • 301: FedEx FedEx 2-Day
  • 302: FedEx FedEx 2-Day AM
  • 303: FedEx FedEx Express Saver
  • 304: FedEx Standard Overnight
  • 305: FedEx First Overnight
  • 306: FedEx Priority Overnight
  • 320: FedEx International Economy
  • 321: FedEx International First
  • 322: FedEx International Priority
  • 401: DHLGlobalMail Parcels Expedited
  • 402: DHLGlobalMail Parcel Ground
  • 403: DHLGlobalMail Parcel Plus Expedited
  • 404: DHLGlobalMail Parcel Plus Ground

Order Items

Receive a single Order Item

By Whiplash ID

GET https://www.whiplashmerch.com/api/order_items/201374
	HTTP/1.1 200 OK[]
	{	"available":true,
		"created_at":"2013-06-05T23:48:19-04:00",
		"description":"Modest Mouse Polar Bear Shirt, L / Navy Blue",
		"id":201374,
		"item_id":141065,
		"order_id":97477,
		"package_id":89792,
		"packaging":false,
		"packed":1,
		"price":"20.0",
		"quantity":1,
		"sku":"MMPolarBear",
		"updated_at":"2013-06-06T09:57:07-04:00",
		"originator_id":"288507135",
		"provider":"shopify"
		}
	

Using Originator ID

Orders received via an e-commerce platform or our API may also store the incoming ID as the originator_id. You can find and update using this ID as well.

GET https://www.whiplashmerch.com/api/order_items/originator/288507135
	HTTP/1.1 200 OK[]
	{	"available":true,
		"created_at":"2013-06-05T23:48:19-04:00",
		"description":"Modest Mouse Polar Bear Shirt, L / Navy Blue",
		"id":201374,
		"item_id":141065,
		"order_id":97477,
		"package_id":89792,
		"packaging":false,
		"packed":1,
		"price":"20.0",
		"quantity":1,
		"sku":"MMPolarBear",
		"updated_at":"2013-06-06T09:57:07-04:00",
		"originator_id":"288507135",
		"provider":"shopify"
		}
	

PUT https://www.whiplashmerch.com/api/order_items/originator/222113
All successful update requests return a status of 204.

Items

Receive a list of Items

Available Parameters
  • limit - The number of items returned. Default is 50, maximum is 250
  • offset/page - Page to show (defaults to 1)
  • order_by - Order (defaults to 'updated_at DESC, created_at DESC')
  • since_id — Restrict results to after the specified ID
  • created_at_min — Show items created after date (format: 2008-01-01 03:00)
  • created_at_max — Show items created before date (format: 2008-01-01 03:00)
  • updated_at_min — Show items last updated after date (format: 2008-01-01 03:00)
  • updated_at_max — Show items last updated before date (format: 2008-01-01 03:00)
GET https://www.whiplashmerch.com/api/items.json?limit=1
   HTTP/1.1 200 OK[]
   [
      {"available":true,
      "is_bundle":false,
      "created_at":"2013-04-25T14:21:11-04:00",
      "description":"Natural Polar Bear Tote",
      "exp_quantity":15,
      "height":"0.5",
      "id":141590,
      "image_file_name":null,
      "image_originator_url":"http://yourserver.com/your/image/url",
      "image_updated_at":null,
      "length":"7.0",
      "media_mail":false,
      "packaging":false,
      "price":"10.0",
      "quantity":14,
      "sku":"MMPBTote",
      "street_date":null,
      "title":"Modest Mouse Polar Bear Tote",
      "updated_at":"2013-05-14T12:22:16-04:00",
      "vendor":"Modest Mouse",
      "weight":"0.4",
      "wholesale_cost":null,
      "width":"7.0",
      "originators":
         [
            {  "group_id":"133186757",
               "original_id":"302434029",
               "provider":"api"
               }
            ]
      }
   ]

   

Receive a single Item

By Whiplash ID

GET https://www.whiplashmerch.com/api/items/141590
   HTTP/1.1 200 OK[]
      {"available":true,
      "is_bundle":false,
      "created_at":"2013-04-25T14:21:11-04:00",
      "description":"Natural Polar Bear Tote",
      "exp_quantity":15,
      "height":"0.5",
      "id":141590,
      "image_file_name":null,
      "image_originator_url":"http://yourserver.com/your/image/url",
      "image_updated_at":null,
      "length":"7.0",
      "media_mail":false,
      "packaging":false,
      "price":"10.0",
      "quantity":14,
      "sku":"MMPBTote",
      "street_date":null,
      "title":"Modest Mouse Polar Bear Tote",
      "updated_at":"2013-05-14T12:22:16-04:00",
      "vendor":"Modest Mouse",
      "weight":"0.4",
      "wholesale_cost":null,
      "width":"7.0",
      "originators":
         [
            {  "group_id":"133186757",
               "original_id":"302434029",
               "provider":"api"
               }
            ]
      }
   

Update an Item

Change an Order’s sku, title, description, weight, exp_quantity, available, image_originator_url, vendor, price, wholesale_cost, media_mail, packaging, length, width, height, is_bundle, originator_id, originators_attributes, street_date, include_inbound_in_published (the only attributes modifiable through the API)

PUT https://www.whiplashmerch.com/api/items/141590
All successful update requests return a status of 204.

Using Originator ID

Items received via an e-commerce platform or our API may also store the incoming ID as the orignator_id. You can find and update using this ID as well.

GET https://www.whiplashmerch.com/api/items/originator/302434029
   HTTP/1.1 200 OK[]
      {"available":true,
      "is_bundle":false,
      "created_at":"2013-04-25T14:21:11-04:00",
      "description":"Natural Polar Bear Tote",
      "exp_quantity":15,
      "height":"0.5",
      "id":141590,
      "image_file_name":null,
      "image_originator_url":"http://yourserver.com/your/image/url",
      "image_updated_at":null,
      "length":"7.0",
      "media_mail":false,
      "packaging":false,
      "price":"10.0",
      "quantity":14,
      "sku":"MMPBTote",
      "street_date":null,
      "title":"Modest Mouse Polar Bear Tote",
      "updated_at":"2013-05-14T12:22:16-04:00",
      "vendor":"Modest Mouse",
      "weight":"0.4",
      "wholesale_cost":null,
      "width":"7.0",
      "originators":
         [
            {  "group_id":"133186757",
               "original_id":"302434029",
               "provider":"api"
               }
            ]
      }
   

PUT https://www.whiplashmerch.com/api/items/originator/302434029
All successful update requests return a status of 204.