Cost

The following services are included in this functional area:

• Average Cost

  • Average Cost Upload Service

    • Update Average Cost

• Cost Changes

  • Cost Change Upload Service

    • Create Cost Change Effective Immediately

    • Manage Cost Changes

• Pricing Cost

  • Pricing Cost Download Service

    • Get Pricing Cost

Average Cost

The following services are included in this functional area:

• Average Cost Upload Service

  • Update Average Cost

Average Cost Upload Service

The following services are included in this functional area:

• Update Average Cost

Update Average Cost

Functional Area

Cost - Average Cost

Business Overview

This service can be used to update the weighted average cost (WAC) from an external system for one or more item/location combinations. It also creates a transaction data record posting with transaction code 70 for the difference in cost, based on the owned inventory at the location at the time the cost change is applied.

The web service can be called with the following details:

• Item

• Location

• Location type

• New average cost (must be greater than 0)

Service Type

PUT

ReST URL

MerchIntegrations/services/cost/averageCost/update

Availability During Nightly Batch Cycle

This service will not be available when batches that affect inventory are in-progress.

Input Payload Details

Table 5-18 Update - Object. See list of elements for detail

Element Name	Required	Data Type	Description
items	No	Collection of Object	Collection of items and locations for which weight average cost needs to be updated.

Table 5-19 Items - Object. See list of elements for detail

Element Name	Required	Data Type	Description
item	Yes	String (25)	Contains the item number for which the average cost has to be updated
location	Yes	Number (10)	Store or virtual warehouse location number.
locationType	Yes	String (1)	Location Type. Valid values are 'S' (store) and 'W' (warehouse).
averageCost	Yes	Number (20,4)	New average cost.

Sample Input Message

{
  "items": [
    {
      "item": "101450060",
      "location": 6000,
      "locationType": "S",
      "averageCost": 19.50
    }
  ]
}

Response Code: 200 (Success)

Sample Response Message

{
  "status": "SUCCESS",
  "message": "Service call is successful"
}

Response Code: 400 (Error)

In case of error, the following standard error response will be returned. The element "validationErrors" will be present when input payload or input parameters are not as per the schema definition of this service. The element "businessError" will be present if the payload passes schema validation but exception is caught while processing business logic.

Sample Error Message

{
  "status": "ERROR",
  "message": "Error found in validation of input payload",
  "validationErrors": [
    {
      "error": "must be one of Y, N",
      "field": "createRecord.arg0.approveInd",
      "inputValue": "X"
    }
  ],
  "businessError": [
    "Error message"
  ]
}

Cost Changes

The following services are included in this functional area:

• Cost Change Upload Service

  • Create Cost Change Effective Immediately

  • Manage Cost Changes

Cost Change Upload Service

The following services are included in this functional area:

• Create Cost Change Effective Immediately

• Manage Cost Changes

Create Cost Change Effective Immediately

Functional Area

Cost - Cost Changes

Business Overview

This service allows external systems to update unit costs within Merchandising. All cost changes that are sent through this service are executed immediately. This service 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/location relationships in Merchandising. Cost changes can be performed at the item level, or at the following levels of the organization hierarchy - chain, area, region, district or store. Unit costs are updated for all stores within the location group. Warehouses are only impacted by cost changes applied at the warehouse level, since they are not part of the organization hierarchy. Since the user has the flexibility to have child items with the same or different purchase type compared to the parent item, any cost change created at the parent item level will impact only those child items having the same ownership as the parent. Cost changes can be created for individual child items as well.

The service takes in a collection of cost changes and will return success and failure through the service response object. This service validates that all the required fields are provided and also checks the supplier's currency and the item status. In case differentiator IDs are passed in the message, it verifies that they are valid for the provided item. The service 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 service performs the following actions:

• Creates a cost change event in the ‘Executed’ status, with the current date set as the effective date.

• Updates the unit cost in Merchandising for all item/supplier/country and item/supplier/country/locations based on the information provided.

• Creates price history records for all item/locations that get updated as part of the cost change.

• If the recalculate order indicator is set to Yes, it updates all relevant order/item/locations unit cost in Merchandising.

It is important to note that cost changes sent through this service 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.

Service Type

POST

ReST URL

MerchIntegrations/services/cost/costChange/immediate/create

Availability During Nightly Batch Cycle

This service will not be available during total duration of nightly batch run cycle.

Input Payload Details

Table 5-20 Create - Object. See list of elements for detail

