Prepare your systems for Shop Cash

Before you launch Shop Cash workflows with third-party systems, confirm the following requirements:

• Your ERP, OMS, fulfillment, accounting, and return systems can accept more than one payment method on one order.
• shop_cash is mapped as a payment method where gateway values are available.
• Shop Cash isn't treated as a discount, gift card, or store credit.
• The authorization value is stored as an opaque variable-length string of at least 1024 characters. If possible, use an unbounded text field.
• Captures, voids, and refunds are identified by transaction ID rather than by the authorization value. Admin API capture and void operations use parentTransactionId, and refund operations use parentId.
• Your systems don't parse, decode, normalize, hash, or truncate Shop Cash authorization values.
• Your systems can handle grouped payouts, where one shop_cash_credit row can represent multiple orders.
• Your reconciliation workflow doesn't assume that one order equals one payout row.
• Your reconciliation workflow can handle the Shop Cash portion and card or Shop Pay Installments portion settling on different payouts.
• Your refund workflow can process partial refunds across card or Shop Pay Installments and Shop Cash.
• Refund apps can refund the Shop Cash capture transaction, not the authorization transaction.
• If you ran Shop Campaigns before January 2026, your finance workflow handles the historical shop_cash_campaign_billing_debit and related campaign billing rows separately from order revenue. Campaign costs from January 2026 onward are charged to your Shopify bill instead.

Shop Cash testing has limitations because Shop Cash depends on Shop buyer accounts, Shop Cash balances, Shopify Payments, and Shop Cash settlement infrastructure.

The most reliable way to validate an enterprise integration end to end is to place a low-value production order through Shop, and then refund it. This creates production-like order transactions, capture data, payout activity, refund transactions, and refund debit activity that flow through Shopify admin, Admin API data, payout exports, and payout API data.

Development stores can help validate some API field shapes and mapping logic, but they don't reliably exercise the full Shop-originated checkout, buyer balance, and settlement flow. Test mode and the Bogus gateway don't create production-like Shop Cash payout rows because they don't use a live Shopify Payments settlement flow.

You can usually test the following workflows with a low-value production order initiated from Shop:

• Order ingestion for a multi-payment-method order that includes Shop Cash and Shop Pay or Shop Pay Installments.
• ERP or OMS mapping for shop_cash.
• Storage of the full Shop Cash authorization value.
• Full and partial refunds against the order.
• Ingestion of shop_cash_refund_debit payout activity.
• Payout reconciliation for Shop Cash credits.
• Pre-order or capture-at-fulfillment behavior, if your store uses delayed capture.
• Return app handling for orders with more than one payment method.

When you test in production, use a low-value order and follow your store's internal test order and refund procedures.

Contact Shopify Support if you need help with any of the following scenarios:

• Reviewing Shop Cash availability for a market that's in rollout.
• Investigating a failed Shop Cash capture or refund.
• Investigating a missing Shop Cash payout transaction after your normal payout cadence plus one additional payout cycle.
• Reviewing whether a voided or expired Shop Cash authorization can be re-authorized.
• Planning a launch for a complex ERP, OMS, pre-order, or fulfillment workflow.

Before you scale Shop Cash order volume, complete the following checks:

• ERP and OMS payment-method mapping is deployed and verified for shop_cash.
• A sample Shop Cash order is ingested end to end, including authorization and capture transactions.
• A sample Shop Cash payout credit is reconciled to the source order or orders.
• A sample Shop Cash refund is processed and reconciled to the refund debit.
• Grouped Shop Cash payout rows are supported or have a manual reconciliation process.
• Partial refund allocation is understood by your support and finance teams.
• Pre-order, manual capture, and capture-at-fulfillment behavior is validated, if applicable.
• Return apps can identify and refund the correct Shop Cash capture transaction.
• Support and finance teams know the difference between customer Shop Cash balance, Shop offers, and Shop Campaign billing activity.

For API and order data requirements, refer to Shop Cash order data and third-party integrations. For payout requirements, refer to Reconciling Shop Cash payouts.