OrderItemUpdate URL

Update order items in an existing order. This URL can do all that OrderItemAdd URL can do (that is, add products and items in one or more orders into the order list).

 

URL 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 is completed successfully.

orderItemId_ i

The identifier of the OrderItem to be updated. If specified, then the catEntryId_i and partNumber_i parameters (for the same value of i) are ignored.

storeId

The store identifier, which is mandatory only if you want to add products or items to the orders. The storeId is required to check if the item is available in the store. If you have specified the storeId once, it is cached for future use.

catEntryId_ i

The identifier of a catalog entry to be used to create a new OrderItem.

partNumber_ i

If partNumber is specified, then the catEntryId_i parameter is ignored. When the partNumber_i and memberId_i parameters are specified, they determine a catalog entry by selecting the PARTNUMBER and MEMBER_ID columns in the CATENTRY table. This command behaves as if the identifier for that catalog entry were specified as the value for catEntryId_i.

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. To achieve compatibility with previous versions of WebSphere Commerce, set memberID to *storeOwner. This 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

The quantity of the item to be added to the order. This parameter is required when catEntryId_i or partNumber_id are specified. It is optional when OrderItemId_i is specified.

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 identifier 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 order items.

contractId_ i

The ID of the contract associated with the order. 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 ID of the offer associated with the order. This parameter can be repeated.

orderId

This is an internally-generated identifier that specifies zero or more orders to be updated, using order reference numbers or one of the special abbreviations "**", ".", "*", ".t", "*t". See Order abbreviations for a description of these abbreviations. If no pending orders exist for a particular store, a new pending order will be created. If more than one pending order is specified, order item entries will be created or updated for each of the specified orders.

outOrderName

Names of name-value pairs to be added to the redirection URL. The values of the added name-value pairs are the reference numbers of the created or updated orders.

outOrderItemName

Names of name-value pairs to be added to the redirection URL. The values of the added name-value pairs are the reference numbers of the created or updated order items.

listId

The interest item list ID. When you specify this parameter, the OrderItemUpdate command will create a new order which contains all the items in the list. You may use one of the special abbreviations "." and "*". See the Catalog abbreviations for a description.

orderDesc

Description for the new order created by this command.

continue

Controls whether the order-item update continues when one or more 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. This parameter can be repeated.

check

A list of OrderItems that should be checked by the CheckInventoryAvailability task command. This parameter can be repeated.

allocate

A list of OrderItems that should be allocated from existing inventory. This parameter can be repeated.

backorder

A list of OrderItems that should be allocated from expected inventory if they are not allocated from existing inventory. 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). This parameter can be repeated.

configurationId_ i

If this OrderItem represents a configured Dynamic Kit, this is the configuration ID. This parameter can be repeated.

continue

If an OrderItem cannot be created, 0 - terminate execution and rollback, and 1 - ignore the create or update operation for that OrderItem and continue execution.

expandConfigurationId_ i

Add multiple OrderItems, one for each component identified by expandConfigurationId_ i whose orderItemId attribute is null.

isExpedited_i

The default value for this parameter is N. If it is Y, orderitem will be marked as EXPEDITED.

calculateOrder

The default value for this parameter is 0. If it is 1, OrderCalculateCmd will be called to calculate the charges for the order.

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 provided by the gift giver to the gift registrant.

shipToRegistrant_ i

Specifies where gifts should be delivered. A value of 1 indicates that gifts should be shipped directly to the gift registrant, using the address provided during gift registry profile creation.

doPrice

Specifies whether the command should 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.

Note for ATP inventory: The remerge, merge, check, allocate, backorder and reverse parameters are applicable only if ATP inventory is enabled (see the INVENTORYSYSTEM column in the STORE table). They represent lists of OrderItems that will be passed to the DoInventoryActionCmd which invokes 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 URLs.

The default ATP parameter values are as follows:

• remerge=*n

• merge=*n

• check=***

• allocate=*n

• backorder=*n

• reverse=*n

Example 1

The following example creates a shipping record for one unit of a catalog entry with reference number 18 and has an attribute of monogram CJK. This shipping record is added to the customer's current pending orders. When the command completes, the OrderItemDisplay command is called.

   
http://myhostname/webapp/wcs/stores/servlet/OrderItemUpdate?addressId=2
   
&catEntryId=18&attrName=monogram&attrValue=CJK&quantity=1&shipModeId=4
    &URL=OrderItemDisplay

 

Example 2

