Item Master Service

The Item Master provides Radial, Inc. with your product information at the SKU level. All forms of Radial fulfillment, including store fulfillment, require the Item Master. An item must exist in Radial systems before receiving activity can occur and before any customer orders can be accepted.

You can use the Item Master API endpoints to:

Add or update items.
Retrieve items.
Upload items in bulk through a .csv file.

Important: You can also create the Item Master as an XML file and upload it to an SFTP mailbox. If you have a large number of items; for example, 1000 or more, use the XML-based Item Master feed for the initial upload of your item catalog, then use the endpoints to work with single items. Refer to Item Master Feed for details.

Endpoints

Action	Operation	Endpoint	Description
Create or update a single item.	PUT	/item-service/stores/{storeId}/items/{itemId}	Limited to one item per API call. If an item already exists in Radial systems, it is updated. If the item does not exist, it is created. By default, all item data is fully overwritten. Data elements not sent are deleted in Radial systems. See Custom Attributes for the exception to this. To keep unsent data elements as they are, use the optional merge parameter.
Upload a .csv file containing multiple items to Radial.	POST	/item-service/clients/{storeId}/upload	Files can contain new and existing items. To update an existing item, send all data elements. You cannot send only the changed items. The .csv file does not include all elements that can be transmitted via the PUT method.
Retrieve an item.	GET	/item-service/stores/{storeId}/items/{itemId}	One item per API call

For details on each endpoint, refer to the following topics:

Item Types

Item Type	Description
CUSTOM	Customization. A virtual item that represents a charge to the consumer to customize another item. The customization item includes a description of the customization options selected by the customer; for example, "Monogramming" or "Team jersey customization". Each type of customization offered to consumers must be defined as an individual item. A customization item is passed in the order message along with the item being customized.
DONATION	Donation. A virtual item that represents a consumer's donation to a charitable cause.
GC	Physical gift card. The gift card is fulfilled and then activated before the consumer receives the gift card in the shipment. Each option offered (such as choices of visual design or denominations) should be created as a separate item. The value of the gift card is always passed in the order line. Tthe client has the choice of creating a separate item for each possible dollar value of the gift card or by using one gift card SKU. If a single SKU is used for gift cards, then store reports generated at the SKU level provide less specific information about gift cards.
GIFTMESSAGE	This item contains a gift message.
GIFTWRAP	Gift wrap. A physical item representing gift wrap or a gift box. If multiple options (for example, choices of designs or colors of gift wrap or gift boxes) are offered, each option must be created as a separate item.
MERCH	A physical merchandise item, such as a shirt, a blender, or a coupon insert. At a typical store, the vast majority of items sold are Merch items.
OGC	Online gift certificate that is hosted and processed by Radial. OGCs are Radial's in-house product for gift certificates that don’t have a physical card associated with them, just a payment account number and PIN.
POSTSALEFULFILLMENT	Post-sale fulfillment. A virtual item classified separately from other virtual item types such as Donation or Warranty SKUs. These items are not fulfilled from a warehouse and should not be printed on a packing slip.
REFUNDGC	Refund Physical Gift Cards are used when refunding the value of a return or a price adjustment to the consumer when a physical gift card was used as a tender in the original sale. This item type would be used for accounting purposes to differentiate refunds from the original tender. This Item Type is optional. If not used, any refunds to the return order where a physical gift card was used reissue a GC item and not the RefundGC item.
REFUNDOGC	Refund online gift certificate. The "Refund" categorization is used for accounting purposes to differentiate refunds from the original tender.
REFUNDOGCFORCOD	Refund online gift certificate issued against a COD order.
REFUNDOGCFORCVS	Refund online gift certificate issued against a CVS order.
REFUNDVGC	Refund virtual gift cards. Used when refunding the value of a return or a price adjustment to the consumer when a virtual gift card was used as a tender in the original sale. This item type is used for accounting purposes to differentiate refunds from the original tender. It is optional to use this item type. If not used, any refunds to the return order where a virtual gift card was used reissue a VGC item and not the RefundVGC item
VGC	Virtual gift card. The gift card is not physically fulfilled, but is activated in the same way a physical gift card is. VGC is functionally similar to OGC, but processed by a third-party gift-card provider (for example, SVS or ValueLink).
WARRANTY	Product warranty. A virtual item representing a warranty purchased for another physical item on the order.
WARRANTYDEP	Dependent warranty. Can only be purchased with another item. Is not included in search results.
WARRANTYALONEDEP	Warranty item can be sold independently or with the purchase of another item. Is included in search results.
INSTALLSVCDEP	A type of installation service that can be purchased with another item. When searching, this item is not returned in the search results. This item cannot be purchased alone.
INSTALLSVCALONEDEP	A type of installation service that can be purchased independently or with another item. Is included in search results.

