Configure the GraphQL payout flow

The new GraphQL-based Shopify payout to NetSuite payout and deposit flow is available under Flows > Payout.

This consolidated flow combines the payout process previously handled by two separate flows. It retrieves Shopify Payments payout summaries and their underlying transactions, including sales, refunds, fees, adjustments, and other supported transaction types. It then creates the corresponding payout custom records, bank deposits, and variance transactions in NetSuite.

For stores with multiple Shopify business entities, the flow retrieves and processes payouts for each business entity, and syncs each transaction type to the NetSuite GL account configured in the settings for that entity.

The flow uses Shopify GraphQL APIs to retrieve payout and transaction data. The previous payout flows remain available during the transition period, but we recommend migrating to the new GraphQL payout flow.

Key benefits

• GraphQL-based payout retrieval: Retrieves payout summaries and detailed balance transactions through Shopify GraphQL APIs.
• Simplified payout processing: A single flow now creates payout custom records, bank deposits, and variance transactions in NetSuite.
• Business entity-based account mapping: Maps Shopify Payments transaction types for each business entity to the appropriate NetSuite GL account and subsidiary.
  • Before running the flow, manually configure account mappings for every Shopify business entity that processes payouts, including the primary business entity.
• Support for additional transaction types: The Transaction types field is a multi-select dropdown that lets you group multiple Shopify Payments transaction types to sync to the same NetSuite GL account. This means transaction types such as Shopify Cash Credit and Shopify Collective can be combined into a single mapping row. If a transaction type is not available in the dropdown, you can enter it manually using the Custom transaction types (comma-separated) field.
• Improved transaction traceability: Shopify payout transactions, including Charge, Refund, Adjustment, Variance (catch-all), and applicable tax adjustments, are synced with the details required for bank reconciliation.
• Non-blocking variance handling: Missing transactions and amount mismatches are recorded as variance transactions without preventing deposit creation.
• Safe reprocessing: Shopify payout and transaction IDs help prevent duplicate records when payout data is processed again during re-sync.

Existing payout flows

The following existing flows now display a Deprecated tag:

• [Deprecated] Shopify Payout Transactions to NetSuite Deposit 
• [Deprecated] Shopify Payout to NetSuite Payout Custom Record 

These flows remain available during the transition period. However, we recommend migrating to Shopify payout to NetSuite payout and deposit before the existing flows are retired.

Understand how the GraphQL payout flow works

The Shopify payout to NetSuite payout and deposit flow processes a Shopify payout from start to finish in a single flow.

It first retrieves Shopify payout summaries and creates corresponding payout custom records in NetSuite. For stores with multiple Shopify business entities, the flow retrieves payouts separately for each configured business entity. It then retrieves the detailed Shopify Payments transactions included in each payout, such as sales, refunds, fees, adjustments, Shopify Cash Credit, Shopify Collective, and other supported transaction types.

The flow uses the Business entity transaction type to account mapping to determine the NetSuite GL account for each transaction type and business entity. It then creates the corresponding NetSuite bank deposits.

If Shopify returns a business entity that is not configured in the payout mappings, the flow stops processing that entity and reports the missing configuration instead of skipping its payouts.

If a payout contains more than 2,000 transaction lines, the flow splits the payout across multiple NetSuite deposits.

When a related NetSuite transaction is missing, or its amount does not match the Shopify transaction, the flow creates a variance transaction without blocking deposit creation. Shopify payout and transaction IDs are used to prevent duplicate records during payout data reprocessing.

The flow completes this processing through five steps:

1. Get payouts from Shopify: Retrieves Shopify Payments payout summaries through Shopify GraphQL APIs.
2. Post payout custom records to NetSuite: Creates a corresponding payout custom record in NetSuite for each Shopify payout. Each record includes the following fields under the General section:
   • Shopify business entity ID: The unique identifier of the Shopify business entity associated with this payout.
   • Shopify business entity name: The name of the Shopify business entity associated with this payout.
     
3. Get Shopify payout transactions: Retrieves the detailed Shopify Payments transactions associated with each payout.
4. Post deposits to NetSuite: Creates the corresponding NetSuite bank deposits using the retrieved payout transactions and configured account mappings.
   If a payout contains more than 2,000 transaction lines, the flow creates multiple deposits.
5. Post payout variance transactions to NetSuite: Creates variance transactions for missing NetSuite transactions or amount mismatches without blocking deposit creation.

Configure payout account mappings

Prerequisite: Before running the flow, ensure that a business entity is pre-selected and configured for every Shopify business entity that processes payouts. All business entities must be set up to ensure payout reports sync properly.

Use Business entity transaction type to account mapping to assign NetSuite GL accounts by Shopify business entity and transaction type.

Configure mappings for every Shopify business entity that processes payouts, including the primary business entity. The mapping is initially empty and must be configured manually.

Values from the following settings are not automatically copied into this mapping:

• [Deprecated] NetSuite bank deposit account
• [Deprecated] NetSuite account to track adjustments and fees
• [Deprecated] NetSuite account to track variance
• [Deprecated] NetSuite account to track Marketplace sales tax

The GraphQL payout flow remains disabled until you enable it. Complete the required account mappings before enabling Shopify payout to NetSuite payout and deposit.