The following example adds ten units of catalog entry number 2 to all the customer's current pending orders. When the command completes, the OrderItemDisplay command is called.

   
http://myhostname/webapp/wcs/stores/servlet/OrderItemUpdate?catEntryId=2
   
&quantity=10&orderId=*&outOrderName=orderId&URL=/webapp/wcs/stores/servlet/OrderItemDisplay

 

Example 3

The following example updates three OrderItem IDs.

   
http://myhostname/webapp/wcs/stores/servlet/OrderItemUpdate?URL=OrderItemDisplay
   
&quantity_1=2&quantity_2=7&orderItemId_1=117&orderItemId_2=118
    &orderItemId_3=113&quantity_3=2

 

Behavior

• The command calls ResolveOrdersCmd with the input parameter orderId to get a list of orders. If 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.

  1. The enumeration group i must be an integer. Different groups do not have to be consecutive integers. The command will handle each enumeration group in numeric order.

  2. If a parameter has enumeration group 0, this parameter will apply to any missing enumeration group. For example,

     OrderItemUpdate?orderItemId_1=aaaa&orderItemId_2=bbbb&quantity_0=5&quantity_2=10
     

     The quantity for orderItemId aaaa will change to 5 and the quantity for orderItemId bbbb will change to 10. This means that the quantity_0=5 acted as a default for the missing quantity_1 attribute. However, the explicitly specified quantity_2=10 was used.

  3. If a parameter does not have an enumeration group, then it overrides all other enumeration groups. For example

     OrderItemUpdate?orderItemId_1=aaaa&orderItemId_2=bbbb&quantity=3&quantity_0=5&quantity_2=10
     

     The quantity for orderItemId aaaa and bbbb will change to 3. The quantity=3 attribute overrides the value of quantity_2, assigning a value of 3 for the missing quantity_1 attribute.

  4. 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 handle only one item; all parameters in other enumeration groups will be ignored.

• The command does the following for each enumeration group i of parameters:

  1. 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 takes effect and the others are 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.

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

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

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

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

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

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

  8. If the same enumeration group i is specified more than once, only one is effective and the others are ignored.

  9. 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 of these checks fail, an exception is thrown. But if the parameter continue is specified with value 1, the error is ignored. This order item is not added and the command continues 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 the parameters to update the order item.

  1. If the parameter addressId_ i is not specified, for a registered user, the default is 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 there is no shipping address defined in the contract used in this order item, otherwise it is the shipping address that the contract allows). If the address cannot be found in the ADDRESS table, the addressId will be NULL for the order item in the ORDERITEMS table. For the existing shipping address of an order item, it will be refreshed with the address identifiers of the address belonging to the same user with status "P" and the same nickname. If there is no such address, then set the default to the addressId if you can find the default address.

  2. If the quantity_i is zero, the order item is removed from the order. The order item is sent to a trashcan order, or is removed from the database. See, Configuring deleting order items and requisition lists.

  3. If the quantity_i is different from the orderItem's original quantity and doPrice is N, the price bit flag PREPAREFLAGS_PRICE_REFRESHED is set to 0.

  4. If the parameter shipModeId_ i is not specified, the default is taken from the STOREDEF table.

  5. 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, except for order items which were generated or whose price were manually entered (overridden by the administrator). All input trading agreements to be used are verified if they apply compatible payment methods. The currency is always the same as the currency from the order.

  6. The SKIP_REPRICING attribute in the prepareFlags field protects the pricing of an item. If changes are made to the order item that affect price (including shipping and taxes), it removes the SKIP_REPRICING attribute.

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

• Updates the price for all order items that were updated or created by the command. For store price prepare flag 8, all order items in the order are recalculated.

  1. If the doPrice parameter is set to N, do the following checks to determine whether to reset the PREPAREFLAGS_PRICE_REFRESHED price bit flag of each order item.

     1. If the offerIds parameter is set for the order item and it is different from ORDERITEMS.OFFER_ID , or ORDERITEMS.OFFER_ID is null, reset the bit flag to 0.

     2. If the contractIds parameter is set for the order item and it is different from ORDERITEMS.TRADING_ID, or ORDERITEMS.TRADING_ID is null, reset the bit flag to 0.

     3. Call the CheckAndResetOrderItemPriceFlagCmd task command to check and reset the PREPAREFLAGS_PRICE_REFRESHED bit flag for the order item if its created time has been expired.

  2. For each order item, if doPrice is N and the PREPAREFLAGS_PRICE_REFRESHED bit flag is 1, then the price is not refreshed. If the bit flag is 0, the price is refreshed with the same behavior as doPrice=Y, which is the default value of the doPrice parameter.

  3. Update order item prices if the order items are not generated items, quotations, or price overridden items.

  4. Set the PREPAREFLAGS_PRICE_REFRESHED bit flag to 1 for updated order items.

