Halloween DealsAmazon USHalloween week deals: useful picks before month-endAmazon US: current deals, useful picks and tech finds.Check DealsSlow PC?RecommendedPC slow today? Run a repair scan before it gets worseResolve common Windows issues and optimize system performance.Scan NowHalloween DealsAmazon USOctober picks are moving - compare before checkoutAmazon US: current deals, useful picks and tech finds.See Picks×
FREEDOM251

Freedom251 › Blog › API integration

How to Test UCP Checkout in Merchant Center and Fix Integration Errors

By Freedom251 Team · · 10 min read

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Test the checkout capability your merchant actually implements, not a generic “UCP” endpoint. In Merchant Center, cart transfer and native checkout on Google have different simulations and production checklists. Start by confirming the account, market, UCP version, profile URL and sandbox credentials; then run capability-specific transactions and classify every failure as either a protocol/server failure or a business outcome.

The most damaging implementation mistakes are sending business errors with 4xx/5xx status codes, using an unrecognized error code, copying a response example from the wrong UCP version, and validating checkout without validating webhooks and profile discovery. The workflow below covers all of those checks.

As an Amazon Associate I earn from qualifying purchases.

Choose the UCP checkout path before testing

Merchant Center validation is capability-specific. Decide where the customer’s checkout finishes and select the corresponding path in the integration workflow.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Capability Where checkout completes Core operations to test Additional considerations
Transfer to merchant cart The merchant’s own cart and checkout Create a cart; where supported, get, update and cancel it Cart API behavior, product-ID matching and the cart-transfer production checklist
Native checkout on Google Google’s checkout experience using the merchant’s native checkout endpoints Create a checkout session, update it (for example, with shipping information), and complete it Account configuration, order status and webhook setup, the UCP Program Addendum, and optional identity linking
Identity linking Associated with native checkout Identity-linking validation in the Merchant Center workflow Use it only when the selected native-checkout design requires customer-account linking

Do not assume that passing one path proves the other. If an integration supports both native checkout and cart transfer, select and complete both capability checklists. The integration hub’s rollout is gradual and its stated scope covers products sold within the United States, so verify that the target account, feature and market are enabled in the live Merchant Center interface before investing in test automation.

#1 Best Overall
Eyoyo Mini 1D Bluetooth Barcode Scanner | 3-in-1 Bluetooth & USB Wired & 2.4G Wireless, Portable Bar Code Reader, Work with Windows, Android, iOS, Tablets or Computers
  • Super Mini Pocket 1D Scanner: Completely mini pocket size and ultralight at 35 g(1.2 oz), making the Eyoyo barcode scanner a better choice for portable use, especially for bookstores, online stores, retail shops, warehouses, and similar places
  • 3-in-1 Connection Ways: Easily switch between 2.4G wireless, Bluetooth, and USB wired modes to suit your needs; Eyoyo Bluetooth barcode scanner offers a transmission range of up to 30 m(98 ft) in 2.4G mode and up to 50 m(164 ft) in Bluetooth mode without barriers
  • Advanced 1D Scanning Technology: The Eyoyo 1D scanner effortlessly captures almost all common 1D barcodes, including UPC/EAN, Code 39, Interleaved 2 of 5, Code 93, Code 128, Codabar, Industrial 25, Matrix 25, and more; With superior decoding capability, it also can scan damaged, distorted, colorful, and reflective barcodes
  • Please Note: This scanner only supports printed 1D barcodes and does not support scanning any 1D codes or 2D QR codes from phone or computer screens or printed 2D QR codes; it is not compatible with square pos or square register systems
  • High Compatibility: The Eyoyo Bluetooth scanner seamlessly connects with laptops, PCs, POS systems, smartphones, tablets, iPhones, iPads, and other devices; It is compatible with common computer operating systems such as Windows XP/7/8/10/11, Mac OS, Linux

Prepare the test environment

Separate staging and production credentials

Keep sandbox or staging keys separate from production keys. The Merchant Center workflow asks for separate credentials for those environments. Record which UCP profile, API key or OAuth bearer token belongs to each environment so a successful sandbox run cannot be mistaken for production readiness.

