---
title: "Track a purchase"
method: POST
path: "/api/commerce/trackPurchase"
tags: ["commerce"]
---

# Track a purchase

`POST /api/commerce/trackPurchase`

Track purchase events. <code>shoppingCartItems</code> field on the user profile is cleared. User profile is also updated if it already exists (created otherwise) using the user request field. Also, note that there is a soft limit on the number of unique fields a user can have (default is 1,000). Types of data fields must match the types sent in previous requests, across all data fields in the project.<br/><br/>Learn about <a href="https://support.iterable.com/hc/articles/29156459027348">identifying users by <code>userId</code> and <code>email</code></a>.

## Request body

- TrackPurchaseRequest
  - `campaignId` integer
  - `createdAt` integer — Time event happened. Set to the time event was received if unspecified. Expects a Unix timestamp.
  - `dataFields` object — Additional fields to be tracked.
  - `id` string — Optional purchase id. If a purchase exists with that id, the purchase will be updated. If none is specified, a new id will automatically be generated and returned. Note that this ID cannot be longer than 512 bytes.
  - `items` CommerceItem[], required
    - `categories` string[] — Categories this product belongs to. It can belong to multiple categories. Each category is a breadcrumb in list form.
    - `dataFields` object — Additional item properties
    - `description` string
    - `id` string, required — Unique product identifier
    - `imageUrl` string — URL to an image of the item.
    - `name` string, required
    - `price` number, double, required
    - `quantity` integer, required
    - `sku` string
    - `url` string — URL to the item.
  - `templateId` integer — Used in AB testing attribution
  - `total` number, double, required — Total order dollar amount
  - `user` ApiUserUpdateRequest, required
    - `createNewFields` boolean — Whether new fields should be ingested and added to the schema. Defaults to project's setting to allow or drop unrecognized fields.
    - `dataFields` object — Data to store on the user profile identified by <code>userId</code> or <code>email</code>.
    - `email` string — An email address that identifies a user profile in Iterable. Provide an <code>email</code> or a <code>userId</code> (but not both), depending on <a href="https://support.iterable.com/hc/articles/29156459027348">how your project identifies users</a>.
    - `mergeNestedObjects` boolean — Merge top-level objects instead of overwriting them. Defaults to <code>false</code>. For example, if a user profile has data <code>{"mySettings":{"mobile":true}}</code> and the request has data <code>{"mySettings":{"email":true}}</code>, merging results in <code>{"mySettings":{"mobile":true,"email":true}}</code>.
    - `preferUserId` boolean — Whether or not a new user should be created if the request includes a <code>userId</code> that doesn't yet exist in the Iterable project. Defaults to <code>false</code>. Only respected in API calls for <a href="https://support.iterable.com/hc/articles/29156459027348">email-based projects</a>.
    - `userId` string — A user ID that identifies a user profile in Iterable. Provide an <code>email</code> or a <code>userId</code> (but not both), depending on <a href="https://support.iterable.com/hc/articles/29156459027348">how your project identifies users</a>.

## Response `200`

successful operation

## Other responses

- `400` — Invalid parameters
- `401` — Invalid API key
- `409` — Email/userId conflict

---

[API](https://skmtc.net/iterable/apis/iterable-api.md) · [All operations](https://skmtc.net/iterable/apis/iterable-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/iterable/iterable-api/revisions/afaab604b58c/schema)