openapi: 3.1.0 info: title: VaultGraph Portal API version: 0.1.1 description: Server-to-server endpoints exposed by the VaultGraph portal (beta). servers: - url: https://app.vaultgraph.com description: Production components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key schemas: CheckoutPayment: type: object properties: handlers: type: array items: type: object properties: config: type: object additionalProperties: {} config_schema: type: string id: type: string instrument_schemas: type: array items: type: string name: type: string spec: type: string version: type: string required: - config - config_schema - id - instrument_schemas - name - spec - version additionalProperties: false instruments: type: array items: type: object properties: billing_address: type: object properties: address_country: type: string address_locality: type: string address_region: type: string extended_address: type: string first_name: type: string full_name: type: string last_name: type: string phone_number: type: string postal_code: type: string street_address: type: string additionalProperties: false credential: type: object properties: type: type: string card_number_type: type: string enum: - dpan - fpan - network_token cryptogram: type: string cvc: type: string eci_value: type: string expiry_month: type: number expiry_year: type: number name: type: string number: type: string required: - type additionalProperties: false handler_id: type: string id: type: string type: type: string enum: - card brand: type: string expiry_month: type: number expiry_year: type: number last_digits: type: string rich_card_art: type: string rich_text_description: type: string required: - handler_id - id - type - brand - last_digits additionalProperties: false selected_instrument_id: type: string required: - handlers additionalProperties: false CheckoutLink: type: object properties: title: type: string type: type: string url: type: string required: - type - url additionalProperties: false UcpEnvelope: type: object properties: capabilities: type: array items: type: object properties: config: type: object additionalProperties: {} extends: type: string name: type: string schema: type: string spec: type: string version: type: string required: - name - version additionalProperties: false version: type: string required: - capabilities - version additionalProperties: false CheckoutCreatePayment: type: object properties: instruments: type: array items: type: object properties: billing_address: type: object properties: address_country: type: string address_locality: type: string address_region: type: string extended_address: type: string first_name: type: string full_name: type: string last_name: type: string phone_number: type: string postal_code: type: string street_address: type: string additionalProperties: false credential: type: object properties: type: type: string card_number_type: type: string enum: - dpan - fpan - network_token cryptogram: type: string cvc: type: string eci_value: type: string expiry_month: type: number expiry_year: type: number name: type: string number: type: string required: - type additionalProperties: false handler_id: type: string id: type: string type: type: string enum: - card brand: type: string expiry_month: type: number expiry_year: type: number last_digits: type: string rich_card_art: type: string rich_text_description: type: string required: - handler_id - id - type - brand - last_digits additionalProperties: false selected_instrument_id: type: string additionalProperties: false OrderLineItem: type: object properties: id: type: string item: type: object properties: id: type: string image_url: type: string price: type: number title: type: string required: - id - price - title additionalProperties: false parent_id: type: string quantity: type: object properties: fulfilled: type: number total: type: number required: - fulfilled - total additionalProperties: false status: type: string enum: - fulfilled - partial - processing totals: type: array items: type: object properties: amount: type: number display_text: type: string type: type: string enum: - discount - fee - fulfillment - items_discount - subtotal - tax - total required: - amount - type additionalProperties: false properties: type: array items: type: object properties: name: type: string minLength: 1 value: type: string required: - name - value additionalProperties: false required: - id - item - quantity - status - totals additionalProperties: false OrderFulfillment: type: object properties: expectations: type: array items: type: object properties: id: type: string method: type: object properties: id: type: string name: type: string method_type: type: string enum: - shipping - pickup - digital required: - id - name - method_type additionalProperties: false line_items: type: array items: type: object properties: id: type: string quantity: type: integer minimum: 0 required: - id - quantity additionalProperties: false destination: type: object properties: full_name: type: string first_name: type: string last_name: type: string phone_number: type: string street_address: type: string extended_address: type: string address_locality: type: string address_region: type: string postal_code: type: string address_country: type: string instructions: type: string additionalProperties: false fulfillable_on: type: string required: - id - method - line_items - destination additionalProperties: false events: type: array items: type: object properties: id: type: string type: type: string occurred_at: type: string line_items: type: array items: type: object properties: id: type: string quantity: type: integer minimum: 0 required: - id - quantity additionalProperties: false description: type: string carrier: type: string tracking_number: type: string tracking_url: type: string required: - id - type - occurred_at - line_items additionalProperties: false additionalProperties: false OrderMessage: type: object properties: id: type: string body: type: string created_at: type: string required: - id - body - created_at additionalProperties: false ErrorResponse: type: object required: - error properties: error: type: string detail: type: string Shop: type: object description: Representation of a shop in the VaultGraph portal. properties: id: type: string description: Public short identifier for the shop. name: type: string description: Human-readable name of the shop. description: type: - string - "null" description: Optional description of the shop. created_at: type: string format: date-time description: Timestamp when the shop was created. updated_at: type: string format: date-time description: Timestamp when the shop was last updated. additionalProperties: true ShopCreateRequest: type: object description: Request payload for creating a new shop. properties: name: type: string description: Human-readable name of the shop. description: type: - string - "null" description: Optional description of the shop. required: - name additionalProperties: true ShopUpdateRequest: type: object description: Request payload for updating an existing shop. properties: name: type: string description: Updated human-readable name of the shop. description: type: - string - "null" description: Updated description of the shop. required: - name additionalProperties: true Price: type: object required: - amount - currency properties: amount: type: integer description: Integer minor units (e.g. cents for USD). currency: type: string pattern: ^[A-Z]{3}$ description: ISO 4217 currency code. PriceRange: type: object required: - min - max properties: min: $ref: "#/components/schemas/Price" max: $ref: "#/components/schemas/Price" Media: type: object required: - type - url properties: type: type: string description: Media kind, e.g. "image". url: type: string alt_text: type: - string - "null" width: type: integer height: type: integer Variant: type: object required: - id - product_id - title - price - availability properties: id: type: string product_id: type: string title: type: string sku: type: - string - "null" price: $ref: "#/components/schemas/Price" list_price: $ref: "#/components/schemas/Price" availability: type: object required: - available properties: available: type: boolean media: type: array description: Variant-specific gallery media. Optional. items: $ref: "#/components/schemas/Media" image_url: type: string description: Primary display image URL for this variant (its first image, falling back to the product's). Present whenever an image exists. url: type: string description: Merchant link to this variant. Optional. Product: type: object required: - id - title - categories - price_range - variants properties: id: type: string title: type: string brand: type: string description: Brand or maker label, e.g. "Ray-Ban". Optional. description: type: - string - "null" media: type: array description: Gallery media. Optional — omit it for an image-less product. items: $ref: "#/components/schemas/Media" image_url: type: string description: Primary display image URL (the first image in media). Present whenever the product has any image media. categories: type: array items: type: string price_range: $ref: "#/components/schemas/PriceRange" list_price_range: $ref: "#/components/schemas/PriceRange" variants: type: array items: $ref: "#/components/schemas/Variant" url: type: string description: Merchant link to this product. Optional. ProductPage: type: object required: - products properties: products: type: array items: $ref: "#/components/schemas/Product" pagination: type: object required: - has_next_page properties: cursor: type: string description: Opaque next-page token. Present iff has_next_page is true. has_next_page: type: boolean total_count: type: integer Category: type: object required: - value description: One entry in a store's category vocabulary. `value` is usable verbatim in a catalog search's filters.categories. properties: value: type: string count: type: integer description: Store-global product count for this category, never query-scoped. SearchCatalogRequest: type: object description: Catalog search criteria. Every field is optional. properties: query: type: string description: Free-text search query. filters: type: object properties: categories: type: array items: type: string description: Match products in ANY listed category (OR logic). price: type: object properties: min: type: integer description: Inclusive lower bound, minor units. max: type: integer description: Inclusive upper bound, minor units. pagination: type: object properties: cursor: type: string description: Opaque token from a previous response. limit: type: integer minimum: 1 maximum: 100 Item: type: object required: - id - title - price properties: id: type: string title: type: string price: type: integer description: Integer minor units. image_url: type: string LineItem: type: object required: - item - quantity properties: id: type: string item: type: object required: - id properties: id: type: string description: References an Item.id. quantity: type: integer minimum: 1 parent_id: type: string properties: type: array description: Merchant-defined custom fields, each a { name, value } pair (e.g. an engraving or gift message). Echoed on the order; lines of the same item with different properties stay separate. items: type: object required: - name - value properties: name: type: string value: type: string Total: type: object required: - type - amount properties: type: type: string enum: - subtotal - discount - items_discount - fulfillment - tax - fee - total amount: type: integer display_text: type: string Buyer: type: object properties: email: type: string first_name: type: string full_name: type: string last_name: type: string phone_number: type: string BillingAddress: type: object properties: full_name: type: string first_name: type: string last_name: type: string phone_number: type: string street_address: type: string extended_address: type: string address_locality: type: string address_region: type: string postal_code: type: string address_country: type: string CheckoutCreateRequest: type: object required: - currency - line_items - payment properties: currency: type: string line_items: type: array items: $ref: "#/components/schemas/LineItem" buyer: $ref: "#/components/schemas/Buyer" payment: $ref: "#/components/schemas/CheckoutCreatePayment" CheckoutResponse: type: object required: - id - currency - status - line_items - links - totals - payment - ucp properties: id: type: string currency: type: string status: type: string enum: - canceled - complete_in_progress - completed - incomplete - ready_for_complete - requires_escalation line_items: type: array items: allOf: - $ref: "#/components/schemas/LineItem" - type: object properties: item: $ref: "#/components/schemas/Item" totals: type: array items: $ref: "#/components/schemas/Total" totals: type: array items: $ref: "#/components/schemas/Total" buyer: $ref: "#/components/schemas/Buyer" links: type: array items: $ref: "#/components/schemas/CheckoutLink" payment: $ref: "#/components/schemas/CheckoutPayment" ucp: $ref: "#/components/schemas/UcpEnvelope" Order: type: object required: - id - created_at - checkout_id - currency - permalink_url - line_items - totals - fulfillment - ucp properties: id: type: string display_id: type: string description: Short, customer-facing order reference shown on receipts and emails. Distinct from the opaque `id`; for display only. Absent when the store has no separate reference. example: ORD_1042 created_at: type: string format: date-time description: ISO 8601 timestamp of when the order was placed. example: 2026-06-23T10:15:00Z checkout_id: type: string currency: type: string description: ISO 4217 currency code of the order's monetary amounts. example: GBP permalink_url: type: string line_items: type: array items: $ref: "#/components/schemas/OrderLineItem" totals: type: array items: $ref: "#/components/schemas/Total" fulfillment: $ref: "#/components/schemas/OrderFulfillment" messages: type: array description: Optional store-to-customer notes about the order items: $ref: "#/components/schemas/OrderMessage" ucp: $ref: "#/components/schemas/UcpEnvelope" OrderPage: type: object required: - orders properties: orders: type: array items: $ref: "#/components/schemas/Order" pagination: type: object required: - has_next_page properties: cursor: type: string description: Opaque next-page token. Present iff has_next_page is true. has_next_page: type: boolean total_count: type: integer FulfillmentMethod: type: object description: A selectable fulfillment option for a checkout. Use `id` as `fulfillment_method_id` in `setCheckoutFulfillment`. Shipping methods require a `shipping_address`; pickup/digital do not. Money is integer minor units. required: - id - name - description - amount - currency - method_type properties: id: type: string name: type: string description: type: string amount: type: integer description: Integer minor units. currency: type: string pattern: ^[A-Z]{3}$ method_type: type: string enum: - shipping - pickup - digital UCPDiscoveryProfile: type: object required: - version - capabilities - services properties: version: type: string capabilities: type: array items: type: object required: - name - spec - version - schema properties: name: type: string spec: type: string version: type: string schema: type: string services: type: object additionalProperties: type: object required: - spec - version properties: spec: type: string version: type: string rest: type: object properties: endpoint: type: string schema: type: string mcp: type: object properties: endpoint: type: string schema: type: string paths: /api/commerce/catalog/categories: get: summary: List catalog categories operationId: listCatalogCategories description: The store's full category vocabulary, for catalog discovery. Each label is usable verbatim in the `filters.categories` of a catalog search; the optional `count` is store-global, never scoped to a search. tags: - Commerce security: - ApiKeyAuth: [] responses: "200": description: The store's category vocabulary content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/Category" "401": description: Missing or invalid API key content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/commerce/catalog/products/{id}: get: summary: Get a catalog product operationId: getCatalogProduct tags: - Commerce security: - ApiKeyAuth: [] parameters: - in: path name: id required: true schema: type: string responses: "200": description: Product detail content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Product" "404": description: Product not found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/commerce/catalog/search: post: summary: Search catalog products operationId: searchCatalogProducts tags: - Commerce security: - ApiKeyAuth: [] requestBody: required: false description: Search criteria. Every field is optional — an empty body returns the first page of the whole catalog. content: application/json: schema: $ref: "#/components/schemas/SearchCatalogRequest" responses: "200": description: One page of products, with optional next-page pagination content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/ProductPage" "400": description: Invalid search request body content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "401": description: Missing or invalid API key content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/commerce/checkouts/{id}/buyer: post: summary: Set the buyer and optional billing address on a checkout operationId: setCheckoutBuyer tags: - Commerce security: - ApiKeyAuth: [] parameters: - in: path name: id required: true schema: type: string requestBody: required: true content: application/json: schema: type: object required: - buyer properties: buyer: $ref: "#/components/schemas/Buyer" billing_address: $ref: "#/components/schemas/BillingAddress" responses: "200": description: Updated checkout content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/CheckoutResponse" /api/commerce/checkouts/{id}/complete: post: summary: Complete a checkout (returns the resulting Order) operationId: completeCheckout tags: - Commerce security: - ApiKeyAuth: [] parameters: - in: path name: id required: true schema: type: string responses: "201": description: Order created content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Order" "409": description: Checkout is empty or not in an open state content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/commerce/checkouts/{id}/discount: post: summary: Apply a discount code to a checkout operationId: applyCheckoutDiscount tags: - Commerce security: - ApiKeyAuth: [] parameters: - in: path name: id required: true schema: type: string requestBody: required: true content: application/json: schema: type: object required: - code properties: code: type: string responses: "200": description: Updated checkout content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/CheckoutResponse" /api/commerce/checkouts/{id}/fulfillment-methods: get: summary: List fulfillment methods available for a checkout description: Returns the flat list of selectable methods (`id`, `name`, `description`, `amount`, `currency`, `method_type`). Use a method's `id` as `fulfillment_method_id` in `setCheckoutFulfillment`. operationId: listCheckoutFulfillmentMethods tags: - Commerce security: - ApiKeyAuth: [] parameters: - in: path name: id required: true schema: type: string responses: "200": description: Available fulfillment methods content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/FulfillmentMethod" /api/commerce/checkouts/{id}/fulfillment: post: summary: Set the fulfillment method on a checkout description: Selects a fulfillment method using a selection envelope (`selected_option_id` + `destinations[]`). When the chosen method's `method_type` is `shipping`, the first destination is required and the call fails with `fulfillment_address_required` (400) without it. Destinations are ignored for `pickup` and `digital` methods. Multi-destination split fulfillment is not supported — only the first destination is used. operationId: setCheckoutFulfillment tags: - Commerce security: - ApiKeyAuth: [] parameters: - in: path name: id required: true schema: type: string requestBody: required: true content: application/json: schema: type: object required: - selected_option_id properties: selected_option_id: type: string description: ID of the chosen fulfillment method. destinations: type: array description: Postal destinations. First entry is used for `shipping` methods. items: type: object required: - street_address - address_locality - postal_code - address_country properties: first_name: type: string last_name: type: string full_name: type: string phone_number: type: string street_address: type: string extended_address: type: string address_locality: type: string address_region: type: string postal_code: type: string address_country: type: string description: ISO 3166-1 alpha-2 country code, uppercase (e.g. 'GB', 'US'). responses: "200": description: Updated checkout content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/CheckoutResponse" "400": description: A shipping method was selected without a shipping address content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/commerce/checkouts/{id}/line-items/{lineId}: patch: summary: Update a line item quantity (0 removes it) operationId: updateCheckoutLineItem tags: - Commerce security: - ApiKeyAuth: [] parameters: - in: path name: id required: true schema: type: string - in: path name: lineId required: true schema: type: string requestBody: required: true content: application/json: schema: type: object required: - quantity properties: quantity: type: integer responses: "200": description: Updated checkout content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/CheckoutResponse" delete: summary: Remove a line item from a checkout operationId: removeCheckoutLineItem tags: - Commerce security: - ApiKeyAuth: [] parameters: - in: path name: id required: true schema: type: string - in: path name: lineId required: true schema: type: string responses: "200": description: Updated checkout content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/CheckoutResponse" /api/commerce/checkouts/{id}/line-items: post: summary: Append line items to a checkout operationId: addCheckoutLineItems tags: - Commerce security: - ApiKeyAuth: [] parameters: - in: path name: id required: true schema: type: string requestBody: required: true content: application/json: schema: type: object required: - line_items properties: line_items: type: array items: $ref: "#/components/schemas/LineItem" responses: "200": description: Updated checkout content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/CheckoutResponse" /api/commerce/checkouts/{id}: get: summary: Get a checkout operationId: getCheckout tags: - Commerce security: - ApiKeyAuth: [] parameters: - in: path name: id required: true schema: type: string responses: "200": description: Checkout detail content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/CheckoutResponse" "404": description: Checkout not found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/commerce/checkouts: post: summary: Create a checkout operationId: createCheckout tags: - Commerce security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CheckoutCreateRequest" responses: "201": description: Checkout created content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/CheckoutResponse" "400": description: Invalid payload content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/commerce/orders/{id}: get: summary: Get an order operationId: getOrder tags: - Commerce security: - ApiKeyAuth: [] parameters: - in: path name: id required: true schema: type: string responses: "200": description: Order detail content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Order" "404": description: Order not found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/commerce/orders: get: summary: List orders for the caller operationId: listOrders tags: - Commerce security: - ApiKeyAuth: [] parameters: - in: query name: limit required: false schema: type: integer minimum: 1 maximum: 100 description: Maximum orders to return on this page. - in: query name: cursor required: false schema: type: string description: Opaque cursor from a previous response's `pagination.cursor`. Omit for the first page. responses: "200": description: One page of orders, with optional next-page pagination content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/OrderPage" "400": description: Invalid pagination parameters content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "401": description: The caller must authenticate before listing orders (`authentication_required`). content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/shops/{id}: get: summary: Get shop detail operationId: getShop tags: - Shops security: - ApiKeyAuth: [] parameters: - in: path name: id required: true schema: type: string responses: "200": description: Shop detail content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Shop" "400": description: Missing or invalid shop short id content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "401": description: Missing or invalid API key content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "404": description: Shop not found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Server error while fetching shop content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" put: summary: Update shop operationId: updateShop tags: - Shops security: - ApiKeyAuth: [] parameters: - in: path name: id required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ShopUpdateRequest" responses: "200": description: Shop updated content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Shop" "400": description: Invalid payload or invalid shop short id content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "401": description: Missing or invalid API key content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "404": description: Shop not found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Server error while updating shop content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" delete: summary: Delete shop operationId: deleteShop tags: - Shops security: - ApiKeyAuth: [] parameters: - in: path name: id required: true schema: type: string responses: "200": description: Shop deleted content: application/json: schema: type: object properties: id: type: string "400": description: Missing or invalid shop short id content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "401": description: Missing or invalid API key content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "404": description: Shop not found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Server error while deleting shop content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/shops: get: summary: List shops description: Returns merchant-owned shops for the authenticated API key. operationId: listShops tags: - Shops security: - ApiKeyAuth: [] responses: "200": description: List of shops content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/Shop" "401": description: Missing or invalid API key content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Server error while fetching shops content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" post: summary: Create shop description: Creates a new merchant-owned shop. operationId: createShop tags: - Shops security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ShopCreateRequest" responses: "201": description: Shop created content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Shop" "400": description: Invalid payload content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "401": description: Missing or invalid API key content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Server error while creating shop content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /.well-known/ucp/{deployment}: get: summary: UCP capability discovery for a deployment operationId: ucpDiscovery tags: - Commerce parameters: - in: path name: deployment required: true schema: type: string responses: "200": description: UCP Discovery profile content: application/json: schema: $ref: "#/components/schemas/UCPDiscoveryProfile" "404": description: Deployment not found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" tags: - name: Shops description: Shop management endpoints. - name: Commerce description: Deployment-scoped commerce endpoints (catalog, checkout, order). Authenticated with a deployment (`dk_`) API key. Internal plumbing between the hosted MCP server and the merchant adapter — merchants integrate via the MCP, not these REST routes.