Universal Commerce Protocol-tutorial: bouw je eerste UCP-server

In deze gids leer je wat het Universal Commerce Protocol (UCP) is, voor wie het is gebouwd, waarom er een nieuwe commercestandaard nodig is en hoe de architectuur werkt. 

Je volgt ook een praktische walkthrough om je eigen UCP-voorbeeldserver op te zetten, het discovery-profiel te verkennen, een checkout-sessie te maken en lokaal een volledige voorbeeldflow uit te voeren. 

Dit geeft je zowel een helder begrip van het protocol als een praktisch startpunt om te testen hoe UCP werkt in een echte implementatie.

Introductie tot het Universal Commerce Protocol

Het Universal Commerce Protocol is een open standaard die AI-agents, apps, bedrijven en betalingsproviders helpt samenwerken in één gedeelde shoppingflow. In plaats van voor elke nieuwe partner een maatwerkintegratie te bouwen, biedt UCP een gemeenschappelijke manier van communiceren.

UCP is ontworpen voor moderne agent-geleide shopping, waarbij mensen producten ontdekken en kopen via AI-assistants en conversatie-interfaces. Het ondersteunt de volledige reis, van ontdekken wat een bedrijf aanbiedt tot het starten van de checkout en het gestructureerd afhandelen van de aankoop.

Bron: Google Developers Blog

Simpel gezegd fungeert UCP als een gedeelde taal voor commerce. Een bedrijf kan publiceren wat het ondersteunt, en een agent kan die informatie lezen en ermee interacteren zonder een eenmalige API-integratie nodig te hebben. Shopify omschrijft het als infrastructuur die is gebouwd om agentic commerce op schaal mogelijk te maken.

UCP is ook open-source en leverancier-neutraal. Het is ontworpen om met bestaande commercesystemen te werken en is compatibel met het Agent Payments Protocol (AP2) voor veilige, door agents aangestuurde betalingen. Het kan ook over verschillende transports werken, waaronder REST-API’s, agent-tot-agent-communicatie en MCP. 

Voor wie is het Universal Commerce Protocol gebouwd?

Het UCP is gebouwd voor de belangrijkste groepen die betrokken zijn bij moderne digitale commerce. Het doel is om hen allemaal een gedeelde manier van communiceren te geven, zodat ze kunnen samenwerken zonder voor elke koppeling maatwerkintegraties te hoeven bouwen.

Het is vooral ontworpen voor:

1. AI-agents en consumentenplatforms

Dit zijn de apps, assistenten en ontdekkingsplekken die gebruikers helpen producten te vinden en aankopen te doen. UCP helpt hen begrijpen wat een bedrijf ondersteunt en er gestructureerd mee te interacteren. Google beschrijft dit als het verbinden van consumentoppervlakken met bedrijfsbackends voor naadloos shoppen.

2. Bedrijven en merchants

UCP helpt bedrijven hun producten, checkout-flows en ondersteunde features in een standaardformaat beschikbaar te maken. Zo wordt het makkelijker om met verschillende AI-platforms en agents samen te werken zonder voor elk afzonderlijk een aparte integratie te bouwen.

3. Betalingsproviders

Betalingsproviders maken ook deel uit van het UCP-ecosysteem. Het protocol is ontworpen om verschillende payment handlers en betaalmiddelen flexibel te ondersteunen, zodat betalingen veilig kunnen worden afgehandeld over verschillende systemen heen.

4. Ontwikkelaars en protocolbouwers

UCP is open-source, dus het is ook gebouwd voor ontwikkelaars die de standaard willen implementeren, uitbreiden of eraan willen bijdragen. Het UCP-project nodigt bedrijven, ontwikkelaars en betalingsproviders expliciet uit om mee de toekomst van het protocol vorm te geven.

Kortom, UCP is gebouwd voor iedereen die betrokken is bij door AI aangedreven commerce: het platform dat de gebruiker helpt shoppen, het bedrijf dat het product verkoopt, het betalingssysteem dat de transactie verwerkt en de ontwikkelaars die de verbindingen daartussen bouwen.

Waarom een nieuwe commercestandaard nodig is

Er is een nieuwe commercestandaard nodig omdat de meeste huidige commercesystemen zijn gebouwd voor traditionele websites en mobiele apps, niet voor AI-assistants en conversatieshoppen. 

