Documentation

This is the early access documentation preview for Custom Views. This documentation might not be in sync with our official documentation.

Editing Placed Orders

This tutorial explains how to edit an already placed order.

Order Edits versus Direct Order Updates

The first aspect to be aware of when it comes to order editing is the difference between an OrderEdit and a direct order update. The basic principle of an OrderEdit is that it implies financial changes to the purchase agreement. When, for example, line items are to be removed, added, or have their quantity changed, the agreement of the order is changed in a manner that the order total is impacted. Update actions like these have to be captured and processed under an OrderEdit. Direct order updates, on the other hand, do not impact the order total. When ,for example, the status of the order or a line item is updated, or delivery details are added to the order, these update actions can be performed directly on the order and do not have to be performed through an OrderEdit.

Here is an overview of the order properties that can be updated directly and the properties that have to be updated through an OrderEdit:

Properties that can be updated directly:

  • Order Number
  • States
  • Locale
  • Customer Email Address
  • Billing Address
  • Shipping Address *
  • Payment Info
  • Return Info
  • Deliveries
  • Sync Info

Properties that have to be updated through an OrderEdit:

  • Line Items
  • Custom Line Items
  • Shipping Address *
  • Shipping Rate Input
  • Discounts

Please note that it is possible to update all the properties from the first list under an OrderEdit as well. When an OrderEdit is created because financial aspects of the agreement are to be changed, non-financial properties, such as for example, email address change, can be updated alongside the financial ones.

(*) You may notice that Shipping Address is listed twice. State and country of a shipping address are used to identify shipping method and rate for an order. This evaluation will, however, only be triggered when the changes to state and country occur within an OrderEdit. If change to state and country is performed via a direct order update, no evaluation of the shipping method and rate will occur.

Example Order Used In This tutorial

Throughout this tutorial, order editing will be illustrated using the order seen below. It is an order with ID "b1065dc8-71c8-4e19-ae3c-1d62df4fec8f" and contains line items of product 1, product 2 and product 3 with a cart discount of 10% on all line items.

{
  "id": "b1065dc8-71c8-4e19-ae3c-1d62df4fec8f",
  "version": 1,
  "totalPrice": {
    "centAmount": 126000
  },
  "lineItems": [
    {
      "id": "c911b62d-353a-4388-93ee-8d488d9af962",
      "quantity": 10,
      "productId": "7c8f813e-6a7d-42d4-8f4e-1a17acdc3724",
      "name": {
        "en": "product 1"
      },
      "price": {
        "value": {
          "centAmount": 1000
        }
      },
      "discountedPricePerQuantity": {
        "discountedPrice": {
          "includedDiscounts": [
            {
              "discount": {
                "typeId": "cart-discount",
                "id": "5422c3d1-7529-4446-bc1b-786c3a38e44f"
              },
              "discountedAmount": {
                "centAmount": 100
              }
            }
          ]
        }
      },
      "totalPrice": {
        "centAmount": 9000
      }
    },
    {
      "id": "aca11e06-38b4-4e0f-be22-97558eb9bd26",
      "quantity": 20,
      "productId": "055b24da-816e-4ddf-858e-cbaab3cba23c",
      "name": {
        "en": "product 2"
      },
      "price": {
        "value": {
          "centAmount": 2000
        }
      },
      "discountedPricePerQuantity": {
        "discountedPrice": {
          "includedDiscounts": [
            {
              "discount": {
                "typeId": "cart-discount",
                "id": "5422c3d1-7529-4446-bc1b-786c3a38e44f"
              },
              "discountedAmount": {
                "centAmount": 200
              }
            }
          ]
        }
      },
      "totalPrice": {
        "centAmount": 36000
      }
    },
    {
      "id": "2c39acfe-a004-4e44-86a7-b0ea1e9b7483",
      "quantity": 30,
      "productId": "674a1c66-e76b-40f2-b410-0c0dcbedc388",
      "name": {
        "en": "product 3"
      },
      "price": {
        "value": {
          "centAmount": 3000
        }
      },
      "discountedPricePerQuantity": {
        "discountedPrice": {
          "includedDiscounts": [
            {
              "discount": {
                "typeId": "cart-discount",
                "id": "5422c3d1-7529-4446-bc1b-786c3a38e44f"
              },
              "discountedAmount": {
                "centAmount": 300
              }
            }
          ]
        }
      },
      "totalPrice": {
        "centAmount": 81000
      }
    }
  ],
  "inventoryMode": "None",
  "shippingAddress": {
    "country": "DE"
  }
}

Anatomy of an Order Edit

Before illustrating how the above order can be edited, let us first give an overview of the anatomy of an OrderEdit. It is important to think of an OrderEdit as an entity in its own right and not just an action applied to an order. Thus, an OrderEdit consists mainly of the fields id, version, resource, comment, stagedActions, result.

