Catalog JSON Schema

Modified on Tue, Jun 23 at 4:20 PM

GPA Catalog Export — JSON Schema Reference

This article documents the structure of the JSON file produced when a catalog is exported from Global Product Access. Use this reference when building integrations that consume GPA catalog export data.

Root Object

{
  "Catalog": { ... },
  "Products": [ ... ]
}

The root object contains two top-level keys: Catalog, which describes the catalog itself, and Products, which is an array of individual product records.

Catalog Object

Field	Type	Description
`Id`	string (UUID)	Unique catalog identifier
`CompanyId`	string (UUID)	ID of the publishing company
`CompanyName`	string	Display name of the publishing company
`CategoryId`	string (UUID)	ID of the catalog's product category
`CategoryName`	string	Display name of the product category
`Name`	string	Catalog name
`Description`	string	Catalog description
`IsPriceVisible`	boolean	Whether prices are visible to subscribers
`ThumbnailUrl`	object	Catalog thumbnail image. See Image Object.
`Status`	string	Catalog status (`Draft`, `Active`, etc.)
`Type`	string	Catalog visibility (`Public`, `Private`)
`ProductCount`	integer	Total number of products in the catalog
`ActiveProductCount`	integer	Number of active products in the catalog
`SubscriberCount`	integer	Number of active subscribers
`ComplianceEngineIds`	array (UUID)	IDs of compliance engines applied to this catalog
`ExternalCatalogNumber`	string / null	External reference number, if applicable
`TagFilters`	array (string)	Tags used for dynamic product filtering
`Integrations`	array	Marketplace or EDI integrations connected to this catalog
`CanDownload`	boolean	Whether the catalog can be downloaded
`CreatedAt`	string (ISO 8601)	Catalog creation timestamp
`UpdatedAt`	string (ISO 8601)	Catalog last updated timestamp

Product Object

Each item in the Products array represents a single product record (one SKU / size-color combination).

Note on dual field naming: Several fields appear twice in each product record — once in snake_case (e.g. sku_internal_identifier) and once in camelCase (e.g. sku). Both represent the same value. The dual naming is maintained for backwards compatibility with integrations built on earlier versions of the GPA export format.

Identifiers

Field	Type	Description
`id`	string (UUID)	Unique product identifier
`company_id`	string (UUID)	ID of the owning company
`sku` / `sku_internal_identifier`	string	Internal SKU — conditionally required
`upc` / `upc_12_digit_barcode`	string / null	12-digit UPC barcode — conditionally required
`ean` / `ean_13_digit_barcode`	string / null	13-digit EAN barcode — conditionally required
`gtin` / `gtin_global_trade_item_number`	string / null	Global Trade Item Number — conditionally required
`isbn` / `isbn_book_identifier`	string / null	ISBN (books only)
`styleNumber` / `style_number_manufacturer_reference`	string	Manufacturer style or reference number
`additionalPartNumber` / `additional_identifier_supplier_part_number`	string / null	Supplementary supplier part number

Identifier rule: At least one of sku, upc, ean, or gtin must be present on every product.

Core Product Fields

Field	Type	Description
`name` / `product_name_consumer_facing`	string	Consumer-facing product name
`description` / `product_description` / `description_text`	string	Product description (may contain HTML entities)
`featuresBenefitsMarketingMessages` / `features_benefits_marketing_messages`	string / null	Marketing feature copy
`category` / `product_category_internal`	string	Internal product category label
`status`	string	Product status (`Active`, `Inactive`, etc.)
`startDate` / `pricing_effective_start_date`	string (ISO 8601) / null	Date product becomes active
`endDate` / `pricing_effective_end_date`	string (ISO 8601) / null	Date product is automatically archived

Pricing

Field	Type	Description
`price` / `selling_price_per_unit`	number / null	Selling price per unit
`wholesalePrice` / `net_cost_wholesale`	number / null	Wholesale / net cost
`msrp` / `list_price_msrp`	number / null	Manufacturer's suggested retail price
`netPrice` / `promotional_price`	number / null	Promotional or net price
`currency` / `currency_code_iso`	object	Currency. See Lookup Object.
`canViewPrice` / `can_view_price`	boolean	Whether the subscriber can see prices

Inventory

Field	Type	Description
`inventory` / `available_quantity`	number / null	Available inventory quantity
`unitOfMeasure` / `unit_of_measure_uom`	object	Unit of measure. See Lookup Object.

