Shopify

The shopify module lets editors search and import products and collections from a Shopify store through Brightspot's federated search, and can automatically re-import a product when it changes in Shopify.

Dependencies

Depends on db-http and the Shopify Admin GraphQL API, called through an Apollo GraphQL client. The shopify-api module holds the GraphQL schema and queries that Apollo's Gradle plugin generates typed classes from; it has no runtime logic of its own. Product and collection search each live in their own module, shopify-product and shopify-collection, since they're distinct content types that share the same store account configuration.

Installation

Maven

<!-- Requires Brightspot 5.0 or later. -->
<dependency>
    <groupId>com.brightspot.dbhttp</groupId>
    <artifactId>shopify</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle

// Requires Brightspot 5.0 or later.
implementation 'com.brightspot.dbhttp:shopify:1.0.0'

Gradle (Kotlin DSL)

// Requires Brightspot 5.0 or later.
implementation("com.brightspot.dbhttp:shopify:1.0.0")

Maven

<!-- Requires Brightspot 5.0 or later. -->
<dependency>
    <groupId>com.brightspot.dbhttp</groupId>
    <artifactId>shopify-product</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle

// Requires Brightspot 5.0 or later.
implementation 'com.brightspot.dbhttp:shopify-product:1.0.0'

Gradle (Kotlin DSL)

// Requires Brightspot 5.0 or later.
implementation("com.brightspot.dbhttp:shopify-product:1.0.0")

Maven

<!-- Requires Brightspot 5.0 or later. -->
<dependency>
    <groupId>com.brightspot.dbhttp</groupId>
    <artifactId>shopify-collection</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle

// Requires Brightspot 5.0 or later.
implementation 'com.brightspot.dbhttp:shopify-collection:1.0.0'

Gradle (Kotlin DSL)

// Requires Brightspot 5.0 or later.
implementation("com.brightspot.dbhttp:shopify-collection:1.0.0")

API reference

Product

brightspot.shopify.db.product.ShopifyProductDatabase extends HttpDatabase and searches Shopify products by title, product type, tag, Id, status, last-updated date, price, and inventory. Shopify limits each page to 250 products and paginates with a cursor rather than an offset, so the database tracks each search's cursor per web request.

brightspot.shopify.db.product.ShopifyProduct extends ExternalItem.

Field	Type	Description
productId	String	The Shopify product Id. Filterable in search.
productTitle	String	The product title.
description	String	The product description.
onlineStoreUrl	String	The product's storefront URL.
featuredImage	ShopifyProductImage	The product's featured image.
media	List<ShopifyProductImage>	All product images.
updatedAt	Date	When the product was last updated in Shopify. Filterable in search.
options	List<ShopifyProductOption>	The product's option names and values (for example size or color).
shopifyProductVariants	List<ShopifyProductVariant>	The product's variants, each with its own SKU, price, and inventory.
statusSelection	ShopifyStatus	The product's status in Shopify: active, archived, or draft. Filterable in search.
price	double	The product's price. Filterable in search.
inventory	int	The product's inventory count. Filterable in search.

Collection

brightspot.shopify.db.collection.ShopifyCollectionDatabase extends HttpDatabase and searches Shopify collections by title, collection type, Id, and last-updated date, using the same cursor-based pagination as products.

brightspot.shopify.db.collection.ShopifyCollection extends ExternalItem.

Field	Type	Description
collectionId	String	The Shopify collection Id. Filterable in search.
title	String	The collection title.
description	String	The collection description.
productCount	int	The total number of products in the collection.
updatedAt	Date	When the collection was last updated in Shopify. Filterable in search.
conditions	List<ShopifyCollectionCondition>	The rules defining a smart collection.
shopifyProducts	List<ShopifyProduct>	The first 10 products in the collection.
collectionType	ShopifyCollectionType	Whether the collection is manually curated or rule-based (smart). Filterable in search.

note

A collection only imports its first 10 products directly. When productCount exceeds 10, the collection's edit page shows a link to view the remaining products directly in Shopify.

Configuration

A store's credentials are stored on brightspot.shopify.db.ShopifyAccount (internalName, storeUrl, shopifyAccessToken, apiSecretKey), collected into a Set<ShopifyAccount> on ShopifySiteSettings, shown under Site Settings > Integrations > Shopify. A site can configure multiple Shopify store accounts.

apiSecretKey verifies webhook signatures for automatic updates: each account has an autoUpdateSettings (ShopifyWebhookSettings) with an enabled toggle and a set of subscriptions, each specifying which product events to subscribe to (ShopifyProductWebhookTopic: create, update, delete) and a ShopifyProductWebhookProcessor to handle them. ShopifyWebhookProcessingTask checks for received webhooks once a minute.

Extending the integration

The module doesn't ship a content type for imported products or collections, or a concrete webhook processor. To let editors create a local content record from search results, define a content type and extend ExternalItemConverter<ShopifyProduct, T> or ExternalItemConverter<ShopifyCollection, T> to convert the external item into it on import.

To act on subscribed webhook events—for example, applying an update to that content record when the source product changes in Shopify—extend ShopifyProductWebhookProcessor and implement create, update, and delete.