Skip to content
Criée

Amending and cancelling an order

Keeping or losing time priority, writing an amendment with annuler and passer, and the traps of cancellation.

Lesson 1010 min

By the end of this lesson

  • Predict how amending an order affects its time priority
  • Write an amendment with annuler then passer, keeping the rank
  • Handle what annuler returns, including for an order already filled
In this lesson5

An order in the book is not frozen. The client can reduce its quantity, increase it, change its limit or cancel it altogether. Each move affects the order's place in the queue, and that place decides what it will receive. In the lesson Order life cycle and the FIX protocol, the amend request had a name, OrderCancelReplaceRequest (G), but no engine method answered it. This lesson builds one.

Order amendment

A change to the quantity or the limit of a resting order; depending on the change, the order keeps or loses its time priority.

The priority rule

Amending an order loses time priority if the limit changes or the quantity increases; priority is kept if the quantity decreases (Euronext Trading Manual, 2021, section 2). The BVMAC's 2008 draft market rules provided for the same rule (Instruction no. 2, 2008, section 2.5).

The logic shows in the queue. Reducing a quantity harms nobody: the orders behind get filled sooner. Increasing a quantity while keeping one's place would mean jumping ahead of those already waiting at the same price. Changing the limit means changing queue.

The rule above comes from the Euronext manual and a 2008 BVMAC draft. Our research found no current BVMAC text detailing order amendment. Treat it as the teaching engine's specification, to be confirmed before any production use.

Three amendments, on stage

The queue below waits at 10,000: A, B then C; D waits at 9,950. Pick an amendment to B, then follow what it changes when a sell of 70 arrives. Watch B's rank after the amendment above all.

Amending an order1/4
10,000
Arank 1
30 × 10,000
Brank 2
20 × 10,000
Crank 3
25 × 10,000
9,950
Drank 4
15 × 9,950

initial book

A queue at 10,000

A, B and C wait at 10,000, in arrival order; D waits at 9,950.

From memory: does B, reduced from 20 to 10, keep its place ahead of C? And B increased to 40?

In code: cancel, then re-submit

The teaching engine only knows passer and annuler. An amendment can be written with these two methods, thanks to one detail of the API: passer accepts a rang supplied by the caller. Keeping priority means re-submitting the order with its old rank. This split is a design choice of this course, not a description of a real platform.

import { Carnet, type Execution } from '@criee/marche'

type Changement = { quantite?: number; limite?: number | null }

function trouver(c: Carnet, id: string) {
  const { achats, ventes } = c.ordres()
  return [...achats, ...ventes].find((o) => o.id === id)
}

/** Design choice: cancel then re-submit; the rank is kept only if the quantity drops at the same limit. */
export function modifier(carnet: Carnet, id: string, ch: Changement): Execution[] | null {
  const actuel = trouver(carnet, id)
  if (!actuel) return null                                   // already filled, cancelled or unknown
  const quantite = ch.quantite ?? actuel.quantite
  const limite = ch.limite === undefined ? actuel.limite : ch.limite
  if (!Number.isInteger(quantite) || quantite <= 0) return null // validate BEFORE cancelling
  const garde = limite === actuel.limite && quantite <= actuel.quantite
  const { sens, rang } = actuel
  carnet.annuler(id)
  return carnet.passer({ id, sens, quantite, limite, ...(garde ? { rang } : {}) })
}

Let us follow it step by step on the scene's queue.

const c = new Carnet(10000)
c.passer({ id: 'A', sens: 'achat', quantite: 30, limite: 10000 }) // rank 1
c.passer({ id: 'B', sens: 'achat', quantite: 20, limite: 10000 }) // rank 2
c.passer({ id: 'C', sens: 'achat', quantite: 25, limite: 10000 }) // rank 3
c.passer({ id: 'D', sens: 'achat', quantite: 15, limite: 9950 })  // rank 4

modifier(c, 'B', { quantite: 10 })
// garde = true: B is re-submitted with rank 2 → A r1, B r2, C r3, D r4