Resource

The resource refers to the order that is to be edited. It can be used with reference expansion with the query parameter expand=resource to get the current data of the Order into the obj field.

{
  "resource": {
    "id": "b1065dc8-71c8-4e19-ae3c-1d62df4fec8f",
    "typeId": "order",
    "obj": {
      "totalPrice": {
        "centAmount": 126000
      },
      "lineItems": [
        {
          "quantity": 10,
          "id": "c911b62d-353a-4388-93ee-8d488d9af962",
          "totalPrice": {
            "centAmount": 9000
          }
        },
        {
          "quantity": 20,
          "id": "aca11e06-38b4-4e0f-be22-97558eb9bd26",
          "totalPrice": {
            "centAmount": 36000
          }
        },
        {
          "quantity": 30,
          "id": "2c39acfe-a004-4e44-86a7-b0ea1e9b7483",
          "totalPrice": {
            "centAmount": 81000
          }
        }
      ]
    }
  }
}

Comment

The comment allows you to document the reason for creating the OrderEdit.

{
  "comment": "The customer called immediately after creating the order to correct the quantities."
}

StagedActions

The stagedActions array contains the update actions which are intended to be applied to the order. The OrderEdit can be thought of as an umbrella entity that encapsulates a series of updates. Once an OrderEdit has been applied, it is no longer possible to update the stagedActions or to apply them again.

{
  "stagedActions": [
    {
      "action": "changeLineItemQuantity",
      "lineItemId": "c911b62d-353a-4388-93ee-8d488d9af962",
      "quantity": 23
    }
  ]
}

Result

The polymorphic result fields holds the state of the OrderEdit.

NotProcessed

Unapplied OrderEdits appear in the OrderEdit query endpoint as NotProcessed.

{
  "result": {
    "type": "NotProcessed"
  }
}

PreviewSuccess

Unapplied valid OrderEdits which are fetched or updated via key or ID contain a preview of the updated order as well as the messages that would be emitted if applied.

{
  "result": {
    "type": "PreviewSuccess",
    "preview": {
      "totalPrice": {
        "centAmount": 137700
      },
      "lineItems": [
        {
          "quantity": 23,
          "id": "c911b62d-353a-4388-93ee-8d488d9af962",
          "discountedPricePerQuantity": {
            "discountedPrice": {
              "includedDiscounts": [
                {
                  "discount": {
                    "typeId": "cart-discount",
                    "id": "5422c3d1-7529-4446-bc1b-786c3a38e44f"
                  },
                  "discountedAmount": {
                    "centAmount": 100
                  }
                }
              ]
            }
          },
          "totalPrice": {
            "centAmount": 20700
          }
        },
        {
          "quantity": 20,
          "id": "aca11e06-38b4-4e0f-be22-97558eb9bd26",
          "discountedPricePerQuantity": {
            "discountedPrice": {
              "includedDiscounts": [
                {
                  "discount": {
                    "typeId": "cart-discount",
                    "id": "5422c3d1-7529-4446-bc1b-786c3a38e44f"
                  },
                  "discountedAmount": {
                    "centAmount": 200
                  }
                }
              ]
            }
          },
          "totalPrice": {
            "centAmount": 36000
          }
        },
        {
          "quantity": 30,
          "id": "2c39acfe-a004-4e44-86a7-b0ea1e9b7483",
          "discountedPricePerQuantity": {
            "discountedPrice": {
              "includedDiscounts": [
                {
                  "discount": {
                    "typeId": "cart-discount",
                    "id": "5422c3d1-7529-4446-bc1b-786c3a38e44f"
                  },
                  "discountedAmount": {
                    "centAmount": 300
                  }
                }
              ]
            }
          },
          "totalPrice": {
            "centAmount": 81000
          }
        }
      ]
    },
    "messagePayloads": [
      {
        "lineItem": {
          "id": "c911b62d-353a-4388-93ee-8d488d9af962",
          "quantity": 23,
          "discountedPrice": {
            "value": {
              "centAmount": 900
            },
            "includedDiscounts": [
              {
                "discount": {
                  "typeId": "cart-discount",
                  "id": "5422c3d1-7529-4446-bc1b-786c3a38e44f"
                },
                "discountedAmount": {
                  "centAmount": 100
                }
              }
            ]
          },
          "discountedPricePerQuantity": [
            {
              "quantity": 10,
              "discountedPrice": {
                "value": {
                  "centAmount": 900
                },
                "includedDiscounts": [
                  {
                    "discount": {
                      "typeId": "cart-discount",
                      "id": "5422c3d1-7529-4446-bc1b-786c3a38e44f"
                    },
                    "discountedAmount": {
                      "centAmount": 100
                    }
                  }
                ]
              }
            }
          ],
          "totalPrice": {
            "centAmount": 9000
          }
        },
        "addedQuantity": 13,
        "type": "OrderLineItemAdded"
      },
      {
        "lineItemId": "c911b62d-353a-4388-93ee-8d488d9af962",
        "discountedPricePerQuantity": [
          {
            "quantity": 23,
            "discountedPrice": {
              "value": {
                "centAmount": 900
              },
              "includedDiscounts": [
                {
                  "discount": {
                    "typeId": "cart-discount",
                    "id": "5422c3d1-7529-4446-bc1b-786c3a38e44f"
                  },
                  "discountedAmount": {
                    "centAmount": 100
                  }
                }
              ]
            }
          }
        ],
        "totalPrice": {
          "centAmount": 20700
        },
        "taxedPrice": {
          "totalNet": {
            "centAmount": 17395
          },
          "totalGross": {
            "centAmount": 20700
          }
        },
        "type": "OrderLineItemDiscountSet"
      },
      {
        "edit": {
          "typeId": "order-edit",
          "id": "f745cccd-31cf-49f2-94ea-5c2bebb38b6e"
        },
        "result": {
          "type": "Applied",
          "appliedAt": "2018-09-25T14:33:45.926Z",
          "excerptBeforeEdit": {
            "totalPrice": {
              "centAmount": 126000
            },
            "taxedPrice": {
              "totalNet": {
                "centAmount": 105882
              },
              "totalGross": {
                "centAmount": 126000
              },
              "taxPortions": [
                {
                  "rate": 0.19,
                  "amount": {
                    "centAmount": 20118
                  },
                  "name": "de"
                }
              ]
            },
            "version": 1
          },
          "excerptAfterEdit": {
            "totalPrice": {
              "centAmount": 137700
            },
            "taxedPrice": {
              "totalNet": {
                "centAmount": 115714
              },
              "totalGross": {
                "centAmount": 137700
              },
              "taxPortions": [
                {
                  "rate": 0.19,
                  "amount": {
                    "centAmount": 21986
                  },
                  "name": "de"
                }
              ]
            },
            "version": 5
          }
        },
        "type": "OrderEditApplied"
      }
    ]
  }
}

