---
title: Order manipulation
slug: commerce-connect-15/docs/order-manipulation
createdAt: 2026-07-30T20:34:41.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, the cart cache is not helpful because cache invalidation can impact site performance. Use the `episerver:commerce.DisableOrderRepositoryCache` setting to turn off the cart cache. Only use this setting if you understand the consequences. (Applies to version 13.13.)
:::

## Create orders

When you create orders using the default implementation of `IOrderGroupFactory`, the `Forms` collection always contains an `IOrderForm`, and that form's `Shipments` collection always contains an `IShipment`. If you implement a custom `IOrderGroupFactory`, follow the same convention.

The following example shows how to 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

The following example shows how to load a cart, wishlist, payment plan, and purchase order.

```csharp
var orderRepository = ServiceLocator.Current.GetInstance<IOrderRepository>();
var contactId = PrincipalInfo.CurrentPrincipal.GetContactId();

// Loading the cart returns 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 the customer.
var carts = orderRepository.Load<ICart>(contactId, "Default");

// LoadOrCreateCart creates a cart if one does not exist.
var cart = orderRepository.LoadOrCreateCart<ICart>(contactId, "Default");

// Loading the wishlist returns null if it 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 wishlists for the customer.
var wishlists = orderRepository.Load<ICart>(contactId, "Wishlist");

// LoadOrCreateCart creates a wishlist if one does not exist.
var wishlist = orderRepository.LoadOrCreateCart<ICart>(contactId, "Wishlist");

// Loading a purchase order.
var purchaseOrder = orderRepository.Load(orderReference) as IPurchaseOrder;
var purchaseOrder = orderRepository.Load<IPurchaseOrder>(orderGroupId);

// Loading purchase orders for the customer.
var purchaseOrders = orderRepository.Load<IPurchaseOrder>(contactId, "Default");

// Loading a payment plan.
var paymentPlan = orderRepository.Load(orderReference) as IPaymentPlan;
var paymentPlan = orderRepository.Load<IPaymentPlan>(orderGroupId);

// Loading payment plans for the customer.
var paymentPlans = orderRepository.Load<IPaymentPlan>(contactId, "Default");

// Loading all orders for the customer.
var orders = orderRepository.Load(contactId, "Default");
```

## Save orders

Note that the purchase order number should be unique. The following example shows how to 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 an order

The following example shows how to delete an order.

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

## Create and delete an order form

The following example shows how to 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 a new order form (b2b).
var orderForm = orderGroupFactory.CreateOrderForm(cart);
cart.Forms.Add(orderForm);
orderForm.Name = "Default";

// Delete the order form.
cart.Forms.Remove(orderForm);
```

## Add and remove shipments

The following example shows how to 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 a shipment to the first form.
var shipment = orderGroupFactory.CreateShipment(cart);
// Pass in orderGroupFactory for unit testing because a form will be created if none exists.
cart.AddShipment(shipment, orderGroupFactory);
// Set the address after adding to the collection because of an implementation limitation.
shipment.ShippingAddress = orderGroupFactory.CreateOrderAddress(cart);

// Create and add a shipment to the second form (b2b).
var secondForm = cart.Forms.Last();
var shipment = orderGroupFactory.CreateShipment(cart);
cart.AddShipment(secondForm, shipment);
// Set the address after adding to the collection because of an implementation limitation.
shipment.ShippingAddress = orderGroupFactory.CreateOrderAddress(cart);

// Remove the shipment from the first form.
cart.GetFirstForm().Shipments.Remove(shipment);

// Remove the shipment from the second form (b2b).
cart.Forms.Last().Shipments.Remove(shipment);
```

## Add and remove payments

The following example shows how to 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 a payment to the first form.
var creditCard = orderGroupFactory.CreateCardPayment(cart);
var invoice = orderGroupFactory.CreatePayment(cart);
// Pass in orderGroupFactory for unit testing because a form will be created if none exists on the cart.
cart.AddPayment(creditCard, orderGroupFactory);
cart.AddPayment(invoice, orderGroupFactory);
// Set the address after adding to the collection because of an implementation limitation.
creditCard.BillingAddress = orderGroupFactory.CreateOrderAddress(cart);

// Create and add a payment to the 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 the address after adding to the collection because of an implementation limitation.
creditCard.BillingAddress = orderGroupFactory.CreateOrderAddress(cart);

// Remove the payment from the first form.
cart.GetFirstForm().Payments.Remove(payment);

// Remove the payment from the second form (b2b).
cart.Forms.Last().Payments.Remove(payment);
```

## Add line items to shipments

The following example shows how to 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 a line item to the first shipment on the first form.
var lineItem = orderGroupFactory.CreateLineItem("code", cart);

// Use orderGroupFactory for unit testing.
cart.AddLineItem(lineItem, orderGroupFactory);

// Add a line item to the second shipment on the first form.
var shipment = cart.GetFirstForm().Shipments.Last();
var lineItem = orderGroupFactory.CreateLineItem("code", cart);
cart.AddLineItem(shipment, lineItem);

// Add a line item to the first shipment on the second form.
var orderForm = cart.Forms.Last();
var lineItem = orderGroupFactory.CreateLineItem("code", cart);

// Add orderGroupFactory for unit testing. 
cart.AddLineItem(orderForm, lineItem, orderGroupFactory);

// Remove a line item from the first shipment on the first form. 
cart.GetFirstShipment().LineItems.Remove(lineItem);

// Remove a line item from the second shipment on the first form.
cart.GetFirstForm().Shipments.Last().LineItems.Remove(lineItem);

// Remove a line item from the first shipment on the second form (b2b).
cart.Forms.Last().Shipments.First().LineItems.Remove(lineItem);
```

## Set billing and shipping addresses

The following example shows how to set 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 the address.
address.Id = "Billing";
cart.GetFirstForm().Payments.First().BillingAddress = address;

// Because an address with the ID "Billing" already exists, that address is reused instead of creating another one on the order.
var reuseOtherAddress = orderGroupFactory.CreateOrderAddress(cart);
reuseOtherAddress.Id = "Billing";
cart.GetFirstShipment().ShippingAddress = reuseOtherAddress;

// Use RegionName and RegionCode when working with US states.
address.RegionName = "California";
address.RegionCode = "CA";
address.CountryCode = "US";
address.CountryName = "United States";
```

## Add notes to orders

The following example shows how to 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-/)