Shop Pay Admin API Guide

Shop Pay is a fully integrated payment method, supported both in the storefront checkout and via the Admin API. Shop Pay transactions send the customer through a Shop Pay redirect flow, with the resulting order information provided back to your application. Below are the steps needed to get Shop Pay set up and working on the Admin API.

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.

API Payment Redirect Flow

Below is a high-level overview of the user flow when creating orders on the Admin API that utilize the payment method redirect flow.

Create Order on Admin API

When creating a new order using Shop Pay, you must specify the payment_method=shop_pay as well as provide a payment_return_url. The payment_return_url is your endpoint that will receive a POST request containing the final order data.

{
    "payment_method": "shop_pay",
    "payment_details": {
        "payment_return_url": "<external checkout url>",
        "shop_pay_account": "<shop pay account id>" // optional
    }
}

Redirect Customer to Payment Complete URL

The response when creating the order will provide a payment_complete_url. Your application should redirect the customer to this URL for completing the payment on the store's Shop Pay Checkout page.

{
    "reference_transaction_id": null,
    "payment_complete_url": "https://<domain>/shop-pay/checkout/<session id>/"
}

Receiving Order Data

After the customer has completed their payment, they will be redirected to your application with a POST request containing data in the response key comprising all of the order information as a string. See examples below.

import json

def order_receiver_view(request):
    data = json.loads(request.POST.get("response"))
    ...
    return HttpResponse(status=201)

Upsells

Shop Pay does not support one-click upsells through the ordersAddLineItemsCreate API.

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 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 for Shop Pay orders.

• Refunds can be full or partial, using ordersRefundCalculateCreate and ordersRefundCreate as for other payment methods (see 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 and dispute.updated webhooks don't fire for shop_pay transactions.

Campaigns API

The 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. Set the campaign's payment_gateway_group_id to a gateway group whose methods in gatewayGroupsList include shop_pay, and add it to the matching list.