Create a purchase

Authentication

Request

string

required

Must be "create_purchase".

uuid

required

The lead to record the purchase against. Your company must have access to this lead’s channel.

number

Amount of the purchase. Used by percentage reward triggers and stored on the purchase row.

string

Stored as the purchase name.

string

Stored as the purchase description.

timestamp

The date of the purchase. Defaults to the current time if omitted.

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.

Response

Returns the created purchase record.

object

Show Purchase object

uuid

Purchase ID.

timestamp

When the record was created.

uuid

The lead this purchase belongs to.

string

Product name.

string

Product description.

number

Purchase amount.

timestamp

Purchase date.

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

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

{
  "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.

Overview

Channels

Leads

Purchases

Create a purchase

Authentication

Request

Response

Side effects

Example

Request

Response

Errors

​Authentication

​Request

​Response

​Side effects

​Example

​Request

​Response

​Errors

Authentication

Request

Response

Side effects

Example

Request

Response

Errors