Skip to main content
Square is a POS-native integration. It supplies provider catalog and inventory inputs and can own certified order projection, fulfillment, in-person tender, refund, and reconciliation behavior, but it never becomes a browser payment processor. Crave’s organization-owned catalog and typed location overlays stay authoritative for storefront pricing, availability, and schedules. Stripe is the only online processor. For PAY_AT_STORE, Square is the settlement adapter and provider-recorded cash is preferred; a certified audited-cash fallback remains merchant authority, not a second adapter.

​
Activation flow

1

Connect Square via OAuth

Authorize the requested merchant, customer, catalog, order, payment, refund, card, gift-card, inventory, location, and loyalty scopes.
2

Map one Square location

Bind the Crave location to the exact Square location after currency, timezone, and capability checks.
3

Import, review, and publish the canonical catalog

Stage Square objects against stable Crave identities, resolve mapping conflicts, apply target-location price and availability overlays, and publish a fresh reviewed snapshot. Import and reconciliation never publish automatically or overwrite unrelated location overlays.
4

Activate routing, then certify provider-native readiness

Activate the reviewed POS-routed policy first; this still does not expose pay at store. Pair the exact Terminal with a Devices API pairing code, prove order visibility, native tender, refund, webhook, and reconciliation behavior, then certify the same active policy revision. Delivery additionally requires explicit Square Delivery certification and DoorDash Drive credentials.

​
Pay at store flow

  1. Crave persists one unpaid canonical order and routes its immutable fulfillment identity to Square.
  2. Staff starts collection from Crave Orders Manager on the exact certified, mapped Square Terminal. A Square POS app running only on a phone is not a substitute for a certified Terminal device.
  3. Square records the native tender. Signed webhooks and provider readback append immutable tender evidence to the existing Crave settlement.
  4. Crave marks payment PAID only after exact amount, currency, account, location, order, and tender evidence match. Fulfillment may progress while payment is still DUE.
If payment evidence is delayed, the operator sees the certified refresh, fallback-read, warning, and action-required thresholds plus Verifying payment — do not charge again. Reconciliation retains the same collection identity; it never starts another charge.

​
Authority rules

  • Online checkout always uses the order-first Stripe flow. The storefront does not load Square Web Payments, tokenize Square cards, or create Square checkout sessions.
  • Square payment and tender identifiers enter Crave only as provider-native order or webhook evidence bound to the exact tenant, connection, location, and order.
  • Square constructs its provider order from mapped catalog variations, taxes, discounts, service charges, and an optional order-linked Loyalty reward. The resulting provider total must reconcile to Crave’s accepted immutable quote; Square never rewrites the canonical catalog or customer-facing total.
  • Staff tip is recorded on the final Square Payment. DoorDash courier tip and the authoritative Drive fee plus tax are Square Order service charges.
  • Provider-native split tenders and gift-card evidence remain server-side reconciliation inputs. The storefront cannot create or fund them.
  • All refunds are admitted through the canonical Refund, RefundAllocation, and RefundDispatchOperation owner before a later provider adapter performs a write.
  • A refund of the payment that purchased a gift card triggers an idempotent Square ADJUST_DECREMENT activity with reason PURCHASE_WAS_REFUNDED, because refunding that funding payment does not reverse the loaded gift-card balance.
  • Square Loyalty replaces LIP for Square-authoritative locations. Enrollment, reward preview, issue, redemption, point accrual, and webhook projection use the Square customer and Loyalty account.
  • Provider-native loyalty evidence is reconciled independently from Stripe online payment collection; no loyalty action changes the browser processor.
  • Enrollment requires a phone that is currently verified on the active Clerk session. If the customer has no verified phone, direct them to the Clerk-managed profile or reverification flow, obtain a fresh crave-customer token, and retry enrollment. An E.164-shaped profile value or historical Crave timestamp alone is not accepted as proof. Clerk phone verification does not accept Square marketing text terms.
  • Customer loyalty history is location-scoped at GET /customer/locations/{locationId}/loyalty/ledger. A Square-authoritative location reads the current balance with RetrieveLoyaltyAccount and the reverse-chronological activity ledger with SearchLoyaltyEvents (up to 30 entries per page). It never falls back to LIP when Square is connected. The retained location binding keeps that exclusion in force if Square credentials or runtime health degrade, so Crave cannot mutate a second loyalty ledger through quote, cart, completion, cancellation, refund, or durable retry hooks. A queued LIP mutation rechecks the task location before delivery and terminates without a provider call after Square takes authority. Legacy tasks without location authority fail closed as well.
  • When an administrator approves a customer loyalty claim, Crave resolves the claim order’s location before choosing the provider. A Square-authoritative order writes the approved correction through Square AdjustLoyaltyPoints with a stable provider idempotency key and retains the returned Square event ID. Provider errors leave the claim retryable; Crave never posts that adjustment to LIP. Orders at locations without Square authority continue to use the configured LIP program.
  • Completed Square orders accrue Loyalty points with an order-scoped provider idempotency key. A failed or ambiguous accrual is retained as a durable LOYALTY_EFFECT operation; the worker re-proves the completed Square tenders, current tenant and location binding, and returned Loyalty events before it marks the cart projection complete.
  • Vendor confirmation, ready-for-pickup, and completion actions update the exact Square fulfillment before Crave commits the matching local state. Each update uses the current Square order version, fulfillment UID, and a stable idempotency key. Square-originated fulfillment webhooks apply locally without echoing the same transition back to Square.
  • Crave subscription is the launch revenue base. Pay at store does not take a transaction split from the Square tender, and prepared-but-uncollected or no-show loss remains merchant risk under configured identity and exposure limits.

