GlobaleCatalogFeed - Global-e Docs

This job is part of the default Global-e SFCC cartridge functionality. GlobaleCatalogFeed generates a product catalog CSV from SFCC catalog data and uploads it to an SFTP folder configured in site preferences. Global-e pulls the file from that location for product classification and restriction processing. See also: Jobs overview, GlobaleProducts (restriction import), Restricted / forbidden products, Configuration.

Overview

Global-e requires periodic catalog exports for product classification and restrictions. The job has two steps:

Step	Step type	Description
GenerateCatalogFeed	`custom.GlobaleGenerateCatalogFeed`	Builds the catalog CSV from `geCatalogFeedConfig` and writes it to the IMPEX folder
UploadCatalogFeed	`custom.GlobaleUploadCatalogFeed`	Uploads the generated file to the SFTP location configured in site preferences

GenerateCatalogFeed — builds the CSV from site preference Catalog Feed Configuration (geCatalogFeedConfig) and writes it under IMPEX.
UploadCatalogFeed — uploads that file from IMPEX to the configured SFTP folder so Global-e can import it.

Note the following about GlobaleCatalogFeed behavior:

It iterates all products in the configured storefront catalog (feedData.catalogId). By default it skips product sets, master products, and variation-group products — enable addMasterProducts / addVariationGroupProducts to include them. (As a special case, when a variation group’s master product has no categories, its variants are exported.)
It exports products to a newly generated CSV file (not in-place catalog updates).

Information and error messages are written to the GLOBALE custom log (logger category GLOBALE) when catalog data or upload configuration issues occur. Configure it under Administration → Site Development → Development Setup → Custom Log Settings.

High-level flow

The job picks up products created or modified since the last run and writes them to a CSV file. That file is pushed to a pre-defined SFTP folder hosted by the merchant or Global-e. A Global-e service watches the SFTP folder, classifies new and updated products, and returns classification and restriction data through the Global-e API. GlobaleProducts imports that data back into SFCC product custom attributes (geRestrictedCountries, geIsForbidden, geVatRates). Flow: SFCC catalog → GlobaleCatalogFeed CSV → SFTP → Global-e classification → API → GlobaleProducts → SFCC product attributes.

Installation and scheduling

After Installation, schedule GlobaleCatalogFeed to run periodically (typically once daily; adjust to your catalog update frequency). The job is disabled by default in metadata/jobs.xml. Assign job flows only to Global-e operated sites. Replace the sample site ID (RefArchGlobal) with your site IDs during deployment.

Mandatory catalog fields

Global-e expects these fields in the catalog CSV (configure columns in geCatalogFeedConfig):

SKU
Display Name
Product Description
Country Of Origin
Image URL
Kids products

When product data is not in SFCC

If mandatory fields live in another backend system, you can disable GlobaleCatalogFeed and export the catalog from your product management system instead. Global-e can process CSV files and native SFCC XML exports.

Catalog feed columns

The table below lists standard catalog feed columns. Include optional columns when the data is available — Global-e recommends populating as many as possible.

#	Column Name	Type	Description	Sample Value	Comments
1	Id	String	SKU	22398003
2	ParentProductID	String	Master product ID when applicable	P22398003
3	HS Code (Commodity code)	String	Product commodity code	62052000
4	Product Category	String	Product category	Ladies Shoes
5	DisplayName	String	Product name on the website	Diamond Quilted Cushion
6	LongDescription	String	Long description	A stylish cushion brings added comfort to your bed.
7	Height	Number	Product height (default: cm)	1
8	Width	Number	Product width (default: cm)	5
9	Length	Number	Product length (default: cm)	3
10	Volume	Number	Volumetric weight (default: cubic cm)	NULL
11	Weight	Number	Product weight (default: gr)	460
12	OriginCountry (ISO3)	String	Country of manufacture	GB
13	IsBlocked	Number	Block product in all Global-e operated countries	0
14	IsVirtual	Number	Non-physical product (courses, memberships, vouchers)	0
15	VATRate	Number	VAT rate to apply	20
16	Price	Number	Product price in merchant currency	12.99
17	Keywords	String	Product keywords	shirt
18	Size	String	Product size	S
19	Color	String	Product color	Blue
20	IsKidsProduct	Number	Kids clothing flag (required for correct VAT)	0
21	ProductURL	String	Product page URL	https://www.merchant.com/product/
22	ImageURL	String	Product image URL	https://www.merchant.com/product/image.png	Often populated on full export only; in delta mode you may emit empty values — see column type `static` below.
23	IS DG	Number	Dangerous goods flag (DHL via Global-e)	0	`IsDangerousGoods = 1` is blocked automatically for DHL dangerous goods.

