---
updatedAt: 2026-05-28T11:56:07.000Z
---

# Purchase

Reports that the user completed a purchase.

> 👍 Required for e-commerce sections.

### Parameters

* **name:** Human-readable name, not used to identify an event type
* **properties:** A container for the event properties as specified in the following table:

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Property
      </th>

      <th>
        Description
      </th>

      <th>
        Type
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        **dyType**
      </td>

      <td>
        Must be "purchase-v1".
      </td>

      <td>
        String
      </td>
    </tr>

    <tr>
      <td>
        **value**
      </td>

      <td>
        The total monetary value of the event (the total cart purchased, not just the item that triggered the event); in the actual payment currency.
      </td>

      <td>
        Float (dollars.cents).<br /><br /><span style="color:gray; font-size:0.8em;">Numbers are rounded to the nearest 0.01. Numbers smaller than 0.005 are rounded down to 0.</span>
      </td>
    </tr>

    <tr>
      <td>
        **currency<br />**<br /><span style="color:gray; font-size:0.8em;">Optional, but required for multi-currency sites</span>
      </td>

      <td>
        The currency used for the value
      </td>

      <td>
        String<br /><span style="font-size:0.8em;">[List of supported currencies](https://support.dynamicyield.com/hc/en-us/articles/360022558254#h_01F248KMJV1VWADRC2H7WYFWCZ)</span>
      </td>
    </tr>

    <tr>
      <td>
        **uniqueTransactionId**<br /><span style="color:gray; font-size:0.8em;">Optional, but recommended</span>
      </td>

      <td>
        Ensures that a purchase is recorded only once per transaction ID. The first purchase event with a given `uniqueTransactionId` is processed, while any subsequent purchase events with the same value are filtered out for the next 30 days, even if duplicate events are reported.
      </td>

      <td>
        String<br /><span style="color:gray; font-size:0.8em;">Maximum of 64 characters</span>
      </td>
    </tr>

    <tr>
      <td>
        **cart**
      </td>

      <td>
        The cart's absolute current state. Products are ordered from the first added to the cart to the most recent.
      </td>

      <td>
        Object

        See the cart property table that follows for details.
      </td>
    </tr>
  </tbody>
</Table>

**Cart object properties:**

| Property      | Description                                   | Type                               |
| :------------ | :-------------------------------------------- | :--------------------------------- |
| **productId** | SKU exactly as it appears in the product feed | String                             |
| **quantity**  | Number of items                               | Number                             |
| **itemPrice** | The price of the item added                   | Float in the format: dollars.cents |

**Example: Implementation via script**

```javascript
DY.API("event", {
  name: "Purchase", // Human-readable name, not used to identify an event type
  properties: {
    uniqueTransactionId: "123456", // Will remove redundant events. Must be a string. Max 64 characters.
    dyType: "purchase-v1", // Identifies this event as a purchase
    value: 90.55, // Total cart value in actual payment currency, as float (dollars dot cents)
    currency: "any supported currency code", // Optional non-default currency used
    cart: [
      // itemPrice is per quantity of one, and in the same format as the total "value":
      // float of dollars.cents in the payment currency (which is only defined once above)
      {
        productId: "item-34454", // SKU exactly as in the product feed!
        quantity: 1,
        itemPrice: 65.87,
        size: "XL" // Size is *optional and a customer-specific string*
      }, {
        productId: "sku-4324-bg",
        quantity: 2,
        itemPrice: 12.34,
        size: "M"
      }
    ]
  }
});
```

**Example: Implementation via Experience API (server-side)**

```json
"events":[{
  name: "Purchase",
  properties: {
    dyType: "purchase-v1",
    value: 349.80,
    uniqueTransactionId: "exampleTransactionId",
    cart: [
      {
        productId: "p-tv78615a",
        quantity: 1,
        itemPrice: 249.90,
      },
      {
        productId: "p-cr91275g",
        quantity: 2,
        itemPrice: 49.95
      }
    ]
  }
} ]
```

> 👍 Go to the [API reference for the Events endpoint](https://dy.dev/dy-dev/reference/track-events) to learn more.

<br />