Franchise Management

The following services are included in this functional area:

• Customer Credit Status Upload Service

  • Update Customer Credit Status

• Franchise Order Upload Service

  • Create Franchise Orders

  • Manage Franchise Orders

Customer Credit Status Upload Service

The following services are included in this functional area:

• Update Customer Credit Status

Update Customer Credit Status

Functional Area

Franchise Management

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.

Service Type

PUT

ReST URL

MerchIntegrations/services/franchiseManagement/customerCreditStatus/update

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

• Manage Franchise Orders

Create Franchise Orders

Functional Area

Franchise Management

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.

Service Type

POST

ReST URL

MerchIntegrations/services/franchiseManagement/franchiseOrder/create

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

Functional Area

Franchise Management

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 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 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 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 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.

Service Type

PUT

ReST URL

MerchIntegrations/services/franchiseManagement/franchiseOrder/manage

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."
      ]
    }
  ]
}