Configuration

Feed settings are stored in site preference Catalog Feed Configuration (geCatalogFeedConfig): Merchant Tools → Site Preferences → Custom Site Preference Groups → Global-e Catalog Jobs Example configuration:

{
	"impex": {
		"folderPath": "/src/globale/catalog/",
		"archiveFolderPath": "/src/globale/catalog/archive/"
	},
	"sftpCredentialIDs": [
		"Globale-SFTPCatalogFeedUpload"
	],
	"file": {
		"name": "globale_catalog_feed_{datetime}",
		"columns": [
			{
				"header": "Id (* mandatory field)",
				"type": "product",
				"attr": "ID"
			},
			{
				"header": "ParentProductID",
				"type": "product",
				"attr": "masterProduct.ID"
			},
			{
				"header": "HS Code (Commodity code)",
				"type": "product",
				"attr": "custom.hsCode",
				"fallback": {
					"type": "static",
					"attr": ""
				}
			},
			{
				"header": "Product Category",
				"type": "category",
				"attr": "displayName",
				"categoriesSeparator": ","
			},
			{
				"header": "DisplayName (*)",
				"type": "product",
				"attr": "name",
				"fallback": {
					"type": "product",
					"attr": "ID"
				}
			},
			{
				"header": "LongDescription(*)",
				"type": "product",
				"attr": "longDescription.markup"
			},
			{
				"header": "Height",
				"type": "product",
				"attr": "custom.geHeight",
				"fallback": {
					"type": "static",
					"attr": ""
				}
			},
			{
				"header": "Width",
				"type": "product",
				"attr": "custom.geWidth",
				"fallback": {
					"type": "static",
					"attr": ""
				}
			},
			{
				"header": "Length",
				"type": "product",
				"attr": "custom.geLength",
				"fallback": {
					"type": "static",
					"attr": ""
				}
			},
			{
				"header": "Volume",
				"type": "product",
				"attr": "custom.geVolume",
				"fallback": {
					"type": "static",
					"attr": ""
				}
			},
			{
				"header": "Weight (*)",
				"type": "weight",
				"attr": "custom.geWeight",
				"unit": "kg",
				"fallback": {
					"type": "static",
					"attr": ""
				}
			},
			{
				"header": "OriginCountry (ISO3) (*)",
				"type": "product",
				"attr": "custom.manufacturerCountryCode",
				"fallback": {
					"type": "static",
					"attr": ""
				}
			},
			{
				"header": "IsBlocked (*)",
				"type": "product",
				"attr": "custom.geIsBlocked",
				"fallback": {
					"type": "static",
					"attr": ""
				}
			},
			{
				"header": "IsVirtual",
				"type": "product",
				"attr": "custom.geIsVirtual",
				"fallback": {
					"type": "static",
					"attr": "0"
				}
			},
			{
				"header": "VATRate",
				"type": "tax"
			},
			{
				"header": "Price",
				"type": "price",
				"attr": "gbp-sale-prices",
				"fallback": {
					"type": "product",
					"attr": "priceModel.price.value",
					"fallback": {
						"type": "static",
						"attr": "0"
					}
				}
			},
			{
				"header": "Keywords",
				"type": "static",
				"attr": ""
			},
			{
				"header": "Size",
				"type": "variationAttribute",
				"attr": "size",
				"value": "value"
			},
			{
				"header": "Color",
				"type": "variationAttribute",
				"attr": "color",
				"value": "value"
			},
			{
				"header": "ProductURL",
				"type": "productUrl",
				"attr": "pid",
				"controller": "Product-Show",
				"host": "www.example.com"
			},
			{
				"header": "ImageURL",
				"type": "imageUrl"
			}
		]
	},
	"feedData": {
		"localeId": "default",
		"catalogId": "storefront-catalog-m-non-en",
		"processOnlyModifiedProducts": true
	}
}

The impex, sftpCredentialIDs, file, file.name, file.columns, feedData, and feedData.localeId keys are required. Other keys (such as file.type, file.separator, file.quote, and most feedData.* flags) are optional and fall back to defaults — see the tables below.

Top-level settings