Confirm account and market access

  • Open the Merchant Center UCP integration hub and confirm that the account can access the required workflow.
  • Verify that the selected capability is currently available for the account and the market in which products are sold.
  • Check the declared UCP version in the profile and implementation before copying any response shape or error example.
  • For a service-provider integration, confirm that the provider’s test account has been enabled for UCP sandbox access and advanced checkout-management services.

Publish and test profile discovery

Host a publicly reachable merchant profile over HTTPS at the exact /.well-known/ucp location. The endpoint must return valid JSON, declare the capabilities that the merchant intends to validate, and be reachable from Google’s test environment without an internal network, temporary tunnel or login wall. A profile that advertises native checkout while the Merchant Center flow is configured only for cart transfer creates a capability mismatch before the first cart or session request is made.

Assemble authentication material

Use the test API credentials requested by the sandbox flow. Depending on the integration, that can mean an API key or an OAuth bearer token. Check that the credential is active in the same environment as the profile and endpoints. An expired token, a key restricted to a different project, or a staging profile paired with a production credential should be diagnosed as an authentication or configuration problem, not as a checkout business error.

Free tools Windows power users keep installed

One-click scans. No signup required.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Run Merchant Center sandbox simulations

The sandbox asks you to provide the UCP profile location and applicable test credentials, then exercises the operations associated with the selected capability. Run the following sequence for each environment.

Rank #2
Sale
Tera Barcode Scanner Wireless 1D Laser Cordless Barcode Reader with Battery Level Indicator, Versatile 2 in 1 2.4Ghz Wireless and USB 2.0 Wired
  • Larger battery enables longer continuous usage and twice the stand-by time. With the unique battery indicator light showing the remaining battery level, no more Low Battery Anxiety.
  • The curved handle is extended and widened. With specially designed smooth and flat trigger for a better grip.
  • The orange anti shock silicone protective cover can prevent scratches and friction even when dropped from up to 6.56 feet. IP54 technology protects the wireless barcode scanner from dust.
  • Plug and play with the USB receiver or the USB cable, no driver installation needed. Easy and quick to set up. Wireless transmission distance reaches up to 328 ft. in barrier free environment.
  • Supports almost all 1D Barcodes: Febraban Bank Code, Codabar, Code 11, Code93, MSI, Code 128, EAN-128, Code 39, EAN-8, EAN-13, UPC-A, ISBN, Industrial 25, Interleaved 25, Standard 25, Matrix. Reads damaged, fuzzy, reflective and smudged barcodes.
  1. Declare the capability. Select transfer to merchant cart, native checkout, identity linking, or the supported combination in the integration hub. Save the selected UCP version and environment in the test record.
  2. Submit the profile location. Enter the public HTTPS URL that resolves to the merchant’s /.well-known/ucp profile. Confirm that the returned JSON is valid and that its capability declarations match the selection made in step one.
  3. Supply test authentication. Enter the sandbox API key or OAuth bearer token. Do not reuse production secrets in the sandbox form.
  4. Run the capability simulation. Follow the operation set for the selected path. Record request identifiers, HTTP status, response messages and timestamps for every action.
  5. Repeat after correcting one class of fault. Change one variable at a time—profile discovery, authentication, payload, business fixture or webhook endpoint—so the next result identifies the fix rather than masking several simultaneous changes.

Cart-transfer simulation

At minimum, create a cart using the product and quantity fixture supplied by the test. Where the selected implementation supports them, retrieve the cart, update its contents or quantities, and cancel it. Verify that product IDs, quantities, prices and availability in the cart response agree with the merchant’s declared configuration. A cart that is created successfully but cannot be retrieved or cancelled is not a complete cart-transfer implementation.

Native-checkout simulation

Exercise checkout-session creation first, then an update such as shipping information, and finally completion. Check that each response reflects the current totals and fulfillment choices. A successful create call does not prove that updates or completion are safe: those stages can expose tax, shipping, inventory, payment or fraud rules that are not evaluated during session creation.

End-to-end service-provider simulation

Service providers should run the additional end-to-end transaction tests in their sandbox. These tests verify payload validation, the format of error responses and webhook acknowledgements, rather than checking only whether an endpoint returns a response. Keep the webhook delivery and acknowledgement logs with the checkout trace; an order can appear to complete while its lifecycle notification is failing.

What’s actually slowing this PC down?

Pick the symptom - the matching free tool is one click away.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Classify failures by HTTP layer and business layer