Dat oudere model leunt vaak op custom API’s en eenmalige integraties, wat het traag en lastig schaalbaar maakt over veel platforms. UCP is gemaakt om dat op te lossen door bedrijven, agents en platforms één gedeelde manier van communiceren te geven.

Naarmate meer mensen via AI-tools gaan shoppen, moet commerce live-acties ondersteunen zoals productontdekking, checkout, kortingen en bestelupdates binnen hetzelfde gesprek. 

UCP is ontworpen voor deze nieuwere stijl van shoppen, waarbij de ervaring interactiever is en plaatsvindt op verschillende digitale vlakken.

Het is ook nodig omdat het huidige commerce-ecosysteem gefragmenteerd is. Verschillende bedrijven, betalingsproviders en platforms gebruiken vaak verschillende systemen. UCP helpt ze samen te brengen met een gemeenschappelijke standaard, zodat ze kunnen samenwerken zonder telkens dezelfde integraties opnieuw te bouwen.

Kort gezegd: UCP is nodig omdat oude commercetools niet zijn gebouwd voor AI-geleide shopping. Het geeft de industrie een modernere, flexibelere basis voor hoe mensen voortaan producten ontdekken en kopen.

De architectuur van het Universal Commerce Protocol begrijpen

Het Universal Commerce Protocol (UCP) is een modulair systeem voor agentic commerce. Het geeft bedrijven, AI-agents en betalingsproviders een gedeelde manier om de shoppingreis af te handelen, van discovery tot checkout en verder. 

In plaats van voor elk platform aparte maatwerkintegraties te bouwen, laat UCP een bedrijf publiceren wat het ondersteunt, zodat een agent die informatie kan lezen en een standaardflow kan volgen. 

UCP is modulair en uitbreidbaar ontworpen, ondersteunt transports zoals REST, MCP en A2A, en werkt met payment handlers zodat bedrijven hun bestaande betaalopzet makkelijker kunnen blijven gebruiken.

1. Het bedrijf publiceert een discovery-profiel

Een UCP-enabled bedrijf stelt een profiel bloot op /.well-known/ucp. Dit profiel vertelt platforms en agents wat het bedrijf ondersteunt vóórdat een transactie begint, inclusief beschikbare capabilities en endpoints.

2. De agent leest de ondersteunde capabilities

Na discovery controleert de agent welke services en capabilities het bedrijf aanbiedt. De eerste release van UCP richt zich op kerncapabilities zoals Checkout, Identity Linking en Order Management, die fungeren als de belangrijkste bouwstenen van het protocol.

3. Extensies voegen extra features toe

UCP houdt de kernflow eenvoudig, maar bedrijven kunnen indien nodig optionele extensies toevoegen. Deze extensies bouwen voort op de kerncapabilities en laten bedrijven rijkere features ondersteunen zonder het hele protocol te wijzigen.

4. De flow loopt via een ondersteund transport

Zodra de agent weet wat er wordt ondersteund, kan deze interacteren met het bedrijf via een ondersteund transport zoals REST, MCP of A2A. Dit maakt dezelfde commerce-logica makkelijker bruikbaar over API’s, AI-tools en agent-tot-agent-systemen.

5. Betaling wordt afgehandeld via payment handlers

UCP scheidt de commerceflow van de betaallaag. Bedrijven kunnen ondersteunde payment handlers declareren en het protocol is zo ontworpen dat merchants hun bestaande betaalintegraties kunnen blijven gebruiken in plaats van alles vanaf nul op te bouwen.

6. Veilige, agent-geleide betalingen kunnen AP2 gebruiken

UCP is compatibel met het Agent Payments Protocol (AP2), dat een beveiligde laag toevoegt voor door agents aangestuurde betalingen. Dit helpt om veiligere autorisatie te ondersteunen wanneer een AI-agent namens een gebruiker handelt.

End-to-end-walkthrough van het Universal Commerce Protocol

Deze gids laat een complete Universal Commerce Protocol-flow zien met de Python-referentie-implementatie. Je zet de voorbeeldserver voor merchants op, laadt een demo-catalogus van een bloemenwinkel, ontdekt de bedrijfs-capabilities, maakt een checkout-sessie, past een korting toe en stopt vervolgens de server.

Stap 1: Zet de businessserver op