​
Delivery with DoorDash Drive

Delivery is fail-closed until the location has fresh capability evidence whose source is square_live_pos_delivery_certification, a selected DOORDASH_DRIVE provider, and valid Drive credentials. Crave requests a five-minute Drive quote, fingerprints its address and cart inputs, adds fee + tax and courier tip to the Square Order, pays that exact order, then accepts the same Drive quote. Definite dispatch rejection triggers idempotent Square refund compensation. An ambiguous timeout is reconciled using the same external delivery ID and is never auto-refunded while a courier job might exist. DoorDash webhooks update Crave tracking and the Square delivery fulfillment. Active deliveries are also retrieved every 60 seconds when their last reconciliation is more than two minutes old, so a missing webhook does not strand tracking state. Order cancellation reaches a conclusive DoorDash cancel state before Square refund processing begins.

​
Webhooks

Create the Square subscription against:
Subscribe to the exact events handled by this release:
Set SQUARE_WEBHOOK_SIGNATURE_KEY only in the sandbox secret manager. Never paste it into tickets, chat, source control, or browser configuration. Crave verifies Square’s signature over the untouched body and exact notification URL, then acknowledges only after durable inbox storage. For DoorDash Drive, register:
Configure the same Basic or OAuth Authorization value in DoorDash and the DOORDASH_WEBHOOK_AUTHORIZATION sandbox secret. Crave compares the exact value in constant time, durably stores the event, serializes delivery projections, and retries failures.

​
Health and recovery

The Square integration page shows authorization and mapping status, capability readiness, last reconciliation, last webhook receipt, and pending or failed events. Use Reconcile to refresh locations, catalog, inventory, orders, payments, refunds, customers, cards, Loyalty programs, promotions, accounts, events and rewards, plus gift cards and their location activity. Gift-card account numbers are redacted before reconciliation evidence is stored. Use Retry events after repairing a dependency. A webhook HTTP success means the event was stored; projection occurs asynchronously and remains observable. The runtime also enqueues one tenant-scoped full completeness sweep for every mapped Square location in each UTC day. The durable operation pins the exact organization, connection, and binding, runs the same canonical path as the operator action, and records the successful system reconciliation in the health timeline. Provider or network failures use bounded exponential retry; an expired read-only lease is safe to replay, while changed binding evidence fails closed for operator review. Faster catalog, webhook, payment/refund, checkout-abandonment, Loyalty, and DoorDash workers continue to repair their own nonterminal domains between full sweeps.

​
Admin endpoints

Disconnecting preserves canonical catalog and historical evidence. Active or degraded commerce modules must be deactivated or rolled back first.

Slack Community

Ask questions and get help from the Crave team and community.

Email Support

Reach out to hello@craveup.com for direct support.

​
Confirm a location mapping

Use the existing location-binding POST endpoint with squareLocationId and preview: true first. Show the returned Crave location, Square location, account and blocker reasons to the merchant. After confirmation, POST the same squareLocationId with the returned confirmation object (connectionId, bindingId, revisionToken). A changed connection, mapping, policy or displayed location requires a new preview. Direct saves without confirmation are rejected. Mapping preparation does not establish menu-sync or routing activation readiness.