A custom integration is useful if Frontstack doesn’t provide an integration for your source system or if you want to push your data to Frontstack directly.

​
Basic Configuration

The data feed of a custom integration requires just one configuration: the name of the payload field that contains the Source ID of the record.

The Source ID identifies the record in Frontstack and optimally uses the same field your source system also uses to identify records (e.g. a UUID, SKU, product number, internal ID …). Any payload without a Source ID will not be processed.

Custom integrations use the Ingest API to sync data with Frontstack. The examples below use a field called id as the Source ID.

​
General record structure

We established the following conventions so your integration can work with context-specific data (as defined in the project configuration) properly:

​
Channel-specific data

With @channel and the key of your integration’s channels, you can define data that differs per channel. For example, you can provide different description texts for your B2C and B2B customers by using two channels.

{
  "id": 1,
  "productNumber": "my-product-1234",
  "name": "My Product",
  "categoryIds": [14, 23, 30],
  "@channel": {
    "b2c": {
      "technicalProductName": "My Product (Revision 241)"
    },
    "b2b": {
      "technicalProductName": "AA-241-1234"
    }
  }
}

In this example, you see two different technical product names for the same product. One for B2C and one for B2B. The value for name however would be the same for both channels.

​
Translation-specific data

In a typical project, you will have different translations of your content for different languages.

Use @translation and the key of your translations to define that content.

{
  "id": 1,
  "productNumber": "my-product-1234",
  "categoryIds": [14, 23, 30],
  "@translation":{
    "de-DE":{
      "name": "Produkt 1",
      "description":"Ein Text"
    },
    "en-GB":{
      "name": "Product 1",
      "description":"Some Text"
    }
  }
}

In this example, you see two different names and descriptions for the same product. One for German and one for British English.

​
Currency-specific data

If you’re targeting different markets, you may have prices for different currencies.

Use @currency and the ISO key of your currencies (e.g. EUR or USD) to define your prices.

{
  "id": 1,
  "productNumber": "my-product-1234",
  "categoryIds": [14, 23, 30],
  "@currency": {
    "EUR": {
      "productPrice": {
        "gross": 19.99,
        "net": 16.79,
        "currency": "EUR",
        "precision": 2
      }
    },
    "USD": {
      "productPrice": {
        "gross": 19.99,
        "net": 19.99,
        "currency": "USD",
        "precision": 2
      }
    }
  }
}

In this example, you see two different prices for the same product. One price for EUR and one for USD.

​
Combination

You can combine all structures to further customize your data. Keep in mind, that we resolve your record in the order of @channel > @currency > @translation.

​
Product variants

Products in a custom integration can have a parent-child structure. This allows for a main product with variants (like color or size) or a standalone basic product.

Basic products appear as both products and variants. Main products act as containers for their variants, appearing in product blocks, while variants appear in variant blocks. See block storage configuration for more details.

To associate a variant with its parent product, include the parent Source ID in your payload. Set the field name in the Custom Integration configuration.

Since we have to assume a non-deterministic import order of your data (variants can be imported before their main product), we need to establish a convention for distinguishing between the following product types based on their structure:

  • Basic product (no variants)
  • Main product (has variants)
  • Variant product (has a parent product)

​
Basic product

A basic product is a product that does not have any variants. Provide the parent source ID identical to your source ID.

{
  "id": "my-product-123",
  "parentId": "my-product-123",
}

​
Main product

A main product is a product that has variants. Provide an empty parent source ID.

{
  "id": "my-product-456",
  "parentId": ""
}

​
Variant product

A variant product is a product that has a parent product. Provide the parent source ID.

{
  "id": "my-product-123-red-small",
  "parentId": "my-product-123"
}