Vendure: Administrator-created Orders / editing Orders

[drewniakradoslaw]

It's nice as if it was possible to add orders directly from the administration panel. Possibility to edit orders, for example price to pay, invoice or purchased product.

[chladog]

I see this as big topic, from my use-case and experience there are some features to consider:

• adding new OrderLines to the order (& autocomplete-search field of ProductVariants)
• changing quantities of the OrderLine in the order
• removing OrderLines from the order
• ^ products should be allocated/released accordingly
• visual feedback of total amount already paid and difference that needs to be refunded or to be charged extra (a button that would do the action of either refunding (surplus) or create a new payment (shortage) to which we could hook an email.
• adding multiple custom surcharges (#470) with custom description (custom extra fee, product that are not in system, discounts (should be possible to enter negative value)) & selection of their tax category
• promotions should be recaulcated based on changes to the order by administrator (but maybe some use cases would need an option to "freeze" promotions already applied)
• changes should be logged in history timeline stating a person responsible (probably better if there is an "edit mode" and the changes happen in batch with "update button").
• fulfilled items shouldn't be editable (though items from cancelled fulfillments should be)
• changing & adding shipping methods (current data model allows only single shipping per order, but there might be cases when order is needed to be split into 2 independently charged fulfillments (though could be handled by surchages feat.)
• changes not possible to delivered orders.
• possibility to restore cancelled order
• changing payment method

[michaelbromley]

Excellent feedback! Thanks and also I want to cancel this issue now cos it is too complex 😅

Gonna dump some rough thoughts here to help me attack this beast.

New OrderState for editing

Currently any modification to the Order are restricted to when the Order is in the AddingItems state. I think we'd need something similar, an explicit state, e.g. Modifying which signals that we are able to make these changes.

This state would be accessible by default from any of the states from PaymentAuthorized to PartiallyDelivered inclusive.

Admin API changes

One option is to add a bunch of mutations to the Admin API, mirroring those of the Shop API:

type Mutation {
  addItemToOrder(orderId: ID!, productVariantId: ID!, quantity: Int!): UpdateOrderItemsResult!
  removeOrderLine(orderLineId: ID!): RemoveOrderItemsResult!
  adjustOrderLine(orderLineId: ID!, quantity: Int): UpdateOrderItemsResult!
}

One problem I see with this is that we can't then do an atomic operation of making several modifications to the order at once.

visual feedback of total amount already paid and difference that needs to be refunded or to be charged extra (a button that would do the action of either refunding (surplus) or create a new payment (shortage) to which we could hook an email.

This for example would be very difficult to do, as we'd need to hold some "before all modifications" state in order to compare prices. We can't just rely on storing that state in the Admin UI, since the whole thing would be broken by a browser refresh.

So it might make sense to create a single "mega mutation" that takes an input object covering _all possible_ modification, and which executes them in one go, e.g.:

type Mutation {
  modifyOrder(input: ModifyOrderInput!): Order
}

input ModifyOrderInput {
  id: ID!
  addItems: [AddItemInput!]
  adjustOrderLines: [OrderLineInput!] # also handles removal, when quantity === 0
  surcharges: [SurchargeInput!]
  recalculatePromotions: Boolean!
  note: String # description of the modification for the order history timeline
}

input AddItemInput {
  productVariantId: ID!
  quantity: Int!
}

input OrderLineInput {
  orderLineId: ID!
  quantity: Int!
}

input SurchargeInput {
  description: String!
  amount: Int!
}

I tend to think this "mega mutation" approach will work best. It allows us to easily build a single atomic set of changes and would even wrap the entire thing in a DB transaction as a bonus. Then all the data can be bundled together in a single OrderHistoryEntry.

Payment handling

The above mutation does not account for how we would handle payments though. Perhaps it makes sense to have an actual DB entity for this:

export class OrderModification extends VendureEntity {
   // why did we do it?
  note: string;

  // track all the OrderItems created/cancelled by this modification
  orderItems: OrderItem[];

  // The associated Payment (if net positive modification)
  payment: Payment[];

  // The associated Refund (if net negative modification)
  refund: Refund[];

  // Has the payment change been settled?
  settled: boolean;
}

So the workflow could go like:

1. Transition to Modifying state
2. Execute a modifyOrder mutation with all changes
3. Receive the Order back, now it has a new OrderModification item attached to it (add a modifications field to Order entity)
4. Handle payment of that Modification, either create a new Payment, or add a Refund to an existing payment.
5. Transition back to the original state.

[michaelbromley]

One question @chladog regarding this line:

adding multiple custom surcharges (#470) with custom description (custom extra fee, product that are not in system, discounts (should be possible to enter negative value)) & selection of their tax category

Specifically with a _negative surcharge_ such as a negotiated discount with the customer. From a taxation perspective, how would you expect tax to work on a discount? Do you have a good mental model for this because I get confused thinking about it :D

[chladog]

@michaelbromley Sorry, missed this message :-) frankly I wasn't paying as much attention to taxes as I should've (our data goes directly to accounting program). I'm sure after your research on the topic #573 you know more than me in this regards.
I just know there is a business need for shop managers to be able to apply custom discounts and surcharges additionally to changing order contents made of in-system items (products, shippings).

_Let me know if there is still need clarification on tax process I can consult our accountant_

[michaelbromley]

The core parts of order modification are now in place in core & admin-ui. This was a huge task - over 50 hours of work!

I'm going to close this issue, but it is possible that some of the details are still missing, and there are probably edge-cases that will need to be fixed. But I want to get the feature out there in the next release and then let's take individual bugs/missing features up as we find them, as new separate issues.