RIB Subscription Designs

3 RIB Subscription Designs

This chapter provides an overview of the RIB subscription APIs used in by Merchandising.

Allocation Subscription API

This section describes the allocation subscription API.

Functional Area

Allocation

Business Overview

This API allows an external application to create, update, and delete allocations within Merchandising. The Oracle Retail Allocation Cloud Service does not use this API to interface allocations to Merchandising. Allocations created or updated using this API include those that are based on warehouse inventory, as well as those using inventory from another transaction, such as a purchase order, another allocation, a transfer, or a shipment (Vendor ASN or BOL). When allocating using something other than warehouse inventory, the ID of the transaction must also be included.

Allocations only involve stockholding locations. This includes the ability to process allocations to both company and franchise stores, as well as any stockholding warehouse location, excepting internal finishers. If an allocation for a franchise store is received, Merchandising will also create a corresponding franchise order. This API supports multiple types of destination locations (warehouses as well as stores) as part of the detail section within the same message.

Allocation details can be created, edited, or deleted within the allocation message, including adding new locations to existing allocations, or modifying quantities for existing locations. If modifying an existing location, it assumes the passed-in quantity is an adjustment to the current quantity as opposed to an overwrite.

Details can be individually removed from an allocation if the detail is not in-transit, received, or in progress. An entire allocation can be deleted if none of details are in-transit or received or in progress.

Allocation Creation

When new allocations are being created, this API first validates that all required fields are present. After that, business-level validation on the input information will be performed. Detail line items must exist on an allocation header create message for an allocation to be created. New item location relationships will be created for allocation detail line items that did not previously exist.

Allocation Modification

Modifying an existing allocation will first validate the existence of the allocation header for modification. Only the allocation description and release date on the header can be modified.

Table 3-1 Allocation Create or Update

Message Element	Included?	Notes
Allocation	Always	Contains the unique identifier of the allocation. This should fall within the range of Merchandising IDs already designated for allocations.
Allocation Description	Always	Contains the user defined description of the allocation.
Order No.	Optional	Contains the purchase order with which the allocation is associated. Only used if the source for the allocation is a purchase order.
Item	Always	Contains the transaction level item that is being allocated.
From Location	Always	Contains the location that is the source of the allocation. This must be a valid stockholding virtual warehouse.
Release Date	Optional	Contains the earliest date on which the warehouse should ship the allocation.
Origin Indicator	Optional	Indicates the source application that sends the allocation. Valid values are Oracle Retail Advanced Inventory Planning (AIP) and externally generated (EG). It will be defaulted to EG, if not provided.
Allocation Details	Optional	Child Node
Doc ID	Optional	Contains identification number for a transfer, another allocation, bill of landing number (BOL), or advanced shipping notice (ASN) number for a purchase order. This field is populated according to documentation type and indicates where the inventory for the allocation should be sourced. This should be null if the source for the allocation is warehouse inventory or a purchase order.
Documentation type	Optional	Contains the type of allocation product source. Valid values are ASN, Transfer (TSF), Bill of Lading (BOL), or Allocation (ALLOC). When this is passed in as null, the source is assumed to be a PO or warehouse inventory if not PO number provided.

Allocation Details

New detail records can be added to an existing allocation. Modification of the existing details on the allocation is also supported by this API. If modifying an existing location, Merchandising assumes the passed-in quantity is an adjustment to the current quantity as opposed to an overwrite. The API verifies the allocation is not in-transit, received, nor in progress and that the quantity does not fall to zero or below.

Table 3-2 Allocation Details Create or Update

Message Element	Included?	Notes
To Location	Always	Contains the destination location of the allocation. This must be an active stockholding store or virtual warehouse.
To location Type	Always	Contains the type of the destination location. Valid values are S (store) and W (warehouse)
Quantity Allocated	Always	Contains the allocated quantity of the item for the destination location. When the allocation is being created this value must be a positive integer. If this value is being modified, it will contain the quantity adjusted (positive or negative), rather than an override value
In Store Date	Optional	Contains the date the item is to be in store. This date will be included in the Merchandising publication for communication to the warehouse.

Deleting Allocations

Allocation Header Delete

During an allocation header delete, on successfully validating the information in the message, the allocation header is updated to Cancelled (C) status.

Message Element	Included?	Notes
Allocation	Always	Contains the unique identifier of the allocation being deleted.
Allocation Detail	Optional	Child Node

Allocation Details Delete

The detail records are validated and deleted from the allocation on receipt of a detail delete message.

Message Element	Included?	Notes
To Location	Always	Contains the destination location being deleted.
To Location Type	Always	Contains the location type of the destination location being deleted.

Error Handling

If any errors are encountered in the validations described above, or in any of the message structure validations, a status of E is returned to the external system along with the appropriate error message. If the message has been successfully persisted, a success status (S), is returned to the external system indicating that the message has been successfully received and persisted to the Merchandising database.

Message XSD

Below are the filenames that correspond with each message type. Please consult the Oracle Retail Integration Guide for each message type for the details on the composition of each message.

Message Type	Message Type Description	XML Schema Definition (XSD)
XAllocCre	External Allocation Create via RIB	XAllocDesc.xsd
XAllocDel	External Allocation Delete via RIB	XAllocRef.xsd
XAllocDtlCre	External Allocation Detail Create via RIB	XAllocDesc.xsd
XAllocDtlDel	External Allocation Detail Delete via RIB	XAllocRef.xsd
XAllocDtlMod	External Allocation Detail Modification via RIB	XAllocDesc.xsd
XAllocMod	External Allocation Modification via RIB	XAllocDesc.xsd

Appointment Subscription API

This section describes the appointments subscription API.

Functional Area

Inventory

Business Overview

Merchandising subscribes to an appointment when merchandise arrives at a location. It also processes the appointment messages and attempts to receive against and close out the appointments. In addition, Merchandising attempts to close the document that is related to the appointment, when applicable. A document can be a purchase order, a transfer, or an allocation.

New Appointments

An appointment is created when a shipment is about to arrive at a location. After performing the business-level validation, this message will update the status to Scheduled (SC). This message contains the location-level information.

New Appointment Details

This message contains the item information associated with an appointment, including the ASN and the document number (PO, transfer or allocation).

Updated Appointments

An update message updates the status of an existing appointment if already exists. Valid values for the status column include:

SC–Scheduled
MS–Modified Scheduled
AR–Arrived
AC–Closed

Updated Appointment Details

This message updates an appointment detail record that was previously sent, such as an update to the quantity for an item. If the record doesn’t already exist, it is added.

Table 3-3 Appointment Header

Message Element	Required?	Notes
Appointment Number	Always	This field contains the unique number generated by warehouse while creating an appointment.
From Location	Always	This field contains the location where the merchandise has been sent.
To Location	Optional	Not used.
Appointment Start	Optional	Not used.
Appointment Action Status	Always	This field contains the status of the appointment. Valid values include: SC - Scheduled, MS - Modified Scheduled, AR - Arrived, and AC-Closed.

Table 3-4 Appointment Detail Message

Message Element	Required?	Notes
Item	Always	This field contains the items shipped to the location.
Unit Quantity	Always	This field contains the quantity of the item slated to be sent to the location.
PO Number	Always	This field contains the purchase order, transfer or allocation corresponding to the shipped merchandise.
Document type	Always	This field indicates the type of document corresponding to the shipped merchandise. Possible choices are Purchase Order (P), Transfer (T), or Allocation (A).
ASN Number	Optional	This field contains the advance shipping notice number associated with the appointment. It is populated only when the appointment is based on an ASN.

Delete Appointments

This message deletes any existing appointment and detail records.

Delete Detail Level Appointments

This API deletes a detail record for an existing appointment.

Table 3-5 Appointment Header

Message Element	Required?	Notes
Appointment Number	Always	This field contains appointment number being deleted.
From Location	Always	This field contains the location from which the appointment is being deleted.

Table 3-6 Appointment Detail Message

Message Element	Required?	Notes
Item	Always	This field contains the item being deleted from the appointment.
PO Number	Always	This field contains the purchase order, transfer or allocation containing the item being deleted from the appointment.
ASN Number	Optional	This field contains the advance shipping notice number associated with the item/appointment being deleted. It is populated only when the appointment is based on an ASN.

Error Handling

If any errors are encountered in the validations described above or any of the message structure validations, a status of E is returned to the external system along with the appropriate error message. If the message has been successfully persisted, a success status (S), is returned to the external system indicating that the message has been successfully received and persisted to the Merchandising database.

Message XSD

Below are the filenames that correspond with each message type. Please consult the Oracle Retail Integration Guide for each message type for the details on the composition of each message.

Message Types	Message Type Description	XML Schema Definition (XSD)
Appointcre	Appointment Create Message	AppointDesc.xsd
Appointhdrmod	Appointment Header Modify Message	AppointDesc.xsd
Appointdel	Appointment Delete Message	AppointRef.xsd
Appointdtlcre	Appointment Detail Create Message	AppointDesc.xsd
Appointdtlmod	Appointment Detail Modify Message	AppointDesc.xsd
Appointdtldel	Appointment Detail Delete Message	AppointRef.xsd

ASN Outbound Subscription API

This section describes the ASN outbound subscription API.

Functional Area

Inventory

Business Overview

Merchandising receives advanced shipping notifications (ASNs), also known as a bill of lading (BOL) messages, from a warehouse management system (WMS), like Oracle Warehouse Management Cloud, or a store inventory system like Oracle Retail Store Inventory and Operations Cloud Service (SIOCS).

These ASNs are notifications to Merchandising that inventory is moving from one location to another. These notification messages contain data that is used by Merchandising to create or modify a shipment record. ASNs are received for:

Pre-existing allocations.
Pre-existing transfers.
Externally generated transfers, created in the store or warehouse (created as transfer type of EG within Merchandising).

An ASN message may contain multiple transfers or allocations, and as a result, the shipment record in Merchandising will reflect these multiple movements of merchandise. A BOL number on the shipment record is a means of tracking one or more transfers and allocations back through the respective stock order records. Shipments for customer orders, franchise orders, and franchise returns are also managed through this API. If the receiving location is a non-stockholding location, like in the case of a warehouse shipment to a non-stockholding franchise store, or a warehouse shipment direct to a customer (that is processed through a non-stockholding store) then the shipment will be auto-received when processed by Merchandising.

Note:

ASNs related to a purchase order from a supplier are classified as an Inbound ASNs. Details for those types of expected shipments are found in the ASN In Subscription API section.

Other Notes

For customer order fulfillment, SIOCS will send an ASN Out message that does not include a ship-to location. Merchandising ignores these messages.
Store to customer fulfillment request will not have associated transfer in Merchandising. When Oracle Retail Store Inventory and Operations Cloud Service (SIOCS) ships the customer order, SIOCS will generate an Outbound ASN message with an empty To Location or with Location Type as Customer (C). Since there are no associated transfers in Merchandising, Merchandising will not process these Outbound ASN messages. The reserved inventory will be backed out in Merchandising when Merchandising processes a SALES transaction backend.
Messages consumed through this API can create new shipments or update existing shipments. A new shipment record will be created in Merchandising with Input status if the BOL number is not yet associated to any shipment record. If the BOL number is already associated to a shipment record, the shipment record will be updated accordingly.
The Universal Identification Number (UIN) child node may be included in the message, but this information is not used by Merchandising. This is used by SIOCS.
A Shipment and Carton Custom Flex Attribute child nodes can be included in the message, but this information is not used by Merchandising. This is used by SIOCS.

Shipment Message Details

When inventory is shipped from one location to another, Merchandising will be notified and will then create a shipment record based on the content of the message received. If the shipment already exists, the details of the existing shipment will be updated. The message includes the following:

ASNOUT Details

Message Element	Required?	Notes
Schedule Number	Optional	Not used by Merchandising.
Auto Receive Indicator	Optional	Not used by Merchandising.
To Location	Optional	This field contains the location where the shipment will be delivered.
To Location Type	Optional	This field contains the location type of the location where the shipment will be delivered to. Valid values are store (S), warehouse (W), or finisher (E).
To Store Type	Optional	Not used by Merchandising.
To Stockholding Indicator	Optional	Not used by Merchandising.
From Location	Always	This field contains the location from which the shipment was sourced. This applies to transfer and allocation shipments.
From Location Type	Optional	This field contains the location type of the location from which the shipment was sourced. Valid values are store (S) or warehouse (W).
From Store Type	Optional	Not used by Merchandising.
From Stockholding Indicator	Optional	Not used by Merchandising.
ASN Number	Optional	This field contains the bill of lading number associated with the shipment.
ASN Type	Optional	Not used by Merchandising.
Container Quantity	Optional	This field contains the number of boxes associated with the shipment.
BOL Number	Always	This field contains the transaction sequence number from the transfer shipment confirmation process. This is the same as the ASN Number.
Shipment Date	Optional	This field contains the date the transfer and/or allocation was shipped.
Estimated Arrival Date	Optional	This field contains the estimated arrival date when the shipment is expected to arrive at the destination.
Shipment Address 1	Optional	Not used by Merchandising.
Shipment Address 2	Optional	Not used by Merchandising.
Shipment Address 3	Optional	Not used by Merchandising.
Shipment Address 4	Optional	Not used by Merchandising.
Shipment Address 5	Optional	Not used by Merchandising.
Shipment City	Optional	Not used by Merchandising.
Shipment State	Optional	Not used by Merchandising.
Shipment Zip Code	Optional	Not used by Merchandising.
Shipment Country ID	Optional	Not used by Merchandising.
Trailer Number	Optional	Not used by Merchandising.
Seal Number	Optional	Not used by Merchandising.
Transshipment Number	Optional	Not used by Merchandising.
Comments	Optional	This field contains any miscellaneous comments about the shipment.
Carrier Code	Optional	This field contains the courier that will deliver the shipment.
Carrier Service Code	Optional	This field contains the service level code for the courier that will deliver the shipment. Valid values are found in code type CSVC. Not used by Merchandising.
System Code	Optional	Not used by Merchandising.
From Location Virtual Warehouse	Optional	Not used by Merchandising.

Child Nodes

ASNOUT Distro Details

ASNOUT Distro Details

This level of the message contains the details about the individual stock orders contained in the shipment.

Message Element	Required?	Notes
Distro Number	Always	This field contains the transfer number or allocation number associated with the shipment.
Distro Doc Type	Always	This field determines if the Distro Number specified is a Transfer (T) or an Allocation (A).
Customer Order Number	Optional	This contains the customer order number associated with the transfer on the shipment.
Fulfill Order Number	Optional	This contains the fulfillment order number associated with the customer order number for the transfer on the shipment.
Consumer Direct	Optional	Not used by Merchandising.
Comments	Optional	This field contains any comments about the stock orders contained in the shipment.

Child Nodes

ASNOUT Carton Details

ASNOUT Carton Details

This section of the message contains details about the cartons for a distro on a shipment.

Message Element	Required?	Notes
Final Location	Optional	Not used by Merchandising.
Container ID	Always	This field contains the carton number for shipments originating from the ASN process as carton shipments. This field will be zero for all shipments that are not at a carton level.
Container Weight	Optional	Not used by Merchandising.
Container Length	Optional	Not used by Merchandising.
Container Width	Optional	Not used by Merchandising.
Container Height	Optional	Not used by Merchandising.
Container Cube	Optional	Not used by Merchandising.
Expedite Flag	Optional	Not used by Merchandising.
In Store Date	Optional	Not used by Merchandising.
Tracking Number	Optional	This field contains a unique tracking number that is used to track containers through a carrier's system. Not used by Merchandising.
Freight Charge	Optional	Not used by Merchandising.
Master Container ID	Optional	Not used by Merchandising.
Comments	Optional	This field contains any comments about the shipment container.
Weight	Optional	This field contains the actual weight shipped for the container.
Weight UOM	Optional	This field contains the unit of measurement for weight (for example, pounds, kilograms) that was shipped.
Carrier Shipment Number	Optional	Not used by Merchandising.
Original Item ID	Optional	Not used by Merchandising.

Child Nodes

ASNOUT Item Details

This section outlines details about the items in the carton.

Message Element	Required?	Notes
Item ID	Always	This field contains the unique identifier for the item.
Unit Quantity	Always	This field contains the quantity of the item shipped in the carton for this shipment in the standard unit of measure.
Gross Cost	Optional	Not used by Merchandising.
Priority Level	Optional	Not used by Merchandising.
Order Line Number	Optional	This field is used to carry the customer order line number value for customer orders. This field is not used by Merchandising for non-customer orders.
Lot Number	Optional	Not used by Merchandising.
Final Location	Optional	Not used by Merchandising.
From Disposition	Optional	This value is used to determine if the quantity shipped is available or unavailable. Valid values for this field are inventory status codes (INV_STATUS_CODE) in the INV_STATUS_CODES table in Merchandising.
To Disposition	Optional	Not used by Merchandising.
Voucher Number	Optional	Not used by Merchandising.
Voucher Expiration Date	Optional	Not used by Merchandising.
Container Quantity	Optional	Not used by Merchandising.
Comments	Optional	Not used by Merchandising.
Unit Cost	Optional	This field contains the unit cost of the item in the shipment. This is used only for the Brazil Localization setup to calculate transaction code 74 (Recoverable Tax for Destination Location). In all other cases this should be NULL.
Base Cost	Optional	This value will be used for the Brazil Localization setup only to get the base cost (BC) from Fiscal Management for a transfer, which will flow into Merchandising. In all other cases this should be NULL.
Weight	Optional	This field contains the actual weight shipped. This may be included for catch weight items. If not included Merchandising will use the average weight or nominal weight for the item at the shipping location.
Weight UOM	Optional	This field contains the unit of measurement for weight (for example, pounds, kilograms) shipped. Required if weight is included in the message.

Error Handling

Message XSD

Below are the filenames that correspond with each message type. Please consult the Oracle Retail Integration Guide for each message type for the details on the composition of each message.

Message Types	Message Type Description	XML Schema Definition (XSD)
asnoutcre	ASN Outbound Create Message	ASNOutDesc.xsd

Cost Change Subscription API

This section describes the cost change subscriptions.

Functional Area

Price and Cost

Business Overview

Merchandising exposes an API that will allow external systems to update unit cost within Merchandising. Cost changes can be performed at the item level, or at the following levels of the organization hierarchy: chain, area, region, district, and store. Unit costs are updated for all stores within the location group. Because warehouses are not part of the organization hierarchy, they are only impacted by cost changes applied at the warehouse level.

All cost changes that are sent through this API are executed immediately. The cost change subscription creates both the cost change events with an effective date of the current date, as well as updates unit costs for item/locations that already exist in Merchandising. It does not create or delete item/locations in Merchandising.

In addition to RIB, Merchandising also exposes this API as a web service. The web service takes in a collection of cost changes and will return success and failure through the service response object. See the "Cost Change Service" section of this document in the "Provider Services" section of "SOAP Web Services" more information.

This API checks that the required fields are provided and checks the supplier's currency and the item status. If differentiator IDs are passed in, it verifies that they are valid for the passed in item. The API also retrieves the following:

Transaction level items, if the passed in item is an item parent
All locations based on the passed in hierarchy type and value, if provided.
All item/location combinations where the passed in supplier/country is the primary supplier/country at an item location.
All orderable buyer packs that the passed-in item or its children, if above transaction level
All item/locations on approved (and worksheet) order, if the recalculate order indicator is set to Yes.

This API will perform the following actions:

Create a cost change event in Executed status, with an effective date of the current date.
Update the unit cost in Merchandising for all item/supplier/country and item/supplier/country/locations based on the information provided.
Create price history for all item/locations that got updated as part of the cost change.
If the recalculate order indicator is Yes, update all relevant order/item/locations unit cost in merchandising.

It is important to note that cost changes sent through this API do not include estimated landed costs. The cost updated here is the default purchase cost, before any deals, that will be used for purchase orders created in Merchandising, similar to cost changes initiated in Merchandising.

The format for creating and updating cost changes is shown below.

Table 3-7 Cost Change

Message Element	Required?	Notes
Item	Yes	This field contains the item to which the cost change applies. It can be a parent item, but its item level cannot be greater than its transaction level. This cannot be a buyer pack.
Supplier	Yes	This field contains the number of the supplier. The supplier must be a valid supplier in merchandising. This can be a primary or non-primary supplier.
Origin Country ID	Yes	This field contains the identifier of the origin country of the item/supplier to which the cost change will apply. This value must be a valid country in merchandising. This can be the primary or a non-primary country.
Diff ID	No	This field contains the identifier for a differentiator. This can be used with a parent or grandparent item. This value must be a valid differentiator ID in merchandising.
Unit Cost	Yes	This field contains the new unit cost of the item in the currency specified on the message.
Recalculate Order Indicator	Yes	This field indicates if orders in approved status for items on the cost change will be recalculated with the new cost. Valid values are Yes (Y) and No (N).
Currency Code	Yes	This field contains the currency code of the unit cost. This must be a valid currency code in merchandising.
Hierarchy Level	No	This field indicates the level of the organizational hierarchy to which the cost change applies. Valid values are: CH - chain AR - area RE - region DI - district S - store W - warehouse
Cost Change Hierarchy	No	Child node
Custom Flex Attributes	No	Child node
Purchase Rate	No	This field contains the percentage of the retail price which will determine the cost paid to the supplier for a consignment or concession item.

Table 3-8 Cost Change Hierarchy

Message Element	Required?	Notes
Hierarchy Value	Yes	This field contains the hierarchy value at the specified level of the hierarchy which encompasses the locations affected by the cost change. This value must exist as a valid chain, area, region, district, store or warehouse in Merchandising.

Custom Flex Attributes

If any custom flex attributes (CFAS) for the cost change have been added or modified, it will trigger an update message. The node of the integration that supports this will contain the name of the attribute as it is defined in the group set level view, the value of the custom attribute. If it is a date attribute, the date value is in a separate field. Flex attributes can only be added to or updated; they cannot be deleted.

Table 3-9 Flex Attributes

Message Element	Required?	Notes
Name	Yes	Holds the attribute name.
Value	Conditional	Holds the value of the attribute for number and character type attributes. Either the value or the value date field should be provided.
Value Date	Conditional	Holds the date for date type attributes. Either the value or the value date field should be provided.

Error Handling

This API ensures that the correct message type is passed in for cost change messages. If the message type is invalid, an error status is returned to the external system, along with the appropriate error message. This is to inform the external system that the message type is invalid.

The standard error handling functions of Merchandising are in place in this API and return messages as appropriate to the outcome.

Message XSD

Below are the filenames that correspond with each message type. Please consult the Oracle Retail Integration Guide for each message type for the details on the composition of each message.

Message Type	Message Type Description	XML Schema Definition (XSD)
xcostchgmod	External Cost Change Modify	XCostChgDesc.xsd

Currency Exchange Rate Subscription API

This section describes the currency exchange rates subscription API.

Functional Area

Foundation

Business Overview

Currency exchange rates constitute financial information that is subscribed to by Merchandising. A currency exchange rate is the price of one country's currency expressed in another country's currency. This API assumes the currency codes are already present in Merchandising. This API supports creating new rates by date and updating existing rates for the same conversion date. Deleting previously created rates is not supported.

Table 3-10 Currency Exchange Rates

Message Element	Required?	Notes
From Currency	Yes	The source currency code of the currency exchange rate.
To Currency	Yes	The resultant currency code of the currency exchange rate.
Conversion Date	Yes	Contains the date on which the currency rate became or will become active.
Conversion Rate	Yes	The exchange rate between the two currency codes for the type and effective date.
Conversion Type	Yes	This field identifies the type of exchange rate the history exists for. Valid values are defined under code type EXTP: Consolidation – C Operational – O Letter of Credit/Bank – L Purchase Order – P Customs Entry – U Transportation - T

Error Handling

Message XSD

Here are the filenames that correspond with each message type. Please consult the RIB documentation for each message type to get a detailed picture of the composition of each message.

Message Types	Message Type Description	XML Schema Definition (XSD)
CurrRateCre	Currency Rate Create Message	CurrRateDesc.xsd
CurrRateCre	Currency Rate Modify Message	CurrRateDesc.xsd

Customer Order Fulfillment Subscription API

Functional Area

Customer Order Fulfillment

Business Overview

Merchandising provides an interface to process Customer Order Fulfillment requests from an external order management system (OMS). If the system option OMS_IND = 'Y', then Merchandising expects to receive customer orders via this API. If the system option PERSIST_CUSTOMER_DATA_IND = ‘N', personal information will not be stored in the customer order table in Merchandising.

Merchandising supports two integration methods for processing Customer Order Fulfillment messages from OMS - either through RIB or Web service. At implementation time, clients should decide on either one or the other integration method, but not both. The same core logic is used to validate and persist customer orders to Merchandising tables.

In a RIB implementation, Merchandising subscribes to Customer Order Fulfillment messages. When a customer order is created, or partially or fully cancelled, the customer order information is sent from the Order Management System (OMS) to the RIB. Merchandising subscribes to the customer order information as published from the RIB and places the information onto Merchandising tables.
In a web service implementation, Merchandising exposes a FulfillOrder Web service to create or cancel a customer order in Merchandising. OMS will invoke the service with customer order details to place the information on Merchandising tables. See Customer Order Fulfillment Service in the "SOAP Web Services" chapter of this document for more details on this method.

The Customer Order Fulfillment message staged will go through a process of validation. Records that pass validation will create new customer order records. If any validation error occurs, transaction will be rolled back, and no customer orders will be created.

There are two scenarios where a customer order fulfillment request cannot be created in Merchandising:

Due to data validation errors (for example, invalid item).
Due to 'No Inventory' - There is not enough inventory available at the source location or item is not ranged or inactive at the source location, or item is not supplied by the supplier (in a PO scenario).

Other Notes

Non-stockholding franchise stores cannot part of a fulfillment order, either as a sourcing location or as a fulfillment location.
Catch weight and transformable sellable items are not supported in this integration. To sell items that can vary by weight, like bananas through online channels, setup should be done as a regular (non-catch weight) item with a unit cost and standard UOM defined in items of eaches.
It is assumed that customer orders will be captured in the selling UOM in OMS, but that all transactions will be communicated to Merchandising in standard UOM.
If the same customer order fulfillment request is sent for a different item or for an existing item but with a different item line number, the existing PO or transfer will be updated.

The Customer Order Fulfillment messages contain information such as delivery type, source type and destination type. Based on these, the system should proceed to create a Purchase Order, Transfer or Inventory Reservation. The table below shows the customer order scenarios for the combination of delivery type, source type and destination type.

Scenario #	Source Location	Fulfillment Location	Delivery Type	Transaction created
1	Warehouse	Store	Pickup in Store	Virtual WH to Physical Store Transfer + Reservation. FulfilOrdDesc will contain: 1st leg: source_loc_type = 'WH', fulfill_loc_type = 'S' 2nd leg: source_loc_type = NULL, fulfill_loc_type = 'S'.
2	Warehouse	Store	Ship to Customer	Virtual WH to Physical Store Transfer + Reservation. FulfilOrdDesc will contain: 1st leg: source_loc_type = 'WH', fulfill_loc_type = 'S' 2nd leg: source_loc_type = NULL, fulfill_loc_type = 'S'.
3	Store A	Store B	Pickup in Store	Physical Store to Physical Store Transfer + Reservation. FulfilOrdDesc will contain: 1st leg: source_loc_type = 'ST', fulfill_loc_type = 'S' 2nd leg: source_loc_type = NULL, fulfill_loc_type = 'S'.
4	Store A	Store B	Ship to Customer	Physical Store to Physical Store Transfer + Reservation. FulfilOrdDesc will contain: 1st leg: source_loc_type = 'ST', fulfill_loc_type = 'S' 2nd leg: source_loc_type = NULL, fulfill_loc_type = 'S'.
5	NULL	Store	Pickup in Store	Reservation. FulfilOrdDesc will contain: Single-leg: source_loc_type = NULL, fulfill_loc_type = 'S'.
6	NULL	Store	Ship to Customer	Reservation. FulfilOrdDesc will contain: Single-leg: source_loc_type = NULL, fulfill_loc_type = 'S'.
7	NULL	Warehouse	Ship to Customer	Virtual WH to Virtual Store Transfer. FulfilOrdDesc will contain: Single-leg: source_loc_type = 'WH', fulfill_loc_type = 'V'.
8	Vendor	Store	Pickup in Store	Purchase Order to Physical Store + Reservation. FulfilOrdDesc will contain: 1st leg: source_loc_type = 'SU', fulfill_loc_type = 'S' 2nd leg: source_loc_type = NULL, fulfill_loc_type = 'S'.
9	Vendor	Store	Ship to Customer	Purchase Order to Physical Store+ Reservation. FulfilOrdDesc will contain: 1st leg: source_loc_type = 'SU', fulfill_loc_type = 'S' 2nd leg: source_loc_type = NULL, fulfill_loc_type = 'S'.
10	NULL	Vendor	Ship to Customer	Purchase Order to Virtual Store FulfilOrdDesc will contain: Single-leg: source_loc_type = 'SU', fulfill_loc_type = 'V'.

The customer order subscription API supports create and cancel operations using the following message types belonging to the 'fulfilord' message family:

fulfilordapprdel - used by Merchandising to cancel customer orders.
fulfilordreqdel - used by SIOCS to request a customer order cancellation. This message type is used only by SIOCS and is ignored by Merchandising.
fulfilordpocre - used to create purchase orders because of customer order fulfillment requests.
fulfilordtsfcre - used to create transfers because of customer order fulfillment requests.
fulfilordstdlvcre - used to perform inventory reservation because of customer order fulfillment requests.

The format for creating customer order fulfillment requests is shown below.

Table 3-11 Create Customer Order Fulfillment

Message Element	Required?	Notes
Customer Order Number	Yes	This field contains the master customer order number from OMS.
Fulfillment Order Number	Yes	This field contains the unique number from OMS related to the fulfillment details. A single customer order can have one or more fulfillment orders.
Source Location Type	No	This field contains the location type where the fulfillment order will be sourced. This could be either SU for supplier, ST for store, or WH for warehouse. This would only be populated for vendor, warehouse, or multi-site fulfillment orders. Both source location type and source location ID must be populated, or both should be NULL.
Source Location ID	No	This field contains the store, supplier or warehouse number associated with sourcing the fulfillment order. This would only be populated for vendor, warehouse, or multi-site fulfillment orders. Both source location type and source location ID must be populated, or both should be NULL. If the source location type is supplier, this must be a valid supplier site in Merchandising. If the source location type is store, this should be a valid stockholding customer orderable company or franchise store. If the source location type is warehouse, it can be a valid physical or virtual warehouse.
Fulfillment Location Type	No	This field indicates the location type associated with fulfilling the fulfillment order. This would be either S (for physical store) or V (for virtual store).
Fulfillment Location ID	Yes	This field indicates the store number associated with fulfilling the fulfillment order. This should always be populated with a virtual or physical store number. The fulfillment location ID should be different from the source location ID.
Partial Delivery Indicator	Yes	This field indicates if the fulfillment order can be picked and shipped partially (N) or if it should be shipped only when complete (Y).
Delivery Type	No	This field indicates the fulfillment method - ship to customer or store pickup. Valid values are S (ship direct) and C (customer pickup).
Carrier Code	No	This field indicates the carrier the order is to be shipped with, if specified on the fulfillment order.
Carrier Service Code	No	This field indicates the method that was selected for shipping by the customer placing the order (for example, Standard Shipping, Overnight, and so on). Valid values are from code type CSVC.
Consumer Delivery Date	Yes	This field indicates the desired date the delivery is required by the customer. This will be in GMT time.
Consumer Delivery Time	No	This field indicates the desired time the delivery is required by the customer. This will be in GMT time. Both Delivery Date and Delivery Time should be populated, or both should be NULL.
Delivery Charges	No	This field contains the delivery charges on drop ship. Used for Brazil implementations only. This value should be greater than 0.
Delivery Charges Currency	No	This field contains the currency of the delivery charges. It must be a valid currency code in Merchandising. Delivery Charges and Delivery Charges Currency must both be populated, or both should be NULL.
Comments	No	This field contains any comments sent by OMS about the order.
Customer Order Fulfillment Details	Yes	Child Node
Fulfillment Order Customer Details	Conditional	Child node
Flex Attributes	No	Child node Not used in Merchandising
Order Placed Store	No	This field indicates the store number associated with the location that the customer order was placed. For on-line orders this would contain the virtual store number associated with the on-line store. For orders captured in a physical store this would contain the store number for the physical store.

Table 3-12 Create Customer Order Fulfillment Details

Message Element	Required?	Notes
Item	Yes	This field indicates the item ordered by the customer.
Reference Item	No	This field indicates the reference item (barcode) ordered by the customer. This is supported for vendor drop-ships orders only.
Order Quantity SUOM	Yes	This field contains the quantity that was ordered by the customer in item's standard unit of measure.
Standard UOM	No	This field contains the item's standard unit of measure.
Transaction UOM	No	This field indicates the original transaction unit of measure the order was placed in.
Substitute Indicator	Yes	This field indicates if substitutes are allowed on a fulfillment order. This will only be used by orders passed to SIOCS.
Unit Retail	No	This field contains the unit sales retail of item on the fulfillment order. This will only be used by Brazil orders in case of warehouse fulfillment or vendor sourced POs shipped directly to the customer. It is needed for sales nota fiscal generation.
Retail Currency	No	This field contains the currency for the unit retail. This will only be used by Brazil orders in case of warehouse fulfillment or vendor sourced POs shipped directly to the customer. It is needed for sales nota fiscal generation.
Comments	No	This field is used to indicate any special instructions for the item, such as services (monograms, engrave, etc.).
Item Line Number	No	This field contains the detail item line number on the fulfillment order.

Only one customer order detail record should exist for each fulfillment order. If the system options value Retain Customer Data is set to Y and the order is fulfilled from the supplier or warehouse with the fulfillment location type as virtual store, then this node is required. If Retain Customer Data is N, then only the customer number will be retained.

