---
title: Order manipulation
slug: commerce-connect-14/docs/order-manipulation
createdAt: 2026-07-23T10:25:32.641Z
---

Manipulation of purchase orders and related items is based on classes and methods in the `EPiServer.Commerce.Order` namespace.

These are the key interfaces:

- `IOrderRepository`
- `IOrderRepositoryExtensions`
- `IOrderGroupExtensions`
- `IOrderGroupFactory`

:::hint{type="info"}
**Note**
If you have more than 10 instances, cart cache might be a burden on ServiceBus as multiple messages will be sent to clear cache when a cart is updated. You can use the `episerver:commerce.DisableOrderRepositoryCache` setting to turn off cart cache. Only use the setting if you are aware of the consequences. \[Applies to version 13.13].
:::

## Create orders

When creating orders using the default implementation of `IOrderGroupFactory`, there is always an `IOrderForm` in the Forms collection. There is also always an `IShipment` on the Shipments collection of the `IForm`. If you create a custom `IOrderGroupFactory`, assume you need this as well.

**Example:** Create a cart, purchase order, and payment plan.

```csharp
var orderRepository = ServiceLocator.Current.GetInstance<IOrderRepository>();
    var contactId = PrincipalInfo.CurrentPrincipal.GetContactId();
    
    //Create cart
    var cart = orderRepository.Create<ICart>(contactId, "Default");
    
    //Create purchase order
    var purchaseOrder = orderRepository.Create<IPurchaseOrder>(contactId, "Default");
    
    //Create payment plan
    var paymentPlan = orderRepository.Create<IPaymentPlan>(contactId, "Default");
```

## Load orders

**Example:** Load a cart, wishlist, payment plan, and purchase order.

```csharp
var orderRepository = ServiceLocator.Current.GetInstance<IOrderRepository>();
    var contactId = PrincipalInfo.CurrentPrincipal.GetContactId();
    
    //loading cart will return null if it does not exist
    var cart = orderRepository.LoadCart<ICart>(contactId, "Default");
    var cart = orderRepository.Load<ICart>(orderGroupId);
    var cart = orderRepository.Load(orderReference) as ICart;
    
    //load all carts for customer
    var carts = orderRepository.Load<ICart>(contactId, "Default");
    
    //load or create cart will create cart if does not exist
    var cart = orderRepository.LoadOrCreateCart<ICart>(contactId, "Default");
    
    //loading wishlist will return null if does not exist
    var wishlist = orderRepository.LoadCart<ICart>(contactId, "Wishlist");
    var wishlist = orderRepository.Load<ICart>(orderGroupId);
    var wishlist = orderRepository.Load(orderReference) as ICart;
    
    //load all whishlists for customer
    var wishlists = orderRepository.Load<ICart>(contactId, "Wishlist");
    
    //load or create wishlist will create cart if does not exist
    var wishlist = orderRepository.LoadOrCreateCart<ICart>(contactId, "Wishlist");
    
    //loading purchase order
    var purchaseOrder = orderRepository.Load(orderReference) as IPurchaseOrder;
    var purchaseOrder = orderRepository.Load<IPurchaseOrder>(orderGroupId);
    
    //loading purchase orders for customer
    var purchaseOrders = orderRepository.Load<IPurchaseOrder>(contactId, "Default");
    
    //loading payment plan
    var paymentPlan = orderRepository.Load(orderReference) as IPaymentPlan;
    var paymentPlan = orderRepository.Load<IPaymentPlan>(orderGroupId);
    
    //loading payment plans for customer
    var paymentPlans = orderRepository.Load<IPaymentPlan>(contactId, "Default");
    
    //loading all order for customer
    var orders = orderRepository.Load(contactId, "Default");
```

## Save orders

Note that the purchase order number should be unique.

**Example:** Save a cart, purchase order, and payment plan.

