Shop Cash order data and third-party integrations

When a customer uses Shop Cash on an order, Shop Cash is treated as a payment method. It's not a discount, gift card, or store credit. Any remaining order balance is paid with Shop Pay or Shop Pay Installments.

For example, if a customer uses $25 USD in Shop Cash on a $100 USD order, then the order includes a Shop Cash payment for $25 USD and a Shop Pay payment for $75 USD. Your order data can include more than one payment method for the same order.

Shop Cash appears as an order transaction with the gateway value shop_cash where gateway values are available. The Shop Cash transaction follows the standard transaction lifecycle, such as authorization, capture, void, and refund. Shop Cash doesn't use a combined sale transaction kind.

If the customer also uses a Shop offer from a Shop Campaign, then the campaign-funded value is included in the same shop_cash order transaction amount. The buyer-balance and campaign-funded portions aren't represented as separate order transactions. As of January 2026, campaign costs are charged to your Shopify bill rather than deducted from your payouts, so campaign billing transactions in payout activity apply only to campaigns that ran before that date. For more information, refer to Fees, Shop Campaigns, and Shop Cash.

Third-party systems that import orders, transactions, payments, fulfillments, refunds, or returns need to recognize Shop Cash as a payment method. If a system doesn't recognize Shop Cash, then orders that include Shop Cash can fail to import, import with incomplete payment data, or require manual mapping.

Review the following requirements with your third-party system provider:

• The system can support more than one payment method on one order.
• The system can map shop_cash as a payment method.
• The system doesn't treat Shop Cash as a discount, gift card, or store credit.
• The system stores the order transaction ID for each Shop Cash authorization, capture, void, and refund.
• The system stores the full Shop Cash authorization value without truncating it, if the value is included in the data that the system imports.
• The system treats authorization values as opaque strings and doesn't parse, decode, normalize, hash, or infer meaning from them.
• The system can process refunds that return funds to both Shop Pay and Shop Cash.
• The system can reconcile Shop Cash payout transactions separately from card payment transactions.
• The system doesn't assume that transactions are returned in a specific order.

If your third-party system assumes that each order has only one payment method, then contact the provider before processing Shop Cash orders through that system.

The authorization value on a Shop Cash transaction is an opaque, variable-length string. It isn't a short card authorization code and isn't human-readable.

If your ERP, OMS, or another third-party system imports Shop Cash authorization values, store the full value exactly as provided. Use a variable-length or unbounded text field where possible.

When your system stores Shop Cash authorization values, follow these guidelines:

• Don't truncate the value to a short fixed length, such as 50 or 100 characters.
• Don't parse or infer meaning from any part of the value.
• Don't use the authorization value to identify transactions for capture, void, or refund API operations.

Truncated authorization values can cause third-party imports or downstream ERP and OMS processing to fail.

To support captures, voids, and refunds through the Admin API, store order transaction IDs and parent transaction relationships. Admin API capture and void operations identify the authorization transaction with parentTransactionId. Refund operations identify the refundable capture transaction with parentId.

When an app or integration issues a Shop Cash refund through the API, the refund must be parented to the Shop Cash capture transaction, not the Shop Cash authorization transaction. Refunds against the authorization transaction are rejected.

Refund apps and webhook handlers should identify the refundable Shop Cash capture transaction, calculate the remaining refundable amount for that capture, and create the refund against the capture transaction ID.

When you use the Admin API, order exports, payout exports, or third-party app exports, treat Shop Cash as payment data. Depending on the export or API resource that you use, Shop Cash information can be represented through payment method, gateway, order transaction, payout transaction, and refund data.

When you build or update an integration, store the following information for orders that include Shop Cash:

• Order ID and order name.
• Payment method or gateway value, such as shop_cash where available.
• Order transaction IDs for each payment transaction.
• Transaction kind and status, such as authorization, capture, refund, or void.
• Transaction amount and currency.
• Parent transaction relationships, when available.
• Payment IDs, where available.
• Full authorization values, if your system imports them.
• Payout IDs and balance transaction IDs when you're reconciling payouts.
• Refund transaction IDs when you're reconciling returns.

For details about available Admin API fields, refer to the Admin API order transaction developer documentation. Avoid relying on deprecated fields such as OrderTransaction.authorizationCode for new integrations.

The following simplified example shows a $100 USD order paid with $75 USD through Shopify Payments and $25 USD through Shop Cash. Values are illustrative only.

{
  "transactions": [
    {
      "kind": "authorization",
      "gateway": "shopify_payments",
      "status": "success",
      "amount": "75.00",
      "currency": "USD",
      "parent_id": null,
      "authorization": "ch_3OabcXYZ..."
    },
    {
      "kind": "authorization",
      "gateway": "shop_cash",
      "status": "success",
      "amount": "25.00",
      "currency": "USD",
      "parent_id": null,
      "authorization": "<long-opaque-variable-length-string>"
    },
    {
      "kind": "capture",
      "gateway": "shop_cash",
      "status": "success",
      "amount": "25.00",
      "currency": "USD",
      "parent_id": "<shop-cash-authorization-transaction-id>",
      "authorization": null
    }
  ]
}

Shop Cash can look similar to other payment or promotional values, but your systems should treat each value separately:

Before you rely on a third-party system for orders that include Shop Cash, confirm the following requirements:

• Shop Cash is mapped as a payment method.
• Orders with Shop Cash and Shop Pay are imported with both payment methods.
• Payment method logic doesn't assume one payment method per order.
• Authorization values are stored as long opaque strings and aren't truncated.
• Refund logic can refund the correct capture transaction.
• Refund logic can return funds to the correct payment methods.
• Payout reconciliation can account for Shop Cash credit, refund, and campaign transaction types.
• Fulfillment, accounting, and return workflows don't treat Shop Cash as a discount.

If you use multiple systems, then complete this review for each system that receives order, transaction, payout, fulfillment, refund, or return data.