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.