UCP’s error model separates transport or protocol failures from expected business outcomes. Applying the wrong class is a common reason for confusing Merchant Center messages.

Rank #3
NETUM Bluetooth Barcode Scanner, Support 2.4G Wireless & Bluetooth & Wired Connect Smart Phone, Tablet, PC, CCD Bar Code Reader Work with Windows, Mac,Android (NT-1228BC)
  • Widely Compatible: Bluetooth Barcode Scanner for iPhone iPad Android Tablet PC, Support HID / SPP / BLE mode via bluetooth, Work with Windows XP/7/8/10, Mac OS, Windows Mobile, Android OS, iOS, Linux.
  • Strong Recognition Ability: With the 2500 pixels high-resolution CCD sensor Engine, Rapidly decodes all 1D and stacked barcodes (including ISBN book), even worn, damaged or tightly spaced codes. Scan 1D codes directly from paper or screen, such as a computer monitor, smartphone, or tablet, or scan through glass surfaces, plastic shrink wrap, a CCD scanner is likely the best way to go.
  • Automatic Scanning: NT-1228bc barcode scanner have three scanning modes: manual trigger mode, continuous scanning mode and auto-sensing scanning mode. In addition, there is a storage mode. Storage mode can be used when you are out of range of Bluetooth and wireless connectivity. Supports storage of up to 100,000 barcodes. Note: Before use, you need to scan the corresponding setting barcode on the manual.
  • 2600mAh Battery Upgraded: Continuous scanning up to 200,000 times on a full charge. After a full charge the scanner can be used for one month at least, even in warehouses and at pos checkout counters where scanners are frequently used. In libraries and hospitals it can be used even longer.
  • Programmable Configuration: Add custom prefixes/ suffixes, delete characters, Add keyboard keys/ combinations (terminator TAB, CR&LF, Home etc.), Enable or disable the barcode type as you want. Buzzer can be set to mute to allow for a quiet operation.(Note: It does not work with square POS / Divalto / DoorDash / Lightspeed POS system)
Situation How to report it Typical examples What to inspect
Malformed request, invalid authentication or unavailable server Use the appropriate standard HTTP status and protocol-level details Invalid request shape, rejected credential, timeout or server outage HTTP status, authentication configuration, request schema and server availability
Business rule or checkout outcome Return HTTP 200 with a structured messages array Out of stock, payment decline, fraud rejection, changed totals or quantity limit Canonical UCP code, message type, human-readable content, severity and affected path

Payment declines and fraud rejections are business outcomes under the published error guidance, so they should not be converted into a generic 4xx or 5xx response merely because the order cannot proceed. Conversely, a server that cannot parse a request or authenticate a caller should not pretend that the customer’s cart is out of stock.

Use canonical codes, not a generic invalid

Every business message needs the canonical UCP code, a message type, readable content and the required severity. Use the path field when it helps identify the affected request or response field. Published examples include out_of_stock, item_unavailable, item_ineligible, quantity_invalid_limit_exceeded, quantity_invalid_minimum_not_met and totals_changed. Select the code whose documented meaning matches the actual condition and follow the published recoverability guidance for that code.

Do not invent a broad code such as invalid. Google warns that an unrecognized code can cause the Google UI to fall back to a generic “something went wrong” message, producing a poor checkout experience and hiding the action the customer should take.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Keep error content safe

Error messages must not contain personally identifiable information or sensitive personal information. Log a private correlation ID on your side and return a safe, customer-appropriate explanation through the UCP message. Do not place an email address, phone number, payment credential, government identifier or other sensitive value in the code, message text or field path.

Rank #4
WoneNice USB Laser Barcode Scanner Wired Handheld Bar Code Scanner Reader Black
  • Plug and play, This laser handheld barcode scanner has simple installation with any USB port and Ideal for businesses, shops and warehouse operations. Its function is unbeatable and easy to use, design is stylish
  • Compatible with Windows, Mac, and Linux; works with Word, Excel, Novell, and all common software
  • Scanning Speed: 200 scans per second. Scanning angle: Inclination angle 55°, Elevation angle 65°. Operational Light Source:Visible Laser 650-670nm.
  • Decode Capability: Code11, Code39, Code93, Code32, Code128, Coda Bar, UPC-A, UPC-E, EAN-8, EAN-13, ISBN/ISSN, JAN.EAN/UPC Add-on2/5 MSI/Plessey, Telepen and China Postal Code,Interleaved 2 of 5, Industrial 2 of 5, Matrix 2 of 5, etc ; 300 configurable options for prefix, suffix and termination strings, support turn on/off the beep.
  • Color: Black. Dimensions: 3.6 x 2.6 x 6.1 inches. Type of Cable: 2M or 6ft straight cable. Shock: 1.5m drop on concrete surface. Regulatory Approvals: FCC CE.

