API Order

The Spiffy Stores API Order object represents a request from a customer to purchase one or more products from your store. The process of creating an order during the checkout process collects together sets of information about the customer's requested, including customer details and billing and shipping addresses, a list of the items being purchased, information about the payment, and shipping and fulfilment details.

Order Properties

id	{ "id" : 123456789 } A unique numeric identifier for the order. This ID is only used with the API interface. This ID is not the same as the Order Number, which is also a unique numeric identifier for the order, but is used by the store owner and customer.
order_number	{ "order_number" : 1045 } A unique numeric identifier for the order that is used as a reference number for the store owner and customers. This is not the same as the id, which is only used to refer to orders within the API.
name	{ "name" : "#001045" } This is the order_number, formatted according the the store preferences for order number formatting.
browser_ip	{ "browser_ip" : "202.60.66.249" } This is the IP address used by the customer when the order was placed.
buyer_accepts_marketing	{ "buyer_accepts_marketing" : true } If the customer indicates during the checkout process that they are happy to receive marketing and other promotional emails, then their response is recorded here.
cart_token	{ "cart_token" : "65853ecbd10916e70999e7056b01a5e7" } This is a unique token that identifies the cart that is associated with a particular order.
created_at	{ "created_at" : "2007-10-24T18:26:31Z" } The date and time when the order was created. The timestamp is in ISO 8601 format.
updated_at	{ "updated_at" : "2014-01-16T05:50:56Z" } The date and time when the order was last updated. The timestamp is in ISO 8601 format.
currency	{ "currency" : "AUD" } The three letter currency code (ISO 4217) used for the order.
email	{ "email" : "customer@any_domain.com" } The customer's email address.
credit	{ "credit" : "0.0" } An order can have credit applied to it from a customer's account. If this is the case, then the amount of credit that has been applied to the order is returned here.
taxes_included	{ "taxes_included" : true } For certain tax systems such as GST and VAT, the amount of tax is included in the price of an item and in this case, this field will return true. In a sales tax system, where the amount of sales tax is added to the final amount of the order, then false will be returned.
tax_price	{ "tax_price" : "3.04" } The total amount of all taxes applied to the order.
included_tax_price	{ "included_tax_price" : "3.04" } The total amount of all taxes applied to the order that are included as part of the item prices.
tax_label	{ "tax_label" : "GST" } The description of the tax item applied to the entire order.
discount_price	{ "discount_price" : "0.0" } The total amount of all discounts that have been applied to the order via coupon codes. Note that this does not include the amount of any discount that has been calculated as a result of a shopping cart discount. This amount is available through line_items_discount_price.
cart_discount_price	{ "cart_discount_price" : "3.8" } The total amount of all discounts that have been applied to the order via shopping cart discounts.
shipping_price	{ "shipping_price" : "17.2" } The total amount of shipping costs for the order.
shipping_lines	{ "shipping_lines" : [   { "code": "WEIGHT_BASED",     "price": "7.2",     "weight": 0.2,     "title": "Australia Post - Regular Parcel"   } ] } An array of shipping_line objects is returned. Each object represents a physical parcel that needs to be shipped, based upon the weight and physical dimensions of the products that have been ordered. Each shipping_line has the following properties: code - This describes the type of shipping method being used price - The price for shipping the parcel weight - The weight of the parcel title - The description for the shipping method The following shipping method codes are used: WEIGHT_BASED The calculated price is based upon the weight of the parcel FREE_SHIPPING The parcel has free shipping SHIPPING_CODE The price for shipping is determined by the Shipping Code
surcharge_price	{ "surcharge_price" : "1.63" } The total amount added to the order as a surcharge. This can include surcharges added for the use of specific credit-cards or other payment methods.
surcharge_percentage	{ "surcharge_percentage" : "1.5" } The percentage amount of the surcharge.
surcharge_label	{ "surcharge_label" : "Surcharge on payment by Visa card (1.5%)" } The description of the surcharge that has been applied.
subtotal_price	{ "subtotal_price" : "16.19" } The total amount of the order less coupon code discounts, but before shipping and additional taxes.
total_line_items_price	{ "total_line_items_price" : "16.19" } The total amount of the order, before shipping and additional taxes and before any coupon code discounts have been applied.
total_price	{ "total_price" : "33.39" } The total amount of all items in the order, including shipping, taxes and discounts.
test	{ "test" : false } Return true if this is a test order.
gateway	{ "gateway" : "Bank Deposit" } The name of the payment gateway that was used to process the payment for this order.
note	{ "note" : "This order has top priority." } The text of an optional note that can be attach to the order by the store owner.
total_weight	{ "total_weight" : 200.0 } The total weight of all items in the order, expressed in grams.
attributes	{ "attributes" : {     "child_name": "Timmy",     "delivery_date": "2018-12-25"   } }
financial_status	{ "financial_status" : "paid" } Returns the current financial status of the order. The following statuses are used: pending - Payment for the order is still pending authorized - Payment has been authorized partially_paid - The order has been partially paid paid - The order has been fully paid
fulfilment_status	{ "fulfilment_status" : null } Returns the current fulfilment status of the order. The following statuses are used: fulfilled - All items in the order have been fulfilled null: None of the items in the order have been fulfilled partial: At least one item in the order has been fulfilled
tax_lines	{ "tax_lines" : [   { "title": "Including GST",     "rate": "0.1",     "price": "3.04"   } ] } An array of tax_line objects is returned. Each object details the total taxes applicable to the order, and has the following properties: title - The description of the tax rate - The rate of tax to be applied price - The amount of tax to be charged
cancel_reason	{ "cancel_reason" : "Fraudulent order" } If an order has been cancelled, the reason for the cancellation is returned. The following reasons may be returned: Customer changed/cancelled order Items unavailable Fraudulent order Other
cancelled_at	{ "cancelled_at" : "2015-02-23T03:02:51Z" } The date and time when the order was cancelled. The timestamp is in ISO 8601 format.
closed_at	{ "closed_at" : "2015-02-23T03:02:51Z" } The date and time when the order was closed. The timestamp is in ISO 8601 format.
discount_codes	{ "discount_codes" : [   { "code": "STOCKTAKE",     "amount": "0.1",     "type": "3.04"   } ] } An array of discount_code objects is returned. Each object details the coupon code discounts that have been applied to the order, and has the following properties: code - The coupon code for the discount amount - The amount of the discount type - The type of discount applied The following discount types are supported: percentage - The discount is a percentage amount of the order fixed_amount - The discount is a fixed amount off the order free_shipping - The discount gives free shipping discount_price - The discount is a fixed price for a product
billing_address	{ "billing_address" : {   "id": 2075,   "title": "Mr",   "first_name": "Frodo",   "last_name": "Baggins",   "name": "Mr Frodo Baggins",   "company": "The Fellowship of the Ring",   "address1": "1 Bag End",   "address2": "",   "city": "Hobbiton",   "province": "The Shire",   "province_code": "",   "country": "Middle Earth",   "country_code": "ME",   "zip": "1234",   "phone": "0412123456"} } Returns the billing address associated with the order. The address has the following properties: id - A unique identifier for the address title - The customer's title first_name - The customer's first name last_name - The customer's last name name - The customer's full name, including title company - An optional company name address1 - The first line of the mailing address address2 - The optional second line of the mailing address city - The city or suburb of the mailing address province - The province or state of the mailing address province_code - The standard province or state abbreviation country - The country of the mailing address country_code - The standard country code abbreviation zip - The postal or zip code of the mailing address phone - A contact phone number for the customer
shipping_address	{ "shipping_address" : {   "id": 2075,   "title": "Mr",   "first_name": "Frodo",   "last_name": "Baggins",   "name": "Mr Frodo Baggins",   "company": "The Fellowship of the Ring",   "address1": "1 Bag End",   "address2": "",   "city": "Hobbiton",   "province": "The Shire",   "province_code": "",   "country": "Middle Earth",   "country_code": "ME",   "zip": "1234",   "phone": "0412123456"} } Returns the shipping address associated with the order. The address has the following properties: id - A unique identifier for the address title - The customer's title first_name - The customer's first name last_name - The customer's last name name - The customer's full name, including title company - An optional company name address1 - The first line of the shipping address address2 - The optional second line of the shipping address city - The city or suburb of the shipping address province - The province or state of the shipping address province_code - The standard province or state abbreviation country - The country of the shipping address country_code - The standard country code abbreviation zip - The postal or zip code of the shipping address phone - A contact phone number for the customer
customer	{ "customer" : {   "id": 6,   "title": "Mr",   "first_name": "Frodo",   "last_name": "Baggins",   "name": "Mr Frodo Baggins",   "email": "frodo@theshire.com",   "accepts_marketing": true,   "created_at": "2010-06-15T13:15:50Z",   "updated_at": "2015-02-23T03:02:51Z",   "note": "This customer has an interest in rings.",   "orders_count": 512,   "state": "enabled",   "total_spent": "11230.63",   "sign_in_count": 261,   "current_sign_in_at": "2015-02-23T03:02:51Z",   "current_sign_in_ip": "192.168.10.164",   "last_sign_in_at": "2015-02-19T05:58:54Z",   "last_sign_in_ip": "192.168.10.164",   "wholesale": false,   "credit": "0.0",   "tags": "friend,ring_bearer,brave,hobbit" } } Returns an object containing information about the customer. This information is only available if the customer has registered for an account, so this information will not be available for guest checkout orders. Customer objects contain the following fields: id - A unique numeric identifier for the customer title - The customer's title first_name - The customer's first name last_name - The customer's last name name - The customer's full name, including title email - The customer's email address accepts_marketing - Acceptance of marketing emails created_at - The date and time when the account was created updated_at - The date and time when the account was updated note - Additional information about the customer orders_count - The number of orders placed by the customer state - The current state of the customer's account Valid states are: enabled disabled invited declined total_spent - The total amount spent by the customer sign_in_count - The number of successful sign ins current_sign_in_at - The time of the current sign in current_sign_in_ip - The IP address of current sign in last_sign_in_at - The time of the last sign in last_sign_in_ip - The IP address of the last sign in wholesale - Customer has access to wholesale prices credit - Amount of credit in customer's account tags - Tags associated with customer
line_items	{ "line_items" : [   { "id": 1200,     "product_id": 1512,     "variation_id": 1705,     "product_exists": true,     "quantity": 1,     "sku": "3445657",     "name": "Cute Dog - Brown",     "title": "Cute Dog",     "variation_title": "Brown",     "discount_description": "<br/>10% Off<br/>Wholesale",     "vendor": "Spiffy Stores",     "weight": 0.2,     "grams": 200.0,     "length": 0.0,     "width": 0.0,     "height": 0.0,     "price": "19.99",     "wholesale_price": "9.99",     "taxable": true,     "discount_price": "3.8",     "total_price": "16.19",     "ship_separately": false,     "free_shipping": false,     "requires_shipping": true,     "fulfilment_service": "manual",     "fulfillable_quantity": 1,     "shipping_method": "",     "instalments": 1,     "gift_card": false,     "fulfilment_status": null   } ] } An array of line_item objects, containing information about the items that have been ordered. Each object has the following properties: id - A unique numeric identifier for the line item product_id - A unique numeric identifier for the product variation_id - A unique numeric identifier for the product variation product_exists - Indicates whether the product still exists quantity - The number of product variations that have been ordered sku - The stock keeping unit code for the product variation name - The combined name of the product and variation title - The name of the product variation_title - The title of the product variation discount_description - Shopping cart discounts description vendor - The supplier or manufacturer of the product weight - The weight of the item in store units grams - The weight of the item in grams length - The length of the item in store units for shipping width - The width of the item in store units for shipping height - The height of the item in store units for shipping price - The price of the item wholesale_price - The wholesale price of the item taxable - Indicates if the item is taxable discount_price - The amount of applied shopping cart discounts total_price - The total amount for this line item ship_separately - The item is bulky and needs separate shipping free_shipping - The item has free shipping requires_shipping - The item requires physical shipping fulfilment_service - The fulfilment method or service provider fulfillable_quantity - The amount that can be fulfilled shipping_method - The shipping method used instalments - The number of payment instalments for the item gift_card - Indicates if the item is a gift card fulfilment_status - Indicates the status of the fulfilment Items that are marked as gift cards are not taxed or included in any shipping charge calculations.
fulfilments	{ "fulfilments" : [   { "id": 397,     "order_id": 1035,     "tracking_company": "",     "tracking_number": "12345678",     "tracking_numbers": ["12345678"],     "tracking_url": "",     "tracking_urls": [],     "status": "Success",     "receipt": {},     "inventory_management": "spiffy",     "created_at": "2015-02-12T06:27:11Z",     "updated_at": "2015-02-12T06:28:06Z",     "line_items": [     { "id": 1198,       "product_id": 1534,       "variation_id": 2178,       "product_exists": true,       "quantity": 1,       "sku": "123456789",       "name": "Suitcase - Red/Large/Leather",       "title": "Suitcase",       "variation_title": "Red/Large/Leather",       "discount_description": "<br/>10% Off",       "vendor": "Spiffy Stores",       "weight": 0.1,       "grams": 100.0,       "length": 0.0,       "width": 0.0,       "height": 0.0,       "price": "12.34",       "wholesale_price": "0.0",       "taxable": true,       "discount_price": "1.23",       "total_price": "11.11",       "ship_separately": false,       "free_shipping": false,       "requires_shipping": true,       "fulfilment_service": "manual",       "fulfillable_quantity": 1,       "shipping_method": "",       "instalments": 1,       "gift_card": false,       "fulfilment_status": "fulfilled"}     ]   } ] } An array of fulfilment objects is returned, representing individual parcel shipments for this order. Each object has the following properties: id - The unique numeric identifier for the fulfilment order_id - The unique numeric identifier for the order tracking_company - The name of the shipping company tracking_number - A unique number used to track the shipment tracking_numbers - An array of tracking numbers tracking_url - The URL used to determine tracking status tracking_urls - An array of tracking URLs status - The status of the fulfilment receipt - The receipt data for the fulfilment inventory_management - The inventory management method created_at - The date and time the fulfilment was created updated_at - The date and time the fulfilment was updated line_items - The line items included in this fulfilment
transactions	{ "transactions" : [   { "id": 253,     "order_id": 378,     "amount": "10.0",     "authorization": "1156177",     "created_at": "2015-02-27T18:08:34Z",     "gateway": "Friendly Bank",     "kind": "Authorization",     "status": "Success",     "transaction_id": "",     "description": "TRANSACTION APPROVED" } ] } An array of transaction objects is returned representing all of the financial transactions associated with the order. Each object has the following properties: id - The unique numeric identifier for the transaction order_id - The unique numeric identifier for the order amount - The amount processed in the transaction authorization - The authorization code returned by the payment gateway created_at - The date and time the transaction was created gateway - The name of the gateway that processed the transaction kind - The type of transaction Sale - The combination of Authorization and Capture Authorization - Payment has been agreed but not processed Capture - Payment is completed after an Authorization Void - The transaction has been cancelled Refund - The transaction has been reversed status - The status of the transaction Success - The transaction completed normally Pending - The transaction has yet to be completed Error - There was an error in the transaction Failure - A failure prevented processing the transaction transaction_id - The transaction identifier returned by the gateway description - A text description of the transaction

