3 ReST Services

This chapter gives an overview about the Pricing ReSTful Web service implementation and the APIs used in Pricing. For more information on the ReST architectural style applied for building Web services, access the following URL:

http://www.oracle.com/technetwork/articles/javase/index-137171.html

To provide visibility to the background processing that's occurring, services write to the JOB_AUDIT_LOGS table in the database. Reports can be built based on this to provide visibility to what is happening in the background. Additionally, to assist users and developers in troubleshooting any error that may arise, the payload that was processed is also stored in the JOB_AUDIT_PAYLOAD table in the database.

Once the nightly batch run has started, web service execution will be halted, and users will receive a warning message that the nightly batch run has commenced.

Introduction

Pricing ReST support several web services, including the ability to query data and the ability to create and update data within the solutions. A few were built specifically to support mobile applications. These may not be useful for general use, however if you wanted to build your own mobile applications leveraging these services, this can be done. The ReSTful Web services Java code cannot be customized.

Common Characteristics

Services are secured using J2EE-based security model.

• Realm-based User Authentication: This verifies users through an underlying Realm. The username and password are passed using HTTP basic authentication.

• Role-based Authorization: This assigns users to roles; authenticated users can access the services with Pricing application roles or custom roles that are assigned to:

  • For Pricing: PRICING_APPLICATION_ADMINISTRATOR_JOB

• The communication between the server and client is encrypted using one-way SSL. In non-SSL environments the encoding defaults to BASE-64 so it is highly recommended that these ReST services are configured to be used in production environments secured with SSL connections.

• If you are using Merchandising data filtering, that will apply to the services as well. The user ID used for the calling the service should be added to the Merchandising SEC_USER table (APP_USER_ID), and then associated to the appropriate group in SEC_USER_GROUP table.

Standard Request and Response Headers

Pricing ReSTful web services have the following standard HTTP headers:

Accept:  application/xml or application/JSON
Accept-Language: en-US

Note:

Accept-Language is not mandatory, and defaults to en-US. User can change it though, in case they need content in a specific language.

Depending on the type of the operation or HTTP method, the corresponding response header is updated in the HTTP response with the following codes:

• GET/READ : 200

• PUT/CREATE : 201 created

• POST/UPDATE : 204

• DELETE : 204

Standard Error Response

Example response payload in case of service error is depicted below:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<messagesRDOes>
  <messagesRDO>
    <message>REST Service Version Mismatch</message>
    <messageType>ERROR</messageType>
    <status>BAD_REQUEST</status> 
  </messagesRDO>
</messagesRDOes>

• Message: The error message - translated.

• Message Type: Value of ERROR is returned.

• Status: For a bad request or error, the status is BAD_REQUEST.

• The http error code for an error response is 400.

Pricing URL Paths

Based on your implementation, you will need to prefix the end point with just the deployment hostname. The format that should be used for the hostname is rex.retail.<Region Name>.ocs.oraclecloud.com/<Customer Subnamespace>/, where <Region Name> is the region for your data center and <Customer Subnamespace> is specific to your company's name and environment (production, stage, and so on).

The following links provide access to the Pricing services:

• The ReSTful Web services swagger URL is available at:

  https://<hostname>/PricingServices/swagger-ui/

• The ReSTful Web services openapi.yaml is available at:

  https://<hostname>/PricingServices/services/openapi.yaml

• The ReSTful Web services WADL file is available at:

  https://<hostname>/PricingServices/services/application.wadl
  

• The ReSTful Web services are available at:

  https://<hostname>/PricingServices/services/private/<service>
  

OAuth for REST Service Authentication

OAuth 2.0 is the industry standard protocol for authorization. Pricing cloud services REST Services now supports OAuth 2.0. To invoke these services, you need to obtain and access token and use it as a bearer token.

Note:

Basic Authentication access is no longer supported for these services.

Steps to Enable

To obtain a token and call the services, use the following steps:

1. This step should be performed one time for a given environment. Generate the OAuth Client App with the environment-specific scope.

   Each environment has a different scope that is available after the provisioning of the environment. Use this scope to generate the OAuth Client App using the Retail Home UI. For details, refer to the "Creating OAuth Client Apps" section of the Retail Home Administration Guide, which can be found under Common Cloud Services Solutions in the Oracle Retail Help Center. Once the OAuth Client App is generated, note the client ID and secret. This information will be required for an access token to call REST services.

2. Get an access token using the OAuth client ID and secret from IDCS with the following command:

   export ACCESS_TOKEN="$(curl -u <Client ID>:<Secret> -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' --request POST https://<IDCS_BASE_URL>/oauth2/v1/token -d 'grant_type=client_credentials&scope=<Customer Environment Specific Scope>' | jq -r '.access_token')"
   

   The token is generally valid for 1 hour.

3. REST clients that need to call Pricing REST service end points should use the client ID and secret of the OAuth client generated in the previous step to get an access token.

   OAuth tokens can also be obtained by REST client tools like Postman for testing purposes by filling in the necessary details like client ID/secret and scope. Use the below information in such cases:

   Authorization: OAuth 2.0
   Access Token URL: https://<IDCS_BASE_URL>/oauth2/v1/token
   Client ID: <Client id of OAuth client app>
   Client Secret: <Client secret of OAuth client app>
   Scope: <Custom environment specific scope>
   

   The scope pattern that is used in the MFCS IDCS app creation template is rgbu:merch:<SERVICETYPE>-<ENVIRONMENT> where SERVICETYPE is MFCS and ENVIRONMENT is the environment type (STG, PRD, UAT, DEV1, DEV2, and so on).

   For example:

   "scope": "rgbu:merch:MFCS-PRD"
   "scope": "rgbu:merch:MFCS-STG"
   

   Example using the access token as a bearer token:

   curl --location --request GET 'http://<hostname or IP address>:<port number>/ RmsReSTServices/services/private/Common/vDate' \ --header 'Authorization: Bearer $ACCESS_TOKEN'

Price Inquiry

Business Overview

This service provides the ability to query the selling price of item/locations for a given date.

Service Type

POST

REST URL

/priceInquiry

Roles Allowed

PRICING_APPLICATION_ADMINISTRATOR_JOB, rgbu:merch:system

Request Headers

Accept:  <application/json or application/xml>
Accept-Language: <locale>
Content-Type: <application/json or application/xml>

For Example:

Accept:  application/json
Accept-Language: en-US
Content-Type: application/json

URL Query Parameters

N/A

Request Body

{
"itemLocations": [
  {
    "item": null,
    "location": null
  }, … (Possible list, comma separated for multiple)
  ],
  "date": null,
  "pageNumber": null,
  "pageSize": null,
  "sortOrder": null
}

Entity	Key	Type	Value
price inquiry	itemLocations	entity list	Item locations for inquiry
price inquiry	date	varchar	Date in the format YYYY-MM-DD
price inquiry	pageNumber	numeric	Page number to return
price inquiry	pageSize	numeric	Total number of results per page
price inquiry	sortOrder	varchar	ASC (ascending) or DESC (descending)
item location	item	varchar	Item ID (parent, transaction, or reference)
item location	location	numeric	Location ID (store or virtual warehouse)

Response Body

[
  {
    "requestedItem": null,
    "transactionItem": null,
    "location": null,
    "date": null,
    "onClearance": null,
    "sellingPrice": null,
    "sellingUom": null,
    "currency": null
  }
]

Entity	Key	Type	Value
price	requestedItem	varchar	Item ID (parent, transaction, or reference)
price	transactionItem	varchar	Transaction Item ID
price	location	numeric	Location ID (store or virtual warehouse)
price	date	varchar	Date in the format YYYY-MM-DD
price	onClearance	varchar	Y (yes) or N (no)
price	sellingPrice	numeric	Decimal selling price
price	sellingUom	varchar	Selling unit of measure
price	currency	varchar	Location's currency

Initial Retail

Business Overview

This service provides the ability to query the initial retail of an item/location.

Service Type

GET

REST URL

/initialRetail?item=<item>&location=<location>

Roles Allowed

PRICING_APPLICATION_ADMINISTRATOR_JOB, rgbu:merch:system

Request Headers

Accept:  <application/json or application/xml>
Accept-Language: <locale>
Content-Type: <application/json or application/xml>

For Example:

Accept:  application/json
Accept-Language: en-US
Content-Type: application/json

URL Query Parameters

Key	Type	Value
item	varchar	Item ID (transaction or reference)
location	numeric	Location ID (store or virtual warehouse)

Request Body

N/A

Response Body

[
  {
    "item": null,
    "location": null,
    "currentDate": null,
    "onClearance": null,
    "sellingPrice": null,
    "sellingUom": null,
    "currency": null
  }
]

Entity	Key	Type	Value
price	item	varchar	Item ID (transaction or reference)
price	location	numeric	Location ID (store or virtual warehouse)
price	currentDate	varchar	Date in the format YYYY-MM-DD
price	onClearance	varchar	Y (yes) or N (no)
price	sellingPrice	numeric	Decimal selling price
price	sellingUom	varchar	Selling unit of measure
price	currency	varchar	Location's currency

Price Change Induction

Business Overview

This service provides the ability to create, modify, and delete price changes via the induction process.

Service Type

POST

REST URL

/priceChange/induction

Roles Allowed

PRICING_APPLICATION_ADMINISTRATOR_JOB, rgbu:merch:system

Request Headers

Accept:  <application/json or application/xml>
Accept-Language: <locale>
Content-Type: <application/json or application/xml>

For Example:

Accept:  application/json
Accept-Language: en-US
Content-Type: application/json

URL Query Parameters

N/A

Request Body

[
  {
    "action": null,
    "newGroupBatch": null,
    "priceChangeGroup": null,
    "priceChangeGroupDesc": null,
    "priceChange": null,
    "item": null,
    "diff": null,
    "locationType": null,
    "location": null,
    "effectiveDate": null,
    "updatedEffectiveDate": null,
    "changeType": null,
    "changeValue": null,
    "sellingUom": null,
    "multiUnitImpact": null,
    "multiUnitRetail": null,
    "multiUnits": null,
    "multiUnitSellingUom": null,
    "roundingRule": null,
    "reason": null,
    "status": null,
    "ignoreConstraints": null,
    "primarySupplier": null,
    "purchaseType":  null,
    "generatedBy":  null
  }, … (Possible list, comma separated for multiple)
]

Key	Type	Value
action	varchar	"NEW", "MOD", or "DEL"
newGroupBatch	numeric	Transient numeric identifier to group related clearances together in the same clearance group upon creation.
priceChangeGroup	numeric	Price change group display ID
priceChangeGroupDesc	varchar	Price change group description
priceChange	numeric	Price change display ID
item	varchar	Item identifier (parent or transaction)
diff	varchar	Differentiator ID
locationType	numeric	0: Store, 1: Zone, 2: Warehouse
location	numeric	Location ID (either store, warehouse, or zone)
effectiveDate	varchar	Effective date in the format YYYY-MM-DD
updatedEffectiveDate	varchar	Updated effective date in the format YYYY-MM-DD
changeType	numeric	0: Change by Percent, 1: Change by Amount, 2: Fixed Price, 3: Reset POS Price
changeValue	numeric	Decimal change value
sellingUom	varchar	Selling unit of measure for Fixed Price change type
multiUnitImpact	varchar	AU: Add or Update, R: Remove, N: No Change
multiUnitRetail	numeric	Decimal multi unit fixed price change value
multiUnits	numeric	Multi unit quantity
multiUnitSellingUom	varchar	Selling unit of measure for multi unit price change
roundingRule	varchar	Rounding rule ID (technically name column RPM_ROUNDING_RULE.NAME)
reason	varchar	Reason code ID (CODE_DETAIL.CODE)
status	numeric	1: Worksheet, 2: Submitted, 3: Rejected, 4: Approved, 5: Executed, 10: Processing
ignoreConstraints	varchar	"Y" or "N"
primarySupplier	numeric	Item/Location Primary Supplier Site
purchaseType	numeric	0: Owned, 1:Consignment, 2:Concession
generatedBy	varchar	"S": Supplier, "R": Retailer

Response Body

{
  "statusMsg": null,
  "failPcTable": [
    {
      "newGroupBatch": null,
      "priceChange": null,
      "item": null,
      "diff": null,
      "locationType": null,
      "location": null,
      "effectiveDate": null,
      "errorMsg": null,
      "errorCode": null
    }, … (Possible list, comma separated for multiple)
  ]
}

Clearance Induction

Business Overview

This service provides the ability to create, modify, and delete clearance markdowns and clearance resets via the induction process.

Service Type

POST

REST URL

/clearance/induction

Roles Allowed

PRICING_APPLICATION_ADMINISTRATOR_JOB, rgbu:merch:system

Request Headers

Accept:  <application/json or application/xml>
Accept-Language: <locale>
Content-Type: <application/json or application/xml>

For Example:

Accept:  application/json
Accept-Language: en-US
Content-Type: application/json

URL Query Parameters

N/A

Request Body

[
  {
    "action": null,
    "newGroupBatch": null,
    "clearanceGroup": null,
    "clearanceGroupDesc": null,
    "clearance": null,
    "markdown": null,
    "item": null,
    "diff": null,
    "locationType": null,
    "location": null,
    "effectiveDate": null,
    "updatedEffectiveDate": null,
    "changeType": null,
    "changeValue": null,
    "roundingRule": null,
    "reason": null,
    "status": null,
    "primarySupplier": null,
    "purchaseType": null,
    "generatedBy": null
  }, … (Possible list, comma separated for multiple)
]

Key	Type	Value
action	varchar	"NEW", "MOD", or "DEL"
newGroupBatch	numeric	Transient numeric identifier to group related clearances together in the same clearance group upon creation.
clearanceGroup	numeric	Clearance group display ID
clearanceGroupDesc	varchar	Clearance group description
clearance	numeric	Clearance display ID
markdown	varchar	Markdown code ID (CODE_DETAIL.CODE)
item	varchar	Item identifier (parent or transaction)
diff	varchar	Differentiator ID
locationType	numeric	0: Store, 1: Zone, 2: Warehouse
location	numeric	Location ID (either store, warehouse, or zone)
effectiveDate	varchar	Effective date in the format YYYY-MM-DD
updatedEffectiveDate	varchar	Updated effective date in the format YYYY-MM-DD
changeType	numeric	0: Change by Percent, 1: Change by Amount, 2: Fixed Price, 3: Reset POS Price
changeValue	numeric	Decimal change value
roundingRule	varchar	Rounding rule ID (technically name column RPM_ROUNDING_RULE.NAME)
reason	varchar	Reason code ID (CODE_DETAIL.CODE)
status	numeric	1: Worksheet, 2: Submitted, 3: Rejected, 4: Approved, 5: Executed, 10: Processing
primarySupplier	numeric	Item/Location Primary Supplier Site
purchaseType	numeric	0: Owned, 1:Consignment, 2:Concession
generatedBy	varchar	"S": Supplier, "R": Retailer

Response Body

{
  "statusMsg": null,
  "failClrTable": [
    {
      "newGroupBatch": null,
      "clearance": null,
      "item": null,
      "diff": null,
      "locationType": null,
      "location": null,
      "effectiveDate": null,
      "errorMsg": null,
      "errorCode": null
    }, … (Possible list, comma separated for multiple)
  ]
}

Promotion Induction

Business Overview

This service provides the ability to create, modify, and delete promotions through the induction process.

Service Type

POST

REST URL

/promotion/induction

Roles Allowed

PRICING_APPLICATION_ADMINISTRATOR_JOB, rgbu:merch:system

Request Headers

Accept:  <application/json or application/xml>
Accept-Language: <locale>
Content-Type: <application/json or application/xml>

For Example:

Accept:  application/json
Accept-Language: en-US
Content-Type: application/json

URL Query Parameters

N/A

Request Body

[
  {
    "action": null,
    "newPromotionBatch": null,
    "promotionDescription": null,
    "campaign": null,
    "generatedBy": null,
    "offers": [
      {
        "action": null,
        "newOfferBatch": null,
        "offerDescription": null,
        "template": null,
        "startDate": null,
        "startTime": null,
        "endDate": null,
        "endTime": null,
        "couponCode": null,
        "couponCodeRequired": null,
        "distributionRule": null,
        "exclusiveDiscount": null,
        "currency": null,
        "comments": null,
        "customerDescription": null,
        "status": null,
        "primarySupplier": null,
        "purchaseType": null,
        "offerConditions": [
          {
            "action": null,
            "buyXAndYConditionNumber": null,
            "buySpendValue": null,
            "buyQuantityUom": null,
            "priceRestrictionOperator": null,
            "priceRestrictionValue1": null,
            "priceRestrictionValue2": null,
            "items": [
              {
                "action": null,
                "itemLevel": null,
                "department": null,
                "clazz": null,
                "subclass": null,
                "supplierSite": null,
                "brand": null, 
                "item": null,
                "diff": null,
                "excluded": null
              }
            ]
          }
        ],
        "offerReward": {
          "action": null,
          "discountType": null,
          "discountValue": null,
          "applyTo": null,
          "applyDiscountNumberOfTimes": null,
          "priceRestrictionOperator": null,
          "priceRestrictionValue1": null,
          "priceRestrictionValue2": null,
          "items": [
            {
              "action": null,
              "itemLevel": null,
              "department": null,
              "clazz": null,
              "subclass": null,
              "supplierSite": null,
              "brand": null, 
              "item": null,
              "diff": null,
              "excluded": null
            }
          ]
        },
        "offerLocations": [
          {
            "action": null,
            "locationType": null,
            "location": null,
            "excluded": null
          }
        ],
        "customAttributes": [
         {
            "action": null,
            "name": null,
            "value": null
         }
        ]
      }
    ]
  }, … (Possible list, comma separated for multiple)
]

