Loading...
Area: Episerver B2B Commerce

Cart API handler

Recommended reading 

HTTP Verb: GET

URL: /api/v1/carts

Description: Returns all of the saved, abandoned, submitted carts for the logged in user.

Base: HandlerBase<GetCartCollectionParameter, GetCartCollectionResult>

Handlers:

Order Handler

Description

500 GetCartCollectionHandler

Gets collection of carts. If requester is not signed in then handler return error result. If BillToId parameter not specified then handler return carts for current bill to. If current user doesn't have any bill to then handler return error result.

Order Handler

Description

500 GetCartsQuery Creates the initial carts query that returns carts (CustomerOrder) for a bill-to customer. The BillToId property on the parameter object is used to find the bill-to customer. Other than filtering by bill-to customer, this query has not been filtered, sorted, or paged. The query is stored in the CartsQuery property on the result object.
600 ApplyFiltering Applies additional filters to the CartsQuery. Filters out customer orders where the bill-to and ship-to customers are NOT active. Filters the CartsQuery using the Status property on the parameter by searching for carts with that status. If the Status property equals "AwaitingApproval", only carts that require approval by or were requested to be approved by the current user are returned. If the current user has the "Administrator" role, then carts assigned to any of the current users ship-to customers are returned. If the Status property equals "Saved", only carts saved by the current user are returned. The query can also be filtered by other properties on the parameter object, including OrderNumber, ShipToId, FromDate and ToDate (applies to the order date of the order), and OrderTotal and OrderTotalOperator.
700 ApplySort Applies a sort to the CartsQuery. If the Sort property on the parameter object is empty, the query is sorted by the ModifiedOn date (in descending order), otherwise the query is sorted like so:
"ordergrandtotal" - Sorts by the order total of the cart.
"initiatedbyusername" - Sorts by whichever user started/created the order.
800 ApplyPaging Applies paging to the CartsQuery. If the PageSize property on the parameter object has a value, the query is paged using the PageSize and Page properties on the parameter object. If the PageSize property has no value, the default page size will be used (configured using the "Number of items that display per page by default." setting).
900 ExecuteQuery Executes the CartsQuery after the query has been expanded, filtered, sorted, and paged. The result is stored in the Carts property on the result object.
1000 GetCartPrices For each cart in the result, calculates the pricing and populates the CartPrices property on the result object with a pricing object, which contains OrderSubTotal, OrderGrandTotal, ShippingAndHandling, and TotalTax.

HTTP Verb: GET

URL: /api/v1/carts/{cartId}

Description: Return a single shopping cart

Base: HandlerBase<GetCartParameter, GetCartResult>

Handlers:

Order Handler

Description

500 GetCartHandler Gets cart. If CartId parameter not specified then handler create new cart using current context.
600 GetCartApprovalHandler

Set information for Order Approval. If user not signed in then cart doesn't require approval. If user role is Requisitioner or Buyer1 then cart requires approval. If OrdertTotal more than available budget then cart requires approval.

800 GetCartPunchOutHandler

If the current session is a punchout session then user can't request quote and can't see line notes. If punchout session mode is Inspect then link 'Continue shopping' doesn't show.

Order Handler

Description

500 GetCart Retrieves a cart. If the CartId property on the parameter object has a value, the application retrieves the cart using that id. If the cart is not found, an error is returned. Otherwise, the cart is found using the configured cart order provider (configured using the "Cart Provider" setting). If the cart still is not found and the CreateIfNotFound property on the parameter object equals "true", the cart order provider creates a new cart for the current user and website. If the cart still is not found, the handler creates a new cart for the current user, website, and bill-to and ship-to customers. The cart is stored in the Cart property on the result object.
600 ValidateCustomers If either the bill-to or ship-to customer on the cart are NOT active, an error is returned.
700 ValidateAvailability Checks whether or not the cart being requested is available to the current user, using the rules below.
  • If multiple carts are being requested (the CartId property on the parameter object is null), this handler is skipped.
  • If the current user is not authenticated, an error is returned.
  • If the current user is viewing "Saved" carts (the PlacedByUserName on the cart object is not empty and matches the current users username), the rest of the handler is skipped.
  • If the cart is for the current user, the rest of the handler is skipped.
  • If the current user is required to approve the cart, the rest of the handler is skipped.
  • If the cart is in a status of "AwaitingApproval" or "Submitted" and the user has the "Administrator" role and the bill-to and ship-to customers are not assigned to the current user, an error is returned.
  • If the cart type equals "Order", an error is returned.
  • If the cart has a salesperson and the current user is not the salesperson or the manager of the salesperson, an error is returned.
