Order Edits

OrderEdit are containers for financial changes after an Order has been placed.

In case no financial aspect of an order should be changed use Order Update which does not perform a recalculation. An alternative if no deliveries or payments occurred could be to replicate the order as a new cart.

The OrderEdit tutorial shows some examples how edits can be performed.

Representations

OrderEdit

  • id - String
    The unique ID of the OrderEdit.
  • version - Number
    The current version of the OrderEdit.
  • createdAt - DateTime
  • lastModifiedAt - DateTime
  • key - String - Optional
    Unique identifier for this edit.
  • resource - Reference to an Order
    The order to be updated with this edit.
  • stagedActions - Array of StagedOrderUpdateAction
    The actions to apply to the Order. Cannot be updated after the edit has been applied.
  • custom - CustomFields - Optional
  • result - OrderEditResult
    Contains a preview of the changes in case of unapplied edit. For applied edits, it contains the summary of the changes.
  • comment - String - Optional
    This field can be used to add textual information regarding the edit.

OrderEditDraft

  • key - String - Optional
    Unique identifier for this edit.
  • resource - Reference to an Order
    The order to be updated with this edit.
  • stagedActions - Array of StagedOrderUpdateAction
    The actions to apply to resource.
  • custom - CustomFieldsDraft - Optional
    The custom fields.
  • comment - String - Optional
    This field can be used to add additional textual information regarding the edit.
  • dryRun - Boolean - Optional, defaults to false
    When set to true the edit is applied on the Order without persisting it.

StagedOrderUpdateAction

See the detailed list of StagedOrderUpdateActions for all update actions available for an OrderEdit.

Many of the update actions for an OrderEdit are known from the update actions available for a Cart. Below is an overview showing the update actions that an Order Edit and a Cart share, as well as the update actions unique to an Order Edit.

The table furthermore provides an overview of the update actions that can only be done within an Order Edit and not as a direct Order update.

Update Action Cart direct Order OrderEdit
setCustomerEmail x x x
setShippingAddress x x x
setBillingAddress x x x
setCountry x - x
recalculate x - -
setShippingMethod x - x
setCustomShippingMethod x - x
addDiscountCode x - x
removeDiscountCode x - x
setCustomerId x x x
setAnonymousId x - -
setCustomerGroup x - x
setCustomType x x x
setCustomField x x x
addPayment x x x
removePayment x x x
setShippingMethodTaxRate x - x
setShippingMethodTaxAmount x - x
setCartTotalTax x - -
setOrderTotalTax - - x
changeTaxMode x - x
setLocale x x x
changeTaxRoundingMode x - x
setShippingRateInput x - x
changeTaxCalculationMode x - x
addShoppingList x - x
setDeleteDaysAfterLastModification x - -
addItemShippingAddress x x x
removeItemShippingAddress x x x
updateItemShippingAddress x x x
setShippingAddressAndShippingMethod - - x
setShippingAddressAndCustomShippingMethod - - x
LineItem update actions      
applyDeltaToLineItemShippingDetailsTargets x - -
setLineItemShippingDetails x x x
addLineItem x - x
removeLineItem x - x
changeLineItemQuantity x - x
setLineItemCustomType x x x
setLineItemCustomField x x x
setLineItemTaxRate x - x
setLineItemTaxAmount x - x
setLineItemTotalPrice x - x
setLineItemPrice x - x
CustomLineItem update actions      
applyDeltaToCustomLineItemShippingDetailsTargets x - -
setCustomLineItemShippingDetails x - -
addCustomLineItem x - x
removeCustomLineItem x - x
setCustomLineItemCustomType x x x
setCustomLineItemCustomField x x x
setCustomLineItemTaxAmount x - x
setCustomLineItemTaxRate x - x
changeCustomLineItemQuantity x - x
changeCustomLineItemMoney x - x

OrderEditResult

Provides information about the state of the OrderEdit. Four possible states exist:

  • NotProcessed
  • PreviewFailure
  • PreviewSuccess
  • Applied

