Skip to main content

Shopify

Plugin for Gesso Commerce Provider​

note

The following describes general usage, if you setup your project following getting-started/install then these next steps have already been handled for you.

Requirements​

A Shopify store Trial Sign up. Note from the Admin dashboard in Settings ending in .myshopify.com:

  • Shopify Storefront URL

An app, created at https://admin.shopify.com/store/<storename>/settings/apps/development, with Admin and Storefront API scopes set. Note from the app under API credentials:

  • Storefront API access token

The Search & Discovery app installed, with any filters you intend to use configured at https://admin.shopify.com/store/<storename>/apps/search-and-discovery/filters.

Shopify Payments setup using fake details for verification, with test mode enabled at https://admin.shopify.com/store/<storename>/settings/payments. Any legal warnings you see do not apply to dev stores.

Installation​

Install the Gesso Commerce provider

  • pnpm install @acromedia/gesso-commerce

Install Gesso Shopify plugin

  • pnpm install @acromedia/gesso-shopify

Configure the package

  • Set the SHOPIFY_STORE_DOMAIN and SHOPIFY_ACCESS_TOKEN env values, either in .env or directly

  • The SHOPIFY_STORE_DOMAIN is what we referred to above as Shopify Storefront URL

  • The SHOPIFY_ACCESS_TOKEN is what we referred to above as Storefront API access token

Generate a gesso.config.json

note

This file configured to default to Acro’s test storefront. You will need to update this file with information specific to your storefront.

  • pnpm gesso config shopify

If you didn't pass Shopify options to @acromedia/create-gesso and you're adding this module for the first time construct the provider using

  • pnpm gesso construct commerce shopify

After running the construct script you will now see a commerce.ts file in the root directory of your project. This file takes care of telling gesso-commerce what plugin system is being used and ensures the correct hooks are exposed by gesso-commerce.

Register the plugin with the provider

  • Under your source files directory (commonly src) there will be a newly added commerce.ts file.
// commerce.ts
// Import the commerce provider
import { commerce } from "@acromedia/gesso-commerce";
// Import the provider plugins
import plugin from "@acromedia/gesso-shopify";
// Import the Gesso config.
import config from '../gesso.config.json';

// Register the plugins and config with commerce provider.
const commerce = commerce(plugin, config);

export default commerce;

Usage​

// import the commerce provider from the commerce.ts file.
import commerce from "./commerce";

// Import your required functionality.
const { useProduct } = commerce;

const ProductPage = ({ productId }) => {
  // Example implementation of the useProduct hook provided via Gesso Commerce.
  const { payload, error, state } = useProduct(productId);

  return <ProductDetails product={payload} />;
};

Payments via Shopify​

The default payment provider for Shopify is their in-house Shopify Payments. This covers all of your major service providers (not to mention a ton of minor SPs) and third parties like Apple Pay, Google Pay, etc. You can apply for verification at https://admin.shopify.com/store/<storename>/settings/payments using bogus details, sites like https://wise.com/ca/bank-codes/transit-number/td-bank are useful for this type of data. Once that is complete you should click on Manage and activate test mode at the bottom of the form.

Free payments​

Currently this is the only supported way to complete a checkout process. There aren't many use cases for it, essentially this would be used for free items in the shop that do not apply for tax nor are they physical products (no shipping).

Usage​
// import the commerce provider from the commerce.ts file.
import commerce from "./commerce";

const { useCheckout } = commerce;

const FreeCheckoutPage = async ({contactEmail, shippingProfile, cartId }) => {
  const { complete } = useCheckout(cartId);

	let checkout;
	try {
		checkout = await complete(contactEmail, shippingProfile);
	} catch (e) {
		redirect("/500");
	}

  return <FreeCheckoutSuccess checkout={checkout} />;
};

Credit Card payments​

info

TBD