---
title: "Create a purchase"
method: POST
path: "/v4/purchases"
tags: ["Purchases"]
---

# Create a purchase

`POST /v4/purchases`

Records a purchase against a subscriber, identified by `email_address` — use this to sync order data from your e-commerce platform into Kit so it appears on the subscriber's profile and can drive purchase-based automations. If no subscriber with that email address exists, one is created (in the `active` state) as part of the request.

Provide the external `transaction_id` (required), monetary breakdown (`subtotal`, `tax`, `shipping`, `discount`, `total`), a 3-letter `currency` code (e.g. `USD`), `transaction_time`, and the purchased `products` — each product needs a `pid` (your platform's product identifier); products that don't exist yet are created automatically.

**Note:** purchases are matched on `transaction_id`, so submitting one that already exists updates the existing purchase instead of creating a duplicate. The `products` in your request are *added* to that purchase as additional line items — they don't replace the ones already recorded — so resending the same products will duplicate the line items. Only include `products` you haven't already synced for that `transaction_id`.

Returns `422` when required parameters are missing or invalid.

## Request body

- object
  - `purchase` object, required
    - `email_address` string, required — The subscriber that the purchase belongs to
    - `transaction_id` string, required
    - `status` string, required
    - `subtotal` number, float, required
    - `tax` number, float, required
    - `shipping` integer, required
    - `discount` number, float, required
    - `total` number, float, required
    - `currency` string, required — 3 letter currency code (e.g. `USD`)
    - `transaction_time` string, required
    - `products` object[], required — Array of purchased products
      - `name` string, required — Product name
      - `pid` string, required — This is your identifier for a product. Each product provided in the `products` array must have a unique pid. Variants of the same product should have the same pid.
      - `lid` string, required — Each product should have a unique `lid` (i.e., line item identifier) for this purchase.
      - `quantity` integer, required — Product quantity
      - `unit_price` number, float, required — Product price
      - `sku` string, required — Product sku

## Response `201`

Creates a purchase for the provided subscriber and returns its details. It also creates products if they don't exist.

- object
  - `purchase` object, required
    - `id` integer, required
    - `transaction_id` string, required
    - `subscriber_id` integer, required
    - `status` string, required
    - `email_address` string, required — The subscriber that the purchase belongs to
    - `currency` string, required — 3 letter currency code (e.g. `USD`)
    - `transaction_time` string, required
    - `subtotal` number, float, required
    - `discount` number, float, required
    - `tax` number, float, required
    - `total` number, float, required
    - `products` object[], required
      - `quantity` integer, required — Product quantity
      - `lid` string, required — Each product should have a unique `lid` (i.e., line item identifier) for this purchase.
      - `unit_price` number, float, required — Product price
      - `sku` string, required — Product sku
      - `name` string, required — Product name
      - `pid` string, required — This is your identifier for a product. Each product provided in the `products` array must have a unique pid. Variants of the same product should have the same pid.
    - `source` string

## Other responses

- `401` — Returns a 401 if the token and/or account cannot be authenticated
- `422` — Returns a 422 when one or more of the parameters are invalid

---

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