OrderEditResult

OrderEditPreviewSuccess

The result contains a preview field in which the order is presented as it would appear if the stagedActions were to be applied. In a similar fashion, the messagePayloads field contains the message bodies of the order shown in preview.

Please note that the result is generated on the fly when an OrderEdit is called. Its data is not persisted but always dynamically pulled by dry running the update actions from stagedActions on the current order version, NOT from the order version at the time of the edit creation. Therefore, result fields cannot be used in query predicates (except for type "NotProcessed" and "Applied").

  • type - String - "PreviewSuccess"
  • preview - Order (not a reference to Order)
    The order preview. The preview also runs Order API Extensions if there are any.
  • messagePayloads - Array of OrderMessagePayload
    The messages which would be emitted if this edit would be applied.

If reference expansion is used on the resource field, a race condition can occur if the order is updated after the preview is calculated but before resource is expanded, in which case the preview is based on an older order version. This rare case can be detected when the messagePayloads contains an OrderEditApplied Message which has in excerptBeforeEdit a different order version than the expanded order.

OrderEditPreviewFailure

Result if the stagedActions cannnot be applied to the order. Like OrderEditPreviewSuccess the data is calculated on the fly and not queryable.

  • type - String - "PreviewFailure"
  • errors - Array of Error

OrderEditNotProcessed

The edit has not been applied or processed in any way. The type field can be queried.

  • type - String - "NotProcessed"

OrderEditApplied

Contains information about a successful applied edit.

  • type - String - "Applied"
  • appliedAt - DateTime the time stamp when the edit was applied.
  • excerptBeforeEdit - OrderExcerpt
    The summary of the order before the edit was applied.
  • excerptAfterEdit - OrderExcerpt
    The summary of the order after the edit was applied.

OrderExcerpt

A summary about the order concerning total price and version.

  • totalPrice - Money
  • taxedPrice - TaxedPrice - Optional
  • version - the version of the Order.

OrderMessagePayload

It is an OrderMessage without the common Message envelope fields, but still contains the payload and the type of the message.

  • type - String
    The type of the message.

Get OrderEdit

Get OrderEdit by ID

Endpoint: /{projectKey}/orders/edits/{id}
Method: GET
OAuth2 Scopes: view_order_edits:{projectKey}
Response Representation: OrderEdit

Get OrderEdit by Key

Endpoint: /{projectKey}/orders/edits/key={key}
Method: GET
OAuth2 Scopes: view_order_edits:{projectKey}
Response Representation: OrderEdit

Query OrderEdits

Endpoint: /{projectKey}/orders/edits
Method: GET
OAuth2 Scopes: view_order_edits:{projectKey}
Response Representation: PagedQueryResult with the results array of OrderEdit
calculates Order Preview: false
Query Parameters:

Create an OrderEdit

Endpoint: /{projectKey}/orders/edits
Method: POST
OAuth2 Scopes: manage_order_edits:{projectKey}
Request Representation: OrderEditDraft
Response Representation: OrderEdit calculates Order Preview: true

It is possible to create multiple OrderEdits for one order and apply then in sequence to the Order. It is, however, also possible to create multiple OrderEdits in parallel as alternatives to each other and have only one of them be applied to the Order. Please note that the OrderEdit feature in its initial release does not support the tracking or reserving of inventory. An OrderEdit can therefore only be created if the InventoryMode of the order is "None".

Update OrderEdit

Update OrderEdit by ID

Endpoint: /{projectKey}/orders/edits/{id}
Method: POST
OAuth2 Scopes: manage_order_edits:{projectKey}
Response Representation: OrderEdit
calculates Order Preview: true
Fields:

  • version - Number - Required
    The expected version of the OrderEdit on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.
  • actions - Array of UpdateAction - Required
    The list of update actions to be performed on the OrderEdit.
  • dryRun - Boolean - Optional, defaults to false
    When set to true the edit is applied on the Order without persisting it.

Update OrderEdit by Key