```csharp
var orderRepository = ServiceLocator.Current.GetInstance<IOrderRepository>();
    
    var reference = orderRepository.Save(cart);
    var reference = orderRepository.Save(purchaseOrder);
    var reference = orderRepository.Save(paymentPlan);
    var reference = orderRepository.SaveAsPurchaseOrder(cart);
    var reference = orderRepository.SaveAsPaymentPlan(cart);
```

## Delete orders

**Example:** Delete an order.

```csharp
var orderRepository = ServiceLocator.Current.GetInstance<IOrderRepository>();
    orderRespository.Delete(orderReference);
```

## Work with order forms

**Example:** Create and delete an order form.

```csharp
var orderRepository = ServiceLocator.Current.GetInstance<IOrderRepository>();
    var orderGroupFactory = ServiceLocator.Current.GetInstance<IOrderGroupFactory>();
    var contactId = PrincipalInfo.CurrentPrincipal.GetContactId();
    var cart = orderRepository.LoadCart<ICart>(contactId, "Default");
    
    //create and add new order form (b2b)
    var orderForm = orderGroupFactory.CreateOrderForm(cart);
    cart.Forms.Add(orderForm);
    orderForm.Name = "Default";
    
    //delete order form
    cart.Forms.Remove(orderForm);
```

## Work with shipments

**Example:** Add and remove shipments from order forms.

```csharp
var orderRepository = ServiceLocator.Current.GetInstance<IOrderRepository>();
    var orderGroupFactory = ServiceLocator.Current.GetInstance<IOrderGroupFactory>();
    
    var contactId = PrincipalInfo.CurrentPrincipal.GetContactId();
    var cart = orderRepository.LoadCart<ICart>(contactId, "Default");
    
    //Create and add shipment to first form
    var shipment = orderGroupFactory.CreateShipment(cart);
    //pass in orderGroupFactory for unit testing as a from will be created if there is none o
    cart.AddShipment(shipment, orderGroupFactory);
    //Set address after adding to collection because of limitation in implementation
    shipment.ShippingAddress = orderGroupFactory.CreateOrderAddress(cart);
    
    //Create and add shipment to second form (b2b)
    var secondForm = cart.Forms.Last();
    var shipment = orderGroupFactory.CreateShipment(cart);
    cart.AddShipment(secondForm, shipment);
    //Set address after adding to collection becasue of limitation in implementation
    shipment.ShippingAddress = orderGroupFactory.CreateOrderAddress(cart);
    
    //Remove shipment from first form
    cart.GetFirstForm().Shipments.Remove(shipment);
    
    //Remove shipment from second form (b2b)
    cart.Forms.Last().Shipments.Remove(shipment);
```

## Work with payments

**Example:** Add and remove payments from order form.

```csharp
var orderRepository = ServiceLocator.Current.GetInstance<IOrderRepository>();
    var orderGroupFactory = ServiceLocator.Current.GetInstance<IOrderGroupFactory>();
    var contactId = PrincipalInfo.CurrentPrincipal.GetContactId();
    var cart = orderRepository.LoadCart<ICart>(contactId, "Default");
    
    //Create and add payment to first form
    var creditCard = orderGroupFactory.CreateCardPayment(cart);
    var invoice = orderGroupFactory.CreatePayment(cart);
    //pass in orderGroupFactory for unit testing as a from will be created if there is none on the cart.
    cart.AddPayment(creditCard, orderGroupFactory);
    cart.AddPayment(invoice, orderGroupFactory);
    //Set address after adding to collection becasue of limitation in implementation
    creditCard.BillingAddress = orderGroupFactory.CreateOrderAddress(cart);
    
    //Create and add payment to second form (b2b)
    var secondForm = cart.Forms.Last();
    var creditCard = orderGroupFactory.CreateCardPayment(cart);
    var invoice = orderGroupFactory.CreatePayment(cart);
    cart.AddPayment(secondForm, creditCard);
    cart.AddPayment(secondForm, invoice);
    //Set address after adding to collection becasue of limitation in implementation
    creditCard.BillingAddress = orderGroupFactory.CreateOrderAddress(cart);
    
    //Remove payment from first form
    cart.GetFirstForm().Payments.Remove(payment);
    
    //Remove payment from second form (b2b)
    cart.Forms.Last().Payments.Remove(payment);
```

