Carting

Introduction

The carting system in allows businesses to work with shopping carts for clients as a staff member, which includes creating new carts, getting existing carts, deleting carts, as well as adding item and payment information for those carts, and ultimately checking out and processing the cart to complete the order.

How It Works

Carting was designed around a typical ecommerce shopping cart system where a user can build a cart with multiple items, add methods to pay for those items, and eventually checkout where they would actually purchase their items and process payments.

The carting system stores shopping carts per client (end user), business location, and the subscriber, so an end user can only have one cart at a single location and subscriber, and multiple staff members can update and checkout the cart.

How To Use It

  • Starting a Shopping Session

    When a client would like to purchase a product or service, the first thing the staff member would do is see if the client already has a shopping cart, or if a new one is needed. To facilitate this the GetShoppingSession API endpoint was developed.

    The GetShoppingSession endpoint will find a valid, existing cart for a client, or if one isn’t found will create and return a new cart to be used.

    For understand the GetShoppingSession endpoint parameters and response please see the dynamic API documentation.

  • Working with Cart Items

    The carting item system is used to add, update, or delete items from a cart.
    For more information on the Cart Items API, see dynamic API documentation for Cart Items

    • Add an item to a cart

      To add an item to a shopping cart, POST a CatalogItem to the Add Cart Item endpoint.
      The Subscriber Items API will return a CartItem object that represents the item that was just added to the cart.

      Note: When adding Account Payments that have the "Force price and credit fields to match in Business Mode" option enabled, editing the price of the item will automatically adjust the credit amount as well. The credit amount is not editable and will be ignored if edited.

    • Update item in a cart

      To update an item already in a shopping cart, send an HTTP PUT with a CatalogItem to the Update Item endpoint

      The Subscriber Items API will return a CartItem object that represents the item that was just added to the cart.

    • Delete payment from cart

      To delete an item that exists in the cart, send a HTTP DELETE to the Delete Item endpoint with the Cart Item ID.

      Example
      Subscriber/{Subscriber ID}/Location/{Location ID}/Carts/{Cart ID}/Items/{Cart Item ID}

      The subscriber items API will return a HTTP Response Code for the request

  • Working with Tips

    A Tip is just CatalogItem with special metadata that designates the amount of tip, and which staff member the tip is to be applied.

    Tip CatalogItems are added, updated, and removed as any other Cart Item. Working With Cart Items

    • Getting Tip Catalog Item

      To get a tip item to add to a shopping cart, issue a GET request to CatalogItem to the Search Tip endpoint.

      The Subscriber Items API will return a CartItem object that contains the necessary meta data to add a tip for a staff member. Example Tip Metadata

  • Working with Cart Payments

    The carting payments system is used to add, update, or remove payments from a cart; the storage and retrieval of user payments is done via the payments system.
    Please see payments.mbodev.me for more info on storing and retrieving user payments.

    For more information on the Cart Payments API, see dynamic API documentation for Cart Payments

    • Add payment to cart

      To apply payments to cart in current shopping session, POST a PaymentMethod to the Subscriber Payments endpoint.

      The Subscriber Payments API will return a CartPaymentItem object that represents the payment that was just added.

    • Update payment in cart

      To update a payment that exists in the cart, issue a HTTP PUT to CartPaymentItem object to the Subscriber Payments endpoint.

      The subscriber payments API will return a CartPaymentItem object that represents the payment that was just updated.

    • Delete payment from cart

      To delete a payment that exists in the cart, issue a HTTP DELETE to Subscriber Payments endpoint appending the payment id in guid form.

      Example
      /Subscriber/{Subscriber ID}/Location/{Location Id}/Cart/{Cart Id}/Payments/{Cart Payment ID}

      The subscriber payments API will returns HTTP Response Code for the request

  • Working with Manual Discounts

    The carting discount system is used to add, update, or remove discounts from a cart.

    Important items to note regarding Manual Discount support

    • Only discounts of type "Manual" can be added to the cart via the discounts API
    • When applying manual discounts by percentage, percentage is represented by a scale of 0-1 (25% would need to be specified as .25)
    • Manual discounts must specify one or more catalog item's to be applied to

    For more information on the Cart Discounts API, see dynamic API documentation for Cart Discounts

    • Add manual discount to cart

      To apply payments to cart in current shopping session, POST a CatalogDiscount to the Cart Discounts endpoint.

      The Cart Discounts API will return a CartDiscountItem object that represents the discount that was just added.

    • Update manual discount in cart

      To update a payment that exists in the cart, issue a HTTP PUT to CartDiscountItem object to the Cart Discounts endpoint.

      The Cart Discounts API will return a CartDiscountItem object that represents the discount that was just updated.

    • Delete manual discount from cart

      To delete a manual discount that exists in the cart, issue a HTTP DELETE to Cart Discounts endpoint appending the discount id in guid form.

      Example
      /Subscriber/{subscriberId}/Location/{locationId}/Cart/{cartId}/Discounts/{Cart Discount ID}

      The Cart Discounts API will returns HTTP Response Code for the request

  • Checking Out

    Now that you've added all your items and payment to the shopping cart, you can checkout!

    To learn more about the checkout process, see the Checkout page