PreviewFailure

Unapplied invalid OrderEdits which are fetched or updated via key or ID return an array of errors.

{
  "result": {
    "errors": [
      {
        "code": "InvalidField",
        "message": "The value '-1' is not valid for field 'quantity'. Negative quantity is not allowed.",
        "action": {
          "action": "changeLineItemQuantity",
          "lineItemId": "c911b62d-353a-4388-93ee-8d488d9af962",
          "quantity": -1
        },
        "actionIndex": 1,
        "invalidValue": -1,
        "field": "quantity"
      }
    ],
    "type": "PreviewFailure"
  }
}

Applied

The state when an edit has taken effect on the order:

  • the order version that the OrderEdit resulted in, as well as the order version the OrderEdit was applied to
  • a timestamp capturing when the OrderEdit was applied
  • the totalPrice and the taxedPrice before and after the OrderEdit was applied
{
  "result": {
    "type": "Applied",
    "appliedAt": "2018-09-25T14:33:50.505Z",
    "excerptBeforeEdit": {
      "totalPrice": {
        "centAmount": 126000
      },
      "taxedPrice": {
        "totalNet": {
          "centAmount": 105882
        },
        "totalGross": {
          "centAmount": 126000
        },
        "taxPortions": [
          {
            "rate": 0.19,
            "amount": {
              "centAmount": 20118
            },
            "name": "de"
          }
        ]
      },
      "version": 1
    },
    "excerptAfterEdit": {
      "totalPrice": {
        "centAmount": 109800
      },
      "taxedPrice": {
        "totalNet": {
          "centAmount": 92269
        },
        "totalGross": {
          "centAmount": 109800
        },
        "taxPortions": [
          {
            "rate": 0.19,
            "amount": {
              "centAmount": 17531
            },
            "name": "de"
          }
        ]
      },
      "version": 12
    }
  }
}

Order Edit Flow

The basic flow for an OrderEdit is to:

  • Create an order edit
  • Configure intended changes
  • Review the preview
  • Apply the order edit

In the following, each step will be explained with examples.

1. Create an Order Edit

To create an OrderEdit, the endpoint POST /{projectKey}/orders/edits is called.

When you create an OrderEdit, there is no pointer to a specific order version and no properties from the order are copied and persisted into the OrderEdit. The OrderEdit is merely a staging area that captures the intended changes that are to be performed on the order.

It is possible to create several OrderEdits in parallel for the same order. As mentioned above, an OrderEdit can be given a comment which allows you to for example, document the reason for creating the OrderEdit.

