guide
User Guide
Everything you need to run your commerce operations on WhaleTools. From store setup to AI-powered automation.
Getting Started
Create your store, generate an API key, and make your first API call in under five minutes.
Create a store
Sign up at whaletools.dev and create your first store from the dashboard. Each store gets its own dedicated VM with Postgres, AI agent, and workflow engine.
Generate an API key
Go to Settings > API Keys in the ops dashboard. Create a key with the scopes you need. Live keys start with wk_live_, test keys with wk_test_.
Make your first request
Use the x-api-key header to authenticate. Try listing your products to confirm everything works.
# List your products
curl https://vm.whaletools.cloud/v1/products \
-H "x-api-key: wk_live_your_key_here"Products
Create products with variants, set pricing tiers, manage images, and organize your catalog with categories and collections.
Create a product
POST to /v1/products with a name, price, and optional description. The product gets a unique ID and is immediately available via the API.
Add variants
Products can have variants (size, color, etc). POST to /v1/products/:id/variations with option values and variant-specific pricing.
Set pricing
Each product or variant has a price in cents. Set compare_at_price for sale display. Use price lists for wholesale or multi-currency.
# Create a product
curl -X POST https://vm.whaletools.cloud/v1/products \
-H "x-api-key: wk_live_..." \
-H "Content-Type: application/json" \
-d '{"name":"Espresso Blend","price":1495,"sku":"ESP-001"}'Orders
Walk through the checkout flow, manage fulfillment status, process refunds, and track order lifecycle events.
Checkout flow
Create a cart, add items, then POST to /v1/checkout to create an order. The checkout intent handles payment collection and order creation atomically.
Fulfillment
Update order status through pending > processing > shipped > delivered. Each transition fires a webhook event for downstream systems.
Refunds
POST to /v1/orders/:id/refund with an amount or line_items array. Partial and full refunds are supported. The payment provider handles the actual reversal.
# Create a checkout
curl -X POST https://vm.whaletools.cloud/v1/checkout \
-H "x-api-key: wk_live_..." \
-H "Content-Type: application/json" \
-d '{"cart_id":"cart_abc123","payment_method":"pm_..."}'Customers
Create and search customer profiles, view order history, manage loyalty points, and use AI-powered customer intelligence.
Create a customer
POST to /v1/customers with name and email. Duplicate emails are rejected with a 409 conflict error.
Search customers
GET /v1/customers?q=search_term supports full-text search across name, email, and phone. Combine with filters for segment targeting.
Loyalty points
Enroll customers in your loyalty program. Points accrue automatically on orders and can be redeemed at checkout via the loyalty API.
# Create a customer
curl -X POST https://vm.whaletools.cloud/v1/customers \
-H "x-api-key: wk_live_..." \
-H "Content-Type: application/json" \
-d '{"name":"Jane Doe","email":"jane@example.com"}'Inventory
Track stock levels across locations, create adjustments, initiate transfers between locations, and configure units of measure.
Stock adjustments
POST to /v1/inventory/adjustments to increment or decrement stock. Each adjustment is logged with a reason code for audit trails.
Transfers
Move inventory between locations with /v1/inventory/transfers. Transfers go through requested > in_transit > received states.
Units of measure
Configure custom units (each, case, pallet) and conversion factors. The inventory system tracks quantities in the configured base unit.
# Adjust stock
curl -X POST https://vm.whaletools.cloud/v1/inventory/adjustments \
-H "x-api-key: wk_live_..." \
-H "Content-Type: application/json" \
-d '{"product_id":"prod_...","location_id":"loc_...","quantity":50,"reason":"restock"}'POS
Set up terminal devices, process in-person checkout, manage cash drawer sessions, and handle card-present payments.
Terminal setup
Register a terminal device with POST /v1/pos/terminals. Each terminal gets a unique device_id and is linked to a location.
POS checkout
Create a POS session, scan or search products, and complete payment. Card-present payments use the terminal integration; cash and other methods are recorded directly.
Close session
End a POS session with POST /v1/pos/sessions/:id/close. This reconciles the cash drawer, logs all transactions, and generates the shift report.
# Register a terminal
curl -X POST https://vm.whaletools.cloud/v1/pos/terminals \
-H "x-api-key: wk_live_..." \
-H "Content-Type: application/json" \
-d '{"name":"Counter 1","location_id":"loc_...","device_type":"stripe_s700"}'AI Agent
Chat with the built-in AI agent, create automated workflows, and let the agent handle commerce operations on your behalf.
Start a conversation
POST to /v1/agent/chat with a message. The agent has access to your store data and can answer questions, create products, look up orders, and more.
Workflows
Define event-driven workflows that trigger on order.created, customer.created, and other events. Workflows can include agent steps that use AI to make decisions.
Automation
Use the agent to automate repetitive tasks: restock alerts, customer follow-ups, report generation, and inventory reconciliation.
# Send a message to the agent
curl -X POST https://vm.whaletools.cloud/v1/agent/chat \
-H "x-api-key: wk_live_..." \
-H "Content-Type: application/json" \
-d '{"message":"What were my top 5 products this week?"}'Analytics
Query sales reports, customer dashboards, product performance, and real-time metrics through the analytics API.
Sales reports
GET /v1/analytics/sales returns revenue, order count, and average order value for a date range. Group by day, week, or month.
Dashboards
The analytics API powers the ops dashboard. Query customer lifetime value, cohort retention, product velocity, and more.
Real-time metrics
Live metrics are available via the telemetry API. Track active sessions, current cart values, and conversion funnel in real time.
# Sales report for the last 30 days
curl "https://vm.whaletools.cloud/v1/analytics/sales?period=30d&group_by=day" \
-H "x-api-key: wk_live_..."Webhooks
Subscribe to real-time events, verify webhook signatures, and handle delivery retries for reliable event-driven integrations.
Subscribe
POST to /v1/webhooks with a URL and list of event types. The endpoint receives JSON payloads for each matching event.
Verify signatures
Each webhook includes a Whale-Signature header. Verify it using HMAC-SHA256 with your webhook secret to confirm authenticity.
Retry policy
Failed deliveries (non-2xx response) retry with exponential backoff: 1m, 5m, 30m, 2h, 24h. After 5 attempts the event is marked as failed in the dead letter queue.
# Create a webhook subscription
curl -X POST https://vm.whaletools.cloud/v1/webhooks \
-H "x-api-key: wk_live_..." \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/hooks","events":["order.created","order.paid"]}'API Keys
Manage API key scopes, rotate keys without downtime, and understand the permission model for secure integrations.
Scopes
Each key has scopes like read:products, write:orders, or * for full access. Use the minimum scopes needed for each integration.
Key rotation
Create a new key, update your integration to use it, then delete the old key. Both keys work simultaneously during the transition window.
Security
Never expose API keys in client-side code. Use server-side proxies or the Storefront SDK (which uses public keys) for browser-facing integrations.
# Create a scoped API key
curl -X POST https://vm.whaletools.cloud/v1/api-keys \
-H "x-api-key: wk_live_admin_key..." \
-H "Content-Type: application/json" \
-d '{"name":"Storefront read-only","scopes":["read:products","read:inventory"]}'