Element Name	Required	Data Type	Description
items	Yes	Collection of Object	It's a referenced element. For detailed description, please refer referenced element doc.

Table 5-21 Items - Object. See list of elements for detail

Element Name	Required	Data Type	Description
item	Yes	String (25)	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	Number (10)	The ID of the supplier that sources the items the cost change affects. This value must be predefined on the SUPS table. This can be a primary or non-primary supplier.
originCountry	Yes	String (3)	The identifier of the origin country of the item supplier to which the cost change will apply. This value must be predefined on the COUNTRIES table. This can be the primary or a non-primary country.
diffId	No	String (10)	The identifier for a differentiator. This can be used with a parent or grandparent item. The cost change will explode to all the parent's transaction level items with the differentiator. This value must be predefined on the DIFF_IDS table.
unitCost	Yes	Number (20,4)	The new unit cost of the item in the currency specified on the message. Tables item_supp_country_loc, item_loc_soh, and ordloc will also be updated with this value, depending on the values in tags hier_level and hier_value.
recalculateOrderInd	Yes	String (1)	This field will indicate if orders in approved status for items on the cost change will be recalculated with the new cost. Valid values will be Y (yes) and N (no).
currencyCode	Yes	String (3)	The currency code of the unit cost. This value must be predefined on the currencies table and must be the currency of the supplier.
hierarchyLevel	No	String (2)	The hierarchy level of the hierarchy value. This field will indicate 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).
details	No	Collection of Object	References a collection of hierarchy details
customFlexAttribute	No	Collection of Object	References a collection of customer flexible attributes.
purchaseRate	No	Number (12,4)	This column contains the percentage of the retail price which will determine the cost paid to the supplier for a consignment or concession item.

Table 5-22 Details - Object. See list of elements for detail

Element Name	Required	Data Type	Description
hierarchyValue	Yes	Number (10)	The ID of the specified hierarchy level which encompasses the locations affected by the cost change.

Table 5-23 CustomFlexAttribute - Object. See list of elements for detail

Element Name	Required	Data Type	Description
name	Yes	String (30)	Holds the attribute name.
value	No	String (250)	Holds the numeric or string value of the attribute.
valueDate	No	date	Holds the date value of the attribute.

Sample Input Message

{
  "items": [
    {
      "item": "100900006",
      "supplier": 2400,
      "originCountry": "US",
      "diffId": "String",
      "unitCost": 9.65,
      "recalculateOrderInd": "N",
      "currencyCode": "USD",
      "hierarchyLevel": "S",
      "details": [
        {
          "hierarchyValue": 1521
        }
      ],
      "customFlexAttribute": [
        {
          "name": "REVIEW_DATE",
          "value": null,
          "valueDate": "2001-12-31"
        }
      ],
      "purchaseRate": 18.00
    }
  ]
}

Response Code: 200 (Success)

Sample Response Message

{
  "status": "SUCCESS",
  "message": "Service call is successful"
}

Response Code: 400 (Error)

In case of error, the following standard error response will be returned. The element "validationErrors" will be present when input payload or input parameters are not as per the schema definition of this service. The element "businessError" will be present if the payload passes schema validation but exception is caught while processing business logic.

Sample Error Message

{
  "status": "ERROR",
  "message": "Error found in validation of input payload",
  "validationErrors": [
    {
      "error": "must be one of Y, N",
      "field": "createRecord.arg0.approveInd",
      "inputValue": "X"
    }
  ],
  "businessError": [
    "Error message"
  ]
}

Manage Cost Changes

Functional Area

Cost – Cost Change

Business Overview

This service is used by an external source, usually a supplier, to create and maintain future-dated cost changes in Merchandising. The service accepts a collection of cost changes and returns success or failure through the service response object. This service uses the cost change induction staging tables, populates those tables, then invokes the existing cost change induction API that validates the data and populates the base tables. 

Service Type

Post

ReST URL

RmsRestServices/services/private/costChange

Input Parameters – Cost Change Header Record