Dropship Required Elements

For items that are fulfilled by dropship, the item entry must include the elements listed in the following example.

Copy this code sample.

  "dropShipSupplier" : {
  "name" : "NIKE INC",
  "number" : "290-29333", 
  "partNumber" : "00197593986498" 
  }

Custom Attributes

Custom attributes can be defined in the Item Master/Item/Custom Attributes element. You can use custom attributes to pass data elements that are not explicitly defined in the Item Master schema. Each custom attribute is specified in an <Attribute> element, with a name (Attribute@name) and a value (Attribute/Value), as shown in the following example.

Important: Before you add any custom attributes, discuss your needs with your Radial representative.

Copy this code sample.

 "customAttributes": [
        {
            "name": "AltItemId",
            "value": "LAMR18"
        },

Unless you want to update, add, or delete specific attributes for an item, you don’t need to send custom attributes when you send an update. This is how custom attribute updates work:

If you send a custom attribute when you send an update for an item record:
- If the attribute does not exist, it is added.
- If the attribute exists, it is updated.
If you do not send an existing custom attribute when you send an update for an item, the attribute is not deleted and remains unchanged.
To delete a custom attribute, you must explicitly specify the delete operation for the attribute. Note: You have the option to specify an Add, Update, or Delete operation for each custom attribute; however, an operation is not required.

The following table lists the custom attributes used to modify existing orders and create new orders.

Custom Attribute Name	Description
MinOrderableQuantity	Minimum quantity that must be purchased of this item in a single order.
MaxOrderableQuantity	Maximum quantity that may be purchased of this item in a single order.
FreightClass	Dictates how (Scac and Service) and where (destination region) the product is eligible to ship.
DimensionalWeight	The “weight” used to calculate the shipping cost of bulky, lightweight packages.
DimensionalWeightUOM	Dimensional Weight Unit of Measure (for example, LBS).
ShippingChargeOverride	Item Override Shipping Charge (per unit charge).
ShippingSurchargeOverride	Item Override Shipping Surcharge (per unit surcharge).
EligibleToModify	Specifies whether the item quantity can be modified when an existing order is modified.
ProductID	Product ID that is displayed on the product page on the client site and on the ROM UI on the Item Search screen.
ProductTitle	Product title that is displayed on the product page on the client site and on the ROM UI on the Item Search screen.
ASSOCIATE_DELIVERY_ELIGIBLE	Specifies whether the item is eligible for same-day delivery by a store associate.

Examples

Your Radial Team can supply appropriate examples to fit your business needs.

Standard Item
Standard Item w/Extended Attribute(s)
Standard Item w/Custom Attribute(s)
Gift Wrap Item
Customization Item (monogram maybe?)
Virtual Item

Open API Specifications and Field Definitions

Field Definitions

Type	Field Name	Data Type	Field Rules	Is Required	Description
Item	item	complex type			Encapsulates the Item as is the root element of the payload
	catalogId	String	Size (min = 1 to max = 4)	required *	The identifier is provided by Radial for an individual or organization.
	clientId	String	Size (min = 1 to max = 32)	required *	The identifier is provided by Radial for an individual or organization.
	clientItemId	String	Size (min = 1 to max = 16)	required *	Advertised SKU number; The unique SKU-level identifier for the item. This is the retailer/client unique item ID or SKU. This is the primary key for the Item Master. Allowable Values: Text string Required: Yes Length: 15 Default Value: blank Restrictions: This item ID may not change or the new key is considered a new item.
	countryOfOrigin		Size (max = 2) Follow the ISO 3166 two letter/alpha format.	Required: No for domestic shipments but yes for international shipments.	A country in which goods were completely derived or manufactured. http://www.iso.org/iso/country_codes.htm
	description	String	Size (max = 120)		Short description of the item used in the OMS and WMS in the catalog’s base language. Stores having group sales must send a meaningful item description in the item master since the content feed is not loaded into OMS.
	freightClass	String	Size (max = 20)		Only used by Order modify. Dictates how (Scac and Service) and where (destination region) the product is eligible to ship.
	fulfillmentOverride	String			Only used for sourcing. Control the fulfillment of an item. This allows clients to override the fulfillment sourcing for any given item; for example, "StoreOnly", "WarehouseOnly", "DC001Only." Allowable Values: Text string Required: No Length: 40 Default Value: blank Restrictions: Needs to be pre-agreed on the values before sending on item master. Aliases: N/A
	giftCardTenderCode	String		required * One of: SD SP ST SV SX	Only used for Gift cards (Physical and Virtual) Type of gift card to be used for activation. Allowable values: SD TRU Digital Gift Card SP SVS Physical Gift Card ST SmartClixx Gift Card Canada SV SVS Virtual Gift Card SX SmartClixx Gift Card Note: This list may vary based on the gift card supplier.
	gii	String	leave blank		Leave blank. Internal use only. Global Item ID
	hazardousMaterialCode	String	Size (max = 4)		Configurable. Work with Radial to configure hazardous material code(s) for the item.
	itemId	String	Size (min = 1 to max = 40)	required *	This identifier includes the catalog ID and the item's unique ID within that catalog. The syntax for this identifier is: <catalogId> + "-" + <clientItemId>.
	productId	String	Size (max = 20)		Product ID that is displayed on the product page on the client site and on the ROM UI on the Item Search screen.
	productTitle	String	Size (max = 200)		Product title that is displayed on the product page on the client site and on the ROM UI on the Item Search screen..
	salesClass	String	Size (max = 25)	required *	Based on inventory availability, determines product display behavior for the item in the web store. Allowable Values: stock - Item is cartable if inventory is available and street date has passed advanceOrderOpen
	sourcingOverride	String			Only used in sourcing
	sourcingPreference	String			Only used in sourcing
	status	String	Size (max = 12) Active or Inactive		Indicates an item's availability. Allowable Values: - Active - Inactive (item is not displayed in catalog) - Discontinued
	styleDescription	String	Size (max = 255)		A short description or title of the style for the item. Allowable Values: Text string Required: No Length: 255 Default Value: blank Restrictions: N/A Aliases: N/A
	styleId	String	Size (max = 15)		A code that identifies the specific appearance type or variety in which an item is available. Allowable Values: Text string Required: Yes Length: 15 Default Value: blank Restrictions: N/A Aliases: N/A
	taxCode	String	Size (max = 5)	required	The Radial Inc-assigned tax group to which the item belongs. Allowable Values: Text string Required: No (BUT - This field is mandatory for ROM) Length: 5 Default Value: blank Restrictions: N/A Aliases: N/A
	type	String	One of: GIFT WRAP CUSTOM REFUNDOGC W VGC DONATION PF GiftMessage MERCH GC BUNDLE OGC	required	Specifies the type of item. Not restricted by the schema. Allowable Values: GIFT WRAP: Physical Gift Wrap. CUSTOM: Customization SKUs. A virtual item that represents a charge to the consumer to customize an item as well as a description of the customization options selected by the customer. REFUNDOGC: Refund Online Gift Certificate. 'Refund' used for accounting purposes to differentiate Refunds from the original tender. W: Product warranty. A virtual item representing a warranty purchased for another physical item on the order. VGC: Functionally similar to OGC’s except they are processed by a 3rd-party gift-card provider (ex: SVS or ValueLink). DONATION: Donation SKU. A virtual item that represents a consumer's donation to a charitable cause. PF: Pre Fulfill example : Donation GC: Physical Gift Cards. GiftMessage: This item is a Gift Message. MERCH: A typical physically-fulfilled item. GC: Gift Card, physical GC BUNDLE: Bundle parent SKU OGC: Online Gift Certificates that are hosted/processed by Radial Inc. They are our in-house product for gift certificates that don’t have a physical card associated with them (only a payment account number and PIN).
	bundle	true/false			Determines items included if this is a bundle product.
	dropShipped	true/false			Specifies if this item can be fulfilled using a drop shipper. Allowable Values: false - item cannot be fulfilled using a drop shipper true - item can be fulfilled using a drop shipper Required: Yes Default Value: false
	eligibleToModify	true/false			Product ID that is displayed on the product page on the client site and on the ROM UI on the Item Search screen.
	infiniteInventory	true/false			Ability to set the infinite inventory for any particular item, this is mainly used for items like warranties, virtual items, gift cards , customizations or any other service items. Default false.
	inventoryCheckEligible	true/false			Default false
	isFeedItem	true/false	not persisted **
	onPreOrder	true/false			Presell functionality. Item can be sold before on the market
	shipTogether	true/false			Ship Together program eligibility
	splitToOne	true/false			Used for Virtual Gift Card at Activation. Splits the order into multiple lines with Qty of 1 for each line
	maxGCAmount	numeric	Size Digits(integer = 15 fraction = 2)		MaxGCAmount which is mandatory if the Item is Gift Item. Used in refund order.
	maxOrderableQuantity	numeric			Maximum quantity that may be purchased of this item in a single order.
	maxShipmentProcessingDays	numeric			Maximum ship days rounded up to nearest day
	minOrderableQuantity	numeric			Minimum quantity that must be purchased of this item in a single order.
	minShipmentProcessingDays	numeric			Minimum ship days rounded down to nearest day
	brand	Brand			Encapsulates the selling name and description used to identify a product for advertising purposes.
	color	Color			Color
	streetDate	Date			Presell functionality. Earliest date the OMS will allocate the product. Default Value: blank. The ISODate format is "2023-12-15T10:00:00Z".
	dropShipSupplier	DropShipSupplier			Required with "is drop ship flag" is is true
	hierarchy	Hierarchy			Used by WMS to classify items.
	customDynamicAttributes	List of Attribute			Random key value pairs
	bundleItems	List of BundleItem			A list of Bundled Items
	images	List of Image
	sizes	List of Size
	upcs	List of UPC
	manufacturer	Manufacturer
	cartonMassDimensions	MassDimensions
	dimensionalWeight	MassDimensions			The “weight” used to calculate the shipping cost of bulky, lightweight packages.
	displayMassDimensions	MassDimensions
	shippingMassDimensions	MassDimensions
	cartonPackagingDimensions	PackagingDimensions
	displayPackagingDimensions	PackagingDimensions
	shippingPackagingDimensions	PackagingDimensions
	unitCost	Price
	shipAlone	String	Yes/No
	supplier	Supplier

Brand	brand	complex type
	name	String	Size (max = 50)		The selling and promotional name used to identify a product for advertising and name recognition purposes. Allowable Values: Text string Required: No Length: 50 Default Value: blank Restrictions: N/A Aliases: N/A
	description	List of BrandDescription			Short Description of the selling and promotional name used to identify a product for advertising and name recognition purposes. Allowable Values: Text string Required: No Length: 100 Default Value: blank Restrictions: N/A Aliases: N/A

BrandDescription	brandDescription	complex type
	locale	String	Size (max = 5)		A locale represents a specific geographical, political, or cultural region. It is used to define language, date/time formatting, numerical formatting, currency symbols, and other regional-specific settings in software applications. For example, the code "en_US" represents the English language in the United States.
	description	String	Size (max = 100)

Color	color	complex type
	code	String	Size (min = 1, max = 40)	required *
	descriptions	List of ColorDescription	Size (min = 1)	required *

ColorDescription	colorDescription	complex type
	locale	String	Size (max = 5)		A locale represents a specific geographical, political, or cultural region. Example: "en_US"
	description	String	Size (min = 1, max = 4000)	required *

Date		date type			The ISODate formats are "2023-12-15T10:00:00Z".
Date
DropShipSupplier	dropShipSupplier	complex type			If this item is fulfilled by a Drop Shipper then Supplier Number, Supplier Name, and Supplier Part Number are required. Without the three values, the FILE will be rejected.
	name	String	Size (min = 1, max = 120)	required *	Name of the Drop Ship Supplier fulfilling the item. Default Value: blank
	number	String	Size (min = 1, max = 15)	required *	Unique Radial Inc-assigned code for this supplier. Default Value: blank
	partNumber	String	Size (min = 1, max = 15)	required *	ID or SKU used by Supplier to identify this item. Default Value: blank Restrictions:

Hierarchy	hierarchy	complex type			Encapsulates the merchandise structure for the item. Primarily used for reporting. The hierarchy is client-defined. One example of use, by an apparel company might be as follows: Department = client name SubDepartment = Male, Female Class = If the SubDepartment is "Femaile", possible classes might be "blouses", "pants", "shoes" "accessories", etc.
	deptNumber	numeric		required *	Product Hierarchy Level 1 (Dept). Default Value: blank .
	deptDescription	String	Size (max = 25)		Product Hierarchy Level 1 description. Default Value: blank Offering: Interfaces and Tools
	subDeptNumber	numeric		required *	Product Hierarchy Level 2 (Sub-Dept). Default Value: blank Restrictions: N/A Aliases: N/A Offering: SOMS, Interfaces and Tools
	subDeptDescription	String	Size (max = 25)		Product Hierarchy Level 2 description. Default Value: blank Restrictions: N/A Aliases: N/A Offering: Interfaces and Tools
	classNumber	numeric		required *	Product Hierarchy Level 3 (Class). Default Value: blank Restrictions: N/A Aliases: N/A
	classDescription	String	Size (max = 25)		Product Hierarchy Level 3 description. Default Value: blank Restrictions: N/A Aliases: N/A
	subClassNumber	numeric		required *	SubClass code. Allowable Values: Default Value: blank Restrictions: N/A Aliases: N/A
	subClassDescription	String	Size (max = 25)		SubClass description. Allowable Values: Default Value: blank Restrictions: N/A Aliases: N/A

Attribute	attribute	complex type			Attributes are name/value pairs.
	name	String	Size (max = 50)	required *
	value	String	Size (max = 255)

BundleItem	bundleItem	complex type			When bundle is true, items listed are a bundle product.
	item	Item			Each items element contains an itemID and an action used to modify a bundle. There is one BundleItem occurrence for each product in a bundle.
	itemId	String			The client or vendor ID for the item to be included in the bundle. Allowable Values: Text string Required: Yes Length: 35 Default Value: blank Restrictions: N/A Aliases: N/A
	operationType	String			Add or delete
	pricePercentage	numeric			Percentage value of each child item in the bundle.
	quantity	numeric

FulfillmentTypeId	fulfillmentTypeId	enumeration	SHIP_TO_HOME, SHIP_TO_STORE, STORE_PICK_UP		Limited the choices: SHIP_TO_HOME, SHIP_TO_STORE, or STORE_PICK_UP
FulfillmentTypeId
Image	image	complex type			Meta information necessary to link to the product image
	url	String	Size (min = 1, max = 255)	required *
	type	String	Size (min = 1, max = 32)	required *
	view	String	Size (max = 32)
	height	numeric		required *
	width	numeric		required *

Size	size	complex type
	locale	String	Size (max = 5)		A locale represents a specific geographical, political, or cultural region. Example: "en_US"
	code	String	Size (min = 1, max = 40)	required *
	description	String	Size (min = 1, max = 255)	required *

UPC	upc	complex type			Universal Product Code
	upcType	String		required *
	upc	String		required *
	operationType	String

Manufacturer	manufacturer	complex type			Manufacturer
	name	String	Size (max = 50)		Company Name of the Manufacturer.
	id	String	Size (max = 50)		The code assigned to the item by the manufacturer to uniquely identify the item.
	manufacturingDate	Date			The date which the item was built/assembled by the manufacturer. Allowable Value: ISO 8601 standard with offset from UTC. The ISODate format is "2023-12-15T10:00:00Z".

MassDimensions	massDimensions	complex type			MassDimensions
	unit	String	Lower case	required *	units must be lower cased (e.g. in, ft, lb)
	weight	numeric	Size Digits(integer=14, fraction=4)	required *

PackagingDimensions	packagingDimensions	complex type			PackagingDimensions
	unit	String		required *
	width	numeric	SIze Digits(integer = 14, fraction = 4)	required *
	length	numeric	SIze Digits(integer = 14, fraction = 4)	required *
	height	numeric	SIze Digits(integer = 14, fraction = 4)	required *

Price	price	complex type			Price
	currency	String	Size (min = 1, max = 3)	required *
	value	numeric	Size Digits(integer = 19, fraction = 2)	required *

Supplier	supplier	complex type			Encapsulates the information related to the agency providing the goods or materials.
	name	String	Size (max = 50)		The name of the individual/organization responsible for providing/supplying the merchandise identified within the purchase order. Default Value: blank
	id	String	Size (max = 50)		Specifies the individual/organization that acts as a source for merchandise and services offered for sale, or for supplies and services consumed by the buyer and/or client. Default Value: blank
	partNumber	String	Size (max = 15)		Specifies Buyer and/or Client assigned SupplierPartNumber Default Value: blank