800 SetCurrency Sets the currency on the cart. If a specific cart is being requested (the CartId property on the parameter object has a value), this handler is skipped. If the current currency matches the cart currency, the rest of the handler is skipped.
The cart stored in the Cart property on the result object is updated. The current currency is updated on the cart object. The RecalculateTax and RecalculatePromotions properties are set to "true". The ShippingCalculationNeededAsOf property is set to the current datetime (using the DateTimeProvider). Then, the cart pricing is recalculated using the updated cart currency.
850 GetCartRealTimeInventory If the IInventoryService is RealTime, calls IRealTimeInventoryService.GetInventory for all of the products on the CartLines to establish them in cache in one call to the external inventory service for all of the products in the Cart.
900 RecalculateCart Recalculates the cart pricing if ALL of these conditions are met:
  • The cart contains order lines
  • The cart has the status of "Cart" or "AwaitingApproval"
  • The cart pricing has not been calculated within a certain amount of time (configured using the "Number of Minutes Before Repricing Cart" setting).
If all the conditions are not met, this handler is skipped. Otherwise, the cart pricing is recalculated (including tax). If the cart is not a quote or job quote (cart type is not equal to "Quote" and "Job"), the promotions are also included in the cart recalculation. If the recalculation fails, the CanCheckOut property is set to "false" and the CartNotPriced is set to "true".
1000 PopulateUserData If the current user is not authenticated, this handler is skipped. Populates the following properties on the result object using the current user:
  • IsAuthenticated - whether or not the current user is authenticated
  • UserLabel - the display name for the user (either the username or full name for an authenticated user or "guest" for a guest user)
  • UserRoles - the roles assigned to the current user (none for guest)
  • CanRequisition - whether or not requisitions are allowed and the current user has the "Requisitioner" roles
  • IsSubscribed
  • IsSalesperson
1100 PopulateCustomersResults Uses the GetBillToHandler and GetShipToHandler to retrieve the bill-to or ship-to customer for the cart or the current user. The bill-to and ship-to customers are stored in the GetBillToResult and GetShipToResult, respectively.
1200 PopulateCounts Populates the following properties on the result object using the cart:
  • LineCount
  • TotalQtyOrdered
  • TotalCountDisplay - uses either the LineCount or TotalQtyOrdered (configured using the "Mini-Cart Quantity Display" setting)
1300 PopulateCanCheckOut Defaults the CanCheckOut property on the result object to "true", but changes the value based on the rules below.
  • If the GetCartLineResults property on the parameter object equals "false" and the cart line count in the cart does not match the LineCount calculated in the previous handler (this can be due to order lines that have been voided or not completely configured), the CanCheckOut property is set to "false".
  • If the CanRequisition property on the result object (calculated earlier) equals "true", the CanCheckOut property is set to "false".
  • If the cart pricing has NOT been calculated within a certain amount of time (configured using the "Number of Minutes Before Repricing Cart" setting), the CanCheckOut property is set to "false".
1400 PopulateCanModifyOrder Populates the CanModifyOrder property on the result object. If the cart status equals one of the following statuses, the CanModifyOrder property is set to "true".
  • Cart
  • Saved
  • AwaitingApproval
  • QuoteProposed
  • QuoteRejected
  • QuoteRequested
  • QuoteCreated
  • PunchOut
  • PunchOutOrderRequest
If the ForModification property on the result object equals "true" and the CanModifyOrder property equals "false", an error is returned.
1500 PopulateSettings Populates properties on the result object using a combination of settings and other data. See additional information below.
1600 CopyCustomPropertiesToResult Copies custom properties configured for the customerOrder entity to the Properties property on the result object.
1700 CalculateShipping Uses the pricing pipeline to calculate the shipping costs for the cart. If the CalculateShipping property on the parameter object equals "false" or the cart has no active cart lines, this handler is skipped. If the shipping calculation failed, the CanCheckOut property on the result object is set to "false".
1800 CalculateTaxes Uses the pricing pipeline to calculate the tax costs for the cart. If the CalculateTax property on the parameter object equals "false", this handler is skipped.
1900 PopulateTotals Populates the following cart totals on the result object:
  • OrderSubTotal
  • OrderSubTotalWithOutProductDiscounts
  • OrderGrandTotal - this is taken from the cart object stored in the result object
  • ShippingAndHandling
  • TotalTax
  • CurrencySymbol - this is taken from the cart object stored in the result object or the current currency in the site context
  • RequestedDeliveryDate - this is taken from the cart object stored in the result object
2000 PopulateCanBypassCheckoutAddress If the CanRequisition property on the result object equals "true", this handler is skipped. Defaults to setting the CanBypassCheckoutAddress property on the result object to "false", but changes the value based on the rules below.
  • If the "Bypass Addresses On Checkout" setting equals "false", the rest of the handler is skipped.
  • If the ship-to Address1 property is a PO Box, the rest of the handler is skipped.
  • If any of the bill-to or ship-to customer address fields are required but are empty, the rest of the handler is skipped.
