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

# Python SDK

> Official Python SDK for CutMeShort API

## Installation

Install via pip:

```bash theme={null}
pip install cutmeshort
```

## Requirements

* Python 3.8 or higher
* requests library (installed as dependency)

## Quick Start

```python theme={null}
#!/usr/bin/env python3
from cutmeshort import CMSClient

bearer_token = "your_bearer_token"
client = CMSClient(token=bearer_token)
```

## Non-Deferred Lead Tracking

Track lead events with complete information including the `click_id`.

```python theme={null}
#!/usr/bin/env python3
from cutmeshort import CMSClient

bearer_token = "your_bearer_token"
client = CMSClient(token=bearer_token)

# Standard lead with complete payload
response = client.track_lead(
    click_id="5e6e1650-5641-4a2b-bec6-218288a86dbf",
    event_name="signup_started",
    customer_external_id="user_42",
    customer_name="John Doe",
    customer_email="john@example.com",
)

print(response)
```

### Lead Tracking Parameters

* `click_id` (str) - The unique click identifier
* `event_name` (str) - Name of the lead event (e.g., "signup\_started", "email\_verified")
* `customer_external_id` (str) - Your internal customer identifier
* `customer_name` (str, optional) - Full name of the customer
* `customer_email` (str, optional) - Customer's email address
* `timestamp` (str, optional) - ISO 8601 timestamp (auto-set if not provided)

## Deferred Lead Tracking

Use deferred mode for two-step lead attribution when the `click_id` isn't available at the event time.

### Step 1: Initialize Deferred Lead Tracking

```python theme={null}
#!/usr/bin/env python3
from cutmeshort import CMSClient

bearer_token = "your_bearer_token"
client = CMSClient(token=bearer_token)

# Step 1: Setup deferred mode - store clickId association
response = client.track_lead(
    click_id="5e6e1650-5641-4a2b-bec6-218288a86dbf",
    event_name="lead_captured",
    customer_external_id="user_72",
    customer_name="Jane Smith",
    customer_email="jane@example.com",
    mode="deferred",
)

print(response)
```

### Step 2: Track Follow-up Events

```python theme={null}
#!/usr/bin/env python3
from cutmeshort import CMSClient

bearer_token = "your_bearer_token"
client = CMSClient(token=bearer_token)

# Step 2: Later, track using just customer_external_id (no click_id)
response = client.track_lead(
    event_name="kyc_completed",
    customer_external_id="user_72",
)

print(response)
```

**Key Benefits:**

* Store click context for later reference
* Track multiple user journey events without losing attribution
* Simplify event tracking for complex workflows

**Complete Deferred Example:**

```python theme={null}
#!/usr/bin/env python3
from cutmeshort import CMSClient

bearer_token = "your_bearer_token"
client = CMSClient(token=bearer_token)

# Initialize deferred tracking
client.track_lead(
    click_id="5e6e1650-5641-4a2b-bec6-218288a86dbf",
    event_name="signup_started",
    customer_external_id="user_42",
    customer_name="cutmeshort",
    customer_email="cutmeshort@cms.com",
    mode="deferred",
)

# Track email verification without click_id
client.track_lead(
    event_name="email_verified",
    customer_external_id="user_42",
)
```

## Sale Tracking

Track completed sales and revenue events with full transaction details.

```python theme={null}
#!/usr/bin/env python3
import os
from cutmeshort import CMSClient

# Get Bearer token from environment
bearer_token = os.environ.get("CMS_BEARER_TOKEN", "your_bearer_token")

# Create client
client = CMSClient(token=bearer_token)

# Track a sale
response = client.track_sale(
    click_id="id_123",
    event_name="purchase_completed",
    customer_external_id="user_42",
    invoice_id="inv_987",
    amount=4999,  # amount in cents ($49.99)
    currency="USD",
    customer_name="John Doe",
    customer_email="john@example.com",
)

print(response)
```

### Sale Tracking Parameters

* `click_id` (str) (optional) - The unique click identifier
* `event_name` (str) - Name of the sale event (e.g., "purchase\_completed", "payment\_received")
* `customer_external_id` (str) - Your internal customer identifier
* `invoice_id` (str) - Invoice or transaction identifier
* `amount` (int) - Amount in cents (e.g., 4999 = \$49.99)
* `currency` (str) - 3-letter currency code (e.g., "USD", "EUR", "INR")
* `customer_name` (str, optional) - Customer's name
* `customer_email` (str, optional) - Customer's email
* `timestamp` (str, optional) - ISO 8601 timestamp (auto-set if not provided)

## Error Handling

```python theme={null}
#!/usr/bin/env python3
from cutmeshort import CMSClient

client = CMSClient(token="your_bearer_token")

try:
    response = client.track_lead(
        click_id="5e6e1650-5641-4a2b-bec6-218288a86dbf",
        event_name="signup_started",
        customer_external_id="user_42",
    )
    
    if response.success:
        print("✅ Lead tracking successful!")
    else:
        print(f"❌ Error: {response.error}")
        
except Exception as e:
    print(f"Exception: {str(e)}")
```

## Documentation

For complete documentation, visit [Python SDK Docs](https://github.com/Cut-Me-Short/cutmeshort)