Table 3-13 Create Fulfillment Order Customer Details

Message Element	Required?	Notes
Customer Number	Yes	This field indicates the number that uniquely identifies the customer in OMS.
Delivery First Name	No	This field contains the first name of the contact person at the delivery address on the fulfillment order.
Delivery Phonetic First	No	This field contains the phonetic first name of the contact person at the delivery address on the fulfillment order.
Delivery Last Name	No	This field contains the last name of the contact person at the delivery address on the fulfillment order.
Delivery Phonetic Last	No	This field contains the phonetic last name of the contact person at the delivery address on the fulfillment order.
Delivery Preferred Name	No	This field contains the preferred name of the contact person at the delivery address on the order.
Deliver Company Name	No	This field contains the company name of the contact person at the delivery address on the fulfillment order.
Deliver Address 1	No	This field contains the first line of the delivery address of the customer.
Delivery Address 2	No	This field contains the second line of the delivery address of the customer.
Delivery Address 3	No	This field contains the third line of the delivery address of the customer.
Delivery Country	No	This field contains the county portion of the delivery address.
Delivery City	No	This field contains the city portion of the delivery address.
Delivery State	No	This field contains the state portion of the delivery address.
Delivery Country ID	No	This field contains the country portion of the delivery address.
Delivery Post	No	This field contains the postal code portion of the delivery address.
Delivery Jurisdiction	No	This field identifies the jurisdiction code of the delivery country-state relationship.
Delivery Phone	No	This field contains the delivery phone number.
Delivery E-mail	No	This field contains the delivery email.
Bill First Name	No	This field contains the first name of the customer to be billed for this fulfillment order.
Bill Phonetic First	No	This field contains the phonetic first name of the customer to be billed for this fulfillment order.
Bill Last Name	No	This field contains the last name of the customer to be billed for this fulfillment order.
Bill Preferred Name	No	This field contains the preferred name of the customer to be billed for this fulfillment order.
Bill Company Name	No	This field contains the company name of the customer to be billed for this fulfillment order.
Bill Address 1	No	This field contains the first line of the billing address of the customer.
Bill Address 2	No	This field contains the second line of the billing address of the customer.
Bill Address 3	No	This field contains the third line of the billing address of the customer.
Bill Country	No	This field contains the county portion of the billing address.
Bill City	No	This field contains the city portion of the billing address.
Bill State	No	This field contains the state portion of the billing address.
Bill Country ID	No	This field contains the country portion of the billing address.
Bill Post	No	This field contains the postal code portion of the billing address.
Bill Jurisdiction	No	This field identifies the jurisdiction code for the billing country-state relationship.
Bill Phone	No	This field contains the billing phone number.
Bill E-mail	No	This field contains the billing e-mail address.

The format for cancelling customer order fulfillment requests is shown below.

Table 3-14 Cancel Customer Order Fulfillment

Message Element	Required?	Notes
Customer Order Number	Yes	Holds the master customer order number from OMS.
Fulfillment Order Number	Yes	This field contains the unique number from OMS related to the fulfillment details. A single customer order can have one or more fulfillment orders.
Source Location Type	No	This field contains the original sourcing location type for the fulfillment order being cancelled. This would be either SU for supplier, ST for store, or WH for warehouse. This would only be populated for vendor, warehouse, or multi-site fulfillment orders.
Source Location ID	No	This field contains the store, supplier or warehouse number associated with sourcing the fulfillment order being cancelled. This would only be populated for vendor, warehouse, or multi-site fulfillment orders.
Fulfillment Location Type	No	This field indicates the location type associated with fulfilling the fulfillment order being cancelled. This would be either S (for physical store) or V (for virtual store).
Fulfillment Location ID	Yes	This field indicates the store number associated with fulfilling the fulfillment order being cancelled.
Fulfillment Order Detail	Yes	Child node

Table 3-15 Cancel Customer Order Fulfillment Detail

Message Element	Required?	Notes
Item	Yes	This field contains the item cancelled by the customer.
Reference Item	No	This field contains the reference item cancelled by the customer. This is supported for vendor drop-ships orders only.
Cancel Quantity SUOM	Yes	This field contains the quantity that should be cancelled from the order in item's standard unit of measure.
Standard UOM	No	This field contains the item's standard unit of measure.
Transaction UOM	No	This field indicates the original transaction unit of measure the order is placed in.
Item Line Number	No	This field indicates the detail item line number on the fulfillment order that is being cancelled.

In a RIB implementation, once fulfillment create messages are processed in Merchandising, Merchandising will publish to the RIB a customer order fulfillment confirmation message with a message type of 'fulfilordcfmcre' via the customer order fulfillment confirmation publishing API. Confirmation messages will only be sent for customer order fulfillment creates requests that result in creating purchase orders and transfers in Merchandising. It will not be sent for cancel requests, or for customer order fulfillment requests that result in inventory reservation.

If a customer order is partially fulfilled, a confirmation message with status 'P' will be sent with details of fulfilled order quantity.
If a customer order is not fulfilled at all due to unavailable inventory, a confirmation message with status 'X' will be sent without any details.
If a customer order is fulfilled completely due to available inventory, a confirmation message with status 'C' will be sent with details for the fulfilled order quantity.

See Customer Order Fulfillment Confirmation Publication API for more details on the confirmation message sent.

Error Handling

Message XSD

Here are the filenames that correspond with each message type. Please consult the RIB documentation for each message type in order to get a detailed picture of the composition of each message.

Message Types	Message Type Description	XML Schema Definition (XSD)
Fulfilordapprdel	Fulfilment Cancel Message	FulfilOrdRef.xsd
Fulfilordreqdel	Fulfilment Cancel Request Message	FulfilOrdRef.xsd
Fulfilordpocre	Fulfilment PO Create Message	FulfilOrdDesc.xsd
Fulfilordtsfcre	Fulfilment Transfer Create Message	FulfilOrdDesc.xsd
Fulfilordstdlvcre	Fulfilment Store Delivery Create Message	FulfilOrdDesc.xsd

Differentiator Group Subscription API

This section describes the Differentiator group subscription API.

Functional Area

Items

Business Overview

This API allows external systems to create, edit, and delete differentiator groups within Merchandising. Diff ID details can be added, edited, or deleted within the diff group message. When creating a new diff group, diff ID must be included, but they can also be passed in with their own specific message type. Diff ID detail create and modify messages must also include the diff group record.

Creating Diff Groups

When a new differentiator group is created, this API will first validate that all required fields are present in the message. When creating a new differentiator group at least one detail line must also be included in the message. After that, business level validation on the input information will be performed. The tables below summarize the validation.

Table 3-16 Diff Group Header

Message Element	Required?	Notes
Differentiator Group Identifier	Yes	This field contains the unique differentiator group identifier.
Differentiator Type	Yes	This field contains the differentiator type, such as C for color. Must exist as a valid diff type in Merchandising.
Differentiator Group Description	Yes	This field contains the description of the differentiator group.
Create Date Time	No	This field contains the date and time the differentiator group was created. If it is not populated on the subscription message it will be defaulted to the time of creation in Merchandising.
Differentiator Group Detail	Conditional	Child node This is required in a diff group detail create and modify message.

Table 3-17 Diff Group Detail

Message Element	Required?	Notes
Differentiator ID	Yes	This field contains the identifier of the differentiator contained within the differentiator group. This id must be unique within the diff group and must already exist in Merchandising.
Display Seq	No	This field contains the order in which the diff ID should appear within the differentiator group, when displayed on-line.
Create Date Time	No	This field contains the date/time the differentiator ID was added to the differentiator group. If it is not populated on the subscription message it will be defaulted to the time of creation in Merchandising.

Updating Diff Groups

When updating a differentiator group, the group ID must already be present in the Merchandising. Changes can be sent for header level updates or detail level updates. If the changes are at the header level, then all of the required header level information needs to be included in the update, similar to that described above for creating a new differentiator. However, the diff details should not be included in a header only update. Fields that can be updated at the header level using this API include:

Differentiator type
Differentiator group description

For updating the record, the diff group ID is required in the header level and diff ID is required at the detail level. Fields that can be updated at the detail level using this API include:

Display seq

Deleting Diff Groups

If you are deleting a differentiator detail in the differentiator group or deleting the whole differentiator group, then the API will validate that the differentiator group is valid and that it is not associated with any items or diff ranges. If you are deleting the whole differentiator group, then no details should be included in the message. If you are deleting a detail record on the differentiator, then validation will be done to ensure that the diff ID exists on the differentiator group.

Table 3-18 Diff Group Header

Message Element	Required?	Notes
Differentiator Group Identifier	Yes	This field contains the diff group to be deleted.
Differentiator Group Detail	Conditional	Child node This is required in a diff group detail delete message.

Message Element

Required?

Notes

Differentiator Group Identifier

Yes

This field contains the diff group to be deleted.

Differentiator Group Detail

Conditional

Child node

This is required in a diff group detail delete message.

Table 3-19 Diff Group Detail

Message Element	Required?	Notes
Differentiator ID	Yes	This field contains the identifier of the differentiator that will be deleted, that is contained within the differentiator group. This id must be unique within the diff group and must already exist in Merchandising.

Error Handling

Message XSD

Below are the filenames that correspond with each message type. Please consult the Oracle Retail Integration Guide for each message type for the details on the composition of each message.

Message Types	Message Type Description	XML Schema Definition (XSD)
XDiffGrpDes	Diff Group Create and Modify	XDiffGrpDesc.xsd
XDiffGrpDtl	Diff Group Detail Create and Modify	XDiffGrpDesc.xsd
XDiffGrpRef	Diff Group Delete	XDiffGrpRef.xsd
XDiffGrpDtlRef	Diff Group Detail Delete	XDiffGrpRef

Differentiator Subscription API

This section describes the Diff ID subscription API.

Functional Area

Items

Business Overview

This API subscribes to differentiators from external systems to create, update or delete differentiators in Merchandising. This subscription API provides a means to keep Merchandising in sync with an external system. These transactions are performed immediately upon message receipt so success or failure can be communicated to the calling application.

Creating Differentiators

When a new differentiator is created, this API will first validate that all required fields are present in the message. After that, business level validation on the input information will be performed. The business validation:

verifies the diff id does not contain white space or underscores
verifies if diff id is not already present as a diff id or diff group id
verifies the diff type is a valid value on the code detail table under code type DIFF

If all the validations are met, the differentiator in the message data is created in Merchandising.

The format for creating and updating differentiators is shown below.

Table 3-20 Differentiator

Message Element	Required?	Notes
Differentiator ID	Yes	This field contains the unique identifier of the differentiator. This must be a valid value under the code type DIFF.
Differentiator Type	Yes	This field contains the identifier of the differentiator type. This value must be a valid diff_type in merchandising.
Differentiator Description	Yes	This field contains the description of the differentiator.
Industry Code	No	This field contains the unique reference number which represents all possible combinations of sizes according to the National Retail Federation.
Industry Subgroup	No	This field contains a sub-grouping code used by industry standards to further identify the differentiator.
Create Date Time	No	This contains the date and time the differentiator was created. If this field is not populated on the message it will default to the time of creation in merchandising.

Updating Differentiators

When a differentiator is updated, this API will first validate that all required fields are present in the message. After that, business level validation on the input information will be performed. If all the validations are met, the differentiator in the message data is updated in Merchandising. The message and validation is similar to that of the creating differentiators.

Deleting Differentiators

When a differentiator is deleted, this API will first validate that all required fields are present in the message. After that, business level validation on the input information will be performed. The business validation:

verifies if diff id to be deleted exists in Merchandising

If all the validations are met, the differentiator in the message data is deleted from Merchandising.

Table 3-21 Differentiator

Message Element	Required?	Notes
Differentiator ID	Yes	This field contains the unique identifier of the differentiator being deleted.

Error Handling

Message XSD

Here are the filenames that correspond with each message type. Please consult RIB documentation for each message type in order to get a detailed picture of the composition of each message.

Message Type	Message Type Description	XML Schema Definition (XSD)
xdiffidcre	Differentiator Create	XDiffIDDesc.xsd
xdiffidmod	Differentiator Modify	XDiffIDDesc.xsd
xdiffiddel	Differentiator Delete	XDiffIDRef.xsd

DSD Deals Subscription API

This section describes the DSD deals subscription API.

Functional Area

Deals

Business Overview

Direct store delivery (DSD) is the delivery of merchandise and/or services to a store without the benefit of a pre-approved purchase order, such as when the supplier drops off merchandise directly in the retailer's store. This process is common in convenience and grocery stores, where suppliers routinely come to restock merchandise. In these cases, the invoice may be given to the store (as opposed to sent to corporate), and the invoice may or may not be paid for out of the register.

Merchandising subscribes to DSD messages from the RIB. These messages notify Merchandising of a direct store delivery transaction at a location so that it may record the purchase order and account for it in the store's inventory. Merchandising also subscribes to DSD deals messages for deals applicable to any DSD order and performs the following functionalities as necessary:

Applies any deals to a DSD purchase order if the deals indicator in the message is set to Y
Creates a shipment
Receives a shipment.
Creates an invoice

Table 3-22 DSD Deals

Message Element	Required?	Notes
Order Number	Yes	This field contains the order number.
Supplier	Yes	This field contains the supplier number for the deal being created for this order, not the supplier site.
Store	Yes	This field contains the location the shipment will be delivered to.
Department	No	The department in which all the items on the order belong.
Currency Code	Yes	This field contains a code identifying the currency the supplier uses for business transactions.
Paid Indicator	Yes	This field indicates if the invoice has already been paid. Valid values are Y (invoice has already been paid) or N (invoice should be paid in accounts payable system).
External Reference Number	No	If the invoice indicator is Y (invoice has been created), the external reference number, proof of delivery number, or payment reference number must be provided.
Proof of Delivery Number	No	This field contains the proof of delivery or service number given at the time of receipt at the store. This field will also be included when the invoice is interfaced through Sales Audit.
Payment Reference Number	No	This field contains the reference number attached to the invoice payment, used when the invoice is paid from the POS system and interfaced through Sales Audit.
Payment Date	No	This field contains the date when the invoice was paid from the POS system. This field will be populated when the invoice is interfaced through Sales Audit.
Deals Indicator	Yes	This field indicates whether deals need to be applied to the order or not. Valid values are Yes (Y) and No (N).
Shipment	Yes	This field contains the corresponding shipment for the order that was applied by the deal.
Invoice Id	Yes	This field contains the invoice number for the purchase order of this deal.
Invoice Indicator	Yes	This field indicates whether an invoice was created for this receipt by the supplier. Valid values are Yes (Y) and No (N).
Receipt Date	Yes	This field contains the date of the receipt.
Quantity Sum	Yes	This field contains the total quantity for the invoice.
Cost Sum	Yes	This field contains the total merchandise cost for the invoice. This field will be held in the invoice currency.
External Receipt Number	Yes	This field holds the external transaction sequence number for the receipt.

Note:

Invoices are not created if Invoice Matching is not running, if the invoice indicator or paid indicator from the message is N, or if paid indicator on the message is Y and Sales Audit is not running.

Error Handling

Message XSD

Here are the filenames that correspond with each message type. Please see RIB documentation for each message type in order to get a detailed picture of the composition of each message.

Message Types	Message Type Description	XML Schema Definition (XSD)
dsddealscre	DSD Deals Create Message	DSDDealsDesc.xsd

DSD Receipt Subscription API

This section describes the DSD receipt subscription API.

Functional Area

Purchase Orders

Business Overview

Direct store delivery (DSD) is the delivery of merchandise to and/or the performance of services in a store without the benefit of a pre-approved purchase order. When the delivery or service occurs, the store inventory system (for example, SIOCS) informs Merchandising of the receipt, which also generates the purchase order at the same time. The receipt can include both the merchandise item as well as the non-merchandise information associated with the order. This information works in conjunction with payment details sent via Sales Audit if payment was made a part of the delivery or service at the store.

Table 3-23 DSD Receipt Header

Message Element	Required?	Notes
Supplier	Yes	This field contains the unique identifying number for a supplier for the receipt.
Origin Country ID	Yes	This field contains the identifier of the country from which the item is being sourced.
Store	Yes	This field contains the location where the items were delivered.
Department	Conditional	The department in which all the items on the order belong.
Currency Code	Yes	This field contains a code identifying the currency the supplier uses for business transactions.
Paid Indicator	Yes	This field indicates if the invoice has already been paid. Valid values are Y (invoice has already been paid) or N (invoice should be paid in accounts payable system).
External Reference Number	No	If the invoice indicator is Y (invoice has been created), the external reference number, proof of delivery number, or payment reference number must be provided.
Proof of Delivery Number	No	This field contains the proof of delivery or service number given at the time of receipt at the store. This field will also be included when the invoice is interfaced through Sales Audit.
Payment Reference Number	No	This field contains the reference number attached to the invoice payment, used when the invoice is paid from the POS system and interfaced through Sales Audit.
Payment Date	No	This field contains the date when the invoice was paid from the POS system. This field will be populated when the invoice is interfaced through Sales Audit.
Invoice Indicator	Yes	This field indicates whether an invoice was created for this receipt by the supplier. Valid values are Yes (Y) and No (N).
Deals Indicator	Yes	This field indicates whether deals need to be applied to the order or not. Valid values are Yes (Y) and No (N).
DSD Detail	No	Child node
DSD Non-Merchandise	No	Child node
External Receipt Number	No	This field holds the external transaction sequence number for the receipt.
Receipt Date	No	This field contains the date of the receipt.

Table 3-24 DSD Receipt Detail

Message Element	Required?	Notes
Item	Yes	This field contains the item in the receipt. The item must be an approved item that is at transaction level or above.
Quantity Received	Yes	This field contains the number of items received for the item/shipment combination. The value must be greater than 0.
Unit Cost	No	This field contains the cost of the item from the supplier/origin country in the supplier's currency.
Weight	No	This field contains the weight of the item in the receipt, if it is a catch weight item.
Weight UOM	No	This field contains the unit of measure of the received weight.
DSD Detail UIN	No	Child node; not used in Merchandising

Table 3-25 DSD Non-Merchandise

Message Element	Required?	Notes
Non-Merchandise Code	Yes	This field contains the non-merchandising code that will be added to an invoice for services or other non-merchandise costs associated with the order.
Non-Merchandise Amount	Yes	This field contains the amount of the non-merchandise cost that was invoiced. This field will be held in the invoice currency.
VAT Code	No	This field contains the code identifying the VAT rate that should be applied to the non-merchandise amount entered.
Service Performed Indicator	Yes	This field indicates if a service was performed for the non-merchandise cost. Valid values are yes (Y) or no (N).

Error Handling

Message XSD

Here are the filenames that correspond with each message type. Please consult the RIB documentation for each message type to get a detailed picture of the composition of each message.

Message Types	Message Type Description	XML Schema Definition (XSD)
dsdreceiptcre	DSD Receipt Create Message	DSDReceiptDesc.xsd
dsdreceiptmod	DSD Receipt Modify Message	DSDReceiptDesc.xsd

Freight Term Subscription API

This section describes the freight terms subscription API.

Functional Area

Foundation Data

Business Overview

Freight terms are financial arrangement information related to shipping that can be subscribed to by Merchandising from a financial system. Freight terms are the terms for shipping - for example, the freight terms could be a certain percentage of the total cost, a flat fee per order, and so on. After confirming the validity of the records enclosed within the message, Merchandising is updated with the information.

Creating/Updating Freight Terms

When a new freight term is created, this API will first validate that all required fields are present in the message. Required fields are terms, description, enabled flag, and start and end dates. After required field validation, the freight term record in the message will be inserted if the term does not exist. If the freight term exists, then the dates and enabled flag will be updated.

Message Element	Required?	Notes
Freight Terms	Yes	Contains a number that uniquely identifies the freight terms.
Terms Description	Yes	Contains a description of the freight terms used in the system.
Enabled Flag	Yes	Indicates whether the freight terms are valid or invalid within the respective application. Valid values are Y and N.
Active Start Date	Yes	Indicates the date for assigning an active date to the Freight Terms.
Active End Date	Yes	Indicates the date for assigning an inactive date to the Freight Terms.

Error Handling

If an error occurs in this procedure, a call will be placed to a function to build a complete error message. This message together with a status of E is returned to the external system. If the message has been successfully persisted, a success status (S), is returned to the external system indicating that the message has been successfully received and persisted to the Merchandising database.

Message XSD

Below are the filenames that correspond with each message type. Please consult the RIB documentation for each message type in order to get a detailed picture of the composition of each message.

Message Types	Message Type Description	XML Schema Definition (XSD)
FrtTermCre	Freight Term Create Message	FrtTermDesc.xsd

General Ledger Chart of Accounts Subscription API

This section describes the GL chart of accounts subscription API.

Functional Area

Financial Integration

Business Overview

This API is used when Retail Financial Integration (RFI) is not being used and integration with a financial system is a custom or to a non-Oracle financials system. When using RFI with an Oracle Financial system the Chart of Accounts Information in Merchandising and Sales Audit is created through a mapping and COA validation process.

Before Merchandising can publish stock ledger data to an external financial application, it must receive the General Ledger chart of accounts (GLCOA) structure. The chart of accounts is the financial application’s debit and credit account segments (for example, company, cost center, account, and so on). These are mapped to the transactions, locations, and product hierarchy in Merchandising when stock ledger data and Sales Audit totals are sent to the General Ledger. In some financial applications, these are known as code combination chart fields. There is also a primary account, in some systems know as a CCID that uniquely identifies the combination of segment or chart field values. Upon receipt of GLCOA message data, Merchandising populates the data to the FIF_GL_ACCT table.

Create and Update Chart of Accounts

This message is used to create new chart of account entries, as well as update existing entries. The message payload details are shown below.

Table 3-26 Chart of Accounts Create

Message Element	Required?	Notes
Primary Account	Always	This field denotes the primary account for a chart of accounts.
Attribute 1	Optional	Secondary account information. A value is required if description 1 is supplied.
Attribute 2	Optional	Secondary account information. A value is required if description 2 is supplied.
Attribute 3	Optional	Secondary account information. A value is required if description 3 is supplied.
Attribute 4	Optional	Secondary account information. A value is required if description 4 is supplied.
Attribute 5	Optional	Secondary account information. A value is required if description 5 is supplied.
Attribute 6	Optional	Secondary account information. A value is required if description 6 is supplied.
Attribute 7	Optional	Secondary account information. A value is required if description 7 is supplied.
Attribute 8	Optional	Secondary account information. A value is required if description 8 is supplied.
Attribute 9	Optional	Secondary account information. A value is required if description 9 is supplied.
Attribute 10	Optional	Secondary account information. A value is required if description 10 is supplied.
Attribute 11	Optional	Secondary account information. A value is required if description 11 is supplied.
Attribute 12	Optional	Secondary account information. A value is required if description 12 is supplied.
Attribute 13	Optional	Secondary account information. A value is required if description 13 is supplied.
Attribute 14	Optional	Secondary account information. A value is required if description 14 is supplied.
Attribute 15	Optional	Secondary account information. A value is required if description 15 is supplied.
Description 1	Optional	Description of the attribute 1 field. Required if attribute 1 is supplied.
Description 2	Optional	Description of the attribute 2 field. Required if attribute 2 is supplied.
Description 3	Optional	Description of the attribute 3 field. Required if attribute 3 is supplied.
Description 4	Optional	Description of the attribute 4 field. Required if attribute 4 is supplied.
Description 5	Optional	Description of the attribute 5 field. Required if attribute 5 is supplied.
Description 6	Optional	Description of the attribute 6 field. Required if attribute 6 is supplied.
Description 7	Optional	Description of the attribute 7 field. Required if attribute 7 is supplied.
Description 8	Optional	Description of the attribute 8 field. Required if attribute 8 is supplied.
Description 9	Optional	Description of the attribute 9 field. Required if attribute 9 is supplied.
Description 10	Optional	Description of the attribute 10 field. Required if attribute 10 is supplied.
Description 11	Optional	Description of the attribute 11 field. Required if attribute 11 is supplied.
Description 12	Optional	Description of the attribute 12 field. Required if attribute 12 is supplied.
Description 13	Optional	Description of the attribute 13 field. Required if attribute 13 is supplied.
Description 14	Optional	Description of the attribute 14 field. Required if attribute 14 is supplied.
Description 15	Optional	Description of the attribute 15 field. Required if attribute 15 is supplied.
Set of Books	Always	Indicates the set of books that these accounts apply to.

Error Handling

Message XSD

Below are the filenames that correspond with each message type. Please consult the Oracle Retail Integration Guide for each message type for the details on the composition of each message.

Message Types	Message Type Description	XML Schema Definition (XSD)
Glcoacre	GL COA Create Message	GLCOADesc.xsd

Inbound ASN Subscription API

This section describes the ASNIN subscription API.

Functional Area

Shipping and Receiving

Business Overview

A supplier or consolidator will send an advanced shipping notice (ASN) to Merchandising. Merchandising subscribes to the ASN information and places the information onto Merchandising tables depending upon the validity of the records enclosed within the ASN message.

The ASN message will consist of a header record, a series of order records, carton records, and item records. For each message, header, order, and item records will be required. The carton portion of the record is optional. If a carton record is present, however, then that carton record must contain items.

The header record will contain information about the shipment, such as where it is being shipped and when it is estimated to arrive. The order records will identify which purchase orders are associated with the shipment. If the shipment is packed in cartons, carton records will identify which items are in which cartons. The item records will contain the items on the shipments, along with the quantity shipped.

The location that is contained on the ASN will represent the expected receiving location for the order. If the location is a non-stockholding store in Merchandising, then the shipment will also be automatically received when the ASN is processed. Two types of non-stockholding stores orders are supported in this integration – franchise stores and drop ship customer orders.

Once the ship quantity is matched, an invoice is generated for Invoice Matching.

Note:

This message can also be used by stores and warehouses for inbound transfer and allocation shipments. However, for Merchandising, those shipments are all processed as an Outbound ASN.

Creating/Updating ASN

When a new ASN is created or updated, this API will first validate that all required fields are present in the message. Additionally, when creating or updating an ASN at least one detail line must also be included in the message. After that, business level validation on the input information will be performed. The tables below summarize these two types of validation.

ASN Header

Message Element	Required?	Notes
Schedule Number	Optional	Not used in Merchandising.
Auto Receive	Optional	Not used in Merchandising.
Destination Location	Optional	Contains the location that the shipment will be delivered to. For purchase orders this will always be either a store or a physical warehouse.
Destination Location Type	Optional	This column contains the destination location type of the destination location field. Valid values are 'S' = store, and 'W' = warehouse.
Destination Store Type	Optional	Not used in Merchandising
To Stockholding Indicator	Optional	Not used in Merchandising
Source Location	Optional	Not used in Merchandising
Source Location Type	Optional	Not used in Merchandising
Source Location Store Type	Optional	Not used in Merchandising
From Stockholding Indicator	Optional	Not used in Merchandising
Advance Shipment Number	Always	This column contains the advance shipping notice number associated with the shipment.
Shipment Type	Always	This column is used to determine the ship origin. If it is C, that means it is a carton shipment and the shipment origin in Merchandising is set to 6 (ASN UCC-128). Otherwise, the Merchandising shipment origin will be defaulted to 0 (ASN Shipment).
Container Quantity	Optional	Not used in Merchandising.
Bill of Lading Number	Optional	This column holds the bill of lading number associated with a shipment from the PO receiving process.
Shipment Date	Always	This column contains the date the PO was shipped.
Estimated Arrival Date	Optional	This field contains the estimated arrival date of a vendor PO shipment.
Ship Address 1	Optional	Not used in Merchandising.
Ship Address 2	Optional	Not used in Merchandising.
Ship Address 3	Optional	Not used in Merchandising.
Ship Address 4	Optional	Not used in Merchandising.
Ship Address 5	Optional	Not used in Merchandising.
Ship City	Optional	Not used in Merchandising.
Ship State	Optional	Not used in Merchandising.
Ship Postal Code	Optional	Not used in Merchandising.
Ship Country	Optional	Not used in Merchandising.
Trailer Number	Optional	Not used in Merchandising.
Seal Number	Optional	Not used in Merchandising.
Carrier Code	Optional	This column contains a code that indicates the carrier that is involved in the shipment.
Carrier Service Code	Optional	Not used in Merchandising.
Vendor Number	Always	This column contains the supplier who will provide the merchandise specified in the order.
Ship payment method	Optional	This column indicates the payment terms for freight charges associated with the order. Valid values are found in code type SHMT.
Comments	Optional	Contains any comments about the shipment.

ASN PO

Message Element	Required?	Notes
Order Number	Always	Identifies the order number which relates to the goods delivered in the shipment.
Document Type	Optional	Not used in Merchandising.
Not After Date	Optional	This column contains the last date that delivery of the order will be accepted.
Comments	Optional	This column contains any comments about the shipment.

ASN Carton Detail

This is an optional node inside the PO details. If the shipment type is C then the carton details and the items within the carton are validated.

Message Element	Required?	Notes
Final Location	Always	This will be the final destination of the carton. For a cross-dock order this will be the allocation location, otherwise it will be the direct to order location.
Container ID	Always	This column holds the UCC-128 carton number.
Container Weight	Optional	Not used in Merchandising.
Container Length	Optional	Not used in Merchandising.
Container Width	Optional	Not used in Merchandising.
Container Height	Optional	Not used in Merchandising.
Container Cube	Optional	Not used in Merchandising.
Expedite Flag	Optional	Not used in Merchandising.
In Store Date	Optional	Not used in Merchandising.
Carrier Shipment Number	Optional	Not used in Merchandising.
Tracking Number	Optional	Not used in Merchandising.
Freight Charge	Optional	Not used in Merchandising.
Master Container ID	Optional	Not used in Merchandising.

ASN Item Details

This is a mandatory node inside the PO and the optional Carton Node. For each message, header, order, and item records will be required. The carton portion of the record is optional. If a carton record is present, then that carton record must contain items in it.

Message Element	Required?	Notes
Final Location	Conditional	This column contains the final location for the order. If it is a pre-allocated order that has been pre-marked, then this is required and would contain the allocation location.
Item Number	Optional	This column contains unique identifier for the item. Either VPN, item number, or reference item must be specified in the message.
Unit Quantity	Always	This column contains the quantity of the item that is expected to be received.
Priority Level	Optional	Not used in Merchandising.
VPN	Optional	This column contains the vendor product number used to find the item number. Either VPN, item number, or reference item must be specified in the message.
Order Line Number	Optional	Not used in Merchandising
Lot Number	Optional	Not used in Merchandising.
Reference Item Number	Optional	The column contains a bar code or reference item. Either VPN, item number, or reference item must be specified in the message.
Distro Number	Optional	Not used in Merchandising.
Consumer Direct Order	Optional	Not used in Merchandising.
Customer Order Number	Optional	Not used in Merchandising.
Fulfill Order Number	Optional	Not used in Merchandising.
Distro Document Type	Optional	Not used in Merchandising.
Container Quantity	Optional	Not used in Merchandising.
Comments	Optional	Not used in Merchandising.

Note:

Universal Identification Number (UIN) Details and Flex Attribute is not used by Merchandising.

Delete ASN

When deleting an ASN, Merchandising will validate that the shipment is not in received status. If in a valid status, the shipment will be deleted. When deleting the ASN records, if Invoice Matching is integrated, it will populate the staging table for Invoice Matching to know which shipments have been purged.

Message Element	Required?	Notes
Destination Location	Optional	Contains the location that the shipment will be delivered to. For purchase orders this will always be either a store or a physical warehouse.
Destination Location Type	Optional	This column contains the destination location type of the destination location field. Valid values are 'S' = store, and 'W' = warehouse.
Destination Store Type	Optional	Not used in Merchandising
To Stockholding Indicator	Optional	Not used in Merchandising
Source Location	Optional	Not used in Merchandising
Source Location Type	Optional	Not used in Merchandising
Source Store Type	Optional	Not used in Merchandising
Source Stockholding Indicator	Optional	Not used in Merchandising
ASN Number	Always	This column contains the advance shipping notice number associated with the shipment. The delete happens based on the ASN number where the origin of shipping is through ASN shipment or through ASN UCC-128.

Error Handling

Message XSD

Below are the filenames that correspond with each message type. Please consult the Oracle Retail Integration Guide for each message type for the details on the composition of each message.

Message Types	Message Type Description	XML Schema Definition (XSD)
asnincre	ASN in Create	ASNInDesc.xsd
asninmod	ASN in Modification	ASNInDesc.xsd
asnindel	ASN in delete	ASNInRef.xsd

Inventory Adjustment Subscription API

This section describes the Inventory Adjustment Subscription API.

Functional Area

Inventory

Business Overview

Merchandising receives requests for inventory adjustments from an integration subsystem through the Inventory Adjustment Subscription API. The requests contain information about the item and location whose inventory is being adjusted, the quantity to adjust, a from and to disposition code, and the reason for the adjustment. Merchandising uses information in these requests to:

Adjust overall quantities of stock on hand for an item at a location.
Adjust the availability of item-location quantities based on status.

After initial processing and validation, Merchandising performs the following tasks:

The item/location is ranged if it does not already exist.
For total stock on hand adjustments:
- Stock on hand is updated for the item at the location, for total stock on hand adjustments.
- Stock adjustment is recorded to the Merchandising transaction level stock ledger
For status-based adjustments:
- Quantities by inventory status are adjusted for the item/location combination.
- Non-sellable quantity is updated for the item/location.
For both types, an audit trail is created for the inventory adjustment by item, location, inventory status and reason.

Note:

An adjustment can impact both total stock on hand and inventory status at the same time.

Inventory Adjustment Transaction Codes

Whenever the status or quantity of inventory changes, Merchandising writes transaction codes to adjust inventory values in the stock ledger. The types of inventory adjustment transaction codes are:

Tran code 22 - Adjustments where positive and negative adjustments are made to total stock on hand using a reason code with the COGS indicator = N. In this case, a transaction is inserted to the transaction level stock ledger for both the retail and cost value of the adjustment.
Tran code 23 - Adjustments where positive and negative adjustments are made to total stock on hand using a reason code with the COGS indicator = Y. In this case, a transaction is inserted to the transaction level stock ledger for both the retail and cost value of the adjustment.
Tran code 25 - Adjustments to inventory status, where inventory is moved to or from an unavailable or non-sellable status.

Other Notes:

One or both of the to disposition and from disposition fields must have values. Both cannot be empty.
The item must be inventoried and approved.
If the item is a simple pack catch weight item, then the weight and weight UOM are either both defined or both NULL. Weight UOM must be of the type Mass.
The item is a transaction-level or a reference item. When a reference item is passed in, its parent item (the transaction level item) has its inventory adjusted.
If adjusting a pack at a warehouse, the pack item must have its inventory tracked at the pack level (receive as type = Pack for the item/warehouse).
If the location is a warehouse, then either a virtual or physical warehouse can be supported. If it is a virtual warehouse, it must be a stockholding warehouse. If it is a physical warehouse, then the adjusted quantity is distributed among the virtual locations of the physical location.

The table below contains the details of the message as well as the validations.

Table 3-27 Inventory Adjustment Header

Message Element	Required?	Notes
Destination ID	Yes	This field contains the location where the inventory adjustment is being made.
Inventory Adjustment Detail	Yes	Child node

Table 3-28 Inventory Adjustment Detail

Message Element	Required?	Notes
Item	Yes	This contains the item for which stock is being adjusted. The item should be an approved inventory item.
Adjustment Reason Code	No	This field contains the reason for inventory adjustment. This field will only have a value for sellable inventory types.
Unit Quantity	Yes	This field contains the number of units to be added or reduced. The value should not be 0 and should be a whole number if the standard UOM of the item is EA.
Transshipment Number	No	Not used
From Disposition	Conditional	From Disposition and To Disposition should both have values or both should be NULL.
To Disposition	Conditional	From Disposition and To Disposition should both have values or both should be NULL.
From Trouble Code	No	Not used
To Trouble Code	No	Not used
From WIP Code	No	Not used
To WIP Code	No	Not used
Transaction Code	No	Not used
User ID	Yes	This field contains the name of the user who created the inventory adjustment.
Create Date Time	Yes	This field contains the date and time the inventory adjustment was made.
PO Number	No	This field contains either a PO, Allocation, BOL or Transfer number associated to the inventory adjustment based on the doc_type. The value should exist in Merchandising.
Document Type	No	This field indicates the type of document where the inventory adjustment originated from. Valid values are: P - Purchase Order T - Transfer A - Allocation
Auxiliary Reason Code	No	Not used
Weight	Conditional	This contains the weight of the item. Weight and Weight UOM should both have values or both should be NULL.
Weight UOM	Conditional	This is the unit of measurement for weight. Weight and Weight UOM should both have values or both should be NULL. This value should belong to the uom_class, MASS.
Unit Cost	No	This field contains the unit cost of the item.
Inventory Adjustment UIN	No	Child node

Table 3-29 Inventory Adjustment UIN

Message Element	Required?	Notes
Unique Identification Number	Yes	This field contains the Universal Identification Number of the item at the location.
Status	Yes	This field contains the status code of the UIN.

Error Handling

Message XSD

Below are the filenames that correspond with each message type. Please consult the Oracle Retail Integration Guide for each message type for the details on the composition of each message.

Message Types	Message Type Description	XML Schema Definition (XSD)
invadjustcre	Inventory Adjustment Create Message	InvAdjustDesc.xsd

Inventory Request Subscription API

This section describes the inventory request subscription API.

Functional Area

Inventory Request Subscription

Business Overview

Merchandising receives requests for inventory using the Inventory Request API, which allows for items to be ordered by the store and fulfilled by the Merchandising. Unlike store order replenishment, Merchandising fulfills inventory requests from the store regardless of replenishment review cycles, delivery dates, and any other factors that may restrict a request from being fulfilled.

For item/store combinations that are on the Store Order type of replenishment in Merchandising, orders will be placed using this API and then the replenishment process builds the recommended order quantity (ROQ) based on the store's requests. Requests that will not be reviewed prior to the date requested by the store are fulfilled through a one-off process (executed real-time through this API) that creates warehouse transfers and/or purchase orders to fulfill the requested quantities.

For item/location combinations that are currently using other methods of replenishment in Merchandising, the store requested quantities will be added on top of the calculated recommended order quantities to increase the overall replenishment. It can also be used for item/store combinations not on replenishment in Merchandising. In these cases, the one-off process described above will be used to create a POs or transfers utilizing attributes defined for the item/location.

Other validation notes:

Order quantities will be rounded using the store order multiple when an order is created for a warehouse or to the case size if ordering from the supplier.
Upcharges will always be applied to a transfer, when they can be defaulted.
Merchandising will validate that all items belong to the same department when department level ordering (supplier) or department level transfers (warehouse) are being used.
The store must be open for ordering.

Creating Inventory Requests

The table below summarizes these validations applicable for this API.

Message Element	Required?	Notes
Item	Always	The item must be approved, orderable, and inventoried item; it must also be ranged to the location in the inventory request and must be active at that location.
Unit of purchase	Always	Unit of purchase must either be eaches (EA), case (CA), or pallet (PA).
Need date	Always	This is the date that the store needs the item by.
Need quantity	Always	This is the quantity being requested in standard UOM.
Delivery slot	Optional	Valid delivery slots are in the delivery_slot table.
Store	Always	The store must exist as a valid stockholding store in Merchandising.
Request type	Optional	Store order (SO) or Inventory Request (IR) If the request type is SO or blank, then replenishment method should be store order. If the request type is IR, delivery slot should be provided.

Error Handling

Message XSD

Here are the filenames that correspond with each message type. Please consult the RIB documentation for each message type in order to get a detailed picture of the composition of each message.

Message Types	Message Type Description	XML Schema Definition (XSD)
InvReqCre	Inventory Request Create Message	InvReqDesc.xsd

Item Location Subscription API

This section describes the item location subscription API.

Functional Area

Items

Business Overview

This API subscribes to item location from external systems to create or modify item location combinations in Merchandising. Item/location relationships can be created for an item and a single location or using one of the levels of the organizational hierarchy.

Creating Locations

When a new item location is created, this API will first validate that all required fields are present in the message. Additionally, when creating a new item location at least one detail line must also be included in the message. After that, business level validation on the input information will be performed. The tables below summarize these two types of validation.

Updating Item Location

When updating an item location, this API will first validate that all required fields are present in the message. Additionally, when updating an item location at least one detail line must also be included in the message. After that, business level validation on the input information will be performed. The tables below summarize these two types of validation.

Table 3-30 Item Location Create and Update

Message Element	Required?	Notes
Item	Yes	Must be an existing item in Merchandising.
Hier Level	Yes	Must be a valid organization hierarchy level. Valid values are chain (CH), area (AR), region (RE), district (DI), store (S) or warehouse (W).

Table 3-31 Item Location Detail Create and Update

Message Element	Required?	Notes
Hier Value	Yes	Must be valid ID for a chain, area, region, district, store or warehouse given the Hier Level.
Status	Yes	For new item/location relationships, this must be active (A), inactive (I), discontinued (C). If it is an update to an existing item/location, valid values are active (A), inactive (I), discontinued (C), or delete (D).
Store Ord Mult	Yes	This contains the multiple in which the item needs to be shipped from a warehouse to the location. Valid values are found in ORML.
Source Method	Conditional	This field determines the primary sourcing for this item/location. Valid values are Supplier (S) or Warehouse (W). Must either be supplier site or virtual warehouse. Additionally, valid value is dependent on the Hier Level: For Hier Level of store (S): Source Method is required to be warehouse (W) for wholesale or franchise stores. For Hier Level of warehouse (W) Source Method is required to be supplier (S) Source Method must be W if the Source Warehouse is populated.
Source Warehouse	Conditional	This determines which warehouse is the sourcing location for this item/location. This value is required if the sourcing method is Warehouse. Must be a valid virtual warehouse. Additionally, item should already be ranged to the Source Warehouse.
Receive as Type	Conditional	This determines whether the stock on hand for a pack component item or the buyer pack itself will be updated when a buyer pack is received at a warehouse. Valid values are Each (E) or Pack (P). Must be blank if Item is not a pack or Hier Level is not warehouse. Must be eaches (E), when Hier Level is warehouse and Hier Value is an internal finisher. Must be pack (P), when Item is a vendor pack. Must be pack (P), when Item order as type is pack and warehouse break pack indicator is N.
Taxable Indicator	No	This field determines if the item is taxable at the location. Valid values are Yes (Y) or No (N).
UIN Type	No	This contains the type of unique identification number (UIN) used to identify the instances of the item at the location. Valid values are found in code type UINT.
UIN Label	Conditional	This contains the label for the unique identification number (UIN) when displayed. Valid values are found in code type ULBL. UIN Label is required if UIN Type is populated.
Ext UIN Indicator	No	This indicates if unique identification number (UIN) is being generated in the external system. Valid values are Yes (Y) or No (N).
Primary Supplier	No	This contains the primary supplier site for the item/location.
Primary Country	No	This contains the primary country of sourcing for the item/location.
Local Item Description	No	Could be used to have an alternate description for the item at this language, such as in another language.
Ti	No	This determines the number of shipping units (cases) that make up one tier of a pallet. Multiply TI x HI to get total number of cases for a pallet.
Hi	No	This determines the number of tiers that make up a complete pallet (height). Multiply TI x HI to get total number of cases for a pallet.
Daily Waste Percent	No	This defines the average percentage lost from inventory on a daily basis due to natural wastage.
Local Short Description	No	Could be used to provide an alternative short description for the item at this location, such as in another language.
UIN Type	No	This contains the type unique identification number (UIN) used to identify the instances of the item at the location. Valid values are found in code type UINT.
UIN Label	No	This contains the label for the unique identification number (UIN) when displayed. Valid values are found in code type ULBL.
Capture Time	No	This determines when the unique identification number (UIN) should be captured for an item during transaction processing. Valid values are found in code type CPTM.
Unit Cost	No	This contains the current unit cost of the item based on the primary supplier/country for the location in local currency.
Cost UOM	No	This is used to allow costs to be managed in a different UOM than the standard UOM.
Purchase Type	No	This defines whether the item is owned, consignment stock, or a concession item at the location. Valid values are: 0 - Owned 1 - Consignment 2 - Concession
Calculation Basis	No	This determines if the cost for the consignment/concession item will be managed either based on cost per unit or as a percentage of retail. Valid values are: C - Cost per Unit P - Purchase Rate
Purchase Rate	No	This contains the percentage of the retail price which will determine the cost paid to the supplier for a consignment or concession item, if the calculation basis for the item/location is Purchase Rate.
Promotable Indicator	No	This determines whether the retailer is allowed to specify if the item is promotable or not. Valid values are Yes (Y) or No (N).

Table 3-32 Item Location Trait Create or Update

Message Element	Required?	Notes
Launch Date	No	This holds the date when the item is initially sold at the location.
Quantity Key Options	No	This field determines whether the quantity key on a POS can be used for this item at the location. Valid values are found in code type RPO.
Manual Price Entry	No	This field determines whether the price for the item/location can be entered manually on POS. Valid values are found in code type RPO.
Deposit Code	No	This determines whether a deposit is associated with this item at the location. Valid values are found in code DEPO.
Food Stamp	No	This determines whether the item is approved for food stamps at the location. Valid values are Yes (Y) or No (N).
WIC	No	This determines whether the item is approved for WIC at the location. Valid values are Yes (Y) or No (N).
Proportional Tare Percent	No	This is the proportion of the total weight of a unit of an item that is the packaging. For example, if the tare item is bulk candy, this is the proportional of the total weight of one piece of candy that is the candy wrapper.
Fixed Tare Value	No	This is the tare of the packaging. For example, if the tare item is bulk candy, this is weight of the bag and twist tie.
Fixed Tare UOM	No	This contains the unit of measure value associated with the tare value.
Reward Eligible	No	This determines whether the item is legally valid for various types of bonus point/award programs at the location. Valid values are Yes (Y) or No (N).
National Brand Competitor Item	No	This contains the nationally branded item to which it will be compared to. Will contain a valid item ID.
Return Policy	No	This determines the return policy for the item at the location. Valid values are found in code type RETP.
Stop Sale	No	This defines if the sale of the item should be stopped immediately at the location (i.e., in case of recall etc.). Valid values are Yes (Y) or No (N).
Electronic Market Clubs	No	This contains the code that represents the marketing clubs to which the item belongs to at the location. Valid values are found in code type MKTC.
Report Code	No	This determines to which reports the location should run. Valid values are found in code type REPC.
Shelf Life on Selection	No	This contains the required shelf life for an item on selection in days.
Shelf Life on Receipt	No	This contains the required shelf life for an item on receipt in days.
Investment Buy Shelf Life	No	Indicates the shelf life in days for this item at this location, which is used by the Investment Buy replenishment processing.
Store Reorderable	No	This determines whether the store may re-order the item. Valid values are Yes (Y) or No (N).
Rack Size	No	This determines the rack size that should be used for the item.
Full Pallet Item	No	This determines whether a store must reorder an item in full pallets only. Valid values are Yes (Y) or No (N).
In Store Market Basket	No	This contains the in-store market basket code for the item/location combination. Valid values are found in code type STMB.
Storage Location	No	This contains the current storage location or bin number for the item at the location.
Alternate Storage Location	No	This contains the preferred alternate storage location or bin number for the item at the location.
Returnable	No	This determines if the item can be returned at this location. Valid values are Y or N.
Refundable	No	This determines if the item is refundable at the location or not. Valid values are Yes (Y) or No (N).
Back Order	No	This determines if the item can be back ordered to the location. Valid values are Yes (Y) or No (N).

Flex Attributes

If you have defined any custom flex attributes (CFAS) for item locations, then they can be integrated as part of this API. The node of the integration that supports this will accept the name of the attribute as it is defined in the group set level view and the value for the attribute. For date type CFAS attributes, there is a separate value column to pass the value.

Table 3-33 Flex Attributes

Message Element	Required?	Notes
Name	Yes	Holds the attribute name.
Value	No	Holds the value of the attribute for number and character type attributes
Value Date	No	Holds the date for date type attributes.

Error Handling

If any errors are encountered in the validations described above or any of the message structure validations, a status of E is returned to the external system along with the appropriate error message. If the message has been successfully persisted, a success status (S) is returned to the external system, indicating that the message has been successfully received and persisted to the Merchandising database.

Message XSD

Below are the filenames that correspond with each message type. Consult the RIB documentation for each message type in order to get a detailed picture of the composition of each message.

Message Type	Message Type Description	XML Schema Definition (XSD)
xitemloccre	External item locations create	XItemlocDesc.xsd
xitemlocmod	External item locations modification	XItemlocDesc.xsd

Item Reclassification Subscription API

This section describes the item reclassification subscription API.

Functional Area

Merchandise Hierarchy

Business Overview

Merchandising subscribes to item reclassification messages, which update the department, class, and/or subclass for the item, that are published by an external system. This subscription is necessary in order to keep Merchandising in sync with the external system. This API allows external systems to create and delete item reclassification events within Merchandising.

Only the following item types can be interfaced using this API:

Transaction level items without a parent
Parent items, whose child items are the transaction level, such as with a fashion style (parent) and its SKUs (children)
Complex pack items - but the reclassification cannot include the component items in the pack

The following item types cannot be reclassified:

Child items with a parent - these are reclassified when the parent is updated
Reference items - these below transaction level items are automatically reclassified with the transaction level item or its parent, whichever applies
Simple Packs - these are reclassified when the component item is reclassified

This API allows a reclassification event to be created for a department/class/subclass combination that does not yet exist. This is valid as long as the merchandise hierarchy is scheduled to be created on or prior to the reclassification taking effect.

New/Updated Reclassifications

When a reclassification is created, both a reclassification header and detail are required. For an update, either to update the header or add a detail, all fields in both header and detail nodes are required.

Reclassification Header

Message Element	Required?	Notes
Reclass Number	Always	This is the unique number which identifies the reclassification event. For a detail create message, the reclassification number should already exist in Merchandising.
Reclass Description	Always	This is the description of the reclassification event.
Reclass Date	Always	The date on which the reclassification event is scheduled to take place. The date must be at least a day after the current business day.
To Department	Always	The department to which the item will belong after the reclassification event. The dept/class/subclass combination must already exist or will be created before the reclassification date.
To Class	Always	The class to which the item will belong after the reclassification event. The dept/class/subclass combination must already exist or will be created before the reclassification date.
To Subclass	Always	The subclass to which the item will belong after the reclassification event. The dept/class/subclass combination must already exist or will be created before the reclassification date.
Item Reclassification Detail	Always	Child node

Reclassification Detail

Message Element

Required?

Notes

Item

Always

This is the item that will be reclassified. Following are the validations that will be done on upload:

Must be a level 1 item

If the item is a pack, it should not be a simple pack.

Must not be on any approved order

Must not be an orderable buyer pack that can be received as component items.

Must not be on an existing reclassification

Deleting Reclassifications

Reclassifications can be deleted by:

Deleting a single reclassification event
Deleting specific items on a reclassification event
Deleting all reclassification events on a particular event date
Deleting all reclassification events

Reclassification Header

Message Element	Required?	Notes
Reclass Number	Conditional	The reclassification event that will be deleted. If this is populated in a header delete message, then the specific reclassification event will be deleted. This is required in a header delete message if Reclass Date is NULL and the Purge All indicator is N or NULL. If Reclass Number is provided, Reclass Date should be NULL.
Reclass Date	Conditional	The date of the reclassification events to be deleted. If this is populated in a header delete message, then all reclassification events occurring on the given date will be deleted. This is required in a header delete message if the Reclass Number is NULL and the Purge All indicator is N or NULL. If Reclass Date is provided, Reclass Number should be NULL.
Purge All	Conditional	If this field is Y in a header delete message, then all item reclassification events will be deleted. When the purge indicator is Y, both Reclass Number and Reclass date should be NULL. If the Purge All indicator is NULL or N, only the Reclass Number or the Reclass date should contain a value.
Reclassification Detail	Optional	Child Node

Reclassification Detail

Message Element	Required?	Notes
Item	Conditional	This is the item within a reclassification event that will be deleted. This is the only field required for detail delete messages as an item can only exist in one reclassification event. The entire reclassification event will be deleted when no item detail exists after detail deletion.

Error Handling

Message XSD

Here are the filenames that correspond with each message type. Please consult the RIB documentation for each message type in order to get a detailed picture of the composition of each message.

Message Type	Message Type Description	XML Schema Definition (XSD)
xitemrclscre	External item reclassification create	XItemRclsDesc.xsd
xitemrclsdtlcre	External item reclassification detail create	XItemRclsDesc.xsd
Xitemrclsdel	External item reclassification delete	XitemRclsRef.xsd
Xitemrclsdtldel	External item reclassification detail delete	XItemRclsRef.xsd

Item Subscription API

This section describes the item subscription API.

Functional Area

Items

Business Overview

This API subscribes to items from external systems to create, update or delete items in Merchandising. This subscription API provides a means to not only create, update and delete items but also create, update, and delete other details of the item structure.

Item messages include the detail nodes for the supplier and supplier/country. If the item is not a non-sellable pack, the item/zone/price node is also required. Optional nodes can be included in the message for supplier/country, supplier/country/location, pack components, item/VAT, dimension, UDA, season, image, translations, HTS, assessments, expenses, and upcharges.

This API supports the insertion of data into the Item Induction staging tables based on the data sent through Oracle Retail Integration Bus (RIB), without requiring that the data sent to be functionally complete. If a complete set of item data is sent by the external system through this API, then it is possible to automatically trigger the upload of the data directly into Merchandising by setting a flag in the RIB message, such that item information is uploaded without further user interaction.

Items must be created and maintained following a logical hierarchy as outlined by the referential integrity of the item database tables: Item parents before child items; item components before items that are packs; items before item-suppliers; item/suppliers before item/supplier/countries; items before item/locations (a separate API), and so on. Failing to do so results in message failure.

The auto-creation of item children using differentiator records attached to an item parent, as currently occurs using Merchandising online processes, is not supported in this API.

These transactions are performed immediately upon message receipt so success or failure can be communicated to the calling application.

Creating Items

When a new item is created, this API will first validate that all required fields are present in the message. After that, business level validation on the input information will be performed. If all the validations are met, the item in the message data is created in Merchandising. The tables below summarize these two types of validation.

Header Level Validation

Message Element	Required?	Notes
Item	Always	The unique identifier of the main item on the message.
Item parent	Optional	Must be an existing item in Merchandising.
Item grandparent	Optional	Must be an existing item in Merchandising.
Pack indicator	Optional	Valid values are Y and N. The value Y indicates this item is a pack item.
Item level	Optional	Valid values are 1 (single level or pack item), 2 (child item), and 3 (grandchild item).
Transaction level	Optional	Valid values are 1, 2, and 3.
Differentiator 1	Optional	Must be an existing differentiator or differentiator group in Merchandising. If the item on the message is a parent. this field may contain a differentiator group ID.
Differentiator 2	Optional	same as Differentiator 1.
Differentiator 3	Optional	same as Differentiator 1.
Differentiator 4	Optional	same as Differentiator 1.
Department	Always	Must be an existing department in Merchandising.
Class	Optional	Must be an existing class in the dept in Merchandising.
Subclass	Optional	Must be an existing subclass in the dept/class in Merchandising.
Item description	Always	Contains the complete, long description for the item being created.
Item supplier country location hierarchy level	Optional	Must be a valid organization hierarchy level. Valid values are: A - Area AI - All Internal Finishers AS - All Stores AW - All Warehouses D - District DW - Default Warehouse I - Internal Finisher L - Location Trait PW - Physical Warehouse R - Region S - Store T - Transfer Zone W - Warehouse
Item zone price hierarchy level	Optional	Must be a valid organization hierarchy level. Valid values are chain (C), area (A), region (R), district (D), store (S) or warehouse (W). Must be null if the item is a non-sellable pack.
Short Description	Optional	Contains a shortened description of the item being created. Generally, this description would be used by other systems where it is problematic to display the full long description (for example, a POS system, or customer receipt).
Cost zone group id	Optional	Must be an existing cost zone in Merchandising. Must be null if landed cost is not being used in the system or the item is an orderable buyer pack.
Standard UOM	Optional	Must be a valid UOM. Defaulted to Eaches (EA), if not populated in the message.
Store order multiple	Optional	Valid values are Cases (C), Inners (I), and Eaches (E).
Forecast indicator	Optional	Indicates if this item will have a sales forecast created for it by a forecasting module. Valid values are Y and N. Must be N if the item is a pack.
Simple pack indicator	Conditional	Valid values are Y and N. This field is required if the item is a pack.
Contains inner indicator	Always	Valid values are Y and N. This should be Y if the item is a pack and at least one component item is a pack. Otherwise, it should be N.
Sellable indicator	Optional	Indicates if this item will be made available for sale to end consumers. Valid values are Y and N. It should be Y for a non-pack item.
Orderable indicator	Optional	Indicates if this item will be orderable. Valid values are Y and N. It should be Y for a non-pack item.
Pack type	Optional	Valid values are buyer (B) and vendor (V). Must be Null for a non-pack item.
Order as type	Optional	Must be a valid code from code type PARC if populated: E - Eaches P - Pack Must be Null for a non-pack item.
Comments	Optional	Free form text
Create datetime	Optional
Status	Optional	Valid values are worksheet (W), submitted (S), approved (A) and deleted (D).
UOM conversion factor	Optional
Package size	Optional
Handling temperature	Optional	Must be a valid code from code type HTMP if populated.
Handling sensitivity	Optional	Must be a valid code from code type HSEN if populated.
Manufacturer's recommended retail	Optional
Waste type	Optional	Must contain either: SL - Sales Wastage SP - Spoilage Wastage
Waste percentage	Optional	Must be greater than 0 or less than 100 if populated.
Item number type	Optional	Must be a valid code from code type UPCT if populated (note: new codes for this code type are not supported): EAN13 - EAN/UCC-13 EAN13S - EAN/UCC-13 with Supplement EAN8 - EAN/UCC-8 ISBN10 - ISBN-10 ISBN13 - ISBN-13 ITEM - Oracle Retail Item Number MANL - Manual NDC - NDC/NHRIC - National Drug Code PLU - PLU SSCC - SSCC Shipper Carton UCC14 - EAN/UCC-14 UPC-A - UCC12 UPC-AS - UCC12 with Supplement UPC-E - UCC8 UPC-ES - UCC8 with Supplement VPLU - Variable Weight PLU
Catch weight indicator	Optional	Indicates if this item should be weighed upon receipt. Valid values are Y and N.
Constant dimension indicator	Optional	Valid values are Y and N.
Gift wrap indicator	Optional	Valid values are Y and N.
Ship alone indicator	Optional	Valid values are Y and N.
External source system	Optional	Not used by Merchandising.
Size group 1	Optional	Not used by Merchandising.
Size group 2	Optional	Not used by Merchandising.
Size 1	Optional	Not used by Merchandising.
Size 2	Optional	Not used by Merchandising.
Color	Optional	Not used by Merchandising.
System indicator	Optional	Not used by Merchandising.
UPC supplement	Optional	Not used by Merchandising.
UPC type	Optional	Not used by Merchandising.
Primary UPC indicator	Optional	Not used by Merchandising.
Primary replenishment indicator	Optional	Not used by Merchandising.
Item aggregate indicator	Optional	Used only for a parent level item. Used in conjunction with the Diff 1-4 aggregate indicators to define which diff values should be used in aggregations along with the parent item, for example, to specify a style (parent item) /color (diff) aggregation. Valid values are Y and N.
Differentiator 1 aggregate indicator	Optional	Valid values are Y and N.
Differentiator 2 aggregate indicator	Optional	Valid values are Y and N.
Differentiator 3 aggregate indicator	Optional	Valid values are Y and N.
Differentiator 4 aggregate indicator	Optional	Valid values are Y and N.
Perishable indicator	Optional	Valid values are Y and N.
Notional pack indicator	Optional	Valid values are Y and N.
Stock on Hand inquiry at pack indicator	Optional	Valid values are Y and N.
AIP case type	Optional	Must be one of the following if populated: F - Formal I - Informal
Order type	Optional	Must be one of the following if populated: F - Fixed Weight V - Variable Weight
Sale type	Optional	Must be one of the following if populated: L - Loose Weight V - Variable Weight Each
Catch weight UOM	Optional
Deposit item type	Optional	Valid values are: E - Contents A - Container Z - Crate T - Returned Item (Empty bottle)
Inventory indicator	Optional	Indicates if inventory will be managed for this item. Valid values are Y and N.
Item transformation indicator	Optional	Valid values are Y and N.
Container item	Conditional	Required if the Deposit item type is E.
Package UOM	Optional
Format ID	Optional	Required for Variable PLU item types.
Prefix	Optional
Brand	Optional	Must be an existing brand in Merchandising if populated.
Product classification	Optional	Must be a valid code from code type PCLA if populated.
Item description secondary	Optional
Description uppercase	Optional
Merchandise indicator	Optional	Valid values are Y and N.
Original retail	Optional
Retail label type	Optional	Must be a valid code from code type RTLT if populated.
Retail label value	Optional
Default waste percentage	Always	Must be NULL for below transactional level items. Must be greater than 0 and less than 100, if populated. For transactional level or above items, this field must be populated if wastage type is SP.
Item service level	Optional
Check UDA indicator	Optional
Deposit in price per UOM	Optional	Required if deposit item type is E. Valid values are: E - Exclusive of Deposit Amount I - Inclusive of Deposit Amount
Attempt RMS load	Always	Valid values are STG and Merchandising. The value STG indicates the item will be loaded into induction staging environment as an incomplete item. The value Merchandising indicates the item is complete and an attempt to create the item in Merchandising will be made. In the case of Merchandising, the item will be subject to all validations for a completed item.

A pack item may be created by providing the component item information while creating the item. This detail is required if item is a pack item. Below are the validations:

Message Element

Required?

Notes

Component item

Always

Must be an existing item in Merchandising.

Pack quantity

Always

Must be an integer if standard UOM is 'EA'.

Must be greater than 0.

Additionally, item zone prices may be updated together with the creation of a new item. Below are the validations:

Message Element	Required?	Notes
Hierarchy ID	Always
Base retail Indicator	Optional	Not used by Merchandising.
Selling unit retail	Optional
Selling UOM	Optional	Unit of Measure for the selling unit retail. UOM must be from either the QTY, MASS, VOL, AREA or DIMEN class.
Multi selling UOM	Optional	Unit of Measure for the multi-selling units and retail. UOM must be from either the QTY, MASS, VOL, AREA or DIMEN class.
Country ID	Optional
Currency code	Optional	Not used by Merchandising.
Multi units	Optional	Must be populated only if multi-unit retail is populated. Must be greater than 1 if populated.
Multi-unit retail	Optional	Must be greater than 0.

If the above validations pass, then the item will be created with the status defined in the message. If the status in the message is approved, then the item will also be subjected to a series of approval checks. For an item to be successfully approved, mandatory information such as supplier, supplier country, component item information (if item is a pack) is required to be passed as part of the item message. If the item cannot be approved, it will not be created.

You can also include following information on the item - expenses, HTS and assessments, tickets, UDA, VAT (for SVAT tax type), Upcharges, Images, Seasons, Item supplier country locations. If included, these will be created simultaneously with the creation of the item.

Updating Items

Updates can be made to the items that are in Worksheet, Submitted or Approved. For the update messages, the API will validate that the item number included in the message already exists in Merchandising.

Header Level Updates

Only header level fields need to be provided for header level updates. Any item details included in the message will be ignored for a header level update message. There are certain fields that are not allowed to be updated at header level depending on the status, and if these are still provided in the message, appropriate error message will be returned.

Deleting Items

If you are deleting an item, the API will first validate that the item number is valid. The item number is the only required field for a header delete message. If the item does not exist in Merchandising a reject message will be returned.

Optionally the item detail records can be deleted by integrating as part of the item delete message.

Table 3-34 Item Delete

Message Element	Required?	Notes
Item	Always	Must be an existing item in Merchandising.
Hierarchy Level	Optional	Not used
Item Country	Optional	Child Node
Item Supplier	Optional	Child Node
Item VAT	Optional	Child Node
Item Image	Optional	Child Node
Item Season	Optional	Child Node
Item UDA	Optional	Child Node
Item Pack	Optional	Not used.
System Indicator	Optional	Not used.
UPC Supplement	Optional	Not used.
Item Header Translation	Optional	Child Node
Item HTS	Optional	Child Node
Item Expenses	Optional	Child Node
Item Ticket	Optional	Child Node
Item Up-Charges	Optional	Child Node

Creating an Item Supplier

An item supplier may be created together with the creation of a new item or added to an existing item. Below are the message details and validations:

Message Element	Required?	Notes
Supplier	Always	Must be an existing supplier in Merchandising.
Primary supp indicator	Always	Indicates if this supplier is the primary supplier for the item. An item can only have one primary supplier. Valid values are Y and N.
VPN	Optional	Vendor Part/Product Number. Must not contain the new line, pipe, linefeed or semicolon characters.
Supplier label	Optional
Consignment rate	Optional	Used only for consignment items, to specific the rate of consignment (the percentage of the retail price that will be remitted to the supplier).
Supp discontinue date	Optional	Must be greater than or equal vdate.
Direct ship indicator	Optional	Indicates if this item can be directly shipped to end consumers from this supplier. Valid values are Y and N.
Pallet name	Optional	Must be a valid code from code type PALN if populated: FLA - Flat PAL – Pallet Additional codes can be added to the code type.
Case name	Optional	Must be a valid code from code type CASN if populated: BA - Barrel BBL - Barrel BE - Bundle BG - Bag BI - Bin BJ - Bucket BK - Basket BX - Box CA - Can CON - Container CR - Crate CS - Case CT - Carton PACK - Pack PO – Pot Additional codes can be added to the code type.
Inner name	Always	Must be a valid code from code type INRN if populated: EA - Eaches INR - Inner SCS - Sub-Case SPACK - Sub-Pack Additional codes can be added to the code type.
Primary case size	Conditional	Required for an orderable item that has been configured for Informal (I) case types.
Supplier differentiator 1	Optional
Supplier differentiator 2	Optional
Supplier differentiator 3	Optional
Supplier differentiator 4	Optional
Concession rate	Always	Required for items defined as concession items.
Default expense profiles indicator	Optional

Updating an Item Supplier

In order to update an item's supplier information, the supplier must exist for the item in Merchandising, otherwise, an error will be returned. All fields identified in the create section above are updateable and will go through the same validation as in the creation of an item supplier.

Deleting an Item Supplier

In order to delete an item supplier, the supplier must exist for the item in Merchandising, otherwise, an error will be returned. Optionally the item supplier detail records can be deleted by integrating as part of the item supplier delete message.

Table 3-35 Item Supplier Delete

Message Element	Required?	Notes
Supplier	Always	Must be an existing supplier for the item in Merchandising.
Delete Children Indicator	Always	Indicates whether the deletion should be applied to all associated item/supplier records below the item level of the item specified on the deletion message. Valid values are Y and N.
Item Supplier Country	Optional	Child node.
Item Supplier Country of Manufacture	Optional	Child node.
Item Supplier translation	Optional	Child node.

Creating an Item Supplier Country

An item supplier country may be created together with the creation of a new item or added to an existing item supplier. Below are the validations:

Message Element	Required?	Notes
Origin country ID	Always	Must be an existing country in Merchandising.
Primary country indicator	Always	Indicates the primary origin country for the item / supplier. An item/supplier can only have one primary origin country. Valid values are Y and N.
Unit cost	Optional	Contains the unit cost for the item/supplier/origin country. This must be provided if the item is orderable.
Lead time	Optional	Must be between 0 and 9999.
Pickup lead time	Optional	Must be between 0 and 9999.
Minimum order quantity	Optional	Must be greater than 0.
Maximum order quantity	Optional	Must be greater than 0.
Supplier hierarchy level 1	Optional	Can be used to identify the first level of a supplier hierarchy, such as the manufacturer.
Supplier hierarchy level 2	Optional	Can be used to identify the second level of a supplier hierarchy, such as the distributor.
Supplier hierarchy level 3	Optional	Can be used to identify the third level of a supplier hierarchy, such as the wholesaler.
Default UOP	Always	Contains the default Unit of Purchase for the item at the supplier/origin country.
Supplier pack size	Always	Must be greater than 0. Must not be a decimal if Cost UOM class is Qty
Inner pack size	Always	Must be less than supplier pack size and supplier pack size must be a multiple of inner pack size if populated. Must not be decimal if Cost UOM class is Qty
Ti	Always	Contain the number of cased in a tier on a pallet. Must be greater than 0. The pallet size for an item is the supplier pack size x Ti x Hi.
Hi	Always	Contains the number of tiers high for a pallet. Must be greater than 0. The pallet size for an item is the supplier pack size x Ti x Hi.
Cost UOM	Always	Must be an existing Unit of measure in Merchandising. If the UOM Class is QTY, inner pack size and supp pack size cannot be a decimal.
Tolerance type	Conditional	Must be one of the following: A - Actual P - Percentage Required for a variable weight simple pack catchweight item.
Minimum tolerance	Conditional	Required if the item is a variable weight simple pack catchweight item. Must be greater than 0. Must be less than 100 for Percentage tolerance type. Must be less than net weight for Actual tolerance type. Must be less than max tolerance.
Maximum tolerance	Optional	Required if the item is a variable weight simple pack catchweight item. Must be greater than 0. Must be less than 100 for Percentage tolerance type. Must be greater than net weight for Actual tolerance type. Must be greater than max tolerance.
Supplier hierarchy type 1	Optional	Used in conjunction with the Supplier Hierarchy Level 1 to define the type, for example Manufacturer.
Supplier hierarchy type 2	Optional	Used in conjunction with the Supplier Hierarchy Level 1 to define the type, for example Distributor.
Supplier hierarchy type 3	Optional	Used in conjunction with the Supplier Hierarchy Level 1 to define the type, for example Wholesaler.
Round level	Optional	Must be one of the following: C - Case CL - Case/Layer CLP - Case/Layer/Pallet L - Layer LP - Layer/Pallet P – Pallet Used in conjunction with the rounding percentages to determine when to round up or down to the nearest inner, case, layer, or pallet.
Round to inner percentage	Always	Must be between 0 and 100.
Round to case percentage	Always	Must be between 0 and 100.
Round to layer percentage	Always	Must be between 0 and 100.
Round to pallet percentage	Always	Must be between 0 and 100.
Packing method	Optional	Must be a valid code from code type PKMT if populated: FLAT - Flat HANG - Hanging
Default expense profiles indicator	Optional
Purchase type	Conditional	Required if consignment concession flag is Y. 0 – Owned (default) 1 - Consignment 2 - Concession
Calculation basis	Conditional	Required if consignment concession flag is Y and purchase type is either 1 or 2. C - Cost per Unit P - Purchase Rate
Purchase rate	Conditional	Required if purchase type is either 1 or 2 and calculation basis is P. Must be between 0 and 100.

Updating an Item Supplier Country

In order to update an item supplier country information, the supplier country must exist for the item in Merchandising, otherwise, an error will be returned. All the updateable fields will go through the same validation as in the creation of an item supplier country.

Deleting an Item Supplier Country

In order to delete an item supplier country, the supplier country must exist for the item in Merchandising, otherwise, an error will be returned.. Optionally, the item supplier country detail records can be deleted by integrating as part of the item supplier country delete message.

Table 3-36 Item Supplier Country Delete

Message Element	Required?	Notes
Origin Country Id	Always	Must be an existing supplier country for the item in Merchandising.
Item Supplier Country Location	Optional	Child Node
Item Supplier Country Dimension	Optional	Child Node

Creating Item Supplier Manufacturing Country

An item supplier manufacturing country may be created together with the creation of a new item or added to an existing item supplier. Below are the validations:

Message Element	Required?	Notes
Manufacturer country ID	Always	Must be an existing country in Merchandising.
Primary manufacturer country indicator	Optional	Valid values are Y and N.

Updating Item Supplier Manufacturing Country

In order to update an item supplier country information, the supplier manufacturing country must exist for the item in Merchandising, otherwise, an error will be returned. All the updateable fields will go through the same validation as in the creation of an item supplier manufacturing country.

Deleting Item Supplier Manufacturing Country

In order to delete an item supplier manufacturing country, the supplier manufacturing country must exist for the item in Merchandising, otherwise, an error will be returned.

Table 3-37 Item Supplier Country of Manufacture Delete

Message Element	Required?	Notes
Manufacturer Country Id	Always	Must be an existing supplier manufacturer country for the item in Merchandising.

Creating Item Supplier Country Location

Item supplier country location can be created together with the creation of a new item or added to an existing item supplier country. Records are not required at this level for an item. If provided the values override those defined at the item/supplier/country level for the specified location(s). Below are the validations:

Message Element	Required?	Notes
Hierarchy ID	Always	Must be NULL when item-supplier-country-location hierarchy level is either All Stores (AS), All Warehouses (AW) or All Internal Finishers (AI). Required if item-supplier-country-location hierarchy level is either Store (S), Default Warehouse (DW), Warehouse (W), Physical Warehouse (PW), Internal Finisher (I), District (D), Region (R), Area (A), Transfer Zone (T) or Location Trait (L). Contains the identifier for the specified location hierarchy level. For example, if the location hierarchy level is S this will contain a store ID.
Unit cost	Optional	Required if item is an owned item or a consignment/concession item with calculation basis as C, when consignment concession flag is set to Y. Required if consignment concession flag is set to either N or D. Must be blank for buyer packs. Must be greater than 0 and less than 9999999999999.9999 if populated.
Negotiated item cost	Optional
Primary location indicator	Optional	Indicates if the location is the primary for the item/supplier/origin country. Valid values are Y and N.
Pickup lead time	Optional	Must be between 0 and 9999.
Round level	Optional	Must be one of the following: C - Case CL - Case/Layer CLP - Case/Layer/Pallet L - LayerLP - Layer/Pallet P – Pallet Used in conjunction with the rounding percentages to determine when to round up or down to the nearest inner, case, layer, or pallet.
Round to case percentage	Optional	Must be between 0 and 100.
Round to layer percentage	Optional	Must be between 0 and 100.
Round to pallet percentage	Optional	Must be between 0 and 100.
Round to inner percentage	Optional	Must be between 0 and 100.
Supplier hierarchy level 1	Optional	Can be used to identify the first level of a supplier hierarchy, such as the manufacturer.
Supplier hierarchy level 2	Optional	Can be used to identify the second level of a supplier hierarchy, such as the distributor.
Supplier hierarchy level 3	Optional	Can be used to identify the third level of a supplier hierarchy, such as the wholesaler.
Cost UOM	Always	Must be an existing Unit of measure in Merchandising.
Purchase type	Conditional	Must be populated when consignment concession flag is Y. 0 - Owned 1 - Consignment 2 - Concession
Calculation basis	Conditional	Must be provided when consignment concession flag is Y and purchase type is either 1 or 2. Must be one of the following: C - Cost per Unit P - Purchase Rate
Purchase rate	Conditional	Must be provided if purchase type is either 1 or 2 and calculation basis is P. Must be between 0 and 100.

Updating Item Supplier Country Locations

In order to update an item supplier country location information, the supplier country location must exist for the item in Merchandising, otherwise, an error will be returned. All the updateable fields will go through the same validation as in the creation of an item supplier country location.

Deleting Item Supplier Country Locations

In order to delete an item supplier country location, the supplier country location must exist for the item in Merchandising, otherwise, an error will be returned.

Table 3-38 Item Supplier Country Location Delete

Message Element	Required?	Notes
Hierarchy Id	Always	Must be an existing location for the item supplier country in Merchandising.

Creating Item Supplier Country Dimensions

Item supplier country dimensions can be created together with the creation of a new item or added to an existing item supplier country. Dimensions are not required for an item. However, if non-standard units of measure will be used for the item there must be a case-type dimension provided. For example, for a selling unit retail to be defined in ounces there must be a dimension defined containing the liquid and volume to be used when converting between a unit and an ounce. Below are the validations:

Message Element	Required?	Notes
Dimension object	Always	Must be one of the following: CA - Case EA - Each IN - Inner PA - Pallet
Tare weight	Optional	Must be greater than zero and less than weight (gross weight).
Tare type	Optional	Must be one of the following: D - Dry W - Wet
Length width and height UOM	Conditional	Must be a valid UOM of the UOM Class DIMEN, if populated.
Length	Optional	Must be provided if dimension object is populated and UOM class is DIMEN. Must be greater than 0.
Width	Optional	Must be provided if dimension object is populated and UOM class is DIMEN. Must be greater than 0.
Dim height	Optional
Liquid volume	Optional	Required if dimension object is populated and it's UOM class is LVOL. Must be greater than 0, if populated.
Liquid volume UOM	Optional	Must be a valid UOM of the UOM Class LVOL, if populated.
Statistical cube	Optional	Must be greater than 0, if populated.
Weight UOM	Optional	Must be a valid UOM of the UOM Class MASS, if populated.
Weight	Optional	Required if tare type and net weight are populated. Must be less than tare weight, if populated. Must be greater than 0, if populated.
Net weight	Optional	Minimum tolerance value must be less than net weight for an actual tolerance type. Maximum tolerance value must be greater than net weight. Must be greater than 0, if populated. Must be less than or equal to weight (gross weight).
Presentation method	Optional	Must be a valid code from code type PCKT, if populated.

Updating Item Supplier Country Dimensions

In order to update an item supplier country dimension information, the supplier country dimension must exist for the item in Merchandising, otherwise, an error will be returned. All the updateable fields will go through the same validation as in the creation of an item supplier country dimension.

Deleting Item Supplier Country Dimensions

In order to delete an item supplier country dimension, the supplier country dimension must exist for the item in Merchandising, otherwise, an error will be returned.

Table 3-39 Item Supplier Country Dimension Delete

Message Element	Required?	Notes
Dimension Object	Always	Must be an existing supplier country dimension for the item in Merchandising.

Creating Item VAT

Item VAT (value added tax) may be created together with the creation of a new item or added to an existing item when default tax type for the system is SVAT (Simple VAT). If not populated, item vat is defaulted from the corresponding department's vat information. Below are the validations:

Message Element	Required?	Notes
VAT Type	Always	Valid values for are Cost (C), Retail (R) and Both (B).
VAT Region	Always	Must be an existing VAT Region in Merchandising, if populated
VAT Code	Always	Must be an existing VAT code in Merchandising, if populated
Active Date	Always	Must not be earlier than or equal to vdate.
Reverse VAT Indicator	Always	Valid values are Y and N.

Deleting Item VAT

In order to delete an item VAT, the vat information must exist for the item in Merchandising, otherwise, an error will be returned.

Table 3-40 Item VAT Delete

Message Element	Required?	Notes
VAT Type	Always	Must be an existing VAT type for the VAT Item in Merchandising.
VAT Region	Always	Must be an existing VAT region for the VAT Item in Merchandising.
VAT Code	Always	Must be an existing VAT code for the VAT Item in Merchandising.
Active Date	Always	Must be an existing active date for the VAT Item in Merchandising.

Creating Item UDA

Item UDA (user defined attribute) of type date/freeform text/list of value can be created together with the creation of a new item or added to an existing item. Below are the validations:

Message Element	Required?	Notes
UDA ID	Always	Must be an existing UDA in Merchandising for the given display type.
Display type	Always	Must contain one of the following to indicate the type of UDA: DT – Date LV – List of Values FF – Free Form
UDA date	Optional	Must be populated for 'DT' display type.
UDA value	Optional	Must be populated for 'LV' display type.
UDA text	Optional	Must be populated for 'FF' display type.
New UDA date	Optional	Must not already be present in Merchandising for the given item UDA combination. Must not be same as the existing value for the given item UDA combination.
New UDA value	Optional	Must not already be present in Merchandising for the given item UDA combination. Must not be same as the existing value for the given item UDA combination.
New UDA text	Optional	Must not already be present in Merchandising for the given item UDA combination. Must not be same as the existing value for the given item UDA combination.

Updating Item UDA

In order to update an item UDA of type date/freeform text/list of values, the UDA must exist for the item in Merchandising, otherwise, an error will be returned. All the updateable fields will go through the same validation as in the creation of an item UDA.

Deleting Item UDA

In order to delete an item UDA, the UDA must exist for the item in Merchandising, otherwise, an error will be returned.

Table 3-41 Item UDA Delete

Message Element

Required?

Notes

UDA Id

Always

Must be an existing UDA for the Item in Merchandising.

Display Type

Always

Display Type of the UDA. Valid values are:

LV - List of Values

FF - Freeform

DT - Date

UDA Value

Optional

This can either be a UDA value (for LV display type) or a UDA date (for DT display type) or a freeform text (for FF display type). This must an existing value for the Item UDA in Merchandising.

Creating Item Season

Item Seasons can be created together with the creation of a new item or added to an existing item. Below are the validations:

Message Element	Required?	Notes
Season ID	Always	Must be an existing season in Merchandising.
Phase ID	Always	Must be an existing phase for the given season in Merchandising.
Item season sequence number	Optional	Used to ensure uniqueness. Each season/phase combination for an item should have a unique sequence number.
Diff ID	Optional	Can be used to differentiate an item/season by a diff, for example if the season/phase applies to only a specific color for a style.
Create datetime	Optional	Holds the date time stamp the item/season/phase was created.
Last update datetime	Optional	Holds the date time stamp of the most recent update by the Last update ID.
Last update ID	Optional	Holds the ID of the user who most recently updated this record.
color	Optional	Not used by Merchandising.

Deleting Item Season

In order to delete an item season, the season-phase ID must exist for the item in Merchandising, otherwise, an error will be returned.

Table 3-42 Item Season Delete

Message Element	Required?	Notes
Season ID	Always	Must be an existing season for the Item in Merchandising.
Phase ID	Always	This must be an existing phase for the item season in Merchandising.
Differentiator ID	Optional	This must be a valid group/differentiator ID for the item in Merchandising.
Color	Optional	Not used.

Creating Item Images

Item images can be created together with the creation of a new item or added to an existing item. Below are the validations:

Message Element	Required?	Notes
Image name	Always	Contains the image file name (for example, image.jpg).
Image address	Optional	Contains the image URL path. If not provided the system default will be used.
Image description	Optional	Contains a name for the image that is logical for a user to be able to identify the image.
Create datetime	Optional	May contain the date timestamp the image was added for the item.
Last update datetime	Optional	May contain the date timestamp for when the image was last updated.
Last update ID	Optional	May contain the ID for the user that made the last update.
Image type	Always	Must be a valid code from code type = IITD if populated: H - High L - Low M - Medium T - Thumbnail
Primary indicator	Always	Valid values are Y and N.
Display priority	Always	Must be greater than 0.

Updating Item Images

In order to update an item image, the image name must exist for the item in Merchandising, otherwise, an error will be returned. All the updateable fields will go through the same validation as in the creation of an item image.

Deleting Item Images

In order to delete an item image, the image must exist for the item in Merchandising, otherwise, an error will be returned. Optionally, the item image translation can be deleted by integrating as part of the item image delete message.

Table 3-43 Item Image Delete

Message Element	Required?	Notes
Image Name	Always	Must be an existing image for the item in Merchandising.
Image Translations	Optional	Child Node

Creating HTS and Assessments

HTS and Assessment may be created together with the creation of a new item or added to an existing item. Below are the validations:

Table 3-44 HTS Validation

Message Element	Required?	Notes
HTS	Always	Contains the HTS code. The specified code must exist in Merchandising.
Import country ID	Always	Contains the country ID where the item is being imported into and the HTS code applies.
Origin country ID	Always	Contains the country ID where the item originated from.
Effect from Date	Always	Contains the first date the HTS code is effective for the item.
Effect to Date	Always	Contains the last date the HTS code is effective for the item.
Clearing zone ID	Optional	Must be an existing clearing zone in Merchandising and the clearing zone must be associated with the import country.
Status	Optional	Valid values are worksheet (W) and approved (A).

Table 3-45 HTS Assessment Validation

Message Element	Required?	Notes
Component ID	Always	Component ID must exist on the ELC components table.
CVB code	Optional	Required if the component rate calculation basis is value (V), otherwise this will be defaulted to NULL. Must be a valid CVB code in Merchandising.
Component rate	Optional	Must be greater than or equal to 0 is populated. Required if CVB Code is populated.
Per count	Optional	Required if CVB Code is populated. Defaulted to NULL if calculation basis is V, else it must be greater than or equal to 0.0001.
Per count UOM	Optional	Required if calculation basis is V - Value. Must be an existing UOM in Merchandising.
Estimated assessment Value	Optional
Nominal flag 1	Optional	Valid values are '+', '-' and 'N', if populated. Defaulted to N if not populated.
Nominal flag 2	Optional	Valid values are '+', '-' and 'N', if populated. Defaulted to N if not populated.
Nominal flag 3	Optional	Valid values are '+', '-' and 'N', if populated. Defaulted to N if not populated.
Nominal flag 4	Optional	Valid values are '+', '-' and 'N', if populated. Defaulted to N if not populated.
Nominal flag 5	Optional	Valid values are '+', '-' and 'N', if populated. Defaulted to N if not populated.

Updating HTS and Assessments

In order to update HTS and assessments, the record to be updated must exist in Merchandising, otherwise, an error will be returned. Status and origin country ID can be updated at the HTS level. For assessments, all fields identified in the create section above except for component ID are updateable and will go through the same validation as in the creation of assessments.

Deleting HTS and Assessments

In order to delete HTS and assessments, the record to be deleted must exist in Merchandising, otherwise, an error will be returned.

Table 3-46 Item HTS Delete

Message Element	Required?	Notes
HTS	Always	The specified HTS code must exist for the item in Merchandising.
Import country ID	Always	The specified import country Id must exist for the item/HTS in Merchandising.
Origin country ID	Always	The specified HTS import Id must exist for the item/HTS in Merchandising.
Effect from Date	Always	The specified effective from date must exist for the item/HTS in Merchandising.
Effect to Date	Always	The specified effective to date must exist for the item/HTS in Merchandising.
Item HTS Assessments	Optional	Child Node

Table 3-47 Item HTS Assessments Delete

Message Element	Required?	Notes
Component Id	Always	The specified component must exist for the item HTS assessment in Merchandising.

Creating Expenses

Expenses may be created together with the creation of a new item or added to an existing item that has suppliers defined. Below are the validations:

Message Element	Required?	Notes
Supplier	Always	Item supplier relationship must exist in Merchandising.
Component ID	Always	Component ID must exist on the ELC components table of type Expense (E).
Discharge port	Always	Must be an existing outside location of type 'DP' in Merchandising, if populated.
Origin country ID	Optional	Must be an existing country in Merchandising, if populated.
Lading port	Optional	Must be an existing outside location of type 'LP' in Merchandising, if populated.
Zone ID	Optional	Must be an existing cost zone in Merchandising, if populated.
Zone group ID	Optional	Must be an existing cost zone group in Merchandising, if populated.
Base Expense Indicator	Optional	Valid values are Y and N.
CVB code	Optional	Must be a valid CVB code in Merchandising.
Component rate	Optional	Required if component ID is populated. Must be greater than or equal to 0 if populated.
Per count	Optional	Required if calculation basis is S (Specific). Must be greater than 0, if populated. Defaulted to NULL for Value calculation basis.
Per count UOM	Optional	Required if calculation basis is Specific (S). Must be an existing UOM in Merchandising, if populated. Defaulted to NULL for Value (V) calculation basis.
Component currency	Optional	Must be an existing currency in Merchandising if populated.
Update orders Indicator	Optional	Valid values are Y and N, if populated.
Nominal flag 1	Optional	Valid values are '+', '-' and 'N', if populated.
Nominal flag 2	Optional	Valid values are '+', '-' and 'N', if populated.
Nominal flag 3	Optional	Valid values are '+', '-' and 'N', if populated.
Nominal flag 4	Optional	Valid values are '+', '-' and 'N', if populated.
Nominal flag 5	Optional	Valid values are '+', '-' and 'N', if populated.

Updating Expenses

In order to update expenses, the item/supplier/component ID must exist in Merchandising, otherwise, an error will be returned. All fields identified in the create section above except for supplier/component ID are updateable and will go through the same validation as in the creation of expenses.

Deleting Expenses

In order to delete expenses, the item/supplier/component ID/discharge must exist for the item in Merchandising, otherwise, an error will be returned.

Table 3-48 Item Expense Delete

Message Element	Required?	Notes
Supplier	Always	Must be an existing supplier expense for the item in Merchandising.
Component Id	Always	Must be an existing component Id for the item supplier expense in Merchandising.
Discharge port	Always	Must be an existing discharge port location for the item supplier expense in Merchandising.
Origin country ID	Optional	Must be an existing country for item supplier expense in Merchandising, if populated.
Lading port	Optional	Must be an existing lading port location for the item supplier expense in Merchandising, if populated.
Zone ID	Optional	Must be an existing cost zone for item supplier expense in Merchandising, if populated.

Creating Tickets

Tickets may be created together with the creation of a new item or added to an existing item. Below are the validations:

Message Element	Required?	Notes
Ticket type ID	Always	Must be an existing ticket type in Merchandising.
PO print type	Optional	Must be one of the following: A - On Approval R - On Receipt This is used to indicate when ticket requests will be created for the item.
Print on price change Indicator	Always	Valid values are Y and N.
Ticket over percentage	Optional	Must be greater than 0, if populated.

Updating Tickets

In order to update tickets, the item/ticket type ID must exist in Merchandising, otherwise, an error will be returned. All fields identified in the create section above except for ticket type ID are updateable and will go through the same validation as in the creation of item tickets.

Deleting Tickets

In order to delete item tickets, the item/ticket type ID must exist in Merchandising, otherwise, an error will be returned.

Table 3-49 Item Ticket Delete

Message Element	Required?	Notes
Ticket type ID	Always	Must be an existing ticket type for the item in Merchandising.

Creating Up-charges

Upcharges may be created together with the creation of a new item or added to an existing item. Below are the validations:

Table 3-50 Header Level Validation

Message Element	Required?	Notes
From location type	Always	Valid values are store (S), warehouse (W), physical warehouse (PW), area (A), region (R), country (C).
From location	Optional	Valid location or hierarchy ID.
To location type	Always	Valid values are store (S), warehouse (W), physical warehouse (PW), area (A), region (R), country (C).
To location	Optional	Valid location or hierarchy ID.

Table 3-51 Detail Level Validation

Message Element	Required?	Notes
Component ID	Always	Component ID must exist on the ELC components table.
Component rate	Always
Per count	Optional	Must be greater than 0.
Per count UOM	Optional	Must be an existing UOM in Merchandising.
Up charge group	Always	Must be an existing Upcharge Group in Merchandising.
Component currency	Always	Must be an existing currency in Merchandising.
Transfer allocation default indicator	Optional

Deleting Up-charges

In order to delete item upcharges, the upcharge or upcharge/component ID must exist for the item in Merchandising, otherwise, an error will be returned.

Table 3-52 Item Up-charges Header Delete

Message Element	Required?	Notes
From location type	Always	Valid values are store (S), warehouse (W), physical warehouse (PW), area (A), region (R), country (C).
From location	Optional	Location or hierarchy ID from which upcharges are being deleted.
To location type	Always	Valid values are store (S), warehouse (W), physical warehouse (PW), area (A), region (R), country (C).
To location	Optional	Location or hierarchy ID to which upcharges are being deleted.
Detail Up-charges	Optional	Child node

Table 3-53 Item Up-charges Header Delete

Message Element	Required?	Notes
Component ID	Always	Component ID must exist on the item up-charges in Merchandising.
Transfer allocation default indicator	Optional

Updating Up-charges Detail

In order to update an item upcharge detail, the upcharge/component ID must exist for the item in Merchandising, otherwise, an error will be returned.

Creating Item Country

For GTAX tax type, item country can be created together with the creation of a new item or added to an existing item. If not provided, country is defaulted. Below are the validations:

Message Element	Required?	Notes
Country ID	Always	Must be an existing country in Merchandising.

Deleting Item Country

In order to delete an item country, the item country must exist in Merchandising, otherwise, an error will be returned.

Table 3-54 Item Country Delete

Message Element	Required?	Notes
Country ID	Always	Must be an existing country for the item in Merchandising.

Flex Attributes

If custom flex attributes (CFAS) have been defined for items, at item or item/supplier or item/supplier/country or item/supplier/country/location level, then they can be integrated as part of this API. The node of the integration that supports this will accept the name of the attribute as it is defined in the group set level view and the value for the attribute. Flex attributes can only be added to or updated on an item at header and detail levels but cannot be deleted.

Message Element	Required?	Notes
Name	Always	Holds the name of the attribute.
Value	Optional	Holds the value of the attribute for non-date attributes.
Value Date	Optional	Holds the value of the attribute for date attributes.

Translated Language

If translations have been defined for items, at item or item/image or item/supplier level, then they can be integrated as part of this API. The node of the integration that supports this will accept the language and the description specified in the language. Translations can be added, updated or deleted.

Table 3-55 Item Header Translation Create or Update

Message Element	Required?	Notes
Language	Always	Contains the language in which the translated text is maintained. Must be a valid language in Merchandising.
Short Description	Optional	Contains the translated text for the item short description.
Item Description	Always	Contains the translated text for the item description.
Item Description Secondary	Optional	Contains the translated text for the secondary description of the item.

Table 3-56 Item Header Translation Delete

Message Element	Required?	Notes
Language	Always	Contains the language of the translated text that needs to be deleted.

Table 3-57 Item Supplier Translation Create or Update

Message Element	Required?	Notes
Language	Always	Contains the language in which the translated text is maintained. Must be a valid language in Merchandising.
Supplier Differentiator 1	Optional	Contains the translated text for supplier differentiator 1.
Supplier Differentiator 2	Optional	Contains the translated text for supplier differentiator 2.
Supplier Differentiator 3	Optional	Contains the translated text for supplier differentiator 3.
Supplier Differentiator 4	Optional	Contains the translated text for supplier differentiator 4.
Supplier Label	Optional	Contains the translated text for the supplier label.

Table 3-58 Item Supplier Translation Delete

Message Element	Required?	Notes
Language	Always	Contains the language of the translated text that needs to be deleted.

Table 3-59 Item Image Translation Create or Update

Message Element	Required?	Notes
Language	Always	Contains the language in which the translated text is maintained. Must be a valid language in Merchandising.
Image Description	Always	Contains the translated text for the item image description.

Table 3-60 Item Image Translation Delete

Message Element	Required?	Notes
Language	Always	Contains the language of the translated text that needs to be deleted.

Error Handling

Message XSD

Below are the filenames that correspond with each message type. Please consult the Oracle Retail Integration Guide for each message type for the details on the composition of each message.

Message Types	Message Type Description	XML Schema Definition (XSD)
xitemcre	Item Create Message	XItemDesc.xsd
xitemmod	Item Modify Message	XItemDesc.xsd
xitemdel	Item Delete Message	XItemRef.xsd
xitemsupcre	Item/Supplier Create Message	XItemDesc.xsd
xitemsupmod	Item/Supplier Modify Message	XItemDesc.xsd
xitemsupdel	Item/Supplier Delete Message	XItemRef.xsd
xitemsupctycre	Item/Supplier/Country Create Message	XItemDesc.xsd
xitemsupctymod	Item/Supplier/Country Modify Message	XItemDesc.xsd
xitemsupctydel	Item/Supplier/Country Delete Message	XItemRef.xsd
xiscmfrcre	Item/Supplier/Country of Manufacture Create Message	XItemDesc.xsd
xiscmfrmod	Item/Supplier/ Country of Manufacture Modify Message	XItemDesc.xsd
xiscmfrdel	Item/Supplier/ Country of Manufacture Delete Message	XItemRef.xsd
xiscdimcre	Item/Supplier/Country/Dimension Create Message	XItemDesc.xsd
xiscdimmod	Item/Supplier/Country/Dimension Modify Message	XItemDesc.xsd
xiscdimdel	Item/Supplier/Country/Dimension Delete Message	XItemRef.xsd
xitemvatcre	Item/Vat Create Message	XItemDesc.xsd
xitemvatdel	Item/Vat Delete Message	XItemRef.xsd
xitemctrycre	Item/Country Create Message	XItemCtryDesc.xsd
xitemctrydel	Item/Country Delete Message	XItemCtryRef.xsd
xitemudacre	Item/UDA Create Message	XItemDesc.xsd
xitemudadel	Item/UDA Delete Message	XItemRef.xsd
xitemimagecre	Item/Image Create Message	XItemDesc.xsd
xitemimagemod	Item/Image Modify Message	XItemDesc.xsd
xitemimagedel	Item/Image Delete Message	XItemRef.xsd
xitemtlcre	Item Master translated language Create Message	XItemDesc.xsd
xitemtlmod	Item Master translated language Modify Message	XItemDesc.xsd
xitemtldel	Item Master translated language Delete Message	XItemRef.xsd
xitemsuptlcre	Item/Supplier translated language Create Message	XItemSupDesc.xsd
xitemsuptlmod	Item/Supplier translated language Modify Message	XItemSupDesc.xsd
xitemsuptldel	Item/Supplier translated language Delete Message	XItemSupRef.xsd
xitemimagetlcre	Item/Image translated language Create Message	XItemImageDesc.xsd
xitemimagetlmod	Item/Image translated language Modify Message	XItemImageDesc.xsd
xitemimagetldel	Item/Image translated language Delete Message	XItemImageRef.xsd
xitemhtscre	Item/HTS create message	XItemDesc.xsd
xitemhtsmod	Item/HTS modify message	XItemDesc.xsd
xitemhtsdel	Item/HTS delete message	XItemRef.xsd
xitemhtsassesscre	Item/HTS assess create message	XItemDesc.xsd
xitemhtsassessmod	Item/HTS assess modify message	XItemDesc.xsd
xitemhtsassessdel	Item/HTS assess delete message	XItemRef.xsd
xitemexpensescre	Item/Expenses create message	XItemDesc.xsd
xitemexpensesmod	Item/Expenses modify message	XItemDesc.xsd
xitemexpensesdel	Item/Expenses delete message	XItemRef.xsd
xitemticketcre	Item/Ticket create message	XItemDesc.xsd
xitemticketmod	Item/Ticket modify message	XItemDesc.xsd
xitemticketdel	Item/Ticket delete message	XItemRef.xsd
xitemseasoncre	Item/Seasons create message	XItemDesc.xsd
xitemseasondel	Item/Seasons delete message	XItemRef.xsd
xitemchgcre	Item up charge create message	XItemDesc.xsd
xitemchgdtlmod	Item up charge detail modify message	XItemDesc.xsd
xitemchgdel	Item up charge delete message	XItemRef.xsd

Location Trait Subscription API

This section describes the location trait subscription API.

Functional Area

Foundation Data

Business Overview

The Location Trait Subscription API processes incoming data from an external system to create, edit and delete location traits in Merchandising. This data is processed immediately upon message receipt so success or failure can be communicated to the external application.

The table below contains the details of the message as well as the validations.

Table 3-61 Location Traits

Message Element	Required?	Notes
Trait ID	Yes	This field contains the unique id number of the location trait.
Trait Description	Yes	This field contains the description of the location trait.

Error Handling

Message XSD

Here are the filenames that correspond with each message type. Please consult RIB documentation for each message type in order to get a detailed picture of the composition of each message.

Message Type	Message Type Description	XML Schema Definition (XSD)
xloctrtcre	External Location Trait Create	XLocTrtDesc.xsd
xloctrtdel	External Location Trait Delete	XLocTrtRef.xsd
xloctrtmod	External Location Trait Modification	XLocTrtDesc.xsd

Merchandise Hierarchy Reclassification Subscription API

This section describes the merchandise hierarchy reclassification subscription API.

Functional Area

Merchandise Hierarchy

Business Overview

This API allows Merchandising to subscribe merchandise hierarchy reclassification messages, that are published by an external system. It is intended to be used by retailers who manage their hierarchies in a system outside Merchandising. This API allows for pending merchandise hierarchy reclassification events to be created, modified or deleted. A separate batch process will read the information off the pending merchandise hierarchy table and creates or modifies the merchandise hierarchy information in Merchandising once the effective date arrives.

Creating Merchandise Hierarchy Reclassifications

When a new merchandise hierarchy reclassification is created, the API will first validate that all required fields are present in the message. Certain of the fields are required regardless of hierarchy level, while others are dependent on other hierarchy configurations. After that, business level validation on the input information will be performed. The tables below summarizes the validation.

Table 3-62 Header Level Validation

