ReturnItemAdd URL

This URL adds products to a return merchandise authorization (RMA).

URL structure

http:// host_name/path/
The fully qualified name of your WebSphere Commerce Server and the configuration path.

osrtnitad

Parameter values

forUser
The logon ID of the user on whose behalf the command will be run; only a person with the authority to process orders can specify this parameter.
forUserId
Same as forUser, but identifying the user by the internal user ID, as found in the USERS table.
creditAdjustment_ i
The amount by which to adjust the product credit amount. The format of this number must fit the rules for a java.math.BigDecimal object. The number must use a period for a decimal place. This amount is placed in the ADJUSTMENT column of the RMAITEM table. This parameter is optional and only valid if the forUserId parameter is specified.
langId
Sets or resets the preferred language for the duration of the session; the supported languages for a store are found in the STORELANG table.
storeId
Required: The store reference number.
orderItemId_ i
Required: The OrderItem ID, if available. To return a component that is not part of a dynamic or static kit, or the entire kit from an OrderItem, a value must be specified for this parameter. To return a part of a dynamic or static kit that has an OrderItem, a value must be specified for this parameter and the catEntryId_ i parameter.
catEntryId_ i
Required: The catalog entry being returned. This value must be either a product or an item. Other catalog entry values are not supported and will call a BAD_MISSING_CMD_PARAMETER exception. To return a component that is not an OrderItem, a value must be specified for this parameter. To return a part of a dynamic or static kit that has an OrderItem, a value must be specified for this parameter and the orderItem_ i parameter.
attrName_ i
Any distinct attribute defined for the product.
attrValue_ i
The value of the product attribute.
RMAId
Required: The identifier of an existing RMA that the return items are to be added to. To create a new RMA, use "**" as the value. If a value is not specified for this parameter, ** is used as the default.
quantity_ i
Required: The quantity being returned.
UOM_ i
The unit of measure for quantity_i. This value should match one of the primary keys in the QTYUNIT table. When it is not specified, then the value of the QUANTITYMEASURE column of the CATENTSHIP table for the row with the same CATENTRY_ID as the OrderItem is used, and the value of the quantity_i parameter is multiplied by the NOMINALQUANTITY column of the same row in the CATENTSHIP table.
comment_ i
A comment about the item being returned.
reason_ i
Required: The reason for the return, as provided by the purchaser. This value can be found in the CODE column of the RTNREASON table with reason type in 'B' or 'C'.
outRMAName
The name to use for the name-value pair which will be passed to the redirected URL. This parameter is useful for chaining commands. If this parameter is not specified, then the value RMAId is used.
URL
Required: The URL to be called when the command completes successfully.

Example

The following example adds 5 units of order item 15 to a new RMA. The reason code for the return is DEFECT. After the RMA is created it is displayed. 


http://myhostname/webapp/wcs/stores/servlet/
ReturnItemAdd?;orderItemId_1=15&quantity_1=5&reason_1=DEFECT&RMAId=**&storeId=1;&URL=ReturnDisplay

