Integration
This article explains how to integrate with third-party services using Prismic's integration field.
This feature isn't yet available for everyone
The integration field is still in beta. It is being progressively deployed to all repositories. If you don't see the integration fields tab in your repository's settings, you can request access via the Prismic Support Portal.
Prismic's integration field allow you to integrate third-party data — such as from e-commerce catalogs or custom APIs — into your repository.
There are three ways you can integrate a third-party data source using an integration field:
- Pull data from a custom read API
- Push data from a custom write API
- Automatically sync with a Shopify catalog
To pull data into an integration field, you must create your own API that conforms to the format prescribed below.
In your repository, navigate to the Settings > Integration Fields.
Select Custom API.
Select pull data from my endpoint, and fill in the Custom API details:
Catalog Name
required
The name of your Custom API catalog. This is shown in the custom type Builder.
Description
required
A description for your Custom API catalog. This is shown in the custom type Builder.
Endpoint
required
The endpoint of your Custom API. The API must output JSON in the specified format (see below).
Access token (Basic auth)
The access token for Basic Authentication to your Custom API catalog.
What to Provide: Simply provide the username of your app’s Basic Auth in this field. Do not encode it in Base64 or add any suffix.
How It's Used: When Prismic sends a GET request to your endpoint, it will automatically encode the provided access token along with a trailing colon (:) and use it in the Basic Auth header. This behaves similarly to how Postman would handle the Basic Auth process.
Click Save. The Integration Field will automatically begin to crawl and sync your Custom API.
Your Custom API format must be compatible with the integration field. The API can have the following properties:
results_size
number (required)
The total number of items to index.
results
array (required)
An array with the results. It must be sorted by the last_update field, and have a maximum of 50 items per page. See information on pagination, below.
results[index].id
string (required)
The unique ID of the item.
This property is not exposed on the Document API. To expose it, include it in results[index].blob.
results[index].title
string (required)
The title of the item. This is shown in the document editor.
results[index].description
string (required)
The description of the item. This is shown in the document editor.
results[index].image_url
string
The image url of the item. This is shown in the document editor.
results[index].last_update
number
The timestamp of the last update for an item, sorted from newest to oldest
results[index].blob
object (required)
An object with the item's data. This is what appears in the in the document in the Prismic API response.
id must be duplicated in the blob to make the integration compatible with the Migration API.
Here is an example of what your custom API should look like:
{
"results_size": 1,
"results": [
{
"id": "1",
"title": "Item Title",
"description" : "Description of the item.",
"image_url" : "https://images.unsplash.com/photo-1577401239170-897942555fb3?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=1600&q=80",
"last_update" : 1509364426938,
"blob": {
"sku": "1",
"title": "First item",
"description": "Description of first item.",
"image_url": "https://images.unsplash.com/photo-1577401239170-897942555fb3?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=1600&q=80"
}
}
]
}The results array can have a maximum of 50 items. If your API contains more than 50 items, you need to set up pagination.
The page number for the API must be passed as a parameter in the URL, so you'll pass ?page=1, for the first page, then ?page=2, and so on.
Automatic content updating
If a change is made in your external API, Prismic will automatically update the data to ensure that you always have the most up-to-date content. The content refresh currently happens every 30 minutes, though interval may change in the future.
Add your Integration Field to a custom type and then add a catalog item to a Prismic document.
The first time you sync your Integration Field, it can take some time to update.
The integration field has a write API that allows you to push data to Prismic so you can create, modify, or delete catalog items via a dedicated enpoint.
Go to Settings > Integrations Fields in your repository, Click on Custom API, and select Push data to Prismic. Only Administrators can edit the integration field configuration.
Enter the Catalog name and description, and then click on Create my Integration Field.
Once your Integration Field is created, you can click on it to view the write API endpoint as well as the access token you'll need to interact with your API.
The integration field write API allows you to create, update and delete items, or reset the entire catalog.
To do so, send a POST request to the endpoint specifying the type of action you want to perform, with necessary information in the header and body.
Let's go over each of the steps to push to your custom catalog.
In your repository, go to Settings > Integration Fields. Scroll down until you find your active Integration Field write API. Click on the pencil edit button; it will open the configuration. From there, copy the endpoint, which will have the following structure:
https://if-api.prismic.io/if/write/<your_repo_and_catalog_names>
Where <your_repo_and_catalog_names> is a string made up of your repository and catalog name.
In this example endpoint, we will assume that the repository name is your_repo_name and the catalog ID is my_catalog.
https://if-api.prismic.io/if/write/your-repo-name--my_catalogBy sending a POST request to your endpoint, you can create, update or delete items in your catalog. The way you write your endpoint will define the action that will take effect:
To create or update items, use the main endpoint:
https://if-api.prismic.io/if/write/your-repo-name--my_catalogTo delete one or more items, use /deleteItems:
https://if-api.prismic.io/if/write/your-repo-name--my_catalog/deleteItemsTo reset the entire catalog, use /reset:
https://if-api.prismic.io/if/write/your-repo-name--my_catalog/resetThe body of the POST requests will depend on the action you want to perform:
- To create items: include an array with the new items following the format specified below.
- To update items: include an array with the existing items and their updated values following the format specified below.
- To delete one or multiple items: include an array with the ID of each item to delete.
- To reset the entire catalog: no body is required.
Items POSTed to the write API should follow the following format. For more information on these properties, see "Custom API format," above.
{
"id": "my_item_id",
"title": "Item Title",
"description" : "Description of the item.",
"image_url" : "http://...",
"last_update" : 1509364426938,
"blob": {
"id": "my_item_id",
"sku": "827",
"title": "First Item",
"description": "Description of first item...",
"image_url": "https://..."
}
}Include a Bearer token in the authorization of the POST request. To find your token in your active, click on the pencil edit button on your Integration Field settings, and scroll down to find the token section.
Here are full examples of raw POST requests to create, update, or delete items; or reset the entire catalog of your Integration Field write API.
You can run a test in a third-party API platform, like Postman.
To create or update:
// Example POST request to Create or Update a catalog with 500+ items
POST /if/write/your-repo-name--my_catalog HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
Host: if-api.prismic.io
Content-Type: application/json
Content-Length: 514
[
{
"id": "0",
"title": "My Item number 0",
"description": "Lorem ipsum",
"image_url": "https://if-test-custom-api.herokuapp.com/asset/0",
"last_update": 1591670070,
"blob": {
"id": "0",
"lorem": "ipsum",
"dolor": "sit"
}
},
{
"id": "1",
"title": "My Item number 1",
"description": "Lorem ipsum",
"image_url": "https://if-test-custom-api.herokuapp.com/asset/1",
"last_update": 1591670070,
"blob": {
"id": "1",
"lorem": "ipsum",
"dolor": "sit"
}
}
]To delete:
// Example POST request to delete three items from a catalog with 500+ items
POST /if/write/your-repo-name--my_catalog/deleteItems HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
Host: if-api.prismic.io
Content-Type: application/json
Content-Length: 514
["id-0", "id-1", "id-2"]To reset:
// Example POST request to reset a catalog, deleting 500+ items
POST /if/write/your-repo-name--my_catalog/reset HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
Host: if-api.prismic.io
Content-Type: application/json
Content-Length: 0Add your Integration Field to a custom type and then add a catalog item to a Prismic document.
The first time you sync your Integration Field, it can take some time to update.
This is the shape of the data from the Prismic API:
// API response example of an integration field
{
// ...
"example_integration_field":{
"id":6562914664611,
"title":"Organic coffee blend",
"body_html":"",
"vendor":"Bare Blends",
"product_type":"coffee blend",
"created_at":"2021-03-08T15:46:19+11:00",
"handle":"organic-toast-golden",
"updated_at":"2021-04-07T10:31:07+10:00",
"published_at":null,
"template_suffix":"",
"published_scope":"web",
"tags":"",
"admin_graphql_api_id":"gid://shopify/Product/6562914664611",
"variants":["…"],
"options":["…"],
"images":["…"],
"image":{"…"}
}
}Prismic has built-in integration with Shopify.
Create or log in to your Shopify account.
On the Admin page, go to Settings in the left navigation menu at the bottom. Select App and sales channels. Once there, click on Develop apps and then Allow custom app development.
Create an app and give it a name. Then go to API credentials > Configure Admin API scopes. Scroll until you find Product listings and click the checkbox for read_product_listings. Then, immediately below in Products, check the checkbox for read_products. Save and Click on Install app.
Now the API credentials are available to use for the next step.
In your repository, navigate to Settings > Integration Fields.
Select Shopify, and fill in the settings. You'll copy and paste the API key, password, and Shared Secret from your Shopify App settings.
Catalog name
required
A name for your Shopify catalog. This will be shown in the custom type builder.
Description
required
A description for your Shopify catalog. This will be shown in the custom type builder.
Endpoint
required
The API endpoint of your Shopify catalog with the following format: your-store.myshopify.com. Without HTTPS.
API key
required
The API key of your Shopify catalog.
Password
required
The Admin API access token of your Shopify catalog. Please note that this access token can only be opened once.
Shared Secret
The API secret key of your Shopify catalog.
Click on Save. The Integration Field will automatically begin to crawl and sync your Shopify catalog.
Add the Integration Field to a custom type.
Integration Fields with Slice Machine has been a highly requested feature request. The field isn't yet available in the Slice Machine Interface, but that doesn't mean you can't use it already.
Here's the temporary solution to add Integration fields to your documents:
1. First, ensure Integration Fields are enabled in your repository. If you don't have it, reach out to us so we can activate it for you. Then, add your catalog.
2. Open your project in your favorite code editor. Run Slice Machine
3. Find the `index.json` of the Custom Type or the `model.json` of your Slice and add the integration Field:
"api_id": {
"type": "IntegrationFields",
"config": {
"catalog": "my-repository--your_store",
"label": "Here goes the field name",
"placeholder": "This is the field placeholder..."
}
}6. Add a new name for the `api_id` of the field and modify the `catalog` value to match repository settings. For example, if your repository is called **lorem** and your Integration catalog is called **my store**, the value will be: `"catalog": "lorem--my_store"`.
7. Save your JSON file, Push your changes to Prismic, and you're done. Now you can visualize and use your integration field in the documents!
Slice Machine Placeholder
You'll see, Field type "Integration Fields" not supported, this is just a placeholder until the field can be edited natively in the Slice Machine UI.
Can't find what you're looking for?
Need technical Support? Spot an error in the documentation? Get in touch with us on our Community Forum.