Message Element	Required?	Notes
Merchandise Hierarchy Level	Always	Indicates the level of merchandise hierarchy. Valid values are V (division), G (group), D (department), C (class), and S (subclass).
Merchandise Hierarchy ID	Always	Holds the merchandise hierarchy ID, of the merchandise hierarchy component being created or updated.
Merchandise Hierarchy parent ID	Always	This field will hold the parent of the hierarchy identified in the Merchandise Hierarchy ID field. This column will only be populated if the Merchandise Hierarchy level is class or subclass.
Merchandise Hierarchy Grandparent ID	Conditional	This field will hold the grandparent ID of the hierarchy identified in the Merchandise Hierarchy ID field. This column will only be populated if the Merchandise Hierarchy Level is subclass.
Merchandise Hierarchy Name	Always	The name of the hierarchy value.
Effective Date	Always	The date the hierarchy change will become effective. The effective date must be greater than or equal to the current date.
Action Type	Conditional	Indicates if this field is an addition (A) or modification (M). It is required on a create message and should not be populated on a modify message.
Buyer	Conditional, Optional	The number of the buyer associated with the entity. This value must be predefined in Merchandising. This field should only hold a value if the hierarchy level indicates division, group, or department.
Purchase Type	Conditional	The code indicates whether items in the department will be created by default as normal merchandise (0), consignment (1), or concession (2). This field is required if the hierarchy level indicates department, otherwise it should be null. Additionally, if the Consignment/Concession system option is set to N, this should always be 0.
Total Market Amount	Optional	This field stores total market amount that is expected for the entity. This field will only be used if the hierarchy value indicates division or department.
Merchandiser	Conditional, Optional	This field indicates the number of the merchandiser associated with the entity. This value must be predefined in Merchandising. This field should hold a value only if the hierarchy level indicates division, group, or department.
Budgeted Markup Percentage	Conditional	This field stores the markup percent of cost. Budgeted Markup Percentage or Budgeted Intake Percentage cannot be both null or both have values. This field is required if the hierarchy level indicates department, otherwise it should be null.
Profit Calculation Type	Conditional	Indicates whether profit will be calculated by direct cost (1) or retail inventory (2). This field is required for a new department, otherwise it should be null. A Department cannot be set up as profit calculation type of Direct Cost and purchase type of Consignment Stock.
Markup Calculation Type	Conditional	Indicates how markup is calculated in the department. Valid values are for a new department, otherwise it should be null.
OTB Calculation Type	Conditional	Indicates how open to buy is calculated in the department. Valid values are cost (C) and retail (R). This field is required for a new department, otherwise it should be null.
Maximum Average Counter	Conditional	The maximum count of days with acceptable data to include in an average for items with the department. This field is required for a new department, otherwise it should be null. The value cannot be a negative.
Average Tolerance Percentage	Conditional	The tolerance percentage value used in averaging for items within a department. This field will only be used for a new department. The value cannot be a negative.
Budgeted Intake Percentage	Conditional	Indicates the markup percent of retail to use as a default for the department. Budgeted Markup Percentage or Budgeted Intake Percentage cannot be both null or both have values. This field is required for a new department, otherwise it should be null.
Department VAT Inclusive Indicator	Conditional	Indicates the default value for the class VAT indicator. When classes are initially set up, they will inherit this value. This field will only be populated when the hierarchy level indicates department.
Class VAT Indicator	Conditional	Indicates if retail is displayed and held with or without VAT for items within a class. Valid values are Y (yes) and N (no). This field is required if the hierarchy level indicates department and you are configured for Simple VAT or Global Tax and must be set to Y in those cases. If you are configured for US Sales Tax, then it must be N.

Updating Merchandise Hierarchy Reclassifications

For updating a previously created reclassification, the hierarchy type must be already present in Merchandising. For updates, the validation is similar to that described above for creating a new reclassification. If updating the effective date of a reclassification that has an Add action type, there should not be any child hierarchy with earlier effective date. For example, if you are adding a department, there cannot be a reclassification for adding a class in the department with an earlier effective date.

Deleting Merchandise Hierarchy Reclassifications

To delete a previously created reclassification event, the below validations will be executed to ensure there are no conflicts, along with checks for the existence of child reclassification records, before deleting the record.

Message Element	Required?	Notes
Merchandise Hierarchy Level	Always	Indicates the level of merchandise hierarchy. Valid values are V (division), G (group), D (department), C (class), and S (subclass).
Merchandise Hierarchy ID	Always	Holds the merchandise hierarchy ID for the selected level.
Merchandise Hierarchy parent ID	Optional	This field will hold the parent of the hierarchy identified in the Merchandise Hierarchy ID field. This column will only be populated if the Merchandise Hierarchy Level is class or subclass.
Merchandise Hierarchy Grandparent ID	Optional	This field will hold the grandparent ID of the hierarchy identified in the Merchandise Hierarchy ID field. This column will only be populated if the Merchandise Hierarchy Level is subclass.

Error Handling

Message XSD

Below are the filenames that correspond with each message type. Please consult the Oracle Retail Integration Guide for each message type for the details on the composition of each message.

Message Types	Message Type Description	XML Schema Definition (XSD)
xmrchhrclscre	Create Merchandise Hierarchy Reclassification	XMrchHrRclsDesc.xsd
xmrchhrclsmod	Modify Merchandise Hierarchy Reclassification	XMrchHrRclsDesc.xsd
xmrchhrclsdel	Delete Merchandise Hierarchy Reclassification	XMrchHrRclsRef.xsd

Merchandise Hierarchy Subscription API

This section describes the merchandise hierarchy subscription API.

Functional Area

Merchandise Hierarchy

Business Overview

The merchandise hierarchy allows the retailer to create the relationships that are necessary to support the product management structure of a company. This hierarchy reflects a classification of merchandise into multi-level descriptive categorizations to facilitate the planning, tracking, reporting, and management of merchandise within the company. If Merchandising is not the system of record for merchandise hierarchy information, then this API may be used to create, update, or delete elements of the merchandise hierarchy, including division, group, department, class, and subclass, based on an external system.

Deleting a division or group will process immediately upon receipt of the message, assuming there are no dependent levels below them. However, departments, classes, and subclasses will not actually be deleted from the system upon receipt of the message. Instead, they will be added to a table, where a background process (Daily Purge of Foundation Data) will occur to ensure the records can be deleted as part of the delete process. For more on this batch process, see the Retail Merchandising System Operations Guide, Volume 1 - Batch Overviews and Designs.

If you are implementing Merchandising with Simple VAT as the default tax type, then department-level VAT records can be created and edited within the department message (VAT records are not deleted). VAT creates can be passed in with a department create message, or they can be passed in with their own specific message type. VAT region and VAT codes records must exist prior to creating department VAT records. Also, when passing in a new VAT region to an existing department with attached items, the VAT information will default to all items.

The merchandise hierarchy must be created from the highest level down. Conversely, the hierarchy must be deleted from the lowest level up. Each lower level references a parent level. This means a department is associated with a group; a class is associated with a department; and a subclass is associated with department/class combination because classes are not unique across departments.

Creating a Company

When a new company is created, this API will first validate that all required fields are present in the message. Business-level validation on the input information will be performed, which checks that the company doesn't already exist. If the validation is met, the company in the message data is created. Only one company can exist in Merchandising.

Updating a Company

When a company is updated, this API will first validate that all required fields are present in the message. Business level validation on the input information will be performed, which verifies if the company ID to be updated already exists. If the company already exists, the company's details in the message data are updated.

The format and validation for creating and updating the company is shown in the table below:

Table 3-63 Company

Message Element	Required?	Notes
Company	Yes	This field contains the unique number which identifies the company for which the system is running.
Company Name	Yes	This field contains the name of the company for which the system is running.
Add_1	Yes	This value contains the first line of the company headquarters address.
Add_2	No	This value contains the second line of the company headquarters address.
Add_3	No	This value contains the third line of the company headquarters address.
City	Yes	This field contains the city of the company headquarters.
State	No	This field contains the state code of the company headquarters. This value must be a valid state in Merchandising.
Country Code	Yes	This field contains the country code of the company headquarters. This value must be a valid country in Merchandising.
Postal Code	No	This field contains the postal code of the company headquarters.

Creating Divisions

When a new division is created, this API will first validate that all required fields are present in the message. Business-level validation on the input information will be performed. The business validation:

Verifies division is not already present.
Verifies that, if total market amount is received, then it should be at least 1000.

If all the validations are met, the division in the message data is created.

Updating Divisions

When a division is updated, this API will first validate that all required fields are present in the message. Business-level validation on the input information will be performed. The business validation:

Verifies division is present.
Verifies that, if total market amount is received, then it should be at least 1000.

If all the validations are met, the division's details are updated.

The format and validation for creating and updating divisions is shown in the table below:

Table 3-64 Division

Message Element	Required?	Notes
Division	Yes	This field contains the unique identifier of the division.
Division Name	Yes	This field contains the name of the division.
Merchant	No	This field contains the number of the merchant associated with the division. This value must be a valid merchant in Merchandising.
Buyer	No	This field contains the number of the buyer associated with the division. This value must be a valid buyer in Merchandising.
Total Market Amount	No	This field contains the total market amount that is expected for the division. If this field is not null it must be at least 1000.

Deleting Divisions

When a division is deleted, this API will first validate that all required fields are present in the message. Business-level validation on the input information will be performed to:

Verify the division already exists.
Verify the division is not associated to a diff group.
Verify the division is not associated to a season id.
Verify the division is not associated to a ticket type.
Verify the division is not associated to a UDA.

If the information passes these validations, the division will be added to a purging staging table for processing in the Daily Purge of Foundation Data process.

The format and validation for deleting division is shown in the table below:

Table 3-65 Division

Message Element	Required?	Notes
Division	Yes	This field contains the unique identifier of the division being deleted.

Creating Groups

When a new group is created, this API will first validate that all required fields are present in the message. Business-level validation on the input information will be performed, which checks whether the group already exists. If it does not exist, the group in the message data is created.

Updating Groups

When a group is updated, this API will first validate that all required fields are present in the message. Business-level validation on the input information will be performed, which verifies whether the group to be updated already exists. If group already exists, the group details are updated.

The format and validation for creating and updating divisions is shown in the table below:

Table 3-66 Groups

Message Element	Required?	Notes
Group Number	Yes	This field contains the number which uniquely identifies the group.
Group Name	Yes	This field contains the name of the group.
Division	Yes	This field contains the identifier of the division of which the group is a member. This value must be a valid division in Merchandising.
Merchant	No	This field contains the number of the merchant associated with the division. This value must be a valid merchant in Merchandising.
Buyer	No	This field contains the number of the buyer associated with the division. This value must be a valid buyer in Merchandising.

Deleting Groups

When a group is deleted, this API will first validate that all required fields are present in the message. Business-level validation on the input information will be performed to:

Verify the group already exists.
Verify the group is not associated to a diff group.
Verify the group is not associated to a season id.
Verify the group is not associated to a ticket type.
Verify the group is not associated to a UDA.

If the information passes these validations, the group will be added to a purging staging table for processing in the Daily Purge of Foundation Data process.

The format and validation for deleting groups is shown in the table below:

Table 3-67 Division

Message Element	Required?	Notes
Group Number	Yes	This field contains the unique identifier of the group being deleted.

Creating Departments

When a new department is created, this API will first validate that all required fields are present in the message. Business-level validation on the input information will be performed. The business validation:

Verifies the department is not already present.
Verifies if total market amount is received then it should be at least 1000.
Verifies the child messages, if included, have their required fields present. The child messages contain the VAT and upcharge details for a department.

If all the validations are met, the department in the message data is created. Custom flex attributes can also be created for the department through this API, if they are active for the department.

Updating Departments

When a department is updated, this API will first validate that all required fields are present in the message. Business-level validation on the input information will be performed. The business validation:

Verifies if the department is present.
Verifies if total market amount is received then it should be at least 1000.
Verifies the child messages, if included, contain all required fields. The child messages contain VAT and upcharge details for a department.

If all the validations are met, the department in the message data is created. Like with create, custom flex attributes can also be updated for the department, if active.

The format and validation for creating and updating departments is shown in the table below:

Table 3-68 Department

Message Element	Required?	Notes
Department	Yes	This contains the number which uniquely identifies the department.
Department Name	Yes	This contains the name of the department being created or updated.
Buyer	No	This field contains the number of the buyer associated to the department. This value must be a valid buyer in Merchandising.
Purchase Type	Yes	This field contains the code which indicates whether items in this department are normal merchandise (0) consignment stock (1) and concession stock (2).
Total Market Amount	No	This field contains the total market amount that is expected for the department. This value cannot be less than 1000.
Merchandiser	No	This field contains the number of the merchandiser that is associated to the department. This value must be a valid merchant in Merchandising.
Group Number	Yes	This field contains the number of the group to which the department belongs. This value must be a valid group in Merchandising
Budgeted Markup	No	This field contains the budgeted markup percentage, the markup percent of cost. If this value is not populated on the message, it will be calculated to be the inverse of the budgeted intake percentage. This column will hold 70% as 70, not .70. This field must have a value if Budgeted Intake is NULL.
Profit Calc Type	Yes	This field contains the number which indicates whether profit will be calculated by direct cost (1) or retail inventory (2). It determines the accounting method to be used in the stock ledger for this department.
Markup Calc Type	Yes	This field contains the code that indicates how markup is calculated in this department. Valid values are cost (C) and retail (R).
OTB Calc Type	Yes	This field contains the code which indicates how open to buy (OTB) is calculated for this department. Valid values are cost (C) and retail (R).
Maximum Average Counter	Yes	This field contains the maximum count of days with acceptable data to include in an average for items within the department. The value should be greater than zero.
Average Tolerance Percentage	Yes	This field contains the tolerance percentage value used in averaging for items within this value. This column will hold 70% as 70, not .70. The value should be greater than zero.
Budgeted Intake	No	This field contains the budgeted intake percentage, which is the percent of the total take that is income. If this field is not populated on the message, it will be calculated as the inverse of the budgeted markup percentage. This column will hold 70% as 70, not .70. This field must have a value if Budgeted Markup is NULL.
Department VAT	No	Child node
Custom Flex Attributes	No	Child node
Department Up-Charges	No	Child node

Deleting Departments

When a department is deleted, this API will first validate that all required fields are present in the message. Business-level validation on the input information will be performed to:

Verify the department already exists.
Verify the department is not associated to a diff group.
Verify the department is not associated to a season id.
Verify the department is not associated to a ticket type.
Verify the department is not associated to a UDA.

If the information passes these validations, the department will be added to a purging staging table for processing in the Daily Purge of Foundation Data process. Flex attributes are deleted when the department is deleted.

The format and validation for deleting departments is shown in the table below:

Table 3-69 Department

Message Element	Required?	Notes
Department	Yes	This contains the number of the department being deleted.
Department Up-Charges	No	Child node

Creating VAT Information for Departments

If you are configured to run Merchandising using Simple VAT (SVAT) for your default tax type, then you can set the VAT rates by region for the department using this API. If included, this API will check for all required fields in the message and create the VAT record for a department. When adding new VAT region to an existing department with attached items, the VAT information will default to all items.

Updating VAT Information for Departments

If you are configured to run Merchandising using Simple VAT (SVAT) for your default tax type, then you can update the VAT rates by region for the department using this API. This API will check for all required fields in the message and updates the VAT information for a department. When updating VAT details for a department with attached items, the VAT information will default to all items.

The format and validation for creating and updating VAT information is shown below:

Table 3-70 Department VAT

Message Element	Required?	Notes
VAT Region	Yes	This contains the number of the VAT region to which this department is associated. This value must be a valid VAT Region in Merchandising.
VAT Code	Yes	This field contains the alphanumeric identifier of the VAT code. This value must be a valid VAT Code in Merchandising.
VAT Type	Yes	This field indicates if the VAT rate is used for purchasing (C), selling (R), or both (B).
Reverse VAT Indicator	No	This field indicates if items in the department are subject to reverse charge VAT at the region. Valid values are Yes (Y) and No (N).

Creating Up-charges for Departments

When a message contains up-charge details, first it validates for the required fields, including "from" locations and "to" locations in the message. If no up-charge record is found, this message creates the up-charge for a department and from/to location combination. As part of the addition, you can indicate in the message if you want to have the up-charges added to existing items or only added for new items. Similarly, there is a flag in the message to indicate whether the new upcharges will be cascaded to transfers and allocations which are unshipped and not in closed or deleted status. The department upcharges will be created as soon as the message is consumed, however the new upcharges will be cascaded to items, transfers, and allocations via batches which runs at the end of every day.

Updating Up-charges for Departments

When a message contains up-charge details, first it validates for the required field in the message. If up-charge record exists for a department and the from/to location combination in the message, then the up-charge details are updated for the department. As part of the update there is also an option to have the up-charges updated for items in the department, or unshipped transfers and allocations for items in the department. The department upcharges will be updated as soon as the message is consumed, however the updates will be cascaded to items, transfers, and allocations via batches which runs at the end of every day.

The format and validation for creating and updating up-charge information is shown in the table below:

Table 3-71 Department Up-Charge Header

Message Element	Required?	Notes
From Location	Conditional	This field contains the source location from which goods will be transferred. This column can contain Country/Area/Region IDs when From Location Type is Country (C), Area (A), or Region (R). It will be a store, virtual warehouse, or physical warehouse when To Location Type is 'S', 'W' or 'PW'. Otherwise, it should be left blank when To Location Type is either All Stores (AS) or All Warehouses (AW).
To Location	Conditional	This field contains the destination location to which goods will be transferred. This column can contain Country/Area/Region IDs when To Location Type is Country (C), Area (A), or Region (R). It will be a store, virtual warehouse, or physical warehouse when To Location Type is 'S', 'W' or 'PW'. Otherwise, it should be left blank when To Location Type is either All Stores (AS) or All Warehouses (AW).
From Location Type	Yes	This field contains the type of source location from which goods will be transferred. Valid values are: C - Country A - Area R - Region S - store W - Virtual Warehouse PW - Physical Warehouse AS - All Stores AW - All Warehouses
To Location Type	Yes	This field contains the type of destination location to which goods will be transferred. Valid values are: C - Country A - Area R - Region S - store W - Virtual Warehouse PW - Physical Warehouse AS - All Stores AW - All Warehouses
Department Up-Charge Detail	No	Child node

Table 3-72 Department Up-Charge Detail

Message Element	Required?	Notes
Component ID	Yes	This field contains the unique identifier of the Up Charge component. This should be a valid cost component in merchandising.
Component Rate	Yes	This field contains the rate to be charged against the cost of the Item/To Location combinations within the department.
Per Count	Yes	This field contains a count indicating the amount of the Per Count Unit of Measure to which the rate applies.
Per Count UOM	Yes	This field contains the unit of measure in which the Per Count is specified. This should be a valid unit of measure in merchandising.
Up-Charge Group	Yes	This field contains the group to which the component ID belongs. Valid values can be found on the codes table.
Component Currency	Yes	This field contains the currency of the Up Charge component. This must be a valid currency in Merchandising.
Effective Date	No	This field contains the date from which the new values are effective in the system.
Item Default Indicator	No	This field indicates if component rate information is updated or not for existing items under the department. Valid values are Yes (Y) and No (No).
Transfer Allocation Default Indicator	No	This field indicates if component rate information is updated or not for existing transfers and allocations under the department. Valid values are Yes (Y) and No (N).

Deleting Up-charges for Departments

When a message contains an up-charge, first it validates for the required field in the message. If up-charge record exists for a department, this message deletes the upcharge details for a department. Deleting up-charges from a department does not automatically remove them from the items or transfers and allocations for items in the department.

The format and validation for deleting up charges is shown in the table below:

Table 3-73 Department Up-Charge Detail

Message Element	Required?	Notes
Component ID	Yes	This field contains the unique identifier of the Up Charge component being deleted.

Creating Classes

When a new class is created, this API will first validate that all required fields are present in the message. Business-level validation on the input information will be performed, which checks whether the class already exists. If the class does not exist, the class in the message data is created. Custom flex attributes can also be created for the class through this API, if they are active for the class.

Updating Classes

When a class is updated, this API will first validate that all required fields are present in the message. Business-level validation on the input information will be performed, which verifies if the class to be updated already exists. If class already exists, the class details are updated. Like with create, custom flex attributes can also be updated for the class, if active.

The format and validation for creating and updating classes is shown in the table below:

Table 3-74 Class

Message Element	Required?	Notes
Class	Yes	This field contains the unique number of the class.
Class Name	Yes	This field contains the name of the class.
Class VAT Indicator	Yes	This field indicates whether retail is displayed and held with or without VAT for items within the class. This field is available when VAT is on in the system and defined at the class level. This field is always defaulted to No (N).
Department	Yes	This field contains the number of the department which contains the class. This value must be a valid department in Merchandising.
Custom Flex Attributes	No	Child node

Deleting Classes

When a class is deleted, this API will first validate that all required fields are present in the message. Business-level validation on the input information will be performed to verify:

The class exists.
It is not associated to a diff group.
It is not associated to a season.
It is not associated to a ticket type.
It is not associated to a UDA.

If these validations pass, the class will be added to a purging staging table for processing in the Daily Purge of Foundation Data process. Flex attributes are deleted when the class is deleted.

The format and validation for deleting classes is shown in the table below:

Table 3-75 Class

Message Element	Required?	Notes
Class	Yes	This field contains the unique number of the class.
Department	Yes	The number of the department which contains the class. This value must be a valid department in Merchandising.

Creating Subclasses

When a new subclass is created, this API will first validate that all required fields are present in the message. Business-level validation on the input information will be performed, which checks whether the subclass already exists. If the subclass does not exist, then it is created. Custom flex attributes can also be created for the subclass through this API, if they are active for the subclass.

Updating Subclasses

When a subclass is updated, this API will first validate that all required fields are present in the message. Business-level validation on the input information will be performed which verifies if the subclass to be updated already exists. If subclass already exists, it is updated. Like with create, custom flex attributes can also be updated for the subclass, if active.

The format and validation for creating and updating subclasses is shown in the table below:

Table 3-76 Subclass

Message Element	Required?	Notes
Subclass	Yes	This field contains the unique number of the subclass.
Subclass Name	Yes	This field contains the name of the subclass.
Class	Yes	This field contains the number of the class which contains the subclass. This value must be a valid class in Merchandising.
Department	Yes	This field contains the number of the department which contains the class. This value must be a valid department in Merchandising.
Custom Flex Attributes	No	Child node

Deleting Subclasses

When a subclass is deleted, this API will first validate that all required fields are present in the message. Business-level validation on the input information will be performed to:

Verify the subclass already exists.
Verify the subclass is not associated to a diff group.
Verify the subclass is not associated to a season id.
Verify the subclass is not associated to a ticket type.
Verify the subclass is not associated to a UDA.

If these validations pass, the subclass will be added to a purging staging table for processing in the Daily Purge of Foundation Data process. Flex attributes are deleted when the subclass is deleted.

The format and validation for deleting classes is shown in the table below:

Table 3-77 Subclass

Message Element	Required?	Notes
Subclass	Yes	This field contains the unique number of the subclass being deleted
Class	Yes	This field contains the unique number of the class.
Department	Yes	The number of the department which contains the class/subclass. This value must be a valid department in Merchandising.

Flex Attributes

If any custom flex attributes (CFAS) for the department, class, or subclass have been added or modified, it will trigger an update message. The node of the integration that supports this will contain the name of the attribute as it is defined in the group set level view, the value of the custom attribute. If it is a date attribute, the date value is in a separate field. Flex attributes can only be added to or updated; they cannot be deleted.

Table 3-78 Flex Attributes

Message Element	Required?	Notes
Name	Yes	Holds the attribute name.
Value	No	Holds the value of the attribute for number and character type attributes
Value Date	No	Holds the date for date type attributes.

Error Handling

Message XSD

Below are the filenames that correspond with each message type. Please consult the Oracle Retail Integration Guide for each message type for the details on the composition of each message.

Message Types	Message Type Description	XML Schema Definition (XSD)
xmrchhrcompcre	External Create Company	XMrchHrCompDesc.xsd
xmrchhrcompmod	External Modify Company	XMrchHrCompDesc.xsd
xmrchhrdivcre	External Create Division	XMrchHrDivDesc.xsd
xmrchhrdivmod	External Modify Division	XMrchHrDivDesc.xsd
xmrchhrdivdel	External Delete Division	XMrchHrDivRef.xsd
xmrchhrgrpcre	External Create Group	XMrchHrGrpDesc.xsd
xmrchhrgrpmod	External Modify Group	XMrchHrGrpDesc.xsd
xmrchhrgrpdel	External Delete Group	XMrchHrGrpRef.xsd
xmrchhrdeptcre	External Create Department	XMrchHrDeptDesc.xsd
xmrchhrdeptmod	External Modify Department	XMrchHrDeptDesc.xsd
xmrchhrdeptdel	External Delete Department	XMrchHrDeptRef.xsd
Xmrchhrvatcre	External Merch Hierarchy VAT create	XMrchHrDeptDesc.xsd
xmrchhrvatmod	External Merch Hierarchy VAT modify	XMrchHrDeptDesc.xsd
xmrchhrdeptchrgcre	External Merch Hier Dept Up-Charge create	XMrchHrDeptDesc.xsd
xmrchhrdeptchrgmod	External Merch Hier Dept Up-Charge modify	XMrchHrDeptDesc.xsd
xmrchhrdeptchrgdel	External Merch Hier Dept Up-Charge delete	XMrchHrDeptRef.xsd
xmrchhrclscre	External Create Class	XMrchHrClsDesc.xsd
xmrchhrclsmod	External Modify Class	XMrchHrClsDesc.xsd
xmrchhrclsdel	External Delete Class	XMrchHrClsRef.xsd
xmrchhrsclsdel	External Delete Subclass	XMrchHrSclsRef.xsd
xmrchhrsclsmod	External Modify Subclass	XMrchHrSclsDesc.xsd
xmrchhrsclsdel	External Delete Subclass	XMrchHrSclsRef.xsd

Order Subscription API

This section describes the PO subscription API.

Functional Area

Purchase Orders

Business Overview

This subscription API is used to keep Merchandising in sync with an external system that is responsible for maintaining purchase orders. It is assumed that the source of orders sent in this API is not the supplier, as vendor managed inventory (VMI) POs can be sent using the Upload Purchase Order and Purchase Order Change Acknowledgements from Suppliers to Merchandising (ediupack) batch upload. It also does not support creating customer order POs or contract POs. Customer order POs are assumed to be sent using the Customer Order Fulfillment Subscription API and contract orders are created using replenishment processes in Merchandising or manually using the UI.

POs can be created, modified or deleted at the header or the detail level. This API also creates, edits, and deletes other data associated with a purchase order, including letter of credit, expenses, harmonized tariff schedules (HTS) and assessments, and custom flex attributes (CFAS). It also will apply rounding rules, default inventory management parameters, apply bracket costs, update open to buy buckets, and insert a record into the deals queue for deals to be applied to the order, if applicable. These transactions are performed immediately upon receipt of the message so that success or failure can be sent back to the calling application.

If the location on a purchase order is a franchise store, a corresponding franchise order is also created along with the PO.

Creating Purchase Orders

New purchase order messages pass through a series of validations such as required field and valid value validations for each field as well as business validations. The tables below summarize these validations.

Table 3-79 Header Level Validation

Message Element	Required?	Notes
Order Number	Always	Must be a unique order number not used by any existing purchase orders in Merchandising.
Supplier	Always	Must be a valid, active supplier in Merchandising. The supplier and locations on the order must belong to the same org unit. If the EDI PO indicator is set to Y, the supplier of the order must also be an EDI supplier.
Currency Code	Optional	Must be a valid currency code. If not provided, this defaults to the currency code used by the supplier.
Terms	Optional	Must be a valid payment terms in Merchandising. If terms is not provided in the message, the API will default this to supplier terms.
Not Before Date	Optional	Must be equal to or after the current date and before the Not After Date, if provided. If the date is not provided, the API will default the value to the current date + default supplier lead time if there are not items attached to the order. If items are already added to the order, it will be defaulted to current date + minimum lead time + minimum pickup lead time among all items in the order.
Not After Date	Optional	Must be equal to or after the current date and after the Not Before Date, if provided. If the date is not provided, the API will default the value to the current date + default supplier lead time if there are not items attached to the order. If items are already added to the order, it will be defaulted to current date + maximum lead time + maximum pickup lead time among all items in the order.
OTB End of Week Date	Optional	Must be a valid end of week date and equal to or after the current date. If the date is not provided, the API will default the value to the last day of the week that the not after date value falls in.
Department	Optional	Must be a valid department in Merchandising. The department field should not be populated if items belonging to different departments are present in the order. Department is required if the Department Level PO system option is Y.
Status	Optional	Valid statuses are Worksheet (W), Submitted (S), or Approved. If not provided, the status will be defaulted to W. Status of closed (C) also allowed, but for order updates only.
Exchange Rate	Optional	The exchange rate should be greater than zero. If not provided, and the currency code is provided, the exchange rate will be based on the given currency code and primary currency. If the currency code is not provided, then the exchange rate will default based on the supplier’s currency code and primary currency.
Include On Order Indicator	Optional	Valid values are Y and N. If not provided in the message, it will be defaulted to Y.
Written Date	Optional	If not provided in the message, it will be defaulted to the current date.
Origin Indicator	Optional	Valid values for origin indicator are: 0 – Merchandising generated PO (from replenishment) 1 – Other system generated PO 2 – Manual purchase order 3 – Buyer worksheet PO 4 – Consignment sales generated PO 5 – Vendor generated PO 6 – AIP generated PO 7 – SIM generated PO 8 – Allocation generated PO 9 – Consignment transfer generated PO 10 – Consignment ownership change generated PO The expected values for this field in purchase order subscription are 1, 2, 6, 7 and 8. If it is not provided in the message, it will be defaulted to 2.
EDI PO Indicator	Optional	Valid values are Y and N. If not provided in the message, it will be defaulted to the supplier’s EDI PO indicator.
Pre Mark Indicator	Optional	Valid values are Y and N. If not provided in the message, it will be defaulted to N. If Y, then the order must be pre-allocated before it is approved.
User ID	Optional	If not passed into the message, then a value will be defaulted for auditing purposes.
Comment	Optional
Attempt RMS Load	Optional	If not passed into the message, then it will be defaulted to RMS, which means that the information will persist to the Merchandising tables as opposed to the staging tables. Valid values are RMS and STG.
Master PO number	Optional	This is can be used for linking multiple orders together for multiple delivery date orders.
Lading Port	Optional	If not provided, this will be defaulted based on supplier import attributes. If provided, it should be a valid lading port in Merchandising.
Discharge Port	Optional	If not provided, this will be defaulted based on supplier import attributes. If provided, it should be a valid discharge port in Merchandising.
Factory	Optional	If not provided, this will be defaulted based on supplier import attributes. If provided, it should be a valid, active factory in Merchandising.
Agent	Optional	If not provided, this will be defaulted based on supplier import attributes. If provided, it should be a valid, active agent in Merchandising.
Ship Method	Optional	If not provided, this will be defaulted based on supplier attributes. This must be a valid ship method in Merchandising, which are stored in the codes table under the code type SHPM.
Partner Type 1	Optional	This should be provided if partner 1 is given. Valid values are S1, S2 and S3. These are stored under the codes table under the code type SUHL.
Partner 1	Optional	If not provided, this will be defaulted based on supplier import attributes. If provided, it should be a valid, active partner in Merchandising for the given partner type. Partner and partner type should be provided, or both should be null.
Partner Type 2	Optional	This should be provided if partner 2 is given. Valid values are S1, S2 and S3. These are stored under the codes table under the code type SUHL.
Partner 2	Optional	If not provided, this will be defaulted based on supplier import attributes. If provided, it should be a valid, active partner in Merchandising for the given partner type. Partner and partner type should be provided, or both should be null.
Partner Type 3	Optional	This should be provided if partner 3 is given. Valid values are S1, S2 and S3. These are stored under the codes table under the code type SUHL.
Partner 3	Optional	If not provided, this will be defaulted based on supplier import attributes. If provided, it should be a valid, active partner in Merchandising for the given partner type. Partner and partner type should be provided, or both should be null.
Payment Method	Optional	Valid values are stored under the code type PYMT in the codes table. If not provided, this will default to the supplier payment method.
Purchase Type	Optional	Valid values are stored under the code type PURT in the codes table. If not provided, this will default to the purchase type defined at the supplier inventory management level.
FOB Title Pass	Optional	This is required for import orders with payment method of Letter of Credit. If this is not provided in the message, it will default to the FOB Title Pass defined at the system level. Valid values are stored under the code type FOBT in the codes table.
FOB Title Pass Desc	Optional	This is required for import orders with payment method of Letter of Credit. If this is not provided in the message, this will default to the FOB Title Pass Description defined at the system level.
PO Type	Optional	This should be a valid PO Type in Merchandising. Valid PO Types are found in the PO_TYPE table.
Import Country ID	Optional	This is required for import orders. The value should be a valid country in Merchandising. If the value is not provided in the message, it will default to the country ID of the primary address of the location in the order.
Order Type	Optional	Indicates the type of order and which Open To Buy bucket will be updated. Valid values are found against code type ‘ORDO’.
Buyer	Optional	This field contains the id of the buyer associated to the PO. Validation is performed against the Buyer table.
Location Type	Optional	This field contains the type of location in the location field. Valid values are S (Store) or W (Warehouse).
Location	Optional	This field contains the location where all items on the order will be delivered to. If populated, it will mean a single location order.
Promotion	Optional	Contains the RPCS offer ID associated with the order to provide a link between the order dialog and the promotions dialog.
QC Indicator	Optional	Determines whether or not quality control will be required when items for this order are received. Valid values are ‘Y’ and ‘N’.
Freight Terms	Optional	This refers to the freight terms related to the PO.
Backhaul Type	Optional	This field contains the type of backhaul allowance that will be applied to the order.
Backhaul Allowance	Optional	This field will contain the backhaul allowance value.
Ship Pay Method	Optional	This indicates the payment terms for freight charges associated with the order. The code type ‘SHMT’ holds the valid values.
FOB Trans Responsibility	Optional	Contains the code indicating the type of the location that is responsible for the transportation of the order.
FOB Trans Responsibility Description	Optional	This field describes the code for the location responsible for the transportation of the order.
Vendor Order No	Optional	This field contains the vendor’s unique identifying number for an order. These orders may have originated by the vendor through the EDI process or this number can be associated to an Oracle Retail order when the order is created on-line.
Freight Contract No	Optional	This field contains the number of the contract with a shipper that will give specific freight rates.
Pickup Location	Optional	This field contains the location at which the order will be picked up, if the order is a Pickup order.
Pickup No	Optional	This field contains the reference number of the Pickup order.
Pickup Date	Optional	This field contains the date when the order can be picked up from the Supplier. This field is only required if the Purchase Type of the order is Pickup.
Appointment Date/Time	Optional	This column will hold the date and time of the receiving appointment at the warehouse.
Import Type	Optional	This is the default importer/exporter assigned to the supplier of the Purchase order. Valid values are stored against code type ‘BTLT’.
Invoice Location	Optional	This identifies the importer/exporter assigned to the supplier. It should reference the WH.WH column.
Clearing Zone	Optional	This column will hold the clearing zone ID.
Routing Location	Optional	This is the default routing location for the import order. It refers the OUTLOC.OUTLOC_ID column.
Master PO No	Optional	This field holds the Master Order Number.
Re-Approve	Optional	This field indicates that the update to the corresponding purchase order needs to be performed, and then it should be approved again.
Earliest Ship Date	Optional	The date before which the items on the purchase order cannot be shipped by the supplier. Represents the earliest earliest ship date of all the items on the order.
Latest Ship Date	Optional	The date after which the items on the purchase order cannot be shipped by the supplier. Represents the greatest latest ship date of all the items on the order.

