Conversions

Track revenue and conversion events attributed to your email campaigns and flows. Conversions support multiple attribution models and can be linked to specific campaigns or flows.

List Conversions

GET

/conversions

List conversions with filtering and pagination

Name	Type	Required	Description
limit	integer	Optional	Number of results to return (default: 100, max: 1000)
offset	integer	Optional	Number of results to skip for pagination (default: 0)
contact_id	string (UUID)	Optional	Filter by contact ID
campaign_id	string (UUID)	Optional	Filter by campaign ID
type	string	Optional	Filter by conversion type: purchase, signup, upgrade, or custom

curl "https://api.topmail.so/api/v1/conversions?type=purchase&limit=50" \
  -H "Authorization: Bearer tm_live_abc123"

{
  "data": [
    {
      "id": "conv-uuid-12345",
      "type": "purchase",
      "revenue": 149.99,
      "currency": "USD",
      "order_id": "order-789",
      "contact": {
        "id": "contact-uuid-67890",
        "email": "customer@example.com"
      },
      "campaign": {
        "id": "campaign-uuid-11111",
        "name": "Summer Sale"
      },
      "flow": null,
      "attribution_model": "last_touch",
      "metadata": {},
      "converted_at": "2025-01-15T14:30:00.000Z",
      "created_at": "2025-01-15T14:30:00.000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 50,
    "offset": 0,
    "has_more": false
  }
}

Create Conversion

POST

/conversions

Track a conversion event for a contact

Name	Type	Required	Description
email	string	Optional	Contact email address. Required if contact_id is not provided.
contact_id	string (UUID)	Optional	Contact ID. Required if email is not provided.
type	string	Optional	Conversion type: purchase, signup, upgrade, or custom (default: custom)
revenue	number	Optional	Revenue amount (must be >= 0)
currency	string	Optional	3-letter ISO currency code (default: USD)
order_id	string	Optional	External order ID for deduplication (max 100 characters)
campaign_id	string (UUID)	Optional	Attribute this conversion to a specific campaign
flow_id	string (UUID)	Optional	Attribute this conversion to a specific flow
attribution_model	string	Optional	Attribution model: last_touch, first_touch, or linear (default: last_touch)
attribution_window	integer	Optional	Attribution window in days, 1-90 (default: 7)
metadata	object	Optional	Arbitrary key-value metadata to store with the conversion

curl -X POST https://api.topmail.so/api/v1/conversions \
  -H "Authorization: Bearer tm_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "type": "purchase",
    "revenue": 149.99,
    "currency": "USD",
    "order_id": "order-789",
    "campaign_id": "campaign-uuid-11111",
    "attribution_model": "last_touch",
    "attribution_window": 7,
    "metadata": {
      "product": "Premium Plan",
      "source": "checkout"
    }
  }'

{
  "data": {
    "id": "conv-uuid-12345",
    "type": "purchase",
    "revenue": 149.99,
    "currency": "USD",
    "order_id": "order-789",
    "contact_id": "contact-uuid-67890",
    "campaign_id": "campaign-uuid-11111",
    "flow_id": null,
    "attribution_model": "last_touch",
    "metadata": {
      "product": "Premium Plan",
      "source": "checkout"
    },
    "converted_at": "2025-01-15T14:30:00.000Z",
    "created_at": "2025-01-15T14:30:00.000Z"
  }
}

Attribution Models

last_touch -- Credit goes to the most recent campaign or flow interaction
first_touch -- Credit goes to the first campaign or flow that engaged the contact
linear -- Credit is distributed equally across all touchpoints