In deze stap installeer je uv voor Python-dependencybeheer en kloon je zowel de UCP Python SDK als de voorbeeldserver-repository. De README van de voorbeeldserver volgt hetzelfde setuppatroon en vermeldt dat het relatieve pad naar de SDK belangrijk is voor de voorbeelden.

Omdat ons besturingssysteem Linux is, gebruiken we de volgende opdracht om uv te installeren. uv is een snelle en betrouwbare Python package- en omgevingsmanager. Het dient een vergelijkbaar doel als tools zoals Anaconda, maar is veel lichter en sneller.

curl -LsSf https://astral.sh/uv/install.sh | sh

Zodra de installatie is voltooid, laad je je terminalsessie opnieuw zodat het uv-commando beschikbaar wordt in de huidige shell.

source ~/.bashrc

Maak vervolgens een nieuwe map met de naam sdk. Deze map slaat de Universal Commerce Protocol Python SDK op wanneer we die uit de GitHub-repository klonen. 

mkdir sdk
git clone https://github.com/Universal-Commerce-Protocol/python-sdk.git 
sdk/python

Ga nu naar de map sdk/python, waar de SDK-repository is gekloond.

pushd sdk/python

Zodra je in de SDK-map zit, installeer je alle vereiste Python-dependencies voor de SDK met uv sync.

uv sync

Ga na het installeren van de dependencies terug naar je vorige werkmap.

popd

Kloon nu de samples-repository, die de Python-referentieserver voor merchants bevat die in deze walkthrough wordt gebruikt.

git clone https://github.com/Universal-Commerce-Protocol/samples.git

Ga vervolgens naar het Python-servervoorbeeld in de samples-repository.

cd samples/rest/python/server

Installeer tenslotte alle Python-dependencies die nodig zijn om de voorbeeldserver te draaien.

uv sync

Op dit punt staat de voorbeeldserver voor het bedrijf klaar in je workspace. Deze server implementeert al de kernshopping-capabilities die door UCP zijn gedefinieerd.

Stap 2: Maak een voorbeeld-productdatabase

In deze stap maak je een lokale, op SQLite gebaseerde demowinkel voor het voorbeeldbedrijf. Het voorbeeldbedrijf in deze tutorial is een bloemenwinkel en deze opdracht laadt de voorbeeldproductcatalogus en transactiedatabase die de server zal gebruiken.

Maak eerst een tijdelijke map waarin de databasebestanden worden opgeslagen.

mkdir /tmp/ucp_test

Voer vervolgens het importscripts uit om de product- en transactiedatabases te maken en te vullen.

uv run import_csv.py \
  --products_db_path=/tmp/ucp_test/products.db \
  --transactions_db_path=/tmp/ucp_test/transactions.db \
  --data_dir=../test_data/flower_shop

Deze opdracht doet het volgende:

• --products_db_path maakt de productcatalogusdatabase aan.
• --transactions_db_path maakt de transactiedatabase aan die wordt gebruikt voor de checkoutstatus.
• --data_dir=../test_data/flower_shop verwijst naar de voorbeeldgegevens van de bloemenwinkel die in de repository zijn opgenomen.

Zodra deze stap is voltooid, zijn je lokale voorbeeldwinkelgegevens klaar en kan de server ze gebruiken.

Stap 3: Start de businessserver

In deze stap start je de voorbeeld-UCP-businessserver. Deze server gebruikt de product- en transactiedatabases die je in de vorige stap hebt gemaakt en stelt de UCP-shopping-API’s beschikbaar op poort 8182.

Voer de volgende opdracht uit om de server op de achtergrond te starten.

uv run server.py \
  --products_db_path=/tmp/ucp_test/products.db \
  --transactions_db_path=/tmp/ucp_test/transactions.db \
  --port=8182 &
SERVER_PID=$!

Deze opdracht doet het volgende:

• uv run server.py start de voorbeeld-Pythonserver.
• --products_db_path koppelt de server aan de productdatabase.
• --transactions_db_path koppelt de server aan de transactiedatabase.
• --port=8182 laat de server draaien op poort 8182.
• & draait het proces op de achtergrond zodat je de terminal kunt blijven gebruiken.
• SERVER_PID=$! slaat het proces-ID op zodat je de server later kunt stoppen.

Op dit punt draait de businessserver en is deze klaar om verzoeken van een agent te accepteren.

