Send order signals with the API

Send an order 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 Order signal guide. To send it from your website or app instead, use Log signal: web, Android, iOS.

Comes each time a contact places an order on your website. Includes total amount and detailed breakdown by product.

mutation {
  createSignals(
    signals: [
      {
        appKey: "{YOUR_APP_KEY}"
        sessionId: "SESS-789456123AB"
        audience: [
          { name: "Customer ID", value: "AAUN-1417508" }
          { name: "Location", value: "10001" }
        ]
        consent: {
          enableOverrideExistingOptOut: false
          email: [
            {
              status: OPT_IN_UNVERIFIED
              consentGroupIds: ["1766699c-c9af-5899-a6d6-a6aaa17a0000"]
            }
          ]
        }
        signalContent: {
          signalType: "order"
          category: "Behavior"
          name: "Online store order"
          effect: "positive"
          currency: "USD"
          orderId: "02937-2025-XIA"
          orderSubtotal: 89.47
          orderShippingHandling: 15.45
          orderTax: 4.47
          orderDiscount: 0
          orderValue: 98.44
          signalTimestamp: "2026-02-22T08:29:30.001Z"
          orderedItems: [
            {
              productId: "AC-PNT-WHT-SM"
              productName: "AWESOME COLORS Interior Paint Satin Finish 32 Fl Oz"
              unitPrice: 39.99
              itemQuantity: 2
              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/bestsellers/awesome-colors-interior-satin-paint"
              ]
              shoppingCartUrl: "https://www.example.com/cart"
              virtualCategory: "Sale"
            }
            {
              productId: "AC-DBL-BRSH-6"
              productName: "AWESOME COLORS Double Thick Chip Paint Brush"
              unitPrice: 9.49
              itemQuantity: 1
              discount: 0
              productCategory: "Painting & Decorating / Tools"
              productUrls: [
                "https://www.example.com/painting-and-decorating/tools/awesome-colors-double-brush"
                "https://www.example.com/painting-and-decorating/must-haves/awesome-colors-double-brush"
              ]
              shoppingCartUrl: "https://www.example.com/cart"
              virtualCategory: ""
            }
          ]
        }
      }
    ]
  ) {
    signalIds
  }
}

Required fields

• orderId: String - Order identifier
• signalType: String - Signal type (valid values: order)

Optional fields

• category: String - Signal category (valid value: Behavior)
• currency: String - Order currency (valid values: ISO 4217 currency codes)
• description: String - Description of the signal
• effect: String - Signal engagement effect (valid values: negative, positive) - We suggest positive for all order signals.
• name: String (up to 256 characters) - Signal name to differentiate from other signals
• orderDiscount: Number - Discount from original price
• orderedItems: Array of objects - Products in the order (separate object per product, not per instance - three identical items = one object with quantity: 3)
• orderShippingHandling: Number - Shipping and handling amount
• orderSubtotal: Number - Subtotal amount (net of discount)
• orderTax: Number - Tax amount
• orderValue: Number - Total order value
• 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.

Ordered items object

Objects in the orderedItems array represent purchased products. Supported fields:

• discount: Number - Discount amount per unit
• imageUrls: Array of strings - URLs of product images
• itemQuantity: Number - Quantity of this product purchased
• productCategory: String - Product category name based on product catalog
• productCategoryId: String - Product category identifier
• productDescription: String - Description of the product
• productId (required): String - Unique product identifier (may match SKU)
• productName (required): String - Name of the product
• productUrls: Array of strings - URLs of product pages
• promotionId: String - ID from marketing campaigns that influenced the purchase
• shoppingCartUrl: String - URL of the shopping cart
• unitPrice (required): Number - Price the customer paid for one unit
• virtualCategory: String - Category based on navigation path (e.g., "New arrivals", "Sale")