Prebuilt Connectors
Prebuilt connectors are back-end time savers when paired with traditional monolithic systems. They often leverage webhooks for near-real-time data syncs and write the transformations on your behalf.
Prebuilt connectors are opinionated and, while they are great for most, they may not be the best match for every enterprise merchant
Shopify Connector
The Shopify Connector indexes products and collections into Nacelle. The connector uses webhooks to ensure data in Nacelle is always up to date. Setting up the connector is a straightforward process that requires a few updates in the Shopify and Nacelle Dashboards.
Shopify Setup
Head over to Shopify and log in to the store.
Create a Private App
A private app must be created to allow Nacelle to communicate with Shopify. To do so, open the store settings and go to the Apps and Sales Channels tab. Next, click on "Develop apps for your store", and then "Create an app".
Name your private app something memorable, like "Nacelle". It’s important to note that this name will show up in Shopify reports and other parts of the UI as a sales channel.
Storefront Access Token Configuration
Next we'll allow Storefront API access. Under the "Configuration" tab, click the "Configure" button under "Storefront API integration". Check all the boxes for all headings and click "Save".
Admin Access Token Configuration
Only applies to merchants using a Shopify Storefront API version that's later than V2022-07
Starting from 2023-04, in order to index Shopify metafields
data into Nacelle, merchants need to provide their Shopify Admin Access Token with read_products
access scope.
Install App
Finally, go to the "API Credentials" tab. Click "Install app", agree. Copy your Storefront API access token and admin access token and store them in a secured note. You will need these tokens for Nacelle to index your data.
Nacelle Setup
Now, head over to the Nacelle Dashboard and log in.
Connector Setup
In the sidebar, click the dropdown for "Space" and select the space to use (or create one). Then, click the top tab "Data Connectors".

Click the "Add Data Connectors" button, and select "Shopify" in the dropdown.
Enter the Shopify store’s .myshopify
subdomain and the Storefront Access Token we copied before. To index metafields
for merchants using Shopify storefront API version later than 2022-07, also enter your Admin Access Token configured in the above section.
We can leave the "Webhook Shared Secret" empty for now. Once you click Save, Nacelle will ingest your data from Shopify.
Initial Sync
Once the connector is added, you’ll see the connector information, including Nacelle's Source ID for the connector. The "Re-index Shopify" button will be disabled, indicating a reindex is in progress. You can come back here at any time to manually reindex all of your Shopify data.
Once ingestion is complete, you can verify that your products and collections have been properly ingested by visiting the appropriate tab in your space or by querying for the data using the Nacelle Storefront API.
Shopify Webhook Setup
You can use Shopify's webhooks to automatically update your data ingested by Nacelle.
To create a new outgoing webhook connection, log in to your Shopify dashboard. All webhook settings are found in Settings > Notifications. At the bottom of the window, click the button for Create webhook. For this example we will create a webhook to tell Nacelle to reindex a product when it has been updated in Shopify.
In the Add a webhook modal, in the dropdown for Event select Product update. For Webhook API Version select 2022-04
. Then in the field for Url paste the URL for Nacelle's webhook receiver API, including your Nacelle spaceId
at the end (found in the Nacelle sidebar). Click Save webhook
<https://shopify-webhook.api.nacelle.com/product/update?spaceId=><your_space_id>
Next copy the webhook signing key at the bottom of your webhook list. Nacelle will use this to verify that webhook updates are coming from Shopify. Back in Nacelle, navigate to your Space Settings, go to the Data Connectors tab, edit the Shopify connector that we've just created. Finally, paste the signature into the Webhook Shared Secret field and save.
Any time a product is updated in your Shopify storefront, it will now trigger Nacelle to reindex that product and keep your data in sync.
Note that automated updates to smart collections will not trigger a Shopify webhook.
Similarly, re-ordering manually sorted collections will not trigger a Shopify webhook. This is a limitation of Shopify. As a workaround, if the collection is otherwise updated (title, description, etc), then this collection update will trigger a Shopify webhook that will trigger Nacelle to fetch updates on smart collections and sort order
Webhook Endpoints
There are six endpoints for receiving different Shopify webhook events that you should configure following the steps above:
Product Create
<https://shopify-webhook.api.nacelle.com/product/create?spaceId=><your_space_id>
Product Update:
<https://shopify-webhook.api.nacelle.com/product/update?spaceId=><your_space_id>
Product Delete:
<https://shopify-webhook.api.nacelle.com/product/delete?spaceId=><your_space_id>
Collection Create:
<https://shopify-webhook.api.nacelle.com/collection/create?spaceId=><your_space_id>
Collection Update:
<https://shopify-webhook.api.nacelle.com/collection/update?spaceId=><your_space_id>
Collection Delete:
<https://shopify-webhook.api.nacelle.com/collection/delete?spcaeId=><your_space_id>
Contentful Connector
The Contentful connector indexes content into Nacelle. The connector uses webhooks to ensure data in Nacelle is always up to date. Setting up the connector is a straightforward process that requires a few updates in the Contentful and Nacelle Dashboards.
If you use internationalization within your CMS, we recommend you leverage the Ingestion API directly
Contentful Setup
Head over to Contentful and log in to the space.
Create an API token
An API Key needs to be created to allow Nacelle to communicate with Contentful. To do so, click on the Settings dropdown, followed by the API Keys link.
Give your key any name you would like, such as "Nacelle". Select the environments to connect the key to.
Before leaving, make a note of the Space ID and the Content Delivery API Access Token. These will be needed later.
Nacelle Setup
Head over to the Nacelle Dashboard and log in.
Connector Setup
From the dashboard home:
Click the settings icon for the space where you’d like to add the connector.