Entity	Key	Type	Value
promotion	action	varchar	"NEW", "MOD" or "DEL"
promotion	newPromotionBatch	numeric	Transient numeric identifier to group related offers together in the same promotion upon creation.
promotion	promotionDescription	varchar	Promotion description
promotion	campaign	varchar	Promotion campaign name
promotion	generatedBy	varchar	"S": Supplier, "R": Retailer
promotion	offers	entity list	Offers for promotion
offer	action	varchar	"NEW", "MOD" or "DEL"
offer	newOfferBatch	numeric	Transient numeric identifier to group related offer details together upon creation.
offer	offerDescription	varchar	Offer description
offer	template	numeric	Offer template code (SELECT CODE FROM CODE_DETAIL WHERE CODE_TYPE IN ('TSOT', 'ISOT', 'TBOT', 'IBOT', 'IGOT')
offer	startDate	varchar	Start date in the format YYYY-MM-DD
offer	startTime	varchar	Start time in the format hh:mm a
offer	endDate	varchar	End date in the format YYYY-MM-DD
offer	endTime	varchar	End time in the format hh:mm a
offer	couponCode	varchar	Coupon code
offer	couponCodeRequired	numeric	0: No, 1: Yes
offer	distributionRule	varchar	Offer distribution code (SELECT CODE FROM CODE_DETAIL WHERE CODE_TYPE = 'OFDR')
offer	exclusiveDiscount	numeric	0: No, 1: Yes
offer	currency	varchar	Offer currency code
offer	comments	varchar	Comments
offer	customerDescription	varchar	Customer description
offer	status	numeric	1: Worksheet, 2: Submitted, 3: Rejected, 4: Approved, 6: Active, 9: Cancelled (SELECT CODE FROM CODE_DETAIL WHERE CODE_TYPE = 'PRST')
offer	primarySupplier	numeric	Item/Location Primary Supplier Site
offer	purchaseType	numeric	0: Owned, 1:Consignment, 2:Concession
offer	offerConditions	entity list	Conditions for offer
offer	offerReward	entity	Reward for offer
offer	offerLocations	entity list	Locations for offer
offer condition	action	varchar	"NEW", "MOD" or "DEL"
offer condition	buyXAndYConditionNumber	numeric	Positive number when template is "Buy X and Y Get Discount" or "Buy X and Y Get Z for Discount"
offer condition	buySpendValue	numeric	Decimal buy/spend value
offer condition	buyQuantityUom	varchar	Buy quantity unit of measure
offer condition	priceRestrictionOperator	varchar	Price restriction operator code (SELECT CODE FROM CODE_DETAIL WHERE CODE_TYPE = 'OPRO')
offer condition	priceRestrictionValue1	numeric	Decimal price restriction value
offer condition	priceRestrictionValue2	numeric	Decimal price restriction value (for second between value)
offer condition	items	entity list	Items for offer condition
offer condition merchandise	action	varchar	"NEW", "MOD" or "DEL"
offer condition merchandise	itemLevel	numeric	Merchandise level (SELECT CODE FROM CODE_DETAIL WHERE CODE_TYPE = 'OFII')
offer condition merchandise	department	numeric	Merchandise department
offer condition merchandise	clazz	numeric	Merchandise class
offer condition merchandise	subclass	numeric	Merchandise subclass
offer condition merchandise	supplierSite	numeric	Merchandise supplier site
offer condition merchandise	brand	varchar	Merchandise brand
offer condition merchandise	item	varchar	Item ID (parent or transaction)
offer condition merchandise	diff	varchar	Differentiator ID
offer condition merchandise	excluded	numeric	0: No, 1: Yes
offer reward	action	varchar	"NEW", "MOD" or "DEL"
offer reward	discountType	numeric	0: Percent Off, 1: Amount Off, 2: Fixed Price (SELECT CODE FROM CODE_DETAIL WHERE CODE_TYPE = 'OFCT')
offer reward	discountValue	numeric	Decimal discount value
offer reward	applyTo	numeric	0: Regular, 1: Clearance, 2: Regular and Clearance (SELECT CODE FROM CODE_DETAIL WHERE CODE_TYPE = 'PRAT')
offer reward	applyDiscountNumberOfTimes	numeric	Number of times the discount can be applied to individual item
offer reward	priceRestrictionOperator	varchar	Price restriction operator code (SELECT CODE FROM CODE_DETAIL WHERE CODE_TYPE = 'OPRO')
offer reward	priceRestrictionValue1	numeric	Decimal price restriction value
offer reward	priceRestrictionValue2	numeric	Decimal price restriction value (for second between value)
offer reward	items	entity list	Items for offer reward
offer reward merchandise	action	varchar	"NEW", "MOD" or "DEL"
offer reward merchandise	itemLevel	numeric	Merchandise level (SELECT CODE FROM CODE_DETAIL WHERE CODE_TYPE = 'OFII')
offer reward merchandise	department	numeric	Merchandise department
offer reward merchandise	clazz	numeric	Merchandise class
offer reward merchandise	subclass	numeric	Merchandise subclass
offer reward merchandise	supplierSite	numeric	Merchandise supplier site
offer reward merchandise	brand	varchar	Merchandise brand
offer reward merchandise	item	varchar	Item ID (parent or transaction)
offer reward merchandise	diff	varchar	Differentiator ID
offer reward merchandise	excluded	numeric	0: No, 1: Yes
offer location	action	varchar	"NEW", "MOD" or "DEL"
offer location	locationType	numeric	0: Store, 1: Zone (SELECT CODE FROM CODE_DETAIL WHERE CODE_TYPE = 'OFLI')
offer location	location	numeric	Location ID (store or zone display ID)
offer location	excluded	numeric	0: No, 1: Yes
customAttributes	action	varchar	"NEW", "MOD" or "DEL"
customAttributes	name	varchar	Custom Flex Attribute Name
customAttributes	value	varchar	Custom Flex Attribute Value If the custom flex attribute value is of date, the format required is yyyy-MM-dd

Response Body

{
  "statusMsg": null,
  "successes": [
    {
      "newPromotionBatch": null,
      "promotion": null,
      "offers": [
        {
          "newOfferBatch": null,
          "offer": null,
        }
      ]
    }
  ],
  "errors": [
    {
      "newPromotionBatch": null,
      "offers": [
        {
          "newOfferBatch": null,
          "conditions": [
            {
              "buyXAndYConditionNumber": null,
              "items": [
                {

                  "itemLevel": null,
                  "department": null,
                  "clazz": null,
                  "subclass": null,
                  "supplierSite": null,
                  "brand": null,
                  "item": null,
                  "diff": null,
                  "excluded": null,
                  "errors": [
                    {
                      "type": null,
                      "field": null,
                      "message": null,
                      "code": null
                    }
                  ]
                }
              ],
              "errors": [
                {
                  "type": null,
                  "field": null,
                  "message": null,
                  "code": null
                }
              ]
            }
          ],
          "reward": {
            "items": [
              {
                "itemLevel": null,
                "department": null,
                "clazz": null,
                "subclass": null,
                "supplierSite": null,
                "brand": null,
                "item": null,
                "diff": null,
                "excluded": null,
                "errors": [
                  {
                    "type": null,
                    "field": null,
                    "message": null,
                    "code": null
                  }
                ]
              }
            ],
            "errors": [
              {
                "type": null,
                "field": null,
                "message": null,
                "code": null
              }
            ]
          },
          "locations": [
            {
              "locationType": null,
              "location": null,
              "excluded": null,
              "errors": [
                {
                  "type": null,
                  "field": null,
                  "message": null,
                  "code": null
                }
              ]
            }
          ],
          "errors": [
            {
              "type": null,
              "field": null,
              "message": null,
              "code": null
            }
          ]
        }
      ],
      "errors": [
        {
          "type": null,
          "field": null,
          "message": null,
          "code": null
        }
      ]
    }
  ]
}

Entity	Key	Type	Value
status	statusMsg	varchar	Status of the promotions create request
status	successes	entity list	Promotion successes
status	errors	entity list	Promotion errors
promotion success	newPromotionBatch	numeric	Transient numeric identifier to map back to the request promotion entity
promotion success	promotion	numeric	Created promotion display ID
promotion success	offers	entity list	Offer successes for promotion
offer success	newOfferBatch	numeric	Transient numeric identifier to map back to the request offer entity
offer success	offer	numeric	Created offer display ID
promotion error	newPromotionBatch	numeric	Transient numeric identifier to map back to the request promotion entity
promotion error	offers	entity list	Offer errors for promotion
promotion error	errors	entity list	Error details for promotion
offer error	newOfferBatch	numeric	Transient numeric identifier to map back to the request offer entity
offer error	conditions	entity list	Condition errors for offer
offer error	reward	entity	Reward error for offer
offer error	locations	entity list	Location errors for offer
offer error	errors	entity list	Error details for offer
offer condition error	buyXAndYConditionNumber	numeric	Numeric identifier to map back to the request condition entity
offer condition error	items	entity list	Item errors for offer condition
offer condition error	errors	entity list	Error details for offer condition
offer condition merchandise error	itemLevel	numeric	Merchandise level to map back to the request condition merchandise entity
offer condition merchandise error	department	numeric	Merchandise department to map back to the request condition merchandise en-tity
offer condition merchandise error	clazz	numeric	Merchandise class to map back to the request condition merchandise entity
offer condition merchandise error	subclass	numeric	Merchandise subclass to map back to the request condition merchandise entity
offer condition merchandise error	supplierSite	numeric	Merchandise supplier site to map back to the request condition merchandise entity
offer condition merchandise error	brand	varchar	Merchandise brand to map back to the request condition merchandise entity
offer condition merchandise error	item	varchar	Item ID (parent or transaction) to map back to the request condition merchandise entity
offer condition merchandise error	diff	varchar	Differentiator ID to map back to the re-quest condition merchandise entity
offer condition merchandise error	excluded	numeric	Excluded value to map back to the re-quest condition merchandise entity
offer condition merchandise error	errors	entity list	Error details for offer condition merchandise
offer reward error	items	entity list	Item errors for offer reward
offer reward error	errors	entity list	Error details for offer reward
offer reward error	itemLevel	numeric	Merchandise level to map back to the request reward merchandise entity
offer reward error	department	numeric	Merchandise department to map back to the request reward merchandise entity
offer reward error	clazz	numeric	Merchandise class to map back to the request reward merchandise entity
offer reward error	subclass	numeric	Merchandise subclass to map back to the request reward merchandise entity
offer reward error	supplierSite	numeric	Merchandise supplier site to map back to the request reward merchandise entity
offer reward error	brand	varchar	Merchandise brand to map back to the request reward merchandise entity
offer reward error	item	varchar	Item ID (parent or transaction) to map back to the request reward merchandise entity
offer reward error	diff	varchar	Differentiator ID to map back to the re-quest reward merchandise entity
offer reward error	excluded	numeric	Excluded value to map back to the request reward merchandise entity
offer reward error	errors	entity list	Error details for offer reward merchandise
offer location error	locationType	numeric	Location type value to map back to the request location entity
offer location error	location	numeric	Location ID to map back to the request location entity
offer location error	excluded	numeric	Excluded value to map back to the request location entity
offer location error	errors	entity list	Error details for offer location
error	type	varchar	E: Error, W: Warning
error	field	varchar	Entity attribute, field, or column in error
error	message	varchar	Error message

Item Price - v1

This end point is marked for deprecation from v24.1.301.0 and is scheduled for removal in 2 years.

Use PricingServices/services/private/omnichannel/v2/item/price/[regular|clearance] instead of this end point.

Business Overview

This service provides the ability to get retail information for a given time period. Used to get initial retail, Regular Price Changes and Clearances. Targeted for OMS/Xstore usage. This endpoint includes business functionality around clearances being reset by regular price changes.

Service Type

GET

REST URL

omnichannel/v1/item/price

Roles Allowed

PRICING_APPLICATION_ADMINISTRATOR_JOB, rgbu:merch:system

Request Headers

Accept:  <application/json or application/xml>
Accept-Language: <locale>

For Example:

Accept:  application/json
Accept-Language: en-US

URL Query Parameters

Parameter	Value	Description	Optional	Data Type
since	ISO-8601 Date and Time	Request data changed since a specific point in time. Use is optional, if not used then changes since 00:00:00 (UTC) on January 1, 1970 will be returned.	Yes	Timestamp
before	ISO-8601 Date and Time	Request data changed before a specific point in time. This parameter provides a mechanism where by callers can exclude data-changes occurring at the present time to avoid getting partial changes due to in-flight changes.	Yes	Timestamp
nodelevel	COMPANY	Request data for a single node in the Organization Hierarchy. Must be used with nodeid to identify the node.	Yes	String
	CHAIN
	AREA
	REGION
	DISTRICT
	STORE
	WAREHOUSE
nodeid	0 .. n	Request data for a single node in the Organization Hierarchy. Must be used with node level to identify the node.	Yes	Integer
pricetype	INITIAL	Request data for a single Price Type.	No	String
	REGULAR
	CLEARANCE
limit	0 .. n	Limit response size to a fixed number of data items to control paging of result data. Use is optional. If not used then a default limit of 1000 is used.	Yes	Integer
offsetkey	generated	Provides the offset information for the next page. This will never be provided on the initial request and will be part of the next link for subsequent requests. It is machine generated and should never be altered.	Yes	String

Request Body

N/A

Response Body

 {
    "hasMore": null,
    "limit": null,
    "count": null,
    "links": [
        {
            "href": null,
            "rel": null
        },
        {
            "href": null,
            "rel": null
        }
    ],
    "items": [
        {
            "action": null,
            "loctype": null,
            "location": null,
            "item": null,
            "price": null,
            "pricetype": null,
            "effective": null,
            "source": null,
            "eventid": null,
            "resetind": null,
            "clearanceind": null
        }
    ]
}

Entity	Key	Value	Description	Data Type
item/loc page	items	entity list	List of item/location prices. Sorted by: loctype (Ascending), location (Ascending), item (Ascending)	List
item	action	NO_CHANGE	Recommended action based on how data has changed since a point in time.	String
		DELETE
		UPSERT
		INSERT
		UPDATE
item	loctype	S (Store)	Location type.	String
		W (Warehouse)
item	location	0 .. n	Location identifier for item price.	Integer
item	item	RMS Item Identifier	Item identifier.	String
item	pricetype	INITIAL	Price Type of item/location price.	String
		REGULAR
		CLEARANCE
item	price	Localized decimal number	Item/location price.	BigDecimal
item	effective	ISO-8601 Date and Time	Date and time when change becomes effective.	Timestamp
item	source		If direct, the price was initiated directly. Implied means the price change was implied by another price change.	String
item	eventid	0 .. n	Pricing Service event id for the price activity.	Integer
item	resetind	0 (No)	Flag to indicate to reset the item to previous price.	Integer
		1 (Yes)
item	clearanceind	0 (No)	Flag to indicate the item is on clearance	Integer
		1 (Yes)
item/loc page	hasMore	TRUE	Boolean flag to indicate if more data is available.	Boolean
		FALSE
item/loc page	limit	0 .. n	Maximum number of records to return in a single request.	Integer
item/loc page	count	0 .. n	Count of records returned in the response. This will be less than or equal to the limit value.	Integer
item/loc page	links	entity list	List of related links.	List
link	rel	self	self: The calling URL.	String
		next	next: Only present if the hasMore flag is trueLink to the next page of data. Applications should the value of the href element to access the next page of data. This url contains a server generated offsetkey parameter to identify the start of the next page.
		describedBy	describedBy: Link to the metadata catalog.
link	href	URL	The related URL.	String

Item Price - v2

Business Overview

This service provides the ability to get retail information for a given time period. Used to get Regular Price Changes. Targeted for non-Oracle Retail applications. This endpoint does not include business functionality around clearances being reset by regular price changes.

Service Type

GET

REST URL

omnichannel/v2/item/price/regular

Roles Allowed

PRICING_APPLICATION_ADMINISTRATOR_JOB, rgbu:merch:system

Request Headers

Accept:  <application/json or application/xml>
Accept-Language: <locale>

For example:

Accept:  application/json
Accept-Language: en-US

URL Query Parameters

Parameter	Value	Description	Optional	Data Type
since	ISO-8601 Date and Time	Request data changed since a specific point in time. Use is optional, if not used then changes since 00:00:00 (UTC) on January 1, 1970 will be returned.	Yes	Timestamp
before	ISO-8601 Date and Time	Request data changed before a specific point in time. This parameter provides a mechanism where by callers can exclude data-changes occurring at the present time to avoid getting partial changes due to in-flight changes.	Yes	Timestamp
nodelevel	COMPANY	Request data for a single node in the Organization Hierarchy. Must be used with nodeid to identify the node.	Yes	String
	CHAIN
	AREA
	REGION
	DISTRICT
	STORE
	WAREHOUSE
nodeid	0 .. n	Request data for a single node in the Organization Hierarchy. Must be used with node level to identify the node.	Yes	Integer
limit	0 .. n	Limit response size to a fixed number of data items to control paging of result data. Use is optional. If not used then a default limit of 1000 is used.	Yes	Integer
offsetkey	generated	Provides the offset information for the next page. This will never be provided on the initial request and will be part of the next link for subsequent requests. It is machine generated and should never be altered.	Yes	String

Request Body

N/A

Response Body

{
    "hasMore": null,
    "limit": null,
    "count": null,
    "links": [
        {
            "href": null,
            "rel": null
        },
        {
            "href": null,
            "rel": null
        }
    ],
    "items": [
        {
            "msgType": null,
            "item": null,
            "location": null,
            "loctype": null,
            "price": null,
            "pricetype": null,
            "effective": null,
            "eventid": null,
            "resetind": null,
            "retailchangeind": null,
            "unitofmeasure": null,
            "currency": null,
            "multiunitimpact": null,
            "multiunits": null,
            "multiunitretail": null,
            "multiunitcurrency": null,
            "multiunitsellinguom": null,
            "source": null,
            "clearanceind" : null,
            "action": null
        }
    ]
} 

Entity	Key	Value	Description	Data Type
item/loc page	items	entity list	List of item/location prices. Sorted by: loctype (Ascending), location (Ascending), item (Ascending)	List
item	action	NO_CHANGE	Recommended action based on how data has changed since a point in time.	String
		DELETE
		UPSERT
		INSERT
		UPDATE
item	msgType	REGPRCCHGCRE	Price Event payload type	String
		REGPRCCHGMOD
		REGPRCCHGDEL
item	loctype	S (Store)	Location type.	String
		W (Warehouse)
item	location	0 .. n	Location identifier for item price.	Integer
item	item	RMS Item Identifier	Item identifier.	String
item	pricetype	REGULAR	Price Type of item/location price.	String
item	price	Localized decimal number	Item/location price.	BigDecimal
item	effective	ISO-8601 Date and Time	Date and time when change becomes effective.	Timestamp
item	eventid	0 .. n	Pricing Service event id for the price activity.	Integer
item	resetind	0 (No)	Flag to indicate to reset the item to previous price.	Integer
		1 (Yes)
item	retailchangeind	0 (No)	Flag to indicate the retail change indicator	Integer
		1 (Yes)
item	unitofmeasure		Unit of Measure	String
item	currency		Currency	String
item	multiunitimpact		Multi UOM impacts	String
item	multiunits		Multi Units indicator	String
item	multiunitretail		Multi Units Retail	String
item	multiunitcurrency		Multi Units Currency	String
item	multiunitsellinguom		Multi Units Selling UOM	String
item	source		If direct, the price was initiated directly. Implied means the price change was implied by another price change.	String
item	clearanceind	0 (No) 1 (Yes)	Flag to indicate the item is on clearance	Integer
item/loc page	hasMore	TRUE	Boolean flag to indicate if more data is available.	Boolean
		FALSE
item/loc page	limit	0 .. n	Maximum number of records to return in a single request.	Integer
item/loc page	count	0 .. n	Count of records returned in the response. This will be less than or equal to the limit value.	Integer
item/loc page	links	entity list	List of related links.	List
link	rel	self	self: The calling URL.	String
		next	next: Only present if the hasMore flag is trueLink to the next page of data. Applications should the value of the href element to access the next page of data. This url contains a server generated offsetkey parameter to identify the start of the next page.
		describedBy	describedBy: Link to the metadata catalog.
link	href	URL	The related URL.	String

Initial Price - v2

This end point is marked for deprecation from v24.1.301.0 and scheduled for removal in 2 years.

Use MerchIntegrations/services/foundation/omnichannel/item/initialprice

Business Overview

This service provides the ability to get retail information for an item at the time of creation. Used to get initial retail. Targeted for non-Oracle Retail applications.

Service Type

GET

REST URL

omnichannel/v2/item/price/initial

Roles Allowed

PRICING_APPLICATION_ADMINISTRATOR_JOB, rgbu:merch:system

Request Headers

Accept: <application/json or application/xml>
Accept-Language: <locale>

For Example:

Accept: application/json
Accept-Language: en-US

URL Query Parameters

Parameter	Value	Description	Optional	Data Type
since	ISO-8601 Date and Time	Request data changed since a specific point in time. Use is optional, if not used then changes since 00:00:00 (UTC) on January 1, 1970 will be returned.	Yes	Timestamp
before	ISO-8601 Date and Time	Request data changed before a specific point in time. This parameter provides a mechanism where by callers can exclude data-changes occurring at the present time to avoid getting partial changes due to in-flight changes.	Yes	Timestamp
nodelevel	COMPANY	Request data for a single node in the Organization Hierarchy. Must be used with nodeid to identify the node.	Yes	String
	CHAIN
	AREA
	REGION
	DISTRICT
	STORE
	WAREHOUSE
nodeid	0 .. n	Request data for a single node in the Organization Hierarchy. Must be used with node level to identify the node.	Yes	Integer
limit	0 .. n	Limit response size to a fixed number of data items to control paging of result data. Use is optional. If not used then a default limit of 1000 is used.	Yes	Integer
offsetkey	generated	Provides the offset information for the next page. This will never be provided on the initial request and will be part of the next link for subsequent requests. It is machine generated and should never be altered.	Yes	String

Request Body

N/A

Response Body

{
   "hasMore": null,
   "limit": null,
   "count": null,
   "links": [
      {
         "href": null,
         "rel": "describedBy"
      },
      {
         "href": null,
         "rel": "self"
      },
      {
         "href": null,
         "rel": "next"
      }
   ],
   "items": [
      {
         "action": null,
         "loctype": null,
         "location": null,
         "item": null,
         "price": null,
         "pricetype": null,
         "effective": null,
         "source": null,
         "eventid": null,
         "resetind": null,
         "clearanceind": 0
      }
   ]
}

Entity	Key	Value	Description	Data Type
item/loc page	items	entity list	List of item/location prices. Sorted by: loctype (Ascending), location (Ascending), item (Ascending)	List
item	action	NO_CHANGE	Recommended action based on how data has changed since a point in time.	String
		DELETE
		UPSERT
		INSERT
		UPDATE
item	loctype	S (Store)	Location type.	String
		W (Warehouse)
item	location	0 .. n	Location identifier for item price.	Integer
item	item	RMS Item Identifier	Item identifier.	String
item	pricetype	INITIAL	Price Type of item/location price.	String
item	price	Localized decimal number	Item/location price.	BigDecimal
item	effective	ISO-8601 Date and Time	Date and time when change becomes effective.	Timestamp
item	source		If direct, the price was initiated directly. Implied means the price change was implied by another price change.	String
item	eventid	0 .. n	Pricing Service event id for the price activity.	Integer
item	resetind	0 (No)	Flag to indicate to reset the item to previous price.	Integer
		1 (Yes)
item	clearanceind	0 (No)	Flag to indicate the item is on clearance	Integer
		1 (Yes)
item/loc page	hasMore	TRUE	Boolean flag to indicate if more data is available.	Boolean
		FALSE
item/loc page	limit	0 .. n	Maximum number of records to return in a single request.	Integer
item/loc page	count	0 .. n	Count of records returned in the response. This will be less than or equal to the limit value.	Integer
item/loc page	links	entity list	List of related links.	List
link	rel	self	self: The calling URL.	String
		next	next: Only present if the hasMore flag is trueLink to the next page of data. Applications should the value of the href element to access the next page of data. This url contains a server generated offsetkey parameter to identify the start of the next page.
		describedBy	describedBy: Link to the metadata catalog.
link	href	URL	The related URL.	String

Clearance Price - v2

Business Overview

This service provides the ability to get clearance for a given time period. Targeted for non-Oracle Retail applications. This endpoint does not include business functionality around clearances being reset by regular price changes.

Service Type

GET

REST URL

omnichannel/v2/item/price/clearance

Roles Allowed

PRICING_APPLICATION_ADMINISTRATOR_JOB, rgbu:merch:system

Request Headers

Accept: <application/json or application/xml>
Accept-Language: <locale>

For example:

Accept: application/json
Accept-Language: en-US

URL Query Parameters

Parameter	Value	Description	Optional	Data Type
since	ISO-8601 Date and Time	Request data changed since a specific point in time. Use is optional, if not used then changes since 00:00:00 (UTC) on January 1, 1970 will be returned.	Yes	Timestamp
before	ISO-8601 Date and Time	Request data changed before a specific point in time. This parameter provides a mechanism where by callers can exclude data-changes occurring at the present time to avoid getting partial changes due to in-flight changes.	Yes	Timestamp
nodelevel	COMPANY	Request data for a single node in the Organization Hierarchy. Must be used with nodeid to identify the node.	Yes	String
	CHAIN
	AREA
	REGION
	DISTRICT
	STORE
	WAREHOUSE
nodeid	0 .. n	Request data for a single node in the Organization Hierarchy. Must be used with node level to identify the node.	Yes	Integer
limit	0 .. n	Limit response size to a fixed number of data items to control paging of result data. Use is optional. If not used then a default limit of 1000 is used.	Yes	Integer
offsetkey	generated	Provides the offset information for the next page. This will never be provided on the initial request and will be part of the next link for subsequent requests. It is machine generated and should never be altered.	Yes	String

Request Body

N/A

Response Body

{
    "hasMore": null,
    "limit": null,
    "count": null,
    "links": [
        {
            "href": null,
            "rel": "describedBy"
        },
        {
            "href": null,
            "rel": "self"
        }
    ],
    "items": [
        {
            "msgType": null,
            "item": null,
            "location": null,
            "loctype": null,
            "price": null,
            "pricetype": null,
            "effective": null,
            "eventid": null,
            "resetind": null,
            "action": null
        }
    ]
}

Entity	Key	Value	Description	Data Type
item/loc page	items	entity list	List of item/location prices. Sorted by: loctype (Ascending), location (Ascending), item (Ascending)	List
item	action	NO_CHANGE	Recommended action based on how data has changed since a point in time.	String
		DELETE
		UPSERT
		INSERT
		UPDATE
item	msgType	CLRPRCCHGCRE	Price Event payload type	String
		CLRPRCCHGMOD
		CLRPRCCHGDEL
item	loctype	S (Store)	Location type.	String
		W (Warehouse)
item	location	0 .. n	Location identifier for item price.	Integer
item	item	RMS Item Identifier	Item identifier.	String
item	pricetype	CLEARANCE	Price Type of item/location price.	String
item	price	Localized decimal number	Item/location price.	BigDecimal
item	effective	ISO-8601 Date and Time	Date and time when change becomes effective.	Timestamp
item	eventid	0 .. n	Pricing Service event id for the price activity.	Integer
item	resetind	0 (No)	Flag to indicate to reset the item to previous price.	Integer
		1 (Yes)
item/loc page	hasMore	TRUE	Boolean flag to indicate if more data is available.	Boolean
		FALSE
item/loc page	limit	0 .. n	Maximum number of records to return in a single request.	Integer
item/loc page	count	0 .. n	Count of records returned in the response. This will be less than or equal to the limit value.	Integer
item/loc page	links	entity list	List of related links.	List
link	rel	self	self: The calling URL.	String
		next	next: Only present if the hasMore flag is trueLink to the next page of data. Applications should the value of the href element to access the next page of data. This url contains a server generated offsetkey parameter to identify the start of the next page.
		describedBy	describedBy: Link to the metadata catalog.
link	href	URL	The related URL.	String

Item Promotion - v1

This end point is marked for deprecation from v24.1.301.0 and scheduled for removal in 2 years.

Use PricingServices/services/private/omnichannel/v2/item/promotion instead of this end point.

Business Overview

This service provides the ability to get promotion information for a given time period. Targeted for OMS/Xstore usage.

Service Type

GET

REST URL

omnichannel/v1/item/promotion

Roles Allowed

PRICING_APPLICATION_ADMINISTRATOR_JOB, rgbu:merch:system

Request Headers

Accept:  <application/json or application/xml>
Accept-Language: <locale>

For Example:

Accept: application/json
Accept-Language: en-US

URL Query Parameters

Parameter	Value	Description	Optional	Data Type
since	ISO-8601 Date and Time	Request data changed since a specific point in time. Use is optional, if not used then changes since 00:00:00 (UTC) on January 1, 1970 will be returned.	Yes	Timestamp
before	ISO-8601 Date and Time	Request data changed before a specific point in time. This parameter provides a mechanism where by callers can exclude data-changes occurring at the present time to avoid getting partial changes due to in-flight changes.	Yes	Timestamp
nodelevel	COMPANY	Request data for a single node in the Organization Hierarchy. Must be used with nodeid to identify the node.	Yes	String
	CHAIN
	AREA
	REGION
	DISTRICT
	STORE
nodeid	0 .. n	Request data for a single node in the Organization Hierarchy. Must be used with node level to identify the node.	Yes	Integer
limit	0 .. n	Limit response size to a fixed number of data items to control paging of result data. Use is optional. If not used then a default limit of 1000 is used.	Yes	Integer
offsetkey	generated	Provides the offset information for the next page. This will never be provided on the initial request and will be part of the next link for subsequent requests. It is machine generated and should never be altered.	Yes	String

Request Body

N/A

Response Body

{
   "hasMore": null,
   "limit": null,
   "count": null,
   "links": [
      {
         "href": null,
         "rel": "describedBy"
      },
      {
         "href": null,
         "rel": "self"
      }
   ],
   "items": [
      {
         "promoid": null,
         "offerid": null,
         "desc": null,
         "custdesc": null,
         "levelcode": null,
         "typecode": null,
         "templateid": null,
         "couponcode": null,
         "couponcodereq": null,
         "startdatetime": null,
         "enddatetime": null,
         "canceldatetime": null,
         "rewards": [
            {
               "rewardid": null,
               "changetype": null,
               "changeamount": null,
               "changepercent": null,
               "qtytodisc": null,
               "qtytodiscuom": null,
               "applyind": null,
               "pricerestrictcode": null,
               "pricerestrictvalue1": null,
               "pricerestrictvalue2": null,
               "rewardsmerch": [
                  {
                     "rewardmerchid": null,
                     "merchlevel": null,
                     "dept": null,
                     "uniqueclass": null,
                     "subclass": null,
                     "uniquesubclass": null,
                     "item": null,
                     "diffid": null,
                     "excludeind": null,
                     "canceldatetime": null,
                     "class": null
                  }
               ]
            }
         ],
         "conditions": [
            {
               "conditionid": null,
               "buyspendtype": null,
               "buyspendvalue": null,
               "buyuom": null,
               "pricerestrictcode": null,
               "pricerestrictvalue1": null,
               "pricerestrictvalue2": null,
               "conditionsmerch": [
                  {
                     "condmerchid": null,
                     "merchlevel": null,
                     "dept": null,
                     "uniqueclass": null,
                     "subclass": null,
                     "uniquesubclass": null,
                     "item": null,
                     "diffid": null,
                     "excludeind": null,
                     "canceldatetime": null,
                     "class": null
                  }
               ]
            }
         ],
         "locations": [
            {
               "location": null,
               "canceldatetime": null,
               "action": null
            }
         ]
      }
   ]
}

Entity	Key	Value	Description	Data Type
item/loc page	items	entity list	List of promotions. Sorted by: promoid (Ascending), offerid (Ascending)	List
promotion offer (item)	promoid	0 .. n	Promotion identifier.	Integer
promotion offer (item)	offerid	0 .. n	Offer Identifier.	Integer
promotion offer (item)	desc	text description	Description of the offer.	String
promotion offer (item)	custdesc	text description	Customer facing description.	String
promotion offer (item)	levelcode	0 (Item)	The level of the offer.	Integer
		1 (Transaction)
promotion offer (item)	typecode	0 (Item Simple)	The type of the offer.	Integer
		1 (Transaction Simple)
		2 (Transaction Buy Get)
		3 (Item Buy Get)
		4 (Item Gift With Purchase)
promotion offer (item)	templateid	0 (Get Discount)	The template of the offer.	Integer
		1 (Buy X, Get Discount)
		2 (Spend X, Get Discount)
		3 (Get Y for Discount)
		4 (Buy)
promotion offer (item)	couponcode	RMS coupon code identifier	Coupon code required by the offer.	String
promotion offer (item)	couponcodereq	0 (No)	Flag to indicate that a coupon is required.	Integer
		1 (Yes)
promotion offer (item)	startdatetime	ISO-8601 Date and Time	Starting date time for the offer.	Timestamp
promotion offer (item)	enddatetime	ISO-8601 Date and Time	Ending date time for the offer.	Timestamp
promotion offer (item)	canceldatetime	ISO-8601 Date and Time	Cancellation date time for the offer.	Timestamp
promotion offer (item)	conditions	entity list	Conditions associated with the offer.	List
offer condition	conditionid	0 .. n	Condition ID.	Integer
offer condition	buyspendtype	0 (Quantity)	The buy spend type of the condition.	Integer
		1 (Amount)
offer condition	buyspendvalue	Localized decimal number	The buy spend value of the condition.	BigDecimal
offer condition	buyuom	RMS UOM Identifier	The buy UOM of the condition.	String
offer condition	pricerestrictcode	B (Between)	Operator for price restriction.	String
		G (Greater Than)
		L (Less Than)
offer condition	pricerestrictvalue1	Localized decimal number	The first value of the price restriction.	BigDecimal
offer condition	pricerestrictvalue2	Localized decimal number	The second value of the price restriction. The second value is only used for between restrictions.	BigDecimal
offer condition	conditionsmerch	entity list	Collection of merchandise for condition.	List
offer condition merchandise	condmerchid	0 .. n	The unique id for the offer condition merch record.	Integer
offer condition merchandise	merchlevel	1 (Department)	The merchandise level.	Integer
		2 (Class)
		3 (Subclass)
		4 (Parent Item)
		5 (Parent/Diff Item)
		6 (Transaction Item)
		8 (All Departments)
offer condition merchandise	dept	0 .. n	Department ID.	Integer
offer condition merchandise	class	0 .. n	The non-unique class ID value.	Integer
offer condition merchandise	uniqueclass	0 .. n	The unique class ID value.	Integer
offer condition merchandise	subclass	0 .. n	The non-unique subclass ID value.	Integer
offer condition merchandise	uniquesubclass	0 .. n	The unique subclass ID value.	Integer
offer condition merchandise	item	RMS Item Identifier	Item ID.	String
offer condition merchandise	diffid	RMS Differentiator Identifier	Differentiator ID.	String
offer condition merchandise	excludeind	0 (No)	The exclude indicator.	Integer
		0 (Yes)
offer condition merchandise	canceldatetime	ISO-8601 Date and Time	Date and time when condition merchandise was cancelled.	Timestamp
promotion offer (item)	rewards	entity list	Rewards associated with the offer.	List
offer reward	rewardid	0 .. n	Reward ID.	Integer
offer reward	changetype	0 (change by percent)	Type of change for the reward.	Integer
		1 (change by amount)
		2 (fixed price)
offer reward	changeamount	Localized decimal number	The change by amount or fixed price amount.	BigDecimal
offer reward	changepercent	Localized decimal number	Percentage value when change type is change by percent.	BigDecimal
offer reward	qtytodisc	Localized decimal number	The qty to discount.	BigDecimal
offer reward	qtytodiscuom	RMS UOM Identifier	UOM of the discount quantity.	String
offer reward	applyind	0 (Regular only)	The apply to indicator of the reward.	Integer
		1 (Clearance only)
		2 (Regular and Clearance)
offer reward	pricerestrictcode	B (Between)	Operator for price restriction.	String
		G (Greater Than)
		L (Less Than)
offer reward	pricerestrictvalue1	Localized decimal number	The first value of the price restriction.	BigDecimal
offer reward	pricerestrictvalue2	Localized decimal number	The second value of the price restriction. The second value is only used for between restrictions.	BigDecimal
offer reward	rewardsmerch	entity list	Collection of merchandise eligible for reward.	List
offer reward merchandise	rewardmerchid	0 .. n	The unique id for the offer reward merch record.	Integer
offer reward merchandise	merchlevel	1 (Department)	The merchandise level.	Integer
		2 (Class)
		3 (Subclass)
		4 (Parent Item)
		5 (Parent/Diff Item)
		6 (Transaction Item)
		8 (All Departments)
offer reward merchandise	dept	0 .. n	Department ID.	Integer
offer reward merchandise	class	0 .. n	The non-unique class ID value.	Integer
offer reward merchandise	uniqueclass	0 .. n	The unique class ID value.	Integer
offer reward merchandise	subclass	0 .. n	The non-unique subclass ID value.	Integer
offer reward merchandise	uniquesubclass	0 .. n	The unique subclass ID value.	Integer
offer reward merchandise	item	RMS Item Identifier	Item ID.	String
offer reward merchandise	diffid	RMS Differentiator Identifier	Differentiator ID.	String
offer reward merchandise	excludeind	0 (No)	The exclude indicator.	Integer
		0 (Yes)
offer reward merchandise	canceldatetime	ISO-8601 Date and Time	Date and time when merchandise reward was cancelled.	Timestamp
promotion offer (item)	locations	entity list	Locations associated with the offer.	List
location	action	NO_CHANGE	Recommended action based on how data has changed since a point in time.	String
		DELETE
		UPSERT
		INSERT
		UPDATE
location	location	0 .. n	Location for promotion.	Integer
location	canceldatetime	ISO-8601 Date and Time	Date time promotion was cancelled for this location.	Timestamp
item/loc page	hasMore	TRUE	Boolean flag to indicate if more data is available.	Boolean
		FALSE
item/loc page	limit	0 .. n	Maximum number of records to return in a single request.	Integer
item/loc page	count	0 .. n	Count of records returned in the response. This will be less than or equal to the limit value.	Integer
item/loc page	links	entity list	List of related links.	List
link	rel	self	self: The calling URL.	String
		next	next: Only present if the hasMore flag is trueLink to the next page of data. Applications should the value of the href element to access the next page of data. This url contains a server generated offsetkey parameter to identify the start of the next page.
		describedBy	describedBy: Link to the metadata catalog.
link	href	URL	The related URL.	String

Item Promotion - v2

Business Overview

This service provides the ability to get promotion information for a given time period. Targeted for OMS/Xstore usage.

Service Type

GET

REST URL

omnichannel/v2/item/promotion

Roles Allowed

PRICING_APPLICATION_ADMINISTRATOR_JOB, rgbu:merch:system

Request Headers

Accept: <application/json or application/xml>
Accept-Language: <locale>

For Example:

Accept: application/json
Accept-Language: en-US

URL Query Parameters

Parameter	Value	Description	Optional	Data Type
since	ISO-8601 Date and Time	Request data changed since a specific point in time. Use is optional, if not used then changes since 00:00:00 (UTC) on January 1, 1970 will be returned.	Yes	Timestamp
before	ISO-8601 Date and Time	Request data changed before a specific point in time. This parameter provides a mechanism where by callers can exclude data-changes occurring at the present time to avoid getting partial changes due to in-flight changes.	Yes	Timestamp
nodelevel	COMPANY	Request data for a single node in the Organization Hierarchy. Must be used with nodeid to identify the node.	Yes	String
	CHAIN
	AREA
	REGION
	DISTRICT
	STORE
	WAREHOUSE
nodeid	0 .. n	Request data for a single node in the Organization Hierarchy. Must be used with node level to identify the node.	Yes	Integer
limit	0 .. n	Limit response size to a fixed number of data items to control paging of result data. Use is optional. If not used then a default limit of 1000 is used.	Yes	Integer
offsetkey	generated	Provides the offset information for the next page. This will never be provided on the initial request and will be part of the next link for subsequent requests. It is machine generated and should never be altered.	Yes	String

Request Body

N/A

Response Body

{
   "hasMore": null,
   "limit": null,
   "count": null,
   "links": [
      {
         "href": null,
         "rel": "describedBy"
      },
      {
         "href": null,
         "rel": "self"
      }
   ],
   "items": [
      {
         "promoid": null,
         "offerid": null,
         "desc": null,
         "custdesc": null,
         "levelcode": null,
         "typecode": null,
         "templateid": null,
         "couponcode": null,
         "couponcodereq": null,
         "startdatetime": null,
         "enddatetime": null,
         "canceldatetime": null,
         "comments": null,
         "distributionrulecode": null,
         "exclusivediscountind": null,
         "primarysupplier": null,
         "purchasetype": null,
         "generatedby": null,
         "rewards": [
            {
               "rewardid": null,
               "changetype": null,
               "changeamount": null,
               "changepercent": null,
               "qtytodisc": null,
               "applyind": null,
               "pricerestrictcode": null,
               "pricerestrictvalue1": null,
               "pricerestrictvalue2": null,
               "rewardsmerch": [
                  {
                     "rewardmerchid": null,
                     "merchlevel": null,
                     "dept": null,
                     "uniqueclass": null,
                     "subclass": null,
                     "uniquesubclass": null,
                     "item": null,
                     "diffid": null,
                     "excludeind": null,
                     "canceldatetime": null,
                     "suppliersite": null,
                     "brandname": null,
                     "class": null
                  }
               ]
            }
         ],
         "conditions": [
            {
               "conditionid": null,
               "buyspendtype": null,
               "buyspendvalue": null,
               "buyuom": null,
               "pricerestrictcode": null,
               "pricerestrictvalue1": null,
               "pricerestrictvalue2": null,
               "conditionsmerch": [
                  {
                     "condmerchid": null,
                     "merchlevel": null,
                     "dept": null,
                     "uniqueclass": null,
                     "subclass": null,
                     "uniquesubclass": null,
                     "item": null,
                     "diffid": null,
                     "excludeind": null,
                     "canceldatetime": null,
                     "suppliersite": null,
                     "brandname": null,
                     "class": null
                  }
               ]
            }
         ],
         "locations": [
            {
               "location": null,
               "canceldatetime": null,
               "action": null
            }
         ]
      }
   ]
}

Entity	Key	Value	Description	Data Type
item/loc page	items	entity list	List of promotions. Sorted by: promoid (Ascending), offerid (Ascending)	List
promotion offer (item)	promoid	0 .. n	Promotion identifier.	Integer
promotion offer (item)	offerid	0 .. n	Offer Identifier.	Integer
promotion offer (item)	desc	text description	Description of the offer.	String
promotion offer (item)	custdesc	text description	Customer facing description.	String
promotion offer (item)	levelcode	0 (Item)	The level of the offer.	Integer
		1 (Transaction)
promotion offer (item)	typecode	0 (Item Simple)	The type of the offer.	Integer
		1 (Transaction Simple)
		2 (Transaction Buy Get)
		3 (Item Buy Get)
		4 (Item Gift With Purchase)
promotion offer (item)	templateid	0 (Get Discount)	The template of the offer.	Integer
		1 (Buy X, Get Discount)
		2 (Spend X, Get Discount)
		3 (Get Y for Discount)
		4 (Buy)
promotion offer (item)	couponcode	RMS coupon code identifier	Coupon code required by the offer.	String
promotion offer (item)	couponcodereq	0 (No)	Flag to indicate that a coupon is required.	Integer
		1 (Yes)
promotion offer (item)	startdatetime	ISO-8601 Date and Time	Starting date time for the offer.	Timestamp
promotion offer (item)	enddatetime	ISO-8601 Date and Time	Ending date time for the offer.	Timestamp
promotion offer (item)	canceldatetime	ISO-8601 Date and Time	Cancellation date time for the offer.	Timestamp
promotion offer (item)	comments	text description	Comments for the offer	String
promotion offer (item)	distributionrulecode	text description	Distribution rule code of the offer	String
promotion offer (item)	exclusivediscountind	0 (No)1 (Yes)	Flag to indicate that the offer is exclusively discounted	Integer
promotion offer (item)	primarysupplier	RMS Supplier Site	Item/Location Primary Supplier Site of the offer	Integer
promotion offer (item)	purchasetype	0 (Owned) 1 (Consignment) 2 (Concession)	Purchase Type of the offer	Integer
promotion offer (item)	generatedby	S (Supplier) R (Retailer)	User type generating the offer	String
promotion offer (item)	conditions	entity list	Conditions associated with the offer.	List
offer condition	conditionid	0 .. n	Condition ID.	Integer
offer condition	buyspendtype	0 (Quantity)	The buy spend type of the condition.	Integer
		1 (Amount)
offer condition	buyspendvalue	Localized decimal number	The buy spend value of the condition.	BigDecimal
offer condition	buyuom	RMS UOM Identifier	The buy UOM of the condition.	String
offer condition	pricerestrictcode	B (Between)	Operator for price restriction.	String
		G (Greater Than)
		L (Less Than)
offer condition	pricerestrictvalue1	Localized decimal number	The first value of the price restriction.	BigDecimal
offer condition	pricerestrictvalue2	Localized decimal number	The second value of the price restriction. The second value is only used for between restrictrions.	BigDecimal
offer condition	conditionsmerch	entity list	Collection of merchandise for condition.	List
offer condition merchandise	condmerchid	0 .. n	The unique id for the offer condition merch record.	Integer
offer condition merchandise	merchlevel	1 (Department)	The merchandise level.	Integer
		2 (Class)
		3 (Subclass)
		4 (Parent Item)
		5 (Parent/Diff Item)
		6 (Transaction Item)
		8 (All Departments)
offer condition merchandise	dept	0 .. n	Department ID.	Integer
offer condition merchandise	class	0 .. n	The non-unique class ID value.	Integer
offer condition merchandise	uniqueclass	0 .. n	The unique class ID value.	Integer
offer condition merchandise	subclass	0 .. n	The non-unique subclass ID value.	Integer
offer condition merchandise	uniquesubclass	0 .. n	The unique subclass ID value.	Integer
offer condition merchandise	item	RMS Item Identifier	Item ID.	String
offer condition merchandise	diffid	RMS Differentiator Identifier	Differentiator ID.	String
offer condition merchandise	excludeind	0 (No)	The exclude indicator.	Integer
		1 (Yes)
offer condition merchandise	canceldatetime	ISO-8601 Date and Time	Date and time when condition merchandise was cancelled.	Timestamp
promotion offer (item)	rewards	entity list	Rewards associated with the offer.	List
offer reward	rewardid	0 .. n	Reward ID.	Integer
offer reward	changetype	0 (change by percent)	Type of change for the reward.	Integer
		1 (change by amount)
		2 (fixed price)
offer reward	changeamount	Localized decimal number	The change by amount or fixed price amount.	BigDecimal
offer reward	changepercent	Localized decimal number	Percentage value when change type is change by percent.	BigDecimal
offer reward	qtytodisc	Localized decimal number	The qty to discount.	BigDecimal
offer reward	qtytodiscuom	RMS UOM Identifier	UOM of the discount quantity.	String
offer reward	applyind	0 (Regular only)	The apply to indicator of the reward.	Integer
		1 (Clearance only)
		2 (Regular and Clearance)
offer reward	pricerestrictcode	B (Between)	Operator for price restriction.	String
		G (Greater Than)
		L (Less Than)
offer reward	pricerestrictvalue1	Localized decimal number	The first value of the price restriction.	BigDecimal
offer reward	pricerestrictvalue2	Localized decimal number	The second value of the price restriction. The second value is only used for between restrictrions.	BigDecimal
offer reward	rewardsmerch	entity list	Collection of merchandise eligible for reward.	List
offer reward merchandise	rewardmerchid	0 .. n	The unique id for the offer reward merch record.	Integer
offer reward merchandise	merchlevel	1 (Department)	The merchandise level.	Integer
		2 (Class)
		3 (Subclass)
		4 (Parent Item)
		5 (Parent/Diff Item)
		6 (Transaction Item)
		8 (All Departments)
offer reward merchandise	dept	0 .. n	Department ID.	Integer
offer reward merchandise	class	0 .. n	The non-unique class ID value.	Integer
offer reward merchandise	uniqueclass	0 .. n	The unique class ID value.	Integer
offer reward merchandise	subclass	0 .. n	The non-unique subclass ID value.	Integer
offer reward merchandise	uniquesubclass	0 .. n	The unique subclass ID value.	Integer
offer reward merchandise	item	RMS Item Identifier	Item ID.	String
offer reward merchandise	diffid	RMS Differentiator Identifier	Differentiator ID.	String
offer reward merchandise	excludeind	0 (No)	The exclude indicator.	Integer
		1 (Yes)
offer reward merchandise	canceldatetime	ISO-8601 Date and Time	Date and time when merchandise reward was cancelled.	Timestamp
offer reward merchandise	suppliersite	text description	Supplier site associated with the item	String
offer reward merchandise	brandname	text description	Brand name associated with the item	String
promotion offer (item)	locations	entity list	Locations associated with the offer.	List
location	action	NO_CHANGE	Recommended action based on how data has changed since a point in time.	String
		DELETE
		UPSERT
		INSERT
		UPDATE
location	location	0 .. n	Location for promotion.	Integer
location	canceldatetime	ISO-8601 Date and Time	Date time promotion was cancelled for this location.	Timestamp
item/loc page	hasMore	TRUE	Boolean flag to indicate if more data is available.	Boolean
		FALSE
item/loc page	limit	0 .. n	Maximum number of records to return in a single request.	Integer
item/loc page	count	0 .. n	Count of records returned in the response. This will be less than or equal to the limit value.	Integer
item/loc page	links	entity list	List of related links.	List
link	rel	self	self: The calling URL.	String
		next	next: Only present if the hasMore flag is trueLink to the next page of data. Applications should the value of the href element to access the next page of data. This url contains a server generated offsetkey parameter to identify the start of the next page.
		describedBy	describedBy: Link to the metadata catalog.
link	href	URL	The related URL.	String