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:

  1. Pull data from a custom read API
  2. Push data from a custom write API
  3. Automatically sync with a Shopify catalog

Pull data into Prismic from a custom API

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)

A basic authorization access token for your Custom API catalog. The access token is suffixed with : and then base64 encoded.

Click Save. The Integration Field will automatically begin to crawl and sync your Custom API.

Custom API format

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.

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.

Here is an example of what your custom API should look like:

Copy
{
  "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"
      }
    }
  ]
}

Pagination

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.

Use your Integration Field data

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.


Push data to Prismic from a custom API

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.

Configure the write API

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.

Get your API endpoint

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.

Copy
https://if-api.prismic.io/if/write/your-repo-name--my_catalog

Create a POST request

By 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:

Copy
https://if-api.prismic.io/if/write/your-repo-name--my_catalog

To delete one or more items, use /deleteItems:

Copy
https://if-api.prismic.io/if/write/your-repo-name--my_catalog/deleteItems

To reset the entire catalog, use /reset:

Copy
https://if-api.prismic.io/if/write/your-repo-name--my_catalog/reset

Add a body to the request

The 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.

Item format

Items POSTed to the write API should follow the following format. For more information on these properties, see "Custom API format," above.

Copy
{
  "id": "my_item_id",
  "title": "Item Title",
  "description" : "Description of the item.",
  "image_url" : "http://...",
  "last_update" : 1509364426938,
  "blob": {
    "sku": "827",
    "title": "First Item",
    "description": "Description of first item...",
    "image_url": "https://..."
  }
}

Add an authorization token

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.

Putting it all together

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:

Copy
// 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": {
      "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": {
      "lorem": "ipsum",
      "dolor": "sit"
    }
  }
]

To delete:

Copy
// 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:

Copy
// 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: 0

Use your integration data

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.

This is the shape of the data from the Prismic API:

Copy
// 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":{"…"}
  }
}

Sync with a Shopify catalog

Prismic has built-in integration with Shopify.

Get your credentials from 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.

Create a Shopify Integration Field

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 in Slice Machine

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:

Copy
"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.


Was this article helpful?
Not really
Yes, Thanks

Can't find what you're looking for? Spot an error in the documentation? Get in touch with us on our Community Forum or using the feedback form above.