Endpoint: /{projectKey}/orders/edits/key={key}
Method: POST
OAuth2 Scopes: manage_order_edits:{projectKey}
Response Representation: OrderEdit calculates Order Preview: true
Fields:

  • version - Number - Required
    The expected version of the OrderEdit on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.
  • actions - Array of UpdateAction - Required
    The list of update actions to be performed on the OrderEdit.
  • dryRun - Boolean - Optional, defaults to false
    When set to true the edit is applied on the Order without persisting it.

Update Actions

SetCustomType

This action sets, overwrites or removes any existing custom type and fields for an existing OrderEdit.

  • action - String - "setCustomType"
  • type - ResourceIdentifier to a Type - Optional
    If set, the custom type is set to this new value.
    If absent, the custom type and any existing custom fields are removed.
  • fields - A valid JSON object, based on the FieldDefinitions of the Type - Optional
    If set, the custom fields are set to this new value.

SetCustomField

This action sets, overwrites or removes any existing custom field for an existing OrderEdit.

SetKey

  • action - String - "setKey"
  • key - String - Optional
    If key is absent or null, this field will be removed if it exists.

SetStagedActions

Replaces the whole stagedActions array. For applied edits the stagedActions cannot be changed.

  • action - String - "setStagedActions"
  • stagedActions - Array of StagedOrderUpdateAction
    The actions to edit the resource.

AddStagedAction

Appends a StagedOrderUpdateAction to the end of the stagedActions array. For applied edits the stagedActions cannot be changed.

SetComment

Sets or unsets the comment.

  • action - String - "setComment"
  • comment - String - Optional

Apply an OrderEdit

Endpoint: /{projectKey}/orders/edits/{id}/apply
Method: POST
OAuth2 Scopes: manage_order_edits:{projectKey}
Response Representation: OrderEdit
Fields:

  • editVersion - Number - Required
    The version of the edit to be applied.
  • resourceVersion - Number - Required
    The current version of the order to which the edit should be applied.

If one or both versions do not match the actual version, then a 409 Conflict response is returned.

When and OrderEdit has been applied, stagedActions can no longer be updated.

An applied edit creates the order message OrderEditApplied if messages are enabled for the project.

Delete OrderEdit by ID

Endpoint: /{projectKey}/orders/edits/{id}
Method: DELETE
OAuth2 Scopes: manage_order_edits:{projectKey} calculates Order Preview: false
Query Parameters:

  • version - Number - Required

Deletion of an OrderEdit does not affect the order.

Delete OrderEdit by Key

Endpoint: /{projectKey}/orders/edits/key={key}
Method: DELETE
OAuth2 Scopes: manage_order_edits:{projectKey} calculates Order Preview: false
Query Parameters:

  • version - Number - Required

Deletion of an OrderEdit does not affect the order.

Detailed List of StagedUpdateActions

Change OrderState

  • action - String - "changeOrderState"
  • orderState - OrderState - Required

This update action produces the OrderStateChanged message.

Change ShipmentState

  • action - String - "changeShipmentState"
  • shipmentState - ShipmentState - Required

This update action produces the OrderShipmentStateChanged message.

Change PaymentState

  • action - String - "changePaymentState"
  • paymentState - PaymentState - Required

Changing the payment state of the order produces the OrderPaymentStateChanged message.

Update SyncInfo

  • action - String - "updateSyncInfo"
  • channel - Reference to a Channel
    Connection to particular synchronization destination.
  • externalId - String - Optional
    Can be used to reference an external order instance, file etc.
  • syncedAt - DateTime - Optional If not provided, then current date would be used

Add ReturnInfo

  • action - String - "addReturnInfo" - Required
  • returnDate - DateTime - Optional
  • returnTrackingId - String - Optional
    Identifies which return tracking ID is connected to this particular return.
  • items - Array of ReturnItemDraft - Required
    The items to be returned.

This update action produces the ReturnInfoAdded message.

Set ReturnShipmentState