Match response details to the declared UCP version

Version drift is a real failure mode. The native-checkout implementation guide dated January 23, 2026 illustrates an unrecoverable session-creation failure with no checkout session ID and an unrecoverable message severity. An April 8, 2026 guide adds ucp.status: "error" to its illustrated response. Those examples are not interchangeable contracts.

  1. Read the UCP version declared by the integration and profile.
  2. Open the implementation and error guidance for that exact version.
  3. Compare required top-level fields, status values, severity values and session identifiers.
  4. Update fixtures, schema validation and negative tests together.
  5. Retest both a recoverable business outcome and an unrecoverable protocol or session-creation failure.

If one copied example passes in a local test while Merchant Center rejects it, compare versions before changing business logic. A response can be semantically correct for one dated guide and structurally wrong for another.

Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Validate the integration plumbing beyond checkout

A checkout endpoint is only one component of a production integration. The service-provider setup requirements identify four pieces that must work together:

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
  • Checkout endpoints: implement the operations required by the chosen capability.
  • Order lifecycle webhooks: publish order-state changes and acknowledge deliveries correctly.
  • Hosted merchant profile: serve valid JSON over publicly reachable HTTPS at /.well-known/ucp.
  • Account relationship notifications: support a redirect callback or ACCOUNT_SERVICE_CHANGE notifications for service proposals and account changes.

Include each component in monitoring and test evidence. A green checkout transaction with a missing order webhook acknowledgement leaves Google without a reliable order state. Likewise, an endpoint can be perfectly implemented while profile discovery fails because the URL redirects to a private host or returns HTML instead of JSON.

Best Value
NetumScan USB 1D Barcode Scanner, Handheld Wired CCD Barcode Reader (1)
  • CCD Image Scanning Technology - NetumScan 1D barcode reader is equiped with advanced CCD sensor, which can quick capture 1D codes from paper and screen, including CODE128, UPC/EAN Add on 2 or 5, that can read even deformed barcodes, i.e. smudged, damaged, fuzzy, reflective barcodes, etc. Reading faster and more accurate than laser scanner.
  • Sturdy Anti-shock and Durable Design - Ergonomic design with high-quality ABS making it can support withstand repeated drops from 2m high to the concrete ground, durable to use. Durable plastic material guarantees long service life.
  • Three scanning mode - Key trigger mode + Auto-induction mode + Continuous Mode. There is no need to pull the trigger in auto-sensing mode and continuous scanning. Sometimes the self-sensing scanning function is in the inactive stage, please contact us and be at your service at any time.
  • Supported 1D Bar Code - 1D Decode Capability: UPC-A, UPC-E, EAN-8, EAN-13, ISSN, ISBN, Code 128, GS1-128, Code39, Code93,Code32, Code11, UCC/EAN128, Interleaved 2 of 5, Industrial 2 of 5, Codabar(NW-7), MSI, Plessey, RSS, China Post, etc.
  • Widely Use Range - This NetumScan Handheld USB barcode scanner can be used in supermarkets, convenience stores, warehouse, library, bookstore, drugstore, retail shop for file management, inventory tracking and POS(point of sale), etc.

Complete the Merchant Center production validation

Native checkout checklist

  1. Select native checkout and confirm the account configuration required by the integration.
  2. Publish the production UCP profile location and verify its capability declarations.
  3. Complete native checkout endpoint validation for session creation, updates and completion.
  4. Run optional identity-linking validation when account linking is part of the implementation.
  5. Configure order status and webhook delivery, then verify acknowledgements.
  6. Review and accept the UCP Program Addendum in the Merchant Center flow.
  7. Submit the completed validation for Google’s review.

