API Reference
Need Help?

added product to cart

The added product to cart event is a key e-commerce tracking action. It should be triggered each time a user adds a product to the online shopping cart.

Unlocked Features

  • Cart abandonment workflow: Streamlines the process of re-engaging customers who have left items in their cart without completing the purchase. See the Cart abandonment guide for more information.
  • Contact segmentation: Enables targeted communication by categorizing contacts based on specific criteria.

Supported Endpoints

EndpointeventVersionorigin
/v5/events (Events API)"" (empty)api
track (JavaScript API)"" (empty)api

We recommend to send this event via JavaScript API

Note: The added product to cart event will be captured only for identified contacts. Contact is identified if:

  • Customer clicked on a campaign email and landed on your website
  • Customer submitted Omnisend Form
  • Using the omnisend.identifyContact function

Example event

Below is an example event provided for testing. You can send this through the available endpoints to evaluate automation, segmentation, or any other custom functionalities.

JavaScript API:


omnisend.push([
  "track",
  "added product to cart",
  {
  "origin": "api",
  "eventID": "f3f61bc6-07b8-4645-92d8-189d882dbcb1",
  "eventVersion": "",
  "eventTime": "2021-07-01T00:00:00Z",
  "properties": {
    "abandonedCheckoutURL": "https://example.com/checkout",
    "cartID": "a342-dsfv12",
    "currency": "EUR",
    "lineItems": [
      {
        "productCategories": [
          {
            "id": "123",
            "title": "Shoes"
          }
        ],
        "productDescription": "The best product with many various features",
        "productDiscount": 10.19,
        "productID": "1",
        "productImageURL": "https://example.com/product/232423-image.jpg",
        "productPrice": 19.99,
        "productQuantity": 2,
        "productSKU": 200,
        "productStrikeThroughPrice": 29.99,
        "productTitle": "The best product",
        "productURL": "https://example.com/product/232423",
        "productVariantID": "123",
        "productVariantImageURL": "https://example.com/product/232423-variant-image.jpg"
      }
    ],
    "addedItem": {
      "productCategories": [
        {
          "id": "123",
          "title": "The best product"
        }
      ],
      "productDescription": "The best product with many various features",
      "productDiscount": 10.19,
      "productID": "1",
      "productImageURL": "https://example.com/product/232423-image.jpg",
      "productPrice": 19.99,
      "productQuantity": 2,
      "productSKU": 200,
      "productStrikeThroughPrice": 29.99,
      "productTitle": "The best product",
      "productURL": "https://example.com/product/232423",
      "productVariantID": "123",
      "productVariantImageURL": "https://example.com/product/232423-variant-image.jpg"
    },
    "value": 19.99
  },
  "contact": {
    "id": "67447b7d5c1cd54488ec24d9",
    "email": "[email protected]",
    "phone": "+443031237300",
    "firstName": "Vanessa",
    "lastName": "Kensington",
    "birthdate": "1997-05-28",
    "gender": "f",
    "address": "9709 Highland Rd.",
    "city": "New York",
    "state": "NY",
    "postalCode": "08723",
    "country": "United States",
    "customProperties": {
      "favoriteColors": [
        "red",
        "blue"
      ],
      "vipStatus": true,
      "vipStatusDate": "2023-06-27T10:48:36Z",
      "vipPoints": 100.59,
      "friendlyTitle": "Miss Vanessa"
    },
    "tags": [
      "vip",
      "form:a12546asdwq"
    ],
    "optIns": [
      {
        "channel": "email",
        "createdAt": "2023-06-27T10:48:36Z",
        "source": "form:omnisend-form:5d5cf027865hed74f4078q44:26"
      }
    ],
    "optOuts": [
      {
        "channel": "sms",
        "createdAt": "2023-06-27T10:48:36Z",
        "reason": "unsubscribed via email",
        "source": "email link"
      }
    ],
    "consents": [
      {
        "channel": "email",
        "createdAt": "2023-06-27T10:48:36Z",
        "ip": "73.240.147.113",
        "source": "form:omnisend-form:5d5cf027865hed74f4078q44:26",
        "userAgent": "Mozilla/5.0"
      }
    ]
  }
}
]);
  • eventName. Either "added product to cart"
  • eventID. This is a unique identifier for the event (UUID v4). If you don't have a unique identifier, you can leave it empty.
  • origin. Use api
  • eventVersion. Currently, use "" (empty)
  • properties.
  • eventTime. Optional. If not provided current date is used
  • contact. Optional. The contact object allows you to send additional details about the contact identified using the omnisend.identifyContact JavaScript function. NOTE: When using contact, ensure you provide at least one of the following values: id, email and/or phone. All other contact information is OPTIONAL.