Then, select the "Data Connectors" tab and click the Add Connector button in the top right of the UI.

From the modal, select "Contentful" in the dropdown.
Enter the Contentful space’s ID, the Environment, and the Delivery Token. Optionally, you can add the Webhook Secret and Preview Token so you can add Contentful preview data. The connector is now ready for action.
From a space:
Select Space Settings from the primary navigation pane and then select the Data Connectors tab. Next, click the Add Connector button in the top right of the UI

From the modal, select "Contentful" in the dropdown.
Enter the Contentful space’s ID, the Environment, and the Delivery Token. Optionally, you can add the Webhook Secret and Preview Token to add Contentful preview data. The connector is now ready for action.
Run Initial Sync
Once the connector is added, you’ll now have the option to Re-Index the connector. Click the Re-Index button in the connector to ingest your Contentful data
Once ingestion is complete, you can verify that your products and collections have been properly ingested by visiting the appropriate tab in your space or by querying for the data using the Nacelle Storefront API.
Contentful Preview Data
To enable Preview Data from Contentful, follow these steps.
From the Contentful dashboard, navigate to Settings, then API keys.
Under the Content delivery/preview tokens tab, select the API key used in your Contentful ingestion connector settings.

The preview token will be found under the label Content Preview API - access token.

Now, head over to the Nacelle dashboard and either click the settings gear icon for the space you’re updating, select the space, go to Space Settings in the primary navigation pane, and click the Data Connectors tab.
Next, click the 3 dots “menu” icon on the Contentful connector and choose Edit.
In the field labeled Contentful Preview Token, add the preview token created in Contentful.
Now, click the Save and Re-Index button, and you’re all set.
Nacelle Contentful CMS App
Nacelle's app for Contentful makes it easy to link products and collections to your content.
Saving product or collection data within content in the CMS can add risk to your composable stack's data consistency. Avoid this by using Nacelle's CMS apps.
It is important to avoid the composable anti-pattern of daisy-chaining, which you can learn more about here: https://nacelle.com/blog/cms-antipatterns-in-headless-commerce.
By using the Nacelle CMS app, you ensure best practices are followed, and daisy chaining is avoided.
Installation
- Inside Contentful, click your organization's name in the top left corner of the app
- In the slide-out menu that appears, click "Organization settings & subscriptions"
- In the top navigation, click "Apps"
- On the next page, click "Create an App"
- Name the app whatever you want (we recommend "Nacelle")
- Provide the Nacelle App URL: https://contentful-app-nacelle.netlify.app
- In the "Locations" section that appears on the page, check the boxes for "App configuration screen" and "Entry field"
- Check the box for "Short text" inside the "Entry field" location
- Click "Create app"
- On the next screen, click "Install to space" in the top right corner
- In the modal that appears, select the environment to deploy to. Typically this will be "master"
- On the next screen, enter your Nacelle Space ID and Token, and click "Install"
Field Setup
Navigate to the Content Model you want to set up the link for. Add a new field and name it "Product Handle" or "Collection Handle". The Field ID will auto-populate but should be manually set to handle
. This will ensure that your content will appear as expected in the Nacelle dashboard.
Navigate to the Appearance settings for the new field. Scroll to the right, where you will see the new Nacelle app.
When you add a new content entry, that field will let you select products or collections from your catalog. Making a selection will populate the content field with a reference to the product or collection of interest.
Contentful webhook setup
Navigate to Contentful Webhooks Settings, via the top navbar, Settings > Webhooks, and click Add Webhook
For the Name field, enter any value, e.g. My Webhook
For the URL field, Select POST and add the URL:
<https://contentful.api.nacelle.com/webhook/contentful
>
Triggers
Check Select specific triggering events
Check Publish
and Unpublish
cells in the Entry
and Asset
row
Headers
Click + Add secret header
For Key enter x-contentful-secret
For Value enter any arbitrary value, e.g. 5f4dcc3b5aa765d61d8327deb882cf99
(md5 hash of “password”)
Click + Add custom header
For Key enter x-nacelle-space-id
For Value enter your Nacelle space id
For Content-type select application/json
Update the Contentful Connector in the Nacelle Dashboard
Navigate to your Nacelle dashboard, select on your desired space, then go to Space Settings in the primary navigation pane, and click the Data Connectors tab.
Next, click the 3 dots “menu” icon on the Contentful connector and choose Edit.
For Contentful Webhook Secret, enter the value you used above for the secret header, x-contentful-secret
Sanity Connector
The Sanity connector indexes content into Nacelle. The connector uses webhooks to ensure data in Nacelle is always up to date. Setting up the connector is a straightforward process that requires a few updates in the Sanity and Nacelle Dashboards.
Sanity setup
Let's start by getting the Sanity project ID by going to the Sanity dashboard and selecting the project.