Table 3-80 Detail Level Validation

Message Element	Required?	Notes
Item Number	Required	Must be an approved, orderable transaction level item in Merchandising supplied by the supplier indicated in the message. The Item Number should not be in the process of being deleted and must be active at the location specified in the message.
Location	Required	Must be a valid stockholding store or virtual warehouse in Merchandising.
Location Type	Required	Valid values are store (S) and warehouse (W).
Unit Cost	Optional	Must be greater than or equal to zero. If more than one virtual warehouse for the same physical warehouse are included in the details for the order, then the unit cost must be the same for those item/warehouses.
Reference Item	Optional	Must be a valid, approved reference item of the item being ordered and should not be in the process of being deleted. The Reference Item should be supplied by the supplier in the message.
Origin Country ID	Optional	Must exist as a valid country for the supplier/item provided in the message. If the country is not provided in the message, the value is defaulted to the item’s primary country of sourcing.
Supplier Pack Size	Optional	Must be greater than zero. If there are several order lines with the same item in the message, the supplier pack size and origin country of these records should all be the same. If not provided in the message, the API will default the value based on the supplier/country for the item.
Quantity Ordered	Required	Must be greater than zero.
Cancel Indicator	Optional	This is used for purchase order detail modification only.
Reinstate Indicator	Optional	This is used for purchase order detail modification only.
Delivery Date	Optional	The date by which goods are to be delivered.
Qty Cancelled	Optional	This field contains the cancelled quantity for the item in the order.
Cancel Code	Optional	This field contains the reason that the line item was cancelled. This field is required if a line item is cancelled.
Estimated Instock Date	Optional	Date that the item on the PO is expected to be available to ship from the PO location to another location.
Earliest Ship Date	Optional	The date before which the item cannot be shipped by the supplier. It will be validated to be a valid date equal to or greater than the business date.
Latest Ship Date	Optional	The date after which the item cannot be shipped by the supplier. It will be validated to be a valid date equal to or greater than the business date.

If the above validation passes, then the purchase order and details will be created with the status set in the message. If the status in the message is approved, then the order will also be subjected to a series of approval checks. If the order cannot be approved, it will not be created.

You can also include information on the order - letter of credit (if the payment method is letter of credit), landed cost expenses, and for import orders you can include HTS and assessments. If included, these will be created simultaneously with the creation of the order.

Updating Purchase Orders

Updates can be made either at header level or at detail level for orders that are in Worksheet, Approved or Closed status. For both kinds of update messages, the API will validate that the order number included in the message already exists in Merchandising while item number and location will be also validated for existence in detail level updates.

Header Level Updates

Only header level fields need to be provided for header-level updates. Any order details included in the message will be ignored for a header-level update message. There are certain fields that are not allowed to be updated at the header level depending on the status, and if these are still provided in the message, no error message will be returned. The values will simply be ignored. However, modifying the following header level fields is allowed made while the order is submitted or approved, without having to set the order in worksheet status:

status
not before date
not after date
terms
include on-order indicator
comments

Detail Level Updates

Order details can be updated for orders in Approved, Worksheet, Submitted or Closed status. The only information needed at the header level is the order number, which if not provided, will cause the message to be rejected. All other details provided at the header level will be ignored. Modifying order quantity, as well as supplier pack size or unit cost on an approved or submitted order will in effect set the order status to worksheet and subject it for automatic re-approval. When modifying order quantities, the full amount should be provided, not just the difference in the old and new values. Validations are also done on quantity changes, such as the ordered quantity should not go below the allocated quantity or replenishment quantity, quantity ordered cannot not be less than quantity received.

Fields that can be modified in worksheet, submitted and approved status:

Supplier Pack Size
Unit Cost - for items with no received quantities
Quantity Ordered

Fields that cannot be modified in statuses other than worksheet:

Origin Country ID
Location

Fields that can be modified only in approved status:

Quantity Cancelled
Cancel Code

Reinstating Order Lines

To reinstate orders, the reinstate indicator should be set to Y. In effect, this will set the cancelled quantities of the line items to 0 and reinstate the ordered quantities. This will set the status of the reinstated order to Worksheet.

Cancelling a Line Item in an Approved Order

In order to cancel a line item on the order, you can set the cancel indicator at the detail level to Y and at the same time, the quantity ordered for that line item must be set to 0. For partial cancellations, either reduce the quantity of an approved order or populate the quantity cancelled field making sure the cancel indicator is blank or set to N. This will allow for the automatic re-approval of the entire order, if there are line items still on the order once processed by the API. The cancel indicator and reinstate indicator cannot be set to Y at the same time.

Deleting Purchase Orders

If you are deleting a line item on the purchase order or deleting the whole purchase order, the API will first validate that the order number is valid. The order number is the only required field for a header delete message. All other fields will be ignored. For detail delete messages, you must provide the item as well and optionally, the location. These should exist in Merchandising, or else a reject message will be returned.

Deleting the Entire Order

In order to delete an entire order, you must send a header delete message. This will in effect set the status of the order at the header level to D. Only worksheet orders can be deleted. Deleting the purchase order cannot be done if the order is submitted, approved or has been approved, or if allocations exist for the order. Delete messages will still be processed, however it will be treated as an update of cancelled quantity and the quantity ordered will be reduced to the quantity available to be cancelled. If this results in all line items being cancelled or if the delete is made at header level, the status of the order will become Closed.

If an order is still in worksheet status, the entire order will be deleted. If the order involves any franchise stores, then any franchise order or return created with the order will also be cancelled or deleted.

Deleting a Line Item

If an order is still in worksheet status, line items will be deleted from the order. If all line items are deleted, the order header will also be deleted. For orders that are not in worksheet status, when a detail delete is requested, it will update the quantities to cancelled quantities and will be subject for re-approval.

Table 3-81 Header Level Validation

Message Element	Required?	Notes
Order Number	Always	Must be an existing order number in Merchandising.
Order Detail	Optional	Child node
Attempt RMS Load	Optional	This field indicates if the message will persist in RMS or the staging tables. Valid values are RMS or STG. If not defined, the default is STG.
Location Expense	Optional	Child node
Item HTS	Optional	Child node

Table 3-82 Detail Validation

Message Element	Required?	Notes
Item	Optional	This field contains the item number that will be deleted in the order.
Location	Always	This field contains the location the item is ordered to.
Reference Item	Optional	The ID of a reference item which can be used instead of using the item field. If the item field is not populated this field is required.

Creating a Purchase Order Letter of Credit

A letter of credit may be created together with the creation of a new order or added to an existing order with a payment method of Letter of Credit. In order to create/edit/delete a letter of credit, the order should be in worksheet status. Below are the validations:

Table 3-83 Creating a Purchase Order Letter of Credit

Message Element	Required?	Notes
Letter of Credit Reference ID	Optional	The reference ID must be exist in Merchandising for the given beneficiary and applicant. The Free on Board title pass description and purchase type in the letter of credit table must match that of the values in the order.
Letter of Credit Group ID	Optional	If included, must be a valid value in Merchandising.
Applicant	Always	The applicant must be an active partner in Merchandising.
Beneficiary	Always	Must be a valid active supplier who can be a beneficiary.
Merchandise description	Always	A description of the merchandise being imported for customs purposes.
Transshipment Indicator	Always	Valid values are Y or N.
Letter of credit indicator	Always	Valid values are Y or N.

Updating a Purchase Order Letter of Credit

In order to update an order letter of credit, the letter of credit must exist for the order in Merchandising, otherwise, an error will be returned. All fields identified in the create section above are updateable and will go through the same validation as in the creation of a letter of credit.

Deleting a Purchase Order Letter of Credit

In order to delete an order letter of credit, the letter of credit must exist for the order in Merchandising, otherwise, an error will be returned.

Creating Expenses

Expenses may be created together with the creation of a new order or added to an existing order that has location records defined. In order to create/edit/delete expenses, the order should be in worksheet status. Below are the validations:

Table 3-84 Create Expenses

Message Element	Required?	Notes
Item	Always	The item/location/location type combination must be present in the order. For buyer packs with an order as type of Pack, this should be a component item in the pack and the item on the order should be present in the pack item field.
Pack item	Optional	If provided, the item/pack item/location/location type combination must be present in the order. This is required if the item on the order is a buyer pack with an order as type of Pack.
Location	Always	The item/location/location type combination must be present in the order.
Location type	Always	The item/location/location type combination must be present in the order. Valid values are S or W.
Component ID	Always	Must be a valid expense component in Merchandising. This should be present in ELC_COMP.
CVB code	Conditional	Required if the component rate calculation basis is value (V), otherwise this will be defaulted to NULL. Must be a valid CVB code in Merchandising.
Cost basis	Optional	Valid values are supplier (S) or order (O). If CVB code is provided, then this should be null.
Component rate	Optional	This will be defaulted based on the component if not provided.
Component currency	Optional	This will be defaulted based on the component if not provided. If it is present in the message, this must be a valid currency code.
Exchange rate	Optional	This should be the exchange rate used in relation to the location on the order. If this is not provided in the message, the API defaults it, depending on the order exchange indicator set at system level. If the indicator is Y, it defaults based on the component currency. If the component currency of the component is the same as that of the location, then exchange rate should be 1. If the system level indicator is set to N, the exchange rate will be based on the location currency.
Per count	Optional	If the component rate calculation basis is specific (S), it is defaulted based on the expensed component if not provided in the message.
Per count UOM	Optional	If the component rate calculation basis is specific (S), it is defaulted based on the expense component if not provided in the message. This must be a valid unit of measure.
Nominal flag 1	Optional	This will be defaulted based on the expense component if not provided. If it is present in the message, this must be N,+, or -.
Nominal flag 2	Optional	This will be defaulted based on the expense component if not provided. If it is present in the message, this must be N,+, or -.
Nominal flag 3	Optional	This will be defaulted based on the expense component if not provided. If it is present in the message, this must be N, +, or -.
Nominal flag 4	Optional	This will be defaulted based on the expense component if not provided. If it is present in the message, this must be N, +, or -.
Nominal flag 5	Optional	This will be defaulted based on the expense component if not provided. If it is present in the message, this must be N,+, or -.

Updating Expenses

In order to update expenses, the order/item/location/component ID must exist for the order in Merchandising, otherwise, an error will be returned. All fields identified in the create section above except for order/item/pack item/location/component id are updateable and will go through the same validation as in the creation of expenses.

Deleting Expenses

In order to delete expenses, the order/item/location/component ID must exist for the order in Merchandising, otherwise, an error will be returned.

Table 3-85 Order Expense Deletion

Message Element	Required?	Notes
Item	Always	This field contains the item number that will be deleted in the order.
Pack Item	Optional	If provided, the item/pack item/location combination must be present in the order.
Location	Always	This field contains the location that the item was ordered to. The item/location combination must be present in the order.
Component ID	Always	Must be a valid expense component in Merchandising. This should be present in ELC_COMP.

Creating HTS and Assessments

HTS and Assessment may be created together with the creation of a new import order or added to an existing order that has location records defined. In order to create/edit/delete HTS and assessments, the order should be in worksheet status. Below are the validations:

Table 3-86 HTS Validation

Message Element	Required?	Notes
Item	Always	The item must exist on the order. For buyer packs with an order as type of Pack, this should be a component item in the pack and the item on the order should be present in the pack item field.
Pack item	Conditional	The item must exist on the order. This is required if the item on the order is a buyer pack with an order as type of Pack.
HTS	Always	Must be a valid HTS code for the supplier's import country in Merchandising
Status	Always	Valid values are Worksheet (W) or Approved (A).
Origin Country ID	Optional	Must be a valid country in Merchandising. If the HTS tracking level is based on country of manufacture, this should be a valid country of manufacture for the item/supplier. If it is not provided, it will default to the item's primary manufacturing country. If the HTS tracking level is country of sourcing, it will default to the primary sourcing country for the item/supplier.
Import Country ID	Optional	Must be a valid country in Merchandising. If not provided, this will default to the import country ID at the order level.

Table 3-87 HTS Assessment Validation

Message Element	Required?	Notes
Component ID	Always	Must be a valid assessment component ID in Merchandising.
Component rate	Optional	This will be defaulted based on the component if not provided.
Per count	Optional	This is defaulted to the component when the calculation basis is specific (S), otherwise this will be defaulted to NULL.
Per count UOM	Optional	This is defaulted to the component when the calculation basis is specific (S), otherwise this will be defaulted to NULL.
CVB code	Optional	This is defaulted to the component when the calculation basis is value (V), otherwise this will be defaulted to NULL.
Nominal flag 1	Optional	This will be defaulted based on the assessment component if not provided. If it is present in the message, this must be N, +, or -.
Nominal flag 2	Optional	This will be defaulted based on the assessment component if not provided. If it is present in the message, this must be N, +, or -.
Nominal flag 3	Optional	This will be defaulted based on the assessment component if not provided. If it is present in the message, this must be N, +, or -.
Nominal flag 4	Optional	This will be defaulted based on the assessment component if not provided. If it is present in the message, this must be N, +, or -.
Nominal flag 5	Optional	This will be defaulted based on the assessment component if not provided. If it is present in the message, this must be N, +, or -.

Updating HTS and Assessments

Deleting HTS and Assessments

In order to delete HTS and assessments, expenses, the record to be deleted must exist in Merchandising, otherwise, an error will be returned.

Table 3-88 Order HTS

Message Element	Required?	Notes
Item	Always	This field contains the item number that will be deleted in the order.
Pack Item	Optional	If provided, the item/pack item combination must be present in the order.
HTS	Always	This field contains the unique identifier for the Harmonized Tariff Schedule code. The item/pack item/HTS must be present in the order.
HTS Assessments	Optional	Child node

Table 3-89 Order HTS Assessments

Message Element	Required?	Notes
Component ID	Always	This field contains the assessment component ID. The item/pack item/HTS/component ID must be present in the order.

Publishing Updates

Purchase orders will be published back to the RIB if approved or previously approved, such that system responsible for managing the purchase orders are notified.

Flex Attributes

If custom flex attributes (CFAS) have been defined for purchase orders, or at the order/item or order/item/location level, then they can be integrated as part of this API. The node of the integration that supports this will accept the name of the attribute as it is defined in the group set level view and the value for the attribute. Flex attributes can only be added to or updated on a purchase order at header and detail levels but cannot be deleted.

Table 3-90 Flex Attributes

Message Element	Required?	Notes
Name	Yes	Holds the attribute name.
Value	No	Holds the value of the attribute for number and character type attributes
Value Date	No	Holds the date for date type attributes.

Error Handling

Message XSD

Here are the filenames that correspond with each message type. Please consult the RIB documentation for each message type in order to get a detailed picture of the composition of each message.

Message Types	Message Type Description	XML Schema Definition (XSD)
XorderCre	Order Create Message	XOrderDesc.xsd
XorderCre (CustFlexAttriVo)	Order Flex Attribute Create Message for the Order Header	XOrderDesc.xsd
XorderDtlCre	Order Detail Create Message	XOrderDesc.xsd
XorderDtlCre (CustFlexAttriVo)	Order Detail Flex Attribute Create message
XorderLCCre	Order LC Create Message	XOrderDesc.xsd
XorderLocExpCre	Order Location Expense Create Message	XOrderDesc.xsd
XorderSkuHtsCre	Order SKU HTS Create Message	XOrderDesc.xsd
XorderSkuHtsAssessCre	Order SKU HTS Assess Create Message	XOrderDesc.xsd
XorderMod	Order Modify Message	XOrderDesc.xsd
XorderMod (CustFlexAttriVo)	Order Header Flex Attribute Modify Message	XOrderDesc.xsd
XorderDtlMod	Order Detail Modify Message	XOrderDesc.xsd
XorderDtlMod (CustFlexAttriVo)	Order Detail Flex Attribute Modify Message	XOrderDesc.xsd
XorderLCMod	Order LC Modify Message	XOrderDesc.xsd
XorderLocExpMod	Order Location Expense Modify Message	XOrderDesc.xsd
XorderSkuHtsMod	Order SKU HTS Modify Message	XOrderDesc.xsd
XorderSkuHtsAssessMod	Order SKU HTS Assess Modify Message	XOrderDesc.xsd
XorderDel	Order Delete Message	XOrderRef.xsd
XorderDtlDel	Order Detail Delete Message	XOrderRef.xsd
XorderLCDel	Order LC Delete Message	XOrderRef.xsd
XorderLocExpDel	Order Location Expense Delete Message	XOrderRef.xsd
XorderSkuHtsDel	Order SKU HTS Delete Message	XOrderRef.xsd
XorderSkuHtsAssessDel	Order SKU HTS Assess Delete Message	XOrderRef.xsd

Organizational Hierarchy Subscription API

This section describes the organizational hierarchy subscription API.

Functional Area

Organizational Hierarchy

Business Overview

If Merchandising is not the system of record for organizational hierarchy information for an implementation, then this API may be used to create, update or delete elements of the hierarchy based on an external system. The organization hierarchy subscription also assigns existing location traits to, or deletes them from the stores in the given organization hierarchy level.

The following organizational hierarchy elements can be created, modified, or deleted using this API: chain, area, region, or district. The organizational hierarchy must be created from the highest level down. Conversely, the hierarchy must be deleted from the lowest level up.

The following validation is applicable for the data sent in this API:

Message Element	Required?	Notes
Hierarchy Value	Always	Indicates the ID of the hierarchy component being added, modified, or deleted. It is validated based on the hierarchy level attribute included.
Hierarchy Description	Conditional	Indicates the description for the hierarchy component. This is required for create only. For modifications, it is optional. For delete, it is ignored.
Hierarchy Level	Always	Indicates the level of the hierarchy being created, updated, or deleted. Valid values are CH (chain), AR (area), RE (region) and DI (district).
Parent	Conditional	Identifies the parent level of the hierarchy for this component. For example, if the hierarchy level is district, this would be the ID of the region for the district.
Manager Name	Optional	Name of the manager for this hierarchy component.
Currency Code	Optional	The code that identifies the currency under which the hierarchy component operations.

Error Handling

Message XSD

Below are the filenames that correspond with each message type. Consult the RIB documentation for each message type in order to get a detailed picture of the composition of each message.

Message Type	Message Type Description	XML Schema Definition (XSD)
XOrgHrCre	External Create Organizational Hierarchy	XOrgHrDesc.xsd
XOrgHrLocTrtCre	External Create Location Trait	XOrgHrDesc.xsd
XOrgHrDel	External Delete Organizational Hierarchy	XOrgHrRef.xsd
XOrgHrLocTrtDel	External Delete Location Trait	XOrgHrRef.xsd
XOrgHrMod	External Modify Organizational Hierarchy	XOrgHrDesc.xsd

Payment Terms Subscription API

This section describes the payment terms subscription API.

Functional Area

Payment Terms

Business Overview

Payment terms are supplier-related financial arrangement information that can be subscribed to by Merchandising from a financial system. Payment terms are the terms established for paying a supplier (for example, 2.5% for 30 days) for purchase orders. After confirming the validity of the records enclosed within the message, Merchandising updates its tables with the information.

Creating Payment Terms

When a new payment term is subscribed to by Merchandising, it will first validate that all required fields are present in the message. Payment terms details should also be present when creating a new payment term, and when creating and updating a new payment term detail. After that, business level validation on the input information will be performed. The tables below summarize these two types of validations.

Table 3-91 Header Level Validation

Message Elements	Required?	Notes
terms	Always	This represents the unique ID to track this payment term in Merchandising.
terms code	Always	This is value is intended to hold the code in the financial system.
terms desc	Always	Description of the supplier terms
rank	Always	Unique number to rate invoice payment terms against purchase order terms

Table 3-92 Message Elements

Message Elements	Required?	Notes
due max amount	Always	This is the maximum amount due by a certain date
percent	Always	Percentage discount if payment is made within the time frame
terms sequence	Optional	The order in which to apply the discount percent
due days	Conditional	This is the number of days until payment is due. The following due days data combinations are valid: Due days, due day of month and due months forward should all be provided Due days, due day of month and due months forward are all NULL Due days should be provided and both due day of month and due months forward are provided.
due day of month	Conditional	Day of month used to calculate due date of invoice payment line. The following due days data combinations are valid: Due days, due day of month and due months forward should all be provided Due days, due day of month and due months forward are all NULL Due days should be provided and both due day of month and due months forward are provided.
due months forward	Conditional	Number of months ahead used to calculate due date of invoice payment line. The following due days data combinations are valid: Due days, due day of month and due months forward should all be provided Due days, due day of month and due months forward are all NULL Due days should be provided and both due day of month and due months forward are provided.
discount days	Conditional	This is the number of days in which payment must be made in order to receive the discount. The following discount days data combinations are valid: Discount days, discount day of month and discount months forward should all be provided Discount days, discount day of month and discount months forward are all NULL Discount days should be provided and both discount day of month and discount months forward are provided. Discount days is NULL and both discount day of month and discount months forward are provided.
discount day of month	Conditional	Day of month used to calculate discount date for invoice payment line The following discount days data combinations are valid: Discount days, discount day of month and discount months forward should all be provided Discount days, discount day of month and discount months forward are all NULL Discount days should be provided and both discount day of month and discount months forward are provided. Discount days is NULL and both discount day of month and discount months forward are provided.
discount months forward	Conditional	Number of months ahead to calculate discount date for invoice payment line. The following discount days data combinations are valid: Discount days, discount day of month and discount months forward should all be provided Discount days, discount day of month and discount months forward are all NULL Discount days should be provided and both discount day of month and discount months forward are provided. Discount days is NULL and both discount day of month and discount months forward are provided.
fixed date	Optional	This is the fixed due date
enabled flag	Always	This flag should be 'Y' if the start active date is less than or equal to the current date and the end date is greater than or equal to the current date. Otherwise, the enabled flag should be 'N'.
start active date	Optional	Start active date must be less than end active date.
end active date	Optional	End date should be greater than start active date.
cutoff day	Optional	This is the last day before payment is scheduled

Payment term details sent via the detail message can also be added when a payment term already exists in Merchandising. If the terms detail being added already exists, an error is raised.

After the message passes all validations, the payment terms are inserted into the Merchandising tables.

Updating Payment Terms

Payment terms can be updated at header or detail level. When updating at the header level, the payment term details for the term being updated should already exist in Merchandising. When updating payment term details, the term header and detail must already exist.

After the message passes all validations, the payment terms in Merchandising are updated. Rank, terms, code, and terms desc are the values that can be updated at header level. At the detail level, due days, due max amount, due months forward, discount days, percent, discount day of month, discount months forward, fixed date, enabled flag, start active date, end active date and cutoff day may be updated.

Error Handling

Message XSD

Here are the filenames that correspond with each message type. Please consult the RIB documentation for each message type in order to get a detailed picture of the composition of each message.

Message Types	Message Type Description	XML Schema Definition (XSD)
PayTermCre	Payment Terms Create Message	PayTermDesc.xsd
PayTermDtlCre	Payment Terms Detail Create Message	PayTermDesc.xsd
PayTermMod	Payment Terms Modify Message	PayTermDesc.xsd
PayTermDtlMod	Payment Terms Detail Modify Message	PayTermDesc.xsd

Receiving Subscription API

This section describes the receiving subscription API.

Functional Area

Receiving

Business Overview

This API processes receipts that Merchandising receives against purchase orders, transfers, and allocations received at a store, warehouse or finisher. Purchase orders can be received at the item level only using this message, while transfers and allocations, collectively referred to as stock orders, may be received at the bill of lading (BOL) level, where the entire shipment is received without including details, carton level, or item level.

When a transfer, PO or allocation is received at a location, Merchandising will update the appropriate tables, including the shipment, the transfer, allocation, or purchase order, stock on hand, as well as other inventory buckets (for example, in-transit). A record of the receipt is also made in the transaction level stock ledger.

Receiving Exceptions

Merchandising has the ability to automatically resolve several common exceptions that can occur during the receiving process. Here are some of the exceptions that can be supported:

Additionally, the following exceptions are automatically processed when a stock order is received through this API:

Receipt Against the Wrong BOL

In this case, the receiving location should send a carton status of Dummy (D) or Overage (O), indicating that a dummy BOL number was used. But, even if that status is not used, this exception processing can still take place. Merchandising will attempt to match the contents of the receipt to a valid BOL as follows:

If the carton belongs to a valid BOL at the given location, Merchandising receives the carton against the intended BOL at the given location.
If the carton belongs to a valid BOL at a related walk-through store, Merchandising receives the carton against the intended BOL at the intended location.
If the carton belongs to a valid BOL at an unrelated location, Merchandising uses the wrong store receiving process.

Walk-through Store Receiving

If you have configured two or more stores as “walk-through” locations, through attribution at on the store table in Merchandising, then if the BOL was intended to be received at the walk-through location instead of the location on the message, Merchandising will automatically adjust the receipt and process against the correct location.

Misdirected Container

Misdirected containers, or wrong store receiving, is when one or more containers on a receipt are identified as having been originally shipped to a different location (Location A) than the location that sent the receipt message (Location B). Whether or not misdirected container receiving is supported in Merchandising is controlled by a system option called Wrong Store Receipt Exception Handling. If this option is unchecked (N), then the receipt at the Location B will raise an error in this API. If set to checked (Y), then the shipment at Location A will be backed out, including in-transit updates, WAC adjustments, and stock ledger postings, and re-applied to Location B, prior to processing the receipt into Location B.

In order correctly manage this processing, Merchandising must receive the original carton number on the receipt. In some cases, such as when integrating with Store Inventory and Operations Cloud Service (SIOCS), the carton ID is reassigned by the receiving location. In that case, the reference carton field in the Receipt Detail node of the message must be populated to trigger this process. Otherwise, it will be treated as an overage at the actual receiving location and the original location will not have its quantities reversed until the transfer is reconciled.

Note:

Wrong location receiving is supported only for item-level transfer/allocation receipts.

Unwanded Cartons

An unwanded carton is a situation where Merchandising never received notification of the original shipment, only the receipt. In this case, if receiving is done at the item level, Merchandising will process both the shipment and receipt together. If item level details are not included for the carton, an error will be raised, as Merchandising will not be able to determine the contents of the carton, having never received the initial shipment details.

Zero Receipts

This type of exception occurs when a location indicates to Merchandising that nothing was received for the item at the location by sending a receipt of zero and indicating that the carton is closed. Merchandising will reconcile the original ship-to location based on system option settings to determine where to write off the lost items.

If a zero receipt occurs for an item that is part of a misdirected container, then some slightly different processing will occur. If the zero receipt is sent after a misdirected container reconciliation, then no further updates will be made, as the line would have been previously reconciled. If a zero receipt occurs before misdirected container processing, then the misdirected container processing at the actual receiving location will be treated as an overage, as the original location would have already been reconciled.

Other Key Notes

Externally generated warehouse-to-warehouse transfers are not supported in Merchandising, where the transfer is created in Merchandising at the physical warehouse level for both locations. For example, a warehouse-to-warehouse transfer created in WMS. This includes the receipt of such a transfer using this API.
Wrong store receiving is not supported for franchise transactions.
Merchandising doesn’t process the top level of this message (ReceiptDesc) or the UIN level details.

Receipt

This node contains the receipt level details to be processed by Merchandising.

Message Element	Required?	Notes
DC Destination ID	Always	Indicates the location that has processed the receipt. For stores, this will be the store ID. For warehouses, this will be the physical warehouse ID.
PO Number	Always	Indicates the transaction that the receipt is for. This must be a valid allocation, transfer or PO number
Customer Order Number	Optional	Not used in Merchandising
Fulfillment Order Number	Optional	Not used in Merchandising
Document Type	Always	Specifies whether the receipt is for an allocation (A), purchase order (P), or transfer (T, D, or V).
Reference Document Number	Optional	Contains a reference number for a document associated to the shipment (e.g., Fiscal Document ID for Brazilian based transactions).
ASN Number	Conditional	Used to relate the receipt message to the previous ASN message. This field is required for transfers and allocations.
Receipt Type	Optional	This field is used in receiving transfers or allocations to determine if the receipt is at the BOL level (BL) or SKU level (SK). If not provided, the value will be defaulted to SK. It is not used for a PO receipt.
From Location	Optional	This field contains the source location of the shipment.
From Location Type	Optional	This field contains the source location type of the shipment. Valid values are: SU - supplier ST - store WH - warehouse
Status	Optional	Indicates the status of the ASN received. This field is used only for stock order receiving. A status of C indicates that the entire ASN is will be set to closed.

Child Nodes

Receipt Detail
Receipt Carton Detail

Receipt Detail

This is a required child node to the receipt level only for item level stock order receipts. For carton level receipts, this should not be populated.

Message Element	Required?	Notes
Item ID	Always	Specifies the item on the allocation, purchase order, or transfer that has been received.
Unit Quantity	Always	Contains the quantity received for the allocation, purchase order, or transfer in the standard unit of measure.
Receipt Transaction Type	Always	Specifies whether the receipt detail line item is for a Receipt (R), Transshipment (T), or Adjustment (A).
Receipt Date	Optional	Identifies the date on which the transaction was received.
Receipt Number	Optional	An externally generated numerical identifier corresponding to the receipt of the item at the location.
Destination ID	Optional	Only used for purchase order receipt, when the purchase order has an allocation attached to it. This element specifies the location to which the allocation is being sent.
Container ID	Optional	Identifies the carton number for the item being received.
Reference Container ID	Optional	Identifies the original carton number the item was shipped under, if it was being received at the wrong destination. This is required by Merchandising to process the updates correctly, as SIOCS reassigns the container ID at the receiving location.
Distro Number	Optional	Only used for purchase order receipts, when the purchase order has an allocation attached to it. This element contains the allocation id.
Distro Document Type	Optional	Only used for purchase orders, when the purchase order has an allocation attached to it. When populated, this value should always be A to specify an allocation.
From Disposition	Optional	This value is used to determine inventory availability. Valid values are in the INV_STATUS_CODES table. The from disposition is used when the to disposition is not provided.
To Disposition	Optional	This value is used to determine if the inventory is available or unavailable, based on the code's INV_STATUS value on the INV_STATUS_CODES table.
To WIP	Optional	Not used in Merchandising
From WIP	Optional	Not used in Merchandising
To Trouble	Optional	Not used in Merchandising
From Trouble	Optional	Not used in Merchandising
User ID	Optional	Not used in Merchandising
Dummy Carton	Optional	Indicates if this carton is a dummy carton. This field is only used for transfer receipts. Valid values are yes (Y) or no (N).
Tampered Carton	Optional	Indicates if the carton was tampered. This field is only used for transfer receipts. Valid values are yes (Y) or no (N).
Unit Cost	Optional	Only used for purchase order receipts. This specifies the unit cost of the item on the order. Cost is converted to the order's currency before insert/update.
Shipped Quantity	Optional	Only used for purchase order receipts. Updates the number of items expected to be received, originally set by the ASN process.
Weight	Optional	Contains the actual weight of the item received for the shipment. This will be included for some catch weight items.
Weight UOM	Optional	Contains the unit of measure of the received weight (e.g., pounds, kilograms) where UOM class is of type MASS. Weight and Weight UOM must both be populated, or both must be NULL.
Gross Cost	Optional	Contains the Unit cost and Expenses incurred on an item in a particular transaction.
Item Line Number	Optional	This field indicates the item line number from customer orders. This must be populated for systems with OMS_IND = Y and RESV_CO_ON_RECEIPT = Y.

Receipt Carton Detail

This is only used for stock order receiving as an alternative to the item level node.

Message Element	Required?	Notes
Carton Status	Conditional	Indicates the status of the carton being received. Valid values are: Actual (A) – this is used for normal carton receiving at the correct location Overage (O) – this should be used if the carton doesn’t belong to the BOL/location being received. In this case, Merchandising will attempt to match the container to the correct BOL. See receiving exceptions above. Dummy BOL (D) – this should be used if the BOL used in the receipt is not valid for the carton/location. In this case, Merchandising will attempt to match the container to the correct BOL. See receiving exceptions above. Closed (C) – indicates that the carton is closed and no more receipts are expected. In this case, Merchandising will reconcile any outstanding quantity for the carton immediately.
Container ID	Conditional	Indicates the container being received. This must be populated for carton level receiving.
Reference Container ID	Optional	Not being used in Merchandising.
Destination ID	Optional	Identifies the location to which the stock order is received.
Receipt Transaction Type	Required	Specifies whether the carton receipt is for a Receipt (R), Transshipment (T), or Adjustment (A).
Receipt Date	Optional	This field contains the date when the carton is received.
Receipt Number	Optional	This field holds the externally generated number when the shipment is received at the location.
User ID	Optional	Not used by Merchandising.
To Disposition	Optional	This value is used to determine inventory availability of the received quantity. Valid values are in the INV_STATUS_CODES table.
Weight	Optional	Contains the actual weight of the item received for the carton. This is used for catch weight containers.
Weight UOM	Optional	Contains the unit of measure of the received weight (e.g., pounds, kilograms) where UOM class is of type MASS. Weight and Weight UOM must both be populated, or both must be NULL.