Parameter Name	Required (For Create)	Required (For Update)	Required (For Delete)	Data Type	Description
action	No	No	No	string	Action type for Cost Change. Valid values are NEW(for create), MOD (for update) or DEL (for delete)
costChange	Yes	Yes	Yes	number	Holds the ID that uniquely identifies the cost change. The ID should not overlap with cost changes created through other modes such as induction or the Merchandising UI.
costChangeDesc	Yes	Yes	No	string	Cost change description. This along with the cost change number identifies the cost change for modification and deletion.
reason	Yes	Yes	No	string	Indicates the reason code for the cost change. Valid values for this input can be found in the COST_CHG_REASON table.
activeDate	Yes	Yes	No	date	Indicates the date on which the cost change will become active. The date format should be YYYY-MM-DD
status	Yes	Yes	No	string	Contains the status of the cost change. Valid values are W = Worksheet, D = Deleted (to be deleted), C = Canceled, A = Approved, E = Extracted, R = Rejected, S = Submitted
costChangeOrigin	Yes	Yes	No	string	Contains a code that identifies the origin of the cost change. This code is used to determine whether the event was created by supplier or by SKU. Cost events with a supplier origin will have multiple detail records all having the same supplier. Cost events with a SKU origin will have multiple detail records that may have multiple SKUs and multiple suppliers. Valid Values are SUP - By Supplier, SKU - By SKU
approvalId	No	No	No	string	Contains the user ID who last approved the cost change.
suppItemDetails					Child Node – cost change detail record. Either this node is populated or the detail location node.
suppItemLocDetails					Child Node – cost change detail location record. Either this node or the detail node is populated.
customFlexAttribute					Child Node – custom flex attributes

Input Parameters – Cost Change Detail Record

Parameter Name	Required (For Create)	Required (For Update)	Required (For Delete)	Data Type	Description
action	No	No	No	string	Holds action type. Valid values are NEW (for create), MOD (for update) or DEL (for delete)
supplier	Yes	Yes	Yes	number	Contains the number that identifies the supplier associated with the cost change.
originCountryId	Yes	Yes	Yes	string	The country where the item was manufactured or significantly altered.
item	Yes	Yes	Yes	string	Unique alphanumeric value that identifies the item.
bracketValue1	No	Yes	Yes	number	The values are the various levels in the vendor price list whereby costing of the items will be affected as the levels are achieved on the purchase orders.
costChangeType	Yes	Yes	No	number	Describes the type of cost change. Valid values are A - Amount, F - Fixed or P - Percentage.
costChangeValue	Yes	Yes	No	number	Holds the value of cost change
recalcOrdInd	No	Yes	No	string	This field indicates whether or not approved order costs should be re-calculated when a supplier cost has changed. Default value for this input is No. Valid values are Y - Yes, N - No
defaultBracketInd	No	No	No	string	This field contains the value that will control which cost is the base cost for processing throughout the system. Each bracket group (either by supplier, supplier/department, supplier/department/location, supplier/location) must have one bracket defined as the default bracket.
calculationBasis	No	No	No	string	This indicates whether 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.
purchaseRate	No	No	No	number	This column contains the percentage of the retail price which will determine the cost paid to the supplier for a consignment or concession item.

Input Parameters – Cost Change Detail Location Record

Parameter Name	Required (For Create)	Required (For Update)	Required (For Delete)	Data Type	Description
action	No	No	No	string	Holds action type. Valid values are NEW (for create), MOD (for update) or DEL (for delete)
supplier	Yes	Yes	Yes	number	Contains the number that identifies the supplier associated with the cost change.
originCountryId	Yes	Yes	Yes	string	The country where the item was manufactured or significantly altered.
item	Yes	Yes	Yes	string	Unique alphanumeric value that identifies the item.
locType	Yes	Yes	Yes	string	Contains the type of the location. Valid values are Store and Warehouse.
loc	Yes	Yes	Yes	number	Number of the location the cost change will occur at. This can represent a store or a warehouse. Cost changes will be managed and stored at the physical warehouse level since the unit cost must remain consistent across all virtual warehouses within the same physical warehouse. The sccext batch program will handle exploding the cost change down to all virtual warehouses for the inputted physical warehouse.
bracketValue1	No	No	No	number	The values are the various levels in the vendors price list whereby costing of the items will be affected as the levels are achieved on purchase orders.
costChangeType	Yes	Yes	No	string	Describes the type of cost change
costChangeValue	Yes	Yes	No	number	Holds the value of the cost change
recalcOrdInd	No	Yes	No	string	This field indicates whether or not approved order costs should be re-calculated when a supplier cost has changed. Default value for this input is No. Valid values are Y - Yes, N - No
defaultBracketInd	No	No	No	string	This field contains the value that will control which cost is the base cost for processing throughout the system. Each bracket group (either by supplier, supplier/department, supplier/department/location, supplier/location) must have one bracket defined as the default bracket.
calculationBasis	No	No	No	string	The ID of the user who last updated this record.
purchaseRate	No	No	No	number	The date and time when this record was last updated.

