Franchise Management
The following services are included in this functional area:
Customer Credit Status Upload Service
The following services are included in this functional area:
Update Customer Credit Status
Business Overview
This service provides a way for an external source, usually a financials system, to update the credit status for a franchise customer in Merchandising. This status is used when determining whether a franchisee order can be approved. Valid values are Y (credit is good) and N (credit issues). For each collection of customer and customer group passed into the service, the credit flag will be updated with the value indicated in the service call.
Merchandising returns failure status as part of the response object in the web service call if credit flag is not updated due to validation errors.
This service supports a collection of record to be submitted. The service either processes all the records or rejects all the record if there is a one or more bad record.
Input Payload Details
Table 5-138 Update - Object. See list of elements for detail
Element Name | Required | Data Type | Description |
---|---|---|---|
collectionSize |
Yes |
Number (4) |
Number of items in the collection. This should match with the number of records in the input message. |
items |
No |
Collection of Object |
Collection of Customer records. |
Table 5-139 Items - Object. See list of elements for detail
Element Name | Required | Data Type | Description |
---|---|---|---|
customerId |
Yes |
Number (10) |
The unique customer identifier. |
customerGroupId |
Yes |
Number (10) |
Customer Group to which the customer belongs to. |
creditInd |
Yes |
String (1) |
Determine if the customer has good credit. valid values 'Y' and 'N'. |
Sample Input Message
{
"collectionSize": 1,
"items": [
{
"customerId": 10061,
"customerGroupId": 1006,
"creditInd": "Y"
}
]
}
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"
]
}
Franchise Order Upload Service
The following services are included in this functional area:
Create Franchise Orders
Business Overview
Deprecated in v24.1.301.0: Scheduled for Removal in 2 Years.
Use MerchIntegrations/services/franchiseManagement/franchiseOrder/manage
This service is used from an external source, usually an order management system, to create franchise orders in Merchandising. This service accepts a collection of franchise order and will return success or failure through the service response object. The franchise order uploaded through this service will be created with an order type of 'EDI'. A linked transfer, PO or store order will be created for the approved franchise orders.
Franchise orders created via this service will be systematically approved if the customer is setup for auto approval, provided the customer has valid credit. If the order does not meet the criteria for auto-approval, Merchandising will create the franchise order in Input or Require Credit Approval and will provide the reason of approval failure in the response object. Franchise orders from customers that are not identified for 'Auto Approval' are uploaded into Merchandising in Input status. Such orders will need to be manually approved in Merchandising to be considered active.
The service allows upload of one or more franchise orders in a single service call. Each request is treated as a single unit of work and if there are no validation errors or business validation errors, all the franchise orders in the message will be created and the service will return success through the service response object. In case of one or more validation errors, the service call will be rejected, and the error response will contain the details of the validation errors.
Item Validation
-
Packs are allowed for warehouse sourced or supplier sourced franchise orders only. If the pack added is a buyer pacwith an 'order as' type of eaches, then the pack is exploded to its components.
-
Deposit container items cannot be added to franchise orders. When the deposit content item is added to an order, the associated container item gets added as well. Deposit item content and container items must have the same costing location.
-
Transformable orderable items can be added to an order, however, transformable sellable items are not allowed, as these are not inventoried.
-
There cannot be multiple detail record for the same source location/item/customer location combination within a franchise order.
-
Multiple order detail lines with the same source location, item and customer location combination in the franchise order is not allowed.
Source Validations
-
For supplier sourced orders, the supplier must be an active supplier and allows direct store deliveries.
-
For supplier sourced franchise order, items must be 'Active' at the franchise store in order to be included on the order.
-
The supplier must belong to the same org unit as the costing location.
-
For warehouse or company store sourced order, the items must not be in 'Delete' status at the source location and must be in either 'Active' or 'Discontinued' status at the franchise store.
-
If the source for franchise order is not specified, then the costing location for the item and franchise store will be used as the source location.
-
If the source location is a physical warehouse, then the service will use distribution rules to determine from which virtual warehouse the inventory will be pulled, similar to distribution rules used for non-franchise transfers.
Customer Location Validation
-
If item/franchise store relationship does not exist, the franchise store would be auto ranged as part of franchise order creation.
-
For source location as a store, the customer store cannot be non-stockholding.
-
When a franchise order is uploaded through this service, having a future cost record for the item/franchise store combination is not necessary. Whether or not the cost template relationship is defined for the item/franchise store, the order can still be approved based on the provided fixed cost. However, if the fixed cost is also not provided, then the order creation would fail.
Inventory Validations
The inventory validation for Franchise orders sourced from company locations is subject to the setting of the 'Validate Availability for External Franchise Orders' system option. If set to No, Franchise Order creation would be carried out without checking for inventory availability. If set to Yes, then the requested quantity is validated against the available inventory at location for the warehouse or store sourced franchise orders. For the warehouse sourced orders, if the requested quantity exceeds the available stock at the warehouse, then Merchandising checks whether the item is on the Store Order replenishment at the same sourcing warehouse for the franchise store. If so, then an order is placed for the sourcing warehouse from the supplier for the unavailable quantity and the sourcing for the franchise location is handled via transfers created through Merchandising replenishment process. When the source location is a store, requested inventory must be available at the location.
Order Date Validations
-
Multiple franchise orders with the same source location, item, customer location and need date combination are not allowed in Merchandising.
-
For the supplier sourced franchise orders, the not after date must be greater than supplier lead time.
-
For the warehouse sourced franchise orders, if the franchise order has a need date that is less than the order lead days in the future, the franchise order is fulfilled with the available warehouse inventory. Any remaining is fulfilled via Store Order replenishment if the item is on Store Order replenishment at the same sourcing warehouse for the franchise store.
-
For store sourced franchise orders, the need date must be within order lead days.
Item Validation
-
Packs are allowed for warehouse sourced or supplier sourced franchise orders only. If the pack added is a buyer pacwith an 'order as' type of eaches, then the pack is exploded to its components.
-
Deposit container items cannot be added to franchise orders. When the deposit content item is added to an order, the associated container item gets added as well. Deposit item content and container items must have the same costing location.
-
Transformable orderable items can be added to an order, however, transformable sellable items are not allowed, as these are not inventoried.
-
There cannot be multiple detail record for the same source location/item/customer location combination within a franchise order.
-
Multiple order detail lines with the same source location, item and customer location combination in the franchise order is not allowed.
Source Validations
-
For supplier sourced orders, the supplier must be an active supplier and allows direct store deliveries.
-
For supplier sourced franchise order, items must be 'Active' at the franchise store in order to be included on the order.
-
The supplier must belong to the same org unit as the costing location.
-
For warehouse or company store sourced order, the items must not be in 'Delete' status at the source location and must be in either 'Active' or 'Discontinued' status at the franchise store.
-
If the source for franchise order is not specified, then the costing location for the item and franchise store will be used as the source location.
-
If the source location is a physical warehouse, then the service will use distribution rules to determine from which virtual warehouse the inventory will be pulled, similar to distribution rules used for non-franchise transfers.
Customer Location Validation
-
If item/franchise store relationship does not exist, the franchise store would be auto ranged as part of franchise order creation.
-
For source location as a store, the customer store cannot be non-stockholding.
-
When a franchise order is uploaded through this service, having a future cost record for the item/franchise store combination is not necessary. Whether or not the cost template relationship is defined for the item/franchise store, the order can still be approved based on the provided fixed cost. However, if the fixed cost is also not provided, then the order creation would fail.
Inventory Validations
The inventory validation for Franchise orders sourced from company locations is subject to the setting of the 'Validate Availability for External Franchise Orders' system option. If set to No, Franchise Order creation would be carried out without checking for inventory availability. If set to Yes, then the requested quantity is validated against the available inventory at location for the warehouse or store sourced franchise orders. For the warehouse sourced orders, if the requested quantity exceeds the available stock at the warehouse, then Merchandising checks whether the item is on the Store Order replenishment at the same sourcing warehouse for the franchise store. If so, then an order is placed for the sourcing warehouse from the supplier for the unavailable quantity and the sourcing for the franchise location is handled via transfers created through Merchandising replenishment process. When the source location is a store, requested inventory must be available at the location.
Order Date Validations
-
Multiple franchise orders with the same source location, item, customer location and need date combination are not allowed in Merchandising.
-
For the supplier sourced franchise orders, the not after date must be greater than supplier lead time.
-
For the warehouse sourced franchise orders, if the franchise order has a need date that is less than the order lead days in the future, the franchise order is fulfilled with the available warehouse inventory. Any remaining is fulfilled via Store Order replenishment if the item is on Store Order replenishment at the same sourcing warehouse for the franchise store.
-
For store sourced franchise orders, the need date must be within order lead days.
Availability During Nightly Batch Cycle
This service will not be available when batches affecting either inventory or cost are in-progress.
Input Payload Details
Table 5-140 Create - Object. See list of elements for detail
Element Name | Required | Data Type | Description |
---|---|---|---|
items |
Yes |
Collection of Object |
References a collection of franchise order creation details. |
Table 5-141 Items - Object. See list of elements for detail
Element Name | Required | Data Type | Description |
---|---|---|---|
customerId |
Yes |
Number (10) |
This value should be a valid customer id. |
orderReferenceNo |
Yes |
String (20) |
This is an external reference number that would be provided by the franchisee for their tracking purposes. |
currencyCode |
Yes |
String (3) |
This field represents the currency of the order, which may or may not be different from the primary currency in the system. Valid values for this field are based on the currency codes held in the CURRENCIES table. |
exchangeRate |
No |
Number (20,10) |
This field represents the exchange rate between the primary currency and the franchise order currency. If this is not provided, it is defaulted based on the conversion type set at system level. |
freight |
No |
Number (20,4) |
This field represents any freight charges associated to the franchise order. |
otherCharges |
No |
Number (20,4) |
This field represents other miscellaneous charges associated to the franchise order. |
defaultBillingLocation |
No |
Number (10) |
A customer's location where the billing for the entire order is sent. If blank, each location is billed. |
billToAddressType |
No |
String (2) |
This field represents the address type for the default billing location. This field is defaulted to Invoice address. |
comments |
No |
String (2000) |
Free form comments associated with the franchise order. |
details |
Yes |
Collection of Object |
Details of the orders. At least one detail item is mandatory. |
Table 5-142 Details - Object. See list of elements for detail
Element Name | Required | Data Type | Description |
---|---|---|---|
item |
Yes |
String (25) |
This is the item which is on the Franchise Order. This should be an approved, inventory, orderable and transaction level item. The item should be ranged to both customer location and source location and must not be a consignment/concession item. |
customerLocation |
Yes |
Number (10) |
This field holds a valid franchise location number. |
sourceLocationType |
No |
String (2) |
Contains the source entity type from where the items will originate. Valid values are ST - Store, WH - Warehouse, SU - Supplier. If this field is populated, the source location should also be populated. |
sourceLocation |
No |
Number (10) |
Contains the location id from where this item will be sourced from. The id will correspond to a company store, warehouse or supplier depending on the source type value. |
requestedQuantity |
Yes |
Number (12,4) |
This field represents the quantity of the item on this record being ordered. This value is always written in the standard UOM for the item. |
unitOfPurchase |
No |
String (3) |
This field contains the unit of purchase information. Must be the standard unit of measure or a valid pallet name/case name/inner name for the item/supplier. |
needDate |
Yes |
date |
This date represents the initial date by which the franchisee wants the item on this order. The date format should be YYYY-MM-DD. The need date can be business date (VDATE) or a date in future. |
notAfterDate |
Yes |
date |
This date represents the last date by which the franchisee will accept the item on this order. The date format should be YYYY-MM-DD. This date should be after need date. |
fixedCost |
No |
Number (20,4) |
This is a user defined cost which will override the customer cost for the item on this order if populated. This should be a positive numeric value. This must be provided if there are no cost templates associated with the item. |
Table 5-143 CreateError - Object. See list of elements for detail
Element Name | Required | Data Type | Description |
---|---|---|---|
customerId |
Yes |
Number (10) |
Input Customer Id |
orderReferenceNo |
Yes |
String (20) |
Input order reference number |
item |
No |
String (25) |
Input item |
customerLocation |
No |
Number (10) |
Input franchise location number |
sourceLocationType |
No |
String (2) |
Input source location type |
sourceLocation |
Yes |
Number (10) |
Input source location id |
errors |
Yes |
Array of String |
List of errors identified during business data processing of the request |
Sample Input Message
{
"items": [
{
"customerId": 1001,
"orderReferenceNo": "1001-A",
"currencyCode": "USD",
"exchangeRate": 52.5,
"freight": 23.5,
"otherCharges": 2.58,
"defaultBillingLocation": 100123,
"billToAddressType": "01",
"comments": "Franchise order 1001-A",
"details": [
{
"item": "104300083",
"customerLocation": 100123,
"sourceLocationType": "ST",
"sourceLocation": 909090,
"requestedQuantity": 9000,
"unitOfPurchase": "EA",
"needDate": "2001-12-31",
"notAfterDate": "2001-12-31",
"fixedCost": 95
}
]
}
]
}
Response Code: 200 (Success)
Table 5-144 CreateResponse - Object. See list of elements for detail
Element Name | Required | Data Type | Description |
---|---|---|---|
items |
No |
Collection of Object |
References a collection of franchise orders created. |
Table 5-145 CreateResponse.Items - Object. See list of elements for detail
Element Name | Required | Data Type | Description |
---|---|---|---|
franchiseOrder |
Yes |
Number (10) |
This is the unique identifier of the franchise order that is generated by Merchandising. |
customerId |
Yes |
Number (10) |
Input Customer Id |
orderReferenceNo |
Yes |
String (20) |
Input order reference number |
status |
Yes |
String (1) |
This contains the status in which the Franchise order was created. This can be I - Input or A - Approved. |
autoApproveErrors |
No |
Array of String |
This will be populated with the reason (like customer fails credit check) why the order could not be approved and ended up getting created in Input status. Using the UI, the franchise order should be approved after fixing the issue. |
transactions |
No |
Collection of Object |
References a collection of transfers or purchase orders created. |
Table 5-146 Transactions - Object. See list of elements for detail
Element Name | Required | Data Type | Description |
---|---|---|---|
customerLocation |
Yes |
Number (10) |
This field holds a valid franchise location number. |
sourceLocation |
Yes |
Number (10) |
Contains the location id from where this item will be sourced from. The id will correspond to a company store, warehouse or supplier depending on the source type value. |
sourceLocationType |
Yes |
String (2) |
Contains the source entity type from where the items will originate. Valid values are ST - Store, WH - Warehouse, SU - Supplier. If this field is populated, the source location should also be populated. |
needDate |
Yes |
date |
This date represents the initial date by which the franchisee wants the item on this order. The date format should be YYYY-MM-DD. The need date can be business date (VDATE) or a date in future. |
documentNo |
Yes |
Number (12) |
This contains the purchase order or transfer number created. |
documentType |
Yes |
String (1) |
This contains the document type generated. This can be P - Purchase Order or T - Transfer. |
Sample Response Message
{
"items": [
{
"franchiseOrder": 30001,
"customerId": 1001,
"orderReferenceNo": "1001-A",
"status": "A",
"autoApproveErrors": [
"null"
],
"transactions": [
{
"customerLocation": 100123,
"sourceLocation": 909090,
"sourceLocationType": "ST",
"needDate": "2001-12-31",
"documentNo": 22145453,
"documentType": "T"
}
]
}
]
}
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.
Table 5-147 CreateError - Object. See list of elements for detail
Element Name | Required | Data Type | Description |
---|---|---|---|
customerId |
Yes |
Number (10) |
Input Customer Id |
orderReferenceNo |
Yes |
String (20) |
Input order reference number |
item |
No |
String (25) |
Input item |
customerLocation |
No |
Number (10) |
Input franchise location number |
sourceLocationType |
No |
String (2) |
Input source location type |
sourceLocation |
Yes |
Number (10) |
Input source location id |
errors |
Yes |
Array of String |
List of errors identified during business data processing of the request |
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": [
{
"customerId": 1001,
"orderReferenceNo": "1001-A",
"item": "104300083",
"customerLocation": 100123,
"sourceLocationType": "ST",
"sourceLocation": 909090,
"errors": [
"Customer Location passed in franchise order is not a valid franchise store."
]
}
]
}
Manage Franchise Orders
Business Overview
This service is used from an external source, usually an order management system, to create and maintain (that is, update, delete and cancel) franchise orders in Merchandising. The service allows upload of one or more franchise orders in a single service call. Each request is treated as a single unit of work and if there are no validation errors or business validation errors, all the franchise orders in the message will be created/updated/deleted and the service will return success through the service response object. In case of one or more validation errors, the service call will be rejected, and the error response will contain the details of the validation errors.
Order Creation
Franchise orders created through this service will have an order type of EDI
. A linked transfer, PO or
store order will be created for the approved franchise orders.
Franchise orders created through this service will be systematically approved if the customer is set up for auto-approval, provided the customer has valid credit. If the order does not meet the criteria for auto-approval, Merchandising will create the franchise order in Input or Require Credit Approval and will provide the reason of approval failure in the response object. Franchise orders from customers that are not set up for auto-approval are uploaded into Merchandising in Input status. Such orders will need to be manually approved in Merchandising to be considered active.
Item Validation
-
Packs are allowed for warehouse sourced or supplier sourced franchise orders only. If the pack added is a buyer pack with an
order as
type ofeaches
, then the pack is exploded to its components. -
Deposit container items cannot be added to franchise orders. When the deposit content item is added to an order, the associated container item gets added as well. Deposit item content and container items must have the same costing location.
-
Transformable orderable items can be added to an order, however, transformable sellable items are not allowed, as these are not inventoried.
-
There cannot be multiple detail record for the same source location/item/customer location combination within a franchise order.
-
Multiple order detail lines with the same source location, item and customer location combination in the franchise order is not allowed.
Source Validation
-
For supplier sourced orders, the supplier must be an active supplier and allows direct store deliveries.
-
For supplier sourced franchise order, items must be
Active
at the franchise store in order to be included on the order. -
The supplier must belong to the same org unit as the costing location.
-
For warehouse or company store sourced order, the items must not be in
Delete
status at the source location and must be in eitherActive
orDiscontinued
status at the franchise store. -
If the source for franchise order is not specified, then the costing location for the item and franchise store will be used as the source location.
-
If the source location is a physical warehouse, then the service will use distribution rules to determine from which virtual warehouse the inventory will be pulled, similar to distribution rules used for non-franchise transfers.
Customer Location Validation
-
If item/franchise store relationship does not exist, the franchise store would be auto ranged as part of franchise order creation.
-
For source location as a store, the customer store cannot be non-stockholding.
-
When a franchise order is uploaded through this service, having a future cost record for the item/franchise store combination is not necessary. Whether or not the cost template relationship is defined for the item/franchise store, the order can still be approved based on the provided fixed cost. However, if the fixed cost is also not provided, then the order creation would fail.
Inventory Validations
The inventory validation for Franchise orders sourced from company locations is subject to the setting of the Validate Availability for External Franchise Orders system option. If set to No, Franchise Order creation would be carried out without checking for inventory availability. If set to Yes, then the requested quantity is validated against the available inventory at location for the warehouse or store sourced franchise orders. For the warehouse sourced orders, if the requested quantity exceeds the available stock at the warehouse, then Merchandising checks whether the item is on the Store Order replenishment at the same sourcing warehouse for the franchise store. If so, then an order is placed for the sourcing warehouse from the supplier for the unavailable quantity and the sourcing for the franchise location is handled through transfers created through the Merchandising replenishment process. When the source location is a store, requested inventory must be available at the location.
Order Date Validations
-
Multiple franchise orders with the same source location, item, customer location and need date combination are not allowed in Merchandising.
-
For the supplier sourced franchise orders, the not after date must be greater than supplier lead time.
-
For the warehouse sourced franchise orders, if the franchise order has a need date that is less than the order lead days in the future, the franchise order is fulfilled with the available warehouse inventory. Any remaining is fulfilled through Store Order replenishment if the item is on Store Order replenishment at the same sourcing warehouse for the franchise store.
-
For store sourced franchise orders, the need date must be within order lead days.
Order Updates
For franchise orders Input status, the Update action will support the updating of a franchise order header and the adding, updating, or deleting of a franchise order detail. Header level updates includes changes such as customer order reference no, freight, and other charges as well as requested quantity, fixed cost, need date, and not after date at the detail level. Besides this, billing address details such as default bill to location, and bill to address can be updated. A new item can be added, and an existing item can be deleted using a Update header level action and a detail level Create or Delete level action respectively.
For an Approved franchise orders, only the requested quantity and fixed cost can be updated via this service. When the requested quantity is decremented, a line level cancellation reason must be provided.
Order Deletes and Cancellations
A franchise order can be deleted by sending an Update action with the status of the order set to Delete (D
). Only orders in Input status can be deleted in Merchandising. If the user sends an Update action, with the status Delete
(D
) for a franchise order that is not in Input status, it will be treated as a cancellation and the quantity
on all the order lines will be set to zero. A warning will be logged for the process to indicate to the user that the order
was cancelled as opposed to being deleted.
Line level cancellations can be performed on approved franchise orders by using a header level action of Update and an
order detail level action of Update with either the cancelled quantity field populated with the quantity to be cancelled;
or with a header level action of Update and an order detail level action of Delete for the desired line, in which case the
entire open quantity on the line will be cancelled. As part of cancellation, franchise orders in Approved or In progress status
will get cancelled by providing the appropriate cancellation reason. Cancellation reasons are configured under the Franchise
Order Cancel Reasons (WFCO
) code type.
Input Payload Details
Table 5-148 Manage - Object. See list of elements for detail
Element Name | Required | Data Type | Description |
---|---|---|---|
collectionSize |
Yes |
Number (4) |
|
items |
Yes |
Collection of Object |
Table 5-149 Items - Object. See list of elements for detail
Element Name | Required | Data Type | Description |
---|---|---|---|
action |
Yes |
String (10) |
Contains the intended action for the franchise order. Valid values are CREATE, UPDATE and DELETE. |
franchiseOrder |
No |
Number (15) |
Contains a unique identifier for the franchise order. |
customerId |
No |
Number (10) |
Contains the numeric identifier of the customer requesting the franchise order. |
orderReferenceNo |
No |
String (20) |
This field holds the ID for the franchise order used in the external system. This a reference number that would be provided by the franchisee which will help in tracking the franchise order created in Merchandising (RMS). |
currencyCode |
No |
String (3) |
Contains the currency of the franchise order. |
exchangeRate |
No |
Number (20,10) |
Contains the exchange rate associated with the franchise order. |
freight |
No |
Number (20,4) |
Contains the freight charge associated with the franchise order. |
otherCharges |
No |
Number (20,4) |
Contains other miscellaneous charges associated with the franchise order. |
billToAddressType |
No |
String (2) |
Contains the address type of the default billing address of the billing location. |
defaultBillingLocation |
No |
Number (10) |
Contains the default billing location of the order. It will hold the customer's location where the billing for the entire order is sent. |
billToIndividualshipmentLocation |
No |
String (1) |
This field indicates if the franchise order is created for billing to individual shipment location. |
orderCancelReason |
No |
String (6) |
This field indicates the reason for order cancellation. |
comments |
No |
String (2000) |
Contains the comments associated with the franchise order. |
status |
No |
String (1) |
Contains the status of the franchise order. |
details |
No |
Collection of Object |
Details of the orders. At least one detail item is mandatory for header action CREATE otherwise ignored. |
Table 5-150 Details - Object. See list of elements for detail
Element Name | Required | Data Type | Description |
---|---|---|---|
action |
Yes |
String (10) |
Contains the intended action for the franchise order. Valid values are CREATE, UPDATE and DELETE. |
item |
Yes |
String (25) |
Contains the item on the franchise order. |
customerLocation |
Yes |
Number (10) |
Contains the franchise store requesting the item. |
sourceLocationType |
Yes |
String (2) |
Contains the source entity type from where the items will originate. Valid values are ST - Store, WH - Warehouse, SU - Supplier. |
sourceLocation |
Yes |
Number (10) |
Contains the location Id from where this item will be sourced from. |
requestedQuantity |
No |
Number (12,4) |
Contains the quantity of the item on this record being ordered. The value is in the mentioned UOP. |
unitOfPurchase |
No |
String (3) |
Contains the unit of purchase of the requested quantity. |
fixedCost |
No |
Number (20,4) |
Contains the cost which will be charged to the customer for the item on the franchise order instead of using pricing cost. |
needDate |
No |
date |
Contains the initial date by which the item is needed in the franchise store. |
notAfterDate |
No |
date |
Contains the last date after which the item may no longer be accepted for a franchise store. |
itemCancelReason |
No |
String (6) |
This field represents the reason an item was cancelled from the franchise order. The cancellation of the item record results in the reduction of the overall order quantity. |
Table 5-151 ManageError - Object. See list of elements for detail
Element Name | Required | Data Type | Description |
---|---|---|---|
customerId |
Yes |
Number (10) |
Input Customer Id |
orderReferenceNo |
Yes |
String (20) |
Input order reference number |
item |
No |
String (25) |
Input item |
customerLocation |
No |
Number (10) |
Input franchise location number |
sourceLocationType |
No |
String (2) |
Input source location type |
sourceLocation |
Yes |
Number (10) |
Input source location id |
errors |
Yes |
Array of String |
List of errors identified during business data processing of the request |
Sample Input Message
{
"collectionSize": 1000,
"items": [
{
"action": "CREATE",
"franchiseOrder": 584081,
"customerId": 1001,
"orderReferenceNo": "1001-A",
"currencyCode": "USD",
"exchangeRate": 52.5,
"freight": 23.5,
"otherCharges": 2.58,
"billToAddressType": "01",
"defaultBillingLocation": 100123,
"billToIndividualshipmentLocation": "Y",
"orderCancelReason": "NS",
"comments": "Franchise order 1001-A",
"status": "A",
"details": [
{
"action": "CREATE",
"item": "104300083",
"customerLocation": 100123,
"sourceLocationType": "ST",
"sourceLocation": 909090,
"requestedQuantity": 9000,
"unitOfPurchase": "EA",
"fixedCost": 95,
"needDate": "2001-12-31",
"notAfterDate": "2001-12-31",
"itemCancelReason": "ED"
}
]
}
]
}
Response Code: 200 (Success)
Table 5-152 ManageResponse - Object. See list of elements for detail
Element Name | Required | Data Type | Description |
---|---|---|---|
franchiseOrders |
Yes |
Collection of Object |
Table 5-153 FranchiseOrders - Object. See list of elements for detail
Element Name | Required | Data Type | Description |
---|---|---|---|
franchiseOrder |
Yes |
Number (10) |
|
customerId |
Yes |
Number (10) |
Input Customer Id. |
orderReferenceNo |
Yes |
String (20) |
Input order reference number. |
status |
Yes |
String (1) |
This contains the status in which the Franchise order was created. This can be I - Input or A - Approved. |
processedStatus |
Yes |
String (20) |
Status of the request action. |
autoApproveErrors |
No |
Array of String |
This will be populated with the reason (like customer fails credit check) why the order could not be approved and ended up getting created in Input status. Using the UI, the franchise order should be approved after fixing the issue. |
transactions |
No |
Collection of Object |
References a collection of transfers or purchase orders created. |
Table 5-154 Transactions - Object. See list of elements for detail
Element Name | Required | Data Type | Description |
---|---|---|---|
customerLocation |
Yes |
Number (10) |
This field holds a valid franchise location number. |
sourceLocation |
Yes |
Number (10) |
Contains the location id from where this item will be sourced from. The id will correspond to a company store, warehouse or supplier depending on the source type value. |
sourceLocationType |
Yes |
String (2) |
Contains the source entity type from where the items will originate. Valid values are ST - Store, WH - Warehouse, SU - Supplier. If this field is populated, the source location should also be populated. |
needDate |
Yes |
date |
This date represents the initial date by which the franchisee wants the item on this order. The date format should be YYYY-MM-DD. The need date can be business date (VDATE) or a date in future. |
documentNo |
Yes |
Number (12) |
This contains the purchase order or transfer number created. |
documentType |
Yes |
String (1) |
This contains the document type generated. This can be P - Purchase Order or T - Transfer. |
Sample Response Message
{
"franchiseOrders": [
{
"franchiseOrder": 584081,
"customerId": 1001,
"orderReferenceNo": "1001-A",
"status": "A",
"processedStatus": "CREATED",
"autoApproveErrors": [
"null"
],
"transactions": [
{
"customerLocation": 100123,
"sourceLocation": 909090,
"sourceLocationType": "ST",
"needDate": "2001-12-31",
"documentNo": 22145453,
"documentType": "T"
}
]
}
]
}
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 do not match the schema definition for this service. The element businessError
will be present if the payload passes schema validation but an exception is caught while processing
the business logic.
Table 5-155 ManageError - Object. See list of elements for detail
Element Name | Required | Data Type | Description |
---|---|---|---|
customerId |
Yes |
Number (10) |
Input Customer Id |
orderReferenceNo |
Yes |
String (20) |
Input order reference number |
item |
No |
String (25) |
Input item |
customerLocation |
No |
Number (10) |
Input franchise location number |
sourceLocationType |
No |
String (2) |
Input source location type |
sourceLocation |
Yes |
Number (10) |
Input source location id |
errors |
Yes |
Array of String |
List of errors identified during business data processing of the request |
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": [
{
"customerId": 1001,
"orderReferenceNo": "1001-A",
"item": "104300083",
"customerLocation": 100123,
"sourceLocationType": "ST",
"sourceLocation": 909090,
"errors": [
"Customer Location passed in franchise order is not a valid franchise store."
]
}
]
}