In order to set a ReturnShipmentState, there needs to be at least one ReturnInfo with at least one ReturnItem created before.

This update action produces the OrderReturnShipmentStateChanged message.

Set ReturnPaymentState

In order to set a ReturnPaymentState, there needs to be at least one ReturnInfo with at least one ReturnItem created before.

Change the state of LineItem according to allowed transitions

  • action - String - "transitionLineItemState"
  • lineItemId - String
  • quantity - Number
  • fromState - Reference to a State
  • toState - Reference to a State
  • actualTransitionDate - DateTime - Optional

This update action produces the LineItemStateTransition message.

Change the state of CustomLineItem according to allowed transitions

  • action - String - "transitionCustomLineItemState"
  • customLineItemId - String
  • quantity - Number
  • fromState - Reference to a State
  • toState - Reference to a State
  • actualTransitionDate - DateTime - Optional

This update action produces the CustomLineItemStateTransition message.

Import State for LineItems

The import of states does not follow any predefined rules and should be only used if no transitions are defined. The quantity in the ItemStates must match the sum of all LineItems states’ quantities.

  • action - String - "importLineItemState"
  • lineItemId - String
  • state - Array of ItemState

Import State for CustomLineItems

The import of states does not follow any predefined rules and should be only used if no transitions are defined. The quantity in the ItemStates must match the sum of all CustomLineItem states’ quantities.

  • action - String - "importCustomLineItemState"
  • customLineItemId - String
  • state - Array of ItemState

Add Delivery

A Delivery can only be added to an Order if its shippingInfo exists.

This update action produces the DeliveryAdded message and the ParcelAddedToDelivery message if the action contains a Parcel.

Set Delivery Address

Sets the address value on an existing Delivery.

  • action - String - "setDeliveryAddress"
  • deliveryId - String The ID of the Delivery which should be updated.
  • address - Address - Optional
    If not set an existing address is removed from the delivery.

This update action produces the DeliveryAddressSet message.

Add Parcel

In order to add a Parcel, there needs to be at least one Delivery created before.

This update action produces the ParcelAddedToDelivery message.

Set Order Number

Sets a string that uniquely identifies an order. It can be used to create more human-readable (in contrast to ID) identifier for the order.

  • action - String - "setOrderNumber"
  • orderNumber - String - Optional
    It should be unique across a project. Once it’s set, it cannot be changed.

Transition State

Transition to a new state. If there is no state yet, the new state must be an initial state. If the existing state has transitions set, there must be a direct transition to the new state. If transitions is not set, no validation is performed. These validations can be turned off by setting the force parameter to true.

  • action - String - "transitionState"
  • state - Reference to a State
  • force - Boolean - Optional - Defaults to false

Transitioning the state of a product produces the OrderStateTransition message.

Set Customer Email

This action sets, overwrites or removes any existing value for customerEmail.
This action does not change the customer email on the Cart the order has been created from.

  • action - String - "setCustomerEmail"
  • email - String - Optional

This action produces a OrderCustomerEmailSet message.

Set Customer Id

Relates a Customer to the order. In case the customer belongs to a CustomerGroup the order’s field customerGroup would be updated automatically. When applied, no prices or discounts will be re-calculated on the order.

  • action - String - "setCustomerId"
  • customerId - String - Optional
    If set, a Customer with the given ID must exist in the project.

This action produces an OrderCustomerSet message.

Set Shipping Address

This action sets, overwrites or removes any existing value for shippingAddress.
Changing the shipping address does not recalculate the cart. The taxes might not fit to the shipping address anymore.
This action does not change the shipping address on the Cart the order has been created from.

  • action - String - "setShippingAddress"
  • address - Address - Optional

This action produces a OrderShippingAddressSet message.

Set Billing Address

This action sets, overwrites or removes any existing value for billingAddress.
This action does not change the billing address on the Cart the order has been created from.

  • action - String - "setBillingAddress"
  • address - Address - Optional

This action produces a OrderBillingAddressSet message.

Set Custom Type