Input Parameters – Custom Flex Attribute Record

Parameter Name	Required (For Create)	Required (For Update)	Required (For Delete)	Data Type	Description
action	No	No	NA	string	Holds action type. Valid values are NEW (for create), MOD (for update) or DEL (for delete)
cfaName	Yes	Yes	NA	string
cfaValue	No	No	NA	string
cfaValueDate	No	No	NA	date

Example JSON input:

[
  {
    "action": "NEW",
    "costChange": 123412,
    "costChangeDesc": "Sample Cost Change",
    "reason": 6,
    "activeDate": "2022-04-18",
    "status": "A",
    "costChangeOrigin": "SKU",
    "approvalId": "SomeUser",
    "suppItemDetails": [
      {
        "action": "NEW",
        "supplier": 60000,
        "originCountryId": "US",
        "item": "123412312",
        "bracketValue1": 0,
        "costChangeType": "F",
        "costChangeValue": 19,
        "recalcOrdInd": "N",
        "defaultBracketInd": "",
        "calculationBasis": "C",
        "purchaseRate": 0
      }
    ],
    "suppItemLocDetails": [
      {
        "action": "NEW",
        "supplier": 30201,
        "originCountryId": "US",
        "item": "103500024",
        "locType": "S",
        "loc": 1521,
        "bracketValue1": 0,
        "costChangeType": "F",
        "costChangeValue": 19,
        "recalcOrdInd": "N",
        "defaultBracketInd": "",
        "calculationBasis": "",
        "purchaseRate": null
      }
    ],
    "customFlexAttribute": [
      {
        "action": "NEW",
        "cfaName": "string",
        "cfaValue": "string",
        "cfaValueDate": "2022-04-18"
      }
    ]
  }
]

Output – Cost Change Response Object

Attribute	Datatype	Description
message	string	Indicates processing outcome and the message is defined by cost type IIPS. Default configured values are “Processed Successfully”, “Processed with errors” or “Processed with warnings”
errors		Child Node – This will be empty when all the records got successfully processed. In case of multiple cost change request in the input and there are one/multiple/all failures, the error/warning reasons for each of the Non-successful cost change request will be captured here.

Output – Cost Change Response Record

Attribute	Datatype	Description
costChange	number	Contains the number that uniquely identifies the cost change.
field	string	This will contain the field in error.
item	string	Unique alphanumeric value that identifies the item.
supplier	number	Contains the number that identifies the supplier associated with the cost change.
originCountryId	string	The country where the item was manufactured or significantly altered.
loc	number	Number of the location the cost change will occur at.
locType	string	Contains the type of the location.
errorMessage	string	Contains the error message

Example JSON Output:

{
  "message": "Processed Successfully",
  "errors": [
    {
      "costChange": 123123,
      "field": "ACTIVE_DATE",
      "item": "123412312",
      "supplier": 60000,
      "originCountryId": "string",
      "loc": 0,
      "locType": "string",
      "errorMessage": "Invalid Active Date."
    }
  ]
}

Table Impact

TABLE	SELECT	INSERT	UPDATE	DELETE
SVC_COST_SUSP_SUP_HEAD	Yes	Yes	No	Yes
SVC_COST_SUSP_SUP_DETAIL	Yes	Yes	No	Yes
SVC_COST_SUSP_SUP_DETAIL_LOC	Yes	Yes	No	Yes
CORESVC_COSTCHG_ERR	Yes	Yes	No	Yes
SVC_PROCESS_TRACKER	Yes	Yes	No	Yes
SVC_CFA_EXT	Yes	Yes	No	Yes
COST_SUSP_SUP_HEAD	Yes	Yes	Yes	Yes
COST_SUSP_SUP_DETAIL	Yes	Yes	Yes	Yes
COST_SUSP_SUP_DETAIL_LOC	Yes	Yes	Yes	Yes
COST_CHANGE_TEMP	Yes	Yes	Yes	Yes
COST_CHANGE_LOC_TEMP	Yes	Yes	Yes	Yes
COST_SUSP_SUP_HEAD_CFA_EXT	Yes	Yes	No	Yes

Pricing Cost

The following services are included in this functional area:

• Pricing Cost Download Service

  • Get Pricing Cost

Pricing Cost Download Service

The following services are included in this functional area:

• Get Pricing Cost

Get Pricing Cost

Functional Area

Cost - Pricing Cost

Business Overview