Once you are in the desired Sanity project, the project ID will be displayed in the header at the top of the screen. Copy this for later.

Click on the “datasets" tab within the Sanity project. (note, you may have multiple). You will need the name of the desired dataset - in this case, “production” - that Nacelle will ingest, so take note of this name.

Private datasets and content previews
For ingestion of private datasets or content previews, you can create an access token and provide it to Nacelle.

In the Sanity project settings, go to the API tab. Click "Add API token", name the token as you'd like, and leave the default "Viewer" permission. Save and copy the generated API token, as you'll need to provide it to Nacelle in the next steps.
Nacelle's setup
Now that your Sanity project is setup, head over to the Nacelle Dashboard and log in.
In the sidebar, click the dropdown for "Space" and select the space to use (or create one). Then, click the top tab "Data Connectors".
Click the "Add Data Connectors" button, and select "Sanity" in the dropdown.
Enter the Sanity Project ID, the Sanity Dataset to ingest, and your Sanity project's Webhook Secret. If desired, include the Sanity API token, which will allow ingestion of draft content and private datasets.
Once you click Save, Nacelle will begin to ingest data from Sanity.
Configure Sanity Webhooks
We can set up Sanity to automatically sync with Nacelle when content is updated. We will set up two webhooks for each Nacelle space, one for create/update and one for delete.
Return to the desired project within Sanity. After opening the project, navigate to the API tab, and create a “GROQ-powered Webhook.”
- Name your Webhook
- Add the correct URL. For Create/Update, it should be
<https://sanity-webhook.api.nacelle.com/create>
. For Delete, it should be https://sanity-webhook.api.nacelle.com/delete - Choose your data set from the drop-down (the same data set that was entered from your initial inputs)
- Select both CREATE and UPDATE, or DELETE from the trigger actions.
- Make sure the “enable webhook” box is checked.
- Add a header
x-nacelle-space-id
, with the value being your Nacelle space ID (located in the Nacelle sidebar) - Add a header
x-nacelle-source-id
, with the value being your connector's Nacelle source ID. You can find this in the Space Settings, Data Connectors tab. - Choose API version
v2021-03-25
from the drop-down. - Create a webhook secret. This is a merchant-created string that's entered into Sanity. It should be the same for both of your Nacelle webhooks. Note it for later as Nacelle will use it to verify the security of your data.
- Hit Save
Example fields to modify from default:

Finally, be sure to go to your Nacelle space, go to the Data Connector tab, and edit the Sanity connector settings to include the webhook secret from above.
Now when your content is changed, Nacelle will continually be updated!
Nacelle Sanity CMS plugin
We have made a Sanity plugin to make it easy to link products and collections to your custom Content types.
Linking product and content data within the CMS can add risk to your composable stack's data consistency. Avoid this with Nacelle's CMS pattern.
It is important to avoid the composable anti-pattern of daisy-chaining, which you can learn more about here: https://nacelle.com/blog/cms-antipatterns-in-headless-commerce.
By using the Nacelle Sanity plugin, you ensure best practices are followed, and daisy chaining is avoided.
Installation & Setup
In your Sanity codebase, install Peer Dependencies
npm i @sanity/ui styled-components
Install the plugin
sanity install @nacelle/sanity-plugin-nacelle-input
Credentials
You'll need to provide the ID and Token associated with your Nacelle space. These credentials can be found in the Nacelle Dashboard.
Config file for single space
./config/@nacelle/sanity-plugin-nacelle-input.json
{
"nacelleEndpoint": "your-nacelle-storefront-api-endpoint",
"nacelleSpaceToken": "your-nacelle-graphql-token"
}
Within
.env.development / .env.production
SANITY_STUDIO_NACELLE_SPACE_ENDPOINT=your-nacelle-storefront-endpoint
SANITY_STUDIO_NACELLE_SPACE_TOKEN=your-nacelle-public-storefront-token
Adding Credentials to Multiple Spaces
Create a config file at
./config/@nacelle/sanity-plugin-nacelle-input.json.
Then add a nacelleSpaces
array:
"nacelleSpaces": [
{
"spaceName": "Space 1",
"nacelleEndpoint": "space-1's-nacelle-storefront-endpoint",
"nacelleSpaceToken": "space-1's-nacelle-public-storefront-token"
},
{
"spaceName": "Space 2",
"nacelleEndpoint": "space-2's-nacelle-storefront-endpoint",
"nacelleSpaceToken": "space-2's-nacelle-public-storefront-token"
}
]
Use in Schema Documents
Set the type field to nacelleReference to use the custom input component:
{
name: 'reference',
title: 'Reference',
type: 'nacelleReference',
}
Options
The custom input component default allows you to reference products or collections.
Realistically, you probably want to restrict the component to either products or collections. To do that, provide either ['products']
or ['collections']
to options.dataType
:
// example: collections ONLY
{
name: 'collectionReference',
title: 'Collection',
type: 'nacelleReference',
options: {
dataType: ['collections']
}
}
// example: products ONLY
{
name: 'productReference',
title: 'Product',
type: 'nacelleReference',
options: {
dataType: ['products']
}
}
Data shape
The custom input component will store a reference object with the following format:
{
type: 'NacelleReference',
referenceType: 'PRODUCT', // PRODUCT or COLLECTION
nacelledEntryId: '123455'
handle: 'blue-shirt'
locale: 'en-US'
}
Backward Compatibility with @nacelle/sanity-plugin-pim-linker
@nacelle/sanity-plugin-pim-linker
For projects using the legacy @nacelle/sanity-plugin-pim-linker
for product/collection references, we provide a backward-compatible custom input called nacelleData
. This input stores only the handle of a particular product or collection rather than a structured nacelleReference
object.
Use in Schema Documents
Set the type
field to nacelleData
to use the custom input component:
{
name: 'handle',
title: 'Handle',
type: 'nacelleData',
}
Data Shape
The backward-compatible custom input component will store only a reference handle.
{
handle: 'blue-shirt'
}
Updated 13 days ago