This action sets, overwrites or removes any existing custom type and fields for an existing order.

Set CustomField

This action sets, overwrites or removes any existing custom field for an existing order.

Set LineItem Custom Type

This action sets, overwrites or removes the existing custom type and fields for an existing order LineItem.

  • action - String - "setLineItemCustomType"
  • type - ResourceIdentifier to a Type - Optional
    If set, the custom type is set to this new value.
    If absent, the custom type and any existing CustomFields are removed at the same time.
  • lineItemId - String
  • fields - A valid JSON object, based on the FieldDefinitions of the Type - Optional
    If set, the custom fields are set to this new value.

Set LineItem CustomField

This action sets, overwrites or removes any existing custom field for an existing order LineItem.

Set CustomLineItem Custom Type

This action sets, overwrites or removes the existing custom type and fields for an existing order CustomLineItem.

  • action - String - "setCustomLineItemCustomType"
  • type - ResourceIdentifier to a Type - Optional
    If set, the custom type is set to this new value.
    If absent, the custom type and any existing CustomFields are removed at the same time.
  • customLineItemId - String
  • fields - A valid JSON object, based on the FieldDefinitions of the Type - Optional
    If set, the custom fields are set to this new value.

Set CustomLineItem CustomField

This action sets, overwrites or removes any existing custom field for an existing order CustomLineItem.

Add Payment

This action adds a payment to the PaymentInfo. The payment must not be assigned to another Order or active Cart yet.

Remove Payment

This action removes a payment from the PaymentInfo.

Set Locale

Sets the locale. Must be one of the languages supported for this Project.

Set Delivery Items

Updates the delivery items of a Delivery.

  • action - String - "setDeliveryItems"
  • deliveryId - String - ID of the Delivery for which the items should be set
  • items - Array of DeliveryItem

This update action produces the DeliveryItemsUpdated message.

Remove Parcel from Delivery

Removes a parcel in a Delivery.

  • action - String - "removeParcelFromDelivery"
  • parcelId - String - ID of the Parcel which shall be removed

This update action produces the ParcelRemovedFromDelivery message.

Remove Delivery

Removes a Delivery.

  • action - String - "removeDelivery"
  • deliveryId - String - ID of the Delivery which shall be removed

This update action produces the DeliveryRemoved message.

Set Parcel Measurements

  • action - String - "setParcelMeasurements"
  • parcelId - String - ID of the Parcel which shall be updated
  • measurements - ParcelMeasurements - Optional

This update action produces the ParcelMeasurementsUpdated message.

Set Parcel Tracking Data

  • action - String - "setParcelTrackingData"
  • parcelId - String - ID of the Parcel which shall be updated
  • trackingData - TrackingData - Optional

This update action produces the ParcelTrackingDataUpdated message.

Set Parcel Items

Updates the items of a Parcel.

  • action - String - "setParcelItems"
  • parcelId - String - ID of the Parcel which shall be updated
  • items - Array of DeliveryItem

This update action produces the ParcelItemsUpdated message.

Set LineItemShippingDetails

Sets the ItemShippingDetails for a line item.

  • action - String - "setLineItemShippingDetails"
  • lineItemId - String
    The ID of the line item that is to be updated.
  • shippingDetails - ItemShippingDetailsDraft - Optional
    The new shipping details for the line item.

Set CustomLineItemShippingDetails

Sets the ItemShippingDetails for a custom line item.

  • action - String - "setCustomLineItemShippingDetails"
  • customLineItemId - String
    The ID of the custom line item that is to be updated.
  • shippingDetails - ItemShippingDetailsDraft - Optional
    The new shipping details for the custom line item.

Add ItemShippingAddress

Add an address to the itemShippingAddresses array.

  • action - String - "addItemShippingAddress"
  • address - Address
    The address must have a key that is unique in this cart/order.

Remove ItemShippingAddress

Removes an address from the itemShippingAddresses array. An address can only be removed if it is not referenced in any ItemShippingTarget.

  • action - String - "removeItemShippingAddress"
  • addressKey - String
    The key of the address that is to be removed

