Manual: Retrieving GPSR related Contact Details

By
Manual Retrieving GPSR related Contact Details

Version 1.0

This manual provides essential guidance on the contact details required under Regulation 2023/988 (EN – EUR-Lex), specifically Articles 40 and 42. It outlines the necessary information businesses must provide to ensure compliance with these regulatory requirements. By following the details in this manual, companies can ensure transparency, accessibility, and adherence to legal obligations.

Contact Details in Icecat Data Files

Icecat provides structured contact details across multiple data formats. This information is available in the following locations:

REFs Files

Contact details are included in reference files, which serve as a centralized data source for brand organizations:

  • BrandOrganizations.xml.gz – XML format for structured data processing.
  • BrandOrganizations.csv.gz – CSV format for easy tabular data handling.

Product Data-Sheets

Brand contact details are also integrated directly into product data sheets:

  • XML Format: new <BrandOrganizations> section added.
  • JSON Format: new "BrandOrganizations" block introduced.

These structured data enhancements allow users to efficiently access and utilize brand organization details for improved communication, support, and business operations.

GPSR Regulation Considerations

  • Icecat’s terminology:
    • Brand Owner = Default Manufacturer
    • Licensee = Manufacturer (if present, check alongside Brand Owner)
    • Representative = The European Union Manufacturer Representative
  • If the Manufacturer (Brand Owner or Licensee) is outside the EU, both the Manufacturer and Representative must be informed.

Brand Responsibility

  • Icecat provides brand-supplied data. It is the brand’s responsibility to update and maintain accurate contact details.

REFs file “BrandOrganizations.xml.gz”

Icecat provides the BrandOrganizations.xml.gz REFs file for structured brand and organization relationships. We recommend utilizing this file if you have the opportunity to build Brand-Organization logic in your system. This approach helps avoid duplicating the same contact details for each product, keeping the data more compact and efficient.

Accessing the BrandOrganizations.xml.gz file:

File Structure:

<?xml version="1.0" encoding="UTF-8"?>
<BrandOrganizations>
    <Brand ID="1" Updated="2025-01-01 00:00:00">
        <BrandOwner>
            <Organization ID="000000000-0000-0000-0000-0000000000000" Name="Organization Name 1" CountryCode="US" State="Oregon" City="Beaverton" Street="One Bowerman Drive" HouseNumber="1" ZIP="97005">
                <URLs>
                    <URL>https://website1.com</URL>
                    <URL>https://website2.com</URL>
                </URLs>
                <Emails>
                    <Email>email1@domain.com</Email>
                    <Email>email2@domain.com</Email>
                </Emails>
            </Organization>
        </BrandOwner>
        <Licensees>
            <Licensee ID="123456789">
                <Organization ID="000000000-0000-0000-0000-0000000000000" Name="Organization Name 2" CountryCode="US" State="California" City="Los Angeles" Street="Main Street" HouseNumber="100" ZIP="90001">
                    <URLs>
                        <URL>https://website3.com</URL>
                    </URLs>
                    <Emails>
                        <Email>email3@domain.com</Email>
                        <Email>email4@domain.com</Email>
                    </Emails>
                </Organization>
                <Scopes>
                    <Categories>
                        <Category ID="101"/>
                        <Category ID="102"/>
                    </Categories>
                </Scopes>
            </Licensee>
        </Licensees>
        <Representatives>
            <Representative ID="123456791">
                <Organization ID="000000000-0000-0000-0000-0000000000000" Name="Organization Name 3" CountryCode="UK" City="London" Street="Baker Street" HouseNumber="221B" ZIP="NW1 6XE">
                    <URLs>
                        <URL>https://website4.com</URL>
                    </URLs>
                    <Emails>
                        <Email>email5@domain.com</Email>
                        <Email>email6@domain.com</Email>
                    </Emails>
                </Organization>
                <Scopes>
                    <Categories>
                        <Category ID="201"/>
                    </Categories>
                </Scopes>
            </Representative>
        </Representatives>
    </Brand>
</BrandOrganizations>

Elements Description:

  • <BrandOrganizations>: The root element containing brand and organization relations.

Brand Element:

  • : Represents a brand and its associated organizations.
    • ID: Brand identifier (found in REFs file SuppliersList.xml.gz).
    • Updated: Timestamp in YYYY-MM-DD HH:MM:SS format indicating the last update.

Brand Relations:

  • <BrandOwner>: The primary manufacturer for all products of the brand. Each brand has only one owner.
  • : Organizations producing products for the brand (can have multiple licenses).
    • Licensee ID: Unique connection identifier between Brand and Organization.
  • : Legal entities representing the brand concerning product sustainability.
    • Representative ID: Unique connection identifier between Brand and Organization.