• After all enumeration groups are processed, if doInventory is set to N, the command will not do inventory action. If doInventory is set to Y, the command does a fulfillment center updating and inventory checking for all order items modified or created.

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

• When partnumber_ i is specified and memberId and memberId_ i are not specified to the OrderItemAdd command, the following algorithm determines the CatalogEntry to be added: If there is only one CatalogEntry with the specified partnumber for sale in the current Store (that is, in any of the Stores in the catalog StorePath of the current Store), use that CatalogEntry. If there is more than one such CatalogEntry object, the partnumber is ambiguous. See below for exception conditions.

• If an OrderItem cannot be added, and the continue parameter specifies 1, continue without creating the OrderItem.

• If the expandConfigurationId_ i parameter is specified, then add an OrderItem for each component identified by the expandConfigurationId_ i parameter whose orderItemId attribute is null. The quantity should be the specified quantity multiplied by the catalogQuantity attribute of the component. The OrderItem configurationId attribute should be set to the specified ConfigurationId. Update the OrderItem prepareFlags attribute to indicate `notConfigured'. If the component has non-null unitPrice and currency attributes, then copy them to the OrderItem price and currency attributes and set the priceOverride flag in the OrderItem prepareFlags attribute. The orderItemId attribute of the component should be updated to refer to the added OrderItem.

• If the orderComment parameter is specified, replace the Order comment attribute with the value specified by the orderComment parameter.

• Update ship information which includes shipping instruction, shipping carrier account number, and shipping charge type.

• The OrderItemAdd and OrderItemUpdate URLs do not populate customizable fields of ORDERS table. These fields can be populated in OrderPrepare command.

• Behavior for IBM Gift Center and WebSphere Commerce order integration:

  • Takes the three additional paramters: externalId_ i, giftMessage_i , and shipToRegistrant_ i.

  • If externalId is specified, the relationship between the order item and the gift registry will be stored in the ORDERITEMGIFT table.

  • Determines where to deliver the item:

    • If shipToRegistrant_ i is set to 1, the order item will be shipped directly to the registrant for the the gift registry. In this case, the command will first find the entry in ORDERITEMGIFT table based on the orderitemId and the externalId, and then it will set the ORDERITEMGIFT.SHIPTORGSTRNT to 1.

    • if shipToRegistrant_i is not set and addressId is set, the item will be shipped to the gift giver, and ORDERITEMGIFT.SHIPTORGSTRNT will be set to 0.

  • If giftMessage is specified, the command will save the information in ORDERITEMGIFT.GIFTMESSAGE.

  • Note that for the IBM Gift Center, the behavior above is implemented by extending ExtendOrderItemProcessCmd which is a task command for OrderItemAdd or OrderItemUpdate. The detailed implementation for this task command is called GiftRegistryExtendOrderItemProcessCmdImpl.

    If you use the IBM Gift Center sample application, after publishing the GiftCenterConsumerDirect.sar, the CMDREG table is updated to specify that the implementation of ExtendOrderItemProcessCmd as GiftRegistryExtendOrderItemProcessCmdImpl. Therefore, if you have already used this extension point for your own implementation, your implementation of ExtendOrderItemProcessCmd will have to extend GiftRegistryExtendOrderItemProcessCmdImpl. Also, since the command accepts no shipping address, if shipToRegistrant is specified, the implementation for UpdateShippingAddressCmd has been changed to GiftRegistryUpdateShippingAddressCmdImpl so that UpdateShippingAddressCmd supports not updating the shipping address if addressId with no value is passed.

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 thrown too if the following errors are encountered:

  1. Input trading agreements are not valid or eligible to use.

  2. Trading agreements that are used in the order apply incompatible payment methods.

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

• If there is more than one such CatalogEntry object, the part number is ambiguous. ECApplicationException is thrown specifying the ERR_PROD_NOT_EXISTING error message. Pass Error Name-Value Pairs 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 having 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.

Related concepts

Order Management subsystem

Related reference

Order Management subsystem URLs
IBM Gift Center and WebSphere Commerce order integration