Add or edit account mappings

1. Open the Shopify–NetSuite integration app and go to Settings > Payout.
2. Locate Business entity transaction type to account mapping.
3. Click the refresh icons beside the Business entity and NetSuite GL account column headings and wait for the available options to load.
4. Add a mapping entry or edit an existing entry. From Business entity, select the entity associated with the payouts.
5. From Transaction types, select one or more transaction types to map to the same NetSuite GL account. For applicable tax transactions, select Tax Adjustment Debit or Tax Adjustment Credit.
6. If a transaction type is not available in the dropdown, enter its key in Custom transaction types (comma-separated). Separate multiple keys with commas.
7. From NetSuite GL account, select the account for the selected transaction types. This account records payout funds, fees, adjustments, or variances, depending on the mapped transaction types.
8. Add or update rows for all required transaction types and every business entity that processes payouts.
9. Click Save.

Refresh available options

Use the refresh icons at the column headings to load all available options when:

• Editing an existing entry: A dropdown may initially display only its saved selection. Refresh the list before selecting a different value.
• Adding an entry: Refresh the list to load the available business entities or NetSuite GL accounts before making a selection.

Wait for loading to finish before selecting values, then click Save after completing your mapping changes.

Map multiple transaction types

You can map multiple Shopify Payments transaction types to the same NetSuite GL account when they require the same accounting treatment.

Create separate mapping rows when:

• The same transaction type must post to different accounts for different business entities.
• Different transaction types must post to different NetSuite GL accounts.
• A transaction type is not available under Transaction types and must be entered under Custom transaction types (comma-separated).
• A business entity uses more than one payout currency and requires different accounts by currency. 

Limitation: Mapping different accounts by payout currency within the same business entity is not currently supported.

Add custom transaction types

Use Custom transaction types (comma-separated) when a Shopify Payments transaction type is not available under Transaction types.

To add custom transaction types:

1. Obtain the Shopify transaction type key.
2. Enter the key in Custom transaction types (comma-separated).
3. Separate multiple transaction type keys with commas.
4. Select the corresponding NetSuite GL account.
5. Save the mapping.

If a transaction type is not selected under Transaction types or entered under Custom transaction types (comma-separated), the flow posts the transaction using the variance account.

Migrate to the GraphQL payout flow

Before migrating, review the settings, schedules, filters, and custom mappings used by the existing payout flows.

Prerequisite: Ensure that the Shopify connection has permission to read Shopify Payments account data. The GraphQL payout flow requires access to Shopify Payments accounts. Reauthorize the Shopify connection if prompted.

To migrate:

1. Open the Shopify-NetSuite integration app.
2. Go to Flows > Payout.
3. Locate Shopify payout to NetSuite payout and deposit.
4. Review the configuration of:
   • [Deprecated] Shopify Payout Transactions to NetSuite Deposit 
   • [Deprecated] Shopify Payout to NetSuite Payout Custom Record
5. Go to Settings > Payout.
6. Under Business entity transaction type to account mapping, manually configure mappings for every business entity that processes payouts, including the primary business entity.
7. Refresh the Business entity and NetSuite GL account lists before adding or editing mapping entries.

8. For each business entity, map Charge, Refund, Adjustment, and Variance (catch-all) to the appropriate NetSuite GL accounts. Configure additional transaction types as applicable.

9. Click Save.
10. Return to Flows > Payout.
11. Enable Shopify payout to NetSuite payout and deposit.
12. Review the custom mappings copied from the existing payout flows to the GraphQL payout flow.
13. Confirm that the payout custom-record and deposit import mappings were transferred correctly. Reconfigure any unsupported lookup or mapping that was not copied.
14. Run the GraphQL payout flow with representative payout data.
15. In NetSuite, confirm that the flow creates:
    • Payout custom records
    • Bank deposits
    • Variance transactions for missing transactions, amount mismatches, or unmapped transaction types
16. Confirm that Shopify Cash Credit, Shopify Collective, and other applicable transaction types post to the expected NetSuite GL accounts.
17. Review the flow execution results and resolve any errors.
18. After successful validation, move the production schedule to the new flow, Shopify payout to NetSuite payout and deposit.
19. Disable the two flows marked [Deprecated] when you are ready to complete the migration.
20. Monitor the initial scheduled runs of the GraphQL payout flow.

Important: The existing payout flows remain available during the transition period. Disable them only after you have tested and validated the GraphQL payout flow.

Limitations

• Multiple payout currencies for one business entity: The mapping supports business entity and transaction type. It does not support assigning different NetSuite GL accounts based on payout currency within the same business entity.
• Differences between authorized and captured amounts: Shopify can report the release of an uncaptured authorization as a refund in payout data. Because the flow cannot reliably distinguish this release from an actual refund, it can create a missing-transaction variance when no corresponding refund exists in NetSuite.
• One customer refund associated with multiple customer deposits: The flow does not fully reconcile a single NetSuite customer refund against multiple customer deposits. Transactions that cannot be matched can be recorded as variances.
• Unmapped transaction types: Shop Pay, Shop Cash, and custom transaction types are not mapped automatically. If these are not configured in the Business entity transaction type to account mapping, the flow posts them to the variance account.