From 67da1aeabbea1d7622edb54c59b82587e7ada550 Mon Sep 17 00:00:00 2001 From: Devin Michael Date: Tue, 20 Oct 2026 12:57:26 +0700 Subject: [PATCH 1/8] Shop Pay guide: capture and refund behavior, Campaigns API, merchant setup link --- .../guides/payment-methods/shop-pay.mdx | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/content/docs/admin-api/guides/payment-methods/shop-pay.mdx b/content/docs/admin-api/guides/payment-methods/shop-pay.mdx index e9a8909..66e8091 100644 --- a/content/docs/admin-api/guides/payment-methods/shop-pay.mdx +++ b/content/docs/admin-api/guides/payment-methods/shop-pay.mdx @@ -13,7 +13,7 @@ import { Callout } from 'fumadocs-ui/components/callout'; For custom Shop Pay checkouts, there are two checkout flows available, the standard method where a user enters their shipping address, chooses products, and then checks out via Shop Pay; and the "One-Click" method, where the user is not required to enter shipping information before being redirected to Shop Pay checkout. -Your store must have an active Shop Pay account to use the Shop Pay payment method. +Your store must have an active Shop Pay account to use the Shop Pay payment method. Merchants connect one under **Settings > Payments > Shop Pay**; see [Shop Pay](https://docs.nextcommerce.com/docs/features/payments/shop-pay) in the merchant docs for setup. ## API Payment Redirect Flow @@ -63,3 +63,17 @@ Shop Pay does not support one-click upsells through the [ordersAddLineItemsCreat ## Recurring Shop Pay does not support recurring transactions and cannot be used as a payment method for an order with subscription items. + +## Capture and Refunds + +Shop Pay orders are always authorized at checkout and captured later. Shopify holds the authorization for 7 days; capture before then or the funds are released to the customer. + +- **Capture** is full amount only. Partial captures aren't supported. +- **Refunds** can be full or partial once the payment is captured. Refunds can return as pending until Shopify confirms them. +- **Refunding an uncaptured order** voids the whole authorization, whatever amount you request. +- **Disputes** are handled in the merchant's Shop Pay store in Shopify admin, not in NEXT. + +## Campaigns API + +Campaigns built on the [Campaigns API](/docs/campaigns/api) accept `shop_pay` as a payment method and follow the same redirect flow. Shop Pay must be enabled as a payment method on each campaign. + From d480c4f3f45d2993f5799f4130a9313a4b1fb3a9 Mon Sep 17 00:00:00 2001 From: Devin Michael Date: Wed, 21 Oct 2026 16:56:39 +0700 Subject: [PATCH 2/8] Shop Pay guide: capture follows the Shop Pay store's capture setting --- content/docs/admin-api/guides/payment-methods/shop-pay.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/admin-api/guides/payment-methods/shop-pay.mdx b/content/docs/admin-api/guides/payment-methods/shop-pay.mdx index 66e8091..13ba89d 100644 --- a/content/docs/admin-api/guides/payment-methods/shop-pay.mdx +++ b/content/docs/admin-api/guides/payment-methods/shop-pay.mdx @@ -66,7 +66,7 @@ Shop Pay does not support recurring transactions and cannot be used as a payment ## Capture and Refunds -Shop Pay orders are always authorized at checkout and captured later. Shopify holds the authorization for 7 days; capture before then or the funds are released to the customer. +Capture timing follows the **Payment capture method** set in the merchant's Shop Pay store in Shopify. With **Automatically at checkout**, which is the recommended setting, payments are captured when the customer pays. With **Manually**, payments are only authorized: Shopify holds them for 7 days, and NEXT's auto-capture (on fulfillment or after a delay) doesn't apply to `shop_pay` yet, so capture them through the [capture API](/docs/admin-api/reference/orders/ordersCaptureCreate) or the dashboard. - **Capture** is full amount only. Partial captures aren't supported. - **Refunds** can be full or partial once the payment is captured. Refunds can return as pending until Shopify confirms them. From 1b1511d8862ac0bdcee337e4f30c7cebbd912890 Mon Sep 17 00:00:00 2001 From: Devin Michael Date: Wed, 28 Oct 2026 14:31:03 +0700 Subject: [PATCH 3/8] Shop Pay guide: payments are captured at order creation --- .../docs/admin-api/guides/payment-methods/shop-pay.mdx | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/content/docs/admin-api/guides/payment-methods/shop-pay.mdx b/content/docs/admin-api/guides/payment-methods/shop-pay.mdx index 13ba89d..a3b08bd 100644 --- a/content/docs/admin-api/guides/payment-methods/shop-pay.mdx +++ b/content/docs/admin-api/guides/payment-methods/shop-pay.mdx @@ -17,7 +17,6 @@ Your store must have an active Shop Pay account to use the Shop Pay payment meth ## API Payment Redirect Flow - import RedirectPaymentFlow from '../../../../_snippets/_redirect-payment-flow.mdx'; @@ -51,7 +50,6 @@ The response when creating the order will provide a `payment_complete_url`. Your ## Receiving Order Data - import RedirectPaymentStep3 from '../../../../_snippets/_redirect-payment-flows-step-3.mdx'; @@ -66,11 +64,9 @@ Shop Pay does not support recurring transactions and cannot be used as a payment ## Capture and Refunds -Capture timing follows the **Payment capture method** set in the merchant's Shop Pay store in Shopify. With **Automatically at checkout**, which is the recommended setting, payments are captured when the customer pays. With **Manually**, payments are only authorized: Shopify holds them for 7 days, and NEXT's auto-capture (on fulfillment or after a delay) doesn't apply to `shop_pay` yet, so capture them through the [capture API](/docs/admin-api/reference/orders/ordersCaptureCreate) or the dashboard. +Shop Pay payments are captured as soon as NEXT creates the order, whatever capture method is set in the merchant's Shop Pay store in Shopify. -- **Capture** is full amount only. Partial captures aren't supported. -- **Refunds** can be full or partial once the payment is captured. Refunds can return as pending until Shopify confirms them. -- **Refunding an uncaptured order** voids the whole authorization, whatever amount you request. +- **Refunds** can be full or partial. Refunds can return as pending until Shopify confirms them. - **Disputes** are handled in the merchant's Shop Pay store in Shopify admin, not in NEXT. ## Campaigns API From 48de98c214b6a04d9b96fe3cb2143ca9fd88d4b6 Mon Sep 17 00:00:00 2001 From: Devin Michael Date: Wed, 28 Oct 2026 15:56:34 +0700 Subject: [PATCH 4/8] Shop Pay guide: capture timing, refund endpoints, disputes, Campaigns API request --- .../docs/admin-api/guides/payment-methods/shop-pay.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/content/docs/admin-api/guides/payment-methods/shop-pay.mdx b/content/docs/admin-api/guides/payment-methods/shop-pay.mdx index a3b08bd..eb0d3dd 100644 --- a/content/docs/admin-api/guides/payment-methods/shop-pay.mdx +++ b/content/docs/admin-api/guides/payment-methods/shop-pay.mdx @@ -13,7 +13,7 @@ import { Callout } from 'fumadocs-ui/components/callout'; For custom Shop Pay checkouts, there are two checkout flows available, the standard method where a user enters their shipping address, chooses products, and then checks out via Shop Pay; and the "One-Click" method, where the user is not required to enter shipping information before being redirected to Shop Pay checkout. -Your store must have an active Shop Pay account to use the Shop Pay payment method. Merchants connect one under **Settings > Payments > Shop Pay**; see [Shop Pay](https://docs.nextcommerce.com/docs/features/payments/shop-pay) in the merchant docs for setup. +Your store must have an active Shop Pay account to use the Shop Pay payment method. Merchants connect one in the NEXT dashboard under **Settings > Payments > Shop Pay**; see [Shop Pay](https://docs.nextcommerce.com/docs/features/payments/shop-pay) in the merchant docs for setup. ## API Payment Redirect Flow @@ -64,12 +64,12 @@ Shop Pay does not support recurring transactions and cannot be used as a payment ## Capture and Refunds -Shop Pay payments are captured as soon as NEXT creates the order, whatever capture method is set in the merchant's Shop Pay store in Shopify. +Shop Pay payments are captured automatically once the customer completes payment on the Shop Pay checkout page, whatever capture method is set in the merchant's Shop Pay store in Shopify. You don't need to call the capture endpoint for Shop Pay orders. -- **Refunds** can be full or partial. Refunds can return as pending until Shopify confirms them. -- **Disputes** are handled in the merchant's Shop Pay store in Shopify admin, not in NEXT. +- **Refunds** can be full or partial, using [ordersRefundCalculateCreate](/docs/admin-api/reference/orders/ordersRefundCalculateCreate) and [ordersRefundCreate](/docs/admin-api/reference/orders/ordersRefundCreate) as for other payment methods. A refund can stay pending until Shopify confirms it. +- **Disputes** are handled in the merchant's Shop Pay store in Shopify admin. They aren't created as NEXT disputes, so `dispute.created` and `dispute.updated` webhooks don't fire for `shop_pay` transactions. ## Campaigns API -Campaigns built on the [Campaigns API](/docs/campaigns/api) accept `shop_pay` as a payment method and follow the same redirect flow. Shop Pay must be enabled as a payment method on each campaign. +The [Campaigns API](/docs/campaigns/api) accepts `shop_pay` as `payment_detail.payment_method`. Its request differs from the Admin API one above: the customer returns to your `success_url`, or to `payment_failed_url` if payment fails, and there's no `payment_return_url` or `shop_pay_account` field. Shop Pay must also be enabled on each campaign, in its payment methods or express payment methods. From bc8f81f567e13582ad91691c10d1f21415859980 Mon Sep 17 00:00:00 2001 From: Devin Michael Date: Wed, 28 Oct 2026 16:58:31 +0700 Subject: [PATCH 5/8] Shop Pay guide: Campaigns redirect step, campaign fields, dispute links --- .../admin-api/guides/payment-methods/shop-pay.mdx | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/content/docs/admin-api/guides/payment-methods/shop-pay.mdx b/content/docs/admin-api/guides/payment-methods/shop-pay.mdx index eb0d3dd..045df64 100644 --- a/content/docs/admin-api/guides/payment-methods/shop-pay.mdx +++ b/content/docs/admin-api/guides/payment-methods/shop-pay.mdx @@ -64,12 +64,18 @@ Shop Pay does not support recurring transactions and cannot be used as a payment ## Capture and Refunds -Shop Pay payments are captured automatically once the customer completes payment on the Shop Pay checkout page, whatever capture method is set in the merchant's Shop Pay store in Shopify. You don't need to call the capture endpoint for Shop Pay orders. +Shop Pay payments are captured automatically once the customer completes payment on the Shop Pay checkout page, whatever capture method is set in the merchant's Shop Pay store in Shopify. NEXT captures the payment itself, so you don't need to call the capture endpoint for Shop Pay orders. - **Refunds** can be full or partial, using [ordersRefundCalculateCreate](/docs/admin-api/reference/orders/ordersRefundCalculateCreate) and [ordersRefundCreate](/docs/admin-api/reference/orders/ordersRefundCreate) as for other payment methods. A refund can stay pending until Shopify confirms it. -- **Disputes** are handled in the merchant's Shop Pay store in Shopify admin. They aren't created as NEXT disputes, so `dispute.created` and `dispute.updated` webhooks don't fire for `shop_pay` transactions. +- **Disputes** are handled in the merchant's Shop Pay store in Shopify admin. They aren't created as NEXT disputes, so they don't appear in `disputesList`, and the [dispute.created](/docs/webhooks/reference/payments/dispute.created) and [dispute.updated](/docs/webhooks/reference/payments/dispute.updated) webhooks don't fire for `shop_pay` transactions. ## Campaigns API -The [Campaigns API](/docs/campaigns/api) accepts `shop_pay` as `payment_detail.payment_method`. Its request differs from the Admin API one above: the customer returns to your `success_url`, or to `payment_failed_url` if payment fails, and there's no `payment_return_url` or `shop_pay_account` field. Shop Pay must also be enabled on each campaign, in its payment methods or express payment methods. +The [Campaigns API](/docs/campaigns/api) accepts `shop_pay` as `payment_detail.payment_method`. Its request differs from the Admin API one above, and there's no `payment_return_url` or `shop_pay_account` field: + +1. Create the order with `payment_detail.payment_method` set to `shop_pay`, and set both `success_url` and `payment_failed_url`. +2. Redirect the customer to the `payment_complete_url` in the response, where they pay with Shop Pay. +3. The customer returns to your `success_url`, or to `payment_failed_url` if payment fails. + +Shop Pay must also be enabled on each campaign, in `available_payment_methods` or `available_express_payment_methods` on [campaignsCreate](/docs/admin-api/reference/campaigns/campaignsCreate). It has to be a method the campaign's gateway group supports. From 4530e9ffb4a3757dd6e876c2de37d0e94e23550d Mon Sep 17 00:00:00 2001 From: Devin Michael Date: Wed, 28 Oct 2026 16:59:06 +0700 Subject: [PATCH 6/8] Shop Pay guide: link Order Refunds --- content/docs/admin-api/guides/payment-methods/shop-pay.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/admin-api/guides/payment-methods/shop-pay.mdx b/content/docs/admin-api/guides/payment-methods/shop-pay.mdx index 045df64..1a24c04 100644 --- a/content/docs/admin-api/guides/payment-methods/shop-pay.mdx +++ b/content/docs/admin-api/guides/payment-methods/shop-pay.mdx @@ -66,7 +66,7 @@ Shop Pay does not support recurring transactions and cannot be used as a payment Shop Pay payments are captured automatically once the customer completes payment on the Shop Pay checkout page, whatever capture method is set in the merchant's Shop Pay store in Shopify. NEXT captures the payment itself, so you don't need to call the capture endpoint for Shop Pay orders. -- **Refunds** can be full or partial, using [ordersRefundCalculateCreate](/docs/admin-api/reference/orders/ordersRefundCalculateCreate) and [ordersRefundCreate](/docs/admin-api/reference/orders/ordersRefundCreate) as for other payment methods. A refund can stay pending until Shopify confirms it. +- **Refunds** can be full or partial, using [ordersRefundCalculateCreate](/docs/admin-api/reference/orders/ordersRefundCalculateCreate) and [ordersRefundCreate](/docs/admin-api/reference/orders/ordersRefundCreate) as for other payment methods (see [Order Refunds](/docs/admin-api/guides/order-management#order-refunds)). A refund can stay pending until Shopify confirms it. - **Disputes** are handled in the merchant's Shop Pay store in Shopify admin. They aren't created as NEXT disputes, so they don't appear in `disputesList`, and the [dispute.created](/docs/webhooks/reference/payments/dispute.created) and [dispute.updated](/docs/webhooks/reference/payments/dispute.updated) webhooks don't fire for `shop_pay` transactions. ## Campaigns API From 8ee694e105a0ce171416c54c6259610a25f29fd8 Mon Sep 17 00:00:00 2001 From: Devin Michael Date: Wed, 28 Oct 2026 17:31:16 +0700 Subject: [PATCH 7/8] Shop Pay guide: link capture, disputes and gateway-group references --- content/docs/admin-api/guides/payment-methods/shop-pay.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/docs/admin-api/guides/payment-methods/shop-pay.mdx b/content/docs/admin-api/guides/payment-methods/shop-pay.mdx index 1a24c04..8946bd4 100644 --- a/content/docs/admin-api/guides/payment-methods/shop-pay.mdx +++ b/content/docs/admin-api/guides/payment-methods/shop-pay.mdx @@ -64,10 +64,10 @@ Shop Pay does not support recurring transactions and cannot be used as a payment ## Capture and Refunds -Shop Pay payments are captured automatically once the customer completes payment on the Shop Pay checkout page, whatever capture method is set in the merchant's Shop Pay store in Shopify. NEXT captures the payment itself, so you don't need to call the capture endpoint for Shop Pay orders. +Shop Pay payments are captured automatically once the customer completes payment on the Shop Pay checkout page, whatever capture method is set in the merchant's Shop Pay store in Shopify; that setting has no effect on NEXT orders. NEXT captures the payment itself, so you don't need to call [ordersCaptureCreate](/docs/admin-api/reference/orders/ordersCaptureCreate) for Shop Pay orders. - **Refunds** can be full or partial, using [ordersRefundCalculateCreate](/docs/admin-api/reference/orders/ordersRefundCalculateCreate) and [ordersRefundCreate](/docs/admin-api/reference/orders/ordersRefundCreate) as for other payment methods (see [Order Refunds](/docs/admin-api/guides/order-management#order-refunds)). A refund can stay pending until Shopify confirms it. -- **Disputes** are handled in the merchant's Shop Pay store in Shopify admin. They aren't created as NEXT disputes, so they don't appear in `disputesList`, and the [dispute.created](/docs/webhooks/reference/payments/dispute.created) and [dispute.updated](/docs/webhooks/reference/payments/dispute.updated) webhooks don't fire for `shop_pay` transactions. +- **Disputes** are handled in the merchant's Shop Pay store in Shopify admin. They aren't created as NEXT disputes, so they don't appear in [disputesList](/docs/admin-api/reference/payments/disputesList), and the [dispute.created](/docs/webhooks/reference/payments/dispute.created) and [dispute.updated](/docs/webhooks/reference/payments/dispute.updated) webhooks don't fire for `shop_pay` transactions. ## Campaigns API @@ -77,5 +77,5 @@ The [Campaigns API](/docs/campaigns/api) accepts `shop_pay` as `payment_detail.p 2. Redirect the customer to the `payment_complete_url` in the response, where they pay with Shop Pay. 3. The customer returns to your `success_url`, or to `payment_failed_url` if payment fails. -Shop Pay must also be enabled on each campaign, in `available_payment_methods` or `available_express_payment_methods` on [campaignsCreate](/docs/admin-api/reference/campaigns/campaignsCreate). It has to be a method the campaign's gateway group supports. +Shop Pay must also be enabled on each campaign, in `available_payment_methods` or `available_express_payment_methods` on [campaignsCreate](/docs/admin-api/reference/campaigns/campaignsCreate). Use the list that contains `shop_pay` for the campaign's gateway group in [gatewayGroupsList](/docs/admin-api/reference/payments/gatewayGroupsList). From 0270411f940fd2a41e2f96035baed427b98689e1 Mon Sep 17 00:00:00 2001 From: Devin Michael Date: Wed, 28 Oct 2026 18:03:16 +0700 Subject: [PATCH 8/8] Shop Pay guide: drop the Shopify setting reference; name payment_gateway_group_id --- content/docs/admin-api/guides/payment-methods/shop-pay.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/docs/admin-api/guides/payment-methods/shop-pay.mdx b/content/docs/admin-api/guides/payment-methods/shop-pay.mdx index 8946bd4..b354780 100644 --- a/content/docs/admin-api/guides/payment-methods/shop-pay.mdx +++ b/content/docs/admin-api/guides/payment-methods/shop-pay.mdx @@ -64,7 +64,7 @@ Shop Pay does not support recurring transactions and cannot be used as a payment ## Capture and Refunds -Shop Pay payments are captured automatically once the customer completes payment on the Shop Pay checkout page, whatever capture method is set in the merchant's Shop Pay store in Shopify; that setting has no effect on NEXT orders. NEXT captures the payment itself, so you don't need to call [ordersCaptureCreate](/docs/admin-api/reference/orders/ordersCaptureCreate) for Shop Pay orders. +Shop Pay payments are captured automatically once the customer completes payment on the Shop Pay checkout page. NEXT captures the payment itself, so you don't need to call [ordersCaptureCreate](/docs/admin-api/reference/orders/ordersCaptureCreate) for Shop Pay orders. - **Refunds** can be full or partial, using [ordersRefundCalculateCreate](/docs/admin-api/reference/orders/ordersRefundCalculateCreate) and [ordersRefundCreate](/docs/admin-api/reference/orders/ordersRefundCreate) as for other payment methods (see [Order Refunds](/docs/admin-api/guides/order-management#order-refunds)). A refund can stay pending until Shopify confirms it. - **Disputes** are handled in the merchant's Shop Pay store in Shopify admin. They aren't created as NEXT disputes, so they don't appear in [disputesList](/docs/admin-api/reference/payments/disputesList), and the [dispute.created](/docs/webhooks/reference/payments/dispute.created) and [dispute.updated](/docs/webhooks/reference/payments/dispute.updated) webhooks don't fire for `shop_pay` transactions. @@ -77,5 +77,5 @@ The [Campaigns API](/docs/campaigns/api) accepts `shop_pay` as `payment_detail.p 2. Redirect the customer to the `payment_complete_url` in the response, where they pay with Shop Pay. 3. The customer returns to your `success_url`, or to `payment_failed_url` if payment fails. -Shop Pay must also be enabled on each campaign, in `available_payment_methods` or `available_express_payment_methods` on [campaignsCreate](/docs/admin-api/reference/campaigns/campaignsCreate). Use the list that contains `shop_pay` for the campaign's gateway group in [gatewayGroupsList](/docs/admin-api/reference/payments/gatewayGroupsList). +Shop Pay must also be enabled on each campaign, in `available_payment_methods` or `available_express_payment_methods` on [campaignsCreate](/docs/admin-api/reference/campaigns/campaignsCreate). Set the campaign's `payment_gateway_group_id` to a gateway group whose methods in [gatewayGroupsList](/docs/admin-api/reference/payments/gatewayGroupsList) include `shop_pay`, and add it to the matching list.