> ## 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.

# PHP SDK

> Official PHP SDK for CutMeShort API

## Installation

Install via Composer:

```bash theme={null}
composer require cutmeshort
```

## Requirements

* PHP 7.4 or higher
* Composer for dependency management
* cURL extension enabled

## Quick Start

```php theme={null}
<?php
require_once __DIR__ . '/vendor/autoload.php';

use CutMeShort\SDK\Client;

$client = new Client();
$client->setAccessToken('your_api_token_here')
    ->setDebug(true);

$trackingApi = $client->getTrackingApi();
```

## Non-Deferred Lead Tracking

Track lead events when you have all the required information available immediately, including the `clickId`.

```php theme={null}
<?php
require_once __DIR__ . '/vendor/autoload.php';

use CutMeShort\SDK\Client;
use CutMeShort\SDK\Models\LeadPayload;

$client = new Client();
$client->setAccessToken('your_api_token_here');

$trackingApi = $client->getTrackingApi();

// Create and track a lead with complete payload
$leadPayload = new LeadPayload();
$leadPayload->setClickId('clickid')
    ->setCustomerExternalId('user_123')
    ->setEventName('signup')
    ->setCustomerName('John Doe')
    ->setCustomerEmail('john@example.com');

try {
    $response = $trackingApi->trackLead($leadPayload);
    
    if ($response->getStatus()) {
        echo "✅ Lead Tracking successful!\n";
        echo "Message: " . $response->getData() . "\n";
    } else {
        echo "❌ Lead Tracking failed\n";
        echo "Error: " . $response->getData() . "\n";
    }
} catch (\Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}
?>
```

### Lead Payload Methods

* `setClickId(string $clickId)` - The unique click identifier
* `setEventName(string $eventName)` - Name of the lead event (e.g., "signup", "email\_verified")
* `setCustomerExternalId(string $id)` - Your internal customer identifier
* `setCustomerName(string $name)` - Full name of the customer
* `setCustomerEmail(string $email)` - Customer's email address
* `setTimestamp(string $timestamp)` - ISO 8601 timestamp (auto-set if not provided)

## Deferred Lead Tracking

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

### Step 1: Store the clickId Association

```php theme={null}
<?php
require_once __DIR__ . '/vendor/autoload.php';

use CutMeShort\SDK\Client;
use CutMeShort\SDK\Models\LeadPayload;

$client = new Client();
$client->setAccessToken('your_api_token_here');

$trackingApi = $client->getTrackingApi();

// Step 1: Create initial lead with deferred mode
$payload = new LeadPayload();
$payload->setClickId('clickid')
    ->setMode('deferred')
    ->setEventName('signup')
    ->setCustomerExternalId('user_123')
    ->setCustomerName('John Doe')
    ->setCustomerEmail('john@example.com');

try {
    $response = $trackingApi->trackLead($payload);
    
    if ($response->getStatus()) {
        echo "✅ Deferred Lead Tracking initialized!\n";
        echo "Stored clickId association with customerExternalId\n";
    } else {
        echo "❌ Failed to initialize deferred lead tracking\n";
    }
} catch (\Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}
?>
```

### Step 2: Track Using Only customerExternalId

```php theme={null}
<?php
require_once __DIR__ . '/vendor/autoload.php';

use CutMeShort\SDK\Client;
use CutMeShort\SDK\Models\LeadPayload;

$client = new Client();
$client->setAccessToken('your_api_token_here');

$trackingApi = $client->getTrackingApi();

// Step 2: Later, track using just customerExternalId (no clickId)
$followUpPayload = new LeadPayload();
$followUpPayload->setCustomerExternalId('user_123')
    ->setEventName('email_verified');

try {
    $response = $trackingApi->trackLead($followUpPayload);
    
    if ($response->getStatus()) {
        echo "✅ Follow-up Lead Tracking successful!\n";
        echo "Used stored clickId from deferred mode\n";
    } else {
        echo "❌ Follow-up Lead Tracking failed\n";
    }
} catch (\Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}
?>
```

**Key Benefits:**

* Store click context for later use
* Track multiple events in a user journey without losing click attribution
* No need to maintain clickId across complex workflows

## Sale Tracking

Track completed sales and revenue events with full transaction details.

```php theme={null}
<?php
require_once __DIR__ . '/vendor/autoload.php';

use CutMeShort\SDK\Client;
use CutMeShort\SDK\Models\SalePayload;

$client = new Client();
$client->setAccessToken('your_api_token_here');

$trackingApi = $client->getTrackingApi();

// Create and track a sale
$salePayload = new SalePayload();
$salePayload->setClickId('clickid')
    ->setEventName('purchase')
    ->setCustomerExternalId('user_123')
    ->setCustomerName('Jane Smith')
    ->setCustomerEmail('jane@example.com')
    ->setInvoiceId('INV-2024-001')
    ->setAmount(4999) // Amount in cents
    ->setCurrency('USD');

try {
    $response = $trackingApi->trackSale($salePayload);
    
    if ($response->getStatus()) {
        echo "✅ Sale Tracking successful!\n";
        echo "Message: " . $response->getData() . "\n";
    } else {
        echo "❌ Sale Tracking failed\n";
        echo "Error: " . $response->getData() . "\n";
    }
} catch (\Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}
?>
```

### Sale Payload Methods

* `setClickId(string $clickId)(optional)` - The unique click identifier
* `setEventName(string $eventName)` - Name of the sale event (e.g., "purchase", "purchase\_completed")
* `setCustomerExternalId(string $id)` - Your internal customer identifier
* `setInvoiceId(string $invoiceId)` - Invoice or transaction identifier
* `setAmount(float $amount)` - Amount in cents (e.g., 4999 = \$49.99)
* `setCurrency(string $currency)` - 3-letter currency code (e.g., "USD", "EUR", "INR")
* `setCustomerName(string $name)` - Customer's name
* `setCustomerEmail(string $email)` - Customer's email
* `setTimestamp(string $timestamp)` - ISO 8601 timestamp (auto-set if not provided)

## Error Handling

```php theme={null}
<?php
try {
    $response = $trackingApi->trackLead($leadPayload);
    
    if ($response->getStatus()) {
        echo "✅ Success!\n";
    } else {
        echo "Error: " . $response->getData() . "\n";
    }
} catch (\Exception $e) {
    echo "Exception caught: " . $e->getMessage() . "\n";
    echo "Code: " . $e->getCode() . "\n";
}
?>
```

## Configuration

```php theme={null}
<?php
$client = new Client();
$client->setAccessToken('your_api_token_here')
    ->setDebug(true)  // Enable debug mode
    ->setTimeout(10000) // Set timeout in milliseconds
    ->setMaxRetries(2); // Set maximum retries
?>
```

## Documentation

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