Miscellaneous

CatalogItem

The CatalogItem is the item information provided from the Catalog Search request.

It is intended to include all details necessary to implement a UI simply based on the details of the item.

The details include, but are not limited to:

  • the item type (ex.: gift card, retail, etc.)
  • any options available (ex.: gift card images, sizes, etc.)
  • item price(s)
  • values (gift card amount)
  • any rules regarding the item (ex.: is the amount editable or not),
  • what payments methods are accepted for that item
  • what fields are required or not for the item (ex.: gift card messages, sender, delivery date, etc.)
  • tip amounts for specified staff member

See the CatalogItem object specification for more details.

PaymentMethod

The PaymentMethod object outlines details for a specific payment method (Credit Card, Cash, Bank Account, Gift Card, etc.). This includes, but is not limited to, the Payment Method Type, rules, options, and any details related to the payment method.

Example

CartPaymentItem

The CartPaymentItem object outlines details for a specific payment as it is applied to the cart

Example

CatalogDiscount

The CatalogDiscount object outlines details for a specific payment as it is applied to the cart
Discount value types are defined in CDiscountValueType (Percentage, Amount)

Example 
                                            {
  "CatalogDiscountItem": {
    "DiscountType": "Manual",
    "Properties": {
      "DiscountValueType": "Percentage",
      "DiscountValue": ".25"
    }
  },
  "CartItemIds": [
    "16becf7a-33e5-43c7-a7b0-376a735ab9f4",
    "df692ca8-09ba-4cbb-8f56-e33f1f1bd4a6"
  ]
}

CartDiscountItem

Cart discount item represents a discount in the cart
Discount value types are defined in CDiscountValueType (Percentage, Amount)

Example 
                                                        {
  "Id": "3a7e0453-e7fa-4a02-b1bc-8d3eda487574",
  "CatalogDiscountItem": {
    "DiscountType": "Manual",
    "Properties": {
      "DiscountValueType": "Percentage",
      "DiscountValue": ".30"
    }
  },
  "Links": [
    "6b953b2f-2fe8-4712-afa7-7d5de89a8e1e",
    "067a9f9f-da99-4e5c-85b9-d8ba295efda2"
  ]
}

Cart Payment Item Tip Metadata

Example tip metadata on CartPaymentItem 

  {
      "Id": null,
      "Name": "Tip",
      "TemplateType": "Tip",
      "Metadata": [
        {
          "Key": "Amount",
          "Value": "0",
          "Type": "Decimal",
          "Label": "Amount",
          "Rules": [
            {
              "Rule": "Required",
              "Value": "True"
            },
            {
              "Rule": "Editable",
              "Value": "True"
            }
          ]
        },
        {
          "Key": "StaffRecipientId",
          "Value": "0",
          "Type": "option:StaffRecipientId",
          "Label": "StaffRecipientId",
          "Rules": [
            {
              "Rule": "Required",
              "Value": "True"
            },
            {
              "Rule": "Editable",
              "Value": "True"
            }
          ]
        }
      ]
    }
  ],
  "Options": [
    {
      "MetadataType": "StaffRecipientId",
      "Items": [
        {
          "Name": "Staff User 1",
          "Value": "2",
          "Properties": {}
        },
        {
          "Name": "Staff User 2",
          "Value": "100000001",
          "Properties": {}
        }, 
      ]
    }
  ]
 }

Helpful Links