Endpoints

GET /api/orders.json

Return a list of open orders. Use the optional status to return other orders.

Optional Parameters

limit	Number of results returned. The default is 30, with a maximum of 50 in a single request.
page	The number of the page to return. The number of results per page is set by the limit parameter. If more results are required, then submit the request again, increasing the page number each time.
ids	A comma-separated list of order ids.
since_id	Limit the results to only include objects which have an id greater than the given value.
created_at_min	Return only the orders created after the given date and time. Use the format "2014-12-31 12:00".
created_at_max	Return only the orders created before the given date and time. Use the format "2014-12-31 12:00".
updated_at_min	Return only the orders updated after the given date and time. Use the format "2014-12-31 12:00".
updated_at_max	Return only the orders updated before the given date and time. Use the format "2014-12-31 12:00".
paid_at_min	Return only the orders paid after the given date and time. Use the format "2014-12-31 12:00".
paid_at_max	Return only the orders paid before the given date and time. Use the format "2014-12-31 12:00".
closed_at_min	Return only the orders closed after the given date and time. Use the format "2014-12-31 12:00".
closed_at_max	Return only the orders closed before the given date and time. Use the format "2014-12-31 12:00".
status	Return only orders with the given status. open - Include only open orders (default) closed - Include only closed orders cancelled - Include only cancelled orders abandoned - Include only abandoned orders any - Include all orders
financial_status	Return only orders with the given financial status. pending - Include only unpaid orders authorized - Include only authorized orders paid - Include only paid orders partially_paid - Include only partially paid orders any - Include orders with any financial status (default)
fulfilment_status	Return only orders with the given fulfilment status. unshipped - Include only unshipped orders shipped - Include only shipped orders partial - Include only partially shipped orders any - Include orders with any fulfilment status (default)
test_status	Return only orders with the given test status. true - Include only test orders false - Exclude all test orders any - Include orders regardless of their test status (default)
customer_id	Return all the orders belonging to the specified customer.
email	Return all orders that have been placed with the specified email address.
fields	A comma-separated list of fields to return in the response. If a list of fields is provided, then the customer, billing_address, shipping_address and line_items fields will always be excluded.

