Send add-to-cart signals with the API

Send an add-to-cart signal to Connect with the createSignals mutation. For authentication, contact mapping, consent and the response, see Send signals with the API (GraphQL).

To learn what this signal captures and how to use it in Connect, see Add to cart signal guide. To send it from your website or app instead, use Log signal: web, Android, iOS.

Triggered when a visitor adds products to their cart.

mutation {
  createSignals(
    signals: [
      {
        appKey: "{YOUR_APP_KEY}"
        sessionId: "SESS-789456123AB"
        audience: [
          { name: "Customer ID", value: "AAUN-1417508" }
        ]
        consent: {
          enableOverrideExistingOptOut: true
          sms: [
            {
              status: OPT_IN
              consentGroupIds: ["72d01db0-a422-5a0d-9b6c-86dd997e0000", "cc45e1ca-7d03-583a-9cb8-608490f70000" ]
            }
          ]
        }
        signalContent: {
          signalType: "addToCart"
          category: "Behavior"
          name: "Add product to cart in online store"
          effect: "positive"
          currency: "USD"
          productId: "AC-PNT-WHT-SM"
          productName: "AWESOME COLORS Interior Paint Satin Finish 32 Fl Oz"
          itemQuantity: 2
          unitPrice: 39.99
          discount: 7
          productCategory: "Painting & Decorating / Paint"
          productUrls: [
            "https://www.example.com/painting-and-decorating/paint/awesome-colors-interior-satin-paint"
            "https://www.example.com/painting-and-decorating/must-haves/awesome-colors-interior-satin-paint"
          ]
          imageUrls: ["https://www.example.com/images/awesome-colors-paint.jpg"]
          shoppingCartUrl: "https://www.example.com/cart"
          signalTimestamp: "2026-02-28T16:22:15.001Z"
        }
      }
    ]
  ) {
    signalIds
  }
}

Required fields

itemQuantity: Number - Quantity of product added to cart. Use integers.
productId: String - Product identifier (may match SKU)
productName: String - Product name
signalType: String - Signal type (valid value: addToCart)
unitPrice: Number - Unit price of the product

Optional fields

category: String - Signal category (valid values: Behavior)
currency: String - Price currency. Valid values: ISO 4217 currency codes. Examples: "USD", "EUR", "GBP".
description: String - Description of the signal
discount: Number - Discount amount or difference between original and current price
imageUrls: Array of strings - Product image URLs
effect: String - Signal engagement effect. Valid values: negative, positive. We suggest using positive for all add-to-cart actions.
name: String - Signal name to differentiate from other signals. Max length - 256 chars.
productCategory: String - Product category name based on catalog
productCategoryId: String - Product category identifier
productDescription: String - Product description
productUrls: Array of strings - Product page URLs
promotionId: String - ID from marketing campaigns (hero images, CTAs) that led to this action
shoppingCartUrl: String - Shopping cart URL
signalCustomAttributes: Array of objects - Additional custom attributes (each object needs name and value string fields)
signalTimestamp: Date - When signal happened (if omitted, Connect uses time when signal was received). Valid values: DateTime strings (ISO 8601). Example: 2026-02-28T16:22:15.001Z.
virtualCategory: String - Category based on navigation path (e.g., "New arrivals", "Sale")