README

The official PHP client for the Elastly REST API.

Elastly prices quote and order lines for B2B sellers. Send a line (product, customer, quantity) and get back a price with the reasoning behind it: which pricing rules fired, what each one added, and how confident the engine is. The engine learns from the outcomes you feed back, so prices improve over time.

This client covers the full v1 API:

Prices: price up to 100 lines in one call.
Ingest: push products, customers, quotes, and orders from your own system in staged batches.
Write-backs: pull approved price changes into your system and confirm them once applied.

Install

composer require elastly/elastly-php

Requires PHP 8.1 or newer.

Authenticate

Create an API key in the dashboard (Settings, then API keys). Keys are scoped: an erp key prices lines, a connector key ingests data and claims write-backs. Send the key as a bearer token.

Price a line

<?php

require __DIR__ . '/vendor/autoload.php';

$config = Elastly\Configuration::getDefaultConfiguration()
    ->setAccessToken('elastly_live_...');

$prices = new Elastly\Api\PricesApi(null, $config);

$line = (new Elastly\Model\PricesRequestLinesInner())
    ->setProductSku('SKU-1042')
    ->setCustomerExternalId('CUST-88')
    ->setQuantity(25);

$request = (new Elastly\Model\PricesRequest())->setLines([$line]);

$response = $prices->getPrices(bin2hex(random_bytes(16)), $request);

foreach ($response->getLines() as $result) {
    if ($result->getOk()) {
        echo $result->getPriceCents() . ' ' . $result->getCurrency() . ': ' . $result->getReasonSummary() . PHP_EOL;
    } else {
        echo 'failed: ' . $result->getMessage() . PHP_EOL;
    }
}

Every response line is either a priced result (getOk() returns true) or a per-line error. One bad line never fails the batch.

Laravel

This package is framework-agnostic, so composer require is all Laravel needs. There is no service provider to register and nothing to publish.

To resolve a configured client from the container, bind it once in AppServiceProvider::register():

use Elastly\Api\PricesApi;
use Elastly\Configuration;

$this->app->singleton(PricesApi::class, function () {
    $config = Configuration::getDefaultConfiguration()
        ->setAccessToken(config('services.elastly.key'));

    return new PricesApi(null, $config);
});

Add the key to config/services.php as 'elastly' => ['key' => env('ELASTLY_API_KEY')], then type-hint PricesApi anywhere Laravel resolves dependencies.

Retries and idempotency

POST /v1/prices requires an Idempotency-Key header. Use a fresh key for each logical request and reuse the same key on retries. A replay returns the stored response, so a retried call never prices twice.

Price with a deadline and a fallback

If you price inside a checkout or quote flow, use the serving layer instead of calling the API directly. It puts a hard deadline on the call (800ms by default), retries transient failures with backoff, trips a circuit breaker when Elastly is down (5 failures, 30 second cooldown), and falls back to a price you supply instead of blocking your flow.

use Elastly\Configuration;
use Elastly\Model\PricesRequestLinesInner;
use Elastly\Serving\FailOpenPolicy;
use Elastly\Serving\FallbackPrice;
use Elastly\Serving\PricesNamespace;
use Elastly\Transport\ElastlyTransport;

$config = Configuration::getDefaultConfiguration()->setAccessToken('elastly_live_...');
$prices = new PricesNamespace(new ElastlyTransport($config));

$line = (new PricesRequestLinesInner())->setProductSku('SKU-1042')->setQuantity(25);

$result = $prices->get($line, FailOpenPolicy::staticFallback(
    fn ($line, $cause) => new FallbackPrice(priceCents: 1500),
));

if ($result->source() === 'elastly') {
    echo $result->priceCents . ' ' . $result->reasonSummary;
} elseif ($result->source() === 'fallback') {
    echo $result->priceCents . ' fallback because ' . $result->cause->reason;
} else {
    echo 'no price available: ' . $result->cause->reason;
}

Every result carries a source: elastly (a real price), fallback (your resolver's price), or unavailable (your resolver returned null). Mistakes on your side, like an invalid request or a bad key, always throw a typed error from Elastly\Errors instead of falling back. Prefer an exception over a fallback price? Pass FailOpenPolicy::throwOnFailure().

The transport handles retries and idempotency keys for you, so you do not need to manage the Idempotency-Key header yourself on this path.

Verify webhooks

Verify the elastly-signature header on every webhook before trusting the payload:

use Elastly\Webhooks\SignatureVerificationError;
use Elastly\Webhooks\WebhooksNamespace;

$webhooks = new WebhooksNamespace();

try {
    $event = $webhooks->verify($rawBody, $signatureHeader, 'whsec_...');
} catch (SignatureVerificationError $error) {
    // reject with a 400
}

echo $event->event;

verify checks the HMAC signature in constant time, rejects replays older than 5 minutes, and returns a typed event.

Close the loop

Elastly learns from the difference between the price it recommended and the price your team actually charged. When you ingest quotes, echo the pricingDecisionId you received from the prices call on the matching quote line. Skip that and the engine has nothing to learn from.

Documentation

API reference
Per-endpoint docs for this client live in docs.

About this repository

This code is generated from the Elastly OpenAPI contract, so pull requests against generated files get overwritten by the next release. If something is broken or missing, open an issue or email support@elastly.io.

License

MIT

elastly / elastly-php

Maintainers

Package info

Statistics

Security