## Work with line items

**Example:** Add line items to shipments.

```csharp
var orderRepository = ServiceLocator.Current.GetInstance<IOrderRepository>();
    var orderGroupFactory = ServiceLocator.Current.GetInstance<IOrderGroupFactory>();
    var contactId = PrincipalInfo.CurrentPrincipal.GetContactId();
    var cart = orderRepository.LoadCart<ICart>(contactId, "Default");
    
    //add line item to first shipment on first form
    var lineItem = orderGroupFactory.CreateLineItem("code", cart);
    
    //use orderFactory for unit testing
    cart.AddLineItem(lineItem, orderGroupFactory);
    
    //add line item to second shipment on first form
    var shipment = cart.GetFirstForm().Shipments.Last();
    var lineItem = orderGroupFactory.CreateLineItem("code", cart);
    cart.AddLineItem(shipment, lineItem);
    
    //add line item to second form first shipment
    var orderForm = cart.Forms.Last();
    var lineItem = orderGroupFactory.CreateLineItem("code", cart);
    
    //add orderFactory for unit testing 
    cart.AddLineItem(orderForm, lineItem, orderGroupFactory);
    
    //remove line item from first form first shipment 
    cart.GetFirstShipment().LineItems.Remove(lineItem);
    
    //remove line item from first form second shipment
    cart.GetFirstForm().Shipments.Last().LineItems.Remove(lineItem);
    
    //remove line item from second form first shipment (b2b)
    cart.Forms.Last().Shipments.First().LineItems.Remove(lineItem);
```

## Work with addresses

**Example:** Get billing and shipping addresses.

```csharp
var orderRepository = ServiceLocator.Current.GetInstance<IOrderRepository>();
    var orderGroupFactory = ServiceLocator.Current.GetInstance<IOrderGroupFactory>();
    var contactId = PrincipalInfo.CurrentPrincipal.GetContactId();
    var cart = orderRepository.LoadCart<ICart>(contactId, "Default");
    
    var address = orderGroupFactory.CreateOrderAddress(cart);
    
    //Use Id to reuse
    address.Id = "Billing";
    cart.GetFirstForm().Payments.First().BillingAddress = address;
    
    //Since there is already an address with "Billing" it will use that address instead of creating another one on the order.
    var reuseOtherAddress = orderGroupFactory.CreateOrderAddress(cart);
    reuseOtherAddress.Id = "Billing";
    cart.GetFirstShipment().ShippingAddress = reuseOtherAddress;
    
    //Region Name and Region Code should be used when dealing with states
    address.RegionName = "California";
    address.RegionCode = "CA";
    address.CountryCode = "US";
    address.CountryName = "United States";
```

## Work with notes

**Example:** Add notes to orders.

```csharp
var orderRepository = ServiceLocator.Current.GetInstance<IOrderRepository>();
    var orderGroupFactory = ServiceLocator.Current.GetInstance<IOrderGroupFactory>();
    var contactId = PrincipalInfo.CurrentPrincipal.GetContactId();
    var cart = orderRepository.LoadCart<ICart>(contactId, "Default");
    
    var notes = cart.Notes;
    
    var note = orderGroupFactory.CreateOrderNote(cart);
    note.CustomerId = contactId;
    note.Type = OrderNoteTypes.Custom.ToString();
    note.Title = "Noted";
    note.Detail = "Something should be noted.";
    note.Created = DateTime.UtcNow;
    notes.Add(note);
    
    orderRepository.Save(cart);
```

**Related blog post:** [CartHelper is dead, long live IOrderRepository](https://world.optimizely.com/blogs/Quan-Mai/Dates/2018/1/carthelper-is-dead-long-live-iorderrepository-/)