> ## Documentation Index > Fetch the complete documentation index at: https://docs.omnicommerce.ai/llms.txt > Use this file to discover all available pages before exploring further. # Manage customer-owned purchase offers > ### Operations create: offers[] (1–5), with stable requestId, exact purchasable product/variant IDs, quantities, shipping country and optional unitAmount proposals. get/cancel: sessionIds[] (1–20). complete: sessionId, paymentProof, and buyer approval of cartVersion, totalAmount and currency. pay: sessionId and the same exact approval; returns checkoutUrl for Stripe-hosted card entry. ### Results and safeguards Batches return ordered per-target results, succeededCount and failedCount. At most ten unpaid offers may be held per customer. Merchant-approved currency, countries, shipping and tax terms are required. Shopify-listed products return the supported Shopify checkout handoff. ### Payment Completion reuses the existing Stripe ACP or x402 rail. Hosted card checkout requires this organization's seller Stripe key and a public HTTPS webhook destination; signed Stripe events and a one-shot durable deadline use the same completion service. The page collects an address within the quoted country. Indeterminate confirmation remains payment_pending and blocks a new payment; x402 uncertainty requires merchant reconciliation. Direct creation honors configured bot verification. Payment completion does not book a carrier or establish delivery. ### Signed offers and buyer agents When the platform signing key is configured, payable offers include checkoutJwt: an ES256 JWT of the offer terms (merchant, cart_version, UCP line items and totals in minor units, expiry). Verify it with the /.well-known/ucp signing_keys entry named by its kid; it can serve as an AP2 checkout_jwt. Requests may carry a Web Bot Auth signature (Signature, Signature-Input and Signature-Agent headers); the verified agent origin is recorded on the offer and order. ## OpenAPI ````yaml /openapi.json post /api/embed/{deploymentId}/checkout-sessions/{operation} openapi: 3.1.0 info: title: OmniCommerce API version: 1.0.0 license: name: Proprietary url: https://omnicommerce.sg/terms description: >- OmniCommerce API surface for agents and developer integrations. Includes public endpoints (merchant discovery, product search, compare, catalog, ACO retrieval) and authenticated endpoints (product management via API key Bearer tokens). servers: - url: https://omnicommerce.sg description: Production - url: http://localhost:3000 description: Local development security: [] tags: - name: agentic-checkout description: Merchant-fulfilled agentic checkout x-group: Agentic Checkout - name: agents description: agents x-group: Agents - name: analytics description: Sales performance across marketplaces x-group: Analytics - name: aops description: Agent operating procedures x-group: AOPs - name: branding description: branding x-group: Branding - name: campaigns description: Campaign briefs, offer windows, and marketplace runs x-group: Campaigns - name: developer-platform description: Authenticated developer platform APIs x-group: Developer Platform - name: documents description: Knowledge base document uploads x-group: Knowledge Base - name: inventory description: Inventory quantities, planning signals, and marketplace listing absence x-group: Inventory - name: looks description: AI-styled product looks x-group: Looks - name: oauth description: OAuth token endpoints x-group: OAuth - name: orders description: Workspace and agentic orders x-group: Orders - name: organizations description: Organization management x-group: Organizations - name: price-books description: Marketplace list-price markup rules x-group: Price Books - name: products description: Product CRUD, bulk import, enrichment, publish, and delist x-group: Products - name: promotions description: Central promotions and marketplace sync x-group: Promotions - name: public-agent description: Public agent discovery and catalog APIs x-group: Public Agent - name: returns description: returns x-group: Returns - name: reviews description: Marketplace product reviews and seller replies x-group: Reviews - name: settlements description: settlements x-group: Settlements - name: ucp description: Universal Commerce Protocol x-group: UCP paths: /api/embed/{deploymentId}/checkout-sessions/{operation}: post: tags: - agentic-checkout summary: Manage customer-owned purchase offers description: >- ### Operations create: offers[] (1–5), with stable requestId, exact purchasable product/variant IDs, quantities, shipping country and optional unitAmount proposals. get/cancel: sessionIds[] (1–20). complete: sessionId, paymentProof, and buyer approval of cartVersion, totalAmount and currency. pay: sessionId and the same exact approval; returns checkoutUrl for Stripe-hosted card entry. ### Results and safeguards Batches return ordered per-target results, succeededCount and failedCount. At most ten unpaid offers may be held per customer. Merchant-approved currency, countries, shipping and tax terms are required. Shopify-listed products return the supported Shopify checkout handoff. ### Payment Completion reuses the existing Stripe ACP or x402 rail. Hosted card checkout requires this organization's seller Stripe key and a public HTTPS webhook destination; signed Stripe events and a one-shot durable deadline use the same completion service. The page collects an address within the quoted country. Indeterminate confirmation remains payment_pending and blocks a new payment; x402 uncertainty requires merchant reconciliation. Direct creation honors configured bot verification. Payment completion does not book a carrier or establish delivery. ### Signed offers and buyer agents When the platform signing key is configured, payable offers include checkoutJwt: an ES256 JWT of the offer terms (merchant, cart_version, UCP line items and totals in minor units, expiry). Verify it with the /.well-known/ucp signing_keys entry named by its kid; it can serve as an AP2 checkout_jwt. Requests may carry a Web Bot Auth signature (Signature, Signature-Input and Signature-Agent headers); the verified agent origin is recorded on the offer and order. operationId: post_embed_by_deploymentid_checkout_sessions_by_operation parameters: - name: deploymentId in: path required: true schema: type: string - name: operation in: path required: true schema: type: string enum: - create - get - cancel - complete - pay requestBody: required: true content: application/json: schema: oneOf: - type: object properties: offers: minItems: 1 maxItems: 5 type: array items: type: object properties: paymentRail: default: acp_stripe type: string enum: - acp_stripe - x402 items: minItems: 1 maxItems: 100 type: array items: type: object properties: productId: type: string minLength: 1 maxLength: 160 quantity: type: integer exclusiveMinimum: 0 maximum: 999 unitAmount: type: number exclusiveMinimum: 0 required: - productId - quantity buyer: type: object properties: name: type: string maxLength: 200 email: type: string maxLength: 320 format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ phone: type: string maxLength: 80 additionalProperties: {} shippingAddress: type: object properties: name: type: string maxLength: 200 line1: type: string maxLength: 300 line2: type: string maxLength: 300 city: type: string maxLength: 160 region: type: string maxLength: 160 postalCode: type: string maxLength: 80 country: type: string maxLength: 80 additionalProperties: {} billingAddress: type: object properties: name: type: string maxLength: 200 line1: type: string maxLength: 300 line2: type: string maxLength: 300 city: type: string maxLength: 160 region: type: string maxLength: 160 postalCode: type: string maxLength: 80 country: type: string maxLength: 80 additionalProperties: {} requestId: type: string minLength: 1 maxLength: 100 required: - items - requestId additionalProperties: false required: - offers additionalProperties: false - type: object properties: sessionIds: minItems: 1 maxItems: 20 type: array items: type: string minLength: 1 maxLength: 160 required: - sessionIds additionalProperties: false - type: object properties: approval: type: object properties: cartVersion: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 totalAmount: type: number exclusiveMinimum: 0 currency: type: string pattern: ^[A-Z]{3}$ required: - cartVersion - totalAmount - currency additionalProperties: false idempotencyKey: type: string minLength: 1 maxLength: 180 paymentProof: type: object propertyNames: type: string additionalProperties: {} sessionId: type: string minLength: 1 maxLength: 160 required: - approval - paymentProof - sessionId additionalProperties: false - type: object properties: sessionId: type: string minLength: 1 maxLength: 160 approval: type: object properties: cartVersion: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 totalAmount: type: number exclusiveMinimum: 0 currency: type: string pattern: ^[A-Z]{3}$ required: - cartVersion - totalAmount - currency additionalProperties: false required: - sessionId - approval additionalProperties: false responses: '200': description: >- Buyer-safe offers or completion result; costs, private metadata and payment proofs are excluded. '400': description: Invalid operation or request. '401': description: Invalid customer session or buyer-agent signature. '402': description: Definitive payment failure. '403': description: Invalid customer scope or merchant checkout disabled. '404': description: Offer not found or belongs to another buyer. '409': description: >- Approval mismatch, payment in progress, or payment reconciliation required. '429': description: Storefront or active offer limit. '503': description: Payment confirmation pending durable retry. security: - customerSession: [] components: securitySchemes: customerSession: type: http scheme: bearer bearerFormat: JWT description: >- Customer session from /api/embed/{deploymentId}/session. Origin and deployment scope must match. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.