< back

Shopping Cart

Cart Functional Overview

All carts have a similar set of functions. They must be able to add items to the cart, change quantity of items in the cart and remove items from the cart. Ideally they should also be able to estimate shipping and taxes for an order and optionally allow for entry of promotional codes (aka coupons).

Because StoreBuilder is designed for customization with an open development layer, you can implement these core functions any way you like or remove/hide these functions.

Cart Implementation Details

The cart page by default will be routed to the /cart url. The cart page will be rendered using the CartViewModel class (including any mixins or extenders for customization) and the sb-cart handlebars template in your active StoreBuilder theme.

POST Request Parameters

You may POST to /cart with either a JSON payload or Form Url Encoded values payload. It the incoming request has a Content-Type:application/json header present then StoreBuilder will look for a JSON payload. If the incoming POST request has a Content-Type:application/x-www-form-urlencoded header present then StoreBuilder will look for Form values.

GET/POST Response Body

If the incoming request has an Accept:application/json header present, then StoreBuilder will return a JSON payload in the response. Otherwise StoreBuilder will return a rendered view as text/html.

If the incoming request is not requesting a json response, then StoreBuilder will additionally look for a X-Requested-With:XMLHttpRequest header to determine whether the response should be a partial view or a complete page. If the X-Requested-With:XMLHttpRequest header is present, then StoreBuilder will return the results of the handlebars template directly, otherwise Storebuilder will route the results to be "wrapped" with any (optional) surrounding view (such as wrapping the results with a Razor view to add all the surrounding page header/footer/etc).

GET/POST Response Data

The data that will either be supplied to Handlebars for rendering a template or serialized as JSON in the response body is defined by the CartViewModel and any mixins that your custom code or other plugins have added to the CartViewModel.

CartViewModel Data

Sample JSON Data

