{
  "openapi": "3.1.0",
  "info": {
    "title": "UCP Shopping Service",
    "description": "Canonical REST interface for UCP Shopping service. Schema references are logical pointers - actual payload shape is determined by negotiated capabilities.\n\n**Endpoint Resolution:** This spec defines operations only. The base URL MUST be obtained from the merchant's discovery profile at `/.well-known/ucp` under `services[\"dev.ucp.shopping\"][transport=rest].endpoint`. The `{endpoint}` server variable below is a placeholder for tooling compatibility."
  },
  "servers": [
    {
      "url": "{endpoint}",
      "description": "Merchant-provided endpoint from UCP discovery profile",
      "variables": {
        "endpoint": {
          "default": "https://merchant.example.com/ucp",
          "description": "Obtain from /.well-known/ucp → services[\"dev.ucp.shopping\"][transport=rest].endpoint"
        }
      }
    }
  ],
  "paths": {
    "/checkout-sessions": {
      "post": {
        "operationId": "create_checkout",
        "summary": "Create Checkout",
        "description": "Create a new checkout session.",
        "parameters": [
          {
            "$ref": "#/components/parameters/authorization"
          },
          {
            "$ref": "#/components/parameters/x_api_key"
          },
          {
            "$ref": "#/components/parameters/signature"
          },
          {
            "$ref": "#/components/parameters/signature_input"
          },
          {
            "$ref": "#/components/parameters/content_digest"
          },
          {
            "$ref": "#/components/parameters/idempotency_key"
          },
          {
            "$ref": "#/components/parameters/request_id"
          },
          {
            "$ref": "#/components/parameters/user_agent"
          },
          {
            "$ref": "#/components/parameters/ucp_agent"
          },
          {
            "$ref": "#/components/parameters/content_type"
          },
          {
            "$ref": "#/components/parameters/accept"
          },
          {
            "$ref": "#/components/parameters/accept_language"
          },
          {
            "$ref": "#/components/parameters/accept_encoding"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/checkout" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Checkout session created",
            "headers": {
              "Signature": {
                "$ref": "#/components/headers/signature"
              },
              "Signature-Input": {
                "$ref": "#/components/headers/signature_input"
              },
              "Content-Digest": {
                "$ref": "#/components/headers/content_digest"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/checkout_response"
                }
              }
            }
          }
        }
      }
    },
    "/checkout-sessions/{id}": {
      "parameters": [
        { "$ref": "#/components/parameters/checkout_session_id_path" }
      ],
      "get": {
        "operationId": "get_checkout",
        "summary": "Get Checkout",
        "description": "Get the latest state of a checkout session.",
        "parameters": [
          {
            "$ref": "#/components/parameters/authorization"
          },
          {
            "$ref": "#/components/parameters/x_api_key"
          },
          {
            "$ref": "#/components/parameters/signature"
          },
          {
            "$ref": "#/components/parameters/signature_input"
          },
          {
            "$ref": "#/components/parameters/request_id"
          },
          {
            "$ref": "#/components/parameters/user_agent"
          },
          {
            "$ref": "#/components/parameters/ucp_agent"
          },
          {
            "$ref": "#/components/parameters/content_type"
          },
          {
            "$ref": "#/components/parameters/accept"
          },
          {
            "$ref": "#/components/parameters/accept_language"
          },
          {
            "$ref": "#/components/parameters/accept_encoding"
          }
        ],
        "responses": {
          "200": {
            "description": "Checkout session retrieved",
            "headers": {
              "Signature": {
                "$ref": "#/components/headers/signature"
              },
              "Signature-Input": {
                "$ref": "#/components/headers/signature_input"
              },
              "Content-Digest": {
                "$ref": "#/components/headers/content_digest"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/checkout_response"
                }
              }
            }
          }
        }
      },
      "put": {
        "operationId": "update_checkout",
        "summary": "Update Checkout",
        "description": "Update Checkout is a full replacement operation. A new Update Checkout operation is not permitted while Checkout status is `complete_in_progress`. Duplicate requests remain subject to Replay Protection. If the Business receives a new Update Checkout request in that state, it leaves the Checkout unchanged and returns the current Checkout with a recoverable error Message.",
        "parameters": [
          {
            "$ref": "#/components/parameters/authorization"
          },
          {
            "$ref": "#/components/parameters/x_api_key"
          },
          {
            "$ref": "#/components/parameters/signature"
          },
          {
            "$ref": "#/components/parameters/signature_input"
          },
          {
            "$ref": "#/components/parameters/content_digest"
          },
          {
            "$ref": "#/components/parameters/idempotency_key"
          },
          {
            "$ref": "#/components/parameters/request_id"
          },
          {
            "$ref": "#/components/parameters/user_agent"
          },
          {
            "$ref": "#/components/parameters/ucp_agent"
          },
          {
            "$ref": "#/components/parameters/content_type"
          },
          {
            "$ref": "#/components/parameters/accept"
          },
          {
            "$ref": "#/components/parameters/accept_language"
          },
          {
            "$ref": "#/components/parameters/accept_encoding"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/checkout" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Current Checkout state after the Update request, whether the update was applied or rejected.",
            "headers": {
              "Signature": {
                "$ref": "#/components/headers/signature"
              },
              "Signature-Input": {
                "$ref": "#/components/headers/signature_input"
              },
              "Content-Digest": {
                "$ref": "#/components/headers/content_digest"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/checkout_response"
                }
              }
            }
          }
        }
      }
    },
    "/checkout-sessions/{id}/complete": {
      "parameters": [
        { "$ref": "#/components/parameters/checkout_session_id_path" }
      ],
      "post": {
        "operationId": "complete_checkout",
        "summary": "Complete Checkout",
        "description": "Place the order",
        "parameters": [
          {
            "$ref": "#/components/parameters/authorization"
          },
          {
            "$ref": "#/components/parameters/x_api_key"
          },
          {
            "$ref": "#/components/parameters/signature"
          },
          {
            "$ref": "#/components/parameters/signature_input"
          },
          {
            "$ref": "#/components/parameters/content_digest"
          },
          {
            "$ref": "#/components/parameters/idempotency_key"
          },
          {
            "$ref": "#/components/parameters/request_id"
          },
          {
            "$ref": "#/components/parameters/user_agent"
          },
          {
            "$ref": "#/components/parameters/ucp_agent"
          },
          {
            "$ref": "#/components/parameters/content_type"
          },
          {
            "$ref": "#/components/parameters/accept"
          },
          {
            "$ref": "#/components/parameters/accept_language"
          },
          {
            "$ref": "#/components/parameters/accept_encoding"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/checkout" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Checkout session completed",
            "headers": {
              "Signature": {
                "$ref": "#/components/headers/signature"
              },
              "Signature-Input": {
                "$ref": "#/components/headers/signature_input"
              },
              "Content-Digest": {
                "$ref": "#/components/headers/content_digest"
              }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/checkout_response" }
              }
            }
          }
        }
      }
    },
    "/checkout-sessions/{id}/cancel": {
      "parameters": [
        { "$ref": "#/components/parameters/checkout_session_id_path" }
      ],
      "post": {
        "operationId": "cancel_checkout",
        "summary": "Cancel Checkout",
        "description": "Cancel a checkout session",
        "parameters": [
          {
            "$ref": "#/components/parameters/authorization"
          },
          {
            "$ref": "#/components/parameters/x_api_key"
          },
          {
            "$ref": "#/components/parameters/signature"
          },
          {
            "$ref": "#/components/parameters/signature_input"
          },
          {
            "$ref": "#/components/parameters/content_digest"
          },
          {
            "$ref": "#/components/parameters/idempotency_key"
          },
          {
            "$ref": "#/components/parameters/request_id"
          },
          {
            "$ref": "#/components/parameters/user_agent"
          },
          {
            "$ref": "#/components/parameters/ucp_agent"
          },
          {
            "$ref": "#/components/parameters/content_type"
          },
          {
            "$ref": "#/components/parameters/accept"
          },
          {
            "$ref": "#/components/parameters/accept_language"
          },
          {
            "$ref": "#/components/parameters/accept_encoding"
          }
        ],
        "responses": {
          "200": {
            "description": "Checkout session canceled",
            "headers": {
              "Signature": {
                "$ref": "#/components/headers/signature"
              },
              "Signature-Input": {
                "$ref": "#/components/headers/signature_input"
              },
              "Content-Digest": {
                "$ref": "#/components/headers/content_digest"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/checkout_response"
                }
              }
            }
          }
        }
      }
    },
    "/carts": {
      "post": {
        "operationId": "create_cart",
        "summary": "Create Cart",
        "description": "Create a new cart session.",
        "parameters": [
          { "$ref": "#/components/parameters/authorization" },
          { "$ref": "#/components/parameters/x_api_key" },
          { "$ref": "#/components/parameters/signature" },
          { "$ref": "#/components/parameters/signature_input" },
          { "$ref": "#/components/parameters/content_digest" },
          { "$ref": "#/components/parameters/idempotency_key" },
          { "$ref": "#/components/parameters/request_id" },
          { "$ref": "#/components/parameters/user_agent" },
          { "$ref": "#/components/parameters/ucp_agent" },
          { "$ref": "#/components/parameters/content_type" },
          { "$ref": "#/components/parameters/accept" },
          { "$ref": "#/components/parameters/accept_language" },
          { "$ref": "#/components/parameters/accept_encoding" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/cart" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Cart created",
            "headers": {
              "Signature": { "$ref": "#/components/headers/signature" },
              "Signature-Input": { "$ref": "#/components/headers/signature_input" },
              "Content-Digest": { "$ref": "#/components/headers/content_digest" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/cart_response" }
              }
            }
          }
        }
      }
    },
    "/carts/{id}": {
      "parameters": [
        { "$ref": "#/components/parameters/cart_id_path" }
      ],
      "get": {
        "operationId": "get_cart",
        "summary": "Get Cart",
        "description": "Get the latest state of a cart session.",
        "parameters": [
          { "$ref": "#/components/parameters/authorization" },
          { "$ref": "#/components/parameters/x_api_key" },
          { "$ref": "#/components/parameters/signature" },
          { "$ref": "#/components/parameters/signature_input" },
          { "$ref": "#/components/parameters/request_id" },
          { "$ref": "#/components/parameters/user_agent" },
          { "$ref": "#/components/parameters/ucp_agent" },
          { "$ref": "#/components/parameters/content_type" },
          { "$ref": "#/components/parameters/accept" },
          { "$ref": "#/components/parameters/accept_language" },
          { "$ref": "#/components/parameters/accept_encoding" }
        ],
        "responses": {
          "200": {
            "description": "Cart retrieved",
            "headers": {
              "Signature": { "$ref": "#/components/headers/signature" },
              "Signature-Input": { "$ref": "#/components/headers/signature_input" },
              "Content-Digest": { "$ref": "#/components/headers/content_digest" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/cart_response" }
              }
            }
          }
        }
      },
      "put": {
        "operationId": "update_cart",
        "summary": "Update Cart",
        "description": "Update a cart session.",
        "parameters": [
          { "$ref": "#/components/parameters/authorization" },
          { "$ref": "#/components/parameters/x_api_key" },
          { "$ref": "#/components/parameters/signature" },
          { "$ref": "#/components/parameters/signature_input" },
          { "$ref": "#/components/parameters/content_digest" },
          { "$ref": "#/components/parameters/idempotency_key" },
          { "$ref": "#/components/parameters/request_id" },
          { "$ref": "#/components/parameters/user_agent" },
          { "$ref": "#/components/parameters/ucp_agent" },
          { "$ref": "#/components/parameters/content_type" },
          { "$ref": "#/components/parameters/accept" },
          { "$ref": "#/components/parameters/accept_language" },
          { "$ref": "#/components/parameters/accept_encoding" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/cart" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Cart updated",
            "headers": {
              "Signature": { "$ref": "#/components/headers/signature" },
              "Signature-Input": { "$ref": "#/components/headers/signature_input" },
              "Content-Digest": { "$ref": "#/components/headers/content_digest" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/cart_response" }
              }
            }
          }
        }
      }
    },
    "/carts/{id}/cancel": {
      "parameters": [
        { "$ref": "#/components/parameters/cart_id_path" }
      ],
      "post": {
        "operationId": "cancel_cart",
        "summary": "Cancel Cart",
        "description": "Cancel a cart session. Returns the cart state at time of cancellation.",
        "parameters": [
          { "$ref": "#/components/parameters/authorization" },
          { "$ref": "#/components/parameters/x_api_key" },
          { "$ref": "#/components/parameters/signature" },
          { "$ref": "#/components/parameters/signature_input" },
          { "$ref": "#/components/parameters/content_digest" },
          { "$ref": "#/components/parameters/idempotency_key" },
          { "$ref": "#/components/parameters/request_id" },
          { "$ref": "#/components/parameters/user_agent" },
          { "$ref": "#/components/parameters/ucp_agent" },
          { "$ref": "#/components/parameters/content_type" },
          { "$ref": "#/components/parameters/accept" },
          { "$ref": "#/components/parameters/accept_language" },
          { "$ref": "#/components/parameters/accept_encoding" }
        ],
        "responses": {
          "200": {
            "description": "Cart cancelled",
            "headers": {
              "Signature": { "$ref": "#/components/headers/signature" },
              "Signature-Input": { "$ref": "#/components/headers/signature_input" },
              "Content-Digest": { "$ref": "#/components/headers/content_digest" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/cart_response" }
              }
            }
          }
        }
      }
    },
    "/catalog/search": {
      "post": {
        "operationId": "search_catalog",
        "summary": "Search Catalog",
        "description": "Search for products in the business's catalog.",
        "parameters": [
          { "$ref": "#/components/parameters/authorization" },
          { "$ref": "#/components/parameters/x_api_key" },
          { "$ref": "#/components/parameters/signature" },
          { "$ref": "#/components/parameters/signature_input" },
          { "$ref": "#/components/parameters/content_digest" },
          { "$ref": "#/components/parameters/request_id" },
          { "$ref": "#/components/parameters/user_agent" },
          { "$ref": "#/components/parameters/ucp_agent" },
          { "$ref": "#/components/parameters/content_type" },
          { "$ref": "#/components/parameters/accept" },
          { "$ref": "#/components/parameters/accept_language" },
          { "$ref": "#/components/parameters/accept_encoding" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/catalog_search_request" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Search results",
            "headers": {
              "Signature": { "$ref": "#/components/headers/signature" },
              "Signature-Input": { "$ref": "#/components/headers/signature_input" },
              "Content-Digest": { "$ref": "#/components/headers/content_digest" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/catalog_search_response" }
              }
            }
          }
        }
      }
    },
    "/catalog/lookup": {
      "post": {
        "operationId": "lookup_catalog",
        "summary": "Batch Lookup Catalog Items",
        "description": "Lookup one or more products by ID with explicit market context. Supports batch lookups of multiple items in a single request.",
        "parameters": [
          { "$ref": "#/components/parameters/authorization" },
          { "$ref": "#/components/parameters/x_api_key" },
          { "$ref": "#/components/parameters/signature" },
          { "$ref": "#/components/parameters/signature_input" },
          { "$ref": "#/components/parameters/content_digest" },
          { "$ref": "#/components/parameters/request_id" },
          { "$ref": "#/components/parameters/user_agent" },
          { "$ref": "#/components/parameters/ucp_agent" },
          { "$ref": "#/components/parameters/content_type" },
          { "$ref": "#/components/parameters/accept" },
          { "$ref": "#/components/parameters/accept_language" },
          { "$ref": "#/components/parameters/accept_encoding" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/catalog_lookup_request" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Lookup result",
            "headers": {
              "Signature": { "$ref": "#/components/headers/signature" },
              "Signature-Input": { "$ref": "#/components/headers/signature_input" },
              "Content-Digest": { "$ref": "#/components/headers/content_digest" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/catalog_lookup_response" }
              }
            }
          }
        }
      }
    },
    "/orders/{id}": {
      "parameters": [
        { "$ref": "#/components/parameters/order_id_path" }
      ],
      "get": {
        "operationId": "get_order",
        "summary": "Get Order",
        "description": "Get the current state of an order. Returns the full order entity as a current-state snapshot. The business verifies the requesting platform created the checkout that produced this order.",
        "parameters": [
          { "$ref": "#/components/parameters/authorization" },
          { "$ref": "#/components/parameters/x_api_key" },
          { "$ref": "#/components/parameters/signature" },
          { "$ref": "#/components/parameters/signature_input" },
          { "$ref": "#/components/parameters/request_id" },
          { "$ref": "#/components/parameters/user_agent" },
          { "$ref": "#/components/parameters/ucp_agent" },
          { "$ref": "#/components/parameters/content_type" },
          { "$ref": "#/components/parameters/accept" },
          { "$ref": "#/components/parameters/accept_language" },
          { "$ref": "#/components/parameters/accept_encoding" }
        ],
        "responses": {
          "200": {
            "description": "Order retrieved or business outcome message",
            "headers": {
              "Signature": { "$ref": "#/components/headers/signature" },
              "Signature-Input": { "$ref": "#/components/headers/signature_input" },
              "Content-Digest": { "$ref": "#/components/headers/content_digest" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/order_response" }
              }
            }
          }
        }
      }
    },
    "/catalog/product": {
      "post": {
        "operationId": "get_product",
        "summary": "Get Product Details",
        "description": "Retrieve complete product detail by identifier. Returns a singular product with a relevant set of variants, exact pricing, and real-time availability. Supports interactive option selection via `selected` and `preferences` parameters for variant narrowing and availability signals.",
        "parameters": [
          { "$ref": "#/components/parameters/authorization" },
          { "$ref": "#/components/parameters/x_api_key" },
          { "$ref": "#/components/parameters/signature" },
          { "$ref": "#/components/parameters/signature_input" },
          { "$ref": "#/components/parameters/content_digest" },
          { "$ref": "#/components/parameters/request_id" },
          { "$ref": "#/components/parameters/user_agent" },
          { "$ref": "#/components/parameters/ucp_agent" },
          { "$ref": "#/components/parameters/content_type" },
          { "$ref": "#/components/parameters/accept" },
          { "$ref": "#/components/parameters/accept_language" },
          { "$ref": "#/components/parameters/accept_encoding" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/catalog_get_product_request" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Product detail",
            "headers": {
              "Signature": { "$ref": "#/components/headers/signature" },
              "Signature-Input": { "$ref": "#/components/headers/signature_input" },
              "Content-Digest": { "$ref": "#/components/headers/content_digest" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/catalog_get_product_response" }
              }
            }
          }
        }
      }
    }
  },
  "webhooks": {
    "orderEvent": {
      "post": {
        "operationId": "order_event_webhook",
        "summary": "Order Event Webhook",
        "description": "Merchant sends order lifecycle events to the platform's registered webhook URL. The platform provides the webhook URL during partner onboarding.",
        "parameters": [
          { "$ref": "#/components/parameters/signature" },
          { "$ref": "#/components/parameters/signature_input" },
          { "$ref": "#/components/parameters/content_digest" },
          { "$ref": "#/components/parameters/ucp_agent" },
          { "$ref": "#/components/parameters/x_api_key" },
          { "$ref": "#/components/parameters/webhook_timestamp" },
          { "$ref": "#/components/parameters/webhook_id" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/order" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Event received and acknowledged",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["ucp"],
                  "properties": {
                    "ucp": {
                      "$ref": "#/components/schemas/ucp"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "checkout_session_id_path": {
        "name": "id",
        "in": "path",
        "required": true,
        "description": "The unique identifier of the checkout session.",
        "schema": {
          "type": "string"
        }
      },
      "cart_id_path": {
        "name": "id",
        "in": "path",
        "required": true,
        "description": "The unique identifier of the cart.",
        "schema": {
          "type": "string"
        }
      },
      "order_id_path": {
        "name": "id",
        "in": "path",
        "required": true,
        "description": "The unique identifier of the order.",
        "schema": {
          "type": "string"
        }
      },
      "authorization": {
        "name": "Authorization",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "Should contain oauth token representing the following 2 schemes: 1. Platform self authenticating (client_credentials). 2. Platform authenticating on behalf of end user (authorization_code)."
      },
      "x_api_key": {
        "name": "X-API-Key",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "Authenticates the platform with a reusable api key allocated to the platform by the business."
      },
      "signature": {
        "name": "Signature",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "RFC 9421 HTTP Message Signature. Required when using HTTP Message Signatures for authentication. Format: `sig1=:<base64-signature>:`."
      },
      "signature_input": {
        "name": "Signature-Input",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "RFC 9421 Signature-Input header. Required when using HTTP Message Signatures for authentication. Format: `sig1=(\"@method\" \"@path\" ...);created=<timestamp>;keyid=\"<key-id>\"`."
      },
      "content_digest": {
        "name": "Content-Digest",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "Body digest per RFC 9530. Required for requests/responses with a body. Format: `sha-256=:<base64-digest>:`."
      },
      "idempotency_key": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        },
        "description": "Ensures duplicate operations don't happen during retries."
      },
      "request_id": {
        "name": "Request-Id",
        "in": "header",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        },
        "description": "For tracing the requests across network layers and components."
      },
      "user_agent": {
        "name": "User-Agent",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "Identifies the user agent string making the call."
      },
      "ucp_agent": {
        "name": "UCP-Agent",
        "in": "header",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Identifies the UCP agent making the call. All requests MUST include the UCP-Agent header containing the signer's profile URI using RFC 8941 Dictionary syntax. The URL MUST point to /.well-known/ucp. Format: profile=\"https://example.com/.well-known/ucp\"."
      },
      "content_type": {
        "name": "Content-Type",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "Representation Metadata. Tells the receiver what the data in the message body actually is."
      },
      "accept": {
        "name": "Accept",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "Content Negotiation. The client tells the server what data formats it is capable of understanding."
      },
      "accept_language": {
        "name": "Accept-Language",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "Localization. Tells the receiver the user's preferred natural languages, often with \"weights\" or priorities."
      },
      "accept_encoding": {
        "name": "Accept-Encoding",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "Compression. The client tells the server which content-codings it supports, usually for compression."
      },
      "webhook_timestamp": {
        "name": "Webhook-Timestamp",
        "in": "header",
        "required": true,
        "schema": {
          "type": "integer"
        },
        "description": "Webhook event occurrence unix timestamp (seconds since epoch)."
      },
      "webhook_id": {
        "name": "Webhook-Id",
        "in": "header",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        },
        "description": "The unique identifier of a webhook event."
      }
    },
    "headers": {
      "signature": {
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "RFC 9421 HTTP Message Signature for response. Contains the signature value in the format `sig1=:<base64-signature>:`."
      },
      "signature_input": {
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "RFC 9421 Signature-Input header for response. Describes signed components, timestamp, and key ID."
      },
      "content_digest": {
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "JCS-canonicalized body digest per RFC 8785. Format: `sha-256=:<base64-digest>:`."
      }
    },
    "schemas": {
      "checkout": {
        "$ref": "../../schemas/shopping/checkout.json"
      },
      "checkout_response": {
        "oneOf": [
          { "$ref": "../../schemas/shopping/checkout.json" },
          { "$ref": "../../schemas/common/types/error_response.json" }
        ]
      },
      "cart": {
        "$ref": "../../schemas/shopping/cart.json"
      },
      "cart_response": {
        "oneOf": [
          { "$ref": "../../schemas/shopping/cart.json" },
          { "$ref": "../../schemas/common/types/error_response.json" }
        ]
      },
      "order": {
        "$ref": "../../schemas/shopping/order.json"
      },
      "order_response": {
        "oneOf": [
          { "$ref": "../../schemas/shopping/order.json" },
          { "$ref": "../../schemas/common/types/error_response.json" }
        ]
      },
      "payment": {
        "$ref": "../../schemas/common/types/payment.json"
      },
      "ucp": {
        "$ref": "../../schemas/ucp.json"
      },
      "catalog_search_request": {
        "$ref": "../../schemas/shopping/catalog_search.json#/$defs/search_request"
      },
      "catalog_search_response": {
        "$ref": "../../schemas/shopping/catalog_search.json#/$defs/search_response"
      },
      "catalog_lookup_request": {
        "$ref": "../../schemas/shopping/catalog_lookup.json#/$defs/lookup_request"
      },
      "catalog_lookup_response": {
        "$ref": "../../schemas/shopping/catalog_lookup.json#/$defs/lookup_response"
      },
      "catalog_get_product_request": {
        "$ref": "../../schemas/shopping/catalog_lookup.json#/$defs/get_product_request"
      },
      "catalog_get_product_response": {
        "oneOf": [
          { "$ref": "../../schemas/shopping/catalog_lookup.json#/$defs/get_product_response" },
          { "$ref": "../../schemas/common/types/error_response.json" }
        ]
      }
    }
  }
}