OrderItemAdd URL
Add items or products to the list of items that are to be shipped.
URL
OrderItemAdd
Controller command
com.ibm.commerce.orderitems.commands.OrderItemAddCmd
Implementation class
com.ibm.commerce.orderitems.commands.OrderItemAddCmdImpl
Commands called
URL structure
- http://host_name/path/
- The fully qualified name of your Transaction server and the configuration path.
Parameter values
- forUser
- The logon ID of the user on whose behalf the command is 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.
- langId
- Sets or resets the preferred language during the session. The supported languages for a store are found in the STORELANG table.
- URL
- Required: The URL to be called when the command completes successfully.
- storeId
- Required: The store reference number, which is mandatory because you cannot buy from a mall.
- catEntryId_i
- Required: The reference number of the items to be put into the order. This parameter is required if the customer does not have a shopping cart. It is not required if a customer order exists.
- partNumber_i
- If this parameter is specified, then the catEntryId parameter is ignored. The partNumber and memberId parameters are used to determine a catentry_id by selecting PARTNUMBER and MEMBER_ID in the CATENTRY table. This command applies the reference number to the value for catEntryId.
- expandConfigurationId_ i
- If this parameter is specified, then add an order item for each component that is identified by this parameter whose orderItemId attribute is null.
- memberId_i
- The identifier for the member that owns the catalog where the order will be placed. To achieve compatibility with previous versions of HCL Commerce, set memberID to *storeOwner. This value specifies the memberID of the owner of the current Store object.
- attrName_i
- Any distinct attribute that is defined for the item. This parameter can be repeated.
- attrValue_i
- The value of the attribute in attrName. This parameter can be repeated.
- quantity_i
- Required: The quantity of the item to be added to the order.
- UOM_i
- The unit of measure for quantity_i. This value should match one of the primary keys in the QTYUNIT table. When not specified, the value of the QUANTITYMEASURE column of the CATENTSHIP table for the row with the same CATENTRY_ID as the OrderItem is used. The value of the quantity_i parameter is multiplied by the NOMINALQUANTITY column of the same row in the CATENTSHIP table.
- addressId_i
- The reference number of the address to which the products and items are shipped.
- shipModeId_i
- The reference number of the shipping mode to be used for the product or item.
- comment_i
- A comment to be included with the created or updated ordered items.
- contractId_i
- The identifier of the contract that governs the order to which the item is being added. There is one default contract for each store but you can set up others. This parameter can be repeated.
- field1_i
- A store-reserved integer value.
- field2_i
- A store-reserved text value. This parameter accepts up to 254 characters.
- offerId_i
- The identifier of the offer that governs the order to which the item is being added. This parameter can be repeated.
- orderId
- The identifier of the order to which the item is being added. This parameter can be repeated.
- outOrderName
- Specifies the names of the reference numbers of the created or updated orders to be added to the redirection URL. Use this parameter and outOrderItemName when chaining commands. This parameter can be repeated.
- outOrderItemName
- The names of the reference numbers of the created or updated order items to be added to the redirection URL. This parameter can be repeated.
- listId
- The interest item list ID. When you specify this parameter, the OrderItemAdd command creates an order that contains all the items in the list.
- orderDesc
- Specifies the order description for a new order that is created by this command.
- continue
- Controls whether the order-item addition continues when one or more of the order items cannot be created or updated. A value of 0 terminates and rolls back execution if an order item cannot be created or updated in the target order. A value of 1 ignores the create or update operation for that order item and continues execution. The default value is 0.
- orderComment
- Sets the order comment if specified.
- remerge
- A list of the OrderItems that should be merged with other OrderItems in the same order and with the same correlationGroup attribute, if possible. OrderItems are not merged unless their InventoryStatus is "NALC", or they are specified by one or more of the allocate, backorder, and reverse parameters. This parameter can be repeated.
- merge
- A list of OrderItems that should be merged with other OrderItems in the same order if possible, regardless of their correlationGroup attributes. OrderItems are not merged unless their InventoryStatus is "NALC", or they are specified by one or more of the allocate, backorder, and reverse parameters. This parameter can be repeated.
- check
- A list of OrderItems that should be checked by the CheckInventory task command. This parameter can be repeated.
- allocate
- A list of OrderItems that should be allocated from existing inventory by the AllocateExistingInventory task command. This parameter can be repeated.
- backorder
- A list of OrderItems that should be backordered, by the AllocateExpectedInventory task command. If the same OrderItem is specified by both the allocate and backorder parameters, it is not backordered if it can be allocated. This parameter can be repeated.
- reverse
- A list of OrderItems whose allocations should be released (de-allocated from existing or expected inventory as appropriate) by calling the DeallocateExistingInventory or DeallocateExpectedInventory task commands. This parameter can be repeated.
- configurationId_i
- If the OrderItem represents a configured Dynamic Kit, this value represents the configuration ID. This parameter can be repeated.
- correlationGroup_i
- The group to which this OrderItem is related. Normally, the correlationGroup is the same as the OrderItemID. OrderItems with the same correlationGroup attribute value represent the same object that the customer wants to buy. A value for correlationGroup can be specified and propagated when either OrderItems are split (by fulfillment center, for example) when inventory is allocated, or when a price quotation is received for an OrderItem. When an OrderItem is split at inventory allocation, the newly created OrderItem inherits the correlationGroup value from the original OrderItem. In a quotation situation, the OrderItem inherits the correlationGroup value from the corresponding OrderItem in the parent order.
- expandConfigurationId_i
- Add multiple OrderItems, one for each component that is identified by expandConfigurationId_ i whose orderItemId attribute is null.
- orderComment
- Sets the order comment attribute.
- isExpedited_i
- The default value is N. If value is set to Y, the orderitem is marked as EXPEDITED.
- calculateOrder
- The default value is 0. If value is 1, OrderCalculateCmd is called to calculate the charges for the order. If the value is 0, Order charges are not calculated in this command.
- requestedShipDate_i
- Marks the requested shipping date for an orderitem.
- shipInstructions_i
- Specifies shipping instructions for one shipmode.
- shipChargTypeId_i
- Results in shipping charge policy, charge by carrier or charge by merchant.
- shipCarrAccntNum_i
- The shipping carrier account number.
- externalId_i
- The unique gift registry external identifier.
- giftMessage_i
- A message that is provided by the gift giver to the gift registrant.
- shipToRegistrant_i
- Specifies where gifts should be delivered. A value of 1 indicates that gifts are shipped directly to the gift registrant, using the address that is provided during gift registry profile creation.
- doPrice
- Specifies whether or not to perform the price calculation subtasks. Set to either do the price tasks (Y), or not (N). Turning off these tasks might result in better performance, but customers might not get the most current price, or product entitlement, when changes occur.
- doInventory
- Specifies whether the command should perform the inventory calculation subtasks. Set to either do the price tasks (Y), or not (N). Turning off these tasks might result in better performance, but customers might not get the most current inventory level, when changes occur.
For more information about the task commands that are called by OrderItemAdd URL see OrderItemBaseCmdImpl.
remerge
, merge
, check
, allocate
, backorder
, and reverse
parameters are applicable only if ATP
inventory is enabled (see the STORE.INVENTORYSYSTEM column in the STORE table). They represent lists
of OrderItems that are passed to the DoInventoryAction task command. This command invokes
AllocateInventory, which calls CheckInventoryAvailability, AllocateExistingInventory, AllocateExpectedInventory, DeallocateExistingInventory, and DeallocateExpectedInventory as specified in the following list. Also, these
parameters accept OrderItem abbreviations, which are detailed in the help for Order Management subsystem URLs.- remerge=*n
- merge=*n
- check=***
- allocate=*n
- backorder=*n
- reverse=*n
- If orderitem is not associated with a gift registry and the shipToRegistrant_ i is set to 1, an exception is thrown.
Multiple items at one transaction
The command can handle multiple items at one transaction. The multiple items are specified using the enumeration group 'i'. If you want to update multiple order items, you can specify orderItemId_i as parameters. For example, i can be 1, 2, or 3. For more information about handling multiple items, see OrderItemAddCmd.
Example 1
The following example adds three units of the product with reference number 24 to each of the customer's current pending orders that are created under the store that carries catalog entry 24. The example indicates that they are to be shipped to the address with reference number 2, and then calls the OrderItemDisplay command.
http://myhostname/webapp/wcs/stores/servlet/OrderItemAdd?addressId=2
&URL=/webapp/wcs/stores/servlet/OrderItemDisplay&catEntryId=24&quantity=3
Example 2
The following example adds ten units of the catalog entry with reference number 2 to the current customer's new order. The parameter orderId is added to the redirection URL; its value is the reference number of the created order, and the OrderItemDisplay command is called.
http://myhostname/webapp/wcs/stores/servlet/OrderItemAdd?catEntryId=2&quantity=10
&orderId=**&outOrderName=orderId&URL=/webapp/wcs/stores/servlet/OrderItemDisplay
Example 3
- Item 312200001
- Item 312200301
- Product 312200200 with attribute 312200201
http://myhostname/webapp/wcs/stores/servlet/OrderItemAdd?catEntryId_1=312200001
&quantity_1=1&shipModeId_1=1&catEntryId_2=312200301&quantity_2=1
&shipModeId_2=1&catEntryId_3=312200200&attrName_3=312200201
&attrValue_3=Value+2200200+1&quantity_3=1&shipModeId_3=1&URL=OrderItemDisplay
Example 4
http://myhostname/webapp/wcs/stores/servlet/OrderItemAdd?catEntryId_1=111&attrName_1=1
&attrValue_1=a&attrName_1=2&attrValue_1=b&quantity_1=1&catEntryId_2=222&attrName_2=21
&attrValue_2=aa&attrName_2=22&attrValue_2=bb&attrName_2=33&attrValue_2=cc&quantity_2=1
&URL=OrderItemDisplay
Behavior
Check if the order is locked by the current CSR. If the order is not locked and called by a CSR, or if it is locked by another CSR, an exception is thrown.
Call ResolveSkuCmd (catalog command) to resolve the SKU and check if the catalog entry is buyable in this store.
Call ResolveOrdersCmd to resolve order IDs. If no order is resolved, then call OrderCreateCmd to create an order.
Create an order item with the information if passed in: catEntryId/partNumber, requestedShipDate, isExpedited, quantity, correlationGroup, comments, orderDesc, field1, field2, and all other parameters.
Copy specified wish list items to order items
Update comments, description, and shipAsComplete for the order
- Call ResolveOrderItemPriceCmd to calculate the best price and update order total
- Pass in parameter doPrice to ResolveOrderItemPriceCmd to control whether the OrderItems can skip pricing again
- Call UpdateShippingAddressCmd to update shipping address
- Update shipping mode
- Call ValidateTradingPaymentCmd to validate that the payment method is compatible with the trading agreement
- If doInventory = Y, call DoInventoryActionCmd to update the fulfillment centers and check for available inventory
- Call UpdateShipInfoCmd to update the shipping instructions, shipping account number and shipping charge type
- Call RaiseOrderEventCmd to raise ORDERITEM_CREATION_EVENT or ORDERITEM_UPDATE_EVENT
- If the flag calculateOrder is set:
- Call OrderCalculateCmd to do calculations that are based on the calUsageIds passed in
- Call ExtendOrderItemProcessCmd to execute any customization logic
You can customize your add to cart process to
prevent shoppers from adding out of stock items to their carts when your store uses a DOM inventory
model. The add to cart process when a DOM inventory model is used includes an empty command
(DOMValidateInventoryStatusCmd
) that you can use in a customization to check the
inventory status for an item in the ORDERITEMS.INVENTORYSTATUS database column. If the inventory is
not allocated (value of NALC) have you implementation of the command throw an exception to prevent
the item from being added to the cart.
Exception conditions
Different exception tasks are called depending on the error.
- If any parameter value is invalid, the command throws an ECApplicationException with message: _ERR_INVALID_INPUT and error view: InvalidInputErrorView.
- If the partNumber is specified but it cannot be found in the catalog, the command throws an ECApplicationException with message: _ERR_PROD_NOT_EXISTING and error view: badPartNumberErrorView.
- ECApplicationException is also thrown if the following errors are encountered:
- Input trading agreements are not valid or eligible to use.
- Trading agreements used in the order applies incompatible payment methods.
- Price Lists cannot be retrieved
When checking inventory for a non-ATP store, if sufficient inventory is on hand, the inventory check passes. Otherwise, the check fails. If the check fails, ECApplicationException is thrown from ResolveFulfillmentCenterCmd with message: _API_CANT_RESOLVE_FFMCENTER and error view: ResolveFulfillmentCenterErrorView, unless the continue parameter is specified as 1.
When checking inventory for an ATP store, the inventory check passes if either the current inventory or expected inventory is sufficient. In cases where both are insufficient and the base item cannot be back ordered in this store (refer to STOREITEM table), or the item specification was discontinued (refer to ITEMSPC table), the inventory check fails and ECApplicationException is thrown from CheckInventoryAvailabilityCmd with message: _API_BAD_INV and error view: CheckInventoryErrorView.
- If there is more than one CatalogEntry object, the partnumber is ambiguous.
ECApplicationException is thrown specifying the ERR_PROD_NOT_EXISTING error message. Error
name-value pairs are passed as follows:
- multiplePartNumberList specifies the ambiguous part numbers
- multiplePartNumberQuantityList specifies the corresponding requested quantities, one for each ambiguous part number
- multiplePartNumberCatalogEntriesList specifies vectors of CatalogEntry identifiers, one for each ambiguous part number. Each vector contains a list of CatalogEntry identifiers of CatalogEntry objects that have the ambiguous part number.
- If an orderitem is not associated with a gift registry and the shipToRegistrant_ i is set to 1, an exception is thrown.