Organization Details:

  • ID: Unique UUID identifier of the organization.
  • Name: Organization’s official name.
  • CountryCode: Alpha-2 country code.
  • State: Applicable only for certain countries (e.g., US).
  • City, Street, HouseNumber, ZIP: Physical address details.
  • URLs: Collection of organization websites.
  • Emails: Collection of contact emails (optional).

Scopes (for Licensees & Representatives):

  • Categories: Defines the scope of product categories for an organization.
  • Category ID: Corresponds to a product category from REFs file CategoriesList.xml.gz.

Implementation Guidelines

Index for Updates

  • Track the Updated attribute in <Brand> to detect changes in relationships, organization data, or scopes.
  • The file updates every 6 hours starting from midnight. Use these intervals for synchronization.

Brand-Organization Attachment to Products

  • For each product, check the Organization Scope Categories for each relation type:
    • Brand Owner (scope to be added soon): The default manufacturer. Attach the Brand Owner organization to all brand products.
    • Licensee: If present, Licensee organizations manufacture specific products.
      • If no Licensee organizations have a scope category, attach all Licensees to the product.
      • If some Licensees have scope categories while others do not:
        • Attach the Licensees matching the product category.
        • If no matches are found, attach all Licensees without scope categories.
      • Consider category hierarchy: Organizations may have upper-level categories, while products always have a final-level category.
    • Representative: Represents the brand in sustainability matters.
      • If no Representative organizations have a scope category, attach all Representatives to the product.
      • If some Representatives have scope categories while others do not:
        • Attach Representatives matching the product category.
        • If no matches are found, attach all Representatives without scope categories.

REFs file “BrandOrganizations.csv.gz”

Icecat provides Brand Organization information in the BrandOrganizations.csv.gz file. This file is recommended for users who work with Product CSV data, as Brand Organization details are not included in standard CSV product exports.

The BrandOrganizations.csv.gz file is available for both Open Icecat and Full Icecat users:

The BrandOrganizations.csv.gz file contains the following columns:

IDUnique connection identifier between Brand and Organization (for Licensee and Representative relation type only)
OrganizationIDUnique UUID identifier of the organization
BrandIDBrand identifier (found in CSV repository – suppliers.txt.gz)
OrganizationTypeBrandOwner, Licensee, Representative
OrganizationNameOrganization’s official name
CountryCodeAlpha-2 country code
StateApplicable only for certain countries (e.g., US)
CityCity where the organization is located
StreetStreet where the organization is located.
HouseNumberHouse or building number
ZIPPostal code
URLsList of official organization websites, separated by a pipeline “|”
EmailsList of contact email addresses, separated by a pipeline “|”
CategoriesList of category IDs associated with the organizations, separated by a pipeline “|”
UpdatedTimestamp in YYYY-MM-DD HH:MM:SS format indicating the last update.

Implementation Guidelines

Index for Updates

  • Track the Updated column for each row to detect changes in relationships, organization data, or scopes.
  • The file updates every 6 hours starting from midnight. Use these intervals for synchronization.

Brand-Organization Attachment to Products

  1. Identify all rows with a common BrandID.
  2. Group organizations by OrganizationType for each BrandID (Brand Owner, Licensee, Representative).
  3. Check the organization Categories for each organization type separately.

Brand Owner

  • Scope definition to be added soon.
  • The default manufacturer of the brand.
  • Attach the Brand Owner organization to all brand products.

Licensee

  • If present, Licensee organizations manufacture specific products.
  • If no Licensee organizations have a category, attach all Licensees to the product.
  • If some Licensees have scope categories while others do not, attach Licensees matching the product category. If no matches are found, attach all Licensees without scope categories.

Representative

  • Represents the brand in sustainability matters.
  • If no Representative organizations have a scope category, attach all Representatives to the product.
  • If some Representatives have scope categories while others do not, attach Representatives matching the product category. If no matches are found, attach all Representatives without scope categories.
  1. Consider category hierarchy:
    • Organizations may have upper-level categories.
    • Products always have a final-level category.

Product XML new <BrandOrganizations> section

Icecat provides the option to include Brand Organization information in product XML files. This feature is recommended only if you do not have the capability to build the logic for attaching organization contact details to products using the REFs file (BrandOrganizations.xml.gz).

Since the BrandOrganizations section is not included in the product XML by default, you must contact your Icecat account manager to enable this feature for your product XML exports.

New section structure:

<?xml version="1.0" encoding="UTF-8"?>
<ICECAT-interface ...>
    <Product ...>
        ...
    <BrandOrganizations>
        <BrandOwner>
            <Organization ID="000000000-0000-0000-0000-0000000000000" Name="Organization Name 1" CountryCode="US" State="Oregon" City="Beaverton" Street="One Bowerman Drive" HouseNumber="1" ZIP="97005">
                <URLs>
                    <URL>https://website1.com</URL>
                    <URL>https://website2.com</URL>
                </URLs>
                <Emails>
                    <Email>email1@domain.com</Email>
                    <Email>email2@domain.com</Email>
                </Emails>
            </Organization>
        </BrandOwner>
        <Licensees>
            <Licensee ID="123456790">
                <Organization ID="000000000-0000-0000-0000-0000000000000" Name="Organization Name 2" CountryCode="US" State="California" City="Los Angeles" Street="Main Street" HouseNumber="100" ZIP="90001">
                    <URLs>
                        <URL>https://website3.com</URL>
                    </URLs>
                    <Emails>
                        <Email>email3@domain.com</Email>
                        <Email>email4@domain.com</Email>
                    </Emails>
                </Organization>
            </Licensee>
        </Licensees>
        <Representatives>
            <Representative ID="123456791">
                <Organization ID="000000000-0000-0000-0000-0000000000000" Name="Organization Name 3" CountryCode="UK" City="London" Street="Baker Street" HouseNumber="221B" ZIP="NW1 6XE">
                    <URLs>
                        <URL>https://website4.com</URL>
                    </URLs>
                    <Emails>
                        <Email>email5@domain.com</Email>
                        <Email>email6@domain.com</Email>
                    </Emails>
                </Organization>
            </Representative>
        </Representatives>
    </BrandOrganizations>

Element Descriptions

Brand Organizations Section

  • This section contains all the Brand-Organization relationships associated with a product.
  • The structure mirrors that of BrandOrganizations.xml.gz, except that product XML does not contain the Updated attribute.

Brand Relations:

  • <BrandOwner>: The main manufacturer of the brand’s products. A brand has only one owner.
  • <Licensees>: Organizations that manufacture products under the brand. A brand may have multiple licensees.
  • <Representatives>: Legal entities responsible for sustainability-related matters for the brand.

Organization Details:

  • ID: Unique UUID identifier for the organization.
  • Name: Official name of the organization.
  • CountryCode: ISO Alpha-2 country code.
  • State: Only available for applicable countries (e.g., US).
  • City, Street, HouseNumber, ZIP: Address details.
  • URLs: List of official websites (mandatory).
  • Emails: Contact email addresses (optional).

Implementation Considerations

Enabling the Block

  • The BrandOrganizations block is not included in product XML by default. To enable this feature, contact your Icecat account manager.

Product Indexing & Updates

  • The presence of Brand Organization information does not trigger product inclusion in the daily index file. This is because most brands have only one Brand Owner (manufacturer), and occasionally a Representative organization, covering all products within the brand’s scope. Icecat prevents unnecessary data processing for partners who are not interested in this information.

Comparison with REFs File (BrandOrganizations.xml.gz)

  • The REFs file provides a complete and efficient method for managing organization relationships.
  • The product XML block should only be used when integrating REFs logic is not possible in your system.

Product JSON new “BrandOrganizations” block

Icecat provides an option to retrieve Brand Organization information via the product JSON API. This feature is recommended if you do not have the capability to build the logic for attaching organization contact details to products using the REFs file (BrandOrganizations.xml.gz).

To access the new BrandOrganizations block, you need to perform a granular API call with the content=brandorganizations parameter.

API Request Example: https://live.icecat.biz/api?shopname={shop_login}&lang={lang_code}&content=brandorganizations&icecat_id={product_id}&app_key={app_key}

JSON Response Structure:

{
  "BrandOrganizations": {
    "BrandOwner": {
      "Organization": {
        "ID": "00000000-0000-0000-0000-000000000000",
        "Name": "Organization Name 1",
        "CountryCode": "US",
        "State": "Oregon",
        "City": "Beaverton",
        "Street": "One Bowerman Drive",
        "HouseNumber": "1",
        "ZIP": "97005",
        "URLs": [
          "https://website1.com",
          "https://website2.com"
        ],
        "Emails": [
          "email1@domain.com",
          "email2@domain.com"
        ]
      }
    },
    "Licensees": [
      {
        "ID": 1234567891,
        "Organization": {
          "ID": "00000000-0000-0000-0000-000000000001",
          "Name": "Organization Name 2",
          "CountryCode": "US",
          "State": "California",
          "City": "Los Angeles",
          "Street": "Main Street",
          "HouseNumber": "100",
          "ZIP": "90001",
          "URLs": [
            "https://website3.com"
          ],
          "Emails": [
            "email3@domain.com",
            "email4@domain.com"
          ]
        }
      },
      {
        "ID": 1234567892,
        "Organization": {
          "ID": "00000000-0000-0000-0000-000000000002",
          "Name": "Organization Name 3",
          "CountryCode": "US",
          "State": "New York",
          "City": "New York",
          "Street": "Broadway",
          "HouseNumber": "1",
          "ZIP": "10001",
          "URLs": [
            "https://website4.com"
          ],
          "Emails": [
            "email5@domain.com",
            "email6@domain.com"
          ]
        }
      }
    ],
    "Representatives": [
      {
        "ID": 1234567893,
        "Organization": {
          "ID": "00000000-0000-0000-0000-000000000003",
          "Name": "Organization Name 4",
          "CountryCode": "UK",
          "City": "London",
          "Street": "Baker Street",
          "HouseNumber": "221B",
          "ZIP": "NW1 6XE",
          "URLs": [
            "https://website5.com"
          ],
          "Emails": [
            "email7@domain.com",
            "email8@domain.com"
          ]
        }
      },
      {
        "ID": 1234567894,
        "Organization": {
          "ID": "00000000-0000-0000-0000-000000000004",
          "Name": "Organization Name 5",
          "CountryCode": "US",
          "State": "California",
          "City": "Los Angeles",
          "Street": "Sunset Boulevard",
          "HouseNumber": "1000",
          "ZIP": "90001",
          "URLs": [
            "https://website6.com"
          ],
          "Emails": [
            "email9@domain.com",
            "email10@domain.com"
          ]
        }
      }
    ]
  }
}

Element Descriptions:

BrandOrganizations Block

  • This block contains all the Brand-Organization relationships associated with a product.
  • The structure mirrors that of BrandOrganizations.xml.gz, except that the JSON does not include the Updated key found in the REFs file.

Brand Relations:

  • BrandOwner: The primary manufacturer of the brand’s products. A brand has only one owner.
  • Licensees: Organizations that manufacture products under the brand. A brand may have multiple licensees.
  • Representatives: Legal entities responsible for sustainability-related matters for the brand.

Organization Details:

  • ID: Unique UUID identifier for the organization.
  • Name: Official name of the organization.
  • CountryCode: ISO Alpha-2 country code.
  • State: Only available for applicable countries (e.g., US).
  • City, Street, HouseNumber, ZIP: Address details.
  • URLs: List of official websites (mandatory).
  • Emails: Contact email addresses (optional).

Implementation Considerations

API Access & Authentication

  • Ensure that you have valid API credentials (shop_login, app_key) for authentication.
  • The icecat_id parameter should correspond to a valid product in the Icecat database.

Data Synchronization

  • Unlike the REFs file, this API call provides real-time data.
  • Since the Brand Organizations data is not included in the standard product JSON response, a separate API call is required.

Comparison with REFs File (BrandOrganizations.xml.gz)

  • The REFs file provides a batch approach for managing organization relationships, while the API allows on-demand retrieval.
  • Using the API is recommended for dynamic integrations where immediate updates are needed.

Read further: Icecat, ,

Most read

Icecat xml

Open Catalog Interface (OCI): Manual for Open Icecat XML and Full Icecat XML

This document describes the Icecat XML method of Icecat's Open Catalog Inte...
 November 3, 2019
manual thumbnail3

Manual for Icecat Live: Real-Time Product Data in Your App

Icecat Live is a (free) service that enables you to insert real-time produc...
 June 10, 2022
Icecat CSV Interface

Manual for Icecat CSV Interface

This document describes the manual for Icecat CSV interface (Comma-Separate...
 September 28, 2016

Manual for Icecat URL: Integrating Links to Product Data Sheets and Images

Version: 1.21, August 28, 2019.
 October 4, 2018
manual thumbnail

Manual for Open Icecat JSON Product Requests

JSON (JavaScript Object Notation) is an increasingly popular means of trans...
 September 17, 2018
Addons plugins

Icecat Add-Ons Overview. NEW: Red Technology

Icecat has a huge list of integration partners, making it easy for clients ...
 October 27, 2023
LIVE JS

How to Create a Button that Opens Video in a Modal Window

Recently, our Icecat Live JavaScript interface was updated with two new fun...
 November 3, 2021

Updated AIRDROP V: Join ICURY Pilot. Trade at Nocks (ICY-EUR) and Txbit (ICY-BTC)

ICURY (ICY), the loyalty token of Iceca...
 January 20, 2020
New Standard video thumbnail

Autheos video acquisition completed

July 21, Icecat and Autheos jointly a...
 September 7, 2021
Personalized Interface File and Catalog from Icecat

Manual Personalized Interface File and Catalog from Icecat

With Icecat, you can generate personalized or customized CSV or Excel files...
 May 3, 2022