{  
    "Id":"8cc4b11e-43b3-4d0d-86c9-a5c30133a49d",
    "RowId":1409,
    "CreatedBy":"user@domain.com",
    "CreatedOn":"2016-03-08T18:40:06.1212567Z",
    "CreatedOnTimestamp":1457462406121,
    "ModifiedBy":"user@domain.com",
    "ModifiedOn":"2016-03-08T18:40:10.3711124Z",
    "ModifiedOnTimestamp":1457462410371,
    "IsTrashed":false,
    "CurrencyId":"f5d2d8b4-81f4-11e2-9e96-0800200c9a66",
    "Currency":{  
        "isoCode":"CAD",
        "name":"Canadian Dollar",
        "exchangeRate":1.00,
        "symbol":"$",
        "formatString":null,
        "displayOrder":0,
        "id":"f5d2d8b4-81f4-11e2-9e96-0800200c9a66",
        "rowId":2,
        "createdBy":null,
        "createdOn":"2015-04-29T03:00:03.9Z",
        "createdOnTimestamp":1430276403900,
        "modifiedBy":null,
        "modifiedOn":"2015-04-29T03:00:03.9Z",
        "modifiedOnTimestamp":1430276403900,
        "isTrashed":false,
        },
    "BillingFirstName":null,
    "BillingLastName":null,
    "BillingOrganization":null,
    "BillingPhoneNumber":null,
    "BillingEmail":"user@domain.com",
    "BillingLine1":null,
    "BillingLine2":null,
    "BillingCity":null,
    "BillingRegionId":null,
    "BillingRegionCode":null,
    "BillingRegionName":"",
    "BillingPostalCode":null,
    "BillingCountryId":null,
    "BillingCountryCode":null,
    "BillingCountryName":"",
    "BillingAddressTypeId":"e5d2d8b7-81f4-11e2-9e96-0800200c9a66",
    "BillingAddressType":null,
    "ShippingInfoSameAsBilling":true,
    "ShippingFirstName":null,
    "ShippingLastName":null,
    "ShippingOrganization":null,
    "ShippingPhoneNumber":null,
    "ShippingEmail":"user@domain.com",
    "ShippingLine1":null,
    "ShippingLine2":null,
    "ShippingCity":null,
    "ShippingRegionId":"49b98b6d-fdd8-49fc-9a11-bf61621919a2",
    "ShippingRegionCode":"BC",
    "ShippingRegionName":"British Columbia",
    "ShippingPostalCode":null,
    "ShippingCountryId":"2b9a5e17-5569-49fd-858e-7bcfa39bac15",
    "ShippingCountryCode":"CA",
    "ShippingCountryName":"Canada",
    "ShippingAddressTypeId":"e5d2d8b7-81f4-11e2-9e96-0800200c9a66",
    "ShippingAddressType":null,
    "ItemsLength":1,
    "Items":[  
        {  
            "Id":"c61bbe23-e4e2-453d-93cf-a5c30133a525",
            "RowId":1493,
            "CreatedBy":"user@domain.com",
            "CreatedOn":"2016-03-08T18:40:06.1212567Z",
            "CreatedOnTimestamp":1457462406121,
            "ModifiedBy":"user@domain.com",
            "ModifiedOn":"2016-03-08T18:40:06.1212567Z",
            "ModifiedOnTimestamp":1457462406121,
            "IsTrashed":false,
            "Sku":"CON-CORE-TOD-LOWPK-5",
            "RetailSku":"CONCTL103-0005",
            "OnlineSku":"CONCTL106PK-5",
            "Name":"Converse Chuck Taylor Toddler Optical Low Top, Pink, 6 Toddlers",
            "Description":"",
            "Quantity":"1",
            "UnitPrice":29.99,
            "UnitPriceAmount":"$29.99",
            "SubTotal":29.990,
            "SubTotalAmount":"$29.99",
            "TotalDiscount":0.0,
            "TotalDiscountAmount":"$0.00",
            "TotalAmount":"$29.99",
            "Url":"https://dev.domain.com/very-cool-product-slug",
            "ThumbnailUrl":"https://dev.domain.com/images/products/small/very-cool-product.jpg",
            "ThumbnailAlt":"Converse Chuck Taylor Toddler Optical Low Top"
            "ViewData":{  
                "ActionResult":"item-added",
                "QuantityChange":1.0
            },
            "CartId":"8cc4b11e-43b3-4d0d-86c9-a5c30133a49d",
            "ProductVariantId":"38fa84b7-d617-45b3-91f2-a48900335d18"
        }
    ],
    "TotalDiscount":0.0,
    "TotalDiscountAmount":"$0.00",
    "RequiresShipping":true,
    "TotalItems":1.0,
    "TotalValue":29.990,
    "TotalValueAmount":"$29.99",
    "TotalShipping":0.0,
    "TotalShippingAmount":"$0.00",
    "TotalTax":0.0,
    "TotalTaxAmount":"$0.00",
    "GrandTotal":29.990,
    "GrandTotalAmount":"$29.99",
    "ContactPaymentMethods":null,
    "ContactPaymentMethodId":null,
    "PaymentValidationMessage":null,
    "Newsletter":false,
    "AddBillingAddressToAddressBook":false,
    "AddShippingAddressToAddressBook":false,
    "CouponError":null,
    "CouponCode":null
}

Data Element Descriptions

The CartViewModel exposes the following data elements for use in your cart Handlebars templates.