c.passer({ id: 'V', sens: 'vente', quantite: 70, limite: 9950 })
// [ { A, V, 10000, 30 }, { B, V, 10000, 10 }, { C, V, 10000, 25 }, { D, V, 9950, 5 } ]

With modifier(c, 'B', { quantite: 40 }) instead, garde is false: B gets rank 5, the counter's next number, and the queue becomes A, C, B. The sell of 70 then fills A for 30, C for 25 and B for only 15.

Cancelling: a boolean, three traps

Carnet.annuler(id) removes the resting order and returns true, or false if it is no longer in the book. Three edge cases deserve a test each:

  • Cancelling a filled order: false. The "filled" state is final; the cancellation comes too late.
  • Cancelling twice: true, then false. An interface that resends the cancellation must expect the second refusal.
  • Reused identifier: two orders with the same id are removed together. This is a known limit of the engine, listed in the "engine contract" sheet.

A cancellation never undoes an execution. If the order has already been partly filled, only the remainder leaves the book. Follow the cancellation scenario: the order goes through "partly filled" before "cancelled", and its 30 filled shares remain filled.

An order’s state machine1/4
ReceivedIn the bookFilledRejectedPartly filledCancelledExpired

tracked order

{
id: 'K-7'
etat: 'recu'
executee: 0
reste: 100
}

receipt

Received

Order K-7 (fictional) arrives: buy 100 shares at 10,000. Press play to follow its transitions.

Going further

The order lost between two calls. A first version of modifier cancelled, then re-submitted without checking anything. With a quantity of 0, what follows is a production trap:

carnet.annuler('B')                                           // true: B has left the book
carnet.passer({ id: 'B', sens: 'achat', quantite: 0, limite: 10000 })
// Error: La quantité doit être un entier strictement positif.
carnet.ordres().achats.map((o) => o.id)                        // [ 'A', 'C', 'D' ]: B has vanished

The client wanted to amend the order; they lost it. The version above validates before cancelling and returns null without touching anything. In a real system the rule reads: an amendment succeeds in full or changes nothing.

Total quantity or remaining quantity? The book keeps only the remaining quantity. An order of 100 already filled for 30 shows 70. If the client asks to "reduce to 50", do they mean the original 100 (leaving 20 to fill) or the 70 remaining? modifier reasons on the remainder. This is a decision to write into the specification, then into a test.

An amendment can execute. Raising D's limit from 9,950 to 10,050, against a sell W of 10 shares at 10,050, does not merely move D: passer immediately returns [{ achat: 'D', vente: 'W', prix: 10050, quantite: 10 }], and D keeps only 5 shares, at rank 6. The caller of modifier must handle these executions like those of a new order.

The supplied rank is not checked. The engine accepts any rang. An order E submitted with rang: 0 goes ahead of A, which arrived before it. Only the gateway knows whether a rank is legitimate: it must guarantee it, and a test must check it.

From memory, linking to the lesson on the book: why does E's rank 0 put it ahead of A, when their prices are equal?

Challenge: the two tests from lesson 7

Go back to the challenge in the lesson From business rule to test case. With modifier, write in Given / when / then: reducing the quantity keeps priority, increasing it loses priority. Choose data that would not pass if garde were always true.

Your turn

A resting order has its quantity reduced. Its time priority is...

1A resting order has its quantity reduced. Its time priority is...

How does modifier keep priority with the engine's API?

2How does modifier keep priority with the engine's API?

What does annuler return for an order already fully filled?

3What does annuler return for an order already fully filled?

Why validate the new quantity before calling annuler?

4Why validate the new quantity before calling annuler?

A raised limit crosses a resting sell. modifier returns...

5A raised limit crosses a resting sell. modifier returns...

Read next: Euronext Trading Manual, 5 juillet 2021

A question? Ask your teacher, or an AI assistant, giving it the title of this lesson.

Share:WhatsAppLinkedIn

Going further