ShelfWatch PHP SDK

Official PHP client for ShelfWatch APIs v2.

composer require shelfwatch/shelfwatch

Requires PHP 8.1 or newer.

Quick start

Create credentials in ShelfWatch Console → Integrations, then:

<?php

use ShelfWatch\ShelfWatch;

$client = new ShelfWatch([
    'api_key' => 'swpk_…',
    'project_id' => 'PROJECT_UUID',
]);

$visits = $client->visits->list([
    'start_date' => '2026-07-01',
    'end_date' => '2026-07-31',
]);
print_r($visits['data']);

$detail = $client->visits->get($visits['data'][0]['visit_uuid'], [
    'include_kpis' => true,
]);

OAuth client credentials

$client = new ShelfWatch([
    'client_id' => 'swoc_…',
    'client_secret' => 'swocs_…',
    'project_id' => 'PROJECT_UUID',
]);
// Access tokens are fetched and refreshed automatically.

API coverage

Resource	Methods
$client->visits	list, get
$client->mdm	stores, users, categories, brands, skus, schedules
$client->reports	list, generate

Filters that accept multiple values can be passed as a comma-separated string or an array:

$client->visits->list([
    'start_date' => '2026-07-01',
    'end_date' => '2026-07-31',
    'visit_status' => ['completed'],
    'store_code' => ['S001', 'S002'],
]);

$stores = $client->mdm->stores(['q' => 'delhi']);
$reports = $client->reports->list();
$rows = $client->reports->generate('visit-level', [
    'start_date' => '2026-07-01',
    'end_date' => '2026-07-07',
]);

Full HTTP reference: ShelfWatch Console → Help and Support, or the apis-v2 docs.

Errors

Typed exceptions map to HTTP status codes:

Exception	Status
ValidationError	400
AuthenticationError	401
ForbiddenError	403
NotFoundError	404
RateLimitError	429
ServerError	5xx
ShelfWatchError	other

use ShelfWatch\Exceptions\NotFoundError;
use ShelfWatch\ShelfWatch;

try {
    $client->visits->get('missing-uuid');
} catch (NotFoundError $e) {
    echo $e->statusCode, ' ', $e->getMessage(), PHP_EOL;
}

Development

composer install
composer test

Publish to Packagist

Tag a release and push; Packagist (or ./scripts/publish.sh) will pick up the tagged version after the GitHub repository is linked.

Bump version in composer.json and ShelfWatch::VERSION / User-Agent before each release.