In an era of AI agents and automated commerce, there is a need for a standardized way for external systems to interact with merchant e-commerce platforms. This concept outlines an Open Commerce API that allows third-party services or autonomous agents to discover a merchant’s offerings, create orders, and execute payments in a consistent, secure manner. Key components include a discoverable manifest, standardized data schemas for products and orders, mechanisms to obtain full order details (including tax and shipping), robust payment handling (integrating cards, tokens, and crypto wallets), and flexible authentication. The goal is to enable seamless, interoperable transactions – any way a consumer and merchant want to transact – while leveraging emerging standards like schema.org for data and HTTP 402-based payment protocols for automation.
To facilitate easy discovery of a merchant’s capabilities, the API uses a well-known URI approach. Merchants host a manifest discovery file at a standardized path (e.g. https://merchant.com/.well-known/commerce-manifest). The .well-known URI prefix is a convention defined by IETF (RFC 8615) to expose site metadata or services at consistent locations across all servers. By using a well-known URL, any client or agent knows exactly where to look for the merchant’s API manifest without needing the merchant to embed custom HTML tags or headers.
The well-known URI can either directly serve the manifest (as a JSON file) or provide a redirect/pointer to the actual manifest’s location (whichever best fits the merchant’s infrastructure). For example, a request to /.well-known/commerce-manifest might return a short JSON with the real manifest URL, or simply return the manifest content. This indirection gives merchants flexibility to host the detailed manifest wherever it makes sense (e.g. on a CDN or subdomain) while still having a fixed discovery path.
Why .well-known? Using .well-known ensures that the manifest is available at a consistent, predictable path on any host. This eliminates the need for custom HTTP headers or HTML advertisements of the API; clients won’t have to scrape pages or look for <meta> tags. Instead, an AI agent or service (like an aggregator or Cloudflare worker) can directly query the well-known URL to retrieve or locate the manifest. This standardized discovery is analogous to how OpenID Connect uses /.well-known/openid-configuration for identity metadata, or how other protocols expose capabilities in a uniform way. By adopting .well-known for commerce, we enable a zero-configuration discovery – any merchant implementing this simply places their manifest file in the known location and any client can find it.
The manifest is a JSON (or JSON-LD) document that describes the merchant’s commerce API endpoints and data formats. It effectively acts as a capability statement. Key elements of the manifest include:
Merchant Info: Basic information like the store name, description, and perhaps a reference to the merchant’s organization identity. This might align with Schema.org’s business schema, but primary use is identification and versioning of the API.
Product Listing Endpoint: The URL or path where an agent can retrieve product data (e.g. /api/products). The manifest specifies how to query this (e.g. a GET request, with optional filters or pagination parameters). Crucially, it also notes the data schema used for product information, which in this standard is based on Schema.org Product. Product data is returned in a structured format (likely JSON-LD) that follows schema.org conventions for products. Using Schema.org vocabulary ensures interoperability and understanding across different systems. For example, each product item can be represented as a Product type with properties like name, description, image, and offers/pricing. The Schema.org definition of Product is broad: “any offered product or service” (it can be a physical good, a rental, etc.). This means even services or digital goods can be described in a similar way to physical products, using the same data model.
Pricing and Offers: Alongside basic product info, pricing is typically provided via Schema.org Offer objects. An Offer represents an offer to transfer some right to an item – e.g. “an offer to sell a product for a certain price”. In practice, the product listing may embed an offers property pointing to an Offer that includes the price (price and priceCurrency), availability (InStock, SoldOut, etc.), and other details like eligible quantity or valid dates. By linking to the Schema.org Offer schema, the manifest makes it clear how pricing data is structured (including currency codes, any discounts, etc.). For example, a product JSON-LD snippet might look like:
{
"@context": "<https://schema.org>",
"@type": "Product",
"name": "Wireless Earbuds Model X",
"description": "Noise-cancelling wireless earbuds with charging case.",
"image": "<https://merchant.com/images/earbuds.jpg>",
"offers": {
"@type": "Offer",
"price": "99.99",
"priceCurrency": "USD",
"availability": "<https://schema.org/InStock>"
}
}
This format aligns with Schema.org so any consumer (AI or service) can parse it using standard vocabulary. We include direct links in documentation to the official schema references for clarity – e.g. Product and Offer. In the manifest, the schema usage might be indicated by a context or an example.
Order Creation Endpoint: The manifest defines how an agent can initiate an order. This is typically a POST endpoint (e.g. /api/orders or /api/cart/checkout). The manifest should describe the required inputs for creating an order: likely a list of product IDs (and quantities) the customer wants to purchase, plus customer details like shipping address, chosen shipping method, and contact info. The data format for order creation requests and responses can also leverage Schema.org types. For instance, the response to creating an order could be structured as a Schema.org Order object or contain one. An Order in Schema.org is essentially a confirmation of a transaction (a receipt), which can encompass multiple line items (each line referencing an Offer that was accepted). We can use this concept to structure the order result.
When the agent posts the order request, the system will calculate any additional costs (tax, shipping, etc.) and return an Order summary. This is where full order amount details are provided: the item subtotal, applicable taxes, shipping fees, discounts, and the final total payable. Ensuring the agent can get the complete price breakdown is critical – the previous step (product listing) only gave item prices, but now we include location-based tax, chosen shipping cost, etc. The manifest’s documentation of the order endpoint will clarify that the response includes these components. For example, the response might include fields (or JSON-LD properties) like price (subtotal), tax (total tax amount), shippingCost, and a totalPaymentDue. In Schema.org terms, an Order or Invoice can use PriceSpecification to detail such components (e.g. indicating whether tax is included or not), or use specific properties like totalPaymentDue (often as an embedded PriceSpecification). The key outcome is that the agent knows exactly how much to pay and for what.
Example: After creating an order, the response might be:
{
"@context": "<https://schema.org>",
"@type": "Order",
"orderNumber": "ABC-12345",
"acceptedOffer": [
{
"@type": "Offer",
"itemOffered": { "@type": "Product", "name": "Wireless Earbuds Model X" },
"quantity": 1,
"price": "99.99",
"priceCurrency": "USD"
}
],
"discount": "0",
"discountCurrency": "USD",
"broker": "OpenCommerceAgent 1.0",
"orderDelivery": {
"@type": "ParcelDelivery",
"provider": "UPS",
"price": "5.00",
"priceCurrency": "USD"
},
"tax": {
"@type": "PriceSpecification",
"price": "8.00",
"priceCurrency": "USD",
"valueAddedTaxIncluded": true},
"totalPaymentDue": {
"@type": "PriceSpecification",
"price": "113. -99,
"priceCurrency": "USD"
},
"paymentStatus": "<https://schema.org/PaymentDue>"
}
This is a conceptual example to illustrate that the order summary includes line items (via acceptedOffer or orderedItem), and separate entries for shipping (orderDelivery cost), tax, and the total due. By returning this information upon order creation, the agent (or user) can review the full cost breakdown before proceeding to payment. In summary, the manifest’s order endpoint definition ensures that the client can retrieve the full order amount including taxes and shipping, addressing the need for transparency in automated checkout.
Other Endpoints: The manifest might list other related endpoints, such as one for retrieving a single product’s details, updating an order (e.g. adding/removing items prior to finalizing), or listing acceptable shipping methods or payment methods. For simplicity, these can be considered optional or part of the main endpoints. The manifest should also contain a list of supported payment methods and authentication methods (discussed in upcoming sections). Notably, Schema.org’s Offer type has an acceptedPaymentMethod property to enumerate what payment types are accepted. While the manifest can directly list payment options in its own schema, aligning with this concept means a merchant could indicate (for example) that it accepts "CreditCard", "USDCStablecoin", "PayPal", etc. This information might be represented as an array of method identifiers or URLs to more details (like PaymentMethod schema or a custom enum) in the manifest.
All schema references in the manifest are hyperlinked to their official definitions for clarity. By using established schemas (Product, Offer, Order, etc.), the API’s data model is self-descriptive and compatible with other tools. It also ensures semantic clarity – any agent can interpret, for example, what an availability: InStock means or that priceCurrency follows ISO 4217 currency codes. The manifest basically ties these together by saying where and how to get the data, and what format it will be in.
A core flow enabled by this API is creating an order (cart) and retrieving the full order details prior to payment. As noted, the agent will call the order creation endpoint with necessary inputs. Let’s break down how this works in practice and how we incorporate the requirement for full pricing details:
Initiating the Order: The agent (or integrator) selects items to purchase, typically using product identifiers obtained from the product listing. It then makes a request (e.g. POST /api/orders) with a payload containing those item IDs and quantities. Additionally, the agent provides a shipping address or selects a shipping option if multiple are available (in some cases, an agent might call a separate endpoint like GET /api/shipping-options?dest=ZIP to get shipping choices and include the chosen one in the order create call). The manifest details what fields are expected – for example: { "items": [ { "sku": "...", "quantity": 2 }, ... ], "shippingAddress": { ... }, "shippingOption": "standard" }.
Order Calculation: Upon receiving this, the merchant’s backend calculates the order. This involves summing item prices, applying any discounts or promo codes (if supported and provided), calculating tax based on the address and items (tax rules), and adding shipping cost based on the chosen method. The result is an Order record that is either created in a pending state or simply simulated if the API allows “estimates.” In our design, we assume the order is created and an order ID is generated (like a cart ID or order reference that will be used for payment).
Response – Full Cost Breakdown: The response to the order creation call returns a JSON structure with all the computed details. This is where taxes and shipping show up. As highlighted earlier, the order response will include each line item’s details and cost, plus aggregate fields:
paymentStatus could be set to PaymentDue or similar to indicate payment is outstanding.This design ensures nothing is hidden. The agent doesn’t need to separately guess taxes or shipping – it’s clearly provided, enabling informed decision-making or user confirmation if a human is in the loop. It addresses the explicit requirement: “There needs to be a way to get the full order amount (Tax, Shipping, etc)”. Yes – it’s returned right after creating the order, before payment.