This web service is used to provide pricing cost information to external systems. This information is assumed to be primarily used by Order Management System (OMS), which manages franchise customer orders and needs visibility to cost information as part of the negotiation process for margin visibility.

Pricing cost for an item at an owned location is the unit cost for the primary supplier/country, less off invoice deals, plus estimated landed costs. Pricing cost for an item at a customer (franchise) location is the unit cost for the costing location, less any deals passed through, plus estimated landed costs (based on system option), plus the franchise cost template details. This service supports providing cost information for an item/location or item/supplier/location.

The following validations are carried out for this service - 

• Only approved, transaction level items are valid.

• The location must be a company store or a physical warehouse that is customer orderable. For a physical warehouse, it must also include the channel ID that should be used.

• For physical warehouses, the cost returned will be for the virtual warehouse that matches the channel ID that is provided in the input. If there is no virtual warehouse that matches that channel in the physical warehouse, then the next best match will be determined based on channel type and the primary warehouse and protected flags on the virtual warehouses in the physical warehouse.

Service Type

POST

ReST URL

MerchIntegrations/services/cost/pricingCost/get

Input Payload Details

Table 5-24 Get - Object. See list of elements for detail

Element Name	Required	Data Type	Description
items	No	Collection of Object	It's a referenced element. For detailed description, please refer referenced element doc.

Table 5-25 Items - Object. See list of elements for detail

Element Name	Required	Data Type	Description
item	Yes	String (25)	Contains the Merchandising item number that uniquely identifies the item. This is required input for the Pricing Cost Service
supplier	No	Number (10)	Contains the Merchandising Supplier number for retrieving the Pricing Cost
supplierCountry	No	String (3)	Contains the country, supplier belongs to for which the Pricing Cost needs to be retrieved.
fulfillLocation	Yes	Number (10)	Contains the location number. This is required input for the Pricing Cost Service.
locationType	Yes	String (1)	Type of item inventory location. Valid values are 'S' (store) and 'W' (warehouse).
channelId	No	Number (4)	Only used when a physical WH is passed. If a channel is passed the results will be limited by the passed in channel.
activeDate	No	date	Contains the active date for which the pricing cost needs to be retrieved.

Sample Input Message

{
  "items": [
    {
      "item": "100100068",
      "supplier": 2400,
      "supplierCountry": "US",
      "fulfillLocation": 1141,
      "locationType": "S",
      "channelId": 1,
      "activeDate": "2001-12-31"
    }
  ]
}

Response Code: 200 (Success)

Table 5-26 GetResponse - Object. See list of elements for detail

Element Name	Required	Data Type	Description
items	No	Collection of Object	It's a referenced element. For detailed description, please refer referenced element doc.

Table 5-27 GetResponse.Items - Object. See list of elements for detail

Element Name	Required	Data Type	Description
item	Yes	String (25)	Contains the Merchandising item number that uniquely identifies the item. This is required input for the Pricing Cost Service
supplier	No	Number (10)	Contains the Merchandising Supplier number for retrieving the Pricing Cost.
supplierCountry	No	String (3)	Contains the country, supplier belongs to for which the Pricing Cost needs to be retrieved.
fulfillLocation	Yes	Number (10)	Contains the location number. This is required input for the Pricing Cost Service.
locationType	Yes	String (1)	Type of item inventory location. Valid values are 'S' (store) and 'W' (warehouse).
channelId	No	Number (4)	Only used when a physical WH is passed. If a channel is passed the results will be limited by the passed in channel.
activeDate	No	date	Contains the active date for which the pricing cost needs to be retrieved.
pricingCost	Yes	Number (20,4)	Contains the retrieved pricing cost from the future cost table for the passed parameters.

Sample Response Message

{
  "items": [
    {
      "item": "100100076",
      "supplier": 6000,
      "supplierCountry": "US",
      "fulfillLocation": 6000,
      "locationType": "S",
      "channelId": 1,
      "activeDate": "2001-12-31",
      "pricingCost": 9.65
    }
  ]
}

Response Code: 400 (Error)

In case of error, the following standard error response will be returned. The element "validationErrors" will be present when input payload or input parameters are not as per the schema definition of this service. The element "businessError" will be present if the payload passes schema validation but exception is caught while processing business logic.

Sample Error Message

{
  "status": "ERROR",
  "message": "Error found in validation of input payload",
  "validationErrors": [
    {
      "error": "must be one of Y, N",
      "field": "createRecord.arg0.approveInd",
      "inputValue": "X"
    }
  ],
  "businessError": [
    "Error message"
  ]
}