Shop Pay Admin API Guide

Create Admin API orders paid with Shop Pay using the redirect payment flow, including standard and one-click checkout options

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.

Your store must have an active Shop Pay account to use the Shop Pay payment method.

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 Details for Order with Shop Pay

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

You can optionally provide a shop_pay_account when creating the order to use a Shop Pay account other than the store default Shop Pay account.

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.

Response with Payment Complete URL

{
    "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.

Order data structure follows Admin Order API and is application/x-www-form-urlencoded in a variable called response. If the order data is an empty dictionary , it means payment collection was unsuccessful and the order was not created.

Example Parsing of Order Data

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.