Skip to main content

Change of Supplier API Overview

Base routes:

  • /change-of-supplier/v1
  • /change-of-supplier/v2

Description​

The Change of Supplier (CoS) process creates and tracks a registration switch for a single MPAN.
SSI validates your request, raises the registration with CSS, waits for market responses, updates MPAN data from inbound messages, and closes the request when the switch is completed or cancelled.

Process Overview (CoS Gain)​

  1. Supplier submits POST /change-of-supplier/v1/{mpid} or POST /change-of-supplier/v2/{mpid}.
  2. SSI validates request/auth/idempotency, checks for active CoS conflicts, and creates the CoS process in Pending.
  3. SSI sends outbound CSS:
    • CSS1700 for initial/new registration path.
    • CSS1800 for standard existing-connection path.
  4. CSS returns CSS2380 (validation):
    • Rejected -> process ends Failed.
    • Validated -> continue.
  5. CSS returns CSS2300 (Pending registration). SSI stores registration state and expects inbound REGS market data.
  6. REGS messages (IF-002, and later IF-001) are processed by SSI to update MPAN/portfolio data.
  7. CSS then moves registration state:
    • CSS2375 -> switch cancelled, process ends.
    • CSS2370 Confirmed -> wait objection-window milestone, then expect next state.
    • CSS2370 SecuredActive -> continue to completion path.
  8. SSI may trigger optional automation from CoS v2 payload (MS/DS appointments, PSR, contact details) while processing inbound market events.
  9. SSI marks the supplier process Success once completion conditions are met (including status progression to Active where applicable).

Process Diagram​

Endpoints​

  • POST /change-of-supplier/v1/{mpid}: create a Change of Supplier request (v1).
  • POST /change-of-supplier/v2/{mpid}: create a Change of Supplier request (v2, supports extra automation payload sections).

Docs in this section​