Update ItemShippingAddress

Updates an address in the itemShippingAddresses array.

  • action - String - "updateItemShippingAddress"
  • address - Address
    The address which is to replace the address with the key already present in the array

SetOrderTotalTax

Updates the total tax amount of the order if it has the ExternalAmount TaxMode.

  • action - String - "setOrderTotalTax"
  • externalTotalGross - Money
    The total gross amount of the Order (totalNet + taxes).
  • externalTaxPortions - Array of TaxPortion - Optional

SetShippingAddressAndShippingMethod

Sets the shipping address and shipping method together to prevent an inconsistent state.

SetShippingAddressAndCustomShippingMethod

Sets the shipping address and a custom shipping method together to prevent an inconsistent state.

  • action - String - "setShippingAddressAndCustomShippingMethod"
  • address - Address
  • shippingMethodName - String - Required
  • shippingRate - ShippingRateDraft - Required
    The shipping rate used to determine the price.
  • taxCategory - Reference to a TaxCategory - Optional
    The given tax category will be used to select a tax rate when a order has the TaxMode Platform.
  • externalTaxRate - ExternalTaxRateDraft - Optional
    An external tax rate can be set if the order has the External TaxMode.

Set Country

Sets the country of the cart. When the country is set, the LineItem prices are updated.

  • action - String - "setCountry"
  • country - String - Optional
    A two-digit country code as per ↗ ISO 3166-1 alpha-2 .

Set ShippingMethod

Sets the ShippingMethod. Prerequisite: The cart must contain a shipping address. This update action can fail with an InvalidOperation if the referenced shipping method has a predicate which does not match the cart.

Set Custom ShippingMethod

Sets a custom shipping method (independent of the ShippingMethods defined in the project). The custom shipping method can be unset with the setShippingMethod action without the shippingMethod. Prerequisite: The cart must contain a shipping address.

  • action - String - "setCustomShippingMethod"
  • shippingMethodName - String - Required
  • shippingRate - ShippingRateDraft - Required
    The shipping rate used to determine the price.
  • taxCategory - Reference to a TaxCategory - Optional
    The given tax category will be used to select a tax rate when a cart has the TaxMode Platform.
  • externalTaxRate - ExternalTaxRateDraft - Optional
    An external tax rate can be set if the cart has the External TaxMode.

Add DiscountCode

Adds a DiscountCode to the cart to enable the related CartDiscounts.

  • action - String - "addDiscountCode"
  • code - String - Required
    The code of an existing DiscountCode.

The number of discount codes in a cart is limited to 10.

Specific Error Codes:

Remove DiscountCode

Removes a discount code from the cart.

Set Customer Group

Sets the customer group of the cart. The LineItem prices will be updated according to the customer group.
This action cannot be used if a customer is assigned to the cart. In that case the platform will automatically select the customer group the respective customer is assigned to.

Set Custom Type

This action sets, overwrites or removes any existing custom type and fields for an existing cart.

  • action - String - "setCustomType"
  • type - ResourceIdentifier to a Type - Optional
    If set, the custom type is set to this new value.
    If absent, the custom type and any existing custom fields are removed.
  • fields - A valid JSON object, based on the FieldDefinitions of the Type - Optional
    If set, the custom fields are set to this new value.

Set CustomField

This action sets, overwrites or removes any existing custom field for an existing cart.

Set ShippingMethod TaxAmount

A shipping method tax amount can be set if the cart has the ExternalAmount TaxMode.

Set ShippingMethod TaxRate

A shipping method tax rate can be set if the cart has the External TaxMode.

Change TaxMode

Changes the TaxMode of a cart. When a tax mode is changed from External to Platform or Disabled, all previously set external tax rates will be removed. When changing the tax mode to Platform, line items, custom line items and shipping method require a tax category with a tax rate for the given shipping address.

  • action - String - "changeTaxMode"
  • taxMode - TaxMode

Change Tax RoundingMode

