Centra for DatoCMS

Select Centra products, exact product variants, and buyable SKU/size items directly from DatoCMS records.

Centra remains the source of truth for catalog data. The plugin stores only stable reference IDs in DatoCMS and loads names, media, prices, availability, stock, SKU values, and other product details live from Centra.

Features

• Product picker restricted to each display's primary variant
• Exact product-variant picker
• SKU/size picker backed by Centra Item IDs
• Single and ordered multiple selections
• Product-first search with SKU, size, product-number, variant, and GTIN discovery
• Live product cards with unresolved and availability states
• Light and dark mode support through DatoCMS UI tokens

Installation

Install Centra from the DatoCMS Marketplace, or install the npm package manually:

1
datocms-plugin-centra

The plugin does not request DatoCMS API permissions.

Configuration

Open the plugin settings and enter:

1. Storefront API URL — the complete Centra no-session GraphQL URL.
2. API token — a read-only token for that endpoint.

Select Save and connect. The plugin validates the credentials by loading one catalog page before saving. The same Centra connection is used in every DatoCMS environment.

Token visibility

The bearer token is stored directly in DatoCMS plugin parameters and is used by the browser through the DatoCMS CORS relay. Masking the input prevents casual disclosure on the settings screen, but it does not turn the token into a server-side secret. Use a dedicated read-only no-session catalog token and restrict access to the DatoCMS project appropriately.

The plugin never uses a Centra shared secret, AMS credentials, or a customer-hosted proxy.

Adding a Centra field

1. Create a DatoCMS JSON field.
2. In the field's Presentation settings, choose Centra.
3. Choose the reference kind:
   • Product (primary variant) — browse one primary DisplayItem per product display.
   • Exact variant — browse every DisplayItem/product variant.
   • SKU / size — choose a nested Centra Item.
4. Choose Single or Multiple cardinality.

Changing a populated field to an incompatible kind or changing a multi-value field with several references to single cardinality does not discard or reinterpret data. The editor asks for an explicit clear or replacement.

Editor workflow

Choose what editors can select

Configure the JSON field for products, exact product variants, or individual SKU/size items.

Search and select exact variants

Search the live Centra catalog, compare image-backed variants, and stage one or more selections before applying them.

Select a specific SKU or size

Expand a product variant and select the exact Centra Item. Repeated SKU strings remain separate rows with their own size and Item ID.

Work with hydrated references

Saved references are rendered with current Centra images, variant details, and availability while the JSON value keeps only stable IDs.

Stored value contract

The JSON field contains a versioned document. null is the only empty value.

One product

1
{
2
  "version": 1,
3
  "kind": "primaryProduct",
4
  "references": [{ "displayItemId": 2752 }]
5
}

Ordered product variants

1
{
2
  "version": 1,
3
  "kind": "variant",
4
  "references": [
5
    { "displayItemId": 2752 },
6
    { "displayItemId": 2810 }
7
  ]
8
}

One SKU/size item

1
{
2
  "version": 1,
3
  "kind": "item",
4
  "references": [
5
    {
6
      "displayItemId": 2752,
7
      "itemId": "opaque-centra-item-id"
8
    }
9
  ]
10
}

The plugin intentionally does not store product names, URIs, images, prices, stock, SKU strings, GTINs, or full product snapshots. Those values can change in Centra and are loaded live.

Resolving references in a frontend

Fetch DisplayItems by the stored numeric IDs. For item references, locate the exact nested item using the stored opaque itemId.

1
query ResolveCentraReferences(
2
  $displayItemIds: [Int!]
3
  $market: [Int!]
4
  $pricelist: [Int!]
5
  $languageCode: [String!]
6
) {
7
  displayItems(
8
    where: { id: $displayItemIds }
9
    limit: 100
10
    market: $market
11
    pricelist: $pricelist
12
    languageCode: $languageCode
13
  ) {
14
    list {
15
      id
16
      name
17
      productNumber
18
      isPrimaryVariant
19
      available
20
      hasStock
21
      productVariant {
22
        id
23
        name
24
        number
25
      }
26
      items {
27
        id
28
        name
29
        sku
30
        GTIN
31
        preorder
32
        stock {
33
          available
34
        }
35
      }
36
    }
37
  }
38
}

Reorder the response using the stored references array. Keep a placeholder for missing DisplayItems or Items instead of silently dropping them.

SKU behavior

Centra exposes buyable sizes as Item objects nested below a DisplayItem. A SKU string is display metadata, not a safe identity: stores can contain repeated SKU values, including repeated values within one DisplayItem.

The plugin therefore stores this pair:

1
type CentraItemReference = {
2
  displayItemId: number;
3
  itemId: string;
4
};

SKU search first asks Centra for matching DisplayItems, then ranks exact nested SKU and GTIN matches in the returned products. Every duplicate match remains selectable. The plugin never scans the entire catalog in the browser.

Availability and stock

Market, pricelist, language, and Centra allocation rules can change what is visible or available. Product and item stock shown in DatoCMS is the current Storefront API response, not a guarantee that checkout will succeed later.

Missing or inactive references remain visible in the field editor with their stored IDs so editors can remove or replace them deliberately.

Troubleshooting

Connection test fails

• Confirm the URL is the complete no-session GraphQL endpoint.
• Confirm the bearer token belongs to the same Storefront API plugin.
• Avoid using the AMS URL as the API endpoint.
• Inspect the HTTP or GraphQL error shown by the plugin; credentials are redacted from messages.

Prices or translations differ from the Centra backoffice

The plugin uses the market, pricelist, and language defaults exposed by the configured no-session endpoint. Adjust those defaults in Centra if the catalog response is not the one editors should browse.

A primary product now shows a warning

The selected DisplayItem is pinned. If Centra later assigns another primary variant, the plugin warns and leaves the existing reference untouched. Replace it explicitly if the content should follow the new primary choice.

Development

1
npm install
2
npm run dev

Then install a private plugin in DatoCMS with http://localhost:5173/ as its entry point.

Run all local checks with:

1
npm run lint
2
npm test
3
npm run build

Centra documentation

• Storefront API architecture
• Catalog product information
• DisplayItem API type
• Item API type