At this point, the CanBypassCheckoutAddress property on the result object is set to "true".
2100 PopulateCarriers Populates the carriers and services for selection during checkout. If the GetShippingOptions property on the parameter object equals "false", this handler is skipped. The carrier options are stored in the Carriers property on the result object.
2200 PopulatePaymentOptions Populates the payment options for selection during checkout. If the GetPaymentOptions property on the parameter object equals "true", this handler is skipped.
  • If the ShowPoNumber property on the result object equals "true", retrieves the non-credit card payment method that matches the bill-to customer TermsCode.
  • If the ShowCreditCard property on the result object equals "true", retrieves the credit card payment methods (includes payment profiles, card types, and expiration dates). The "Accepted Credit Cards" setting is used to select the credit card payment methods.
The payment methods are stored in the PaymentOptions property on the result object. Also sets the PaymentMethod property on the result object equal to the payment method that matches the TermsCode property on the cart.
2300 PopulateQuoteRequiredCount Reports how many cart lines require a quote. If the CanRequestQuote property on the parameter object equals "false", this handler is skipped. If all cart lines require a quote, the CanCheckOut property on the result object is set to "false". The number of cart lines that require a quote is stored in the QuoteRequiredCount property on the result object.
2400 PopulateCostCodes Adds the bill-to customer cost codes to the result. If the ShowCostCode property on the parameter object equals "false", this handler is skipped. The CostCodeLabel property on the result object is populated with the bill-to customers CostCodeDescription, if one is available. If the GetCostCodes property on the parameter object equals "false", the rest of the handler is skipped. Otherwise, all the active cost codes for the bill-to customer are added to the CostCodes property on the result object. If the there are multiple cost codes available (more than one), the ShowCostCode property on the result object is set to "true".
2500 GetCartLines Retrieves product data for each of the cart lines on the cart object. If the GetCartLineResults property on the parameter object equals "false", this handler is skipped. For each of the cart lines, the product, cart line, and cart data are transformed into a GetCartLineResult and added to the collection stored in the CartLineResults property on the result object. If any of the products have insufficient inventory, the CanCheckOut property on the result object is set to "false".
2600 GetRestrictions Determines which products in the cart are restricted for the current website and bill-to and ship-to customers. If the GetRestrictions property on the parameter object equals "false", this handler is skipped. If any of the cart lines have a restricted product, the IsRestricted property the cart line is set to "true". If any GetCartLineResult objects have been marked as restricted, the CanCheckOut property on the result object is set to "false".
2650 SetIsAwaitingApproval Determines if the cart is waiting for approval by another user. If the current user is NOT authenticated or the cart is newly created, the IsAwaitingApproval property on the result object is set to "false". Otherwise, the IsAwaitingApproval property is set to "true" if ALL the conditions below are met:
  • The cart status is "AwaitingApproval"
  • The cart is assigned an approver
  • The approver is the current user or the current user has the "Administrator" role
2700 SetRequiresApproval Determines if the cart requires approval.
  • If the current user is not assigned any roles that require an approver, the RequiresApproval and HasApprover properties on the result object are set to "false". The rest of the handler is skipped.
  • If the "Budgets From Online Orders Only" setting is "true" and the budget enforcement level is set to "User", the budget enforcement level on the cart is set to "None".
  • If the current user is assigned the "Requisitioner" or "Buyer1" role, the RequiresApproval property is set to "true" and the HasApprover property is set to "true" if the current user has an approver assigned. The rest of the handler is skipped.
  • If the budget enforcement level equals "None" or budget management is NOT enabled or the current user is not assigned the "Buyer2" role, the rest of the handler is skipped.
  • If the order total is greater than the available budget for the current user, the RequiresApproval property is set to "true" and the HasApprover property is set to "true" if the current user has an approver assigned.
2800 GetCreditCardBillingAddress Sets the result CreditCardBillingAddress from parsing the latest successful CreditCardTransaction.AvsAddr is there is one.
2900 PopulateWarehouses If the GetWarehouses property on the parameter object equals "true", this handler is skipped. Retrieves all active warehouses and stores the result to the Warehouses collection property on the result object.
3000 GetPunchoutSettings Updates some of the properties on the result object based on the current PunchOut session. If there is no active PunchOut session, this handler is skipped.
  • The CanModifyOrder property on the result object is set equal to itself and whether or not the current PunchOut session is allowed to modify the cart (Create, Edit, or Cancel sessions).
  • The CanRequestQuote property on the result object is set to "false".
  • The ShowLineNotes property on the result object is set to "false".
  • A property named "IsPunchout" is added to the Properties collection on the result object and set to "true".
3100 GetAlsoPurchasedProducts If parameter GetAlsoPurchasedProducts is false, then bypass the handler. If WidgetSettings.EnableDynamicRecommendations is false, then return an error. Otherwise call ICatalogPipeline.GetAlsoPurchasedProducts and set AlsoPurchasedProducts to result.

