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).

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")