Integration

The integration field allows you to integrate third-party data into your repository, such as from e-commerce catalogs or custom APIs.

Add an integration field to a content model

Unlike other field types, integration fields cannot be added through Slice Machine. Instead, it must be added by editing your content model’s JSON file.

• Create a catalog

  See Create an integration catalog for instructions.

• Open your content model’s JSON file

  In your Prismic project, open the slice, page type, or custom type JSON file you want to modify. The file location depends on the content type:

  • Slices: Typically in src/slices/<name>/model.json.
  • Page types: customtypes/<name>/index.json.
  • Custom types: customtypes/<name>/index.json.
• Add an integration field

  Add a property to the content model’s fields like the following. This example adds a product field to a “Featured Product” slice.

  The property name (its API ID) determines the property name in the Document API. Use a short, snake-cased name.

  The label property determines the label shown to content writers in the Page Builder. Use an easily understood name.

  The catalog property determines the data set connected to the integration field. For example, if your repository is called lorem and your catalog is called “my store,” the value will be: "lorem--my_store".

  src/slices/FeaturedProduct/model.json

  Copy

  {
    "id": "featured_product",
    "type": "SharedSlice",
    "name": "FeaturedProduct",
    "description": "FeaturedProduct",
    "variations": [
      {
        // ...
        "primary": {
          "product": { 
            "type": "IntegrationFields", 
            "config": { 
              "catalog": "example-prismic-repository--example_store", 
              "label": "Product"
            } 
          }, 
        },
        // ...
      }
    ]
  }

Create an integration catalog

There are three ways you can integrate a third-party data source using an integration field:

• Pull data from an API.
• Push data to Prismic.
• Sync products from a Shopify store.

Pull data from an API

Prismic can pull data from your API periodically. Your API should return data in a specific format that the Prismic API understands.

• Create an API endpoint

  Your API endpoint should be accessible via the internet and return JSON in the following format.

  type Payload = {
    results_size: number;
    results: Array<{
      id: string;
      title: string;
      description: string;
      blob: object;
      image_url?: string;
      last_update?: number;
    }>;
  };

  Property	Description	Default
  results_size	number The total number of items to pull.
  results	object[] An array of up to 50 items.

  If you have more than 50 items, results_size should be the total number of items. Prismic will call your endpoint multiple times, including a page=<number> URL parameter. Fill results with up to 50 items for each page.

  Item objects should follow the following format:

  Property	Description	Default
  id	string The item’s unique ID. This property is not exposed through the Document API. To expose it, include it in the blob property.
  title	string The item’s title shown in the Page Builder.
  description	string The item’s description shown in the Page Builder.
  blob	object The item’s data. This is what appears in the Document API’s response.
  image_urloptional	string The URL of the item’s image thumbnail shown in the Page Builder.
  last_updateoptional	number The item’s last updated timestamp in Unix time (e.g. 1509364426938). Items are sorted from most recently updated to least recently updated in the Page Builder.

• Open your repository settings

  Navigate to your Prismic repository and go to Settings > Integration Fields.

  You must be the repository owner or have admin rights to access the Integration Fields page.

• Create a Custom API catalog

  Select Pull data from my endpoint and fill out the fields.

  The Catalog Name determines the API ID and the name displayed in your repository settings.

  The Description is shown in your repository settings. Use a short description that will help organize your catalogs.

  The Endpoint determines URL used to pull your data. The URL should output JSON in the specific format that the Prismic API understands.

  The Access token is an optional way to authenticate your API using Basic HTTP authentication. The access token, along with a trailing colon (:), are sent encoded in an Authorization header when Prismic requests your API endpoint.

  Click Create my integration field to save your catalog.

• Pull your data

  Once the catalog is created, Prismic will begin its initial pull from your API and will periodically re-pull.

Push data to Prismic

You can push data to Prismic using a dedicated API endpoint. The endpoint allows for adding, updating, and deleting data.

• Open your repository settings

  Navigate to your Prismic repository and go to Settings > Integration Fields.

  You must be the repository owner or have admin rights to access the Integration Fields page.

• Create a Custom API catalog

  Select Push data to Prismic and fill out the fields.

  The Catalog Name determines the API ID and the name displayed in your repository settings.

  The Description is shown in your repository settings. Use a short description that will help organize your catalogs.

  Click Create my integration field to save your catalog.

• Get your API endpoint and token

  In your repository’s Integration Fields settings, find your catalog. Click the pencil icon to view your catalog settings.

  Your API endpoint is shown under the “Endpoint” field. You will use this endpoint to manage your data.

  Your API token is shown in the “Tokens” section. You must include a token when sending API requests. You can create and revoke tokens from this section.

Once you have your API endpoint and token, you can push, update, and delete data.

Authorize requests

All requests to your API endpoint must include an Authorization header containing your API token:

Authorization: Bearer <your-api-token>

Push items

Send a POST request to your API endpoint containing your items. The request body should contain an array of items in JSON format:

type Payload = Array<{
  id: string;
  title: string;
  description: string;
  blob: object;
  image_url?: string;
  last_update?: number;
}>;

Update items

Send a POST request to your API endpoint containing your updated items. The request body should follow the same format as pushing items.

Delete items

Send a POST request to the /deleteItems path of your API endpoint. For example:

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

The request body should contain an array of item IDs to delete in JSON format.

Delete all items

Send a POST request to the /reset path of your API endpoint. For example:

https://if-api.prismic.io/if/write/example-prismic-repo--my_catalog/reset

The request body should be empty.

Sync products from a Shopify store

Prismic can automatically sync products from a Shopify store.

• Get your Shopify API credentials

  Follow the Create and install a custom app instructions from the Shopify documentation.

  Once your app is created and installed, follow the Get the API credentials for a custom app instructions.

  Hold on to your API credentials; you will need them when you register your Shopify store as a catalog.

• Open your repository settings

  Navigate to your Prismic repository and go to Settings > Integration Fields.

  You must be the repository owner or have admin rights to access the Integration Fields page.

• Create a Shopify catalog

  Select Shopify and fill out the fields.

  The Catalog Name determines the name displayed in your repository settings.

  The Description is shown in your repository settings. Use a short description that will help organize your catalogs.

  The Endpoint should be your Shopify URL. For example: example-store.myshopify.com.

  The API key should be your Shopify API key.

  The Password should be your Shopify Admin API access token. This token can only be viewed once on Shopify.

  The Shared Secret should be your Shopify secret key.

  Click Save to save your catalog.

• Pull your data

  Once the catalog is created, Prismic will begin its initial sync from your Shopify store and will periodically re-sync.

Use integration fields

The integration field’s data can be read from the field’s object.

This example uses an integration field named featured_product.

<h1>Featured product: {slice.primary.featured_product.title}</h1>

Tips

• Use isFilled.integrationField() to check if an integration field has a value

  import { isFilled } from "@prismicio/client";
  
  if (isFilled.integrationField(slice.primary.my_integration_field)) {
    // Do something if `my_integration_field` has a value.
  }

API response

Here is what an integration field looks like from the Document API:

{
  "example_integration": {
    "id": 6562914664611,
    "handle": "organic-toast-golden",
    "title": "Organic coffee blend",
    "vendor": "Bare Blends"
  }
}

The field’s content is determined by the item’s blob property or Shopify product, depending on the type of catalog.