spree_square 0.1.0

data/app/services/spree_square/order_status_mapper.rb

@@ -0,0 +1,87 @@
+module SpreeSquare
+  # Applies a Square order/fulfillment status change to the mapped Spree
+  # order.
+  #
+  # Deliberately does NOT gate on `version` being newer than what's
+  # recorded, despite that being the pattern used elsewhere in this
+  # extension (catalog/inventory sync). Verified directly: Square emits
+  # `order.updated` and `order.fulfillment.updated` for the *same*
+  # underlying mutation carrying the *same* version number — they're two
+  # views of one change, not a sequence. Gating on version meant whichever
+  # webhook's job happened to run first "claimed" that version, and the
+  # other was dropped as "stale" even though it carried different,
+  # necessary information (e.g. the fulfillment transition itself). That
+  # bug was caught by testing a real cancellation end-to-end, not by
+  # inspecting the code.
+  #
+  # Safety against duplicate/out-of-order delivery instead comes from two
+  # places that don't have this problem: WebhookEvent's uniqueness on
+  # Square's own event_id (exact redelivery is a no-op before this class
+  # ever runs), and the state-guarded idempotent operations below (`unless
+  # canceled?`, `if ready?`) — applying the same transition twice, or an
+  # old one after a newer one already landed, does nothing either way.
+  class OrderStatusMapper
+    FULFILLMENT_SHIP_STATES = %w[COMPLETED].freeze
+    # PROPOSED/RESERVED/PREPARED: kitchen-visible progress with no Spree
+    # shipment-state equivalent ("food is cooking") — recorded as a friendly
+    # label on the mapping, not forced into shipment_state.
+    FULFILLMENT_LABEL_STATES = %w[PROPOSED RESERVED PREPARED].freeze
+
+    def self.call(...) = new.call(...)
+
+    def call(square_order_id:, version:, order_state: nil, fulfillment_state: nil)
+      mapping = SpreeSquare::OrderMapping.find_by(square_order_id: square_order_id)
+      return unless mapping
+
+      order = mapping.order
+
+      apply_fulfillment_state(order, fulfillment_state) if fulfillment_state
+      apply_order_state(order, order_state) if order_state
+
+      # Recorded for visibility/debugging (admin page, M8) — informational
+      # only, never gates whether this call's transitions above applied.
+      mapping.update!(square_version: version, last_status: fulfillment_state || order_state || mapping.last_status)
+    end
+
+    private
+
+    def apply_fulfillment_state(order, state)
+      case state
+      when *FULFILLMENT_SHIP_STATES
+        ship!(order)
+      when 'CANCELED', 'FAILED'
+        # This — not order.state — is the real-world cancel signal. Square
+        # rejects setting order.state to CANCELED once a payment has been
+        # processed against it ("Orders cannot be canceled after payments
+        # have been processed") — confirmed by hitting that error directly.
+        # A paid order that isn't happening gets its *fulfillment* canceled
+        # instead (the order itself stays COMPLETED for Square's own
+        # accounting); that's the signal to cancel on the Spree side too.
+        cancel!(order)
+      end
+      # FULFILLMENT_LABEL_STATES (PROPOSED/RESERVED/PREPARED) need no
+      # Spree-side action beyond the last_status the caller persists —
+      # surfaced later as a friendly label on the customer's order status
+      # page.
+    end
+
+    def apply_order_state(order, state)
+      case state
+      when 'CANCELED'
+        # Still handled for the (rarer) case of a Square order canceled
+        # before any payment was attached.
+        cancel!(order)
+      when 'COMPLETED'
+        ship!(order)
+      end
+    end
+
+    def cancel!(order)
+      order.cancel! unless order.canceled?
+    end
+
+    def ship!(order)
+      order.shipments.each { |shipment| shipment.ship! if shipment.ready? }
+    end
+  end
+end

data/app/services/spree_square/revalidator.rb

