Data schema

This page describes the shape of a product and its variants as the Fulify API returns and accepts them. Use it when you map fields from another system, build an integration, or need to know exactly what a field means.

A few rules apply throughout:

Fields can be null. Unless a field is marked as always present, expect null when it has no value.
Prices and measurements are decimal strings. They're returned as text, such as "19.99", so no precision is lost. On a write you can send a number or a string.
Booleans must be JSON booleans. Send true or false, never "false" as a string.
Writes are partial. Only the fields you send change, and null clears a field.

Product

Identity and type

Field	Type	Write	Notes
id	integer	Read-only	Fulify's id for the product.
sku	string	Required	The product's identity. Unique in your organization, compared ignoring case and spaces. Up to 255 characters.
name	string	Yes	Required to create. Up to 255 characters.
type	string	Yes	physical, digital or service. Defaults to physical.
subtitle	string	Yes	Up to 500 characters.
description	string	Yes	HTML, cleaned to the tags the product editor allows.
shortDescription	string	Yes	Plain text.

Pricing

Field	Type	Write	Notes
basePrice	decimal string	Yes	The list price. Required to create. Stored to two decimal places.
salePrice	decimal string	Yes	Sale price.
retailPrice	decimal string	Yes	RRP or MSRP.
costPrice	decimal string	Yes	Your cost.

Prices are in your organization's currency, set in Settings → General. Product prices are rounded to two decimal places, and the largest accepted value is 99,999,999.99.

Identifiers

Field	Type	Write	Notes
upc	string	Yes	UPC barcode.
mpn	string	Yes	Manufacturer part number.
gtin	string	Yes	GTIN or EAN.
binPickingNumber	string	Yes	Warehouse bin location.

Dimensions and shipping

Field	Type	Write	Notes
weight	decimal string	Yes	In your organization's weight unit.
width, height, depth	decimal string	Yes	Product dimensions, in your organization's length unit.
shippingLength, shippingWidth, shippingHeight	decimal string	Yes	Packaged dimensions.
isFreeShipping	boolean	Yes
fixedCostShippingPrice	decimal string	Yes
handlingTimeMin, handlingTimeMax	integer	Yes	Handling time in days.
shippingProfileId	integer	Yes	A shipping profile in your organization.

Weights and dimensions are in the units chosen in Settings → General → Units: grams or kilograms with centimetres, or pounds or ounces with inches. Fulify stores and sends the numbers as entered, so send values in those units.

Condition, availability and ordering

Field	Type	Write	Notes
condition	string	Yes	For example New. Defaults to New.
isConditionShown	boolean	Yes	Show the condition on the storefront.
availability	string	Yes	Defaults to available.
availabilityDescription	string	Yes
inventoryTracking	string	Yes	none, product, variant or by_quantity. Defaults to none.
orderQuantityMinimum, orderQuantityMaximum	integer	Yes	0 means no limit.

SEO and feeds

Field	Type	Write	Notes
pageTitle	string	Yes	SEO title. Up to 255 characters.
metaDescription	string	Yes
metaKeywords	array of strings	Yes
searchKeywords	string	Yes
customUrl	string	Yes	The product's URL path. An existing product keeps its URL when renamed.
ogTitle	string	Yes	Open Graph title. Up to 95 characters.
ogDescription	string	Yes	Open Graph description. Up to 200 characters.
ogType	string	Yes	Defaults to product.
excludeFromGoogleMerchant	boolean	Yes
googleProductCategoryId	integer	Yes	Google product category.
googleCustomLabel0 to googleCustomLabel4	string	Write-only	Accepted on write, not returned on read.
productClassificationId	integer	Yes	Product classification.
productLanguage	string	Yes	A language code such as en or fr.

Customs and tax

Field	Type	Write	Notes
customsTemplateId	integer	Yes	A customs and compliance template in your organization.
countryOfOrigin	string	Yes
taxCode	string	Yes	The tax provider's code.
taxCategoryId	integer	Yes	A tax category in your organization.
unitPriceMeasurement	object	Yes	quantityValue, quantityUnit, referenceValue and referenceUnit.

Media and content

Field	Type	Write	Notes
thumbnailImage	string	Yes	Primary image URL. A public https URL, up to 500 characters.
thumbnailImageAlt	string	Yes	Alt text for the primary image.
images	array	Yes	Objects with url and alt, or plain URL strings. Replaces the whole list. Public https URLs only.
productHighlights	array of strings	Yes
videos	array of objects	Yes	Each with title, description, type, videoId and sortOrder.

Relationships

Field	Type	Write	Notes
brandId	integer	Read-only	Set the brand with brand instead.
brand	string or integer	Write-only	A brand name or id. Must already exist. null clears it.
categoryIds	array of integers	Read-only	Set categories with categories instead.
categories	array	Write-only	Category names or ids. Replaces the product's categories. Must already exist.

