Below the Hood: Common Commerce Protocol (UCP)

1.0 What’s UCP?

The Common Commerce Protocol (UCP) is an open-source customary designed to energy the following technology of agentic commerce. By establishing a standard language and useful primitives, UCP allows seamless commerce journeys between client surfaces, companies, and fee suppliers. It’s constructed to work with present retail infrastructure, and is appropriate with Agent Funds Protocol (AP2) to supply safe agentic funds help. It additionally offers companies versatile methods to combine by way of APIs, Agent2Agent (A2A), and the Mannequin Context Protocol (MCP).

UCP is developed by Google in collaboration with trade leaders together with Shopify, Etsy, Wayfair, Goal, and Walmart endorsed by over 20 international companions throughout the ecosystem like Adyen, American Categorical, Finest Purchase, Flipkart, Macy’s Inc, Mastercard, Stripe, The Dwelling Depot, Visa, Zalando and lots of extra.

UCP is constructed to learn your complete commerce ecosystem

For companies: UCP empowers you to showcase your distinctive product and repair choices at procuring touchpoints throughout client interfaces resembling AI Mode in Google Search and Gemini app, and others sooner or later. With UCP, you personal your corporation logic, and also you stay the Service provider of File. UCP is constructed for retailer flexibility, and offers an ’embedded possibility’ that lets you preserve a totally personalized checkout expertise from day one.
For AI platforms: With UCP, you possibly can allow agentic procuring on your audiences. You possibly can simplify enterprise onboarding utilizing standardized APIs whereas giving them flexibility to make use of MCP, A2A and present agent frameworks of their selection.
For builders: UCP is an evolving open-source customary designed to be community-driven. We invite you to construct the following technology of digital commerce with us.
For fee suppliers: UCP’s open, modular fee handler design allows open interoperability and selection of fee strategies. By way of this design, UCP allows common funds which might be provable. Each authorization is backed by cryptographic proof of consumer consent.
For customers: When your favourite manufacturers undertake UCP, it removes friction from product discovery to resolution, so you possibly can store the manufacturers you like, with peace of thoughts, making certain you get the perfect worth inclusive of your member advantages.

The case for a brand new, versatile customary

As customers embrace conversational experiences, they count on seamless transitions from brainstorming and analysis to closing buy. Meaning it’s crucial to help real-time stock checks, dynamic pricing, and immediate transactions, all inside the consumer’s present conversational context.

Nonetheless, conventional tech infrastructure makes it tough to help this agentic shift. Companies face an N x N integration bottleneck, forcing them to construct bespoke connections for each floor, which finally slows the ecosystem’s shift towards pleasant agentic business experiences.

Developed in collaboration with trade leaders, UCP is designed to deal with this bottleneck and meet the evolving wants of your complete commerce panorama. Not like legacy techniques, UCP standardizes the complete commerce journey – from discovery and consideration to buy and order administration – via a single, safe abstraction layer:

Unified integration: collapses N x N complexity right into a single integration level for all client surfaces.
Shared language: standardizes discovery, functionality schema, and transport bindings to make sure cross-platform interoperability, and end-to-end help for the complete commerce lifecycle.
Extensible structure: constructed with versatile capabilities and extensions framework which might simply scale as new agentic experiences emerge. This design selection additionally permits UCP to increase throughout new verticals.
Safety-first strategy: offers tokenized funds and verifiable credentials, as a secured solution to talk between brokers and enterprise backends.

By lowering integration complexity and eradicating technical obstacles, UCP allows companies to actively take part within the new period of agentic commerce.

UCP Overview

UCP is constructed to energy agentic experiences throughout the commerce ecosystem. It creates a transparent language for client surfaces (resembling AI Mode on Search, Gemini, and others) to connect with enterprise backends (for product discovery, cart checkout and so on) in a standardized and safe method.

Companies and brokers select the providers (for instance, Purchasing and different verticals) they need to help, and expose the capabilities equivalent to them. Capabilities are core commerce constructing blocks resembling checkout and product discovery. These capabilities may also have extensions that increase these capabilities with specialised performance, resembling reductions. UCP’s discovery mechanism permits brokers to dynamically uncover enterprise capabilities and fee choices by way of profiles.

Moreover, UCP fashions a singular funds structure, separating what customers use to pay (devices) from fee handlers (fee processors) permitting it to scale to a various set of present fee suppliers. UCP additionally helps a number of transports together with A2A, MCP and APIs to supply flexibility for companies and brokers to speak. For instance, the Checkout Functionality can have a REST API binding or a MCP binding relying in your platform’s wants.

