> ## Documentation Index
> Fetch the complete documentation index at: https://docs.keenpartner.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a purchase

> Record a purchase against a lead, with optional reward control.

import ApiAuth from "/_snippets/api-auth.mdx";

## Authentication

<ApiAuth />

## Request

<ParamField body="action" type="string" required>
  Must be `"create_purchase"`.
</ParamField>

<ParamField body="lead_id" type="uuid" required>
  The lead to record the purchase against. Your company must have access to this lead's channel.
</ParamField>

<ParamField body="purchase_amount" type="number">
  Amount of the purchase. Used by percentage reward triggers and stored on the purchase row.
</ParamField>

<ParamField body="product_name" type="string">
  Stored as the purchase name.
</ParamField>

<ParamField body="product_description" type="string">
  Stored as the purchase description.
</ParamField>

<ParamField body="date" type="timestamp">
  The date of the purchase. Defaults to the current time if omitted.
</ParamField>

<ParamField body="trigger_ids" type="array of uuid">
  If provided, only these specific reward triggers are evaluated and fired. Each trigger must belong to the lead's channel and have an `"Active"` status. If omitted, all active purchase triggers on the lead's channel fire.
</ParamField>

## Response

Returns the created purchase record.

<ResponseField name="purchase" type="object">
  <Expandable title="Purchase object">
    <ResponseField name="id" type="uuid">Purchase ID.</ResponseField>
    <ResponseField name="created_at" type="timestamp">When the record was created.</ResponseField>
    <ResponseField name="leads_id" type="uuid">The lead this purchase belongs to.</ResponseField>
    <ResponseField name="name" type="string">Product name.</ResponseField>
    <ResponseField name="description" type="string">Product description.</ResponseField>
    <ResponseField name="purchase_amount" type="number">Purchase amount.</ResponseField>
    <ResponseField name="date" type="timestamp">Purchase date.</ResponseField>
  </Expandable>
</ResponseField>

## Side effects

* **Purchase event**: An event record is created with category `purchase`, linked to the new purchase.
* **Reward triggers**: If `trigger_ids` is provided, only those triggers are evaluated. Otherwise, all active `purchase` triggers on the channel fire. Fixed rewards use the trigger's configured amount; percentage rewards are calculated from the `purchase_amount`. Only rewards with an amount greater than zero are inserted.

## Example

### Request

```bash theme={null}
curl -X POST https://data.keenpartner.com/functions/v1/keen-api \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "action": "create_purchase",
    "lead_id": "99887766-5544-3322-1100-aabbccddeeff",
    "purchase_amount": 1500,
    "product_name": "Pro plan",
    "product_description": "Annual subscription",
    "date": "2026-04-21T10:00:00Z",
    "trigger_ids": [
      "66778899-aabb-ccdd-eeff-001122334455"
    ]
  }'
```

### Response

```json theme={null}
{
  "purchase": {
    "id": "55443322-1100-aabb-ccdd-eeff00112233",
    "created_at": "2026-04-21T10:00:05.000Z",
    "leads_id": "99887766-5544-3322-1100-aabbccddeeff",
    "name": "Pro plan",
    "description": "Annual subscription",
    "purchase_amount": 1500,
    "date": "2026-04-21T10:00:00Z"
  }
}
```

## Errors

| Status | Error                   | Cause                                                     |
| ------ | ----------------------- | --------------------------------------------------------- |
| `400`  | `"lead_id required"`    | The `lead_id` field is missing.                           |
| `401`  | `"Invalid API key"`     | Missing or invalid `X-Api-Key` header.                    |
| `403`  | `"Lead not accessible"` | Your company does not have access to this lead's channel. |