README

Official PHP SDK for the TrueTrial API. Manage orders, shipments, temporal elements (trials, warranties, subscriptions), cancellations, and webhooks.

Requirements

• PHP 8.2 or higher
• Guzzle HTTP 7.x

Installation

composer require truetrial/sdk

Quick Start

Create a Client

use TrueTrial\TrueTrial;

$truetrial = new TrueTrial('your-api-key');

// Or with a custom base URL
$truetrial = new TrueTrial('your-api-key', 'https://api.truetrial.com/api/v1');

Create an Order

$order = $truetrial->orders->create([
    'external_order_id' => 'ORD-12345',
    'product_name' => 'Premium Supplement',
    'product_type' => 'physical',
    'product_price_cents' => 4999,
    'product_currency' => 'USD',
    'consumer_email' => 'customer@example.com',
    'consumer_first_name' => 'Jane',
    'consumer_last_name' => 'Doe',
    'temporal_type' => 'trial',
    'temporal_duration_value' => 30,
    'temporal_duration_unit' => 'days',
]);

echo $order['id']; // ULID

List Orders

// All orders
$response = $truetrial->orders->list();

// With filters
$response = $truetrial->orders->list([
    'status' => 'trial_active',
    'page' => 1,
    'per_page' => 25,
]);

foreach ($response['data'] as $order) {
    echo $order['product_name'] . ' - ' . $order['status'] . "\n";
}

Get Order Status

$status = $truetrial->orders->status('01HQ4X5K...');
// Returns: order_status, temporal_element_status, shipment_status

Create a Shipment

$shipment = $truetrial->shipments->create('01HQ4X5K...', [
    'carrier' => 'ups',
    'tracking_number' => '1Z999AA10123456784',
]);

Confirm Digital Delivery

$delivery = $truetrial->digitalDelivery->confirm('01HQ4X5K...', [
    'method' => 'link_click',
    'delivered_at' => '2026-02-08T12:00:00Z',
]);

Manage Temporal Elements

// Get temporal element for an order
$temporal = $truetrial->temporal->get('01HQ4X5K...');

// Extend a trial
$truetrial->temporal->extend('01HQ4X5K...', [
    'additional_days' => 7,
    'reason' => 'Customer request - shipping delay',
]);

// Adjust temporal element
$truetrial->temporal->adjust('01HQ4X5K...', [
    'new_end_time' => '2026-04-01T00:00:00Z',
    'reason' => 'Manual adjustment',
]);

// Submit a warranty claim
$truetrial->temporal->claim('01HQ4X5K...', [
    'description' => 'Product defect - screen crack',
    'evidence' => ['photo_url' => 'https://...'],
]);

// Resolve a warranty claim
$truetrial->temporal->resolveClaim('01HQ4X5K...', [
    'resolution' => 'claim_approved',
    'notes' => 'Replacement authorized',
]);

Cancellations

// Initiate cancellation
$cancellation = $truetrial->cancellations->create('01HQ4X5K...', [
    'reason' => 'Customer changed their mind',
]);

// Get cancellation details
$cancellation = $truetrial->cancellations->get('01HQ4X5K...');

Webhooks

// List webhook subscriptions
$webhooks = $truetrial->webhooks->list();

// Create a webhook subscription
$webhook = $truetrial->webhooks->create([
    'url' => 'https://yourapp.com/webhooks/truetrial',
    'events' => ['order.delivered', 'trial.started', 'trial.expiring'],
]);

// Delete a webhook
$truetrial->webhooks->delete('01HQ4WEBHOOK...');

System Health

$health = $truetrial->system->carrierHealth();

Webhook Verification

Verify incoming webhook signatures to ensure authenticity:

use TrueTrial\Webhook;

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_TRUETRIAL_SIGNATURE'];
$timestamp = (int) $_SERVER['HTTP_X_TRUETRIAL_TIMESTAMP'];
$secret = 'your-webhook-secret';

// Simple verification
$isValid = Webhook::verify($payload, $signature, $secret);

// With timestamp tolerance (reject webhooks older than 5 minutes)
$isValid = Webhook::verify($payload, $signature, $secret, 300, $timestamp);

// Verify and decode in one step
try {
    $event = Webhook::constructEvent($payload, $signature, $secret, 300, $timestamp);

    match ($event['event']) {
        'order.delivered' => handleDelivery($event['data']),
        'trial.started' => handleTrialStart($event['data']),
        'trial.expiring' => handleTrialExpiring($event['data']),
        default => null,
    };
} catch (\TrueTrial\Exceptions\TrueTrialException $e) {
    http_response_code(400);
    echo 'Invalid signature';
}

Data Objects

The SDK includes optional data objects for convenience:

use TrueTrial\DataObjects\Order;
use TrueTrial\DataObjects\PaginatedResponse;

$response = $truetrial->orders->list();
$paginated = PaginatedResponse::fromArray($response);
echo "Page {$paginated->currentPage} of {$paginated->lastPage}\n";

$order = Order::fromArray($response['data'][0]);
echo $order->productName;
echo $order->status;

Available data objects:

• Order -- id, tenantId, consumerId, externalOrderId, productName, productType, productPriceCents, productCurrency, status, metadata, createdAt, consumer
• Consumer -- id, email, firstName, lastName, phone
• Shipment -- id, orderId, carrier, trackingNumber, status, estimatedDelivery, deliveredAt
• TemporalElement -- id, orderId, type, status, durationValue, durationUnit, beginTime, endTime, expiresAt
• Cancellation -- id, orderId, reason, status, cancelledAt
• WebhookSubscription -- id, url, events, secret, lastTriggeredAt
• OrderStatus -- orderId, externalOrderId, orderStatus, temporalElementStatus, shipmentStatus
• PaginatedResponse -- data, currentPage, lastPage, perPage, total

Error Handling

The SDK throws specific exceptions for different error conditions:

use TrueTrial\Exceptions\AuthenticationException;
use TrueTrial\Exceptions\NotFoundException;
use TrueTrial\Exceptions\ValidationException;
use TrueTrial\Exceptions\RateLimitException;
use TrueTrial\Exceptions\ServerException;
use TrueTrial\Exceptions\TrueTrialException;

try {
    $order = $truetrial->orders->get('01HNONEXISTENT');
} catch (AuthenticationException $e) {
    // 401 - Invalid or missing API key
    echo "Auth failed: " . $e->getMessage();
} catch (NotFoundException $e) {
    // 404 - Resource not found
    echo "Not found: " . $e->getMessage();
} catch (ValidationException $e) {
    // 422 - Validation errors
    echo "Validation failed: " . $e->getMessage();
    foreach ($e->errors() as $field => $messages) {
        echo "{$field}: " . implode(', ', $messages) . "\n";
    }
} catch (RateLimitException $e) {
    // 429 - Rate limit exceeded
    $retryAfter = $e->retryAfter(); // seconds until retry, or null
    echo "Rate limited. Retry after: {$retryAfter}s";
} catch (ServerException $e) {
    // 500+ - Server error
    echo "Server error: " . $e->getMessage();
} catch (TrueTrialException $e) {
    // Catch-all for any other SDK error
    echo "Error [{$e->statusCode}]: " . $e->getMessage();
}

All exceptions extend TrueTrialException and include:

• $statusCode -- HTTP status code
• $responseBody -- raw response body string

Enums

The SDK provides string-backed enums for type safety:

use TrueTrial\Enums\OrderStatus;
use TrueTrial\Enums\TemporalType;
use TrueTrial\Enums\TemporalStatus;

$truetrial->orders->list(['status' => OrderStatus::TrialActive->value]);

API Reference

License

MIT