Cart-transfer checklist

  1. Select transfer to merchant cart and publish the production profile location.
  2. Confirm that Merchant Center product IDs match the IDs accepted by the Cart API.
  3. Validate cart creation and the supported get, update and cancel operations.
  4. Verify that the merchant’s cart receives the expected items, quantities and totals.
  5. Submit the completed capability validation for Google’s review.

When both paths are implemented, the production configuration must declare both capabilities accurately and both checklists must be completed. Do not mark a capability as supported merely because the endpoint exists; it must pass the corresponding validation flow.

Service-provider enablement and onboarding checks

Service providers have prerequisites in addition to merchant checkout testing. Sandbox access requires a Google enablement request and test-account setup. The documented prerequisites include Merchant API registration, test accounts, a deployed UCP profile, deployed endpoints and webhooks, and handshake handling. Access to the sandbox UI and advanced checkout-management services can be blocked until enablement is approved.

For merchant relationships, implement the account-change path as well as the transaction path. A service proposal may require a redirect callback, while other relationship changes arrive through ACCOUNT_SERVICE_CHANGE notifications. Test acceptance, rejection, expiration and acknowledgement behavior so a provider can recover when a merchant changes or ends the relationship.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Common Merchant Center errors and fixes

Symptom Likely cause Fix sequence
Sandbox cannot discover the implementation Wrong profile URL, inaccessible HTTPS host, invalid JSON or mismatched declarations Request the exact /.well-known/ucp URL directly, verify a valid JSON response, check public TLS access, then compare declared and selected capabilities.
Authentication fails before a transaction Wrong environment, expired key, invalid bearer token or account mismatch Use the sandbox credential for the sandbox profile and endpoint; rotate or refresh the credential and rerun discovery before testing checkout logic.
Google displays a generic failure for a known stock or payment issue Unrecognized or generic business error code Map the condition to the published canonical code, include severity and any relevant path, and return it in HTTP 200.
Business error is returned as 4xx or 5xx Business and protocol error classes were conflated Reserve HTTP errors for transport or protocol failures; express stock, payment, fraud, quantity and total outcomes through structured messages with HTTP 200.
Copied unrecoverable example fails schema validation Response was copied from a different dated UCP guide Check the declared version and use its required status, session-ID and severity fields.
Checkout completes but order state does not update Lifecycle webhook is missing, unreachable or not acknowledged Inspect delivery logs, endpoint authentication, response status and acknowledgement handling; rerun the end-to-end transaction.
Production checklist shows unexpected capabilities Profile declarations do not match Merchant Center selections Align the profile, selected capability and endpoint implementation, then restart the affected validation flow.
Test setup is blocked before the first transaction Provider account or Google UCP enablement is incomplete Confirm Merchant API registration, test accounts, deployed profile, endpoints, webhooks and handshake handling; complete the enablement request.

Build a repeatable UCP test record

For every run, preserve the environment, account, market, declared UCP version, capability, profile URL, credential type, operation, HTTP status, canonical message code, severity, affected path and webhook acknowledgement. This record lets an engineer distinguish a changed business fixture from a protocol regression and provides evidence for Google’s review.

  • Use fixtures for available, unavailable, out-of-stock, minimum-quantity and maximum-quantity cases.
  • Include a changed-total case so the client handles recalculation instead of assuming the original amount remains valid.
  • Include payment-decline and fraud-rejection cases as HTTP 200 business outcomes.
  • Test an unreachable profile, invalid JSON and invalid credentials as protocol or setup failures.
  • Run version-specific schema tests for both successful and unrecoverable responses.
  • Verify webhook retries and acknowledgements independently of checkout-session success.

Finally, recheck availability and rollout status before production onboarding. UCP capabilities, account access and schemas are evolving; the live Merchant Center account and the implementation guide matching the declared version are the authority for the release you are deploying.

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.

API integrationcheckout testingecommerce developersGoogle Merchant CenterUCPwebhooks

Leave a Reply

Your email address will not be published. Required fields are marked *

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Recommended PC Tool
Recommended PC Tool
PC Slower Than It Used to Be?Free scan - under a minute
Outdated Drivers Are Slowing You DownFree scan - exact matches

Two free Windows tools

One Free Minute Could Fix That PC

Before you go - each of these free tools takes about a minute and tackles what quietly slows a Windows PC down.

Special offer. View Outbyte info, uninstall instructions, EULA, and Privacy Policy.