Square Sandbox Simulator

Generate realistic POS data in your Square sandbox — categories, items, discounts, taxes, team members, customers, orders, payments, and refunds. Built for testing Square integrations without manual data entry.

Features

9 business types — restaurant, cafe/bakery, bar, food truck, fine dining, pizzeria, retail clothing, retail general, salon/spa
1000+ menu items with realistic prices via FactoryBot factories
Realistic order simulation — meal periods, dining options, tips, split payments, refunds
Idempotent operations — safe to re-run; entities matched by name, orders tracked by ID
Full audit trail — every API request/response persisted to PostgreSQL
Timezone-aware — fetches merchant timezone from Square API
CLI + programmatic API — use from terminal or integrate into your Rails app

Installation

gem install square_sandbox_simulator

Or add to your Gemfile:

gem "square_sandbox_simulator"

Quick Start

1. Configure credentials

Create a .env.json file:

{
  "DATABASE_URL": "postgres://localhost:5432/square_simulator_development",
  "locations": [
    {
      "SQUARE_LOCATION_ID": "YOUR_LOCATION_ID",
      "SQUARE_ACCESS_TOKEN": "YOUR_SANDBOX_ACCESS_TOKEN",
      "SQUARE_LOCATION_NAME": "Test Location"
    }
  ]
}

2. Set up database (optional, for audit trail)

simulate db create
simulate db migrate
simulate db seed --type restaurant

3. Create entities in Square

simulate setup --business_type restaurant

This creates categories, items, discounts, tax rates, team members, and customers in your Square sandbox.

4. Generate orders

# Full realistic day (40-120 orders based on day of week)
simulate day

# Specific count
simulate generate -n 50

# Busy day (2x volume)
simulate day -x 2.0

CLI Commands

Command	Description
`simulate setup`	Create entities (categories, items, discounts, taxes, team, customers)
`simulate generate -n N`	Generate N orders for today
`simulate day [-x MULT]`	Generate realistic full day of orders
`simulate status`	Show entity counts
`simulate orders [-l N]`	List recent orders
`simulate summary [-d DATE]`	Daily summary (requires DB)
`simulate delete --confirm`	Delete all entities
`simulate locations`	List configured locations
`simulate db create`	Create PostgreSQL database
`simulate db migrate`	Run migrations
`simulate db seed`	Seed business type data
`simulate db reset --confirm`	Drop, create, migrate, seed

Global flags: -v (verbose), -l LOCATION_ID, -i INDEX (location index)

Programmatic Usage

require "square_sandbox_simulator"

# Configure
SquareSandboxSimulator.configure do |config|
  config.location_id = "YOUR_LOCATION_ID"
  config.access_token = "YOUR_ACCESS_TOKEN"
  config.business_type = :restaurant
end

# Set up entities
generator = SquareSandboxSimulator::Generators::EntityGenerator.new(
  business_type: :restaurant
)
result = generator.setup_all
# => { categories: [...], items: [...], discounts: [...], tax_rates: [...], ... }

# Generate orders
order_gen = SquareSandboxSimulator::Generators::OrderGenerator.new(
  refund_percentage: 5
)
orders = order_gen.generate_realistic_day(multiplier: 1.0)
# or
orders = order_gen.generate_for_date(Date.today, count: 50)

Order Simulation Details

Orders follow realistic restaurant patterns:

Meal Period	Hours	Weight	Avg Items	Avg Party
Breakfast	7-10	15%	3-6	1-3
Lunch	11-14	30%	3-7	1-4
Happy Hour	15-17	10%	3-6	2-5
Dinner	17-21	35%	4-9	2-6
Late Night	21-23	10%	3-6	1-3

Daily volume: weekday 40-60, friday 70-100, saturday 80-120, sunday 50-80

Payment mix: 75% card, 25% cash. Tips: 15-25% dine-in, 0-15% takeout, 10-20% delivery.

Refunds: 5% of orders by default (configurable).

Database Schema

All tables use UUID primary keys. The gem works without a database — audit logging is optional and non-blocking.

Table	Purpose
`business_types`	9 business types with order profiles
`categories`	Menu categories per business type
`items`	Menu items with prices (cents)
`simulated_orders`	Generated order records
`simulated_payments`	Payment records per order
`api_requests`	Full API audit trail (request + response)
`daily_summaries`	Aggregated daily metrics

Services

The gem wraps 5 Square API service areas:

CatalogService — categories, items, discounts, taxes (CRUD + batch)
OrderService — create, search, calculate orders
PaymentService — card payments, cash payments, refunds
CustomerService — create/list customers (20 default)
TeamService — create/search team members (5 default)

Development

bundle install
bundle exec rspec          # 575 tests, 100% branch coverage
bundle exec rubocop        # 0 offenses

License

MIT License. See LICENSE.txt.