In the following example, you can see that the OrderEdit intends to change the quantity of a line item of the order "b1065dc8-71c8-4e19-ae3c-1d62df4fec8f":

{
  "resource": {
    "id": "b1065dc8-71c8-4e19-ae3c-1d62df4fec8f",
    "typeId": "order"
  },
  "stagedActions": [
    {
      "action": "changeLineItemQuantity",
      "lineItemId": "c911b62d-353a-4388-93ee-8d488d9af962",
      "quantity": 23
    }
  ],
  "comment": "The customer called immediately after creating the order to correct the quantities."
}

Once an OrderEdit has been created, it is possible to query it to retrieve the current set of updates it encapsulates. This is done by performing the following query: GET /{projectKey}/orders/edits.

2. Configure Intended Changes

To capture the intended changes an OrderEdit should encapsulate, you post update actions to /{projectKey}/orders/edits/{editId}. If for example, you wish to remove one line item and change the quantity to 33 for another line item, you post the following:

{
  "version": 1,
  "actions": [
    {
      "action": "addStagedAction",
      "stagedAction": {
        "action": "removeLineItem",
        "lineItemId": "aca11e06-38b4-4e0f-be22-97558eb9bd26"
      }
    },
    {
      "action": "addStagedAction",
      "stagedAction": {
        "action": "changeLineItemQuantity",
        "lineItemId": "2c39acfe-a004-4e44-86a7-b0ea1e9b7483",
        "quantity": 33
      }
    }
  ]
}

and get the edit with the updated stagedActions:

{
  "id": "f745cccd-31cf-49f2-94ea-5c2bebb38b6e",
  "version": 3,
  "resource": {
    "id": "b1065dc8-71c8-4e19-ae3c-1d62df4fec8f",
    "typeId": "order"
  },
  "comment": "The customer called immediately after creating the order to correct the quantities.",
  "stagedActions": [
    {
      "action": "changeLineItemQuantity",
      "lineItemId": "c911b62d-353a-4388-93ee-8d488d9af962",
      "quantity": 23
    },
    {
      "action": "removeLineItem",
      "lineItemId": "aca11e06-38b4-4e0f-be22-97558eb9bd26"
    },
    {
      "action": "changeLineItemQuantity",
      "lineItemId": "2c39acfe-a004-4e44-86a7-b0ea1e9b7483",
      "quantity": 33
    }
  ],
  "result": {
    "type": "PreviewSuccess",
    "preview": {
      "totalPrice": {
        "centAmount": 109800
      },
      "lineItems": [
        {
          "quantity": 23,
          "id": "c911b62d-353a-4388-93ee-8d488d9af962",
          "discountedPricePerQuantity": {
            "discountedPrice": {
              "includedDiscounts": [
                {
                  "discount": {
                    "typeId": "cart-discount",
                    "id": "5422c3d1-7529-4446-bc1b-786c3a38e44f"
                  },
                  "discountedAmount": {
                    "centAmount": 100
                  }
                }
              ]
            }
          },
          "totalPrice": {
            "centAmount": 20700
          }
        },
        {
          "quantity": 33,
          "id": "2c39acfe-a004-4e44-86a7-b0ea1e9b7483",
          "discountedPricePerQuantity": {
            "discountedPrice": {
              "includedDiscounts": [
                {
                  "discount": {
                    "typeId": "cart-discount",
                    "id": "5422c3d1-7529-4446-bc1b-786c3a38e44f"
                  },
                  "discountedAmount": {
                    "centAmount": 300
                  }
                }
              ]
            }
          },
          "totalPrice": {
            "centAmount": 89100
          }
        }
      ]
    },
    "messagePayloads": [
      {
        "lineItem": {
          "id": "c911b62d-353a-4388-93ee-8d488d9af962",
          "quantity": 23,
          "discountedPrice": {
            "value": {
              "centAmount": 900
            },
            "includedDiscounts": [
              {
                "discount": {
                  "typeId": "cart-discount",
                  "id": "5422c3d1-7529-4446-bc1b-786c3a38e44f"
                },
                "discountedAmount": {
                  "centAmount": 100
                }
              }
            ]
          },
          "discountedPricePerQuantity": [
            {
              "quantity": 10,
              "discountedPrice": {
                "value": {
                  "centAmount": 900
                },
                "includedDiscounts": [
                  {
                    "discount": {
                      "typeId": "cart-discount",
                      "id": "5422c3d1-7529-4446-bc1b-786c3a38e44f"
                    },
                    "discountedAmount": {
                      "centAmount": 100
                    }
                  }
                ]
              }
            }
          ],
          "totalPrice": {
            "centAmount": 9000
          }
        },
        "addedQuantity": 13,
        "type": "OrderLineItemAdded"
      },
      {
        "lineItemId": "aca11e06-38b4-4e0f-be22-97558eb9bd26",
        "removedQuantity": 20,
        "newQuantity": 0,
        "type": "OrderLineItemRemoved"
      },
      {
        "lineItem": {
          "id": "2c39acfe-a004-4e44-86a7-b0ea1e9b7483",
          "quantity": 33,
          "discountedPrice": {
            "value": {
              "centAmount": 2700
            },
            "includedDiscounts": [
              {
                "discount": {
                  "typeId": "cart-discount",
                  "id": "5422c3d1-7529-4446-bc1b-786c3a38e44f"
                },
                "discountedAmount": {
                  "centAmount": 300
                }
              }
            ]
          },
          "discountedPricePerQuantity": [
            {
              "quantity": 30,
              "discountedPrice": {
                "value": {
                  "centAmount": 2700
                },
                "includedDiscounts": [
                  {
                    "discount": {
                      "typeId": "cart-discount",
                      "id": "5422c3d1-7529-4446-bc1b-786c3a38e44f"
                    },
                    "discountedAmount": {
                      "centAmount": 300
                    }
                  }
                ]
              }
            }
          ],
          "totalPrice": {
            "centAmount": 81000
          }
        },
        "addedQuantity": 3,
        "type": "OrderLineItemAdded"
      },
      {
        "lineItemId": "c911b62d-353a-4388-93ee-8d488d9af962",
        "discountedPricePerQuantity": [
          {
            "quantity": 23,
            "discountedPrice": {
              "value": {
                "centAmount": 900
              },
              "includedDiscounts": [
                {
                  "discount": {
                    "typeId": "cart-discount",
                    "id": "5422c3d1-7529-4446-bc1b-786c3a38e44f"
                  },
                  "discountedAmount": {
                    "centAmount": 100
                  }
                }
              ]
            }
          }
        ],
        "totalPrice": {
          "centAmount": 20700
        },
        "taxedPrice": {
          "totalNet": {
            "centAmount": 17395
          },
          "totalGross": {
            "centAmount": 20700
          }
        },
        "type": "OrderLineItemDiscountSet"
      },
      {
        "lineItemId": "2c39acfe-a004-4e44-86a7-b0ea1e9b7483",
        "discountedPricePerQuantity": [
          {
            "quantity": 33,
            "discountedPrice": {
              "value": {
                "centAmount": 2700
              },
              "includedDiscounts": [
                {
                  "discount": {
                    "typeId": "cart-discount",
                    "id": "5422c3d1-7529-4446-bc1b-786c3a38e44f"
                  },
                  "discountedAmount": {
                    "centAmount": 300
                  }
                }
              ]
            }
          }
        ],
        "totalPrice": {
          "centAmount": 89100
        },
        "taxedPrice": {
          "totalNet": {
            "centAmount": 74874
          },
          "totalGross": {
            "centAmount": 89100
          }
        },
        "type": "OrderLineItemDiscountSet"
      },
      {
        "edit": {
          "typeId": "order-edit",
          "id": "f745cccd-31cf-49f2-94ea-5c2bebb38b6e"
        },
        "result": {
          "type": "Applied",
          "appliedAt": "2018-09-25T14:33:46.922Z",
          "excerptBeforeEdit": {
            "totalPrice": {
              "centAmount": 126000
            },
            "taxedPrice": {
              "totalNet": {
                "centAmount": 105882
              },
              "totalGross": {
                "centAmount": 126000
              },
              "taxPortions": [
                {
                  "rate": 0.19,
                  "amount": {
                    "centAmount": 20118
                  },
                  "name": "de"
                }
              ]
            },
            "version": 1
          },
          "excerptAfterEdit": {
            "totalPrice": {
              "centAmount": 109800
            },
            "taxedPrice": {
              "totalNet": {
                "centAmount": 92269
              },
              "totalGross": {
                "centAmount": 109800
              },
              "taxPortions": [
                {
                  "rate": 0.19,
                  "amount": {
                    "centAmount": 17531
                  },
                  "name": "de"
                }
              ]
            },
            "version": 10
          }
        },
        "type": "OrderEditApplied"
      }
    ]
  }
}

As soon as you post update actions to an OrderEdit, the entire set of actions captured under stagedActions will be run against the order. As a response, you get the order back as if the update actions had been applied. The dry run is always performed against the latest version of the order. Should the order endpoint have any API extensions, these will always be called as part of the dry run.

In addition to the preview order, the response will also include messages. The messages are capturing the semantic change you applied to an order. For example, there will be a OrderLineItemAdded message telling you that a line item was added. Another example could be that with the addition of a specific line item, the order is now eligible for a certain discount, in which case there will be a message OrderDiscountAdded. This makes it easy to see the changes of the OrderEdit and understand the impact on the total order price.

