README

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.

shelfwatch / shelfwatch

Maintainers

Package info

Statistics

Security