How-To: Onboard Customers into Shopfront

Getting Started

Shopfront provides applications with the ability to onboard customers directly onto Shopfront with a free-trial which will automatically connect to your application once they've completed the sign-up form.

This is useful for redirecting users who don't already have a Shopfront account or for creating new trial stores.

Your application and the user will go through the following flow:

1. Create connection token
2. Redirect user to sign-up page
3. User creates trial store
4. Shopfront connects and informs your application

Creating the Onboarding Connection Token

The first step to onboarding a customer to automatically connect to your application is to generate an onboarding connection token, this can be done by sending a POST request to https//onshopfront.com/api/onboard with the following parameters (must be sent as JSON):

• client_id: The Client ID of your application
• client_secret: The Client Secret of your application
• redirect_uri: The redirect URI for your application
• state: The onboarding token's state (to verify the request from Shopfront)
• scope: The scopes requested, must be a string with each scope separated by a string
• contact: (optional) The contact details to pre-populate the sign-up form
• contact.organisation_name: (optional) The name of the organisation
• contact.name: (optional) The user's name
• contact.email: (optional) The user's email
• contact.phone: (optional) The user's phone number

This will then respond with the following JSON body:

• redirect_to: The address to redirect the user to
• token: The ID of the token issued to your application, this can be used to verify the sign-up

const response = await fetch("https://onshopfront.com/api/onboard", {
    method : "POST",
    headers: {
        "Content-Type": "application/json",
        "Accept"      : "application/json",
    },
    body: JSON.stringify({
        client_id    : process.env.SHOPFRONT_CLIENT_ID,
        client_secret: process.env.SHOPFRONT_CLIENT_SECRET,
        redirect_uri : process.env.SHOPFRONT_REDIRECT_URI,
        state        : generateState(),
        scope        : "see_products see_cost",
        contact      : {
            organisation_name: "Test Organisation",
        },
    }),
});

if(response.status !== 200) {
    // We received an error response from Shopfront
    throw new Error("Unable to retrieve onboarding token from Shopfront");
}

const body = await response.json();

// Store the ID of the token for later if required
storeOnboardingToken(body.token);

// Perform the redirect to the sign-up form
redirectUser(body.redirect_to);

$ch = curl_init("https://onshopfront.com/api/onboard");

curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type" => "application/json",
    "Accept"       => "application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "client_id"     => env("SHOPFRONT_CLIENT_ID"),
    "client_secret" => env("SHOPFRONT_CLIENT_SECRET"),
    "redirect_uri"  => env("SHOPFRONT_REDIRECT_URI"),
    "state"         => generateState(),
    "scope"         => "see_products see_cost",
    "contact"       => [
        "organisation_name" => "Test Organisation",
    ],
]));

$response    = curl_exec($ch);
$status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);

curl_close($ch);

if($status_code !== 200) {
    throw new Exception("Unable to retrieve onboarding token from Shopfront");
}

$body = json_decode($response);

// Store the ID of the token for later if required
storeOnboardingToken($body->token);

// Perform the redirect to the sign-up form
redirectUser($body->redirect_to);

Receiving the Connection from Shopfront

After the user has successfully gone through the sign-up process, Shopfront will send a GET request to your redirect_uri specified previously that includes all the details required to authorize the user:

• code: A temporary code to retrieve an access token
• state: The state provided when requesting to onboarding token
• vendor: The subdomain of the store that was redirected
• from_onboarding: The ID of the token that was used to onboard the user

You can then exchange the provided code for an access token (like you would through the normal OAuth flow).

The response for this request will be ignored and the user will be left in Shopfront, so it's best to do things like send notifications to remind the user to complete the authorisation process if there are further requirements by your application.