Events API:


POST /v5/events
Host: api.omnisend.com
Content-Type: application/json

{
  "eventName": "added product to cart",
  "origin": "api",
  "eventID": "f3f61bc6-07b8-4645-92d8-189d882dbcb1",
  "eventVersion": "",
  "eventTime": "2021-07-01T00:00:00Z",
  "contact": {
    "email": "[email protected]"
  },
  "properties": {
    "abandonedCheckoutURL": "https://example.com/checkout",
    "cartID": "a342-dsfv12",
    "currency": "EUR",
    "lineItems": [
      {
        "productCategories": [
          {
            "id": "123",
            "title": "Shoes"
          }
        ],
        "productDescription": "The best product with many various features",
        "productDiscount": 10.19,
        "productID": "1",
        "productImageURL": "https://example.com/product/232423-image.jpg",
        "productPrice": 19.99,
        "productQuantity": 2,
        "productSKU": 200,
        "productStrikeThroughPrice": 29.99,
        "productTitle": "The best product",
        "productURL": "https://example.com/product/232423",
        "productVariantID": "123",
        "productVariantImageURL": "https://example.com/product/232423-variant-image.jpg"
      }
    ],
    "addedItem": {
      "productCategories": [
        {
          "id": "123",
          "title": "The best product"
        }
      ],
      "productDescription": "The best product with many various features",
      "productDiscount": 10.19,
      "productID": "1",
      "productImageURL": "https://example.com/product/232423-image.jpg",
      "productPrice": 19.99,
      "productQuantity": 2,
      "productSKU": 200,
      "productStrikeThroughPrice": 29.99,
      "productTitle": "The best product",
      "productURL": "https://example.com/product/232423",
      "productVariantID": "123",
      "productVariantImageURL": "https://example.com/product/232423-variant-image.jpg"
    },
    "value": 19.99
  }
}

Property explanation & expected types

Value PathDescriptionExampleType
abandonedCheckoutURLStore URL for abandoned checkout. When opened by the user it should show the same checkout that user left.https://example.com/checkoutstring
cartIDStore Cart IDa342-dsfv12string
currencyCurrency code in ISO 4217 formatEURstring
lineItems[]All current items in cart. Should contain all cart items.-array of objects
lineItems[].productCategoriesProduct Categories-array of objects
lineItems[].productCategories.idId123string
lineItems[].productCategories.titleTitleShoesstring
lineItems[].productDescriptionProduct DescriptionThe best product with many various featuresstring
lineItems[].productDiscountAbsolute value of product discount. I.e if current price is 20 and old price is 30, then discount should be 10.10.19number
lineItems[].productIDProduct ID1string
lineItems[].productImageURLDirect link to product imagehttps://example.com/product/232423-image.jpgstring
lineItems[].productPriceCurrent product price19.99number
lineItems[].productQuantityTotal added quantity2number
lineItems[].productSKUCurrent stock units200string
lineItems[].productStrikeThroughPricePrevious product price. This should be filled if product is discounted29.99number
lineItems[].productTitleFull product titleThe best productstring
lineItems[].productURLURL to product pagehttps://example.com/product/232423string
lineItems[].productVariantIDProduct variant ID123string
lineItems[].productVariantImageURLDirect link to a product variant imagehttps://example.com/product/232423-variant-image.jpgstring
addedItemAdded Item-object
addedItem.productCategoriesProduct Categories-array of objects
addedItem.productCategories.idCurrent added product to card product ID123string
addedItem.productCategories.titleFull product titleThe best productstring
addedItem.productDescriptionFull or partial product descriptionThe best product with many various featuresstring
addedItem.productDiscountAbsolute value of product discount. I.e if current price is 20 and old price is 30, then discount should be 10.10.19number
addedItem.productIDProduct ID1string
addedItem.productImageURLDirect link to product imagehttps://example.com/product/232423-image.jpgstring
addedItem.productPriceCurrent product price19.99number
addedItem.productQuantityTotal added quantity2number
addedItem.productSKUCurrent stock units200string
addedItem.productStrikeThroughPricePrevious product price. This should be filled if product is discounted29.99number
addedItem.productTitleFull product titleThe best productstring
addedItem.productURLURL to product pagehttps://example.com/product/232423string
addedItem.productVariantIDProduct variant ID123string
addedItem.productVariantImageURLDirect link to a product variant imagehttps://example.com/product/232423-variant-image.jpgstring
valueTotal sum of all cart items19.99number