Order 1500 PopulateSettings Properties Specifications

Property Description
CanSaveOrder Indicates whether or not saved orders are enabled (configured using the "Saved Orders" setting) and the cart status equals "Cart" and the current user is NOT assigned the "Requisitioner" role.
CanRequestQuote Indicates whether or not request for quote is enabled (configured using the "Request for Quote" setting) and a default salesperson is specified (Customer Defaults "Sales Representative" setting in Admin Console) and the current user is NOT assigned the "Requisitioner" role.
CanEditCostCode The Budgets and Order Approval Settings "Cost Code Editing" setting.
ShowCostCode Indicates whether or not the current bill-to customer is NOT null and the "Show Cost Codes" setting equals "true".
ShowPoNumber The Checkout Settings "Enable Purchase Orders" setting.
ShowPayPal The Payment Settings "Show PayPal" setting.
ShowCreditCard The Checkout Settings "Enable Credit Card as Payment Method" setting.
ShowTaxAndShipping The Cart Settings "Show Tax & Shipping Amount in Cart" setting.
ShowLineNotes The Cart Settings "Show Order Line Notes" setting.
ShowNewsletterSignup The Checkout Settings "Show Subscription Signup During Checkout" setting.
RequiresPoNumber The Checkout Settings "Require Purchase Order Number" setting.

HTTP Verb: PATCH

URL: /api/v1/carts/{cartId}

Description: Update a single shopping cart

Base: HandlerBase<UpdateCartParameter, UpdateCartResult>

Handlers:

Order Handler

Description

500 UpdateCartHandler

Updates a cart. If no OrderLines in cart then go to next handler. If BillToId or ShipToId parameters specified then handler recalculates cart for new BillTo/ShipTo.

501 UpdateCartSubmitForRequisitionHandler

If Status parameter equal 'RequisitionSubmitted' then handler submits the requisition.

550 UpdateCartSaveHandler

Saves the Cart or moves from Saved to Cart.

600 UpdateCartApprovalHandler

If cart status is 'Cart' and Status parameter is 'AwaitingApproval' then handler change status to 'AwaitingApproval' is submitting for approval. If cart status is 'AwaitingApproval' and Status parameter is 'Cart' then handler creates a cookie for the cart being approved.

650 UpdateCartRequestQuoteHandler

If Status parameter is 'QuoteRequested' or 'QuoteCreated' then handler request a quote.

700 UpdateCartProposeQuoteHandler

If Status parameter is 'QuoteProposed' then handler propose a quote.

750 UpdateCartJobAcceptedHandler

If Status parameter is 'JobAccepted' then handler accept job.

900 UpdateCartSubmitHandler If Status parameter is 'Submitted' then handler submits the cart. If no OrderLines in cart then handler returns error result.
Order Handler Description
450 ValidateContext Validates that a credit card payment method is accompanied by a credit card number.
500 GetCart Retrieves a cart using the GetCartHandler handler chain. If the current user is NOT authenticated and the Status property on the parameter object equals "Submitted", an error is returned. The cart is found using the CartId property on the parameter object. The cart object is stored in the GetCartResult property on the result object.
600 CopyCustomPropertiesToCart Copies custom properties configured for the customerOrder entity to the Cart object stored in the GetCartResult property on the result object.
700 SetBillTo Sets the bill-to customer on the cart.
If the BillToId property on the parameter object does NOT have a value or it matches the customer already associated with the cart, the bill-to customer on the cart is updated using that bill-to customer. The rest of the handler is skipped.
If the bill-to customer has changed (the BillToId property does NOT match the customer on the cart) and the ship-to customer has NOT changed (the ShipToId property on the parameter object has no value), an error is returned.
The changed bill-to customer is retrieved and set on the Customer property on the cart object. The RecalculateCart property on the result object is set to "true" (the pricing may differ based on customer).
800 SetShipTo Sets the ship-to customer on the cart. If the ShipToId property on the parameter object does NOT have a value or it matches the customer already associated with the cart and the Status property on the parameter object is not equal to "QuoteProposed", the ship-to customer fields on the cart are updated using that ship-to customer. If the RecalculatePromotions and RecalculateTax properties on the cart object are "true", the RecalculateCart property on the result object is set to "true". The rest of the handler is skipped.

Getting this far means the ship-to customer for the cart has changed. The changed ship-to customer is retrieved and set on the Customer property on the cart object. Also, the customer fields on the cart are updated using the changed ship-to customer and the RecalculateCart property on the result object is set to "true".
900 UpdateCart The following properties on the cart object is updated using the same properties on the parameter object:
  • OrderDate
  • Notes
  • CustomerPO
  • TermsCode
  • RequestedDeliveryDate
1000 RecalculateCart Recalculates the cart pricing. If the RecalculateCart property on the parameter object equals "false", this handler is skipped. Also, the IsRestrictedProductRemovedFromCart property on the result object is set to "true" if any products in the cart are restricted for the current website and customer.
1050 SetupPaypalPayment If the IsPayPal property on the parameter object equals "false" or the Status property on the parameter object is NOT equal to "PaypalSetup" or the current payment gateway is NOT the "PaypalExpress" payment gateway, this handler is skipped.
Populates the PayPalPaymentUrl and PayPalToken properties using the PayPal settings (in the Admin Console). The result is stored in the GetCartResult.PaymentOptions object on the result object. Also sets to the OrderNumber on the cart object.
1100 SetShipVia Calculates the shipping and tax amounts using the selected carrier service (ShipVia). If the carrier service (ShipViaId on the parameter object) is not selected or has changed since the last selection, the shipping and tax amounts for the cart are recalculated.
1200 SetCurrency Sets the cart currency. If the CurrencyId property on the parameter object has no value or the cart currency matches the currency in the parameter object, this handler is skipped.
If the currency in the parameter object does not exist in the application, an error is returned.
Also, the RecalculateCart property on the result object is set to "true".
1300 UpdateCartSubmitForRequisition Updates the cart for the requisition workflow. If the Status property on the parameter object does NOT equal "RequisitionSubmitted", this handler is skipped.
Creates a new customer order with a status of "Requisition", if one does not exist. Copies order lines from current cart to the requisition order, recalculates the pricing for the requisition order, and sets the status for the current cart to "RequisitionSubmitted".
1400 SaveCart Sets the status of the cart to "Saved". If the Status property on the parameter object does NOT equal "Saved" or the cart does not contain order lines, this handler is skipped.
If the CanSaveOrder property on the cart equals "false" or all the order lines contain configured products and the configuration is not complete, an error is returned.
The cart status is set to "Saved". However, before that happens, the promotions are removed from the cart and any remaining order lines with in-progress configurations are removed.
1500 MoveSavedOrderInToCart Moves a saved order back in to the current users cart. If the Status property on the parameter object does NOT equal "Cart" or the cart object on the result object does NOT have a status of "Saved", this handler is skipped.
Transfers the order lines from the saved order to the current cart. Also, updates the GetCartResult property on the result object to point to the current cart and deletes the saved order.
1600 ChangeStatusToAwaitingApproval Changes the current cart to a status of "AwaitingApproval". If the Status property on the parameter object does NOT equal "AwaitingApproval", this handler is skipped.
If the cart status is not equal to "Cart" or "QuoteProposed", this handler is skipped.
The cart OrderNumber is updated. The InitiatedByUserProfile and ApproverUserProfileId properties on the cart object are updated according to the current user and the assigned approver. The cart status is set to "AwaitingApproval".
1700 MoveQuoteRequiredLinesBackToCart Moves and CartLines that have a Product that requires a quote out of the cart being submitted and in to the new shopping cart.
1800 ChangeStatusToCart Approves a cart. This is done when a user approves a cart created by another user. If the current user does NOT have the role of "Administrator" and is NOT the approver for the cart, an error is returned.
If the current user is an "Administrator" and NOT the approver, the application verifies that the current user has access to the ship-to customer associated with the cart. If the current user does NOT have access, the handler chain is exited and not continued.
If the user has access to the ship-to customer or is the cart approver, the cart pricing is updated using the pricing pipeline.
Creates a temporary cookie to keep track of the approved order.
1900 ChangeStatusToSubmitted Submits a cart that was previously approved. This happens after a cart is approved and submitted. Removes the temporary cookie previously created by the ChangeStatusToCart handler.
2000 UpdateCartRequestQuote Updates the quote-related fields on the cart object when a quote is requested. If the Status property on the parameter object does NOT equal "QuoteRequested" or "QuoteCreated", this handler is skipped.
If the user who placed the order and requested the quote has a role of "Requisitioner", an error is returned.
Populates properties on the cart object stored in the GetCartResult.Cart object on the result object. See additional information below.
Also clears promotions from the cart.
2100 UpdateCartProposeQuote Updates the quote-related fields on the cart object when a quote is proposed. The Status and QuoteExpirationDate property on the cart object are populated with the Status property on the parameter object and the configured quote expiration days (if not a job quote), respectively.
2200 UpdateCartJobAccepted Updates the cart status to "JobAccepted" when a job quote is accepted. Also, updates the pricing for the quote.
2300 SubmitCart Updates the cart status to "Submitted". If any of the following is true, an error is returned.
  • Current user is NOT authenticated
  • Cart contains no order lines
  • Cart has restricted products
  • Cart requires a PO number, but has no PO number
  • "Allow Empty Shipping" setting equals "false" and carrier service (ShipVia) not selected for cart
  • Cart status equals "QuoteRequested" and cart type equals "Quote"
  • Cart has already been submitted (status is NOT equal to "Cart", "QuoteProposed", "Saved", "PunchOut", "PunchOutOrderRequest", or "AwaitingApproval")