Visibility, sync and status

Field	Type	Write	Notes
isVisible	boolean	Yes	Visible on the storefront. New products start hidden.
isFeatured	boolean	Yes
publishDate, endDate	timestamp	Yes	Scheduled publish and end dates.
isActive	boolean	sync:write	The master Sync switch. Off for new products. Always present.
syncEnabled	boolean	sync:write	Channel Sync for BigCommerce and Shopify. In the app, a product saved with it off isn't pushed to Linnworks either. Off for new products. Always present.
destinations	array (read), object (write)	sync:write	Connected-app state on read, opt-ins on write. See Sync control.
syncStatus	string	Read-only	The product's channel sync state.
bigcommerceId	integer	Read-only	The linked BigCommerce product id, where there is one.
lastSyncedAt	timestamp	Read-only	Last successful channel sync.
createdAt, updatedAt	timestamp	Read-only	Always present. updatedAt moves on every change and drives updatedSince.
variants	array	See Variants	Returned by GET /products/{sku} only.

syncStatus values include not_synced (never synced, or sync is switched off), pending (changed since the last sync), syncing, synced and error.

See Sync control for how isActive, syncEnabled and destinations work together.

Variant

Field	Type	Write	Notes
id	integer	Read-only
sku	string	Match key	Unique within the product.
options	object	Create only	Option type to value. Not returned on read.
price	string	Yes	Empty means the variant uses the product's base price.
salePrice, retailPrice, costPrice	string	Yes	Send non-negative decimals. Stored as sent.
weight, width, height, depth	string	Yes	Send non-negative decimals, in your organization's units. Stored as sent.
fixedCostShippingPrice	string	Yes
upc, mpn, gtin	string	Yes
binPickingNumber	string	Yes
hsCode	string	Yes	HS tariff code. Empty inherits.
countryOfOrigin	string	Yes	Empty inherits.
taxCode	string	Yes	Empty inherits.
unitPriceMeasurement	object	Yes
inventoryWarningLevel	integer	Yes	Low-stock threshold.
isFreeShipping	boolean	Yes
purchasingDisabled	boolean	Yes
purchasingDisabledMessage	string	Write-only	Accepted on write, not returned on read.
isActive	boolean	Yes	New variants are active unless you send false.
isDefault	boolean	Update only	New variants are never the default.
imageUrl	string	Yes	A public https URL.
images	array	Read-only

Variant prices and measurements are stored exactly as you send them, without rounding. Stock quantities aren't part of the API. See Variants for how variants are matched and created.

Inheritance

Some values flow down from a broader record unless a narrower one sets its own:

Customs and tax: a customs template supplies defaults, the product overrides the template, and a variant overrides the product. On a variant, an empty hsCode, countryOfOrigin or taxCode means "use the product's value".
Variant price: an empty variant price means the variant sells at the product's basePrice, on every channel.

Destination

Each entry in a product's destinations list on read:

Field	Type	Notes
id	string	The connected app. linnworks today.
enabled	boolean	Whether the product is opted in.
status	string	synced, error or pending. null when nothing has been attempted.
lastSyncedAt	timestamp	Last successful push.
error	string	The last error, if any.

Only apps that are installed and included in your plan are listed.

Linked records

Products refer to records you manage in Fulify. The API reads and sets these references but doesn't create or edit the records themselves:

Record	Managed in	Referenced by
Brands	Brands	brand (write), brandId (read)
Categories	Categories	categories (write), categoryIds (read)
Option types and values	Settings → Variant Options	Variant options. Missing values are created; option types aren't.
Tax categories	Settings → Tax	taxCategoryId
Customs templates	Settings → Customs & Compliance Templates	customsTemplateId
Shipping profiles	Settings → Shipping Profiles (ShipperHQ)	shippingProfileId
Size charts	Settings → Selection Guides, or the API	The selection-guide endpoints

What the API doesn't cover

Version 1 of the API doesn't read or write these parts of a product: channel assignments and per-channel overrides, custom fields and attribute templates, content sections such as warranty, shipping, returns and FAQs, badges, features, related products, preorder settings, and stock quantities. Manage them in Fulify.

Field length limits

Text longer than its field's limit makes the product fail with write failed. A dry run doesn't check lengths, so trim values before sending.

Field	Maximum characters
sku, name, pageTitle, upc, mpn, gtin, binPickingNumber, customUrl	255
subtitle, thumbnailImage, thumbnailImageAlt	500
ogTitle	95
ogDescription	200
condition, availability, inventoryTracking, ogType, taxCode	50
weight, width, height, depth and the shipping dimensions	50
countryOfOrigin	100
productLanguage	10
Variant sku, mpn, gtin, binPickingNumber	255
Variant upc, hsCode, taxCode, prices and measurements	50
Variant imageUrl	500