Product POST

URI

https://{DATACENTER}.brightpearl.com/public-api/{ACCOUNT}
/product-service/product/

Refer to our documentation on URI syntax for more information on how to construct URIs.

Description

This message allows you to create Products in Brightpearl. "Brightpearl" is the only supported Sales Channel.

Product Groups

When creating new a Product over API, if a product with the same name exists then a new product-group will be created. The existing product and the product you are creating will be added to this new group product-group. If many products with the same name already exist then the new product you are creating will be added to this product-group.

Product Variations

It is possible to create products with variations using this message. The validation you will need to be aware of is:

  • Option ID must exist
  • Option value ID must exist
  • Option value must be available for the option
  • Option must be available for the specified product type
  • Product cannot already exist in the product group with same option and option value combination
  • You can't have more than 4 options per product group

Field Description Required Default
brandId The ID of the brand for this product. True
collectionId The ID of the collection for this product. False The collection must belong to the product's brand.
productTypeId The ID of the product type. False Defaults to the Default Product Type ID configured in products Setup.
identity This section represents external identifying attributes of a product. False
identity.sku A Stock-Keeping Unit you wish to identify this product by. Max 32 characters. False
identity.ean International Article Number (formerly European Article Number) which identifies this product. Max 14 characters. False
identity.upc The Universal Product Code which identifies this product. Max 14 characters. False
identity.isbn The International Standard Book Number which identifies this product. Max 14 characters. False
identity.mpn The Manufacturing Product Number. Max 100 characters. False
identity.barcode A barcode number which identifies this product. Max 32 characters. False
stock This section is used to specify physical details about the product such as its weight and dimensions. False
stock.stockTracked Specifies if the product is stock tracked. False false
stock.weight Specifies details about the weight of the product. False
stock.weight.magnitude Specifies the weigth of the product. Currently no weight unit is specified within Brightpearl. We assume you use the same for all products. False
stock.dimensions.width Specifies the width of the product. The field is used when calculating the volume of the product. False
stock.dimensions.length Specifies the length of the product. The field is used when calculating the volume of the product. False
stock.dimensions.height Specifies the height of the product. The field is used when calculating the volume of the product. False
financialDetails This section specifies financial details of the product. True if your Brightpearl account is in VAT mode, False if in Sales Tax (taxable will default to false).
financialDetails.taxable When using Sales Tax this option specifies whether the product is taxable. False false.
financialDetails.taxCode This section is used when your Brightpearl account is in VAT Tax mode. It is used to specify the tax class for the product. You can either specify the ID or Code. True if in VAT mode, false if in Sales Tax mode.
financialDetails.taxCode.id Specifies the id for the tax code of this product. False.
financialDetails.taxCode.code Specifies the code for the tax code for this product. False.
salesChannels This section specifies a list of sales channels True
salesChannels.salesChannelName This specifies the name for the sales channel. Must be "Brightpearl". True
salesChannels.productName This specifies the name for the product. Max 128 characters. True
salesChannels.productCondition This specifies the condition of the product. Possible values are: 'new', 'used' and 'refurbished'. False New
salesChannels.categories This section specifies which product categories this product is a member of. True
salesChannels.categories.categoryCode This specifies the code of a category. True
salesChannels.description This section specifies the description of the product. This section is optional however if you include it you must include all sub attributes. False
salesChannels.description.languageCode The 2 letter ISO 3166-2 country code for the language of this description. True
salesChannels.description.text The body of the description. Can be HTML but must be well formed. Maximum 65,535 bytes when encoded as UTF-8. True
salesChannels.description.format The format of the body. Possible values: 'PLAINTEXT','HTML_FRAGMENT' and 'HTML_DOCUMENT'. True
salesChannels.shortDescription This section specifies the short description of the product. This section is optional however if you include it you must include all sub attributes. False
salesChannels.shortDescription.languageCode The 2 letter ISO 3166-2 country code for the language of this short description. True
salesChannels.shortDescription.text The body of the short description. Can be HTML but must be well formed. Maximum 65,535 bytes when encoded as UTF-8. True
salesChannels.shortDescription.format The format of the body. Possible values: 'PLAINTEXT','HTML_FRAGMENT' and 'HTML_DOCUMENT'. True
variations This field lists the options and option values that define the variation for this product. False
variations.optionId Specifies the ID of the Option this variation is for. Not required if no variations specified. True
variations.optionValueId Specifies the ID of the Option value this variation is for. Not required if no variations specified. True
seasonIds Specifies the IDs of the seasons for this product. Takes one or more integers. False
nominalCodeStock Nominal code for Stock False
nominalCodePurchases Nominal code for Purchases False
nominalCodeSales Nominal code for Sales False
composition.bundleComponents Details the component products of the bundle. false
composition.bundleComponents.productId The productId of the bundle component product. True if we supply bundleComponents, False if we don't supply bundleComponents
composition.bundleComponents.productQuantity The quantity of bundle component product. True if we supply bundleComponents, False if we don't supply bundleComponents
reporting For the purposes of reporting False
reporting.categoryId Product category False
reporting.subcategoryId Product category which is a child of categoryId False
reporting.seasonId Season False