Also moves order lines that have a proposed quote back to the current cart.
2400 ProcessInventory Updates the quantity on hand for products that are tracked by the application. If the cart does not have a status of "Submitted", this handler is skipped.
2500 ProcessSubscriptionPurchase Adds a new subscription for any products purchased as a subscription. If the cart does not have a status of "Submitted", this handler is skipped.
2700 ProcessGiftCardTransactions Applies any gift cards used to the cart and creates gift card transactions. If the cart does not have a status of "Submitted", this handler is skipped. If gift cards are ignored for transactions ("Ignore Gift Card Transactions" setting in Admin Console), this handler is skipped.
2800 ProcessCreditCardTransactions Submits a credit card transaction. If the cart does not have a status of "Submitted", this handler is skipped. The card number is required if a credit card is used. If paying by stored payment profile, then that is used instead. Otherwise, the user is paying on account and this handler is skipped. The configured payment gateway is sent the payment transaction to process. If the StorePaymentProfile property on the parameter object equals "true", the payment used is stored as a payment profile for later use with the payment gateway.
2900 PostThirdPartyTax Invokes the configured tax calculator to post the tax for the order. If the cart does not have a status of "Submitted", this handler is skipped.
3000 SubmitOrderToErp Submits the order to the ERP using the "OrderSubmit" standard integration job. If the cart does not have a status of "Submitted" or the settings do not allow submitting orders to the ERP ("Submit Orders to ERP" setting in Admin Console), this handler is skipped.
3100 PopulateConfirmationEmailModel Populates the model object that is used to render the confirmation email. If the cart does not have a status of "Submitted", this handler is skipped. The model object contains order data including order number, order date, bill-to and ship-to customer address info, promotions used, order amounts (including tax and order total), and order lines. The model object is stored in the ConfirmationEmailModel property on the result object.
3200 SendConfirmationEmail Sends the order confirmation email to the email addresses configured in the Admin Console ("Send Order Confirmation To" and "Order Notification Email Address" settings). If the cart does not have a status of "Submitted", this handler is skipped.
3300 CreateOrderHistory Creates history records for the order, including order, order lines, taxes, and promotions. If the cart does not have a status of "Submitted", this handler is skipped.
3400 CopyCustomPropertiesToResult Adds active custom properties configured for customerOrder to the Properties collection stored on the result object.
3500 CreateGetCartResult Retrieves the submitted cart, transforms it into a GetCartResult, and stores it in the GetCartResult property on the result object.
3600 UpdateExperiment Updates active experiments (A/B testing data) with order data if the cart was submitted.

Order 2000 UpdateCartRequestQuote Specifications

Cart Property Sets Value To
PlacedByUserProfile The user profile noted in the UserProfileId property on the parameter object. If that property does not have a value, the current user is used.
PlacedByUserName The username of the user in the PlacedByUserProfile property.
OrderNumber The next order number that is generated.
CurrencyId, Currency The current currency if the cart currency is null.
DefaultWarehouseId, DefaultWarehouse The current warehouse if the cart default warehouse is null.
Type "Job" if the quote is a job quote, otherwise "Quote".
CustomerReference1 The job quote name.
RecalculateTax True
Salesperson If the cart has no salesperson, the customer default salesperson is used.
Status The Status property on the parameter object.

HTTP Verb: DELETE

URL: /api/v1/carts/{cartId}

Description: Remove a single shopping cart

Base: HandlerBase<RemoveCartParameter, RemoveCartResult>

Handlers:

Order Handler

Description

500 RemoveCartHandler Removes a cart. If cart not found or user can't change cart then handler returns error result. If cart status is not 'Cart' or 'Saved' then handler returns error result.
Order Handler Description
500 GetCart Retrieves a cart using the GetCartHandler handler chain. The CartId property on the parameter object is used to find the cart. If a cart is not found, a new cart is created. The cart is stored in the GetCartResult property on the result object.
600 ValidateCart Validates that the cart can be deleted. If the cart status equals "AwaitingApproval", the status is changed to "Void". The rest of the handler is skipped. If the cart cannot be deleted (status of "Cart" or "Saved"), an error is returned.
700 RemovePromotions Removes promotions that have already been applied to the cart. If the status has already been set to "Void", this handler is skipped.
800 RemoveCart Deletes the cart. If the status has already been set to "Void", this handler is skipped.

HTTP Verb: GET

URL: /api/v1/carts/{cartId}/cartlines

Description: Return a collection of products for a specific shopping cart

Base: HandlerBase<GetCartParameter, GetCartResult>

Handlers:

Order Handler

Description

500 GetCartHandler

