ShelfWatch Ruby SDK

Official Ruby client for ShelfWatch APIs v2.

gem install shelfwatch

Requires Ruby 2.6 or newer.

Quick start

Create credentials in ShelfWatch Console → Integrations, then:

require "shelfwatch"

client = ShelfWatch.new(
  api_key: "swpk_…",
  project_id: "PROJECT_UUID",
)

visits = client.visits.list(
  start_date: "2026-07-01",
  end_date: "2026-07-31",
)
puts visits["data"]

detail = client.visits.get(
  visits["data"][0]["visit_uuid"],
  include_kpis: true,
)

OAuth client credentials

client = ShelfWatch.new(
  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
ShelfWatch::ValidationError	400
ShelfWatch::AuthenticationError	401
ShelfWatch::ForbiddenError	403
ShelfWatch::NotFoundError	404
ShelfWatch::RateLimitError	429
ShelfWatch::ServerError	5xx
ShelfWatch::Error	other

require "shelfwatch"

begin
  client.visits.get("missing-uuid")
rescue ShelfWatch::NotFoundError => e
  puts "#{e.status_code} #{e.message}"
end

Development

bundle install
bundle exec rake test

Publish to RubyGems

Create an API key at rubygems.org/profile/api_keys with the Push rubygem scope (see API key scopes). Then either:

# credentials file (~/.gem/credentials or ~/.local/share/gem/credentials)
mkdir -p ~/.gem
chmod 0700 ~/.gem
printf -- "---\n:rubygems_api_key: rubygems_YOUR_KEY\n" > ~/.gem/credentials
chmod 0600 ~/.gem/credentials

or set GEM_HOST_API_KEY for a one-off push:

export GEM_HOST_API_KEY=rubygems_YOUR_KEY

Publish:

./scripts/publish.sh

Or manually:

gem build shelfwatch.gemspec
gem push shelfwatch-*.gem

Bump VERSION in lib/shelfwatch/version.rb (User-Agent follows automatically) before each release.