generated: '2026-08-07'
method: derived
source: >-
  graphql/black-buffalo-storefront.graphql + mcp/black-buffalo-ucp-mcp-tools.json +
  mcp/black-buffalo-storefront-mcp-tools.json + llms/black-buffalo-agents.md
docs: https://shopify.dev/docs/api/storefront
description: >-
  Cross-cutting request/response semantics for the surfaces Black Buffalo actually
  serves. Derived from the anonymously introspected GraphQL SDL, two live MCP tools/list
  responses, the discovery documents, and the provider's own published agent
  instructions.
authentication:
  style: >-
    none for storefront GraphQL and both MCP servers; a UCP agent profile URI for UCP
    tool invocation; OIDC / OAuth 2.0 authorization code + PKCE for customer accounts
  detail: authentication/black-buffalo-authentication.yml
idempotency:
  supported: false
  header: null
  note: >-
    No idempotency key is offered on any observed surface. Neither MCP server exposes an
    idempotency parameter on any of its eighteen tools, and the Storefront GraphQL cart
    mutations are not idempotent. Retry safety comes only from id addressing — repeating
    update_cart with the same add_items adds the items again — so agents must treat cart
    and checkout mutations as at-most-once and reconcile with get_cart / get_checkout.
    This matters most on complete_checkout, where a naive retry risks a duplicate order
    and there is no server-side dedupe key to prevent it.
  no_idempotency_pointer_is_deliberate: true
pagination:
  style: relay-cursor
  applies_to: GraphQL connections (28 *Connection types in the SDL)
  request_params: [first, last, after, before, reverse, sortKey]
  response_fields:
  - edges
  - edges.node
  - edges.cursor
  - nodes
  - pageInfo.hasNextPage
  - pageInfo.hasPreviousPage
  - pageInfo.startCursor
  - pageInfo.endCursor
  mcp: >-
    search_catalog returns paginated results with a deliberately small first page; the
    tool documents pagination.cursor for fetching further pages ("Use the
    pagination.cursor from the response to fetch additional pages when users request
    more results").
field_selection:
  style: graphql-selection-set
  note: GraphQL selection sets replace sparse-fieldset and expansion parameters entirely.
  mcp: >-
    The MCP tools return fixed response shapes; get_product supports `selected` and
    `preferences` for variant narrowing, which is option resolution rather than field
    selection.
identifiers:
  format: 'gid://shopify/{Type}/{id}'
  examples_from_tool_docs:
  - 'gid://shopify/Checkout/abc123'
  - 'gid://shopify/Product/...'
  - 'gid://shopify/ProductVariant/...'
  handles: >-
    Product, Collection, Page, Blog, Article and Metaobject also carry a human-readable
    `handle` used in storefront URLs and in the *ByHandle queries.
  detail: data-model/black-buffalo-data-model.yml
metadata:
  style: metafields and metaobjects
  fields: [metafield, metafields, metaobject, metaobjects]
  mutations: [cartMetafieldsSet, cartMetafieldDelete]
  note: Namespaced custom data (namespace + key) attached to products, variants, collections, carts and the shop.
localization:
  mechanism: '@inContext directive'
  params: [country, language, buyerIdentity, preferredLocationId]
  mcp_equivalent: get_product_details takes country and language.
  reality: >-
    shipsToCountries is [US] and the store currency is USD, so localization is largely
    inert for this merchant.
agent_identity:
  mechanism: 'meta["ucp-agent"]["profile"] — a resolvable agent profile URI'
  required_on: all 13 UCP MCP tools
  enforced_on: tool invocation, resources/list, prompts/list
  note: >-
    The closest thing to a request-tracing convention on this API. There is no
    request-id header, no correlation id and no trace context on any surface.
request_tracing:
  supported: false
  note: No request-id, correlation-id or trace header observed on any surface.
versioning:
  scheme: calendar-quarter path segment for GraphQL; dated protocol versions for UCP
  graphql_pattern: /api/{YYYY-MM}/graphql.json
  graphql_current: '2026-07'
  ucp_supported: ['2026-04-08', '2026-01-23']
  detail: lifecycle/black-buffalo-lifecycle.yml
error_envelope:
  graphql:
    transport_status: 200 with an errors[] array
    request_errors: [message, locations, path, extensions.code]
    mutation_errors: 'typed *UserError lists implementing DisplayableError (field, message, code)'
  mcp:
    transport: JSON-RPC 2.0
    shape: [error.code, error.message, error.data]
    observed: '-32001 "UCP discovery failed" with data.code invalid_profile_url'
  detail: errors/black-buffalo-problem-types.yml
rate_limiting:
  style: query-cost, not header-based
  signal: extensions.cost.requestedQueryCost on every GraphQL response
  headers: none observed
  mcp: no rate-limit headers observed on either MCP endpoint
  docs: https://shopify.dev/docs/api/usage/limits
agent_policy:
  source: https://blackbuffalo.com/robots.txt and https://blackbuffalo.com/agents.md
  human_in_the_loop: >-
    "Checkouts are for humans." Agents must not complete checkout, payment or order
    placement automatically — no scripted form fills, browser automation, or end-to-end
    agent flows that finalize payment without an explicit, contemporaneous human approval
    step.
  disallowed_for_agents: [/cart.js, /recommendations/products]
  preferred_surfaces: [UCP MCP, Storefront MCP, 'https://shop.app/SKILL.md']
  content_restrictions: >-
    /agents.md forbids health claims, cessation framing, "tobacco-free" applied to
    nicotine products, modified-risk claims, comparative superiority claims against named
    competitors, and any recommendation to anyone under 21.
  detail: agentic-access/black-buffalo-agentic-access.yml