---
title: Order manipulation
slug: commerce-connect-13/docs/order-manipulation
docTags: 
createdAt: 2026-07-23T09:44:50.000Z
---

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 cart instances, cart cache is not really helpful as the cache invalidation can impact site performance. You can use the episerver\:commerce.DisableOrderRepositoryCache setting to turn off cart cache. Only use the setting if you are aware of the consequences. onsequences. \[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:** Creating 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:** Loading 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(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(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

**Example:** Saving 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:** Deleting an order.

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

## Work with order forms

**Example:** Creating and deleting 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:** Adding and removing 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:** Adding and removing 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:** Adding 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:** Getting 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:** Adding 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-/)