Stap 4: Ontdek bedrijfs-capabilities

In deze stap bevraag je het UCP-discovery-endpoint. Elk UCP-enabled bedrijf publiceert een discovery-document op /.well-known/ucp, waardoor agents kunnen begrijpen wat het bedrijf ondersteunt vóórdat ze verzoeken doen.

Sla eerst de server-URL op in een variabele zodat de volgende opdrachten leesbaarder zijn.

export SERVER_URL=http://localhost:8182

Haal nu het UCP-discovery-document op van de businessserver.

curl -s $SERVER_URL/.well-known/ucp

Deze response vertelt de agent:

• welke UCP-versie de server ondersteunt,
• welke services beschikbaar zijn,
• welke capabilities zijn geïmplementeerd, zoals checkout en kortingen,
• en welke payment handlers of schema’s worden ondersteund.

Deze discoverystap is belangrijk omdat het de noodzaak van hardgecodeerde, maatwerkintegraties wegneemt. De agent kan de server eerst inspecteren en dan beslissen hoe ermee te interacteren.

Stap 5: Maak een checkout-sessie

In deze stap maak je een nieuwe checkout-sessie met behulp van de UCP-checkout-capability. Dit is het moment waarop de agent het geselecteerde product, koperinformatie en betaalstructuur naar de businessserver stuurt.

Genereer vóór het verzenden van het verzoek de vereiste requestheaders. Deze headers helpen bij requesttracing, idempotentie en handtekeningvalidatie.

export REQUEST_ID=$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)
export IDEMPOTENCY_KEY=$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)
export REQUEST_SIGNATURE="dev"

Dit doet het volgende:

• REQUEST_ID maakt een unieke identifier voor het verzoek aan.
• IDEMPOTENCY_KEY zorgt ervoor dat hetzelfde verzoek niet twee keer wordt verwerkt als het opnieuw wordt geprobeerd.
• REQUEST_SIGNATURE levert de vereiste handtekeningheader. In een lokale demo kan "dev" gebruikt worden als strikte validatie van de handtekening niet wordt afgedwongen.

Verzend nu het checkout-verzoek naar de server.

curl -X POST "$SERVER_URL/checkout-sessions" \
  -H "Content-Type: application/json" \
  -H "UCP-Agent: profile=\"https://agent.example/profile\"" \
  -H "request-id: $REQUEST_ID" \
  -H "idempotency-key: $IDEMPOTENCY_KEY" \
  -H "request-signature: $REQUEST_SIGNATURE" \
  -d '{
    "line_items": [
      { "item": { "id": "bouquet_roses", "title": "Red Rose" }, "quantity": 1 }
    ],
    "buyer": { "full_name": "John Doe", "email": "john.doe@example.com" },
    "currency": "USD",
    "payment": { "handlers": [], "instruments": [] }
  }'

Dit verzoek bevat:

• line_items om te definiëren wat de koper wil aanschaffen,
• item.id om het product te identificeren,
• item.title voor een leesbare naam,
• quantity om aan te geven hoeveel stuks worden gekocht,
• buyer om klantgegevens op te nemen,
• currency om de checkoutvaluta te definiëren,
• en payment om de vereiste betaalstructuur te bieden.

De response retourneert een checkout-sessieobject. Dit bevat de nieuwe checkout-ID, line-item-ID’s, totalen, koperinformatie en de huidige checkoutstatus.

Stap 6: Pas kortingen toe met UCP

In deze stap werk je de bestaande checkout-sessie bij en pas je een kortingscode toe. Kortingen in UCP zijn geïmplementeerd als een extensie van de checkout-capability, dus de korting wordt toegevoegd als onderdeel van het checkout-updateverzoek.

Sla eerst de echte checkout-ID en line-item-ID op die zijn geretourneerd door de vorige checkoutresponse.

export CHECKOUT_ID=5dd08e18-c9c1-4fa1-a0d1-885ca81cda29
export LINE_ITEM_ID=ed72ebe6-2484-4e7b-afc8-a8ff5c8f430e

Genereer vervolgens een nieuwe request-ID en idempotency key voor dit updateverzoek.

export REQUEST_ID=$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)
export IDEMPOTENCY_KEY=$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)
export REQUEST_SIGNATURE="dev"

Verzend nu het bijgewerkte checkout-verzoek met de kortingscode toegevoegd.