Images

Field	Type	Description
`thumbnailUrl` / `product_image_primary`	object	Primary product image. See Image Object.
`galleryUrls` / `product_images_additional`	array	Additional product images. Array of Image Objects.

Classification

Field	Type	Description
`type` / `product_category_global`	object	Global product type. See Lookup Object.
`family` / `product_family_global_classification`	object	Global product family. See Lookup Object.
`subType` / `product_sub_category_global`	object	Global product sub-category. See Lookup Object.

Catalog Membership

Each product includes a catalogs / published_catalogs array listing every catalog the product belongs to.

Field	Type	Description
`catalogId` / `catalog_id`	string (UUID)	ID of the catalog
`catalogName` / `catalog_name`	string	Name of the catalog
`unitPrice` / `selling_price_per_unit`	number / null	Per-catalog unit price override
`inventoryAllocation` / `inventory_allocation`	number / null	Per-catalog inventory allocation
`type`	string	How the product was added (`Manual`, `Tag`, etc.)

Attributes

Each product includes an attributes array of custom and system-defined fields.

Field	Type	Description
`id`	string (UUID)	Attribute definition ID
`name`	string	Attribute name (e.g. `Fabric or Material Description`)
`value`	string	Attribute value
`mandatory`	boolean	Whether the attribute is required at the company level
`is_compliance_required`	boolean	Whether the attribute is required by a compliance engine
`type`	string	Data type (`Text`, `Number`, `Boolean`, etc.)
`options`	array	Predefined value options (for list-type attributes)
`default_value`	string / null	Default value if none is provided
`company_id`	string (UUID) / null	Owning company ID (null = system attribute)
`ref_id`	string / null	External reference ID

Properties

Nested object containing physical, packaging, and ordering details.

Dimensions (`product_dimensions` / `dimensions`)

Field	Type	Description
`product_length` / `length`	number / null	Product length
`product_width` / `width`	number / null	Product width
`product_height` / `height`	number / null	Product height
`dimension_unit_of_measure` / `unit`	string	Unit of measure (`Millimeter`, `Inch`, etc.)

Weight (`product_weight_measure` / `weight`)

Field	Type	Description
`product_weight` / `weight`	number / null	Product weight
`weight_unit_of_measure` / `unit`	string	Unit of measure (`Kilogram`, `Pound`, etc.)

Packaging (`product_packaging` / `packaging`)

Field	Type	Description
`pack_quantity` / `quantityPerPack`	number / null	Units per pack
`package_length` / `PackLength`	number / null	Package length
`package_width` / `PackWidth`	number / null	Package width
`package_height` / `PackHeight`	number / null	Package height
`package_dimension_unit_of_measure` / `dimensionUnit`	string	Package dimension unit
`packaged_product_weight` / `packagedWeight`	number / null	Packaged product weight
`packaged_weight_unit_of_measure` / `weightUnit`	string	Packaged weight unit

Ordering Info (`ordering_info` / `orderingInfo`)

Field	Type	Description
`minimum_order_quantity` / `minimumQuantity`	number / null	Minimum order quantity
`maximum_order_quantity` / `maximumQuantity`	number / null	Maximum order quantity
`gs1_standard_color` / `color`	object	GS1 standard color. See Lookup Object.
`gs1_standard_size` / `size`	object	GS1 standard size. See Lookup Object.
`supplier_color_name` / `customColor`	string	Supplier's custom color name
`supplier_size_name` / `customSize`	string	Supplier's custom size name

Field	Type	Description
`product_tags` / `productTags`	array (string)	Tags applied to the product for dynamic catalog assignment

Variants

Field	Type	Description
`variants`	array	Child variant products grouped under this parent
`variant_attributes_group`	array	Attribute groupings used to define variant dimensions
`options`	array	Selectable option values (e.g. size, color dropdowns)

Reusable Object Definitions

Lookup Object

Used for color, size, currency, unit of measure, and classification fields.

{
  "id":   "string (UUID)",
  "code": "string",
  "name": "string"
}

Image Object

Used for primary and additional product images.

{
  "altText": "string",
  "versions": {
    "original": "string (URL)",
    "thumb":    "string (URL)",
    "small":    "string (URL)",
    "medium":   "string (URL)",
    "large":    "string (URL)"
  }
}