Error Handling

Message XSD

Below are the filenames that correspond with each message type. Please consult the Oracle Retail Integration Guide for each message type for the details on the composition of each message.

Message Types	Message Type Description	XML Schema Definition (XSD)
receiptcre	Receipt Create Message	ReceiptDesc.xsd
receiptordcre	Receipt Create Message for Customer Orders	ReceiptDesc.xsd
receiptmod	Receipt Modify (Adjustment) Message	ReceiptDesc.xsd

RTV Subscription API

This section describes the RTV subscription API.

Functional Area

Returns to Vendor

Business Overview

Merchandising subscribes to return-to-vendor (RTV) messages when an RTV is shipped out from a warehouse or store. This shipment could be for an RTV that was initially created in Merchandising or one initiated in the store or warehouse. The RTV information is sent from a warehouse management system (WMS), such as Oracle WMS Cloud, or the store inventory solutions, such as Oracle Retail Store Inventory and Operations Cloud Service (SIOCS) when the RTV is shipped out of the location.

Note:

Unlike other RIB messages, both new and updates sent through this message use the RTVCre message type.

New RTVs

If the message contains a new RTV generated in the store or warehouse, then it must contain both header and detail information. RTV create messages can only be sent in Approved or Shipped status.

Updated RTVs

If this is an update to an RTV, it can be performed through this API. To update an RTV, you can send either the header information only or both header and detail information. The most common update is to ship a previously created RTV. Approved RTVs can be Shipped if the RTV is created in Merchandising or SIOCS.

It is assumed that RTVs from the warehouse are always created in Shipped status.

Note:

Once RTVs are shipped, they cannot be changed back to Approved. Alternatively, approved RTVs can also be set to Cancelled status, if for some reason they cannot be shipped.

RTV Header

Message Element	Required	Notes
Destination ID	Always	Contains the location shipping the RTV - either the store ID or the physical warehouse ID.
RTV ID	Always	This contains the external reference number for RTVs created outside of Merchandising.
Return Authorization Number	Optional	Contains the number that the supplier provides when the decision is made that the merchandise may be returned. This will be required depending on the configuration of the supplier site in Merchandising.
Vendor Number	Always	Contains the supplier site ID to which the merchandise is being returned. The site must be configured in Merchandising to allow returns.
Address 1	Optional	Contains the first line of the supplier's address for returns. If not provided, the address for an externally created RTV will be pulled from the supplier address information in Merchandising. This applies for all of the below address fields as well.
Address 2	Optional	Contains the second line of the supplier's address for returns.
Address 3	Optional	Contains the third line of the supplier's address for returns.
State	Optional	Contains the state of the supplier's address for returns. The state and country combination must be valid.
City	Optional	Contains the city of the supplier's address for returns.
Postal Code	Optional	Contains the postal code of the supplier's address for returns.
Country	Optional	Contains the country ID of the supplier's address for returns. The state and country combination must be valid.
Creation Time Stamp	Optional	Contains the date the vendor return was created. This defaults to current date if not specified for an externally generated RTV.
Comments	Optional	Contains any comments associated with the return.
RTV Order Number	Optional	This contains the RTV ID generated by Merchandising when the event was created. For externally generated RTVs, this should be NULL.
Status	Optional	This value is used to determine the current status of an externally generated RTV. Valid values are Approved (A) or Shipped (S). If this is Approved, Merchandising will create the RTV and set it to an In Progress status. If this is Shipped or null, it will be set to Shipped status when created or updated.

Child Node

RTV Details
Flex Attribute

RTV Details

Message Element	Required	Notes

Item ID	Always	Unique identifier for the item on the RTV. The item must be a transaction level inventory item or reference item.
Unit Quantity	Always	Contains the quantity of the item being returned to the supplier under this RTV number. A quantity less than zero indicates a quantity cancellation. If the RTV is already in progress, the quantity in the message must not be zero.
Container Quantity	Optional	Not used in Merchandising
From Disposition	Optional	This value is used to determine if the inventory is available or unavailable. Valid values are based on the INV_STATUS values in the INV_STATUS_CODES table.
To Disposition	Optional	Not used in Merchandising
Unit Cost	Optional	Contains the cost per unit for the SKU being returned. This field is stored in the supplier's currency. If not provided, then value will be defaulted based on the system option RTV Unit Cost Source setting - either the from location's weighted average cost, last received cost, or standard cost.
Reason	Optional	Identifies the reason for the return. Valid values are for this field are held in the Merchandising codes tables under code type RTVR. By default, the values are: Q - QC Failed U - Unavailable Inventory. W - Externally Initiated RTV If the reason is not provided for an externally generated RTV, it will be defaulted to W.
Weight	Optional	Actual weight shipped for the item on the RTV, which is used for some catch weight items. It is expected that either both weight and weight UOM have a value or neither have a value.
Weight UOM	Optional	Indicates the unit of measure represented for the provided weight (for example, pounds, kilograms) where UOM class is of type MASS. It is expected that either both weight and weight UOM have a value or neither have a value.
Gross Cost	Optional	Contains the unit cost and expenses incurred on an item in a particular transaction. This is used for Brazil processing only. For all implementations not using the Brazil Localization configuration, this should be NULL.
RTV Detail UIN	Optional	Not used in Merchandising

Flex Attributes

If flex attributes have been defined for an RTV they can be included in this node of the message.

Message Element	Required	Notes
Name	Always	The flex attribute name defined by the business
Value	Optional	The value of the flex attribute defined by the business for alphanumeric or number attributes.
Value Date	Optional	The date value of the flex attribute, if the flex attribute is defined as a date.

Error Handling

Message XSD

Here are the filenames that correspond with each message type. Please consult the RIB documentation for each message type in order to get a detailed picture of the composition of each message.

Message Types	Message Type Description	XML Schema Definition (XSD)
rtvcre	RTV Create Message	RTVDesc.xsd

Stock Count Schedule Subscription API

This section describes the stock count schedule subscription API.

Functional Area

Inventory

Business Overview

Stock count schedule messages are published to the RIB by an inventory sub-system, such as Oracle Retail Store Inventory and Operations Cloud Service (SIOCS), to communicate unit and value stock count schedules to Merchandising. Merchandising uses stock count schedule data to help synchronize the inventories of the integrated system and Merchandising. The integrated system then performs a physical inventory count and uploads the results, and Merchandising compares the discrepancies.

This API allows the external systems to create, update, and delete Unit and Value stock count requests within Merchandising. The count is assumed to be for the full location, unless department, class and subclass data are included.

Creating/Updating Stock Count Requests

When a new stock count request is created or an existing stock count request is modified, this API will validate all the required fields are present in the message. Required information for the stock count includes a description, date, type (always B), location type, and locations. Optionally the merchandise hierarchy information can also be included, but, if not included, it will be assumed the entire location will be counted. After the required field and business validations, the stock counts will be created or updated in Merchandising.

The format used when creating or modifying a stock count is shown below.

Table 3-93 Stock Count Header

Message Element	Required?	Notes
Cycle Count	Yes	This field contains the number which uniquely identifies the stock or cycle count.
Cycle Count Description	Yes	This field contains a description of the cycle or stock count which, along with the cycle count number, identifies the cycle or stock count.
Location Type	Yes	This field contains an indicator which identifies whether the cycle count will be for Stores or Warehouses. Valid values are Store (S) and Warehouse (W).
Stocktake Date	Yes	This field contains the date on which the stock or cycle count will take place. This date should be greater or equal to the current date plus the stake lockout days defined at system level.
Stocktake Type	Yes	This field contains a value which indicates the stock take type. Valid values are Both Unit and Dollar (B) and Unit only (U). However, the RIB interface only allows modification of Unit and Dollar stock take types.
Stock Count Schedule Products	No	Child node
Stock Count Schedule Locations	No	Child node

Table 3-94 Stock Count Schedule Products

Message Element	Required?	Notes
Department	Yes	This field contains the department number where the cycle count will occur. If the value = -1, the stock count will apply to all departments. The dept/class/subclass hierarchy must be a valid hierarchy in Merchandising.
Class	No	This field contains the class number where the cycle count will occur. The dept/class/subclass hierarchy must be a valid hierarchy in Merchandising.
Subclass	No	This field contains the subclass number where the cycle count will occur. The dept/class/subclass hierarchy must be a valid hierarchy in Merchandising.

Table 3-95 Stock Count Schedule Locations

Message Element	Required?	Notes
Location	Yes	This field contains the store or warehouse number on the cycle count. This must be a valid store or a stockholding warehouse in Merchandising.

Deleting Stock Count Requests

When an existing stock count request is deleted, this API will validate all the required fields are present in the message. After required field and business validation, the stock counts will be removed in Merchandising. This API also supports deleting a location from the count. The count and locations can only be deleted through this API if no results have been processed for the location on the count. If the last location is deleted from the count, then the count itself will be deleted.

The format used when deleting a stock count is shown below.

Table 3-96 Stock Count Header

Message Element	Required?	Notes
Cycle Count	Yes	This field contains the number which uniquely identifies the stock or cycle count being deleted.
Stock Count Schedule Locations	No	Child node

Table 3-97 Stock Count Schedule Locations

Message Element	Required?	Notes
Location	Yes	This field contains the store or warehouse being deleted on the cycle count.

Error Handling

Message XSD

Below are the filenames that correspond with each message type. Please consult the RIB documentation for each message type to get a detailed picture of the composition of each message.

Message Types	Message Type Description	XML Schema Definition (XSD)
stkcountschcre	Stock Count Schedule Create Message	StkCountSchDesc.xsd
stkcountschmod	Stock Count Schedule Modify Message	StkCountSchDesc.xsd
stkcountschdel	Stock Count Schedule Delete Message	StkCountSchRef.xsd
stkcountschtldel	Stock Count Schedule Delete Message for a Location	StkCountSchRef.xsd

Stock Order Status Subscription API

This section describes the stock order status subscription API.

Functional Area

Inventory Movement

Business Overview

A stock order is an outbound merchandise request from a warehouse or store. In Merchandising, a stock order takes the form of either a transfer or allocation. Merchandising subscribes to stock order status messages published by an external application, such as a store system (SIOCS, for example) or a warehouse management system (Oracle WMS Cloud, for example) to communicate the status of a specific stock order.

Stock Order Statuses

The following tables describe the stock order statuses for both transfers and allocation document types and what occurs in Merchandising after receiving the respective status. Statuses other than listed below are ignored by Merchandising.

Statuses for Document Types T, D, and S

Document types of T, D, and S all refer to transfers and indicate whether the transfer is initiated in Merchandising, a warehouse system, or a store system, respectively.

Stock Order Status	What Merchandising does
SI (Stock Increased)	Insert or increase transfer quantity and increase item/location transfer reserve quantity for the source location and transfer expected quantity for the destination location.
SD (Stock Decreased)	Delete or decrease the transfer quantity for the transfer/item combination. Transfer quantity for the transfer/item combination will be deleted if the transfer has been created but has not been shipped. Additionally, the item/location transfer reserved quantity for the source location and the transfer expected quantity for the destination location will be decreased.
DS (Details Selected)	Increase the selected quantity for the transfer/item combination.
DU (Details Un-selected)	Decrease the selected quantity for the transfer/item combination.
NI (WMS Line Cancellation)	Decrease selected and transfer quantity for the transfer/item by the quantity on the message and increase the cancelled quantity. Additionally, it will decrease the reserved quantity for the source location and decrease the expected quantity for the destination location by the lesser of the quantity on the message and transfer - shipped quantity. The transfer will also be added to the document close queue if transfer status is not closed. Document Close batch program will then determine if the transfer should be closed based on certain conditions. Transfers with outstanding appointments are not closed.
PP (Distributed)	Decreases the selected quantity and increases the distro quantity for the transfer/item.
PU (Un-Distribute)	Decreases the distro quantity for the transfer/item.
RS (Return to Stock)	Decreases distro quantity and transfer quantity for the transfer/item; the cancelled quantity for the transfer/item is increased. Additionally, transfer reserved is decreased for the item/source location and transfer expected is decreased for the item/destination location for the lesser of the quantity in the message and the transfer - shipped quantity if the transfer status is not closed.
EX (Expired)	Decreases transfer quantity for the transfer/item; the cancelled quantity for the transfer/item is increased. Additionally, transfer reserved is decreased for the item/source location and transfer expected is decreased for the item/destination location for the lesser of the quantity in the message and the transfer - shipped quantity if the transfer status is not closed. The transfer will also be added to the document close queue if transfer status is not closed. Document Close batch program will then determine if the transfer should be closed based on certain conditions. Transfers with outstanding appointments are not closed.
SR (Store Reassign)	Updates the distro quantity for the transfer/item. This can either increase or decrease the value, depending on whether a positive or negative value is sent.

Statuses for Document Type A

Document type A is always used for Allocations.

Stock Order Status	What Merchandising does
SI (Stock Increased)	Insert or increase allocated quantity and increase item/location transfer reserve quantity for the source location and transfer expected quantity for the destination location.
SD (Stock Decreased)	Decrease the allocated quantity for the allocation/item combination. Additionally, the item/location transfer reserved quantity for the source location and the transfer expected quantity for the destination location will be decreased.
DS (Details Selected)	Increase the selected quantity for the allocation/item combination.
DU (Details Un-Selected)	Decrease the selected quantity for the allocation/item combination.
NI (WMS Line Cancellation)	Decrease selected and allocation quantity for the allocation/item by the quantity on the message and increase the cancelled quantity. Additionally, it will decrease the reserved quantity for the source location and decrease the expected quantity for the destination location by the lesser of the quantity on the message and allocation - shipped quantity if the allocation is not closed. The allocation will also be added to the document close queue if allocation status is not closed. Document Close batch program will then determine if the allocation should be closed based on certain conditions. Allocations with outstanding appointments are not closed.
PP (Distributed)	Decreases the selected quantity and increases the distro quantity for the allocation/item.
PU (Un-Distribute)	Decreases the distro quantity for the allocation/item.
RS (Return to Stock)	Decreases distro quantity and allocation quantity for the allocation/item; the cancelled quantity for the allocation/item is increased. Additionally, transfer reserved is decreased for the item/source location and transfer expected is decreased for the item/destination location for the lesser of the quantity in the message and the allocation - shipped quantity if the allocation status is not closed.
EX (Expired)	Decreases allocation quantity for the allocation/item; the cancelled quantity for the allocation/item is increased. Additionally, transfer reserved is decreased for the item/source location and transfer expected is decreased for the item/destination location for the lesser of the quantity in the message and the allocation - shipped quantity if the allocation status is not closed. The allocation will also be added to the document close queue if allocation status is not closed. Document Close batch program will then determine if the allocation should be closed based on certain conditions. Allocations with outstanding appointments are not closed.
SR (Store Reassign)	Updates the distro quantity for the allocation/item. This can either increase or decrease the value, depending on whether a positive or negative value is sent.

For customer orders, Merchandising assumes it will receive updates from an OMS for customer order related stock orders. Therefore, to avoid duplicate processing, Merchandising will ignore No Inventory, Expired, Stock Decreased, and Stock Increased statuses received for a customer order transfer.

Stock Order Status Message Details

The table below summarizes the elements applicable for this API.

Stock Order Status Header

Message Element	Required?	Notes
DC Destination ID	Always	This field contains the location number of the stock order source location.
Location Type	Always	This field contains the type of location in the DC Destination ID field. Valid values are: S - Store W - Warehouse E - Finisher
Store Type	Optional	This field indicates the store type of the DC Destination ID if it is a store. Valid values are: C - company store F - franchise store
Stockholding Indicator	Optional	This field indicates if the DC Destination ID is stockholding or not. Only populated if location type is 'S'. Valid values are Yes (Y) and No (N).
Distro Number	Optional	This field contains the stock order number. This is either the transfer or allocation number in Merchandising.
Distro Document Type	Always	This field specifies whether the stock order status pertains to an allocation (A) or transfer (T) that is already existing in Merchandising. Created Stock Order (D), Customer Order (C), and Virtual Distro (V) are also valid document types but will be ignored by Merchandising.
Context Type	Optional	This field holds the functional area code to which the transfer relates to. Valid values are Promotion (PROM) and Repairing (REPAIR).
Context Value	Optional	This field holds the value relating to the context type like promotion number.
Inventory Type	Optional	This field indicates if a transfer is made from the available (A) or unavailable (U) inventory.
Customer Order Number	Optional	This field holds the master customer order number for a stock order associated with a customer order.
Fulfillment Order Number	Optional	This field holds the number related to the fulfillment details for a stock order associated with a customer order. One or more fulfillment orders could relate back to a single customer order.
System Code	Optional	Not used by Merchandising
From Location Virtual WH	Optional	This field contains the virtual warehouse number of the stock order source location.
Stock Order Status Details	Optional	Child node
Custom Flex Attributes	Optional	Child node – not used by Merchandising

Stock Order Status Detail

Message Element	Required?	Notes
Destination ID	Always	This field contains the location number of the stock order receiving location.
Location Type	Always	This field contains the type of location in the Destination ID field. Valid values are: S - Store W – Warehouse E - Finisher
Store Type	Optional	This field indicates the store type of the Destination ID, if a store. Valid values are: C - Company Store F – Franchise Store
Stockholding Indicator	Optional	This field indicates if the Destination ID is stockholding. Only populated if location type is 'S'. Valid values are: Yes (Y) and No (N).
Item	Always	This field contains the unique identifier for the item.
Original Item	Optional	This field contains the ID of the item being replaced. Populated only when this record is for a substitute item on a customer order.
Order Line Number	Optional	This field is used to carry the customer order line number value for customer orders. It is a derived value for non-customer orders.
Unit Quantity	Optional	This field contains the difference between the number of item units shipped versus the receiving count for the given item. This is subtracted from the document-line-item-unit-count to yield an over/under variance between what a supplier said was shipped and what was counted and received at by the store's staff.
Status	Optional	This field contains the status of the stock order. Valid values are: Accepted (SI), Rejected (SD), Distributed (PP), Un-Distributed (PU), Details Selected (DS), Details Un-selected (DU), WMS Line Cancellation (NI), Return To Stock (RS), Expired (EX), and Store Reassign (SR). Statuses other than listed are ignored by Merchandising. For stock order status explanations, please refer to the Stock Order Statuses section.
User ID	Optional	This field contains the user ID of the user who created the stock order status.
Updated Date	Optional	This field contains the date the stock order status was updated.

Error Handling

Message XSD

Below are the filenames that correspond with each message type. Please consult the Oracle Retail Integration Guide for each message type for the details on the composition of each message.

Message Types	Message Type Description	XML Schema Definition (XSD)
sostatuscre	Stock Order Status Create Message	SOStatusDesc.xsd
CustFlexAttriVo	Stock Order Status Flex Attribute Create	SOStatusDesc.xsd

Store Subscription API

This section describes the store subscription API.

Functional Area

Foundation Data

Business Overview

The Store Subscription API provides the ability to keep store data in Merchandising in sync with an external system if Merchandising is not being used as the system of record for organizational hierarchy information. The store data handled by the API includes basic store data in addition to addresses, store hours, location traits, up-charges, and walk-through stores. Walkthrough stores are used in Merchandising as part of the transfer reconciliation process and are used to indicate two or more stores that have a 'walk through' connection between them - on the sales floor and/or the backroom.

Create or Update Stores

When creating a new store in Merchandising through this API, the data is validated and placed onto the staging table STORE_ADD. The store creation in Merchandising reads from this table and creates the store in Merchandising in an asynchronous mode. When updating an existing store in Merchandising, the API performs the update immediately upon message receipt.

Delete Stores

The API also handles store delete messages. But, like the store creation message subscription process, stores will not actually be deleted from the system upon receipt of the message. After the data has been validated, the store is added to the DAILY_PURGE table for processing through a batch process.

Other Store Attributes

Location traits, walkthrough stores, department-level up-charges, store hours, address data and CFAs must be processed separately as they each have their own distinct message types for creation and deletion.

Location traits and walkthrough store attributes cannot be sent in on a store create message. The store create batch must first process the store before it can have these attributes attached to it. Up-charges, store hours, and addresses can be included for new stores.

The store subscription message also supports the ability to import custom flex attributes from an external system.

Other Notes

Location traits must already exist prior to being added to the store.
Stores and warehouses in Merchandising cannot have the same unique identifier.
Location trait and walkthrough store data cannot be sent on a store create message.

Store Message Details

The table below summarizes the elements applicable for this API.

Table 3-98 Store Create or Update

Message Element	Required?	Notes
Store	Always	This field contains the unique identifier of the store.
Store Name	Always	This field contains the name of the store.
Store Type	Optional	Indicates the type of store. Valid values are: company store (C), franchise store (F).
Store Name (10)	Optional	This field contains the ten-character abbreviation of the store name.
Store Name (3)	Optional	This field contains the three-character abbreviation of the store name
Store Class	Always	This field contains code of the class of which the store is a member. Valid values are A through E.
Store Manager Name	Always	This field holds the name of the store manager.
Store Open Date	Always	This field holds the date on which the store opened.
Store Close Date	Optional	This field holds the date on which the store closed.
Acquired Date	Optional	This field holds the date on which the store was acquired.
Remodel Date	Optional	This field holds the date on which the store was remodeled.
Fax Number	Optional	This field contains the fax number for the store.
Phone Number	Optional	This field contains the phone number for the store.
Email	Optional	This field contains the email address of the store.
Total Square Feet	Optional	This field contains the total square footage of the store.
Selling Square Feet	Optional	This field contains the total square footage of the store's selling area.
Linear Distance	Optional	This field contains the total merchandise space of the store.
Stockholding Indicator	Always	This field indicates if the store can hold stock. Valid values are yes (Y) or no (N). This field cannot be modified.
Channel ID	Always	This field contains the identifier of the channel. This value must be predefined on the CHANNELS table.
Store Format	Optional	This field contains the code of the store format of the store. This value must be predefined on the STORE_FORMAT table.
Mall Name	Optional	This field contains the name of the mall in which the store is located.
District	Always	This field contains the number of the district of which the store is a member. This value must be predefined on the DISTRICT table.
Promo Zone	Optional	Not used by Merchandising.
Transfer Zone	Always	This field contains the transfer zone in which the store is located. This value must be predefined on the TSFZONE table.
Default WH	Optional	This field contains the default warehouse for the store. This value must be a virtual warehouse predefined on the WH table.
Stop Order Days	Optional	This field contains the number of days before the store close date that the store will stop accepting orders.
Start Order Days	Always	This field contains the number of days before the store open date that the store will begin accepting orders.
Currency Code	Always	This field contains the currency code under which the store operates. This value must be predefined on the CURRENCIES table. It cannot be modified.
Language	Optional	This field contains the code of the language used at the store. This value must be predefined on the LANG table. Either ISO code or Lang should not be null. If this field is null, ISO Code will be used for looking up the language to be used.
ISO Code	Optional	This field contains the International Organization for Standards (ISO) character code corresponding to the language used at the store. Either ISO code or Lang should not be null.
Integrated POS Indicator	Always	This field indicates whether Sales Audit should expect files from this store for processing. Valid values are Yes (Y) or No (N).
DUNS Number	Optional	This field holds the Dun and Bradstreet number to identify the store.
DUNS Location	Optional	This field holds the Dun and Bradstreet number to identify the location.
Copy Delivery Indicator	Conditional	This field indicates if the like store's delivery schedule information should be copied to the new store. This value cannot be modified. It will only be used on a store create message.
Copy Activity Indicator	Conditional	This field indicates if the like store's closing date schedule should be copied to the new store. This value cannot be modified. It will only be used on a store create message.
Price Store	Conditional	This field contains the store from which pricing information will be copied to the new store. The pricing store does not need the same currency as the new store.
Cost Location	Conditional	This field contains the location from which to copy cost information to the new store. This field should only be included on store create messages. This value must be existing store or virtual warehouse.
VAT Include Indicator	Optional	This field contains whether tax will be included in the retail prices for the store. Valid values are Yes (Y) or No (N).
VAT Region	Conditional	This field contains the ID of the tax region the store is associated with. This value must be predefined on the VAT_REGION table. It is required if Merchandising is configured for Simple VAT or Global Tax.
Like Store	Conditional	This field holds the store from which the new store will have item/locations copied. This value must be predefined on the STORE table. It cannot be modified and will only be used in a create message.
Copy Replenishment Indicator	Conditional	This field indicates whether replenishment information should be copied from the like store to the new store. This field cannot be modified. It will only be populated on a store create message.
Transfer Entity	Conditional	This field contains the transfer entity of which the store is a part. This value must be predefined on the TSF_ENTITY table. If the system allows intercompany transfers this field is required.
Sister Store	Optional	This field contains the store which will be used to relate historical data to the new store in Allocation. This value must be predefined on the STORE table.
Transaction Number Generated	Always	This field holds the level at which unique POS transaction numbers are generated. Valid values are Store (S) and Register (R).
County	Optional	This field contains the county in which the store is located.
Time Zone Name	Optional	This field contains the Time Zone name.
WF Customer ID	Optional	This field contains the ID associated with a franchise customer for a franchise store. This is required for a franchise store type and should be null for a company store.
Org Unit ID	Optional	This field contains the organizational unit ID value of the store.
Secondary Store Name	Conditional	This field contains the secondary name of the store.
Customer Order Location Indicator	Optional	Indicates that the store can be used to source or fulfill customer orders. Valid values are yes (Y) or no (N).
Gift Wrapping Indicator	Optional	This field indicates weathere a gift wrapping needs to be done or not.
Customer Order Ship Indicator	Optional	This field indicates wheather the customer order has been been shipped from Warehouse or not.
Tax Id	Optional	Contains the unique tax identification number of the store.
Online Store Indicator	Optional	This field indicates how store day will be managed by ReSA. If the indicator is Y then ReSA will automatically open and close the store day.
Store Location Trait	Optional	Child node
Walkthrough Store	Optional	Child node
Store Address	Optional	Child node
Store Hours	Optional	Child node
Store Department Up-charge	Optional	Child node
Custom Flex Attributes	Optional	Child node

Table 3-99 Store Location Trait Create

Message Element	Required?	Notes
Location Trait	Conditional	The identifier of the location trait. Though the node is optional, this field is required if the node is included. The node cannot be populated in the store create message.

Table 3-100 Walkthrough Store Create

Message Element	Required?	Notes
Walkthrough Store	Conditional	A walk-through store of the store being modified. Though the node is optional if it is included this field is required. This node cannot be populated in a store create message.

Table 3-101 Store Address Create or Update

Message Element	Required?	Notes
City ID	Optional	This field contains the city ID or code.
State Name	Optional	This field contains the state name.
Country Name	Optional	This field contains the country name.
Address	Always	This field holds the unique address ID from the source system.
Address Type	Always	This field indicates the type for the address. Valid values are in the ADD_TYPE table. Mandatory address types for a new store are Business (01) and Postal (02).
Primary Address Indicator	Always	This field indicates whether this address is the primary address for this address type. At least one address must be designated as primary for each type.
Address 1	Always	This field contains the first line of the address.
Address 2	Optional	This field contains the second line of the address.
Address 3	Optional	This field contains the third line of the address.
City	Always	This field contains the name of the city that is associated with the address.
State	Optional	This field contains the abbreviation for the state in which the store is located.
Country ID	Always	This field contains the country code where the address exists.
Post	Optional	This field contains the postal code for the address.
Contact Name	Optional	This field contains the name of the contact for the supplier at this address.
Contact Phone	Optional	This field contains the phone number of the contact person at this address.
Contact Telex	Optional	This field contains the telex number of the store’s representative contact.
Contact Fax	Optional	This field contains the fax number of the contact person at this address.
Contact Email	Optional	This field contains the email address of the store’s representative contact.
Oracle Vendor Site ID	Conditional	This field contains the unique identifier of this address in the Oracle Financials, if used.
County	Optional	This field contains the county name for the location.
Jurisdiction Code	Optional	This field contains the ID associated to the tax jurisdiction of the country-state relationship.
Custom Flex Attributes	Optional	Child node

Table 3-102 Store Hours Create or Update

Message Element	Required?	Notes
Store ID	Always	This field contains the unique ID of the store.
Day Number	Always	This field indicates the day of the week for which store timing is being stored. Valid values are from 1 (Sunday) through 7 (Saturday).
Store Open Time	Optional	This field contains the open time for the store. Open time should be in 12-hour format (HH:MI AM or HH:MI).
Store Close Time	Optional	This field contains the close time for the store. Close time should be in 12-hour format (HH:MI AM or HH:MI).

Table 3-103 Store Department Up-charge Header Create or Update

Message Element	Required?	Notes
Hierarchy Level	Always	The hierarchy level for which the up charges are being added or updated. Valid values are Division (DI), Group (GR), Department (DE), and All Departments (AD).
Hierarchy	Optional	The value of the hierarchy based on the level. If the level is division, group, or department, then this should contain a valid ID of that type. If All Departments is the hierarchy level, then this should be left blank.
From Location	Optional	Contains the source location for which the up changes for the hierarchy will apply. Valid values are a country, area, region, store, virtual warehouse, or physical warehouse ID, depending on the from location type included. If the from location type sent is AS or AW, this should be left null.
To Location	Optional	Contains the destination location for which the up changes for the hierarchy will apply. Valid values are a country, area, region, store, virtual warehouse, or physical warehouse ID, depending on the from location type included. If the from location type sent is AS or AW, this should be left null.
From Location Type	Always	Indicates the type of location included as the From Location. Valid values are Country (C), Area (A), Region (R), Store (S), Virtual Warehouse (W), Physical Warehouse (PW), All Stores (AS), or All Warehouses (AW).
To Location Type	Always	Contains the type of location included as the To Location. Valid values are Country (C), Area (A), Region (R), Store (S), Virtual Warehouse (W), Physical Warehouse (PW), All Stores (AS), or All Warehouses (AW).
Store Department Up-charge Details	Optional	Child node

Table 3-104 Store Department Up-charge Details Create or Update

Message Element	Required?	Notes
Component ID	Always	This field contains the unique identifier of the up-charge component.
Component Rate	Always	This field contains the rate to be charged based on the transfer/allocation cost for items in the hierarchy and between from and to locations defined in the up-charge header.
Per Count	Optional	If the component was defined with a calculation basis of Specific, then this field is used to determine how the rate is applied to the items on a transfer or allocation. If the component is defined as Value, this should be blank.
Per Count UOM	Optional	Indicates the unit of measure in which the Per Count is specified.
Up-charge Group	Always	This field contains the group to which the component ID belongs. Valid values can be found on the codes table with a code type of UCHG.
Component Currency	Always	This field contains the currency of the Up Charge component.
Effective Date	Optional	The date from which the new values are effective in the system.
Item Default Indicator	Optional	By default, up-charges defined will be defaulted for new items created in the hierarchy designated at the header level. But this indicator allows you to add the new or updated upcharge to an existing item in the hierarchy. Valid values are Y or N.
Transfer Allocation Default Indicator	Optional	Indicates if component information should be applied to any unshipped transfers or allocations with items and locations that qualify. Valid values are Y or N.

Table 3-105 Store Delete

Message Element	Required?	Notes
Store	Always	The store number being deleted, or for which a location trait or walk through store is being disassociated.
Store Location Trait	Optional	Child node
Walkthrough Store	Optional	Child node
Store Address	Optional	Child node
Store Hours	Optional	Child node
Store Department Up-charge	Optional	Child node

Table 3-106 Store Location Trait Delete

Message Element	Required?	Notes
Location Trait	Conditional	The identifier of the location trait. Though the node is optional, this field is required if the node is included. The node cannot be populated in the store create message.

Table 3-107 Walkthrough Store Delete

Message Element	Required?	Notes
Walkthrough Store	Conditional	A walk-through store of the store being modified. Though the node is optional if it is included this field is required. This node cannot be populated in a store create message.

Table 3-108 Store Address Delete

Message Element	Required?	Notes
Address	Always	The unique identifier of the address being deleted.

Table 3-109 Store Hours Delete

Message Element	Required?	Notes
Store ID	Always	This field contains the unique ID of the store.
Day Number	Always	This field indicates the day of the week for which store timing is being stored. Valid values are from 1 (Sunday) though 7 (Saturday).

Table 3-110 Store Department Up-charge Header Delete

Message Element	Required?	Notes
Hierarchy Level	Always	The hierarchy level for which the up charges are being deleted. Valid values are Division (DI), Group (GR), Department (DE), All Departments (AD).
Hierarchy	Optional	The value of the hierarchy.
From Location	Optional	Contains the source location from which goods will be transferred. This column can contain Country/Area/Region IDs when From Location Type is 'C', 'A', or 'R'. It will be a store, virtual warehouse, or physical warehouse when From Location Type is 'S', 'W' or 'PW'. Otherwise, it should be left blank when From Location Type is either 'AS' or 'AW'.
To Location	Optional	Contains the destination location to which goods will be transferred. This column can contain Country/Area/Region IDs when To Location Type is 'C', 'A', or 'R'. It will be a store, virtual warehouse or physical warehouse when To Location Type is 'S', 'W' or 'PW'. Otherwise, it should be left blank when To Location Type is either 'AS' or 'AW'.
From Location Type	Always	Contains the type of source location from which goods will be transferred. Valid values are Country (C), Area (A), Region (R), Store (S), Virtual Warehouse (W), Physical Warehouse (PW), All Stores (AS), or All Warehouses (AW).
To Location Type	Always	Contains the type of destination location to which goods will be transferred. Valid values are Country (C), Area (A), Region (R), Store (S), Virtual Warehouse (W), Physical Warehouse (PW), All Stores (AS), or All Warehouses (AW).
Store Department Up-charge Details	Optional	Child node

Table 3-111 Store Department Up-charge Details Delete

Message Element	Required?	Notes
Component ID	Optional	This field contains the unique identifier of the up-charge component.
Item Default Indicator	Optional	Indicates if component rate information is deleted or not for existing items under the department.
Transfer Allocation Default Indicator	Optional	Indicates if component rate information is deleted or not for existing transfers and allocations under the department.