Example Request and Response

GET /api/orders.json

HTTP/1.1 200 OK

{
  "orders": [
    { 
      "id": 378,
      "order_number": 1169,
      "name": "#01169",
      "browser_ip": "127.0.0.1",
      "buyer_accepts_marketing": false,
      "cart_token": null,
      "created_at": "2015-02-27T18:08:33Z",
      "updated_at": "2015-02-27T18:08:33Z",
      "currency": "AUD",
      "email": "customer@customer.domain.com",
      "credit": "0.0",
      "taxes_included": true,
      "tax_price": "0.91",
      "included_tax_price": "0.91",
      "tax_label": "GST",
      "discount_price": "0.0",
      "cart_discount_price": "0.0",
      "shipping_price": "0.0",
      "subtotal_price": "10.0",
      "total_line_items_price": "10.0",
      "total_price": "10.0",
      "test": false,
      "gateway": "Friendly Bank",
      "note": "Very important customer",
      "total_weight": 100.0,
      "financial_status": "authorized",
      "attributes": { "name": "Timmy" },
      "billing_address": 
        {
          "id": 687,
          "title": "Mr",
          "first_name": "Important",
          "last_name": "Customer",
          "name":"Mr Important Customer",
          "company": "",
          "address1": "1 Main St",
          "address2": "",
          "city": "Sydney",
          "province": "New South Wales",
          "province_code": "NSW",
          "country": "Australia",
          "country_code": "AU",
          "zip": "1234",
          "phone": "0291234567"
        },
      "shipping_address":
        {
          "id": 688,
          "title": "Mr",
          "first_name": "Important",
          "last_name": "Customer",
          "name": "Mr Important Customer",
          "company": "",
          "address1": "1 Main St",
          "address2": "",
          "city": "Sydney",
          "province": "New South Wales",
          "province_code": "NSW",
          "country": "Australia",
          "country_code": "AU",
          "zip": "1234",
          "phone": "0291234567"
        },
      "customer":
        {
          "id": 6,
          "title": "Mr",
          "first_name": "Important",
          "last_name": "Customer",
          "name": "Mr Important Customer",
          "email": "customer@customer.domain.com",
          "accepts_marketing": true,
          "created_at": "2010-06-15T13:15:50Z",
          "note": "Here is some sample text.",
          "orders_count": 512,
          "state": "enabled",
          "total_spent": "11230.63",
          "updated_at": "2015-02-23T03:02:51Z",
          "sign_in_count": 261,
          "current_sign_in_at": "2015-02-23T03:02:51Z",
          "current_sign_in_ip": "192.168.10.164",
          "last_sign_in_at": "2015-02-19T05:58:54Z",
          "last_sign_in_ip": "192.168.10.164",
          "wholesale": true,
          "credit": "0.0",
          "tags":"friend,wholesaler"
        },
      "fulfilments": [],
      "line_items": [
        {
          "id": 410,
          "product_id": 1506,
          "variation_id": 1691,
          "product_exists": true,
          "quantity": 1,
          "sku": "SHIRT002",
          "name": "T-Shirt - S - Teal-Blue",
          "title": "T-Shirt",
          "variation_title": "S/Teal-Blue",
          "discount_description": "",
          "vendor": "Spiffy Stores",
          "weight": 0.1,
          "grams": 100.0,
          "length": 0.0,
          "width": 0.0,
          "height": 0.0,
          "price": "10.0",
          "wholesale_price": "0.0",
          "taxable": true,
          "discount_price": "0.0",
          "total_price": "10.0",
          "ship_separately": false,
          "free_shipping": false,
          "requires_shipping": true,
          "fulfilment_service": "manual",
          "fulfillable_quantity": 1,
          "shipping_method": "",
          "instalments": 1,
          "gift_card": false,
          "fulfilment_status": null
        }
      ],
      "transactions": [
        {
          "id": 253,
          "order_id": 378,
          "amount": "10.0",
          "authorization": "1156177",
          "created_at": "2009-02-27T18:08:34Z",
          "gateway": "Friendly Bank",
          "kind": "Authorization",
          "status": "Success",
          "transaction_id": "",
          "description": "TRANSACTION APPROVED"
        }
      ],
      "tax_lines": [
        {
          "title": "Including GST",
          "rate": "0.1",
          "price": "0.91"
        }
      ],
      "shipping_lines": [],
      "discount_codes": []
    }, ...
  ]   
}