Changes the tax RoundingMode of a cart. When changing the tax rounding mode, the taxes are recalculated.

  • action - String - "changeTaxRoundingMode"
  • taxRoundingMode - RoundingMode

Set ShippingRateInput

The shippingRateInput is used as an input to select a ShippingRatePriceTier. If no matching tier can be found, or the input is not set, the default price is used.

Change TaxCalculationMode

Changes the TaxCalculationMode of a cart. When changing the tax calculation mode, the taxes are recalculated.

Add Shopping List

Adds all LineItems of a ShoppingList to the cart.

Add LineItem

Adds a product variant in the given quantity to the cart.

If the cart already contains a line item for the same product variant with the same LineItemMode, custom fields, supply and distribution channel, then only the quantity of the existing LineItem is increased. If shippingDetails are set, they will be merged, meaning all addresses will be present afterwards and, for address keys present in both shipping details, the quantity will be summed up. A new line item will always be added when the externalPrice or the externalTotalPrice is set in this update action.
The LineItem price is set as described in LineItem Price selection.

Specific Error Codes:

Remove LineItem

Decreases the quantity of the given LineItem. The LineItem price is updated as described in LineItem Price selection.

  • action - String - "removeLineItem"
  • lineItemId - String - Required
    ID of an existing LineItem in the cart.
  • quantity - Number - Optional If the quantity is absent or the line item quantity drops to less than 1, the line item is removed from the cart.
  • externalPrice - BaseMoney - Optional
    Sets the line item price to the given value when decreasing the quantity of a line item with the ExternalPrice LineItemPriceMode priceMode.
  • externalTotalPrice - ExternalLineItemTotalPrice - Optional
    Sets the line item price and totalPrice to the given values when decreasing the quantity of a line item with the ExternalTotal LineItemPriceMode priceMode.
  • shippingDetailsToRemove - ItemShippingDetailsDraft - Optional
    Container for line item specific address(es) that are to be removed.

Change LineItem Quantity

Sets the quantity of the given LineItem.
If quantity is 0, the line item is removed from the cart.
The LineItem price is updated as described in LineItem Price selection.

ChangeLineItemQuantity does not support changing the shipping details when multiple shipping addresses are set for one line item. RemoveLineItem and AddLineItem support this, but not ChangeLineItem. This is the case because it is not possible to deduct how the distribution of sub-quantities should be adapted in accordance with the overall change in the line item quantity. Thus, the shippingDetails field will be kept in its current state in order to avoid data loss. Use SetLineItemShippingDetails in combination with this update action in one cart update command to change the line item quantity and shipping details together.

  • action - String - "changeLineItemQuantity"
  • lineItemId - String - Required
    ID of an existing LineItem in the cart.
  • quantity - Number - Required
  • externalPrice - BaseMoney - Optional
    Sets the line item price to the given value when changing the quantity of a line item with the ExternalPrice LineItemPriceMode priceMode.
  • externalTotalPrice - ExternalLineItemTotalPrice - Optional
    Sets the line item price and totalPrice to the given values when changing the quantity of a line item with the ExternalTotal LineItemPriceMode priceMode.

Set LineItem TaxRate

A line item tax rate can be set if the cart has the External TaxMode.

  • action - String - "setLineItemTaxRate"
  • lineItemId - String
  • externalTaxRate - ExternalTaxRateDraft - Optional

Set LineItem TaxAmount

A line item tax amount can be set if the cart has the ExternalAmount TaxMode.

  • action - String - "setLineItemTaxAmount"
  • lineItemId - String
  • externalTaxAmount - ExternalTaxAmountDraft - Optional

Set LineItem Price

Sets the price of a line item and changes the priceMode of the line item to ExternalPrice LineItemPriceMode. If the price mode of the line item is ExternalPrice and no externalPrice is given, the external price is unset and the priceMode is set to Platform.

  • action - String - "setLineItemPrice"
  • lineItemId - String
  • externalPrice - BaseMoney - Optional