2.0 The way it works

Let’s use a pattern enterprise retailer and an agent to see how UCP works.

Listed here are urged steps:

Setup a enterprise server and add pattern merchandise to your retailer
Put together your corporation server to simply accept requests from brokers
Allow your agent to find enterprise capabilities
Invoke a checkout functionality together with your agent
Apply reductions to the checkout request together with your agent

2.1 Arrange the enterprise server and add pattern merchandise to your retailer

To arrange a enterprise server, we’ve got created a Samples repository, which accommodates the Python server to host the Enterprise APIs and a UCP SDK which accommodates pattern product information.

Arrange the enterprise server:

mkdir sdk
git clone https://github.com/Common-Commerce-Protocol/python-sdk.git sdk/python
pushd sdk/python
uv sync
popd
git clone https://github.com/Common-Commerce-Protocol/samples.git
cd samples/relaxation/python/server
uv sync

Shell

The enterprise we’re utilizing is a demo flower store. We have now a SQLite based mostly pattern product database that enables us to retailer pattern merchandise for our demo.

Run the next command to create an area database populated with pattern merchandise for the enterprise:

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

Shell

2.2 Put together your corporation server to simply accept requests from brokers

Begin the enterprise server internet hosting the Enterprise APIs on port 8182, pointing to the pattern merchandise database. We begin the server within the background and preserve it working, in order that the shopper can hook up with it.

Run the next command to start out the enterprise server:

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

Shell

2.3 Uncover enterprise capabilities together with your agent

Companies publish the providers they help and corresponding capabilities in an ordinary JSON manifest positioned at /.well-known/ucp. This enables brokers to dynamically uncover options, endpoints, and fee configurations with out hard-coded integrations.

Run this command on your agent to find enterprise providers and capabilities:

export SERVER_URL=http://localhost:8182
export RESPONSE=$(curl -s -X GET $SERVER_URL/.well-known/ucp)
echo $RESPONSE

Shell

Response: 

{
  "ucp": {
    "model": "2026-01-11",
    "providers": { "dev.ucp.procuring": { "model": "2026-01-11", "spec": "https://ucp.dev/specs/procuring", "relaxation": { "schema": "https://ucp.dev/providers/procuring/openapi.json", "endpoint": "http://localhost:8182/" } } },
    "capabilities": [
      { "name": "dev.ucp.shopping.checkout", "version": "2026-01-11", "spec": "https://ucp.dev/specs/shopping/checkout", "schema": "https://ucp.dev/schemas/shopping/checkout.json" },
      { "name": "dev.ucp.shopping.discount", "version": "2026-01-11", "spec": "https://ucp.dev/specs/shopping/discount", "schema": "https://ucp.dev/schemas/shopping/discount.json", "extends": "dev.ucp.shopping.checkout" },
      { "name": "dev.ucp.shopping.fulfillment", "version": "2026-01-11", "spec": "https://ucp.dev/specs/shopping/fulfillment", "schema": "https://ucp.dev/schemas/shopping/fulfillment.json", "extends": "dev.ucp.shopping.checkout" }
    ]
  },
  "fee": {
    "handlers": [
      { "id": "shop_pay", "name": "com.shopify.shop_pay", "version": "2026-01-11", "spec": "https://shopify.dev/ucp/handlers/shop_pay", "config_schema": "https://shopify.dev/ucp/handlers/shop_pay/config.json", "instrument_schemas": [ "https://shopify.dev/ucp/handlers/shop_pay/instrument.json" ], "config": { "shop_id": "d124d01c-3386-4c58-bc58-671b705e19ff" } },
      { "id": "google_pay", "identify": "google.pay", "model": "2026-01-11", "spec": "https://instance.com/spec", "config_schema": "https://instance.com/schema", "instrument_schemas": [  "https://ucp.dev/schemas/shopping/types/gpay_card_payment_instrument.json"
 ], "config": { "api_version": 2, "api_version_minor": 0, "merchant_info": { "merchant_name": "Flower Store", "merchant_id": "TEST", "merchant_origin": "localhost" }, "allowed_payment_methods": [ { "type": "CARD", "parameters": { "allowedAuthMethods": [ "PAN_ONLY", "CRYPTOGRAM_3DS" ], "allowedCardNetworks": [ "VISA", "MASTERCARD" ] }, "tokenization_specification": [ { "type": "PAYMENT_GATEWAY", "parameters": [ { "gateway": "example", "gatewayMerchantId": "exampleGatewayMerchantId" } ] } ] } ] } },
      { "id": "mock_payment_handler", "identify": "dev.ucp.mock_payment", "model": "2026-01-11", "spec": "https://ucp.dev/specs/mock", "config_schema": "https://ucp.dev/schemas/mock.json", "instrument_schemas": [ "https://ucp.dev/schemas/shopping/types/card_payment_instrument.json" ], "config": { "supported_tokens": [ "success_token", "fail_token" ] } }
    ]
  }
}