Examples using filters

GET /api/orders.json?status=closed

GET /api/orders.json?customer_id=2322

GET /api/orders/count.json

Return a count of open orders. Use the optional status to return the count of other orders.

Optional Parameters

since_id	Limit the results to only include objects which have an id greater than the given value.
created_at_min	Return only the orders created after the given date and time. Use the format "2014-12-31 12:00".
created_at_max	Return only the orders created before the given date and time. Use the format "2014-12-31 12:00".
updated_at_min	Return only the orders updated after the given date and time. Use the format "2014-12-31 12:00".
updated_at_max	Return only the orders updated before the given date and time. Use the format "2014-12-31 12:00".
paid_at_min	Return only the orders paid after the given date and time. Use the format "2014-12-31 12:00".
paid_at_max	Return only the orders paid before the given date and time. Use the format "2014-12-31 12:00".
closed_at_min	Return only the orders closed after the given date and time. Use the format "2014-12-31 12:00".
closed_at_max	Return only the orders closed before the given date and time. Use the format "2014-12-31 12:00".
status	Return only orders with the given status. open - Include only open orders (default) closed - Include only closed orders cancelled - Include only cancelled orders abandoned - Include only abandoned orders any - Include all orders
financial_status	Return only orders with the given financial status. pending - Include only unpaid orders authorized - Include only authorized orders paid - Include only paid orders partially_paid - Include only partially paid orders any - Include orders with any financial status (default)
fulfilment_status	Return only orders with the given fulfilment status. unshipped - Include only unshipped orders shipped - Include only shipped orders partial - Include only partially shipped orders any - Include orders with any fulfilment status (default)
test_status	Return only orders with the given test status. true - Include only test orders false - Exclude all test orders any - Include orders regardless of their test status (default)
customer_id	Return all the orders belonging to the specified customer.
email	Return all orders that have been placed with the specified email address.

Example Request and Response

GET /api/orders/count.json

HTTP/1.1 200 OK

{
  "count": 123
}

Examples using filters

GET /api/orders/count.json?status=closed

GET /api/orders/ORDER_ID.json

Return a single order.

Optional Parameters

fields	A comma-separated list of fields to return in the response. If a list of fields is provided, then the customer, billing_address, shipping_address and line_items fields will always be excluded.

Example Request and Response

GET /api/orders/16789.json

HTTP/1.1 200 OK

{
  "order": 
    { 
      "id": 16789,
      "order_number": 23543,
      "name": "#023543",
      "browser_ip": "127.0.0.1",
      "buyer_accepts_marketing": false,
      "cart_token": null,
      "created_at": "2015-02-27T18:08:33Z",
      "updated_at": "2015-02-27T18:08:33Z",
      ...
    }
}

Further Reference

• An Introduction to the Spiffy Stores API
• Creating Private API Keys
• Using the API
• API Reference