@@ -0,0 +1,55 @@
+require 'net/http'
+
+module SpreeSquare
+  # Tells the Next.js storefront which Cache Components tags to drop after a
+  # sync write, so a price/menu/inventory change from Square shows up
+  # immediately instead of waiting out the storefront's cacheLife("tenMinutes")
+  # window.
+  #
+  # Deliberately not routed through Spree's own outbound webhook system
+  # (Spree::WebhookEndpoint): that system's `product.updated` event is
+  # suppressed on touch-only cascades, which is exactly how a price or stock
+  # change reaches the product (variant/price/stock_item touch the product,
+  # they don't update it directly) — so it would silently miss most of what
+  # this extension syncs. This service is called directly from the sync code,
+  # which already knows the exact product with no ambiguity.
+  #
+  # Failure here is logged, never raised — a stale storefront cache for up to
+  # 10 minutes is a much smaller problem than a failed revalidation call
+  # breaking catalog or inventory sync.
+  class Revalidator
+    def self.call(...) = new.call(...)
+
+    def call(tags)
+      return if url.blank? || secret.blank? || tags.blank?
+
+      uri = URI.parse(url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == 'https'
+      http.open_timeout = 2
+      http.read_timeout = 2
+
+      request = Net::HTTP::Post.new(uri.request_uri)
+      request['Content-Type'] = 'application/json'
+      request['x-revalidate-secret'] = secret
+      request.body = { tags: Array(tags) }.to_json
+
+      response = http.request(request)
+      unless response.is_a?(Net::HTTPSuccess)
+        Rails.logger.warn("[SpreeSquare] revalidate call failed (#{response.code}): #{response.body}")
+      end
+    rescue StandardError => e
+      Rails.logger.warn("[SpreeSquare] revalidate call errored: #{e.message}")
+    end
+
+    private
+
+    def url
+      ENV['STOREFRONT_REVALIDATE_URL']
+    end
+
+    def secret
+      ENV['STOREFRONT_REVALIDATE_SECRET']
+    end
+  end
+end

data/app/services/spree_square/webhook_verifier.rb

@@ -0,0 +1,21 @@
+module SpreeSquare
+  # Verifies the `x-square-hmacsha256-signature` header Square sends on every
+  # webhook POST. Algorithm per Square's spec (mirrored from the legacy SDK's
+  # WebhooksHelper, since the current SDK doesn't ship a verifier — Square's
+  # signing scheme itself, not the SDK's shape, is what this depends on):
+  #
+  #   base64(HMAC-SHA256(signing_key, notification_url + raw_request_body))
+  #
+  # compared against the header using a constant-time comparison.
+  class WebhookVerifier
+    def self.valid?(url:, body:, signature:, signing_key:)
+      return false if body.nil? || signature.blank? || signing_key.blank?
+
+      payload = "#{url}#{body}".dup.force_encoding('UTF-8')
+      digest = OpenSSL::HMAC.digest('sha256', signing_key.dup.force_encoding('UTF-8'), payload)
+      expected = Base64.strict_encode64(digest)
+
+      ActiveSupport::SecurityUtils.secure_compare(expected, signature)
+    end
+  end
+end

data/app/subscribers/spree_square/order_completed_subscriber.rb

@@ -0,0 +1,15 @@
+module SpreeSquare
+  # Events & Subscribers is the preferred pattern for this kind of side
+  # effect (per this app's own CLAUDE.md conventions) — react to
+  # order.completed without touching Spree::Order itself.
+  class OrderCompletedSubscriber < Spree::Subscriber
+    subscribes_to 'order.completed'
+
+    def handle(event)
+      order = Spree::Order.find_by_prefix_id(event.payload['id'])
+      return unless order
+
+      SpreeSquare::OrderPushJob.perform_later(order.id)
+    end
+  end
+end

data/app/views/spree/admin/square_oauth/show.html.erb

@@ -0,0 +1,63 @@
+<% content_for :page_title do %>
+  Square Connection
+<% end %>
+
+<div class="card w-full max-w-2xl">
+  <div class="card-header flex items-center justify-between <%= 'bg-green-50' if @credential %>">
+    <span class="font-medium">Square</span>
+    <% if @credential %>
+      <span class="inline-flex items-center text-xs font-medium text-green-700">
+        <span class="w-1.5 h-1.5 rounded-full bg-green-500 mr-1"></span>
+        Connected
+      </span>
+    <% else %>
+      <span class="inline-flex items-center text-xs font-medium text-gray-500">
+        <span class="w-1.5 h-1.5 rounded-full bg-gray-400 mr-1"></span>
+        Not connected
+      </span>
+    <% end %>
+  </div>
+
+  <div class="card-body">
+    <% if @credential %>
+      <dl class="space-y-2 text-sm">
+        <div class="flex justify-between">
+          <dt class="text-gray-500">Merchant ID</dt>
+          <dd><%= @credential.square_merchant_id %></dd>
+        </div>
+        <div class="flex justify-between">
+          <dt class="text-gray-500">Environment</dt>
+          <dd><%= @credential.square_environment %></dd>
+        </div>
+        <div class="flex justify-between">
+          <dt class="text-gray-500">Token expires</dt>
+          <dd><%= @credential.expires_at&.strftime('%b %-d, %Y %H:%M') || '—' %></dd>
+        </div>
+        <div class="flex justify-between">
+          <dt class="text-gray-500">Connected since</dt>
+          <dd><%= @credential.created_at.strftime('%b %-d, %Y') %></dd>
+        </div>
+      </dl>
+      <p class="text-xs text-gray-500 mt-4">
+        Catalog, order, and inventory sync for this store run against this connection.
+        Disconnecting stops all of it immediately — orders already pushed to Square are unaffected.
+      </p>
+    <% else %>
+      <p class="text-sm text-gray-600">
+        Connect this store to Square to sync your menu, push orders, and keep fulfillment
+        status in sync — no manually-generated access token required.
+      </p>
+    <% end %>
+  </div>
+
+  <div class="card-footer">
+    <% if @credential %>
+      <%= button_to admin_disconnect_square_oauth_path, method: :delete, class: 'btn btn-sm btn-light',
+            data: { confirm: 'Disconnect this store from Square? Syncing stops immediately.' } do %>
+        Disconnect
+      <% end %>
+    <% else %>
+      <%= link_to_with_icon 'plug', 'Connect to Square', admin_connect_square_oauth_path, class: 'btn btn-primary' %>
+    <% end %>
+  </div>
+</div>

data/app/views/spree/admin/square_order_mappings/index.html.erb

@@ -0,0 +1,5 @@
+<% content_for :page_title do %>
+  Square Order Mappings
+<% end %>
+
+<%= render_table @collection, :square_order_mappings %>

data/app/views/spree/admin/square_webhook_events/index.html.erb

@@ -0,0 +1,5 @@
+<% content_for :page_title do %>
+  Square Webhook Events
+<% end %>
+
+<%= render_table @collection, :square_webhook_events %>

data/bin/importmap

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../Gemfile', __dir__)
+require 'bundler/setup' if File.exist?(ENV['BUNDLE_GEMFILE'])
+
+require 'rails'
+
+require 'importmap-rails'
+require 'importmap/commands'

data/bin/rails

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# This command will automatically be run when you run "rails" from the root of your extension
+
+ENGINE_ROOT = File.expand_path('../..', __FILE__)
+ENGINE_PATH = File.expand_path('../../lib/spree_square/engine', __FILE__)
+
+require 'rails/all'
+require 'rails/engine/commands'

data/config/importmap.rb

@@ -0,0 +1,6 @@
+pin 'application-spree-square', to: 'spree_square/application.js', preload: false
+
+pin_all_from SpreeSquare::Engine.root.join('app/javascript/spree_square/controllers'),
+             under: 'spree_square/controllers',
+             to:    'spree_square/controllers',
+             preload: 'application-spree-square'

data/config/initializers/spree.rb

@@ -0,0 +1,45 @@
+# Modifier support (M4): let `square_modifier_ids` survive the options
+# hash that Spree::Cart::AddItem filters incoming `options:` params through,
+# so it reaches Variant#square_modifier_ids_price_modifier_amount (the
+# initial price) and LineItem#square_modifier_ids (read by
+# SpreeSquare::Cart::AddItem to build the persistent snapshot rows).
+Spree::PermittedAttributes.line_item_attributes << :square_modifier_ids
+
+Spree.dependencies do |dependencies|
+  dependencies.cart_add_item_service = 'SpreeSquare::Cart::AddItem'
+  # cart_compare_line_items_service is NOT the merge gate it looks like —
+  # Spree::LineItems::FindByVariant calls it but discards the result. The
+  # finder itself is the actual hook (see find_line_item_by_variant.rb).
+  dependencies.line_item_by_variant_finder = 'SpreeSquare::FindLineItemByVariant'
+end
+
+Spree::Api::Dependencies.product_serializer = 'SpreeSquare::ProductSerializer'
+Spree::Api::Dependencies.line_item_serializer = 'SpreeSquare::LineItemSerializer'
+
+# Uncomment lines below to add your own custom business logic
+# such as promotions, shipping methods, etc.
+Rails.application.config.after_initialize do
+  # M5: push a completed order to Square (as an already-paid ticket) as soon
+  # as Spree marks it complete.
+  Spree.subscribers << SpreeSquare::OrderCompletedSubscriber
+
+  # Spree.shipping_methods << Spree::ShippingMethods::SuperExpensiveNotVeryFastShipping
+  # Spree.payment_methods << Spree::PaymentMethods::VerySafeAndReliablePaymentMethod
+
+  # Spree.calculators.tax_rates << Spree::TaxRates::FinanceTeamForcedMeToCodeThis
+
+  # Spree.stock_splitters << Spree::Stock::Splitters::SecretLogicSplitter
+
+  # Spree.adjusters << Spree::Adjustable::Adjuster::TaxTheRich
+
+  # Custom promotions
+  # Spree.calculators.promotion_actions_create_adjustments << Spree::Calculators::PromotionActions::CreateAdjustments::AddDiscountForFriends
+  # Spree.calculators.promotion_actions_create_item_adjustments << Spree::Calculators::PromotionActions::CreateItemAdjustments::FinanceTeamForcedMeToCodeThis
+  # Spree.promotions.rules << Spree::Promotions::Rules::OnlyForVIPCustomers
+  # Spree.promotions.actions << Spree::Promotions::Actions::GiftWithPurchase
+
+  # Spree.taxon_rules << Spree::TaxonRules::ProductsWithColor
+
+  # Spree.exports << Spree::Exports::Payments
+  # Spree.reports << Spree::Reports::MassivelyOvercomplexReportForCfo
+end

data/config/initializers/spree_admin_square_navigation.rb

@@ -0,0 +1,25 @@
+Rails.application.config.after_initialize do
+  Spree.admin.navigation.sidebar.add :square_order_mappings,
+    label: 'Square Orders',
+    url: :admin_square_order_mappings_path,
+    icon: 'receipt',
+    position: 65,
+    active: -> { controller_name == 'square_order_mappings' },
+    if: -> { can?(:manage, SpreeSquare::OrderMapping) }
+
+  Spree.admin.navigation.sidebar.add :square_webhook_events,
+    label: 'Square Webhooks',
+    url: :admin_square_webhook_events_path,
+    icon: 'webhook',
+    position: 66,
+    active: -> { controller_name == 'square_webhook_events' },
+    if: -> { can?(:manage, SpreeSquare::WebhookEvent) }
+
+  Spree.admin.navigation.sidebar.add :square_oauth,
+    label: 'Square Connection',
+    url: :admin_square_oauth_path,
+    icon: 'plug',
+    position: 67,
+    active: -> { controller_name == 'square_oauth' },
+    if: -> { can?(:manage, SpreeSquare::Credential) }
+end

data/config/initializers/spree_admin_square_tables.rb

@@ -0,0 +1,86 @@
+Rails.application.config.after_initialize do
+  Spree.admin.tables.register(:square_order_mappings, model_class: SpreeSquare::OrderMapping, search_param: :square_order_id_cont)
+
+  Spree.admin.tables.square_order_mappings.add :order_number,
+    label: :order,
+    type: :string,
+    sortable: false,
+    filterable: false,
+    default: true,
+    position: 10,
+    method: ->(mapping) { mapping.order&.number }
+
+  Spree.admin.tables.square_order_mappings.add :square_order_id,
+    label: :square_order_id,
+    type: :string,
+    sortable: true,
+    filterable: true,
+    default: true,
+    position: 20
+
+  Spree.admin.tables.square_order_mappings.add :last_status,
+    label: :status,
+    type: :string,
+    sortable: true,
+    filterable: true,
+    default: true,
+    position: 30
+
+  Spree.admin.tables.square_order_mappings.add :push_error,
+    label: :push_error,
+    type: :string,
+    sortable: false,
+    filterable: false,
+    default: true,
+    position: 40
+
+  Spree.admin.tables.square_order_mappings.add :created_at,
+    label: :created_at,
+    type: :datetime,
+    sortable: true,
+    filterable: false,
+    default: true,
+    position: 50
+
+  Spree.admin.tables.register(:square_webhook_events, model_class: SpreeSquare::WebhookEvent, search_param: :event_type_cont)
+
+  Spree.admin.tables.square_webhook_events.add :event_type,
+    label: :event_type,
+    type: :string,
+    sortable: true,
+    filterable: true,
+    default: true,
+    position: 10
+
+  Spree.admin.tables.square_webhook_events.add :status,
+    label: :status,
+    type: :string,
+    sortable: true,
+    filterable: true,
+    default: true,
+    position: 20
+
+  Spree.admin.tables.square_webhook_events.add :processed_at,
+    label: :processed_at,
+    type: :datetime,
+    sortable: true,
+    filterable: false,
+    default: true,
+    position: 30
+
+  Spree.admin.tables.square_webhook_events.add :error_message,
+    label: :error_message,
+    type: :string,
+    sortable: false,
+    filterable: false,
+    default: true,
+    position: 40
+
+  Spree.admin.tables.square_webhook_events.add :created_at,
+    label: :received_at,
+    type: :datetime,
+    sortable: true,
+    filterable: false,
+    default: true,
+    position: 50
+end

data/config/locales/en.yml

@@ -0,0 +1,5 @@
+---
+en:
+  spree:
+    square:
+      hello: Hello SpreeSquare

data/config/routes.rb

@@ -0,0 +1,25 @@
+Spree::Core::Engine.add_routes do
+  # `isolate_namespace Spree` in the engine means a normal `namespace
+  # :spree_square do ... end` block would resolve controllers as
+  # `Spree::SpreeSquare::...` (the isolated module gets prepended). The
+  # leading `/` on the controller path makes it absolute, resolving to the
+  # actual `SpreeSquare::WebhooksController` while keeping the URL prefix.
+  post 'spree_square/webhooks/square', to: '/spree_square/webhooks#create'
+
+  # M8: admin support/diagnostic pages — read-only, hence :index only.
+  # Plain `namespace :admin` here (unlike the webhook route above) resolves
+  # correctly with no path override needed: Spree::Admin::* is the isolated
+  # namespace's own convention, not a mismatch like spree_square/ was.
+  namespace :admin do
+    resources :square_order_mappings, only: [:index]
+    resources :square_webhook_events, only: [:index]
+
+    # Self-service OAuth connection (see Spree::Admin::SquareOauthController).
+    # Explicit named routes rather than `resource :square_oauth` — the
+    # callback is a third, non-CRUD GET action Square itself redirects to.
+    get 'square_oauth' => 'square_oauth#show', as: :square_oauth
+    get 'square_oauth/connect' => 'square_oauth#connect', as: :connect_square_oauth
+    get 'square_oauth/callback' => 'square_oauth#callback', as: :callback_square_oauth
+    delete 'square_oauth' => 'square_oauth#destroy', as: :disconnect_square_oauth
+  end
+end

data/db/migrate/20260809120001_create_spree_square_location_mappings.rb

@@ -0,0 +1,12 @@
+class CreateSpreeSquareLocationMappings < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_square_location_mappings do |t|
+      t.string :square_location_id, null: false
+      t.references :spree_stock_location, null: false, foreign_key: { to_table: :spree_stock_locations }
+
+      t.timestamps
+    end
+
+    add_index :spree_square_location_mappings, :square_location_id, unique: true
+  end
+end

data/db/migrate/20260809120002_create_spree_square_taxon_mappings.rb

@@ -0,0 +1,16 @@
+class CreateSpreeSquareTaxonMappings < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_square_taxon_mappings do |t|
+      t.string :square_category_id, null: false
+      # References spree_taxons — Spree::Category is an STI subclass sharing
+      # that table (see Spree::Category's own comment: it becomes the base
+      # class in 6.0, when spree_taxons is renamed to spree_categories).
+      t.references :spree_taxon, null: false, foreign_key: { to_table: :spree_taxons }
+      t.bigint :square_version
+
+      t.timestamps
+    end
+
+    add_index :spree_square_taxon_mappings, :square_category_id, unique: true
+  end
+end

data/db/migrate/20260809120003_create_spree_square_catalog_mappings.rb

@@ -0,0 +1,20 @@
+class CreateSpreeSquareCatalogMappings < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_square_catalog_mappings do |t|
+      t.string :square_catalog_object_id, null: false
+      # "item" or "item_variation" — which Square object this row mirrors.
+      t.string :square_object_type, null: false
+      t.references :spree_product, null: true, foreign_key: { to_table: :spree_products }
+      t.references :spree_variant, null: true, foreign_key: { to_table: :spree_variants }
+      # Square's optimistic-concurrency token. Compared before writing so a
+      # webhook that arrives out of order (or a duplicate) can't clobber a
+      # newer state with older data.
+      t.bigint :square_version
+      t.datetime :last_synced_at
+
+      t.timestamps
+    end
+
+    add_index :spree_square_catalog_mappings, :square_catalog_object_id, unique: true
+  end
+end

data/db/migrate/20260809140001_create_spree_square_webhook_events.rb

@@ -0,0 +1,26 @@
+class CreateSpreeSquareWebhookEvents < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_square_webhook_events do |t|
+      # Square's notification envelope carries its own event_id — the
+      # idempotency key. Square retries on a slow/failed ack, so the same
+      # event can arrive more than once; the unique index is what makes a
+      # duplicate delivery a no-op instead of double-processing.
+      t.string :square_event_id, null: false
+      t.string :event_type, null: false
+      # `json`, not `jsonb`: SQLite (used by the extension's own dummy app
+      # for fast specs) has no jsonb type, and nothing here does SQL-level
+      # JSON querying — application code only ever reads/writes it as a
+      # plain Ruby hash, so the Postgres jsonb-vs-json performance distinction
+      # doesn't apply.
+      t.json :payload, null: false, default: {}
+      t.datetime :processed_at
+      t.string :status, null: false, default: 'pending' # pending, processed, failed
+      t.text :error_message
+
+      t.timestamps
+    end
+
+    add_index :spree_square_webhook_events, :square_event_id, unique: true
+    add_index :spree_square_webhook_events, :event_type
+  end
+end

data/db/migrate/20260809160001_create_spree_square_modifier_lists.rb

@@ -0,0 +1,16 @@
+class CreateSpreeSquareModifierLists < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_square_modifier_lists do |t|
+      t.string :square_modifier_list_id, null: false
+      t.string :name, null: false
+      t.string :selection_type, null: false, default: 'SINGLE' # SINGLE or MULTIPLE
+      t.integer :min_selected_modifiers
+      t.integer :max_selected_modifiers
+      t.bigint :square_version
+
+      t.timestamps
+    end
+
+    add_index :spree_square_modifier_lists, :square_modifier_list_id, unique: true
+  end
+end

data/db/migrate/20260809160002_create_spree_square_modifiers.rb

@@ -0,0 +1,15 @@
+class CreateSpreeSquareModifiers < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_square_modifiers do |t|
+      t.references :modifier_list, null: false, foreign_key: { to_table: :spree_square_modifier_lists }
+      t.string :square_modifier_id, null: false
+      t.string :name, null: false
+      t.integer :price_cents, null: false, default: 0
+      t.bigint :square_version
+
+      t.timestamps
+    end
+
+    add_index :spree_square_modifiers, :square_modifier_id, unique: true
+  end
+end

data/db/migrate/20260809160003_create_spree_square_product_modifier_lists.rb

@@ -0,0 +1,13 @@
+class CreateSpreeSquareProductModifierLists < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_square_product_modifier_lists do |t|
+      t.references :product, null: false, foreign_key: { to_table: :spree_products }
+      t.references :modifier_list, null: false, foreign_key: { to_table: :spree_square_modifier_lists }
+
+      t.timestamps
+    end
+
+    add_index :spree_square_product_modifier_lists, %i[product_id modifier_list_id],
+              unique: true, name: 'index_square_product_modifier_lists_uniq'
+  end
+end

data/db/migrate/20260809160004_create_spree_square_line_item_modifiers.rb

@@ -0,0 +1,16 @@
+class CreateSpreeSquareLineItemModifiers < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_square_line_item_modifiers do |t|
+      t.references :line_item, null: false, foreign_key: { to_table: :spree_line_items }
+      # Nullable + snapshot columns: if the Modifier record is later deleted
+      # (menu edit in Square), a past order must still show and total exactly
+      # what the customer paid for, unaffected by any later catalog change.
+      t.references :modifier, null: true, foreign_key: { to_table: :spree_square_modifiers }
+      t.string :square_modifier_id
+      t.string :name_snapshot, null: false
+      t.integer :price_cents_snapshot, null: false, default: 0
+
+      t.timestamps
+    end
+  end
+end

data/db/migrate/20260809170001_create_spree_square_order_mappings.rb

@@ -0,0 +1,17 @@
+class CreateSpreeSquareOrderMappings < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_square_order_mappings do |t|
+      t.references :spree_order, null: false, foreign_key: { to_table: :spree_orders }, index: { unique: true }
+      t.string :square_order_id
+      t.string :square_payment_id
+      t.string :square_location_id
+      t.bigint :square_version
+      t.string :last_status
+      t.text :push_error
+
+      t.timestamps
+    end
+
+    add_index :spree_square_order_mappings, :square_order_id, unique: true
+  end
+end