Field	Type	Description	Mandatory	Sample
impex	object	IMPEX folder settings	yes	—
impex.folderPath	string	Folder under IMPEX where generated files are stored	yes	`/globale/catalog/`
impex.archiveFolderPath	string	Folder where uploaded files are archived	yes	`/globale/catalog/archive/`
sftpCredentialIDs	array	Service credential IDs for SFTP upload	yes	`["Globale-SFTPCatalogFeedUpload"]`
file	object	Output file settings	yes	—
file.name	string	Generated file name pattern	yes	`globale_catalog_feed_{datetime}`
file.type	string	File format	no	`csv`
file.separator	string	Column delimiter	no	`,`
file.quote	string	Quote character	no	`"`
file.columns	array	Column definitions	yes	`[]`
feedData	object	Catalog extraction settings	yes	—
feedData.catalogId	string	Catalog ID for product extraction	no	`{{site-catalog-id}}`
feedData.localeId	string	Locale for generated content	yes	`default`
feedData.processOnlyModifiedProducts	boolean	Delta mode — only modified products since last run	yes	`false`
feedData.processProductsPerRunCount	number	Products processed per run	no	`0`
feedData.processOnlyOnlineProducts	boolean	Online products only	no	`false`
feedData.addMasterProducts	boolean	Include master products	no	`false`
feedData.addVariationGroupProducts	boolean	Include variation group products	no	`false`

Column types

Each CSV column is built from a type entry in file.columns:

Type	Description	Example
product	Value from a product attribute (`attr`)	`{"type": "product", "attr": "custom.hsCode"}`
weight	Product weight with unit conversion (`unit`: `kg` → grams in output)	`{"type": "weight", "attr": "custom.geWeight", "unit": "kg"}`
category	Value from product category attribute	`{"type": "category", "attr": "displayName"}`
tax	Product tax rate	`{"type": "tax"}`
price	Price from price book ID in `attr`	`{"type": "price", "attr": "gbp-sale-prices"}`
variationAttribute	Variation attribute value	`{"type": "variationAttribute", "attr": "size", "value": "value"}`
productUrl	Product URL from controller and host	`{"type": "productUrl", "attr": "pid", "controller": "Product-Show", "host": "www.example.com"}`
imageUrl	Product image URL	`{"type": "imageUrl"}`
preference	Site preference value	`{"type": "preference", "attr": "geClientJsMerchantId"}`
static	Literal value from `attr`	`{"type": "static", "attr": ""}` — use for empty ImageURL in delta mode
custom	Value from a custom handler module path (the module exports `getValue(product)`)	`{"type": "custom", "handler": "*/cartridge/scripts/globale/customHandler"}`
code	Inline handler expression evaluated against `column` and `product`	`{"type": "code", "handler": "return (product.custom.product_online_patina ? '1' : '')"}`

The product, price, and weight types support nested fallback chains; the custom and code types fall back to their configured fallback only if the handler throws.

Nested fallback example

Look up a GBP price book first; if missing, use the product default price; otherwise 0:

{
	"type": "price",
	"attr": "gbp-sale-prices",
	"fallback": {
		"type": "product",
		"attr": "priceModel.price.value",
		"fallback": {
			"type": "static",
			"attr": "0"
		}
	}
}

SFTP service credential

Set SFTP credentials from Global-e in service credential Globale-SFTPCatalogFeedUpload (the credential ID referenced by sftpCredentialIDs in geCatalogFeedConfig). At runtime the upload step uses the generic Globale-SFTPUpload service with this credential ID. Administration → Operations → Services → Service Credentials → Globale-SFTPCatalogFeedUpload Set URL, username, and password from Global-e on that credential (URL empty is not used for SFTP host — use the credential host/user/password fields as provided).

Testing

Confirm Catalog Feed Configuration (geCatalogFeedConfig) is set under Merchant Tools → Site Preferences → Custom Site Preference Groups → Global-e Catalog Jobs.
Open Administration → Operations → Jobs → GlobaleCatalogFeed.
Run GlobaleCatalogFeed (Run Now or wait for the schedule).
After the job completes, verify the CSV file appears on the configured SFTP location.

​Overview

​High-level flow

​Installation and scheduling

​Mandatory catalog fields

​When product data is not in SFCC

​Catalog feed columns

​Configuration

​Top-level settings

​Column types

​Nested fallback example

​SFTP service credential

​Testing