HomeGuides
Submit Documentation FeedbackJoin Developer CommunityLog In

Cart

This topic describes the Cart API handler.

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:

OrderHandler

Description

500GetCartsQueryCreates 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.
600ApplyFilteringApplies 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.
700ApplySortApplies 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.
800ApplyPagingApplies 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).
900ExecuteQueryExecutes the CartsQuery after the query has been expanded, filtered, sorted, and paged. The result is stored in the Carts property on the result object.
1000GetCartPricesFor 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:

OrderHandler

Description

500GetCartRetrieves 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.
600ValidateCustomersIf either the bill-to or ship-to customer on the cart are NOT active, an error is returned.
700ValidateAvailabilityChecks 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.
800SetCurrencySets 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.
850GetCartRealTimeInventoryIf 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.
900RecalculateCartRecalculates 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".
1000PopulateUserDataIf 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
1100PopulateCustomersResultsUses 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.
1200PopulateCountsPopulates 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)
1300PopulateCanCheckOutDefaults 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".
1400PopulateCanModifyOrderPopulates 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.
1500PopulateSettingsPopulates properties on the result object using a combination of settings and other data. See additional information below.
1600CopyCustomPropertiesToResultCopies custom properties configured for the customerOrder entity to the Properties property on the result object.
1700CalculateShippingUses 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".
1800CalculateTaxesUses 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.
1900PopulateTotalsPopulates 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
2000PopulateCanBypassCheckoutAddressIf 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".
2100PopulateCarriersPopulates 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.
2200PopulatePaymentOptionsPopulates 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.
2300PopulateQuoteRequiredCountReports 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.
2400PopulateCostCodesAdds 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".
2500GetCartLinesRetrieves 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".
2600GetRestrictionsDetermines 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".
2650SetIsAwaitingApprovalDetermines 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
2700SetRequiresApprovalDetermines 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.
2800GetCreditCardBillingAddressSets the result CreditCardBillingAddress from parsing the latest successful CreditCardTransaction.AvsAddr is there is one.
2900PopulateWarehousesIf 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.
3000GetPunchoutSettingsUpdates 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".
3100GetAlsoPurchasedProductsIf 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

PropertyDescription
CanSaveOrderIndicates 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.
CanRequestQuoteIndicates 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.
CanEditCostCodeThe Budgets and Order Approval Settings "Cost Code Editing" setting.
ShowCostCodeIndicates whether or not the current bill-to customer is NOT null and the "Show Cost Codes" setting equals "true".
ShowPoNumberThe Checkout Settings "Enable Purchase Orders" setting.
ShowPayPalThe Payment Settings "Show PayPal" setting.
ShowCreditCardThe Checkout Settings "Enable Credit Card as Payment Method" setting.
ShowTaxAndShippingThe Cart Settings "Show Tax & Shipping Amount in Cart" setting.
ShowLineNotesThe Cart Settings "Show Order Line Notes" setting.
ShowNewsletterSignupThe Checkout Settings "Show Subscription Signup During Checkout" setting.
RequiresPoNumberThe 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:

OrderHandlerDescription
450ValidateContextValidates that a credit card payment method is accompanied by a credit card number.
500GetCartRetrieves 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.
600CopyCustomPropertiesToCartCopies custom properties configured for the customerOrder entity to the Cart object stored in the GetCartResult property on the result object.
700SetBillToSets 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).
800SetShipToSets 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".
900UpdateCartThe following properties on the cart object is updated using the same properties on the parameter object:
  • OrderDate
  • Notes
  • CustomerPO
  • TermsCode
  • RequestedDeliveryDate
1000RecalculateCartRecalculates 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.
1050SetupPaypalPaymentIf 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.
1100SetShipViaCalculates 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.
1200SetCurrencySets 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".
1300UpdateCartSubmitForRequisitionUpdates 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".
1400SaveCartSets 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.
1500MoveSavedOrderInToCartMoves 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.
1600ChangeStatusToAwaitingApprovalChanges 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".
1700MoveQuoteRequiredLinesBackToCartMoves and CartLines that have a Product that requires a quote out of the cart being submitted and in to the new shopping cart.
1800ChangeStatusToCartApproves 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.
1900ChangeStatusToSubmittedSubmits 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.
2000UpdateCartRequestQuoteUpdates 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.
2100UpdateCartProposeQuoteUpdates 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.
2200UpdateCartJobAcceptedUpdates the cart status to "JobAccepted" when a job quote is accepted. Also, updates the pricing for the quote.
2300SubmitCartUpdates 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.
2400ProcessInventoryUpdates 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.
2500ProcessSubscriptionPurchaseAdds a new subscription for any products purchased as a subscription. If the cart does not have a status of "Submitted", this handler is skipped.
2700ProcessGiftCardTransactionsApplies 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.
2800ProcessCreditCardTransactionsSubmits 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.
2900PostThirdPartyTaxInvokes 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.
3000SubmitOrderToErpSubmits 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.
3100PopulateConfirmationEmailModelPopulates 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.
3200SendConfirmationEmailSends 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.
3300CreateOrderHistoryCreates 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.
3400CopyCustomPropertiesToResultAdds active custom properties configured for customerOrder to the Properties collection stored on the result object.
3500CreateGetCartResultRetrieves the submitted cart, transforms it into a GetCartResult, and stores it in the GetCartResult property on the result object.
3600UpdateExperimentUpdates active experiments (A/B testing data) with order data if the cart was submitted.

