OrderDTO Object

Overview

The REST API makes extensive use of the OrderDTO object whenever working with orders.  This article will help you to know the various members of this object.

Requirements

The following pre-requisites will be necessary to accomplish the goals of this article:

  • General understanding of REST and API’s
  • Understanding of C# and/or JavaScript

Getting Started

There are no tasks needed to get started with understanding this object. 

OrderDTO

The OrderDTO object will contain all of the most common details details of a single order for your Hotcakes Commerce store.  

Members

The following table gives you details on the various members of the OrderDTO object.  The descriptions are based upon default functionality and the default Viewset included with Hotcakes.

Member Default Description
AffiliateID null If the order is being attributed to an affiliate, this ID will not be null.
BillingAddress new AddressDTO Address object for who is being billed for the order.
Bvin (empty string) This is the primary key to uniquely identify a single order.
Coupons new OrderCouponDTO Contains a list of Coupons that have been applied to this order.
CustomProperties new List of CustomPropertyDTO A collection of custom properties that contain additional meta data about the order. 
FraudScore 0 The value determined by the fraud screening configuration.
Id 0 This is an ID that is used primarily for the SQL data source.
Instructions (empty string) Special instructions saved by the customer that submitted the order.
IsPlaced false The order is not placed until the order is submitted from "New" to the "ToDo" state. This value should not be changed manually. The value will always return true for orders that successfully are processed during checkout.
Items new List of LineItemDTO Contains a list of Line Items (products) that are in the order.
ItemsTax null Decimal Total amount of tax for the line items in the order.
LastUpdatedUtc UtcNow The date and time that the order was last updated, in UTC format
Notes new List of OrderNoteDTO Contains a complete list of public and private notes that have been saved to the order.
OrderDiscountDetails new List of DiscountDetailDTO Contains a listing of the discounts that have been applied to this order.
OrderNumber (empty string) This is a text version of the order number and is assigned once the order reaches the "ToDo" state.  This is assigned during the AssignOrderNumber() workflow task. If a value doesn't exist, this order is likely an abandoned cart.
Packages new List of OrderPackageDTO Contains a list of packages that each are a record of shipment for one or more line items.
PaymentStatus Unknown (0) This is an object that describes the current status of payment for the order.The possible values are:
  • Unknown = 0
  • Unpaid = 1
  • PartiallyPaid = 2
  • Paid = 3
  • Overpaid = 4
ShippingAddress new AddressDTO Address object for who is receiving the order, when shipped.
ShippingDiscountDetails new List of DiscountDetailDTO A listing of all of the discounts for the shipping only.
ShippingMethodDisplayName (empty string)  A localized display name matching the shipping method ID.
ShippingMethodId (empty string) Unique ID of the chosen shipping method.
ShippingProviderId (empty string) Unique ID of the provider to be used for shipment.
ShippingProviderServiceCode (empty string) A code used by the shipping provider to indicate the type of service.
ShippingStatus Unknown (0) This is an object that describes the current shipping status of the order.  This value should not be manually set, as it will be set conditionally based upon actions taken by the merchant. The possible values are:
  • Unknown = 0
  • Unshipped = 1
  • PartiallyShipped = 2
  • FullyShipped = 3
  • NonShipping = 4
ShippingTax null Decimal Amount of tax for shipping.
ShippingTaxRate null Decimal The tax rate for shipping.
StatusCode (empty string) This is the ID of the payment status code of the order.  This should match the bvin property of the OrderPaymentStatus object.
StatusName (empty string) The name of the status that matches the StatusCode property as well as the store administration views.
StoreId 0  The identifier of the store that this order belongs to.  This value will always be the same, except in multi-tenant store scenarios.
ThirdPartyOrderId (empty string) This property is primarily used for third party payment providers and other integrations, such as PayPal Express that have their own order numbers.  Currently used with the out of the box PayPal Express payment provider.
TimeOfOrderUtc UtcNow The date and time that the order was placed, in UTC format.
TotalHandling 0 Total amount for handling charges.
TotalShippingBeforeDiscounts 0 Total amount for shipping before discounts are applied.
TotalTax 0 Total amount of tax for the order.
UserEmail (empty string) The email address of the person placing the order.  Either pulled from the user account email address property, or from the guest checkout email address field.
UserID (empty string) The ID that will map to the user in the Hotcakes customer repository.  This does not match the CMS UserID. If empty, this is likely a guest checkout.

 

Example of OrderDTO

