Collect commerce and product information

If you have products on your site, then this is a default set of things you might want to send to enable the most capabilities from Adobe. Though this is a suggestion, it provides a very strong set of data right from the start.

This document uses the ExperienceEvent Commerce Details schema field group. The commerce field group is broken into two parts: the commerce object and the productListItems array. The commerce object lets you indicate which actions are happening to the productListItems array.

TIP

If you are familiar with Adobe Analytics, The commerce is most closely related to the events variable. The productListItems is more closely related to the products variable.

Below is a list of measures available in the commerce object.

TIP

A measure has two fields: id and value. Most of the time, you will use the value field only (for example, 'value':1). The id field allows you to set a unique identifier that you can use to keep track of when the measure was sent. See the XDM documentation for Measure.

Measure Recommendation Description
cartAbandons Optional A cart is no longer accessible or purchasable by the user.
checkouts Highly Recommended A user is no longer browsing for products but is in the process of purchasing a product.
productListAdds Highly Recommended A product is added to a list. Be sure to set the product in the productListItems at the same time.
productListOpens Optional A new product list is created. (For example, a new shopping cart is created.)
productListRemovals Highly Recommended A product is removed from a product list.
productListReopens Optional A product list is reactivated by the user. This often happens in remarketing campaigns.
productListViews Highly Recommended A list of products is viewed.
productViews Highly Recommended A view of a product occured. Be sure to set the product viewed in the productListItems.
purchases Highly Recommended An order is accepted. Must have a product list.
saveForLaters Optional A product is saved for future use.

Here is an example of how you would set these Measures in the SDK.

alloy("sendEvent", {
  "xdm":{
    "commerce":{
      "productViews":{
        "value":1
      }
    }
  }
});

The commerce object also has a special field for collecting order details called order.

Order Option Recommendation Description
currencyCode The ISO 4217 currency for the order total.
payments[paymentItems] The list of payments on an order. A paymentItem includes the following.
currencyCode Optional The ISO 4217 currency for this payment method.
paymentAmount Highly Recommended The value of the payment in the currency code specified.
paymentType Highly Recommended The type of payment (for example, credit_card, gift_card, paypal). See the list of known values for details.
transactionID Optional A unique ID for this payment transaction.
priceTotal Highly Recommended The total for this order after all discounts and taxes have been applied.
purchaseID Highly Recomended The unique identifier assigned by the seller for this purchase.
purchaseOrderNumber Optional A unique identifier assigned by the purchaser for this purchase.

Here is an example of a typical purchase in the SDK.

alloy("sendEvent",{
  "xdm":{
    "commerce":{
      "order":{
        "purchaseID":"123456789",
        "currencyCode":"USD",
        "priceTotal":39.98,
        "payments":[
          {
            "transactionID":"amx12345",
            "paymentAmount":39.98,
            "paymentType":"credit_card",
            "currencyCode":"USD"
          }
        ]
      }
    },
    "productListItems":[
      {
        "SKU":"HT105",
        "name":"The Big Floppy Hat",
        "priceTotal":29.99,
        "quantity":1
      },
      {
        "SKU":"HT104",
        "name":"The Small Floppy Hat",
        "priceTotal":9.99,
        "quantity":1
      }
    ]
  }
});

Lists of products

The product list indicates which products are related to the corresponding action. It is a list of productListItems. Each product has a number of optional fields.

Field Recommendation Description
currencyCode Optional The ISO 4217 currency for for the product. This is only useful when you can have products with different currency codes and when it applies. For example, when there is a purchase or add to cart.
priceTotal Highly Recommended Should only be set when applicable. For example, it might not be possible to set on productView because different variations of the product can have different prices but on a productListAdds.
product Highly Recommended The XDM ID for the product.
productAddMethod Highly Recommended The method that was used to add a product item to the list by the visitor. Set with productListAdds measures, and should only be used when a product is added to the list. Examples include add to cart button, quick add, and upsell.
productName Highly Recommended This is set to the display name or human-readable name of the product.
quantity Highly Recommended The number of units the customer has indicated they require of the product. Should be set on productListAdds, productListRemoves, purchases, saveForLaters, and so on.
SKU Highly Recommended Store Keeping Unit. It is the unique identifier for the product.

Examples

productView event

alloy("sendEvent",{
  "xdm":{
    "commerce":{
      "productViews":{
        "value":1
      }
    },
    "productListItems":[
      {
        "SKU":"HT105",
        "name":"The Big Floppy Hat",
      },
      {
        "SKU":"HT104",
        "name":"The Small Floppy Hat",
      }
    ]
  }
});

productView event

alloy("sendEvent",{
  "xdm":{
    "commerce":{
      "productListAdds":{
        "value":1
      }
    },
    "productListItems":[
      {
        "SKU":"HT105",
        "name":"The Big Floppy Hat",
        "quantity":1,
        "priceTotal":29.99,
        "productAddMethod":"Add to Cart Button"
      },
      {
        "SKU":"HT104",
        "name":"The Small Floppy Hat",
        "quantity":1,
        "priceTotal":9.99,
        "productAddMethod":"Add-on"
      }
    ]
  }
});

checkout event

alloy("sendEvent",{
  "xdm":{
    "commerce":{
      "checkouts":{
        "value":1
      }
    },
    "productListItems":[
      {
        "SKU":"HT105",
        "name":"The Big Floppy Hat",
        "quantity":1,
        "priceTotal":29.99
      },
      {
        "SKU":"HT104",
        "name":"The Small Floppy Hat",
        "quantity":1,
        "priceTotal":9.99
      }
    ]
  }
});

purchase event

alloy("sendEvent",{
  "xdm":{
    "commerce":{
      "order":{
        "purchaseID":"123456789",
        "currencyCode":"USD",
        "priceTotal":39.98,
        "payments":[
          {
            "transactionID":"amx12345",
            "paymentAmount":39.98,
            "paymentType":"credit_card",
            "currencyCode":"USD"
          }
        ]
      }
    },
    "productListItems":[
      {
        "SKU":"HT105",
        "name":"The Big Floppy Hat",
        "priceTotal":29.99,
        "quantity":1
      },
      {
        "SKU":"HT104",
        "name":"The Small Floppy Hat",
        "priceTotal":9.99,
        "quantity":1
      }
    ]
  }
});

On this page