Apart from the update action addStagedAction, which appends a staged action at the end of the stagedActions array of an edit, the action setStagedActions can be used to replace all stagedActions.

3. Review the preview

A careful review is needed due to the order always respecting the current product catalog with the current price configuration and the current promotions.

The previous example is an OrderEdit that occurred close to the time of the original order placement. A customer calling customer service an hour after the order was placed asking for a line item to be removed. In this case, no additional impact of editing the order is likely to occur. Therefore, the staged resulting order and the accompanying messages will reflect only the changes that have been actively posted to the OrderEdit.

Now let us assume that more time has passed between order placement and the creation of an OrderEdit. In this time span, one of the products referred by a line item now has a different price, and the cart discount that applied to the original order was time bound and no longer valid at the time of the OrderEdit. In this case, the actively posted update action is still to remove a line item, but the consequence of the edit is much broader. The staged resulting order does not only have a line item removed; another line item has a new price and the cart discount is no longer applied.

Depending on your business protocol, the OrderEdit can now be updated to account for these derived consequences of opening the order up for editing. In the following example, we assume that business protocol states that the new price will be applied, but that the cart discount should still apply. For such a case, the customer service department have a dedicated discount code, named "10% Cart Discount" that can be applied to achieve the wanted cart discount. Therefore, the "10% Cart Discount" is added to the stagedAction set.

{
  "version": 3,
  "actions": [
    {
      "action": "addStagedAction",
      "stagedAction": {
        "action": "addDiscountCode",
        "code": "code-88aeb706-318a-4170-85e9-eab4d66a0c7b"
      }
    }
  ]
}

You now see in the result that the loss of the cart discount has been circumvented.

For review purposes, it is also important to be aware that the messages that are returned in the OrderEdit response include a OrderEditApplied message. This message captures the "before" and "after" value of the Net Total, Gross Total and Tax Portion. By having such a summary message, it can easily be presented and recognized if the overall impact of the OrderEdit is acceptable and whether the OrderEdit is okay to be applied to the order.