curl -X PUT "$SERVER_URL/checkout-sessions/$CHECKOUT_ID" \
  -H "Content-Type: application/json" \
  -H "UCP-Agent: profile=\"https://agent.example/profile\"" \
  -H "request-id: $REQUEST_ID" \
  -H "idempotency-key: $IDEMPOTENCY_KEY" \
  -H "request-signature: $REQUEST_SIGNATURE" \
  -d "{
    \"id\": \"$CHECKOUT_ID\",
    \"line_items\": [
      {
        \"id\": \"$LINE_ITEM_ID\",
        \"item\": { \"id\": \"bouquet_roses\", \"title\": \"Red Rose\" },
        \"quantity\": 1
      }
    ],
    \"buyer\": {
      \"full_name\": \"John Doe\",
      \"email\": \"john.doe@example.com\"
    },
    \"currency\": \"USD\",
    \"discounts\": {
      \"codes\": [\"10OFF\"]
    },
    \"payment\": {
      \"handlers\": [],
      \"instruments\": []
    }
  }"

Dit verzoek doet het volgende:

• werkt de bestaande checkout bij met PUT,
• neemt de oorspronkelijke checkout-ID op,
• neemt het line-item opnieuw op,
• voegt de sectie discounts toe,
• en past de code 10OFF toe.

De response zou het bijgewerkte checkoutobject moeten retourneren met:

• herberekende totalen,
• het kortingsbedrag,
• het definitieve bijgewerkte totaal,
• en eventuele toegepaste kortingsdetails.

De kortingscode is geldig; je zou de prijswijziging in de response moeten zien.

Stap 7: Zet de server uit

In deze laatste stap stop je de voorbeeldserver van het bedrijf die je eerder bent gestart. Omdat je het proces-ID hebt opgeslagen bij het starten van de server, kun je deze eenvoudig met één opdracht afsluiten.

Voer de volgende opdracht uit om de server te stoppen.

kill $SERVER_PID

Van begin tot eind heb je met succes een complete end-to-end UCP-flow gebouwd en getest op je lokale machine.

Je hebt:

• de vereiste Python-tools geïnstalleerd met uv,
• de UCP Python SDK en voorbeeldserver-repo’s gekloond,
• een voorbeeld-productdatabase voor de bloemenwinkel gemaakt,
• de businessserver gestart,
• de UCP-capabilities van de server ontdekt via het discovery-endpoint,
• als agent een checkout-sessie gemaakt,
• die checkout bijgewerkt door een kortingscode toe te passen,
• en tot slot de server uitgezet.

Kort gezegd heb je een werkend UCP-enabled bedrijf opgezet, er als agent verbinding mee gemaakt, een shopping-checkout aangemaakt en getest hoe UCP updates zoals kortingen afhandelt. Dit geeft je een volledig basisvoorbeeld van hoe een bedrijf en een agent kunnen interacteren via het Universal Commerce Protocol.

Conclusie

Het Universal Commerce Protocol biedt de industrie een gedeelde basis voor AI-geleide commerce. Het creëert een standaardmanier voor bedrijven, AI-agents en betaalsystemen om te communiceren, zodat discovery, checkout, updates en betalingen eenvoudiger worden ondersteund zonder voor elk nieuw platform maatwerkintegraties te moeten bouwen.

In deze gids heb je geleerd wat UCP is, waarom het belangrijk is, hoe de architectuur werkt en hoe je van begin tot eind een complete lokale voorbeeldflow draait. Door de voorbeeldserver op te zetten, de capabilities te ontdekken, een checkout-sessie te maken en een korting toe te passen, heb je gezien hoe UCP commerce omzet in een gestructureerde, agentvriendelijke workflow.

De grootste kans voor UCP is helder: het kan fragmentatie verminderen en commerce interoperabeler maken in een wereld waar shoppen steeds vaker via AI-assistants en conversatie-interfaces gebeurt. 

De echte uitdaging is echter adoptie. Bedrijven kunnen nog steeds kiezen voor custom API’s, bestaande REST-gebaseerde integraties, MCP-gebaseerde tools of andere agent-workflows die ze vandaag al gebruiken. Voor UCP om te slagen, is sterke ecosysteemondersteuning nodig van merchants, platforms, ontwikkelaars en betalingsproviders.