Gets cart. If CartId parameter not specified then handler create new cart using current context.

600 GetCartApprovalHandler

Set information for Order Approval. If user not signed in then cart doesn't require approval. If user role is Requisitioner or Buyer1 then cart requires approval. If OrdertTotal more than available budget then cart requires approval.

800 GetCartPunchOutHandler

If the current session is a punchout session then user can't request quote and can't see line notes. If punchout session mode is Inspect then link 'Continue shopping' doesn't show.

HTTP Verb: POST

URL: /api/v1/carts/{cartId}/cartlines

Description: Add a product to a specific shopping cart

Base: HandlerBase<AddCartLineParameter, AddCartLineResult>

Handlers:

Order Handler

Description

500 AddCartLineHandler

Adds a cart line to the cart. If product can't be added to the cart then handler returns error result.

550 AddCartLineRequisitionHandler

If RequisitionId is specified then handler process requisition.

NOTE: The default quantity limit on any one product item is set to 6 digits. This is not a platform constraint and, as needed, can be overridden in javascript.

Order Handler

Description

500 GetCart Retrieves a cart using the GetCartHandler handler chain. The CartId property on the parameter object is used to find the cart. If a cart is not found, a new cart is created. The cart is stored in the GetCartResult property on the result object.
600 GetProduct Retrieves the product for the cart line using the GetProductCollectionHandler handler chain. The product is stored in the ProductDto property on the result object. If the product cannot be added to the cart (the CanAddToCart property on the product equals "false"), an error is returned.
700 CopyCustomProperties Copies custom properties configured for the customerOrder entity to the CustomProperties property on the result object. Also, adds the product configuration to the CustomProperties property, if the product has a custom configuration.
800 AddCartLine Adds an cart line to the cart and the OrderLine property on the result object. Also updates cart line with the line notes, cost codes (if allowed to edit cost codes, CanEditCostCode property on the cart), unit of measure, and quantity ordered from the parameter object and the product retrieved earlier.
900 RecalculateCart Recalculates the cart pricing (including the specific order line being added) and updates the cart in the GetCartResult property on the result object. If the SkipRecalculateCart property on the parameter object equals "true", this handler is skipped.
1000 CreateGetCartLineResult Uses the CreateGetCartLineResult pipeline to transform the cart, order line, and product objects stored on the result object into a GetCartLineResult. The result is stored in the GetCartLineResult property on the result object.
1100 AddCartLineRequisition If the cart line has been requested as a requisition, adds formatted line notes to the cart line object stored in the GetCartLineResult property on the result object. The notes include who requested the requisition and the item quantity requested.

HTTP Verb: GET

URL: /api/v1/carts/{cartId}/cartlines/{cartLineId}

Description: Return a single product from a specific shopping cart

Base: HandlerBase<GetCartLineParameter, GetCartLineResult>

Handlers:

Order Handler

Description

500 GetCartLineHandler

Gets a cart line. If cart line not found then handler returns error result.

Order Handler Description
500 GetCart Retrieves a cart using the GetCartHandler handler chain and the CartId property on the parameter object. The cart is stored in the GetCartResult property on the result object.
600 GetCartLine Retrieves the cart line from the cart using the CartLineId property on the parameter object. If the cart line is not found, an error is returned. The cart line found is stored in the CartLine property on the result object.
700 GetProduct Retrieves the product for the cart line using the GetProductCollectionHandler handler chain. The product is stored in the ProductDto property on the result object.
800 CreateGetCartLineResult Uses the CreateGetCartLineResult pipeline to transform the cart, order line, and product objects stored on the result object into a GetCartLineResult. The result is stored in the GetCartLineResult property on the result object.

HTTP Verb: PATCH

URL: /api/v1/carts/{cartId}/cartlines/{cartLineId}

Description: Update product information such as qty for a specific shopping cart

Base: HandlerBase<UpdateCartLineParameter, UpdateCartLineResult>

Handlers:

Order Handler

Description

500 UpdateCartLineHandler

Updates a cart line. If cart line not found then handler return error result. If QtyOrdered is 0 or less then handler returns error result.

Order Handler Description
500 GetCartLine Retrieves a cart line using the GetCartLineHandler handler chain. The cart line is found using the CartLineDto and CartId properties on the parameter object. If the CartLineDto is null or the cart line is not found, an error is returned. Otherwise, the cart is stored in the GetCartLineResult property on the result object.
600 UpdateCartLine Updates the quantity ordered, unit of measure, cost code, and line notes on the cart object stored in the GetCartLineResult on the result object. If the quantity ordered is less than zero, an error is returned. If the cost code cannot be edited and the cost code has changed, an error is returned.
700 CopyCustomPropertiesToEntity Copies custom properties from the parameter object to the CartLine object stored in the GetCartLineResult property on the result object.
800 RecalculateCart Recalculates the cart pricing and updates the cart object in the GetCartLineResult property on the result object.
900 CreateGetCartLineResult Uses the CreateGetCartLineResult pipeline to transform the cart, order line, and product objects stored on the result object into a GetCartLineResult. The result is stored in the GetCartLineResult property on the result object.

