Codelet PHP SDK

Official PHP client for the Codelet public API.

Install

composer require codelet/sdk

For local development from this monorepo:

composer install

Usage

<?php

use Codelet\Client;
use Codelet\Generated\Model\CancelSubscriptionRequest;
use Codelet\Generated\Model\IngestEventRequest;

$codelet = new Client(getenv('CODELET_API_KEY')); // cl_live_… or cl_test_…

// Ingest (auto idempotency_key when omitted)
$codelet->ingest(
    (new IngestEventRequest())
        ->setCustomerId('org_42')
        ->setMetric('api_call')
        ->setQuantity('1')
);

$me = $codelet->account->getMe();
$customers = $codelet->customers->listCustomers();
$codelet->subscriptions->cancelSubscription(
    'subs_…',
    (new CancelSubscriptionRequest())->setMode(CancelSubscriptionRequest::MODE_AT_PERIOD_END)
);

Optional constructor args: $baseUrl, $maxAttempts, $headers, $httpClient.

Examples

Create metrics before plans, credit packs, or ingest. Unknown metric names return 400.

Create a metric

use Codelet\Generated\Model\CreateMetricRequest;

$metric = $codelet->metrics->createMetric(
    (new CreateMetricRequest())
        ->setName('api_request')
        ->setDisplayName('API Request')
        ->setAggregation('sum')
);

Create a credit pack

use Codelet\Generated\Model\CreateCreditPackRequest;

$pack = $codelet->creditPacks->createCreditPack(
    (new CreateCreditPackRequest())
        ->setMetric('api_request')
        ->setName('500 API requests')
        ->setPriceAmount('25.00')
        ->setCurrency('USD')
        ->setQuantityGranted('500')
);

Create and publish a plan

use Codelet\Generated\Model\CreatePlanFixedFee;
use Codelet\Generated\Model\CreatePlanRequest;
use Codelet\Generated\Model\CreatePlanUsageFee;
use Codelet\Generated\Model\CreatePlanVersion;
use Codelet\Generated\Model\PlanBillingMode;
use Codelet\Generated\Model\PlanBillingPeriod;
use Codelet\Generated\Model\PlanFixedFeeType;
use Codelet\Generated\Model\PlanMetricBillingTiming;
use Codelet\Generated\Model\PlanMetricPricingModel;

$plan = $codelet->plans->createPlan(
    (new CreatePlanRequest())
        ->setName('Pro')
        ->setDescription('Usage-based Pro plan')
        ->setVersion(
            (new CreatePlanVersion())
                ->setCurrency('USD')
                ->setBillingPeriod(PlanBillingPeriod::MONTHLY)
                ->setBillingMode(PlanBillingMode::POSTPAID)
                ->setFixedFees([
                    (new CreatePlanFixedFee())
                        ->setFeeType(PlanFixedFeeType::PERIOD_CHARGE)
                        ->setName('Platform fee')
                        ->setAmount('29.00'),
                ])
                ->setUsageFees([
                    (new CreatePlanUsageFee())
                        ->setPricingModel(PlanMetricPricingModel::UNIT)
                        ->setBillingTiming(PlanMetricBillingTiming::IN_ARREARS)
                        ->setIncludedQuantity('1000')
                        ->setUnitPrice('0.002')
                        ->setMetric('api_request'),
                ])
        )
);

// Drafts are not checkout-ready until published
$codelet->plans->publishPlan($plan->getId());

Create checkout

Credit pack (one-time purchase):

use Codelet\Generated\Model\CreateCheckoutRequest;

$packCheckout = $codelet->checkout->createCheckout(
    (new CreateCheckoutRequest())
        ->setCustomerId('org_42')
        ->setPackId('pack_…')
        ->setSuccessUrl('https://yourapp.com/billing/success')
        ->setCancelUrl('https://yourapp.com/billing/cancel')
        ->setIdempotencyKey('purchase:order-123')
);
// Redirect the browser to $packCheckout->getCheckoutUrl()

Subscription (plan):

$planCheckout = $codelet->checkout->createCheckout(
    (new CreateCheckoutRequest())
        ->setCustomerId('org_42')
        ->setPlanId('plan_…')
        ->setSuccessUrl('https://yourapp.com/welcome')
);
// Redirect the browser to $planCheckout->getCheckoutUrl()

Pass either customer_id or customer_email, not both. Exactly one of pack_id or plan_id is required.

API reference

All generated methods are available on the Client instance (for example $codelet->customers->listCustomers). Prefer $codelet->ingest(…) over $codelet->usage->ingestEvent(…) when recording usage; the helper fills idempotency_key when omitted.

$codelet->ingest($body)

Ingest a usage event. Same as usage->ingestEvent, but generates idempotency_key when omitted.

Method	Description
ingest(IngestEventRequest $body)	POST /v1/ingest

Account ($codelet->account)

Method	Description
getMe()	API key context (project + environment)

Checkout ($codelet->checkout)

Method	Description
createCheckout($create_checkout_request)	Create a credit pack or subscription checkout

Credit packs ($codelet->creditPacks)

Method	Description
listCreditPacks($metric = null, $active = 'true', $page_size = 20, $cursor = null)	List packs (default: active only)
createCreditPack($create_credit_pack_request)	Create a pack
getCreditPack($pack_id)	Get a pack by ID
updateCreditPack($pack_id, $update_credit_pack_request)	Update name, description, and/or active

Customers ($codelet->customers)

Method	Description
listCustomers($page_size = 20, $cursor = null)	List customers
createCustomer($create_customer_request)	Create a customer
getCustomer($customer_id)	Get a customer
updateCustomer($customer_id, $update_customer_request)	Update editable fields
getCustomerBalance($customer_id, $metric = null)	Credit balances (all metrics, or one)

Metrics ($codelet->metrics)

Method	Description
listMetrics($page_size = 20, $cursor = null)	List metrics
createMetric($create_metric_request)	Create a metric
getMetric($name)	Get a metric by name
updateMetric($name, $update_metric_request)	Partial update (today: display_name)

Plans ($codelet->plans)

Method	Description
listPlans($status = 'published', $page_size = 20, $cursor = null)	List plans (default: published)
createPlan($create_plan_request)	Create a draft plan
getPlan($plan_id, $include_pricing_details = false)	Get a plan
publishPlan($plan_id)	Publish the draft version

Subscriptions ($codelet->subscriptions)

Method	Description
listSubscriptions($customer = null, $status = null, $page_size = 20, $cursor = null)	List subscriptions
getSubscription($subscription_id)	Get a subscription
cancelSubscription($subscription_id, $cancel_subscription_request)	Cancel (at_period_end or immediate)
resumeSubscription($subscription_id)	Clear a scheduled cancellation

Usage ($codelet->usage)

Method	Description
ingestEvent($ingest_event_request)	Ingest a usage event (no auto idempotency key)

Request and response shapes match the OpenAPI spec. See also codelet.co/SKILL.md for merchant integration guidance.

Errors

use Codelet\CodeletException;
use Codelet\RateLimitException;

try {
    $codelet->ingest($request);
} catch (RateLimitException $e) {
    // 429
} catch (CodeletException $e) {
    // other API errors (status + body)
}

Generated APIs throw ApiException from the OpenAPI client. The top-level ingest helper maps those to CodeletException / RateLimitException.

Development

# from repo root
make sdk-generate
cd sdks/php && composer install

Hand-written surface (src/) stays stable. Generated code under generated/ is overwritten by make sdk-generate.