Behavior

  • If RMAId is set to "**", create a new RMA. The currency of the new RMA is set to the currency of one of the return items that is based on an order item. If there is no order item being returned (that is, only catalog entries are returned) then the currency is set to the shopping currency of the caller. The trading Id of the new RMA is set to the trading Id of one of the returned order items. If no order item is being returned then the first trading Id found in the command context (method getCurrentTradingAgreements()) is used. The memberId of the RMA is set to the user Id in the command context.
  • If the RMAId is not set to "**", open the existing RMA and verify that it belongs to the current store.
  • The PREPARED flag of the RMA is set to 'N'.
  • If either the forUser or the forUserId parameter is specified, the RMA must start in status 'EDT', 'PND', 'APP' and the status is set to 'EDT'. Otherwise, the RMA must start in status 'PRC' and the status is changed to 'PRC'.
  • The command can be called with a list of OrderItems and catalog entries. Each will be processed in the following way:
    • If the OrderItem to be added to the RMA, the following happens:
      1. Calls the CheckReturnItemInCorrectStateCmd task command to verify that the order item is in a returnable state.
      2. Checks that currency of the OrderItem is the same as the currency of the RMA.
      3. Checks that the trading Id of the order item is the same as the trading Id of the RMA.
      4. Checks that there are returns terms and conditions for this order item.
      5. Checks that the terms and conditions associated with the trading Id and member Id of the order item are compatible with the terms and conditions associated with the RMA (the same terms and conditions). The terms and conditions associated with the RMA are calculated using the trading id of the RMA and the memberId of an existing returned order item or the memberId of the RMA (if all existing returned items are catalog entries).
      6. If catEntryId is specified (a partial kit return) then call the task command ResolveSkuCmd to resolve the catalog entry ID and item spec ID.
      7. If this is a partial kit return then call task command CalculateReturnItemCreditForCatEntryCmd otherwise call task command CalculateReturnItemCreditCmd.
      8. Adds an item to the RMA and explodes the RMA item into the RMA item components. If this is a kit then create the component records from the OICOMPLIST table associated with the order item. Otherwise one component is created for the returned item.
    • If the category entry is to be added to the RMA, the following happens:
      1. Calls the task command ResolveSkuCmd to resolve the catalog entry ID and item spec id.
      2. The currency of the returned item is set to the currency of the RMA.
      3. Calls the CalculateReturnItemCreditForCatEntryCmd task command to calculate the credit amounts.
  • For all items, the task command AutoApproveReturnItemCmd is called to see if the item can be automatically approved. The returned item will be set to status 'PND' or 'APP' based on the automatic approval.
  • Units of measure are handled similar to the OrderItemAdd command. The quantity with the units of measure specified will be converted to a normalized quantity that is a multiple of the nominal quantity specified in the CATENTSHIP table.
  • To return a component that is not part of a dynamic or static kit, or the entire kit from an OrderItem, the command takes the value for the orderItemId_ i parameter and adds an entry to the RMAITEM table and adds multiple entries to the RMAITEMCMP table, for a kit, or one entry to the RMAITEMCMP table otherwise. When the components of a kit are being added to the RMAITEMCMP table, those components marked as optional (REQUIRED column of the OICOMPLIST table set to 'N') are not recorded.
  • To return a part of a dynamic or static kit that has an OrderItem, the command takes the values for the orderItemId_ i parameter and the catEntryId_ i parameter and adds an entry to the RMAITEM table and an entry to the RMAITEMCMP table.
  • To return a component that is not an OrderItem, the command takes the values for the catEntryId_ i parameter and adds an entry to the RMAITEM table and an entry to the RMAITEMCMP table.
  • Only catalog entries that are products or items can be returned.
  • On successful completion, set up to redirect to the specified URL.
  • Call the task command ExtendReturnItemAddCmd.

Exception conditions

  • If the currency of the order item is not the same as the currency of the RMA, an ECApplicationException is generated with message _ERR_ITEM_RMA_CURRENCY_MISMATCH.
  • If the order item is not in the correct state, determined by the CheckReturnItemInCorrectStateCmd task command then an ECApplicationException is generated with message _ERR_ORD_ITEM_NOT_RETURNABLE.
  • An ECApplicationException is raised with message _ERR_RMA_ININVALID_STATE_FOR_COMMAND in the following circumstances:
    • If neither the forUser nor forUserId parameter is specified, and the RMA status is not set to 'PRC'
    • If either of the parameters, forUser or forUserId is specified and the RMA status is not set to 'EDT', 'PND' or 'APP'.
  • If the trading Id of the order item is not the same as the trading Id of the RMA, an ECApplicationException is generated with message _ERR_ITEM_RMA_TRADING_MISMATCH.
  • If there are no returns terms and conditions for this order item then an ECApplicationException is generated with message _ERR_NO_RETURN_TERMCOND.
  • If the terms and conditions of the order item are different than the terms and conditions associated with the RMA then an ECApplicationException is generated with message _ERR_ITEM_RMA_TERMS_MISMATCH.