This guide provides the technical API reference and payload schemas for version
`2026-01-23` of the Universal Commerce Protocol (UCP) native checkout.

Before building your endpoints, ensure you have reviewed the [Native checkout
overview](https://developers.google.com/merchant/ucp/guides/overview/native-checkout) for the high-level
checkout flow, authentication requirements, and developer tools.

> [!TIP]
> **Tip:** To ensure your API meets the required performance targets, review the [latency optimization](https://developers.google.com/merchant/ucp/guides/overview/native-checkout#latency-optimization) best practices.

> [!NOTE]
> **Note:** Google includes an `Authorization: Bearer <access_token>` header in requests to these endpoints. This is used for both machine-to-machine authentication and [identity
> linking](https://developers.google.com/merchant/ucp/guides/overview/identity-linking).

## 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 now" on a product or "Checkout on Google" from the cart.

**Request:** Google sends the line items, and limited address information about
the buyer, which includes city, state, and ZIP code.

    // Request Example: Create checkout with multiple items.
    {
      "line_items": [
        {
          "item": {
            // Must match ID in product feed
            "id": "product_12345"
          },
          "quantity": 1
        },
        {
          "item": {
            // Must match ID in product feed
            "id": "product_67890"
          },
          "quantity": 1
        }
      ],
      "context": {
        "language": "en"
      },
      "fulfillment": {
        "methods": [
          {
            "type": "shipping",
            "line_item_ids": [
              "line_1",
              "line_2"
            ],
            "destinations": [
              {
                "id": "addr_1",
                "address_locality": "Sunnyvale",
                "address_region": "CA",
                "postal_code": "94089",
                "address_country": "US"
              }
            ],
            "selected_destination_id": "addr_1"
          }
        ]
      }
    }

**Response:** You return the initialized session with totals, taxes (initially
estimated), and payment capabilities.

> [!NOTE]
> **Note:** In the `links` array of the response, you must provide URLs for `privacy_policy` and `terms_of_service`. These two link types are required for display in the Google checkout UI.

    // Response Example: Initialize Session with multiple items.
    {
      "ucp": {
        "version": "2026-01-23",
        "capabilities": {
          "dev.ucp.shopping.checkout": [ { "version": "2026-01-23" } ],
          "dev.ucp.shopping.fulfillment": [ { "version": "2026-01-23", "extends": "dev.ucp.shopping.checkout" } ]
        },
        "payment_handlers": {
          "com.google.pay": [
            {
              "id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
              "version": "2026-01-23",
              "spec": "https://pay.google.com/gp/p/ucp/2026-01-23/",
              "schema": "https://pay.google.com/gp/p/ucp/2026-01-23/schemas/config.json",
              "config": {
                "api_version": 2,
                "api_version_minor": 0,
                "environment": "TEST",
                "merchant_info": {
                  "merchant_name": "Example Merchant",
                  "merchant_id": "KWMZPRLQFTYNXSDB",
                  "merchant_origin": "checkout.merchant.com"
                },
                "allowed_payment_methods": [
                  {
                    "type": "CARD",
                    "parameters": {
                      "allowed_auth_methods": [ "PAN_ONLY", "CRYPTOGRAM_3DS" ],
                      "allowed_card_networks": [
                        "AMEX",
                        "DISCOVER",
                        "JCB",
                        "MASTERCARD",
                        "VISA"
                      ],
                      "billing_address_required": true,
                      "billing_address_parameters": {
                        "format": "FULL",
                        "phone_number_required": true
                      }
                    },
                    "tokenization_specification": {
                      "type": "PAYMENT_GATEWAY",
                      "parameters": {
                        "gateway": "example",
                        "gatewayMerchantId": "exampleGatewayMerchantId"
                      }
                    }
                  }
                ]
              }
            }
          ]
        }
      },
      "id": "da2e25ec-eef8-41b7-a439-4e62dea41bdc",
      "status": "incomplete",
      "messages": [
        {
          "type": "error",
          "code": "missing_buyer_info",
          "path": "$.buyer",
          "content_type": "plain",
          "content": "Buyer information is required for checkout",
          "severity": "recoverable"
        },
        {
          "type": "error",
          "code": "missing_fulfillment_info",
          "path": "$.fulfillment.methods[0].destinations[0]",
          "content_type": "plain",
          "content": "Shipping address is incomplete",
          "severity": "recoverable"
        }
      ],
      "currency": "USD",
      "line_items": [
        {
          "id": "line_1",
          "item": {
            "id": "product_12345",
            "title": "Running Shoes",
            "price": 10000,
            "image_url": "https://merchant.example.com/images/product_12345.png"
          },
          "quantity": 1,
          "totals": [
            {
              "type": "subtotal",
              "amount": 10000
            },
            {
              "type": "total",
              "amount": 10000
            }
          ]
        },
        {
          "id": "line_2",
          "item": {
            "id": "product_67890",
            "title": "T-Shirt",
            "price": 2500,
            "image_url": "https://merchant.example.com/images/product_67890.png"
          },
          "quantity": 1,
          "totals": [
            {
              "type": "subtotal",
              "amount": 2500
            },
            {
              "type": "total",
              "amount": 2500
            }
          ]
        }
      ],
      "totals": [
        {
          "type": "subtotal",
          "display_text": "Subtotal", // Tax-inclusive markets: Set to "Subtotal (including taxes)".
          "amount": 12500 // Tax-inclusive markets: Amount must include tax.
        },
        {
          "type": "fulfillment",
          "display_text": "Ground Shipping", // Tax-inclusive markets: Provide display text for fulfillment totals.
          "amount": 500
        },
        {
          "type": "tax", // Tax-inclusive markets: Omit this entry.
          "display_text": "Estimated Tax",
          "amount": 100
        },
        {
          "type": "total",
          "amount": 13100
        }
      ],
      "fulfillment": {
        "methods": [
          {
            "id": "method_shipping",
            "type": "shipping",
            "line_item_ids": [
              "line_1",
              "line_2"
            ],
            "destinations": [
              {
                "id": "addr_1",
                "address_locality": "Sunnyvale",
                "address_region": "CA",
                "postal_code": "94089",
                "address_country": "US"
              }
            ],
            "selected_destination_id": "addr_1",
            "groups": [
              {
                "id": "group_1",
                "line_item_ids": [
                  "line_1",
                  "line_2"
                ],
                "options": [
                  {
                    "id": "ship_ground",
                    "title": "Ground (3-5 days)",
                    "description": "Estimated Delivery: Fri 5/8", // Maximum length: 200 characters.
                    "totals": [ {"type": "total", "amount": 500} ]
                  },
                  {
                    "id": "ship_express",
                    "title": "Express (1-2 days)",
                    "description": "Estimated Delivery: Wed 5/6", // Maximum length: 200 characters.
                    "totals": [ {"type": "total", "amount": 1500} ]
                  }
                ],
                "selected_option_id": "ship_ground"
              }
            ]
          }
        ]
      },
      "links": [
        {
          "type": "terms_of_service",
          "url": "https://m.com/terms",
          "title": "Terms of Service"
        },
        {
          "type": "privacy_policy",
          "url": "https://m.com/privacy",
          "title": "Privacy Policy"
        }
      ]
    }

### Tax-inclusive pricing

For markets where tax is included in the displayed subtotal rather than itemized
separately, your implementation must adhere to the following requirements when
providing checkout session data:

- **Include tax in the subtotal:** The `amount` field for the `subtotal` entry must include all applicable taxes.
- **Omit separate tax entries:** Don't include a dedicated object with `type:
  "tax"` in the `totals` array.
- **Provide custom display text:** You must include a `display_text` attribute within the subtotal object that explicitly states taxes are included, such as `"Subtotal (including taxes)"`. You must also include a `display_text` attribute for fulfillment entries (e.g. `"Shipping"`).

> [!NOTE]
> **Note:** This approach ensures price transparency and aligns with regional expectations for cohesive order confirmation and detail screens.

**Example: Tax-inclusive totals array**

The following example demonstrates a `totals` array for a merchant in a
tax-inclusive market:

    "totals": [
      {
        "type": "subtotal",
        "display_text": "Subtotal (including taxes)",
        "amount": 12500
      },
      {
        "type": "fulfillment",
        "display_text": "Shipping",
        "amount": 399
      },
      {
        "type": "total",
        "display_text": "Total",
        "amount": 12899
      }
    ]

### 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. For a multi-item session
created under version `2026-01-23` or later, the `line_items` array will
contain multiple item entries.

### 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}`

#### Update shipping address

- **Trigger:** User selects or changes their shipping address.

**Request:** Google updates the fulfillment address when the user changes their
shipping address.

    // Request Example: Update shipping address with multiple items.
    {
      "line_items": [
        {
          // line_items id from Create Checkout response
          "id": "line_1",
          "item": {
            "id": "product_12345"
          },
          "quantity": 1
        },
        {
          // line_items id from Create Checkout response
          "id": "line_2",
          "item": {
            "id": "product_67890"
          },
          "quantity": 1
        }
      ],
      "fulfillment": {
        "methods": [
          {
            "id": "method_shipping",
            "type": "shipping",
            "line_item_ids": [
              "line_1",
              "line_2"
            ],
            "destinations": [
              {
                "id": "addr_1",
                "address_locality": "Mountain View",
                "address_region": "CA",
                "postal_code": "94043",
                "address_country": "US"
              }
            ],
            "selected_destination_id": "addr_1",
            "groups": [
              {
                "id": "group_1",
                "selected_option_id": "ship_ground"
              }
            ]
          }
        ]
      }
    }

**Response:** You recalculate taxes and shipping options as necessary and return
the full checkout object.

    // Response Example: Updated session with new address for multiple items.
    {
      "id": "da2e25ec-eef8-41b7-a439-4e62dea41bdc",
      "currency": "USD",
      "line_items": [
        {
          "id": "line_1",
          "item": {
            "id": "product_12345",
            "title": "Running Shoes",
            "price": 10000,
            "image_url": "https://merchant.example.com/images/product_12345.png"
          },
          "quantity": 1,
          "totals": [
            { "type": "subtotal", "amount": 10000 },
            { "type": "total", "amount": 10000 }
          ]
        },
        {
          "id": "line_2",
          "item": {
            "id": "product_67890",
            "title": "T-Shirt",
            "price": 2500,
            "image_url": "https://merchant.example.com/images/product_67890.png"
          },
          "quantity": 1,
          "totals": [
            { "type": "subtotal", "amount": 2500 },
            { "type": "total", "amount": 2500 }
          ]
        }
      ],
      "totals": [
         { "type": "subtotal", "amount": 12500 },
         // Shipping cost might change based on new address
         { "type": "fulfillment", "display_text": "Ground Shipping", "amount": 600 },
         // Tax will likely change based on new address
         { "type": "tax", "amount": 1120 },
         { "type": "total", "amount": 14220 }
      ],
      "fulfillment": {
        "methods": [
          {
            "id": "method_shipping",
            "type": "shipping",
            "line_item_ids": ["line_1", "line_2"],
            "selected_destination_id": "addr_1",
            "destinations": [
              {
                "id": "addr_1",
                "address_locality": "Mountain View",
                "address_region": "CA",
                "postal_code": "94043",
                "address_country": "US"
              }
            ],
            "groups": [
              {
                "id": "group_1",
                "line_item_ids": ["line_1", "line_2"],
                "selected_option_id": "ship_ground",
                "options": [
                  {
                    "id": "ship_ground",
                    "title": "Ground (3-5 days)",
                    "description": "Estimated Delivery: Fri 5/8", // Maximum length: 200 characters.
                    "totals": [ { "type": "total", "amount": 600 } ]
                  },
                  {
                    "id": "ship_express",
                    "title": "Express (1-2 days)",
                    "description": "Estimated Delivery: Wed 5/6", // Maximum length: 200 characters.
                    "totals": [ { "type": "total", "amount": 1600 } ]
                  }
                ]
              }
            ]
          }
        ]
      }
      // ... other fields like ucp, status, messages, links
    }

#### Full checkout object hydration

**Request:** Google sends the full checkout object with the updated information
(including full fulfillment address and buyer contact) when the buyer
clicks "Pay with GPay".

    // Request Example: full checkout object hydration for multiple items.
    {
      "buyer": {
        "first_name": "John",
        "last_name": "Buyer",
        "email": "johnbuyer@example.com",
        "phone_number": "+18888888888"
      },
      "line_items": [
        {
          "id": "line_1",
          "item": { "id": "product_12345" },
          "quantity": 1
        },
        {
          "id": "line_2",
          "item": { "id": "product_67890" },
          "quantity": 1
        }
      ],
      "fulfillment": {
        "methods": [
          {
            "id": "method_shipping",
            "type": "shipping",
            "line_item_ids": ["line_1", "line_2"],
            "selected_destination_id": "addr_1",
            "destinations": [
              {
                "id": "addr_1",
                "first_name": "Alice",
                "last_name": "Receiver",
                "street_address": "1600 Amphitheatre Pkwy",
                "extended_address": "Suite #60",
                "address_locality": "Mountain View",
                "address_region": "CA",
                "postal_code": "94043",
                "address_country": "US",
                "phone_number": "+18888888888"
              }
            ],
            "groups": [
              {
                "id": "group_1",
                "selected_option_id": "ship_ground"
              }
            ]
          }
        ]
      }
    }

**Response:** You recalculate taxes and shipping options as necessary and return
the full checkout object.

    // Response Example: Session after full hydration with multiple items.
    {
      "ucp": {
        "version": "2026-01-23",
        "capabilities": {
          "dev.ucp.shopping.checkout": [ { "version": "2026-01-23" } ],
          "dev.ucp.shopping.fulfillment": [ { "version": "2026-01-23", "extends": "dev.ucp.shopping.checkout" } ]
        },
        "payment_handlers": {
          "com.google.pay": [
            {
              "id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
              "version": "2026-01-23",
              "spec": "https://pay.google.com/gp/p/ucp/2026-01-23/",
              "schema": "https://pay.google.com/gp/p/ucp/2026-01-23/schemas/config.json",
              "config": {
                "api_version": 2,
                "api_version_minor": 0,
                "environment": "TEST",
                "merchant_info": {
                  "merchant_name": "Example Merchant",
                  "merchant_id": "KWMZPRLQFTYNXSDB",
                  "merchant_origin": "checkout.merchant.com"
                },
                "allowed_payment_methods": [
                  {
                    "type": "CARD",
                    "parameters": {
                      "allowed_auth_methods": [ "PAN_ONLY", "CRYPTOGRAM_3DS" ],
                      "allowed_card_networks": [ "AMEX", "DISCOVER", "JCB", "MASTERCARD", "VISA" ],
                      "billing_address_required": true,
                      "billing_address_parameters": {
                        "format": "FULL",
                        "phone_number_required": true
                      }
                    },
                    "tokenization_specification": {
                      "type": "PAYMENT_GATEWAY",
                      "parameters": {
                        "gateway": "example",
                        "gatewayMerchantId": "exampleGatewayMerchantId"
                      }
                    }
                  }
                ]
              }
            }
          ]
        }
      },
      "id": "da2e25ec-eef8-41b7-a439-4e62dea41bdc",
      "status": "ready_for_complete",
      "currency": "USD",
      "buyer": {
        "first_name": "John",
        "last_name": "Buyer",
        "email": "johnbuyer@example.com",
        "phone_number": "+18888888888"
      },
      "line_items": [
        {
          "id": "line_1",
          "item": {
            "id": "product_12345",
            "title": "Running Shoes",
            "price": 10000,
            "image_url": "https://merchant.example.com/images/product_12345.png"
          },
          "quantity": 1,
          "totals": [
            { "type": "subtotal", "amount": 10000 },
            { "type": "total", "amount": 10000 }
          ]
        },
        {
          "id": "line_2",
          "item": {
            "id": "product_67890",
            "title": "T-Shirt",
            "price": 2500,
            "image_url": "https://merchant.example.com/images/product_67890.png"
          },
          "quantity": 1,
          "totals": [
            { "type": "subtotal", "amount": 2500 },
            { "type": "total", "amount": 2500 }
          ]
        }
      ],
      "totals": [
         { "type": "subtotal", "display_text": "Subtotal", "amount": 12500 },
         { "type": "fulfillment", "display_text": "Ground Shipping", "amount": 600 },
         { "type": "tax", "display_text": "Estimated Tax", "amount": 1120 },
         { "type": "total", "display_text": "Total", "amount": 14220 }
      ],
      "fulfillment": {
        "methods": [
          {
            "id": "method_shipping",
            "type": "shipping",
            "line_item_ids": ["line_1", "line_2"],
            "selected_destination_id": "addr_1",
            "destinations": [
              {
                "id": "addr_1",
                "first_name": "Alice",
                "last_name": "Receiver",
                "street_address": "1600 Amphitheatre Pkwy",
                "extended_address": "Suite #60",
                "address_locality": "Mountain View",
                "address_region": "CA",
                "postal_code": "94043",
                "address_country": "US",
                "phone_number": "+18888888888"
              }
            ],
            "groups": [
              {
                "id": "group_1",
                "line_item_ids": ["line_1", "line_2"],
                "selected_option_id": "ship_ground",
                "options": [
                  {
                    "id": "ship_ground",
                    "title": "Ground (3-5 days)",
                    "description": "Estimated Delivery: Fri 5/8", // Maximum length: 200 characters.
                    "totals": [ { "type": "total", "amount": 600 } ]
                  },
                  {
                    "id": "ship_express",
                    "title": "Express (1-2 days)",
                    "description": "Estimated Delivery: Wed 5/6", // Maximum length: 200 characters.
                    "totals": [ { "type": "total", "amount": 1600 } ]
                  }
                ]
              }
            ]
          }
        ]
      },
      "links": [
        {
          "type": "terms_of_service",
          "url": "https://m.com/terms",
          "title": "Terms of Service"
        },
        {
          "type": "privacy_policy",
          "url": "https://m.com/privacy",
          "title": "Privacy Policy"
        }
      ]
    }

## 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 "Pay with GPay", and Google receives a successful response from [fully hydrated checkout
  update](https://developers.google.com/merchant/ucp/implementation/2026-01-23/native-checkout-api#full_checkout_object_hydration).

**Request:** Google sends the selected payment instrument from the payment
handler including the credential (e.g. [Google Pay tokenization
data](https://developers.google.com/pay/api/web/reference/response-objects#PaymentMethodTokenizationData))
and [risk signals](https://developers.google.com/merchant/ucp/implementation/2026-01-23/risk-signals) about
the buyer for
you to perform your own fraud detection. The token contents will depend on
your Payments Service Provider.

    {
      "payment": {
        "instruments": [
          {
            "billing_address": {
              "first_name": "John",
              "last_name": "Buyer",
              "street_address": "100 Main St",
              "extended_address": "Apt 4B",
              "address_locality": "San Francisco",
              "address_region": "CA",
              "postal_code": "94105",
              "address_country": "US",
              "phone_number": "+18888888888"
            },
            "credential": {
              "token": "examplePaymentMethodToken",
              "type": "PAYMENT_GATEWAY"
            },
            "display": {
              "brand": "VISA",
              "description": "Visa •••• 1234",
              "last_digits": "1234"
            },
            "handler_id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
            "id": "94e7fee0-1a82-4c2a-9ef4-0861a3c829b2",
            "selected": true,
            "type": "card"
          }
        ]
      },
      "signals": {
        "com.google.authentication_triggered": "",
        "com.google.authorization_processed_with_3ds": "",
        "com.google.avs_full_result": "",
        "com.google.cvv_result": "",
        "com.google.ip_address": "203.0.113.1",
        "dev.ucp.buyer_id": "ec46fedc6aad89d3660a50a61d00b4908fd160ecf5dda6d49ed41a605c5b180a",
        "dev.ucp.buyer_ip": "203.0.113.1"
      }
    }

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.

    {
      "id": "da2e25ec-eef8-41b7-a439-4e62dea41bdc",
      "status": "incomplete",
      "messages": [
        {
          "type": "error",
          "code": "missing_buyer_info",
          "severity": "recoverable",
          "content": "Buyer email is required"
        },
        {
          "type": "error",
          "code": "missing_fulfillment_info",
          "severity": "recoverable",
          "content": "Select delivery window for your purchase"
        }
      ]
    }

Upon receiving a Google Pay payment instrument, you must:

1. **Validate handler:** Confirm `handler_id` corresponds to the Google Pay payment handler defined in your configuration.
2. **Extract token:** Retrieve the generated payment method token from `payment.instruments[0].credential.token`.
3. **Process payment:** Use the token and transaction details to complete payment. Refer to [Google Pay API
   documentation](https://developers.google.com/pay/api/web/reference/request-objects#PaymentMethodTokenizationSpecification) for detailed documentation on tokenization specification and handling.

**Response:** If checkout can be completed and you have processed payment, you
return the full checkout object indicating the order is complete, including
the confirmed payment instrument (echoing instrument metadata and billing
address, without the sensitive `credential` token or `signals`), the order
ID, and a permalink URL to the order.

    {
      "ucp": {
          "version": "2026-01-23",
          "capabilities": [...]
      },
      "id": "da2e25ec-eef8-41b7-a439-4e62dea41bdc",
      "status": "completed",

      // ... other fields (line_items, currency, etc.)

      "payment": {
        "instruments": [
          {
            "id": "94e7fee0-1a82-4c2a-9ef4-0861a3c829b2",
            "handler_id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
            "type": "card",
            "selected": true,
            "display": {
              "brand": "VISA",
              "description": "Visa •••• 1234",
              "last_digits": "1234"
            },
            "billing_address": {
              "first_name": "John",
              "last_name": "Buyer",
              "street_address": "100 Main St",
              "extended_address": "Apt 4B",
              "address_locality": "San Francisco",
              "address_region": "CA",
              "postal_code": "94105",
              "address_country": "US",
              "phone_number": "+18888888888"
            }
          }
        ]
      },
      "order": {
        "id": "ORD1773956535.2727807",
        // Example customer-facing order number
        "label": "#100",
        "permalink_url": "https://merchant.example.com/orders/789"
      }
    }

### 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`.

## Error handling

For complete guidelines on how to format error messages and the distinction
between protocol and business logic errors, see the [Error codes
overview](https://developers.google.com/merchant/ucp/guides/overview/error-codes).

### Unrecoverable Error

For version `2026-01-23`, when an unrecoverable business logic error prevents
checkout session creation (e.g., all items are out of stock), return an HTTP
`200 OK`.

In version `2026-01-23`, you
must indicate the terminal failure by omitting the checkout session ID and
specifying `"severity": "unrecoverable"` within the `messages` array. This tells
Google that the request was valid, but a business rule blocked the session
creation.

    HTTP/1.1 200 OK
    Content-Type: application/json

    {
      "ucp": {
        "version": "2026-01-23"
      },
      "messages": [
        {
          "type": "error",
          "code": "out_of_stock",
          "content": "All requested items are currently out of stock",
          "severity": "unrecoverable"
        }
      ],
      "continue_url": "https://merchant.com/"
    }