This command adds items or products to the list of items that are to be shipped.
Command structure
- http://host_name/path/
- The fully qualified name of your WebSphere Commerce Server and the configuration path.
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.
- 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.
- 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 already exists.
- partNumber_i
- If 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, and this command behaves as if that reference number was specified as the value for catEntryId.
- expandConfigurationId_i
- If specified, then add an OrderItem for each component 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.
- 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 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.
- 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 governing 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 governing 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 will create a new order which contains all the items in the list.
- orderDesc
- Specifies the order description for a new order 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 (that is, de-allocated from existing or expected inventory as appropriate) by calling the DeallocateExistingInventory or DeallocateExpectedInventory task commands as appropriate. This parameter can be repeated.
- configurationId_i
- If the OrderItem represents a configured Dynamic Kit, this is 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 the customer wants to buy. A value for correlationGroup can be specified and propagated when either OrderItems are split when inventory is allocated (such as when two fulfillment centers must be used to fill an order for the same item if one fulfillment center has insufficient supply), 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.
Note: The remerge, merge, check, allocate, backorder and reverse parameters are applicable only if ATP inventory is enabled (see the ALLOCATIONGOODFOR column in the STORE table). They represent lists of OrderItems that will be passed to the AllocateInventory task command, which calls the CheckInventoryAvailability, AllocateExistingInventory, AllocateExpectedInventory , DeallocateExistingInventory, and DeallocateExpectedInventory task commands as specified below. Also, these parameters accept OrderItem abbreviations, which are detailed in the help for Order Management subsystem commands.
The default ATP parameter values are as follows:
- remerge=*n
- merge=*n
- check=***
- allocate=*n
- backorder=*n
- reverse=*n
Example 1
The following example adds three units of the product with reference number 24 to each of the customer's current pending orders (only those current pending orders that are created under the store who carries catalog entry 24) indicating that they are to be shipped to the address that corresponds to address 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
The following example adds a bundle whose constituents are as follows: 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
The following example adds two products with multiple attributes to a shopping cart, where the first catalog entry has two attributes and the second catalog entry has three attributes:
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
- The command calls ResolveOrdersCmd with the input parameter orderId to get a list of orders. If the orderId is not specified, the default is "." (the current pending orders).
- The command can handle multiple items at one transaction. The multiple
items are specified using the enumeration group 'i'. For example, if
you want to update multiple order items, you can specify orderItemId_i as
parameters and i can be 1, 2, 3, and so on.
- The enumeration group 'i' must be an integer. They do not have to be consecutive integers. The command will handle each enumeration group in numeric order.
- If a parameter has enumeration group 0, this parameter applies to all other enumeration groups.
- If a parameter does not have an enumeration group, it is in enumeration group 0.
- The parameters orderItemId_i, expandConfigurationId_i, partNumber_i, and catEntryId_i are the keys for each enumeration group. It does not make sense to have one orderItemId to apply to all enumeration groups, so you should not use enumeration group 0 for these parameters. If you use enumeration group 0 or do not specify the enumeration group for these parameters, the command will only handle one item; all parameters in other enumeration groups will be ignored.
- The command does the following for each enumeration group 'i' of
parameters:
- Only one of the following parameters should be specified: orderItemId_i, expandConfigurationId_i, partNumber_i, or catEntryId_i. If more than one of above parameters are specified, only one will take effect and the others will be ignored. The order of precedence is orderItemId_i, expandConfigurationId_i, partNumber_i, then catEntryId_i; if the orderItemId_i is specified, for example, the others are ignored.
- If the parameter orderItemId_i is specified, the parameters expandConfigurationId_i, partNumber_i and catEntryId_i are ignored. The command tries to update the order item.
- If the parameter partNumber_i or parameter catEntryId_i is specified, the command tries to create a new order item and insert it into all resolved orders. If the list of resolved orders is empty, a new pending order is created.
- If the parameter partNumber_i is specified, the parameter catEntryId_i is ignored. The command uses the partNumber_i with the optional parameter memberId_i to find the catalog entry. If the memberId_i is not specified, the default member ID is the store owner's member ID.
- If the parameter expandConfigurationId_i is specified, the command tries to
create multiple new order items and insert them into one order. That is, the
list of resolved orders should be maximal to one. If the list of resolved
orders contains more than one order, the created order items are inserted into
only one order. It does the following:
- It finds all rows in the OICOMPLIST table based on the CONIFGURATIONID = expandConfigurationId_i and ORDERITEMS_ID is null.
- For each row found above, it uses the field CATENTRY_ID to create a new order item.
- The quantity in the order item is the quantity_i specified on the URL multiplied by the field CATALOGQUANTITY.
- If the field UNITPRICE and the field CURRENCY are both not null, they are copied to the order item and the manual price bit in the prepareFlags of the order item is set.
- The field ORDERITEMS_ID of the row is set to the orderitems_id of the newly created order item.
- The configurationid of the order item will be set to the expandConfigurationId_i.
- When a new order is created, the member ID of the new order is set to the current user in the command context and the currency is also taken from the one in the command context.
- When creating a new order item, the parameter quantity_i is required and must be a positive number. The member ID of the order item is taken from the member ID in the order. The storeId is also required.
- If the same enumeration group 'i' is specified more than once, only one is effective and the others are ignored.
- To add a new order item with catEntryId, the following things are checked:
- It calls the ResolveSkuCmd task command to resolve the SKU.
- It checks if the catalog entry is buyable in this store.
- It checks if the customer is entitled to buy this catalog entry.
- If any above checking failed, an exception will be thrown. But if the parameter continue is specified with value 1, the error will be ignored. This order item will not be added and the command will continue to process the next order item.
- Either updating an existing order item when the orderItemId_i is specified
or creating a new order item when the partNumber_i or catEntryId_i is
specified, the command uses the rest of parameters to update the order item.
- If the parameter addressId_i is not specified, for registered user, the default will be the addressId in the ADDRESS table (where the STATUS column has a value of P and the value in the NICKNAME column is the user's login ID obtained from the LOGONID column in the USERREG table). If the address cannot be found in the ADDRESS table, the addressId will be NULL for the order item in the ORDERITEMS table.
- If the quantity_i is zero, the order item is removed from the orders.
- If the parameter shipModeId_i is not specified, the default is taken from the STOREDEF table.
- It calls the GetContractUnitPriceCmd task command to get the contract price of the product or item using the specified trading agreements (contracts) or the eligible trading agreements (contracts), except for order items which were generated or whose price were manually entered (overridden by the administrator). All input trading agreements (contracts) to be used will be verified if they apply compatible payment methods. The currency is always the same as the currency from the order.
- For any orders in which one or more order items got updated or inserted, the orders are unlocked and the lastUpdate fields are updated with the current time stamp.
- After all enumeration groups are processed, the command does a fulfillment updating and inventory checking for all order items modified or created. If the ATP is enabled, it calls AllocateInventoryCmd. Otherwise it calls ResolveFulfillmentCenterCmd which is backward compatible.
- Calls the ExtendOrderItemProcessCmd task command to perform additional processing to meet any unique requirements.
- Sets a RedirectView that will redirect to the URL that is specified.
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 will be thrown too if the following errors are
encountered:
- Input trading agreements (contracts) are not valid or eligible to use.
- Trading agreements (contracts) being used in the order applies incompatible payment methods.
- Price Lists cannot be retrieved
- If ATP is not enabled, the task command ResolveFulfillmentCenterCmd may throw ECApplicationException with message: _API_BAD_INV and error view: ResolveFulfillmentCenterErrorView.