Order 2000 UpdateCartRequestQuote specifications

Cart PropertySets Value To
PlacedByUserProfileThe user profile noted in the UserProfileId property on the parameter object. If that property does not have a value, the current user is used.
PlacedByUserNameThe username of the user in the PlacedByUserProfile property.
OrderNumberThe next order number that is generated.
CurrencyId, CurrencyThe current currency if the cart currency is null.
DefaultWarehouseId, DefaultWarehouseThe current warehouse if the cart default warehouse is null.
Type"Job" if the quote is a job quote, otherwise "Quote".
CustomerReference1The job quote name.
RecalculateTaxTrue
SalespersonIf the cart has no salesperson, the customer default salesperson is used.
StatusThe 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:

OrderHandlerDescription
500GetCartRetrieves 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.
600ValidateCartValidates 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.
700RemovePromotionsRemoves promotions that have already been applied to the cart. If the status has already been set to "Void", this handler is skipped.
800RemoveCartDeletes 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:

OrderHandlerDescription
500GetCartHandlerGets cart. If CartId parameter not specified then handler create new cart using current context.
600GetCartApprovalHandlerSet 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.
800GetCartPunchOutHandlerIf 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>


πŸ“˜

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.

OrderHandlerDescription
500GetCartRetrieves 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.
600GetProductRetrieves 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.
700CopyCustomPropertiesCopies 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.
800AddCartLineAdds 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.
900RecalculateCartRecalculates 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.
1000CreateGetCartLineResultUses 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.
1100AddCartLineRequisitionIf 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:

OrderHandlerDescription
500GetCartRetrieves 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.
600GetCartLineRetrieves 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.
700GetProductRetrieves the product for the cart line using the GetProductCollectionHandler handler chain. The product is stored in the ProductDto property on the result object.
800CreateGetCartLineResultUses 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:

OrderHandlerDescription
500GetCartLineRetrieves 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.
600UpdateCartLineUpdates 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.
700CopyCustomPropertiesToEntityCopies custom properties from the parameter object to the CartLine object stored in the GetCartLineResult property on the result object.
800RecalculateCartRecalculates the cart pricing and updates the cart object in the GetCartLineResult property on the result object.
900CreateGetCartLineResultUses 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:

OrderHandlerDescription
500GetCartLineRetrieves 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.
600RemoveCartLineRemoves 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".
700GetInventoryUpdates the QtyLeft product property on the result object now that the cart line has been removed.
800RecalculateCartRecalculates 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:

OrderHandlerDescription
500ValidateContextVerifies that cart lines have been passed in the AddCartLineParameterCollection property on the parameter object. If the property is null, an error is returned.
600GetCartRetrieves 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.
700GetProductsRetrieves the products for each cart line using the GetProductCollectionHandler handler chain. The products are stored in the GetProductCollectionResult property on the result object.
800AddCartLinesAssociates 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".
900RecalculateCartRecalculates 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:

OrderHandlerDescription
500GetCartRetrieves cart for specified CartId parameter and sets cart to result.Cart.
600CreatePromotionDtosCreates 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:

OrderHandlerDescription
500GetCartRetrieves cart for specified CartId parameter and sets cart to result.Cart.
600ValidatePromotionCodeValidates 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.
700ApplyPromotionApplies 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.
800ValidateAppliedPromotionChecks if promotion was applied correctly. If promotion was not applied correctly then removes related OrderPromotionCode and returns reason why promotion was not applied.
900CreatePromotionDtoCreates 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:

OrderHandlerDescription
500GetPromotionHandlerGets a promotion. If promotion not found then handler returns error result.

Did this page help you?