Categories: Icecat

Manual: Retrieving GPSR related Contact Details

Version 1.1 (Updated on September 26th, 2025)

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>
                <Scopes>
                    <Categories/>
                <Scopes>
            </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:

  • Categories: Defines the scope of product categories for an organization. Self-closed tag <Categories/> means that Brand Owner is applied to all categories.
  • 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: The default manufacturer. Attach the Brand Owner organization to all brand products.
    • The Brand Owner might be restricted to scope categories. If the product is outside the Brand Owner’s scope, the Brand Owner data is skipped.
  • 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

  • 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 the 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 the 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, ,

Olena Vasylynenko

Share
Published by
Olena Vasylynenko
Tags: gpsrmanual
10 months ago

Recent Posts

EU Introduces New Dispute Resolution Rules to Reflect Ecommerce Growth

The European Union has finalised new rules on alternative dispute resolution (ADR) for consumer complaints,…

12 hours ago

Icecat Heads to ISE Barcelona 2026 – See You in February!

Icecat will be attending Integrated Systems Europe (ISE) Barcelona 2026, taking place from 3–6 February…

1 day ago

HousePC Joins Full Icecat to Power Richer Product Content Across Channels

HousePC, a well‑known Italian online retailer specializing in consumer electronics, IT products, home appliances, and…

2 days ago

EU to Charge €3 Duty on Small E‑Commerce Parcels from July 2026

The European Union is preparing a significant change to how cross‑border e‑commerce parcels are treated…

3 days ago

UK-EU Trade Frictions Persist: What It Means for Ecommerce in 2026

More than three years after Brexit officially took effect, British businesses continue to face challenges…

6 days ago

Financial Calendar Icecat N.V.

Below, the financial calendar of Icecat N.V.'s financial reporting dates and preceding closed trading periods…

1 week ago