HTTP Verb: DELETE

URL: /api/v1/carts/{cartId}/cartlines/{cartLineId}

Description: Remove a single product from a specific shopping cart

Base: HandlerBase<RemoveCartLineParameter, RemoveCartLineResult>

Handlers:

Order Handler

Description

500 RemoveCartLineHandler

Removes a cart line. If cart line not found then handler returns error result.

Order Handler Description
500 GetCartLine Retrieves the cart line using the GetCartLineHandler handler chain. The cart line is found using the CartLineId and CartId properties on the parameter object. If the cart line is not found, an error is returned. The cart line along with the cart and associated product id are stored on the result object.
600 RemoveCartLine Removes the cart line from the cart. If the cart now has zero cart lines and the cart status is "AwaitingApproval", the cart status is changed to "Void".
700 GetInventory Updates the QtyLeft product property on the result object now that the cart line has been removed.
800 RecalculateCart Recalculates the cart pricing and updates the cart object in the GetCartResult property on the result object.

HTTP Verb: POST

URL: /api/v1/carts/{cartId}/cartlines/batch

Description: Add a collection of products to a specific shopping cart

Base: HandlerBase<AddCartLineCollectionParameter, AddCartLineCollectionResult>

Handlers:

Order Handler

Description

500 AddCartLineCollectionHandler

Adds a cart line collection to the cart. If collection to add is null then handler returns error result.

Order Handler

Description

500 ValidateContext Verifies that cart lines have been passed in the AddCartLineParameterCollection property on the parameter object. If the property is null, an error is returned.
600 GetCart Retrieves a cart using the GetCartHandler handler chain. The CartId property on the parameter object is used to find the cart. If a cart is not found, an error is returned. The cart is stored in the GetCartResult property on the result object.
700 GetProducts Retrieves the products for each cart line using the GetProductCollectionHandler handler chain. The products are stored in the GetProductCollectionResult property on the result object.
800 AddCartLines Associates the cart with each cart line. Then, copies each of those cart lines to the AddCartLineResultCollection property on the result object. Also each cart line SkipRecalculateCart property is set to "true".
900 RecalculateCart Recalculates the cart pricing and updates the cart in the GetCartResult property on the result object.

HTTP Verb: GET

URL: /api/v1/carts/{cartId}/promotions

Description: Return a collection of promotions applied to a specific shopping cart

Base: HandlerBase<GetPromotionCollectionParameter, GetPromotionCollectionResult>

Handlers:

Order Handler Description
500 GetPromotionCollectionHandler Gets promotion collection.
Order Handler

Description

500 GetCart Retrieves cart for specified CartId parameter and sets cart to result.Cart.
600 CreatePromotionDtos Creates PromotionDto object for each CustomerOrderPromotion in the cart and adds them to result.Promotions.

HTTP Verb: POST

URL: /api/v1/carts/{cartId}/promotions

Description: Apply promotions to a specific shopping cart

Base: HandlerBase<AddPromotionParameter, AddPromotionResult>

Handlers:

Order Handler Description
500 AddPromotionHandler Adds a promotion to the cart. If promotion already applied, expired or already used then handler returns error result.
Order Handler

Description

500 GetCart Retrieves cart for specified CartId parameter and sets cart to result.Cart.
600 ValidatePromotionCode Validates promotion code. If cart already has promotion with this code then returns error. If can't find any promotion for this code then returns error. Sets found promotion to result.PromotionCodePromotion.
700 ApplyPromotion Applies promotion. If promotion code has already been applied to cart then bypass applying. If system does not allow multiple promotions then removes previous promotions before applying.
800 ValidateAppliedPromotion Checks if promotion was applied correctly. If promotion was not applied correctly then removes related OrderPromotionCode and returns reason why promotion was not applied.
900 CreatePromotionDto Creates PromotionDto object and sets it to result.Promotion. Creates promotion display message and adds it to result.Messages collection.

 

HTTP Verb: GET

URL: /api/v1/carts/{cartId}/promotions/{promotionId}

Description: Return a single promotion for a specific shopping cart

Base: HandlerBase<GetPromotionParameter, GetPromotionResult>

Handlers:

Order Handler Description
500 GetPromotionHandler Gets a promotion. If promotion not found then handler returns error result.
Order Handler Description
500 GetCart Retrieves cart for specified CartId parameter and sets cart to result.Cart.
600 CreatePromotionDto Creates PromotionDto object and sets it to result.Promotion.
Do you find this information helpful? Please log in to provide feedback.

Last updated: Dec 11, 2020

Recommended reading