Purchase Event

The Purchase Event is sent through the /webhook endpoint and tracks in-app purchases for attribution.

Endpoint

POST /webhook

When to Call

Send a purchase event every time a user completes an in-app purchase:

Subscription purchases
One-time purchases (remove ads, unlock features)
Consumable purchases (in-game currency, items)

Timing: Send this event immediately after the purchase is confirmed by your payment provider (App Store, Google Play, etc.).

Request Body

Required Fields

Prop

Type

Payload Fields

Prop

Type

Example Request

curl -X POST https://analytics.geeklab.app/webhook \
  -H "Content-Type: application/json" \
  -H "geeklab-api-key: your_api_key" \
  -d '{
    "type": "custom.purchase",
    "created_at": "2024-10-10 10:15:00",
    "creativeToken": "abc123def456",
    "device_name": "MacBook Pro",
    "device_model": "MacBookPro18,3",
    "os_system": "macOS 14.5",
    "utc_offset": "-07:00",
    "retention_day": "0",
    "payload": {
      "item_id": "premium_monthly",
      "item_name": "Premium Monthly Subscription",
      "value": 9.99,
      "currency": "usd",
      "status": "completed",
      "total_purchase_value": 19.98,
      "tr_id": "txn_123456"
    }
  }'

Response

Success Response (200 OK)

Successful requests return 200 OK.

Error Responses

400 Bad Request - Missing required fields

401 Unauthorized - Invalid API key

Field Guidelines

Status Values

Status Field Values

Use "completed" or "success" for successful purchases and "failed" for failed transactions.

"completed" - Transaction was successful
"failed" - Transaction failed or was cancelled

Item ID vs Transaction ID

Item ID

The item_id should be the product identifier, not the transaction ID:

Correct:

"premium_monthly" - Product SKU
"coins_pack_100" - Item identifier

Incorrect:

"txn_abc123" - Transaction ID
"ord_456def" - Order ID

Currency Format

Use lowercase ISO 4217 currency codes:

"usd" - US Dollar
"eur" - Euro
"gbp" - British Pound
"jpy" - Japanese Yen

Purchase Types Examples

Subscription Purchase

{
  "type": "custom.purchase",
  "payload": {
    "item_id": "premium_annual",
    "item_name": "Premium Annual Subscription",
    "value": 79.99,
    "currency": "usd",
    "status": "completed",
    "total_purchase_value": 79.99
  }
}

One-Time Purchase

{
  "type": "custom.purchase",
  "payload": {
    "item_id": "remove_ads",
    "item_name": "Remove Ads Forever",
    "value": 4.99,
    "currency": "usd",
    "status": "completed",
    "total_purchase_value": 84.98
  }
}

Consumable Purchase

{
  "type": "custom.purchase",
  "payload": {
    "item_id": "gems_500",
    "item_name": "500 Gems Pack",
    "value": 2.99,
    "currency": "usd",
    "status": "completed",
    "total_purchase_value": 87.97
  }
}

Revenue Attribution

Purchase events enable powerful analytics in Audiencelab:

Revenue per creative - See which ads drive the most revenue
ROAS calculation - Return on ad spend by campaign
LTV analysis - Lifetime value by acquisition source
Conversion funnels - Track path from install to purchase

Best Practices

Track all purchases - Include every transaction, even small ones
Use accurate values - Report the actual amount charged to the user
Send immediately - Don't batch purchase events; send them as they occur
Include failed transactions - Tracking failures helps identify issues
Consistent item IDs - Use the same item_id for the same product across all users

What's Next

Also track ad monetization:

Ad View Event - Track ad impressions and revenue

On this page