Flex Attributes

If you have defined any custom flex attributes (CFAs) for stores or store addresses, then they can be integrated as part of this API. The node of the integration that supports this will accept the name of the attribute as it is defined in the group set level view and the value for the attribute.

Table 3-112 Custom Flex Attributes

Message Element	Required?	Notes
Name	Always	Indicates the name of the column defined in the group set view for flex attributes defined for the store.
Value	Always	Indicates the value of the attribute for the store if the attribute is a character or number.
Value Date	Always	Indicates the value of the attribute for the store if the attribute is a date.

Error Handling

Message XSD

Below are the filenames that correspond with each message type. Please consult the Oracle Retail Integration Guide for each message type for the details on the composition of each message.

Message Types	Message Type Description	XML Schema Definition (XSD)
XStoreCre	External Store Create	XStoreDesc.xsd
XStoreLocTrtCre	External Store Location Trait Create	XStoreDesc.xsd
XStoreWTCre	External Walk-Through Store Create	XStoreDesc.xsd
XStoreDeptChrgCre	External Department Up-Charge Create	XStoreDesc.xsd
XStoreAddrCre	External Store Address Create	XStoreDesc.xsd
XStoreHrCre	External Store Hours Create	XStoreDesc.xsd
CustFlexAttriVO	External Store Flex Attribute Create	XStoreDesc.xsd
XStoreMod	External Store Modification	XStoreDesc.xsd
XStoreDeptChrgMod	External Department Up-Charge Modify	XStoreDesc.xsd
XStoreAddrMod	External Store Address Modify	XStoreDesc.xsd
XStoreHrMod	External Store Hours Modify	XStoreDesc.xsd
CustFlexAttriVO	External Store Flex Attribute Modify	XStoreDesc.xsd
XStoreDel	External Store Delete	XStoreRef.xsd
XStoreLocTrtDel	External Store Location Trait Delete	XStoreRef.xsd
XStoreWTDel	External Walk-Through Store Delete	XStoreRef.xsd
XStoreDeptChrgDel	External Department Up-Charge Delete	XStoreRef.xsd
XStoreAddrDel	External Store Address Create	XStoreRef.xsd
XStoreHrDel	External Store Hours Delete	XStoreRef.xsd

Transfer Subscription API

This section describes the transfer subscription API.

Functional Area

Transfers

Business Overview

This API subscribes to transfers from external systems to create, update or delete transfers in Merchandising. Within Oracle Retail solutions, this API is also leveraged by Advanced Inventory Planning (AIP) to create standalone transfers generated out of its replenishment processing. AIP does not use this API to update or delete previously created transfers.

Creating Transfers

When a new transfer is created, this API will first validate that all required fields are present in the message. Certain of the fields are required regardless of transfer type and system configuration, while others are dependent on other Merchandising configurations. Additionally, when creating a new transfer at least one detail line must also be included in the message. After that, business level validation on the input information will be performed. The tables below summarize these two types of validation.

Table 3-113 Header Level Validation

Message Element	Required?	Notes
Transfer Number	Yes	Must be a unique transfer number not used by any existing transfers in Merchandising.
From Location Type	Yes	Must be either a store (S) or a warehouse (W).
From Location	Yes	See below.
To Location Type	Yes	Must be either a store (S), warehouse (W), or external finisher (E). For more on transfers with finishing, see below.
To Location	Yes	See below.
Delivery Date	Conditional	When AIP is part of your implementation, this is required for all transfer types, except RAC, EG, and SIM transfers. If included in the message, this must be today or a future date.
Department	Conditional	A system option determines whether or not the department is required for transfers. If the system option is set to require a department, then this must be included in the message. If the system option is set to not require the department, then the department must be null in this message unless the transfer type is SIM, AIP, or EG.
Routing Code	Conditional	If the freight code is Expedite (E), then this must have a value. Otherwise, it must be null. Valid values are 1, 2, or 3. The descriptions for these three options are held in the Codes table under code TRRC and can be configured as needed for your business.
Freight Code	No	If this is included in the message, it must have a value of normal (N), hold (H), or expedite (E). If no value is provided, it will default to normal.
Transfer Type	No	The following types of transfers can be created in this API: Administrative (AD) AIP Generated (AIP) Book (BT) Confirmation (CF) Externally Generated (EG) Intercompany (IC) Manual Requisition (MR) Reallocation (RAC) Return to Vendor (RV) SIM Generated (SIM) If the transfer type is not specified for the new transfer, then it will be defaulted to either Manual Requisition or Intercompany, depending on the legal entities of the locations on the transfer. See below for more details on transfer types.
Status	No	Transfers can be created in Input (I) or Approved (A) status in this API. See below for more on transfer status validation.
Create ID	No	If not passed into the message, then a value will be defaulted for auditing purposes.
Comments	No	Can support up to 2000 characters of text.
Context Type	No	Valid values for this field are found in the Codes table under code type CNTX.
Context Value	No	This may be used to provide additional information about the context of the transfer. For example, if the context type is promotion, this may indicate the promotion number or a description.
Custom Flex Attribute	No	Child node

Table 3-114 Detail Level Validation

Message Element	Required?	Notes
Item	Yes	An item must be a transaction-level, inventoried, and approved in order to be included on a transfer. If the transfer is from a store, then it cannot be a pack item, unless the transfer is of type AIP, SIM, or EG. Also, packs can also only be transferred from a warehouse if they have a receive as type of Pack, so that inventory exists at that level. If a department has been included in the transfer message at the header level, then all items must belong to that department.
Transfer Quantity	Yes	If the item has a standard unit of measure in the quantity class, then the quantity for the transfer must be an integer.
Supplier Pack Size	No	If included, this must be greater than zero. If not included, this will default to the primary supplier's pack size for the item at the from location, if an orderable item. If not orderable, this will default to 1.
Inventory Status	No	All items on a transfer must either be from available status or from unavailable status. A single transfer cannot mix available and unavailable statuses. Available inventory transfers should use a -1 or a null value in this field in the message. Unavailable inventory transfers should include a valid status from the Inventory Status Types configured in your environment.
Unit Cost	No	This is not used by Merchandising.
Adjustment Type	Conditional	This field, along with the adjustment value, is used to calculate the transfer price for intercompany transfers. It will be ignored for all other transfers. If the adjustment value is provided, then the type must also be specified. The valid values for this field are: IA - Increase by Amount IP - Increase by Percent DA - Decrease by Amount DP - Decrease by Percent S - Set Price IA and IP can only be used if you have your system options set to allow the transfer price to exceed weighted average cost.
Adjustment Value	Conditional	If the adjustment type is provided, then the value must also be specified. This must always be a positive amount.

Location Validation

The from and to locations passed into the message must be valid stores or warehouses in Merchandising; but they cannot be the same. If both locations are stores, then they must both exist in the same transfer zone. Additionally, if the to location is a store, then it must be open. This is determined based on whether there is a close date defined for the store and the stop order days.

If either location is a warehouse, then it can be either a physical warehouse or a virtual warehouse, depending on transfer type. A physical warehouse is only allowed as the from location type for an EG type of transfer. Additionally, only Book type transfers are allowed between two warehouses in the same physical warehouse.

If either the from or to location is a franchise store, then the other location cannot be a finisher. If the franchise store is a non-stockholding location, then the other location on the transfer must be a warehouse.

Validation is also done at the item level based on the locations on the transfer. Each item on the transfer must be in active, inactive, or discontinued status at the from location. It also must have been ranged to the from location in Merchandising, when that location is a warehouse. However, if the from location is a store, there is an exception where the transfer can still be created even though it is not yet ranged, which also bypasses inventory validation. This is to support a specific function in Oracle Retail Store Inventory Management (SIM). See the section on SIM Generated transfers below for more details.

If the item is not already ranged to the to location, then ranging will occur when the transfer is created, regardless of status. The ranging that occurs will flag the item/location as unintentionally ranged for all transfer types except AIP.

If the to location is an external finisher, see the section below on transfers with finishing.

Inventory Validation

Another part of the validation that is applicable for all transfers created is that inventory is available for transfer if the status passed through the integration is approve (A), with a few exceptions. First, EG type transfers do not have inventory validated as it is assumed that this type of transfer is generated in the store or warehouse and the inventory availability check has been done in that solution as part of the shipping of the inventory. Additionally, if the system option titled Validate External Warehouse Availability is set to No (unchecked), then warehouse inventory will not be validated for any transfers initiated in this API regardless of type. Store inventory availability is never validated by this API because of support for the process where the item does not need to be ranged to the shipping store.

Status Validation

Transfers can be created in a status of Input (I) or Approved (A) using this API. Transfers in input status are not subject to inventory validation, but all other validations are applicable. Book type transfers can only be created in Input status using this API, as there isn't really a concept of an "approved" book transfer - as soon as it is approved it is executed. Additionally, transfers of type Reallocation (RAC) and Return to Vendor (RV) can also only be created in Input status. Conversely, transfers of type AIP, SIM, and EG must always be created in Approved status. If any validation fails when processing the new transfer that results in it not being able to be approved, the transfer will be created but will remain in input status. The exception to this is for transfers of type AIP, SIM, and EG, as they must always be created in approved status. If they are not able to be approved, the transfer is not created or updated.

Transfer Type Specific Validation

Most of the validation defined above is relevant regardless of transfer type, except where noted. However, there are also some other validations done as part of this API's processing that are specific to a type of transfer.

Administration (AD)

See Manual Requisition

AIP Generated (AIP)

This type of transfer is expected only to be sent from AIP as an output of the replenishment process. As such, Merchandising assumes certain validations have been done by AIP in advance of receiving the transfer and slightly different validation is enforced. The following special validations apply for this transfer type using this API:

Must be created in Approved status
Can only be to stockholding locations
Supports transferring packs from stores
Allows the department number to be passed even when the system option is N
Item/location ranging to the to location will result in the Ranged flag being set to Yes as it is assumed this an intentional ranging.
Can be an intercompany transfer

Book (BT)

Book transfers processed through this API can be created for two virtual warehouses in the same physical warehouse only. This is usually used for inventory rebalancing between virtual locations. The following special validations apply for this transfer type using this API:

Can only be created in Input status
Can only be created for virtual warehouses in the same physical warehouse
Warehouses must be in the same legal entity

Confirmation (CF)

See Manual Requisition

Externally Generated (EG)

Externally Generated transfers are assumed to be created in the store or warehouse. Further, it is assumed that once they get to Merchandising, the transfer is already in process at that location. As such, there are certain validations that are managed differently for this transfer type in this API:

Must be created in Approved status
Supports transferring packs from stores
Allows the department number to be passed even when the system option is N
Can be an intercompany transfer
Uses the physical warehouse number, not a virtual warehouse number, if warehouses are involved

Intercompany (IC)

An intercompany transfer is a type of business to business transaction that sells product from one legal entity and purchases it into another. Legal entities in Merchandising are determined based on the setting of the Intercompany Basis system option, which indicates whether the transfer entity or the set of books of a location should be used. This transfer type is used when either it is explicitly passed into the API or if the transfer type is NULL in the inbound message and the locations are in different legal entities. Other transfer types may also be intercompany, as well, but the below rules apply for those flagged as intercompany type explicitly:

The legal entity of the from and to locations must be different.
If an adjustment type or value is passed into the message, that will be used to calculate the "selling" price between entities. Otherwise, the from location's weighted average cost is used.

Manual Requisition (MR)

This is the most basic type of transfer in Merchandising, so it is used as a default transfer type when either it is explicitly passed into the API or if the transfer type is NULL in the inbound message and the locations are in the same legal entity. The behavior for this transfer type is the same as that for AD and CF types of transfers - those could be used as different reasons for a transfer. For this transfer type the following validation rules are enforced:

Locations must be in the same legal entity

Reallocation (RAC)

A reallocation transfer is assumed to be used to pull back inventory from stores or warehouses to a single warehouse for re-allocation to other stores or other warehouses. This is the type of transfer that is created when a mass-return transfer is created, for example. Because it has unique rules tied to it related to MRTs, some additional validations are followed:

Can only be created in Input status in this API
Locations must be in the same legal entity

Return to Vendor (RV)

A return to vendor type of transfer is similar to a reallocation type, in that it is assumed to be pulling inventory back to a warehouse from stores or other warehouses, but in this case, for the purpose of returning the merchandise to the supplier. This is the type of transfer that is created when a mass-return transfer is created, for example. Because it has some unique rules tied to it related to MRTs, some additional validations are followed:

Can only be created in Input status in this API
Locations must be in the same legal entity

SIM Generated (SIM)

SIM generated transfers are created only by the store orders process in SIM. This functionality is not available in SIOCS. Because of this, they have special rules applied, including the ability to create the transfer even though no item/store relationship exists for the originating location in Merchandising. The rules that apply for this type of transfer include:

Must be created in Approved status
Supports transferring packs from stores
Allows the department number to be passed even when the Merchandising system option is No
Can be an intercompany transfer

All Transfer Types

For all of the above transfer types, if all validation described above passes, then the transfer will be created. If the transfer is created in Approved status, then in addition to the transfer itself, other details may also be created based on the items and locations involved.

Inventory will be updated to reflect the reserved quantity at the from location and expected quantity at the to location.
Upcharges will be applied, if configured, for transfers that do not include a physical warehouse location. For transfers with a physical warehouse, the records for upcharges are added when the transfer is shipped.
An associated franchise order or return will be created if the transfer involves a franchise location.

Transfers with Finishing

Transfers with finishing are sometimes referred to as a two-legged transfer, as they generate two transfers in Merchandising. One from the originating store or warehouse to the finisher and one from the finisher back to a store or warehouse. This API supports the creation of a transfer with finishing only through an external finisher, a type of partner, and back to the originating location. Transfers to an internal finisher are not supported via this integration. To do this, when sending the transfer details in the message, you will indicate the external finisher as the "to" location. Then when the transfer is created, it will automatically generate the second leg.

When creating transfers in this way, it does not generate any work order activities to send to the finisher with the transfer - these will either need to be added manually in the Merchandising screens, or sent separately to the finisher.

Updating Transfers

For updates, the transfer number included in the message must already exist in Merchandising. Changes can be sent for header level updates or detail level updates. If the changes are at the header level, then the all the required header level information need to be included in the update, similar to that described above for creating a new transfer. However, the transfer details should not be included in a header level update. Fields that can be updated at the header level using this API include:

Delivery Date - must always be a date today or later.
Routing Code - if the freight code is updated to expedite (E), then this must also have a value. If freight code is updated to something other than expedite, then this should be null.
Freight Code
Status - to move from Input or Submitted to Approved only. Transfers cannot be moved back to Input status using this API.
Comments
Context Type
Context Value

If the update is at the detail level - to add or update a line item - only the transfer number is required in the header record, the other details are ignored. If not included, then the message will be rejected. Adding a new item to the transfer will use similar validation to that described above when creating the transfer.

If modifying an existing transfer line item, the full transfer quantity should be sent with the update, not the difference from the original quantity. This will be compared to the previous transfer quantity to determine how to update the transfer. For example, if the transfer is in approved or submitted status, a reduction in quantity would update the cancelled quantity on the transfer. It will also be validated to ensure that the quantity change doesn't result in the total transfer quantity being lower than what has already been shipped or what is expected to be picked based on updates to the selected or distro quantities on the transfer. For increases in transfer quantity, if the transfer is in submitted or approved status, then inventory will be validated based on the changed quantity (depending on system option settings) to validate that the additional units are available. The inventory status for the item cannot be modified.

Deleting Transfers

If you are deleting a line item on the transfer or deleting the whole transfer, then the API will validate that the transfer number is valid and that the transfer or transfer line was not already shipped or received, at least partially, or is not in process at the shipping warehouse or store. If you are deleting the whole transfer, then no details should be included in the message. If you are deleting a line on the transfer, then validation will be done to ensure that the item exists on the transfer.

Transfers are not actually deleted via this API, rather they are updated to a deleted status and a secondary process does the actual removal. Transfers can be deleted in any status, other than those already in a closed or deleted status, using this API. If the transfer involved an external finisher, then both legs on the transfer will be marked for delete. Deleting the last line on the transfer will also result in the transfer being flagged for delete.

If the transfer is in a status other than input, moving it to a deleted status or deleting a line will also update inventory to release the reserved inventory at the from location and decrease expected quantity at the to location. As well, if the transfer involves any franchise stores, then any franchise order or return created with the transfer will also be cancelled.

Table 3-115 Transfer Header Delete

Message Element	Required?	Notes
Transfer Number	Always	Must be an existing transfer in Merchandising.
Transfer Detail	Optional	Child node.

Table 3-116 Transfer Detail Delete

Message Element	Required?	Notes
Item	Always	Must be an item on an existing transfer in Merchandising.

Publishing Updates

Because these transfers that can be created, updated, or deleted using this API are managed in an external system, there are some cases where it is not published back out by Merchandising after it is processed to avoid the source system from receiving unneeded updates. This applies for transfers of type EG only. All other transfers will be published back to the RIB if approved or previously approved, such that the store and warehouse solutions responsible for executing the transfers are notified.

Flex Attributes

If you have defined any custom flex attributes (CFAS) for transfers, then they can be integrated as part of this API. The node of the integration that supports this will accept the name of the attribute as it is defined in the group set level view and the value for the attribute. Flex attributes can only be added or updated to a transfer, they cannot be deleted. Additionally, for transfers with finishing, flex attributes can only be added to the first leg of the transfer.

Table 3-117 Flex Attributes

Message Element	Required?	Notes
Name	Yes	Holds the attribute name.
Value	No	Holds the value of the attribute for number and character type attributes
Value Date	No	Holds the date for date type attributes.

Error Handling

Message XSD

Below are the filenames that correspond with each message type. Please consult the Oracle Retail Integration Guide for each message type for the details on the composition of each message.

Message Types	Message Type Description	XML Schema Definition (XSD)
Xtsfcre	Transfer Create	XTsfDesc.xsd
Xtsfdtlcre	Transfer Detail Create	XTsfDesc.xsd
CustFlexAttriVO	Transfer Flex Attribute Create	XTsfDesc.xsd
Xtsfmod	Transfer Modify	XTsfDesc.xsd
Xtsfdtlmod	Transfer Detail Modify	XTsfDesc.xsd
Xtsfdtlmod	Transfer Flex Attribute Modify	XTsfDesc.xsd
Xtsfdel	Transfer Delete	XTsfDesc.xsd
Xtsfdtldel	Transfer Detail Delete	XTsfRef.xsd

Vendor Subscription API

This section describes the vendor subscription API.

Functional Area

Foundation Data

Business Overview

Merchandising subscribes to vendor information that is published from an external financial application; however, this API is not used by Oracle Retail Financial Integration (RFI). Vendor can refer to either a partner or a supplier. Any partners loaded in this API must be created in Merchandising manually using the same ID as is sent in this API, to facilitate integration back to financials. Supplier information subscribed to by this API includes supplier addresses, org unit, and any flex attributes defined at the supplier or address levels.

Vendor Create and Update

When new suppliers or supplier sites are sent from an external system, they must contain the required header details, as well as address and org unit information. If the supplier information sent is for an ID that does not already exist, then this API will create a new supplier or site. If the ID already exists, then this API will update the existing supplier or site. For supplier sites, all addresses are expected to be the same, regardless of type. If a mandatory address type is not included in the message, it will be defaulted based on the provided address. One or more org units can be associated with a supplier site using this API, if applicable.

Table 3-118 Vendor Create and Update

Message Element	Required?	Notes
Vendor Header	Always	Child node
Vendor Address	Optional	Child node
Vendor Org Unit	Optional	Child node

Table 3-119 Vendor Header Create and Update

Message Element	Required?	Notes
Supplier	Always	Unique identifying number for a supplier site within the system.
Supplier Name	Always	This field contains the supplier site name.
Supplier Name Secondary	Optional	This type can hold secondary name for the supplier site with a max length of 240 characters.
Contact Name	Always	This field contains the name of the supplier representative contact for this site.
Contact Phone	Always	This field contains a telephone number for the supplier's representative contact.
Contact Fax	Optional	This field contains a fax number for the supplier's representative contact.
Contact Pager	Optional	This field contains a pager number for the supplier's representative contact.
Supplier Status	Always	This field contains the status of the supplier site. Valid values are: A - Active I - Inactive
QC Ind	Always	This field determines whether orders from this supplier will require quality control.
QC Percentage	Optional	This field contains the percentage of items per receipt that will be marked for quality checking.
QC Frequency	Optional	This field contains the frequency for which items per receipt will be marked for quality checking.
VC Ind	Always	This field determines whether orders from this supplier will require vendor control.
VC Percentage	Optional	This field contains percentage of items per receipt that will be marked for vendor checking.
VC Frequency	Optional	This field contains the frequency for which items per receipt that will be marked for vendor checking.
Currency Code	Always	This field contains code identifying the currency the supplier site uses for business transactions.
Language	Optional	This field contains the supplier’s preferred language.
Terms	Always	This field contains an indicator identifying the purchase terms that will default when an order is created for the supplier site. These terms specify when payment is due and if any discounts exist for early payment.
Freight Terms	Always	This field contains code indicating what freight terms will default when an order is created for the supplier site.
Return Allow Indicator	Always	This field indicates whether the supplier site will accept returns. Valid values are Yes (Y) or No (N).
Return Authorization Required	Always	This field indicates if returns must be accompanied by an authorization number when sent back to the vendor.
Returns Minimum Amount	Optional	This field contains a value if the supplier site requires a minimum merchandise value to be returned to accept the return. Returns of less than this amount will not be processed by the system. This field is stored in the supplier's currency.
Return Courier	Optional	This field contains the name of the courier that should be used for returns to the supplier site.
Handling Percentage	Optional	This field contains the default percent to be multiplied by the return’s total cost to determine the handling cost for the return.
EDI PO Ind	Always	This field indicates whether purchase orders will be sent to the supplier via EDI.
EDI PO Change	Always	This field indicates whether purchase order changes will be sent to the supplier via EDI.
EDI PO Confirmation	Always	This field indicates whether acknowledgements of purchase orders will be sent from the supplier via EDI.
EDI ASN	Always	This field indicates whether the supplier will send Advance Shipment Notifications electronically.
EDI Sales Report Frequency	Optional	This field contains the EDI sales report frequency for the supplier. Valid values are weekly (W) or daily (D).
EDI Supplier Availability Indicator	Always	This field indicates whether the supplier will send availability via EDI.
EDI Contract Indicator	Always	This field indicates whether the supplier site supports contract ordering sent via EDI.
EDI Invoice Indicator	Always	This field indicates whether invoices, debit memos, and credit note requests will be sent to/from the supplier via EDI.
Cost Change Percentage Variance	Optional	This field contains a percent that determines whether a cost change can be auto approve via induction. If the cost change falls within these boundaries, it will be approved when uploaded.
Cost Change Amount Variance	Optional	This field contains an amount (in supplier currency) that determines whether a cost change can be auto approve via induction. If the cost change falls within these boundaries, it will be approved when uploaded.
Replenishment Approval Indicator	Always	This field indicates whether contract orders created via replenishment should be created in Approved status.
Ship Method	Optional	This field contains the default method used to ship the items on the purchase order from the supplier site. Valid values are held in code type SHPM.
Payment Method	Optional	This field indicates the default method for how purchase orders for this site will be paid. Valid options are: LC - Letter of Credit WT - Wire Transfer OA - Open Account
Contact Telex	Optional	This field contains a telex number for the supplier's representative contact.
Contact Email	Optional	This field contains an email address for the supplier's representative contact.
Settlement Code	Always	This field indicates which payment process method is used for the supplier. Valid values are N/A (N) or Evaluated Receipts Settlement (E).
Pre-Mark Indicator	Always	This field indicates whether the supplier site supports pre-marking containers for cross dock orders.
Auto Approved Invoice Indicator	Always	This field indicates whether the supplier's invoices can be automatically approved for payment.
Debit Memo Code	Optional	This field indicates when a debit memo will be sent to the supplier site to resolve a discrepancy. Valid values are: Y - if debit memos are always to be sent L - if debit memos are used only if a credit note is not sent by the invoice due date N - if debit memos are never sent
Freight Charge Indicator	Always	This field indicates whether a supplier site can charge freight costs.
Auto Approve Debit Memo Indicator	Always	This field indicates whether debit memos sent to the supplier site can be automatically approved on creation.
Inventory Management Level	Optional	This field indicates the level for managing supplier inventory information. Valid values are supplier (S), supplier/location (L), supplier/department (D), or supplier/department/location (A). If no value is provided, then if the department level orders system option is set to Yes, then this is defaulted to supplier/department, otherwise it is defaulted to supplier.
Backorder Indicator	Always	This field indicates if backorders or partial shipments will be accepted.
VAT Region	Optional	This field contains the unique identifying number for the VAT region applicable for this site.
Prepay Invoice Indicator	Always	This field indicates whether all invoices for the supplier can be pre-paid.
Service Performed Required Indicator	Always	This field indicates if the supplier's services must be confirmed as performed before paying an invoice from that supplier site.
Invoice Payment Location	Optional	This field indicates where invoices from this supplier site are paid - at the store (S) or centrally through corporate accounting (C).
Invoice Received Location	Optional	This field indicates where invoices from this supplier site are received - at the store (S) or centrally through corporate accounting (C).
Invoice At	Optional	This field indicates if the supplier site invoice lists items at gross cost (G) or net cost (N).
Delivery Policy	Always	This field contains the default delivery policy of the supplier site. Valid values come from the DLVY code type.
Comments	Optional	This field contains any miscellaneous comments associated with the supplier.
Default Item Lead Time	Optional	This field holds the default lead time for the supplier site. The lead time is the time the supplier needs between receiving an order and having the order ready to ship. This value will be defaulted to item/supplier relationships.
DUNS Number	Optional	The Dun and Bradstreet number of the supplier.
DUNS Location	Optional	The Dun and Bradstreet number of the location of the supplier.
Bracket Costing Indicator	Always	This field will determine if the supplier site supports bracket costing pricing structures.
VMI Order Status	Optional	This field determines the status in which any inbound POs from this supplier will be created. A NULL value indicates that the supplier is not a VMI supplier.
End Active Date	Optional	Not used by Merchandising.
DSD Supplier Indicator	Always	This field specifies whether the vendor supports DSD ordering, where the supplier replenishes the store directly, creating the PO and receipt at the same time.
Supplier Quantity Level	Always	This field indicates the supplier site order quantity level. Valid values are cases (CA) or eaches (EA).
Supplier Parent	Optional	This is the supplier number for the supplier sites.
Store Delivery Discrepancy	Optional	Not used by Merchandising
Final Destination Indicator	Always	This field indicates whether the supplier site can ship to final destination or not. Valid values are Yes (Y) or No (N).
External Reference Indicator	Optional	This column holds the ID for the supplier used in the external financial system.
Deal Upload Status	No	This field indicates the status in which the deal will be created when uploaded. The valid values are: W - Worksheet S - Submitted A - Approved
Tax ID	No	This field contains the unique tax identification number of the supplier site.
Custom Flex Attributes	Optional	Child Node

Table 3-120 Vendor Address Create or Update

Message Element	Required?	Notes
Module	Always	This field indicates the data type that the address is attached to. In this case, it will always be 'SUPP'.
Key Value 1	Always	This field holds the ID the address is attached to. In this case, it will be the supplier number.
Key Value 2	Optional	This is not used.
Sequence Number	Always	Number indicating the sequence that addresses within the same type were entered.
Address Type	Always	This field contains the address type. Valid address types are: Business (01) Postal (02) Returns (03) Order (04) Invoice (05) Remittance (06) If any address types have been flagged as mandatory and are not included when the supplier is being created, then if an ordering address has been included, the missing mandatory addresses will be defaulted to that address. If not, then the remittance address will be used. If neither an order nor remittance address is included, then the first address sent is used.
Primary Address Indicator	Always	This field indicates whether the address is the primary address for the address type.
Address 1	Always	This field contains the first line of the address.
Address 2	Optional	This field contains the second line of the address.
Address 3	Optional	This field contains the third line of the address.
City	Always	This field contains the name of the city that is associated with the address.
State	Optional	This field contains the state abbreviation for the address.
Country ID	Always	This field contains the country where the address exists.
Jurisdiction Code	Optional	This field contains the ID associated to the tax jurisdiction of the country-state relationship.
Post	Optional	This field contains the zip code for the address.
Contact Name	Optional	This field contains the name of the contact for the supplier at this address.
Contact Phone	Optional	This field contains the phone number of the contact person at this address.
Contact Telex	Optional	This field contains the telex number of the contact person at this address.
Contact Fax	Optional	This field contains the fax number of the contact person at this address.
Contact Email	Optional	This field contains the email address of the supplier site's contact person.
Custom Flex Attributes	Optional	Child Node

Table 3-121 Vendor Org Unit Create

Message Element	Required?	Notes
Org Unit ID	Always	This field contains org unit ID added or updated for the supplier site.
Primary Pay Site Indicator	Always	This field contains the primary pay site indicator.

Flex Attributes

If custom flex attributes (CFAS) have been defined for suppliers or addresses, then they can be integrated as part of this API. The node of the integration that supports this will accept the name of the attribute as it is defined in the group set level view and the value for the attribute. Flex attributes can only be added to or updated for a supplier and supplier address but cannot be deleted.

Message Element	Required?	Notes
Name	Always	Holds the name of the attribute.
Value	Optional	Holds the value of the attribute for non-date attributes.
Value Date	Optional	Holds the value of the attribute for date attributes.

Error Handling

Message XSD

Below are the filenames that correspond with each message type. Please consult the Oracle Retail Integration Guide for each message type for the details on the composition of each message.

Message Types	Message Type Description	XML Schema Definition (XSD)
vendorcre	Vendor Create	VendorDesc.xsd

Work Order Status Subscription API

This section describes the work order status subscription API.

Functional Area

Transfers

Business Overview

For transfers with finishing, Merchandising subscribes to work order status messages sent from internal finishers indicating that the work order activities are complete. This message is used for internal finishers located in the same physical warehouse as the final destination for the transfer, as there is no physical shipment of goods. Other finishing scenarios exist in which the finisher is not a virtual warehouse that shares a physical warehouse with the transfer's final receiving location. In these instances, Work Order Status messages are not necessary, and Merchandising will disregard Work Order Status messages sent in these scenarios.

Work order status messages contain the items for which the activities have been completed, along with the quantity that was completed. All items on transfers that pass through an internal finisher must have at least one work order activity associated with them. When work order status messages are received for a particular item/quantity, it is assumed that all activities on the work order associated with the item/quantity have been completed. If work order activities involve item transformation or repacking, the work order status messages are always created in terms of the resultant item or pack.

On processing the work order status update, a book transfer is executed between the internal finisher (which is held as a virtual warehouse) and the final receiving location (also a virtual warehouse). If the internal finisher belongs to the sending location's transfer entity, intercompany out and intercompany in transactions are recorded. Quantities on hand, reserved quantities, and weighted average costs are adjusted to accurately reflect the status of the stock.

It is possible to receive multiple Work Order Status messages for a particular item/transfer. Work order completion of partial quantities addresses the following scenarios:

Work order activities could not be performed for the entire quantity of a particular item at one time.
A given quantity of the particular item was damaged while work order activities were performed.

Work Order Example

Assume that a quantity of 20 of item 100 (White XL T-shirt) are sent to an internal finisher at the receiving physical warehouse, where they will be dyed black, thereby transforming them into item 101 (Black XL T-shirt). If all finishing activities were successfully completed in this example, Merchandising could expect to receive a Work Order Status message containing item 101 with a quantity of 20.

Work Order Status Creation

While consuming the Work Order Status message, Merchandising validates that the finisher and the transfer's final receiving location are in the same physical warehouse. If not, processing is halted. If the message contains an item, work order complete processing will be called for that item. Otherwise, said processing will be called for all items on the transfer. If the entire transfer is processed, the child transfer (that is, the second leg) will be set to Shipped status. Note that work orders are always associated with the second leg of multi-leg transfers. Whether processing is performed at the item or transfer level, transfer closing logic will be used to determine if the entire multi-leg transfer can be closed.

Table 3-122 Work Order Status

Message Element	Required?	Notes
Work Order ID	Yes	This field contains the work order number under which the finishing activities were performed.
Distro Number	Yes	This field contains the transfer number containing the work order. This is the 2nd leg transfer number.
Distro Doc Type	Yes	This should always be transfer (T).
Distro Parent Number	No	This is the first leg transfer number. If this field must be the same as the tsf_parent_no of the distro number in the tsfhead table in Merchandising.
Distro Parent Type	No	Not used
Item	Conditional	This contains the item on which the work order has been completed. If an item transformation occurred, this should be the resultant item. If the completed quantity field has a value, then this field is required.
Warehouse	Yes	Not used, but required as input
Location Type	Yes	This field contains the destination location type where the finished goods are sent. Not used, but required as input
Location	Yes	This field contains the destination location where the finished goods are sent. This is the final location of the 2-legged transfer.
Sequence Number	Yes	Not used, but required as input
Work In Process Code	Yes	Not used, but required as input
Instructions	Yes	Not used, but required as input
Complete Date	Yes	This field contains the date when the work order was completed.
Completed Quantity	Conditional	This contains the number of items that resulted from the work order activity. If the item field has a value, then this field is required.
Completed Indicator	Yes	Not used
Work Order Status Inventory Adjustment	No	Child node Not used

Table 3-123 Work Order Status Inventory Adjustment

Message Element	Required?	Notes
From Disposition	No	Not used
To Disposition	No	Not used
Unit Quantity	No	Not used

Error Handling

Message XSD

Here are the filenames that correspond with each message type. Please consult RIB documentation for each message type in order to get a detailed picture of the composition of each message.

Message Types	Message Type Description	XML Schema Definition (XSD)
wostatuscre	Work Order Status Create Message	WOStatusDesc.xsd