{
   "Errors":[

   ],
   "Content":{
      "Coupons":[

      ],
      "Items":[
         {
            "Id":16,
            "StoreId":1,
            "LastUpdatedUtc":"\/Date(1406628188957)\/",
            "BasePricePerItem":1299.0000000000,
            "DiscountDetails":[

            ],
            "OrderBvin":"4140928c-e2c8-4f2f-bb65-167fc912adcc",
            "ProductId":"5d520070-17e5-4587-bddb-9935bc584b6c",
            "VariantId":"21182914-bd5c-47ac-900c-2b33c35801ea",
            "ProductName":"Laptop Computer Sample",
            "ProductSku":"SAMPLE005",
            "ProductShortDescription":"\u003cul class=\"lineitemoptions\"\u003e\u003cli\u003eScreen Size: 15 inch LCD\u003c/li\u003e\u003cli\u003eMemory (RAM): 8GB\u003c/li\u003e\u003cli\u003eWarranty: \u003c/li\u003e\u003c/ul\u003e",
            "Quantity":1,
            "QuantityReturned":0,
            "QuantityShipped":0,
            "ShippingPortion":0.0000000000,
            "StatusCode":"",
            "StatusName":"",
            "TaxRate":0.0000000000,
            "TaxPortion":0.0000000000,
            "SelectionData":[
               {
                  "OptionBvin":"696252e1ef084eefb83a1e9d237db51d",
                  "SelectionData":"d8499dfd6a7f4d93bd1771d3cbf7e893"
               },
               {
                  "OptionBvin":"f5c6fbd865c6494291737f1c2c64b8c1",
                  "SelectionData":"90c9ce3cad0e4b8daba93e825db2de93"
               },
               {
                  "OptionBvin":"dfe277d2a15040ba82c48b93b13c1ff4",
                  "SelectionData":""
               }
            ],
            "IsNonShipping":false,
            "TaxSchedule":-1,
            "ProductShippingWeight":0.0000,
            "ProductShippingLength":0.0000,
            "ProductShippingWidth":0.0000,
            "ProductShippingHeight":0.0000,
            "CustomProperties":[
               {
                  "DeveloperId":"hcc",
                  "Key":"ismarkedforfreeshipping",
                  "Value":"False"
               },
               {
                  "DeveloperId":"hcc",
                  "Key":"istaxexempt",
                  "Value":"False"
               },
               {
                  "DeveloperId":"hcc",
                  "Key":"freeshippingmethodsids",
                  "Value":""
               }
            ],
            "ShipFromMode":1,
            "ShipFromNotificationId":"",
            "ShipFromAddress":{
               "Bvin":"89aad565-1ba6-48c1-a811-d1b0544ee652",
               "LastUpdatedUtc":"\/Date(1398071669897)\/",
               "StoreId":0,
               "NickName":"",
               "FirstName":"",
               "MiddleInitial":"",
               "LastName":"",
               "Company":"",
               "Line1":"319 N. Clematis Street",
               "Line2":"Suite 500",
               "Line3":"",
               "City":"West Palm Beach",
               "RegionName":"Florida",
               "RegionBvin":"FL",
               "PostalCode":"33401",
               "CountryName":"United States",
               "CountryBvin":"bf7389a2-9b21-4d33-b276-23c9c18ea0c0",
               "Phone":"",
               "Fax":"",
               "WebSiteUrl":"",
               "UserBvin":"",
               "AddressType":99
            },
            "ShipSeparately":false,
            "ExtraShipCharge":0.0000
         }
      ],
      "Notes":[
         {
            "Id":1,
            "StoreId":1,
            "LastUpdatedUtc":"\/Date(1406628188963)\/",
            "OrderID":"4140928c-e2c8-4f2f-bb65-167fc912adcc",
            "AuditDate":"\/Date(1406628187107)\/",
            "Note":"Starting Process Order Workflow",
            "IsPublic":false
         },
         {
            "Id":2,
            "StoreId":1,
            "LastUpdatedUtc":"\/Date(1406628188963)\/",
            "OrderID":"4140928c-e2c8-4f2f-bb65-167fc912adcc",
            "AuditDate":"\/Date(1406628187293)\/",
            "Note":"This order was assigned number 1",
            "IsPublic":false
         },
         {
            "Id":3,
            "StoreId":1,
            "LastUpdatedUtc":"\/Date(1406628188967)\/",
            "OrderID":"4140928c-e2c8-4f2f-bb65-167fc912adcc",
            "AuditDate":"\/Date(1406628188040)\/",
            "Note":"Customer IP: 127.0.0.1\u003cbr\u003e Customer Host: 127.0.0.1\u003cbr\u003e Browser: Mozilla/5.0 (Windows NT 6.3; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/36.0.1985.125 Safari/537.36",
            "IsPublic":false
         },
         {
            "Id":4,
            "StoreId":1,
            "LastUpdatedUtc":"\/Date(1406628188967)\/",
            "OrderID":"4140928c-e2c8-4f2f-bb65-167fc912adcc",
            "AuditDate":"\/Date(1406628188103)\/",
            "Note":"Finished Process Order Workflow",
            "IsPublic":false
         },
         {
            "Id":5,
            "StoreId":1,
            "LastUpdatedUtc":"\/Date(1406628188970)\/",
            "OrderID":"4140928c-e2c8-4f2f-bb65-167fc912adcc",
            "AuditDate":"\/Date(1406628188120)\/",
            "Note":"Starting Process Payment Workflow",
            "IsPublic":false
         },
         {
            "Id":6,
            "StoreId":1,
            "LastUpdatedUtc":"\/Date(1406628188970)\/",
            "OrderID":"4140928c-e2c8-4f2f-bb65-167fc912adcc",
            "AuditDate":"\/Date(1406628188527)\/",
            "Note":"Finished Process Payment Workflow",
            "IsPublic":false
         },
         {
            "Id":7,
            "StoreId":1,
            "LastUpdatedUtc":"\/Date(1406628188973)\/",
            "OrderID":"4140928c-e2c8-4f2f-bb65-167fc912adcc",
            "AuditDate":"\/Date(1406628188560)\/",
            "Note":"Starting Order After Payment Workflow",
            "IsPublic":false
         },
         {
            "Id":8,
            "StoreId":1,
            "LastUpdatedUtc":"\/Date(1406628188973)\/",
            "OrderID":"4140928c-e2c8-4f2f-bb65-167fc912adcc",
            "AuditDate":"\/Date(1406628188953)\/",
            "Note":"Finished Order After Payment Workflow",
            "IsPublic":false
         }
      ],
      "Packages":[

      ],
      "Id":1,
      "Bvin":"4140928c-e2c8-4f2f-bb65-167fc912adcc",
      "StoreId":1,
      "LastUpdatedUtc":"\/Date(1406628188953)\/",
      "TimeOfOrderUtc":"\/Date(1406628187407)\/",
      "OrderNumber":"1",
      "ThirdPartyOrderId":"",
      "UserEmail":"host@change.me",
      "UserID":"1",
      "CustomProperties":[
         {
            "DeveloperId":"hcc",
            "Key":"ApplyVATRules",
            "Value":"False"
         }
      ],
      "PaymentStatus":3,
      "ShippingStatus":1,
      "IsPlaced":true,
      "StatusCode":"F37EC405-1EC6-4a91-9AC4-6836215FBBBC",
      "StatusName":"Received",
      "BillingAddress":{
         "Bvin":null,
         "LastUpdatedUtc":"\/Date(1398100982630)\/",
         "StoreId":0,
         "NickName":"",
         "FirstName":"Ursa",
         "MiddleInitial":"",
         "LastName":"Morgan",
         "Company":"Wilkinson Walls Trading",
         "Line1":"0718 Kvfjkpxfc Ohaoja Street",
         "Line2":"9892 Wjeicticu Wgxhtu Street",
         "Line3":"",
         "City":"San Carlos",
         "RegionName":"California",
         "RegionBvin":"CA",
         "PostalCode":"94070",
         "CountryName":"United States",
         "CountryBvin":"bf7389a2-9b21-4d33-b276-23c9c18ea0c0",
         "Phone":"+614-19-8078020",
         "Fax":"",
         "WebSiteUrl":"",
         "UserBvin":"",
         "AddressType":0
      },
      "ShippingAddress":{
         "Bvin":null,
         "LastUpdatedUtc":"\/Date(1398100982630)\/",
         "StoreId":0,
         "NickName":"",
         "FirstName":"Ursa",
         "MiddleInitial":"",
         "LastName":"Morgan",
         "Company":"Wilkinson Walls Trading",
         "Line1":"0718 Kvfjkpxfc Ohaoja Street",
         "Line2":"9892 Wjeicticu Wgxhtu Street",
         "Line3":"",
         "City":"San Carlos",
         "RegionName":"California",
         "RegionBvin":"CA",
         "PostalCode":"94070",
         "CountryName":"United States",
         "CountryBvin":"bf7389a2-9b21-4d33-b276-23c9c18ea0c0",
         "Phone":"+614-19-8078020",
         "Fax":"",
         "WebSiteUrl":"",
         "UserBvin":"",
         "AddressType":0
      },
      "AffiliateID":null,
      "FraudScore":0.00,
      "Instructions":"Aut voluptatem. Voluptatem, at quis rerum eius in dolorem voluptas molestias magni voluptatem, aspernatur magna quibusdam fugiat, consequuntur quos dicta.",
      "ShippingMethodId":"UNKNOWN",
      "ShippingMethodDisplayName":"To Be Determined. Contact Store for Details",
      "ShippingProviderId":"",
      "ShippingProviderServiceCode":"",
      "TotalTax":0.0000000000,
      "ItemsTax":0,
      "ShippingTax":0.0000000000,
      "ShippingTaxRate":0,
      "TotalShippingBeforeDiscounts":0.0000000000,
      "TotalHandling":0.0000000000,
      "OrderDiscountDetails":[

      ],
      "ShippingDiscountDetails":[

      ]
   }
}
Have more questions? Submit a request

Need More Help?

Do you need more assistance with this article? Please review your support options.