JSON

Full response instance.

2.4 Invoke a checkout functionality together with your agent

Run this command on your agent to create a checkout session with the pattern merchandise:

export RESPONSE=$(curl -s -X POST "$SERVER_URL/checkout-sessions" -H 'Content material-Kind: software/json' -H 'UCP-Agent: profile="https://agent.instance/profile"' -H 'request-signature: check' -H 'idempotency-key: 0b50cc6b-19b2-42cd-afee-6a98e71eea87' -H 'request-id: 6d08ae4b-e7ea-44f4-846f-d7381919d4f2' -d '{"line_items":[{"item":{"id":"bouquet_roses","title":"Red Rose"},"quantity":1}],"purchaser":{"full_name":"John Doe","electronic mail":"john.doe@instance.com"},"foreign money":"USD","fee":{"devices":[],"handlers":[{"id":"shop_pay","name":"com.shopify.shop_pay","version":"2026-01-11","spec":"https://shopify.dev/ucp/handlers/shop_pay","config_schema":"https://shopify.dev/ucp/handlers/shop_pay/config.json","instrument_schemas":["https://shopify.dev/ucp/handlers/shop_pay/instrument.json"],"config":{"shop_id":"d124d01c-3386-4c58-bc58-671b705e19ff"}},{"id":"google_pay","identify":"google.pay","model":"2026-01-11","spec":"https://instance.com/spec","config_schema":"https://instance.com/schema","instrument_schemas":["https://ucp.dev/schemas/shopping/types/gpay_card_payment_instrument.json"],"config":{"api_version":2,"api_version_minor":0,"merchant_info":{"merchant_name":"Flower Store","merchant_id":"TEST","merchant_origin":"localhost"},"allowed_payment_methods":[{"type":"CARD","parameters":{"allowedAuthMethods":["PAN_ONLY","CRYPTOGRAM_3DS"],"allowedCardNetworks":["VISA","MASTERCARD"]},"tokenization_specification":[{"type":"PAYMENT_GATEWAY","parameters":[{"gateway":"example","gatewayMerchantId":"exampleGatewayMerchantId"}]}]}]}},{"id":"mock_payment_handler","identify":"dev.ucp.mock_payment","model":"2026-01-11","spec":"https://ucp.dev/specs/mock","config_schema":"https://ucp.dev/schemas/mock.json","instrument_schemas":["https://ucp.dev/schemas/shopping/types/card_payment_instrument.json"],"config":{"supported_tokens":["success_token","fail_token"]}}]}}') && echo $RESPONSE

Shell

Full request instance.

After creating the checkout session, your agent will obtain a checkout id from the server, which can be utilized for extra updates to the checkout session:

RESPONSE:

{
  "ucp": { "model": "2026-01-11", "capabilities": [ { "name": "dev.ucp.shopping.checkout", "version": "2026-01-11" } ] },
  "id": "cb9c0fc5-3e81-427c-ae54-83578294daf3",
  "line_items": [ {
      "id": "2e86d63a-a6b8-4b4d-8f41-559f4c6991ea",
      "item": { "id": "bouquet_roses", "title": "Bouquet of Red Roses", "price": 3500 },
      "quantity": 1,
      "totals": [ { "type": "subtotal", "amount": 3500 }, { "type": "total", "amount": 3500 } ]
    } ],
  "purchaser": { "full_name": "John Doe", "electronic mail": "john.doe@instance.com" },
  "standing": "ready_for_complete",
  "foreign money": "USD",
  "totals": [ { "type": "subtotal", "amount": 3500 }, { "type": "total", "amount": 3500 } ],
  "hyperlinks": [],
  "fee": { "handlers": [], "devices": [] },
  "reductions": {}
}

JSON

Full response instance.

2.5 Use your agent to use reductions to the checkout request

Run this command to allow your agent to use reductions to the checkout session, utilizing the checkout id from the earlier step:

export CHECKOUT_ID=$(echo $RESPONSE | jq -r '.id') && export LINE_ITEM_1_ID=$(echo $RESPONSE | jq -r '.line_items[0].id') && export RESPONSE=$(curl -s -X PUT "$SERVER_URL/checkout-sessions/$CHECKOUT_ID" -H 'Content material-Kind: software/json' -H 'UCP-Agent: profile="https://agent.instance/profile"' -H 'request-signature: check' -H 'idempotency-key: b9ecd4b3-0d23-4842-8535-0d55e76e2bad' -H 'request-id: 28e70993-e328-4071-91de-91644dc75221' -d "{"id":"$CHECKOUT_ID","line_items":[{"id":"$LINE_ITEM_1_ID","item":{"id":"bouquet_roses","title":"Red Rose"},"quantity":1}],"foreign money":"USD","fee":{"devices":[],"handlers":[]},"reductions":{"codes":["10OFF"]}}") && echo $RESPONSE | jq

Shell

Full request instance.

Your agent will obtain the next response with the low cost utilized:

RESPONSE: 

{
  "ucp": { "model": "2026-01-11", "capabilities": [ { "name": "dev.ucp.shopping.checkout", "version": "2026-01-11" } ] },
  "id": "cb9c0fc5-3e81-427c-ae54-83578294daf3",
  "line_items": [ {
      "id": "2e86d63a-a6b8-4b4d-8f41-559f4c6991ea",
      "item": { "id": "bouquet_roses", "title": "Bouquet of Red Roses", "price": 3500 },
      "quantity": 1,
      "totals": [ { "type": "subtotal", "amount": 3500 }, { "type": "total", "amount": 3500 } ] } ],
  "purchaser": { "full_name": "John Doe", "electronic mail": "john.doe@instance.com" },
  "standing": "ready_for_complete",
  "foreign money": "USD",
  "totals": [ { "type": "subtotal", "amount": 3500 }, { "type": "discount", "amount": 350 }, { "type": "total", "amount": 3150 } ],
  "hyperlinks": [],
  "fee": { "handlers": [], "devices": [] },
  "reductions": {
    "codes": [ "10OFF" ],
    "utilized": [ { "code": "10OFF", "title": "10% Off", "amount": 350, "automatic": false, "allocations": [ { "path": "subtotal", "amount": 350 } ] } ]
  }
}

JSON

Full response instance.

Now that you just’ve explored the enterprise and agent communication via UCP, you need to use the next command to cease the enterprise server:

Recap:

We arrange a enterprise server and agent. Utilizing UCP, we noticed how brokers can uncover your corporation capabilities, invoke checkout and even apply a reduction on the checkout request. This walkthrough demonstrates one of many capabilities UCP unlocks. UCP additionally helps different capabilities resembling id linking and order administration, and can proceed to increase to help wealthy client agentic experiences.

It’s also possible to strive it your self by going to the python pattern implementation and following the README.md.

3.0 Combine with Google

The Common Commerce Protocol is designed to be impartial and vendor agnostic, able to powering agentic commerce on any floor or platform. To offer a concrete instance and help seamless adoption, Google has constructed the primary reference implementation of UCP, to energy a brand new shopping for expertise that enables customers to buy straight from eligible companies throughout Google’s conversational experiences like AI Mode in Search and Gemini.

This checkout characteristic permits customers to go from discovery to buy seamlessly. As a result of the protocol is designed to help present funds and pockets suppliers, the Google implementation reduces friction by enabling customers to confidently purchase utilizing Google Pay, utilizing fee and transport info they have already got saved with Google Pockets.

Instance Question: “Discover a lightweight suitcase for an upcoming journey.”

Enterprise Integration by way of Service provider Heart

To take part within the Google implementation for UCP, you will need to have an energetic Service provider Heart account and supply merchandise eligible for checkout. That is to make sure that Google has the mandatory product info to floor your stock to be bought straight inside conversational experiences.

Subsequent steps:

Learn the Google integration information to setup your Service provider Heart account and full a service provider curiosity type to combine with Google.
Full the UCP integration following the directions right here.

Name for collaboration

The Common Commerce Protocol has been co-developed and endorsed by greater than 20 companions throughout the ecosystem, and it’s an open-source venture. We invite builders, companies, and platform architects to affix us in constructing the way forward for commerce and welcome suggestions. You may get concerned as we speak by exploring the specification on our GitHub repository, collaborating in GitHub Discussions and contributing via pull requests.