Field NameData TypeDescription
IdGuidThe primary key for the Cart record.
RowIdintA database generated int key for the cart record.
CreatedBystringThe username of the user who first committed the cart record
CreatedOnDateTimeThe UTC DateTime the cart record was created
CreatedOnTimestamplongThe UNIX timestamp the cart record was created
ModifiedBystringThe username of the last user to modify the cart record
ModifiedOnDateTimeThe UTC DateTime the cart record was last modified
ModifiedOnTimestamplongThe UNIX timestamp the cart record was last modified
IsTrashedboolWhether the cart record has been logically deleted
StoreIdGuidThe primary key for the Store this cart belongs to
CurrencyIdGuidThe primary key of the Currency this cart is using
AccountIdGuid?The primary key of the Account this cart is owned by, if any
AccountAccountViewModelThe instance of the Account this cart is owned by, if any, if loaded from the db
ContactIdGuid?The primary key of the Contact this cart is owned by, if any
ContactContactThe instance of the Contact this cart is owned by, if any, if loaded from the db
BillingFirstNamestringThe First Name of the addressee. (Max Length: 64)
BillingLastNamestringThe Last Name of the addressee. (Max Length: 64)
BillingOrganizationstringThe Organization of the addressee. (Max Length: 128)
BillingPhoneNumberstringThe Phone Number of the addressee (Max Length: 32)
BillingEmailstringThe Email of the addressee (Max Length: 128)
BillingLine1stringThe first line for the address (Max Length: 128)
BillingLine2stringThe second line for this address (Max Length: 128)
BillingCitystringThe City for this address (Max Length: 128)
BillingRegionIdGuid?The primary key for the region for this address
BillingRegionCodestringA non-persisted field used for convenience. If you assign a new value here, it will try to set the RegionId when saved.
BillingPostalCodestringThe Postal Code or ZIP code for this address (Max Length: 16)
BillingCountryIdGuid?The primary key for the country for this address
BillingCountryCodestringA non-persisted field used for convenience. If you assign a new value here, it will try to set the CountryId when saved.
BillingAddressTypeIdGuidThe ID for the AddressType this Address is associated with (Guid.Empty = Unspecified, Commercial, Residential, PO Box).
ShippingInfoSameAsBillingboolTrue if the ship to party is the same as the bill to party
ShippingFirstNamestringThe First Name of the addressee. (Max Length: 64)
ShippingLastNamestringThe Last Name of the addressee. (Max Length: 64)
ShippingOrganizationstringThe Organization of the addressee. (Max Length: 128)
ShippingPhoneNumberstringThe Phone Number of the addressee (Max Length: 32)
ShippingEmailstringThe Email of the addressee (Max Length: 128)
ShippingLine1stringThe first line for the address (Max Length: 128)
ShippingLine2stringThe second line for this address (Max Length: 128)
ShippingCitystringThe City for this address (Max Length: 128)
ShippingRegionIdGuid?The primary key for the region for this address
ShippingRegionCodestringA non-persisted field used for convenience. If you assign a new value here, it will try to set the RegionId when saved.
ShippingPostalCodestringThe Postal Code or ZIP code for this address (Max Length: 16)
ShippingCountryIdGuid?The primary key for the country for this address
ShippingCountryCodestringA non-persisted field used for convenience. If you assign a new value here, it will try to set the CountryId when saved.
ShippingAddressTypeIdGuidThe ID for the AddressType this Address is associated with (Guid.Empty = Unspecified, Commercial, Residential, PO Box).
ItemsCartItemViewModel[]The collection of Cart Items currently in this cart
Items.IdGuidThe primary key for the Cart record.
Items.RowIdintA database generated int key for the cart record.
Items.CreatedBystringThe username of the user who first committed the cart record
Items.CreatedOnDateTimeThe UTC DateTime the cart record was created
Items.CreatedOnTimestamplongThe UNIX timestamp the cart record was created
Items.ModifiedBystringThe username of the last user to modify the cart record
Items.ModifiedOnDateTimeThe UTC DateTime the cart record was last modified
Items.ModifiedOnTimestamplongThe UNIX timestamp the cart record was last modified
Items.IsTrashedboolWhether the cart record has been logically deleted
Items.CartIdGuidThe primary key of the Cart this CartItem belongs to
Items.CartItemGroupIdGuid?The primary key of the CartItemGroup this CartItem belongs to
Items.ProductVariantIdGuid?The primary key of the ProductVariant this CartItem represents
Items.SkustringThe "Stock keeping unit" part number of the item in the cart.
Items.RetailSkustringThe RETAIL "Stock keeping unit" is generally some type of part number used to track an item
Items.OnlineSkustringThe ONLINE "Stock keeping unit" is generally some type of part number used to track an item
Items.NamestringThe name of the item in the cart
Items.DescriptionstringThe Description for this line item, generally copied from the ProductVariant
Items.QuantitystringThe quantity of this item the customer intends to purchase.
Items.UnitPricedecimalThe price per unit of this item within the context of this cart (quantity and customer discounts already taken into account).
Items.UnitPriceAmountstringThe string value of the price per unit of this item within the context of this cart (quantity and customer discounts already taken into account).
Items.SubTotaldecimalThe sub total value of this cart item.
Items.SubTotalAmountstringThe string value of the sub total value of this cart item.
Items.TotalDiscountdecimalThe total value of all discounts applied to this cart item.
Items.TotalDiscountAmountstringThe string value of the total value of all discounts applied to this cart item.
Items.TotalAmountstringThe string value of the total value of this cart item.
Items.DiscountsCartItemDiscount[]The collection of CartItemDiscounts currently applied to this CartItem
Items.UrlstringThe URL for this cart item
Items.ThumbnailUrlstringThe URL for the main Thumbnail image for this cart item
Items.ThumbnailAltstringThe Alt text for the main Thumbnail image for this cart item
ItemGroupsEntityCollection<CartItemGroup>The collection of CartItemGroups currently in this cart
DiscountsCartDiscount[]The collection of CartDiscounts currently in this cart
TotalDiscountdecimalThe sum of all discounts currently in this cart
TotalDiscountAmountstringThe string value of the sum of all discounts currently in this cart
TaxesEntityCollection<CartTax>The collection of CartTaxes currently in this cart
RequiresShippingbool?True if any of the items in the cart require shipping
ShippingQuoteGroupsCartShippingQuoteGroupViewModel[]The collection of ShippingQuotes currently in this cart
SelectedShippingQuoteIdGuid?The Id of the shipping option chosen to ship this order from all available shipping carrier quotes
SelectedShippingQuoteCartShippingQuoteViewModelThe shipping option chosen to ship this order from all available shipping carrier quotes.
TotalItemsdecimal?The number of items currently in this cart (Read Only)
TotalValuedecimal?The sub total value of the cart items in this cart. (Read Only)
TotalValueAmountstringThe string value of the sub total value of the cart items in this cart
TotalShippingdecimal?The total shipping value of this cart
TotalShippingAmountstringThe string value of the total shipping value of this cart
TotalTaxdecimal?The total tax value of this cart
TotalTaxAmountstringThe string value of the total tax value of this cart
GrandTotaldecimal?The grand total of this cart, including taxes.
GrandTotalAmountstringThe string value of the grand total of this cart, including taxes.
IsGuestboolDoes the cart belong to a guest
LoginCompleteboolIs the user associated to this cart record logged in
BillingAddressIdGuid?The primary key of the address used for billing
BillingAddressCompleteboolIs the billing address provided to the cart a complete address
ShippingAddressIdGuid?The primary key of the address used for shipping
ShippingAddressCompleteboolIs the shipping address provided to the cart a complete address
ReadyForShippingboolTrue indicates we are ready to offer the customer to select a shipping quote. Shipping quotes will not be "ready" if we don't yet have proper address/delivery information.
ReadyForPaymentboolTrue indicates we are ready for the customer to pay. We will be ready for payment after a valid shipping quote has been selected.
ItemsLengthintThe number of items currently in this cart (Read Only)
ContactPaymentMethodsContactPaymentMethodViewModel[]The collection of Saved Payment methods
ContactPaymentMethodIdGuid?The primary key of the selected saved payment method
PaymentValidationMessagestringError message for any payment issues
NewsletterboolRegister the logged in user to the stores newsletter
AddBillingAddressToAddressBookboolAdd billing address to the logged in users Address book
AddShippingAddressToAddressBookboolAdd shipping address to the logged in users Address book
CouponErrorstringError message for discount, if any
CouponCodestringDiscount Code currently applied to the cart