Integration

This article explains how to integrate with third party services using Prismic's integration field.

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

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

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. 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"
      }
    }
  ]
}

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.

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.

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:

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

To delete one or more items, use /deleteItems:

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

To reset the entire catalog, use /reset:

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.

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

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:

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

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

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.
Open your project in your favorite code editor. Run Slice Machine
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..."
   }
}

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