Set LineItem TotalPrice

Sets the totalPrice and price of a line item and changes the priceMode of the line item to ExternalTotal LineItemPriceMode. If the price mode of the line item is ExternalTotal and no externalTotalPrice is given, the external price is unset and the priceMode is set to Platform.

Add CustomLineItem

Adds a CustomLineItem to the cart.

If the cart already contains a CustomLineItem with the same slug, name, money, tax category, state, and custom fields, then only the quantity of the existing custom line item is increased. If shippingDetails are set, they will be merged, meaning all addresses will be present afterwards and, for address keys present in both shipping details, the quantity will be summed up. If the cart already contains a custom line item with the same slug that is otherwise not identical, an InvalidOperation error is returned.

  • action - String - "addCustomLineItem"
  • name - LocalizedString
  • quantity - Number - Optional - Defaults to 1
  • money - BaseMoney
  • slug - String
  • taxCategory - Reference to a TaxCategory - Required only for Platform TaxMode
    The given tax category will be used to select a tax rate when a cart has the tax mode Platform.
  • externalTaxRate - ExternalTaxRateDraft - Optional
    An external tax rate can be set if the cart has the External TaxMode.
  • custom - CustomFieldsDraft - Optional
    The custom fields.
  • shippingDetails - ItemShippingDetailsDraft - Optional
    Container for custom line item specific address(es).

Specific Error Codes:

Remove CustomLineItem

Removes the custom CustomLineItem from the cart.

Removing a custom line item does not support specifying a quantity, unlike the removal of line items. Consequently, there is no support to partially remove shippingDetails using this update action. See Change CustomLineItem Quantity for that.

  • action - String - "removeCustomLineItem"
  • customLineItemId - String - Required
    ID of an existing CustomLineItem in the cart.

Change CustomLineItem Quantity

Sets the quantity of the given CustomLineItem.

ChangeCustomLineItemQuantity does not support changing the shipping details when multiple shipping addresses are set for one custom line item. AddCustomLineItem support this. This is the case because it is not possible to deduct how the distribution of sub-quantities should be adapted in accordance with the overall change in the custom line item quantity. Thus, the shippingDetails field will be kept in its current state in order to avoid data loss. Use SetCustomLineItemShippingDetails in combination with this update action in one cart update command to change the custom line item quantity and shipping details together.

  • action - String - "changeCustomLineItemQuantity"
  • customLineItemId - String - Required
    ID of an existing CustomLineItem in the cart.
  • quantity - Number - Required
    The new quantity being a value >= 0. If quantity is 0, the custom line item will be removed from the cart.

Change CustomLineItem Money

Sets the money of the given CustomLineItem.

  • action - String - "changeCustomLineItemMoney"
  • customLineItemId - String - Required
    ID of an existing CustomLineItem in the cart.
  • money - BaseMoney - Required
    The new money.

Set CustomLineItem Custom Type

This action sets, overwrites or removes the custom type and fields for an existing CustomLineItem.

  • action - String - "setCustomLineItemCustomType"
  • type - ResourceIdentifier to a Type - Optional
    If set, the custom type is set to this new value.
    If absent, the custom type and any existing CustomFields are removed at the same time.
  • customLineItemId - String
  • fields - A valid JSON object, based on the FieldDefinitions of the Type - Optional
    If set, the custom fields are set to this new value.

Set CustomLineItem CustomField

This action sets, overwrites or removes any existing custom field for an existing CustomLineItem.

Set CustomLineItem TaxRate

A custom line item tax rate can be set if the cart has the External TaxMode.

  • action - String - "setCustomLineItemTaxRate"
  • customLineItemId - String
  • externalTaxRate - ExternalTaxRateDraft - Optional

Set CustomLineItem TaxAmount

A custom line item tax amount can be set if the cart has the ExternalAmount TaxMode.

  • action - String - "setCustomLineItemTaxAmount"
  • customLineItemId - String
  • externalTaxAmount - ExternalTaxAmountDraft - Optional