The Native integration requires you to build a RESTful API that Google can call to create and manage checkout sessions.
The overall flow is as follows:
- Build checkout session: The user and optionally an Agent are in a loop adding items to the session.
- Handoff to a Google UI: Once the user decides to checkout the Agent (if engaged) passes the control to a Google UI (passing the checkout session data)
- Manual checkout: The user now interacts only with the Google UI to fill in sensitive fulfillment and payment details and submit the order. The Agent is not involved in this part, ensuring determinism.
- Completion & return: The Google UI shows a "Thank You" page to confirm the order. Optionally, the user can be redirected back to the Agent, who may have already been notified of the completed purchase.
Developer Tools
To assist with your Native Checkout API implementation, you can find the following resources in the Universal Commerce Protocol GitHub repository:
- UCP GitHub repository: Explore the main repository for comprehensive documentation, specifications, and community resources.
- SDKs: Use the Software Development Kits to accelerate your integration. Language-specific SDKs are available, including:
Conformance tests: Validate your API endpoints against the UCP specification using the conformance test suite
This helps ensure your implementation meets the required standards and behaviors.
We strongly recommend using these tools to streamline your development and testing process.
Checkout REST API implementation
The following steps describe the API endpoints you will need to implement and their behaviors.
1. Create checkout session
This endpoint allows creation of a checkout session containing the products that a user is interested in buying.
- Endpoint:
POST /checkout-sessions - Trigger: User clicks "Buy" on a product.
Request: Google sends the line items and currency.
{
"line_items": [
{
"item": {
"id": "product_12345", // Must match Product Feed ID
"title": "Running Shoes"
},
"quantity": 1
}
],
"currency": "USD"
}
Response: You return the initialized session with totals, taxes (initially estimated), and payment capabilities. You must include links to your terms of service and privacy policy, which will be linked below the payment button.
{
"ucp": {
"version": "2026-01-11",
"capabilities": [
{
"name": "dev.ucp.shopping.checkout",
"version": "2026-01-11"
},
{
"name": "dev.ucp.shopping.fulfillment",
"version": "2026-01-11"
}
]
},
"id": "gid://merchant.example.com/Checkout/session_abc123",
"status": "incomplete",
"line_items": [
{
"id": "line_1",
"item": {
"id": "product_12345",
"title": "Running Shoes",
"price": 10000
},
"quantity": 1,
"base_amount": 10000,
"subtotal": 10000,
"total": 10000
}
],
"totals": [
{ "type": "subtotal", "amount": 10000 }, // in cents
{ "type": "tax", "amount": 0 },
{ "type": "total", "amount": 10000 }
],
"payment": {
"handlers": [
{
"id": "gpay",
"name": "com.google.pay",
"config": {
"api_version": 2,
"api_version_minor": 0,
"merchant_info": {
"merchant_id": "12345678901234567890",
"merchant_name": "Example Merchant"
},
"allowed_payment_methods": [
{
"type": "CARD",
"parameters": {
"allowed_auth_methods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
"allowed_card_networks": ["VISA", "MASTERCARD"]
},
"tokenization_specification": {
"type": "PAYMENT_GATEWAY",
"parameters": {
"gateway": "stripe",
"gateway_merchant_id": "exampleGatewayMerchantId"
}
}
}
]
}
}
]
},
"links": [
{ "type": "privacy_policy", "url": "https://m.com/privacy" },
{ "type": "terms_of_service", "url": "https://m.com/terms" }
]
}
2. Get checkout session
This endpoint allows retrieval of a checkout session.
- Endpoint:
GET /checkout-sessions/{id}
Request: Google sends the ID of the checkout session. If you use Global IDs
(e.g., gid://merchant.example.com/Checkout/session_abc123), note that the ID
in the request path will only be the last component of this ID (e.g.,
session_abc123).
Response: You return the full checkout object.
3. Update checkout session
This endpoint allows updates to a checkout session. When the shipping address is updated, it must recalculate and return taxes and shipping options.
- Endpoint:
PUT /checkout-sessions/{id} - Trigger: User selects or changes their shipping address, updates their shipping selection, or updates their payment information.
Request: Google sends the full checkout object with the updated information.
{
"id": "gid://merchant.example.com/Checkout/session_abc123",
"buyer": {
"first_name": "John",
"last_name": "Doe",
"email": "john@example.com"
},
"fulfillment": {
"methods": [
{
"type": "shipping",
"destinations": [
{
"id": "dest_1",
"postal_code": "94043",
"country": "US",
"address_locality": "Mountain View",
"address_region": "CA"
}
],
"selected_destination_id": "dest_1"
}
]
},
"payment": {
"selected_instrument_id": "pi_gpay_5678",
"instruments": [
{
"id": "pi_gpay_5678",
"handler_id": "gpay",
"type": "card",
"brand": "mastercard",
"last_digits": "5678",
"rich_text_description": "Google Pay •••• 5678"
}
]
}
// ... other fields (line_items, currency, etc.)
}
Response: You recalculate taxes and shipping options as necessary and return the full checkout object.
{
"id": "gid://merchant.example.com/Checkout/session_abc123",
"totals": [
{ "type": "subtotal", "amount": 10000 },
{ "type": "shipping", "display_text": "Ground Shipping", "amount": 500 },
{ "type": "tax", "amount": 850 },
{ "type": "total", "amount": 11350 }
],
// ... other fields (line_items, currency, etc.)
"fulfillment": {
"methods": [
{
"id": "method_shipping",
"type": "shipping",
"line_item_ids": ["line_1"],
"selected_destination_id": "dest_1",
"destinations": [
{
"id": "dest_1",
"postal_code": "94043",
"country": "US",
"address_locality": "Mountain View",
"address_region": "CA"
}
],
"groups": [
{
"id": "group_1",
"line_item_ids": ["line_1"],
"selected_option_id": "ship_ground",
"options": [
{
"id": "ship_ground",
"title": "Ground (3-5 days)",
"totals": [ {"type": "total", "amount": 500} ]
},
{
"id": "ship_express",
"title": "Express (1-2 days)",
"totals": [ {"type": "total", "amount": 1500} ]
}
]
}
]
}
]
}
}
4. Complete checkout session
This endpoint allows completing a checkout session and placing an order. It should return the completed checkout session and include the order information. Payment processing should begin after this call is received.
- Endpoint:
POST /checkout-sessions/{id}/complete - Trigger: User clicks "Place Order".
Request: Google sends the payment token (encrypted blob) from the provider (e.g., Google Pay), and risk signals about the buyer for you to perform your own fraud detection.
{
"payment_data": {
"id": "pi_gpay_5678",
"handler_id": "gpay",
"type": "card",
"brand": "mastercard",
"last_digits": "5678",
"billing_address": {
"postal_code": "94043",
"address_country": "US"
},
"credential": {
"type": "PAYMENT_GATEWAY",
"token": "{\"signature\":\"...\",\"protocolVersion\":\"ECv2\"...}"
}
}
}
If you require mandatory information to complete checkout that has not been provided in the checkout session, you can prevent checkout completion and request that information by returning a non-complete status in the response.
If Google can collect the missing information using UCP-defined fields (for
example, buyer's email address), set status to incomplete and include one
or more messages in the messages array with severity set to recoverable,
indicating what information is missing.
If Google cannot collect the missing information using UCP-defined fields (for
example, custom delivery scheduling), set status to
requires_escalation. In this case, include one or more messages in the
messages array with severity set to requires_buyer_input or
requires_buyer_review, and set continue_url to hand off the Checkout to
user to fill out the information.
{
"id": "gid://merchant.example.com/Checkout/session_abc123",
"status": "requires_escalation",
"messages": [
{
"type": "error",
"code": "email_required",
"severity": "recoverable",
"content": "Buyer email is required"
},
{
"type": "error",
"code": "schedule_delivery",
"severity": "requires_buyer_input",
"content": "Select delivery window for your purchase"
},
{
"type": "error",
"code": "high_value_order",
"severity": "requires_buyer_review",
"content": "Orders over $500 require additional verification"
}
],
}
Response: If checkout can be completed, you return the full checkout object indicating the order is complete, including the order ID and a permalink URL to the order.
{
"ucp": {
"version": "2026-01-11",
"capabilities": [...]
},
"id": "gid://merchant.example.com/Checkout/session_abc123",
"status": "completed",
// ... other fields (line_items, currency, etc.)
"order": {
"id": "gid://merchant.example.com/Order/789",
"permalink_url": "https://merchant.example.com/orders/789"
}
}
5. Cancel checkout session
This endpoint cancels a checkout session.
- Endpoint:
POST /checkout-sessions/{id}/cancel
Request: Google sends the ID of the checkout session.
Response: You return the full checkout object with the status updated to
canceled.