Example 1

Minimum product post when on VAT.

Request URI

/product/

Request body

{
	"brandId": 74,
	"financialDetails": {
		"taxCode": {
			"id": 7
		}
	},
	"salesChannels": [
		{
			"salesChannelName": "Brightpearl",
			"productName": "Product B",
			"productCondition": "new",
			"categories": [
				{
					"categoryCode": "276"
				}
			]
		}
	]
}

Response

{
	"response": 1045
}

Example 2

Minimum product post when on sales tax.

Request URI

/product/

Request body

{
	"brandId": 74,
	"salesChannels": [
		{
			"salesChannelName": "Brightpearl",
			"productName": "Product B",
			"productCondition": "new",
			"categories": [
				{
					"categoryCode": "276"
				}
			]
		}
	]
}

Response

{
	"response": 1046
}

Example 3

Full expanded Product post.

Request URI

/product/

Request body

{
	"brandId": 34344,
	"collectionId": 5,
	"productTypeId": 1,
	"identity": {
		"sku": "SKU0001",
		"ean": "12323423",
		"upc": "543534563",
		"isbn": "54353453",
		"barcode": "45453"
	},
	"stock": {
		"stockTracked": true,
		"weight": {
			"magnitude": 4324.54
		}
	},
	"financialDetails": {
		"taxable": false,
		"taxCode": {
			"id": 7,
			"code": "T20"
		}
	},
	"salesChannels": [
		{
			"salesChannelName": "Brightpearl",
			"productName": "Product B",
			"productCondition": "new",
			"categories": [
				{
					"categoryCode": "276"
				},
				{
					"categoryCode": "295"
				}
			],
			"description": {
				"languageCode": "en",
				"text": "

Some description

", "format": "HTML_FRAGMENT" }, "shortDescription": { "languageCode": "en", "text": "

Some description

", "format": "HTML_FRAGMENT" } } ], "seasonIds": [ 1, 2, 3 ], "nominalCodeStock": "1000", "nominalCodePurchases": "5000", "nominalCodeSales": "4000", "reporting": { "seasonId": 3, "categoryId": 295, "subcategoryId": 298 } }

Response

{
	"response": 1047
}

Example 4

Creating a product with two options defined.

Request URI

/product/

Request body

{
	"brandId": 74,
	"productTypeId": 4,
	"financialDetails": {
		"taxCode": {
			"id": 1
		}
	},
	"salesChannels": [
		{
			"salesChannelName": "Brightpearl",
			"productName": "Product B",
			"productCondition": "new",
			"categories": [
				{
					"categoryCode": "276"
				}
			]
		}
	],
	"variations": [
		{
			"optionId": 2,
			"optionValueId": 8
		},
		{
			"optionId": 1,
			"optionValueId": 7
		}
	],
	"seasonIds": [
		1,
		2,
		3
	]
}

Response

{
	"response": 1048
}

Example 5

Minimum product post with dimensions defined.

Request URI

/product/

Request body

{
	"brandId": 74,
	"financialDetails": {
		"taxCode": {
			"id": 7
		}
	},
	"salesChannels": [
		{
			"salesChannelName": "Brightpearl",
			"productName": "Product B",
			"productCondition": "new",
			"categories": [
				{
					"categoryCode": "300"
				}
			]
		}
	],
	"stock": {
		"dimensions": {
			"width": "2.25",
			"length": "2.25",
			"height": "8.50"
		}
	}
}

Response

{
	"response": 1045
}

Example 6

Bundle product post.

Request URI

/product/

Request body

{
	"brandId": 34344,
	"collectionId": 5,
	"productTypeId": 1,
	"identity": {
		"sku": "SKU0001",
		"ean": "12323423",
		"upc": "543534563",
		"isbn": "54353453",
		"barcode": "45453"
	},
	"stock": {
		"stockTracked": true,
		"weight": {
			"magnitude": 4324.54
		}
	},
	"financialDetails": {
		"taxable": false,
		"taxCode": {
			"id": 7,
			"code": "T20"
		}
	},
	"salesChannels": [
		{
			"salesChannelName": "Brightpearl",
			"productName": "Product B",
			"productCondition": "new",
			"categories": [
				{
					"categoryCode": "276"
				},
				{
					"categoryCode": "295"
				}
			],
			"description": {
				"languageCode": "en",
				"text": "

Some description

", "format": "HTML_FRAGMENT" }, "shortDescription": { "languageCode": "en", "text": "

Some description

", "format": "HTML_FRAGMENT" } } ], "seasonIds": [ 1, 2, 3 ], "composition": { "bundle": true, "bundleComponents": [ { "productId": 1698, "productQuantity": 1 }, { "productId": 1250, "productQuantity": 1 } ] } }

Response

{
	"response": 1045
}