Understand how Universal Commerce Protocol (UCP) checkout session data maps between Google's UCP and commercetools.
UCP checkout requests are translated from Google into commercetools Cart and Order operations. This page details the field-level mapping for the cart operations and for each phase of the checkout lifecycle.
Cart
For the behavior of the cart operations, see Cart.
Request mapping
When an agent sends a Create Cart or Update Cart request, the component creates a CartDraft or replaces the Line Items and buyer information of the existing Cart.
| UCP field | Related commercetools field | Remarks |
|---|---|---|
request.line_items[*].item.id | CartDraft.lineItems[*].sku | |
request.line_items[*].quantity | CartDraft.lineItems[*].quantity | |
request.buyer.email | CartDraft.customerEmail | |
request.buyer.first_name | CartDraft.billingAddress.firstName | |
request.buyer.last_name | CartDraft.billingAddress.lastName | |
request.buyer.phone_number | CartDraft.billingAddress.phone | |
request.context.language | Not applicable | Localizes the Line Item names in the response. The Cart is stored in the Store's language. |
request.context.currency | Not applicable | The Store currency is used. A different currency is refused on create and ignored on update. |
| Not applicable | CartDraft.currency | Specified by the Store configuration. |
| Not applicable | CartDraft.country | Derived from the Store configuration. |
| Not applicable | CartDraft.store | Specified by the component configuration. |
| Not applicable | CartDraft.lineItems[*].distributionChannel | Specified by the component configuration. |
| Not applicable | CartDraft.lineItems[*].supplyChannel | Specified by the component configuration. |
Response mapping
The Create, Get, Update, and Cancel Cart operations return a response mapped from the Cart.
| UCP field | Related commercetools field | Remarks |
|---|---|---|
id | cart.id | |
currency | cart.totalPrice.currencyCode | |
context.language | Not applicable | The language the response is localized in. |
context.address_country | cart.shippingAddress.country | Only when the Cart has a shipping address. |
line_items | cart.lineItems | |
line_items[*].id | cart.lineItems[*].key or cart.lineItems[*].id | The key, when the Line Item has one. |
line_items[*].item.id | cart.lineItems[*].variant.sku | |
line_items[*].item.title | cart.lineItems[*].name[<locale>] | Falls back to the SKU when the name has no value in the language. |
line_items[*].item.price | cart.lineItems[*].price.value.centAmount | The discounted price, when the price has a discount. |
line_items[*].item.image_url | cart.lineItems[*].variant.images[0].url | First image from the Variant. |
line_items[*].quantity | cart.lineItems[*].quantity | |
buyer.first_name | cart.billingAddress.firstName | |
buyer.last_name | cart.billingAddress.lastName | |
buyer.email | cart.customerEmail | |
buyer.phone_number | cart.billingAddress.phone | |
expires_at | cart.lastModifiedAt plus cart.deleteDaysAfterLastModification | Omitted when the Cart has no deletion window. |
continue_url | cart.store.custom.fields.continueUrl | Included only when the Store publishes a checkout URL. |
links[*].url | cart.store.custom.fields | Refer to link mapping. Included only when the Store publishes policy links. |
Create Checkout Session
Request mapping
When Google sends a Create Checkout Session request, a CartDraft is created in commercetools.
| UCP field | Related commercetools field | Remarks |
|---|---|---|
request.currency | CartDraft.currency | |
request.line_items | CartDraft.lineItems[] | |
request.line_items[*].item.id | CartDraft.lineItems[*].sku | |
request.line_items[*].quantity | CartDraft.lineItems[*].quantity | |
request.buyer.first_name | CartDraft.billingAddress.firstName | |
request.buyer.last_name | CartDraft.billingAddress.lastName | |
request.buyer.email | CartDraft.customerEmail | |
request.buyer.phone_number | CartDraft.billingAddress.phone | |
request.payment.instruments | CartDraft.store | Specified by the component configuration. |
| Not applicable | CartDraft.country | Derived from the Store configuration. |
| Not applicable | CartDraft.lineItems[*].distributionChannel | Specified by the component configuration. |
| Not applicable | CartDraft.lineItems[*].supplyChannel | Specified by the component configuration. |
| Not applicable | CartDraft.lineItems[*].inventoryMode | Specified by the component configuration. |
header.Idempotency-Key | CartDraft.key |
Response mapping
The component returns a checkout session response mapped from the Cart.
| UCP field | Related commercetools field | Remarks |
|---|---|---|
id | cart.id | |
line_items | cart.lineItems | |
line_items[*].id | cart.lineItems[*].variant.sku | |
line_items[*].item.id | cart.lineItems[*].sku | |
line_items[*].item.title | cart.lineItems[*].name[<locale>] | Localized line item name. |
line_items[*].item.price | cart.lineItems[*].price.value.centAmount | |
line_items[*].item.image_url | cart.lineItems[*].variant.images[0].url | First image from the Variant. |
line_items[*].quantity | cart.lineItems[*].quantity | |
line_items[*].total | Line item amount calculation | Refer to the line item total calculation logic. |
buyer.first_name | cart.billingAddress.firstName | |
buyer.last_name | cart.billingAddress.lastName | |
buyer.email | cart.customerEmail | |
buyer.phone_number | cart.billingAddress.phone | |
status | Not applicable | Set to "incomplete". |
currency | cart.totalPrice.currencyCode | |
links[*].url | cart.store.custom.fields | Refer to link mapping. |
expires_at | Not applicable | Current timestamp plus cart.store.custom.fields.expiryInHour. |
continue_url | cart.store.custom.fields.continueUrl | |
payment.handlers | UCP profile | Fetched from the UCP profile configuration. |
Update Checkout Session
Request mapping
When Google sends an Update Checkout Session request, the component updates the existing Cart.
| UCP field | Related commercetools field | Remarks |
|---|---|---|
request.id | cart.id | |
request.currency | CartDraft.currency | |
request.line_items | CartDraft.lineItems[] | |
request.line_items[*].item.id | CartDraft.lineItems[*].sku | |
request.line_items[*].quantity | CartDraft.lineItems[*].quantity | |
request.buyer.first_name | cart.billingAddress.firstName | |
request.buyer.last_name | cart.billingAddress.lastName | |
request.buyer.full_name | cart.billingAddress.firstName and cart.billingAddress.lastName | Split into first and last name fields. |
request.buyer.email | cart.customerEmail | |
request.buyer.phone_number | cart.billingAddress.phone | |
request.fulfillment.methods[*].destinations[*].postal_code | cart.shippingAddress.postalCode | |
request.fulfillment.methods[*].destinations[*].country | cart.shippingAddress.country | |
request.fulfillment.methods[*].destinations[*].address_region | cart.shippingAddress.state | |
header.Idempotency-Key | CartDraft.key |
Response mapping
The updated checkout session response is mapped from the updated Cart.
| UCP field | Related commercetools field | Remarks |
|---|---|---|
id | cart.id | |
line_items | cart.lineItems | Same mapping as Create response. |
buyer.first_name | cart.billingAddress.firstName | |
buyer.last_name | cart.billingAddress.lastName | |
buyer.email | cart.customerEmail | |
buyer.phone_number | cart.billingAddress.phone | |
status | Not applicable | Set to "ready_for_payment". |
currency | cart.totalPrice.currencyCode | |
expires_at | Not applicable | Current timestamp plus cart.store.custom.fields.expiryInHour. |
continue_url | cart.store.custom.fields.continueUrl | |
payment.handlers | UCP profile | Fetched from the UCP profile configuration. |
Complete Checkout Session
Request mapping
When Google sends a Complete Checkout Session request with the Google Pay payment token, it authorizes payment and creates an Order.
| UCP field | Related commercetools field | Remarks |
|---|---|---|
payment_data.billing_address.street_address | cart.billingAddress.streetName and cart.billingAddress.streetNumber | |
payment_data.billing_address.address_locality | cart.billingAddress.city | |
payment_data.billing_address.address_region | cart.billingAddress.state | |
payment_data.billing_address.address_country | cart.billingAddress.country |
Response mapping
The completed checkout session response is mapped from the created Order.
| UCP field | Related commercetools field | Remarks |
|---|---|---|
id | cart.id | |
line_items | order.lineItems | |
line_items[*].id | order.lineItems[*].variant.sku | |
line_items[*].item.id | order.lineItems[*].sku | |
line_items[*].item.title | order.lineItems[*].name.en | |
line_items[*].item.price | order.lineItems[*].price.value.centAmount | |
line_items[*].item.image_url | order.lineItems[*].variant.images[0].url | |
line_items[*].quantity | order.lineItems[*].quantity | |
line_items[*].total | Order line item amount calculation | |
buyer.first_name | order.billingAddress.firstName | |
buyer.last_name | order.billingAddress.lastName | |
buyer.email | order.customerEmail | |
buyer.phone_number | order.billingAddress.phone | |
status | Not applicable | Set to "completed". |
currency | cart.totalPrice.currencyCode |