{
  "result": {
    "type": "PreviewSuccess",
    "preview": {
      "totalPrice": {
        "centAmount": 109800
      },
      "lineItems": [
        {
          "quantity": 23,
          "id": "c911b62d-353a-4388-93ee-8d488d9af962",
          "discountedPricePerQuantity": {
            "discountedPrice": {
              "includedDiscounts": [
                {
                  "discount": {
                    "typeId": "cart-discount",
                    "id": "88aeb706-318a-4170-85e9-eab4d66a0c7b"
                  },
                  "discountedAmount": {
                    "centAmount": 100
                  }
                }
              ]
            }
          },
          "totalPrice": {
            "centAmount": 20700
          }
        },
        {
          "quantity": 33,
          "id": "2c39acfe-a004-4e44-86a7-b0ea1e9b7483",
          "discountedPricePerQuantity": {
            "discountedPrice": {
              "includedDiscounts": [
                {
                  "discount": {
                    "typeId": "cart-discount",
                    "id": "88aeb706-318a-4170-85e9-eab4d66a0c7b"
                  },
                  "discountedAmount": {
                    "centAmount": 300
                  }
                }
              ]
            }
          },
          "totalPrice": {
            "centAmount": 89100
          }
        }
      ]
    },
    "messagePayloads": [
      {
        "lineItem": {
          "id": "c911b62d-353a-4388-93ee-8d488d9af962",
          "quantity": 23,
          "discountedPrice": {
            "value": {
              "centAmount": 900
            },
            "includedDiscounts": [
              {
                "discount": {
                  "typeId": "cart-discount",
                  "id": "5422c3d1-7529-4446-bc1b-786c3a38e44f"
                },
                "discountedAmount": {
                  "centAmount": 100
                }
              }
            ]
          },
          "discountedPricePerQuantity": [
            {
              "quantity": 10,
              "discountedPrice": {
                "value": {
                  "centAmount": 900
                },
                "includedDiscounts": [
                  {
                    "discount": {
                      "typeId": "cart-discount",
                      "id": "5422c3d1-7529-4446-bc1b-786c3a38e44f"
                    },
                    "discountedAmount": {
                      "centAmount": 100
                    }
                  }
                ]
              }
            }
          ],
          "totalPrice": {
            "centAmount": 9000
          }
        },
        "addedQuantity": 13,
        "type": "OrderLineItemAdded"
      },
      {
        "lineItemId": "aca11e06-38b4-4e0f-be22-97558eb9bd26",
        "removedQuantity": 20,
        "newQuantity": 0,
        "type": "OrderLineItemRemoved"
      },
      {
        "lineItem": {
          "id": "2c39acfe-a004-4e44-86a7-b0ea1e9b7483",
          "quantity": 33,
          "discountedPrice": {
            "value": {
              "centAmount": 2700
            },
            "includedDiscounts": [
              {
                "discount": {
                  "typeId": "cart-discount",
                  "id": "5422c3d1-7529-4446-bc1b-786c3a38e44f"
                },
                "discountedAmount": {
                  "centAmount": 300
                }
              }
            ]
          },
          "discountedPricePerQuantity": [
            {
              "quantity": 30,
              "discountedPrice": {
                "value": {
                  "centAmount": 2700
                },
                "includedDiscounts": [
                  {
                    "discount": {
                      "typeId": "cart-discount",
                      "id": "5422c3d1-7529-4446-bc1b-786c3a38e44f"
                    },
                    "discountedAmount": {
                      "centAmount": 300
                    }
                  }
                ]
              }
            }
          ],
          "totalPrice": {
            "centAmount": 81000
          }
        },
        "addedQuantity": 3,
        "type": "OrderLineItemAdded"
      },
      {
        "discountCode": {
          "typeId": "discount-code",
          "id": "819b2bfc-3320-4731-a660-3af5213b8491"
        },
        "type": "OrderDiscountCodeAdded"
      },
      {
        "lineItemId": "c911b62d-353a-4388-93ee-8d488d9af962",
        "discountedPricePerQuantity": [
          {
            "quantity": 23,
            "discountedPrice": {
              "value": {
                "centAmount": 900
              },
              "includedDiscounts": [
                {
                  "discount": {
                    "typeId": "cart-discount",
                    "id": "88aeb706-318a-4170-85e9-eab4d66a0c7b"
                  },
                  "discountedAmount": {
                    "centAmount": 100
                  }
                }
              ]
            }
          }
        ],
        "totalPrice": {
          "centAmount": 20700
        },
        "taxedPrice": {
          "totalNet": {
            "centAmount": 17395
          },
          "totalGross": {
            "centAmount": 20700
          }
        },
        "type": "OrderLineItemDiscountSet"
      },
      {
        "lineItemId": "2c39acfe-a004-4e44-86a7-b0ea1e9b7483",
        "discountedPricePerQuantity": [
          {
            "quantity": 33,
            "discountedPrice": {
              "value": {
                "centAmount": 2700
              },
              "includedDiscounts": [
                {
                  "discount": {
                    "typeId": "cart-discount",
                    "id": "88aeb706-318a-4170-85e9-eab4d66a0c7b"
                  },
                  "discountedAmount": {
                    "centAmount": 300
                  }
                }
              ]
            }
          }
        ],
        "totalPrice": {
          "centAmount": 89100
        },
        "taxedPrice": {
          "totalNet": {
            "centAmount": 74874
          },
          "totalGross": {
            "centAmount": 89100
          }
        },
        "type": "OrderLineItemDiscountSet"
      },
      {
        "discountCode": {
          "typeId": "discount-code",
          "id": "819b2bfc-3320-4731-a660-3af5213b8491"
        },
        "state": "MatchesCart",
        "type": "OrderDiscountCodeStateSet"
      },
      {
        "edit": {
          "typeId": "order-edit",
          "id": "f745cccd-31cf-49f2-94ea-5c2bebb38b6e"
        },
        "result": {
          "type": "Applied",
          "appliedAt": "2018-09-25T14:33:49.759Z",
          "excerptBeforeEdit": {
            "totalPrice": {
              "centAmount": 126000
            },
            "taxedPrice": {
              "totalNet": {
                "centAmount": 105882
              },
              "totalGross": {
                "centAmount": 126000
              },
              "taxPortions": [
                {
                  "rate": 0.19,
                  "amount": {
                    "centAmount": 20118
                  },
                  "name": "de"
                }
              ]
            },
            "version": 1
          },
          "excerptAfterEdit": {
            "totalPrice": {
              "centAmount": 109800
            },
            "taxedPrice": {
              "totalNet": {
                "centAmount": 92269
              },
              "totalGross": {
                "centAmount": 109800
              },
              "taxPortions": [
                {
                  "rate": 0.19,
                  "amount": {
                    "centAmount": 17531
                  },
                  "name": "de"
                }
              ]
            },
            "version": 12
          }
        },
        "type": "OrderEditApplied"
      }
    ]
  }
}

4. Applying an Order Edit

Once you are ready to apply the OrderEdit to the order, you do so by using the apply update action on POST /orders/edits/:id/apply with the version of the order and the version of the edit as parameters:

{
  "resourceVersion": 1,
  "editVersion": 4
}

Taking the second example from above, when the OrderEdit is applied, the resulting order version looks like this:

{
  "id": "b1065dc8-71c8-4e19-ae3c-1d62df4fec8f",
  "version": 12,
  "totalPrice": {
    "centAmount": 109800
  },
  "lineItems": [
    {
      "id": "c911b62d-353a-4388-93ee-8d488d9af962",
      "quantity": 23,
      "productId": "7c8f813e-6a7d-42d4-8f4e-1a17acdc3724",
      "name": {
        "en": "product 1"
      },
      "price": {
        "value": {
          "centAmount": 1000
        }
      },
      "discountedPricePerQuantity": {
        "discountedPrice": {
          "includedDiscounts": [
            {
              "discount": {
                "typeId": "cart-discount",
                "id": "88aeb706-318a-4170-85e9-eab4d66a0c7b"
              },
              "discountedAmount": {
                "centAmount": 100
              }
            }
          ]
        }
      },
      "totalPrice": {
        "centAmount": 20700
      }
    },
    {
      "id": "2c39acfe-a004-4e44-86a7-b0ea1e9b7483",
      "quantity": 33,
      "productId": "674a1c66-e76b-40f2-b410-0c0dcbedc388",
      "name": {
        "en": "product 3"
      },
      "price": {
        "value": {
          "centAmount": 3000
        }
      },
      "discountedPricePerQuantity": {
        "discountedPrice": {
          "includedDiscounts": [
            {
              "discount": {
                "typeId": "cart-discount",
                "id": "88aeb706-318a-4170-85e9-eab4d66a0c7b"
              },
              "discountedAmount": {
                "centAmount": 300
              }
            }
          ]
        }
      },
      "totalPrice": {
        "centAmount": 89100
      }
    }
  ],
  "inventoryMode": "None",
  "shippingAddress": {
    "country": "DE"
  }
}

Order Messages for Applied Edits

When an OrderEdit is applied, the order itself, not the OrderEdit, will trigger a notification with the message OrderEditAppliedMessage.

As with any other message type, the message endpoint can be used to query this message. This will provide you with information about the edit that has been applied to ther order:

GET /messages?where=resource(id = "${order.id}") and resourceVersion > ${edit.result.excerptBeforeEdit.version} and resourceVersion <= ${edit.result.excerptBeforeEdit.version}&sort=sequenceNumber asc

{
  "count": 8,
  "total": 8,
  "results": [
    {
      "id": "ff3e3407-733d-49ff-89a3-92aedd925d0e",
      "type": "OrderLineItemAdded",
      "resourceVersion": 2,
      "sequenceNumber": 2
    },
    {
      "id": "847f154f-ca22-42f6-891b-e90c330eefa4",
      "type": "OrderLineItemRemoved",
      "resourceVersion": 3,
      "sequenceNumber": 3
    },
    {
      "id": "a15008c7-4109-44fd-937e-528c13f7dce4",
      "type": "OrderLineItemAdded",
      "resourceVersion": 5,
      "sequenceNumber": 4
    },
    {
      "id": "7b7389fa-1868-4b69-a82d-67d9a1d32c50",
      "type": "OrderDiscountCodeAdded",
      "resourceVersion": 6,
      "sequenceNumber": 5
    },
    {
      "id": "4bdf5c23-3625-4948-8e8b-1aa92fd3a063",
      "type": "OrderLineItemDiscountSet",
      "resourceVersion": 7,
      "sequenceNumber": 6
    },
    {
      "id": "bb78a28b-d076-4258-b66b-3e5f0568b5bb",
      "type": "OrderLineItemDiscountSet",
      "resourceVersion": 9,
      "sequenceNumber": 7
    },
    {
      "id": "fdacdd5d-7fb8-450a-9567-4c1963ab7f7f",
      "type": "OrderDiscountCodeStateSet",
      "resourceVersion": 11,
      "sequenceNumber": 8
    },
    {
      "id": "d563d033-8797-4768-b9e3-b36889749c4f",
      "type": "OrderEditApplied",
      "resourceVersion": 12,
      "sequenceNumber": 9,
      "result": {
        "type": "Applied",
        "appliedAt": "2018-09-25T14:33:50.505Z",
        "excerptBeforeEdit": {
          "totalPrice": {
            "centAmount": 126000
          },
          "taxedPrice": {
            "totalNet": {
              "centAmount": 105882
            },
            "totalGross": {
              "centAmount": 126000
            },
            "taxPortions": [
              {
                "rate": 0.19,
                "amount": {
                  "centAmount": 20118
                },
                "name": "de"
              }
            ]
          },
          "version": 1
        },
        "excerptAfterEdit": {
          "totalPrice": {
            "centAmount": 109800
          },
          "taxedPrice": {
            "totalNet": {
              "centAmount": 92269
            },
            "totalGross": {
              "centAmount": 109800
            },
            "taxPortions": [
              {
                "rate": 0.19,
                "amount": {
                  "centAmount": 17531
                },
                "name": "de"
              }
            ]
          },
          "version": 12
        }
      }
    }
  ]
}