Skip to content

NetFabric/intelligentium / plugins/ucp/.apm/skills/ucp-business-integration

ucp-business-integration

Verified

Implement the Universal Commerce Protocol (UCP) as a business/merchant: publish a /.well-known/ucp discovery profile, declare capabilities (Checkout, Cart, Order, Identity Linking) and payment handlers, implement REST checkout-session endpoints (create/get/update/complete/cancel), resolve payment instruments, sign responses and order webhooks (RFC 9421), and integrate with Google Merchant Center (product feed eligibility, Google Pay handler, order webhooks). USE FOR: building a UCP-compliant business/merchant server; publishing and hosting a UCP profile; declaring capabilities, extensions, and payment_handlers; implementing the checkout status lifecycle and error messages; signing webhook/response messages; Google UCP merchant integration. DO NOT USE FOR: building a platform/agent that consumes UCP (see ucp-platform-integration); generic e-commerce platform work unrelated to UCP; the AP2/A2A/MCP protocols outside their UCP bindings.

UCP Business Integration

UCP lets a business (merchant/retailer) publish one machine-readable profile that platforms and AI agents discover to run checkout, cart, and order flows — no bespoke integration per platform.

Anatomy

FilePurpose
SKILL.mdRoles, profile skeleton, capability/endpoint quick-reference
references/profile-and-discovery.mdHosting /.well-known/ucp, namespace governance, negotiation, versioning
references/capabilities-and-checkout.mdCheckout/Cart/Order/Identity Linking, status lifecycle, error handling, totals
references/payments-and-signing.mdAdvertising payment handlers, instrument resolution, PCI scope, RFC 9421, AP2
references/google-merchant-integration.mdMerchant Center setup, feed flags, Google Pay handler, order webhook to Google

Roles

RoleYou are...Responsibility
Business (you)Merchant of RecordPublish profile, declare capabilities, process sessions
PlatformApp/AI agent consuming your capabilitiesDiscovers you, drives the session
Credential Provider (CP)Wallet/identity provider (Google Pay, Shop Pay)Issues payment tokens, holds PII
PSPPayment processor (Stripe, Adyen, ...)Authorizes/captures/settles funds

Minimal Business Profile

Published at GET /.well-known/ucp (HTTPS, no redirects, Cache-Control: public, max-age>=60):

{
  "ucp": {
    "version": "2026-04-08",
    "services": { "dev.ucp.shopping": [{ "version": "2026-04-08", "transport": "rest",
      "endpoint": "https://business.example.com/ucp/v1",
      "schema": "https://ucp.dev/2026-04-08/services/shopping/rest.openapi.json" }] },
    "capabilities": { "dev.ucp.shopping.checkout": [{ "version": "2026-04-08",
      "spec": "https://ucp.dev/2026-04-08/specification/checkout",
      "schema": "https://ucp.dev/2026-04-08/schemas/shopping/checkout.json" }] },
    "payment_handlers": { }
  },
  "signing_keys": [{ "kid": "business_2026", "kty": "EC", "crv": "P-256", "x": "...", "y": "...", "use": "sig", "alg": "ES256" }]
}

Standard Capabilities

CapabilityPurpose
dev.ucp.shopping.cartPre-checkout basket transfer (CreateCart only today)
dev.ucp.shopping.checkoutCheckout sessions: cart, tax, payment, order placement
dev.ucp.shopping.orderPost-purchase webhook updates (shipped, delivered, adjustments)
dev.ucp.common.identity_linkingOAuth 2.0 account linking for authenticated checkout
Extensions: discount, fulfillment, payment_authentication, ap2_mandate, buyer_consentOptional, extends a root capability via allOf

Checkout REST Endpoints

OperationMethod & Path
Create CheckoutPOST /checkout-sessions
Get CheckoutGET /checkout-sessions/{id}
Update CheckoutPUT /checkout-sessions/{id} (full replacement)
Complete CheckoutPOST /checkout-sessions/{id}/complete
Cancel CheckoutPOST /checkout-sessions/{id}/cancel

Workflow: New Business Integration

  1. Prepare product data — mark checkout eligibility, disclosures, return/support policy.
  2. Publish your UCP profile declaring services, capabilities, payment_handlers, signing_keys.
  3. Implement the 5 Checkout REST operations and the status lifecycle (incomplete → ... → completed).
  4. Advertise and resolve payment handlers; sign responses and webhooks (RFC 9421).
  5. Default to guest checkout, or implement Identity Linking (OAuth 2.0) for account-linked flows.
  6. Push Order lifecycle webhooks (created, shipped, delivered, adjustments) to each linked platform.

Reference Files

FileLoad When
references/profile-and-discovery.mdHosting/serving the profile, validating namespaces, negotiating capabilities/versions with a platform
references/capabilities-and-checkout.mdImplementing checkout operations, status transitions, error messages, totals, or identity linking
references/payments-and-signing.mdAdvertising payment handlers, resolving instruments, signing messages, or supporting AP2 mandates
references/google-merchant-integration.mdIntegrating with Google Merchant Center, AI Mode, or Gemini checkout
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall