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 each phase of the checkout lifecycle.
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 |