Publication Feed Specification

Tjek Publication Feed Specification

This document describes the JSON feed format used for ingesting publications and offers into the Tjek platform. The publication feed is used to automatically create publications in our system. Clients must follow this specification to ensure compatibility with our system for processing and displaying publications accurately.

Overview

The publication feed must be formatted as a JSON file containing an array of publication objects. Each publication may either point to a paged PDF file or define Incito-compatible offer data inline.

All URLs must use HTTPS and all date/time values must follow the ISO 8601 format.

✨ Root Object (Publication)

Required Fields

id (string): Unique ID of the publication. Example: "2346"
is_available_in_all_locations (boolean): True if available in all locations.

Optional Fields

name (string or null): Publication title. Example: "City Name Week 15"
validity (array of two ISO-8601 date-time strings or null): Validity window.
- Example: ["2024-04-07T22:00:00.000Z", "2024-04-14T22:00:00.000Z"]
visible_from (string or null): Visibility start. Example: "2024-04-05T22:00:00.000Z"
cover_image (string or null): URL to cover image (if no cover image is specified, the first page of the publication will be used by default).
paged_pdf_url (string or null): Link to PDF version.
incito_template_id (string or null): For Incito-based templates.
offers (array of Offer objects): Inline offer list (only for Incito publications).
locations (array): Array of { id: string } location objects.

💰 Offer Object (For Incito Publications Only)

Required Fields

id (string): Unique identifier for the offer.
name (string, max 200 chars): Offer title.

Optional Fields

description (string or null): Description.
tags (array of strings): Section/category tags.
currency_code (string or null): ISO 3-letter currency code.

Price Fields

price (number or null): Standard price.
from_price (number or null): Starting price in a range.
preprice (number or null): Before-discount price.
savings (number or null): Absolute discount.
relative_savings (number or null): Percent discount (e.g. 20).
membership_price (number or null): Member price.
membership_from_price (number or null): Starting member price in range.
membership_savings (number or null): Absolute member discount.
membership_relative_savings (number or null): Percent member discount.
app_price (number or null): App-only price.
coupon_price, coupon_savings, coupon_relative_savings: Coupon-based pricing.

Quantity & Unit Constraints

piece_count_from, piece_count_to: Defines a range of item counts in the offer when products vary by quantity. For example, if the offer includes 15-packs of beer and 18-packs of soda, piece_count_from would be 15 and piece_count_to would be 18. If all items are the same quantity, set both to the same value.
piece_count_min, piece_count_max: Used when the offer requires customers to purchase a minimum or maximum number of items to receive the offer price. E.g., if you need to buy at least 2 packs of soda (each 6x33cl) to get the discount, set piece_count_min to 2. If the deal is limited to a maximum of 6 items per customer, set piece_count_max to 6.
piece_count_get, piece_count_get_for: Used for “multi-buy” promotions. For example, a “3 for the price of 2” deal would be represented as piece_count_get: 3 and piece_count_get_for: 2. Important: piece_count_get_for represents a quantity, not a price.
unit_size_from, unit_size_to: Similar to piece count, this represents unit volume or weight. For example, if the offer includes 0.5L beer bottles and 1.5L cola bottles, set unit_size_from: 0.5 and unit_size_to: 1.5. If the unit size is fixed, both values should be identical.
unit_symbol: The unit type for the unit size fields, e.g., liter, piece, gram, kilogram, milliliter, etc. Must be chosen from the predefined set of supported unit symbols.

Dates

validity (array of two ISO-8601 date-time strings or null): Active range.
visible_from (string or null): Visibility date.

Media & Links

webshop_link (string URI or null): Product URL.
image (string or null): Offer image.
image_pack (array of strings): Additional images.
background_image (string or null): Background image.

Labels & Metadata

priority (number or null): Lower = higher priority.
group_label_1/2/3: Used to group offers into sections (e.g., "Televisions" or page number "3").
comment_label_1/2/3, color_label_1/2/3, pricing_label_1/2/3, custom_label_1/2/3: Optional labels.
legal_info (string or null): Legal disclaimer text.
collapse_id (string or null): Grouping key used to collapse offers into a carousel or similar component in the frontend.

Logos

logos (array): Each has image, and optionally name and type (e.g., energy_class).

📝 Product Object (inside Offer)

Required

id (string): Product ID.
gtin (string or null): Barcode.
name (string): Product name.

Optional

description (string or null)
price, savings, relative_savings (number or null)
brand: { id: string or null, name: string or null }
energy_class, energy_scale (string or null)
image (string or null)
webshop_link (string or null)
custom_label_1/2/3 (string or null)

🌍 Publication Availability

is_available_in_all_locations (boolean): True if global. If false:
locations (array): List of locations the publication applies to.
- Example: [ { "id": "MSCN123" } ]

🧪 Example: PDF-based Publication

{
  "id": "2346",
  "name": "My Store City Name",
  "validity": [
    "2024-04-07T22:00:00.000Z",
    "2024-04-14T22:00:00.000Z"
  ],
  "visible_from": "2024-04-05T22:00:00.000Z",
  "cover_image": null,
  "paged_pdf_url": "https://example.com/campaign123.pdf",
  "offers": [],
  "is_available_in_all_locations": false,
  "locations": [
    { "id": "MSCN123" }
  ]
}

🧪 Example: Incito-based Publication with Offers

{
  "id": "2346",
  "name": "My Store City Name",
  "validity": [
    "2024-04-07T22:00:00.000Z",
    "2024-04-14T22:00:00.000Z"
  ],
  "visible_from": "2024-04-05T22:00:00.000Z",
  "cover_image": "https://example.com/cover_image.jpg",
  "offers": [
    {
      "id": "2500249946",
      "name": "Läsk 6-pack",
      "description": "Pepsi, Zingo, 6x33cl, flera sorter, jfr-pris 15,15/l +pant",
      "tags": [
        "4"
      ],
      "currency_code": "SEK",
      "membership_price": 30,
      "membership_savings": 17.95,
      "piece_count_from": 6,
      "piece_count_to": 6,
      "unit_size_from": 33,
      "unit_size_to": 33,
      "unit_symbol": "centiliter",
      "image": "https://example.com/image1.jpg",
      "image_pack": [
        "https://example.com/image1.jpg",
        "https://example.com/image2.jpg"
      ],
      "custom_label_1": "st",
      "custom_label_2": "Pepsi, Zingo",
      "group_label_1": "4",
      "comment_label_2": "+Pant",
      "comment_label_3": "1",
      "legal_info": "Lägsta 30-dagarspris 34,95/st",
      "products": [
        {
          "id": "7310072000635",
          "gtin": "7310072000635",
          "name": "Läsk 6-pack",
          "brand": {
            "id": "Pepsi",
            "name": "Pepsi"
          }
        },
        {
          "id": "7310072000642",
          "gtin": "7310072000642",
          "name": "Zingo Cola 6-pack",
          "brand": {
            "id": "Zingo",
            "name": "Zingo"
          }
        }
      ]
    }
  ],
  "is_available_in_all_locations": false,
  "locations": [
    { "id": "MSCN123" }
  ]
}

📌 Notes

All date-time values must be in ISO 8601 format.
All URLs must be HTTPS.
Use from_price when product pricing varies.
Use membership_*, coupon_* fields for tailored pricing.
Grouping and labeling fields support flexible frontend presentation.

Please contact our integration support team for additional guidance or clarification.