README

Official PHP client for the ShedCloud Partner API (/partner/v1/*).

Use this package from PHP 8.2+ to call company-scoped Partner API endpoints with an API key (sc_live_…) or OAuth2 client credentials.

Install

composer require shedcloud/partner-api

Hosts

Pass environment for sandbox, or baseUrl for a custom/local override.

Quick start

API key (production)

<?php

require 'vendor/autoload.php';

use ShedCloud\PartnerApi\Auth;
use ShedCloud\PartnerApi\Client;

$client = new Client([
    'auth' => new Auth(apiKey: getenv('SHEDCLOUD_API_KEY')),
]);

$stock = $client->lotStock->list([
    'limit' => 50,
    'purchaseType' => 'Lot Stock',
    'sort' => 'price',
    'order' => 'asc',
]);

echo $stock['total'] . PHP_EOL;
echo $stock['data'][0]['title'] . PHP_EOL;

Sandbox

$client = new Client([
    'environment' => 'sandbox',
    'auth' => new Auth(apiKey: getenv('SHEDCLOUD_API_KEY')),
]);

OAuth2 client credentials

$client = new Client([
    'auth' => new Auth(
        clientId: getenv('SHEDCLOUD_CLIENT_ID'),
        clientSecret: getenv('SHEDCLOUD_CLIENT_SECRET'),
    ),
]);

$orders = $client->orders->list([
    'status' => 'Unprocessed',
    'limit' => 25,
]);

Create credentials in the ShedCloud portal under Settings → Developer API.

Resources

Each resource maps to a section of the hosted reference.

Idempotency and optimistic concurrency

use ShedCloud\PartnerApi\RequestOptions;

$quote = $client->quotes->create([
    'serialNumber' => 'SC-2024-00123',
    'customer' => ['name' => 'Jane Doe', 'email' => 'jane@example.com'],
], RequestOptions::withIdempotencyKey(bin2hex(random_bytes(16))));

$client->orders->update($order['id'], [
    'customerPhone' => '555-0100',
], RequestOptions::withIfMatch($order['version']));

For boolean query params that must be sent even when false, wrap the value:

use ShedCloud\PartnerApi\QueryValue;

$client->quotes->list(['converted' => new QueryValue(false)]);

Webhooks

Verify webhook deliveries with the subscription secret against the raw request body:

use ShedCloud\PartnerApi\Webhooks;

$body = file_get_contents('php://input');
Webhooks::verifySignature(
    getenv('SHEDCLOUD_WEBHOOK_SECRET'),
    $_SERVER['HTTP_X_SHEDCLOUD_SIGNATURE'] ?? '',
    $body,
);

http_response_code(200);

Errors

Failed responses throw ShedCloud\PartnerApi\Exception\PartnerApiException (or AuthException for OAuth token failures):

use ShedCloud\PartnerApi\Exception\PartnerApiException;

try {
    $client->orders->get($id);
} catch (PartnerApiException $e) {
    echo $e->status, ' ', $e->getMessage(), PHP_EOL;
    // $e->isUnauthorized(), isForbidden(), isNotFound(), isRateLimited()
}

Scopes

use ShedCloud\PartnerApi\Scopes;

Scopes::LOT_STOCK_READ; // partner-api.lot-stock.read
Scopes::ORDERS_WRITE;   // partner-api.orders.write

Development

composer install
composer test

Versioning & changelog

The Partner API is additive-only within /partner/v1. This package is tagged with semver in lockstep with API additions.

• API changes: hosted changelog

Docs

• Partner API reference: https://go.shedcloud.com/partner/reference
• Backend source of truth: shedcloud-api-go/docs/PARTNER_API.md
• TypeScript twin: @shedcloud/partner-api
• Go twin: shedcloud-gomod/partnerapi