{"openapi":"3.1.0","info":{"title":"Pivota Agent API","description":"Production-ready API for agent integrations","version":"1.0.0"},"paths":{"/agent/v1/briefs/clarify":{"post":{"tags":["agent-briefs"],"summary":"Clarify Brief","operationId":"clarify_brief_agent_v1_briefs_clarify_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BriefClarifyRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BriefClarifyResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}]}},"/agent/v1/briefs/build":{"post":{"tags":["agent-briefs"],"summary":"Build Brief","description":"Build and persist Brief v0.1.0.\n\nDeterministic: rule-based parsing + explicit unknowns + evidence.","operationId":"build_brief_agent_v1_briefs_build_post","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BriefBuildRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BriefBuildResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/briefs/compatibility/check":{"post":{"tags":["agent-briefs"],"summary":"Check Compatibility","operationId":"check_compatibility_agent_v1_briefs_compatibility_check_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BriefCompatibilityRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BriefCompatibilityResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}]}},"/agent/v1/checkout/external-platform":{"post":{"tags":["agent-checkout"],"summary":"Create External Platform Checkout","description":"Create a merchant/platform-hosted checkout redirect without creating a Pivota order or PSP payment.\n\nThis is the safe non-Shopify fallback when Pivota does not have a live quote adapter:\nthe platform checkout remains responsible for final price, tax, shipping, payment,\ninventory availability, and inventory decrement.","operationId":"create_external_platform_checkout_agent_v1_checkout_external_platform_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCheckoutIntentRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}]}},"/agent/v1/checkout/acp":{"post":{"tags":["agent-checkout"],"summary":"Create Acp Checkout","description":"P-T2.3.1b — initiate an in-chat ACP checkout SCREEN for an ACP-capable,\ncharge-permitted merchant, else fall back to the redirect floor.\n\nDARK: this creates a pivota-acp session (screen/quote) only. It does NOT\ncomplete or charge — real capture is gated behind the kill-switch + P-T2.3.2+.\nBy default (SUBMIT_PAYMENT off) the lane decision routes every merchant to the\nredirect floor, so this endpoint is inert until a merchant is canary-enabled.","operationId":"create_acp_checkout_agent_v1_checkout_acp_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAcpCheckoutRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}]}},"/agent/v1/checkout/acp/{session_id}/complete":{"post":{"tags":["agent-checkout"],"summary":"Complete Acp Checkout","description":"Complete an in-process ACP checkout session: quote → order(acp) → REAL\noff-session charge through the shared Tier-2 gate chain (kill-switch +\ntest/live capture caps — the exact gates POST /agent/v1/payments enforces).\n\nFail-closed: a dark kill-switch or an over-cap charge is a 403 (the gate's\nown error shape), a capture failure is a 502 with a named code, and there is\nNO simulated-capture fallback. Success is returned only when the capture\nactually succeeded; a completed session replays idempotently (never\nre-charges), and an idempotency-key reuse with a different payload is a 409\n`idempotency_conflict` (ACP wire semantics).","operationId":"complete_acp_checkout_agent_v1_checkout_acp__session_id__complete_post","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"session_id","in":"path","required":true,"schema":{"type":"string","title":"Session Id"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteAcpCheckoutRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/checkout/intents":{"post":{"tags":["agent-checkout"],"summary":"Create Checkout Intent","operationId":"create_checkout_intent_agent_v1_checkout_intents_post","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"X-Agent-User-JWT","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Agent-User-Jwt"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCheckoutIntentRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/checkout/prefill":{"get":{"tags":["agent-checkout"],"summary":"Get Checkout Prefill","description":"Return checkout prefill data for the current checkout token (if available).\n\nAuth:\n- X-Checkout-Token (preferred)","operationId":"get_checkout_prefill_agent_v1_checkout_prefill_get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"X-Checkout-UI-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Checkout-Ui-Key"}},{"name":"X-Checkout-UI-Auth","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Checkout-Ui-Auth"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/quotes/preview":{"post":{"tags":["agent-quotes"],"summary":"Preview Quote","operationId":"preview_quote_agent_v1_quotes_preview_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuotePreviewRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuotePreviewResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}]}},"/agent/v1/offers/preflight":{"post":{"tags":["agent-offers"],"summary":"Preflight Quote Offer","description":"Build canonical OfferObject(s) from a quote snapshot and return structured preflight results.\n\nNotes:\n- This endpoint is additive and does not replace existing quote/order endpoints.\n- Enforcement is gated by `MVP_PREFLIGHT_ENFORCE=true`.","operationId":"preflight_quote_offer_agent_v1_offers_preflight_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfferPreflightRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}]}},"/agent/v1/ops/packs/draft":{"post":{"tags":["agent-ops"],"summary":"Create Draft Pack","operationId":"create_draft_pack_agent_v1_ops_packs_draft_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDraftPackRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}]}},"/agent/v1/ops/packs/generate":{"post":{"tags":["agent-ops"],"summary":"Generate Draft Pack","description":"Best-effort generator: creates a draft pack from existing product cache rows.\n\nConstraints:\n- No scraping / automated social discovery. `authorized_signals` are always empty by default.\n- Uses only internal cached product data.","operationId":"generate_draft_pack_agent_v1_ops_packs_generate_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateDraftPackRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}]}},"/agent/v1/ops/packs/{pack_id}":{"get":{"tags":["agent-ops"],"summary":"Get Pack","operationId":"get_pack_agent_v1_ops_packs__pack_id__get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"pack_id","in":"path","required":true,"schema":{"type":"string","title":"Pack Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/ops/packs/{pack_id}/validate":{"post":{"tags":["agent-ops"],"summary":"Validate Pack","operationId":"validate_pack_agent_v1_ops_packs__pack_id__validate_post","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"pack_id","in":"path","required":true,"schema":{"type":"string","title":"Pack Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/ops/packs/{pack_id}/publish":{"post":{"tags":["agent-ops"],"summary":"Publish Pack","operationId":"publish_pack_agent_v1_ops_packs__pack_id__publish_post","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"pack_id","in":"path","required":true,"schema":{"type":"string","title":"Pack Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/citation/search":{"get":{"tags":["agent-citation"],"summary":"Search Citations","operationId":"search_citations_agent_v1_citation_search_get","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","description":"free-text query","default":"","title":"Q"},"description":"free-text query"},{"name":"intent","in":"query","required":false,"schema":{"type":"string","description":"inform (cite) | shop (suppressed)","default":"inform","title":"Intent"},"description":"inform (cite) | shop (suppressed)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":20,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Search Citations Agent V1 Citation Search Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/citation/{citation_id}":{"get":{"tags":["agent-citation"],"summary":"Get Citation","operationId":"get_citation_agent_v1_citation__citation_id__get","parameters":[{"name":"citation_id","in":"path","required":true,"schema":{"type":"string","title":"Citation Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Citation Agent V1 Citation  Citation Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v2/commerce/checkouts":{"post":{"tags":["agent-commerce"],"summary":"Create Commerce Checkout","operationId":"create_commerce_checkout_agent_v2_commerce_checkouts_post","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"X-Agent-User-JWT","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Agent-User-Jwt"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCommerceCheckoutRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v2/commerce/checkouts/{checkout_id}/payment-intent":{"post":{"tags":["agent-commerce"],"summary":"Get Checkout Payment Intent","operationId":"get_checkout_payment_intent_agent_v2_commerce_checkouts__checkout_id__payment_intent_post","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"checkout_id","in":"path","required":true,"schema":{"type":"string","title":"Checkout Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentIntentRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v2/commerce/checkouts/{checkout_id}/status":{"get":{"tags":["agent-commerce"],"summary":"Get Checkout Status","operationId":"get_checkout_status_agent_v2_commerce_checkouts__checkout_id__status_get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"checkout_id","in":"path","required":true,"schema":{"type":"string","title":"Checkout Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v2/commerce/checkouts/{checkout_id}/refunds":{"post":{"tags":["agent-commerce"],"summary":"Create Checkout Refund","operationId":"create_checkout_refund_agent_v2_commerce_checkouts__checkout_id__refunds_post","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"checkout_id","in":"path","required":true,"schema":{"type":"string","title":"Checkout Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutRefundBody"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v2/commerce/checkouts/{checkout_id}/returns":{"post":{"tags":["agent-commerce"],"summary":"Sync Checkout Returns","operationId":"sync_checkout_returns_agent_v2_commerce_checkouts__checkout_id__returns_post","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"checkout_id","in":"path","required":true,"schema":{"type":"string","title":"Checkout Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutReturnBody"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v2/commerce/reap/purchases/prepare":{"post":{"tags":["agent-commerce-reap"],"summary":"Prepare Reap Purchase Selection","description":"Authenticated read-only selection witness, before an original create body exists.\n\nA numeric selector is not a SKU key. Resolve it to exactly one existing live SKU,\nthen use the create lane's proof, seller and own-offer reader with that exact key.\nNo buyer, consent, idempotency, click, enrollment or purchase row is touched; no\nnetwork fetch or provider request is made. Recovery never calls this endpoint.","operationId":"prepare_reap_purchase_selection_agent_v2_commerce_reap_purchases_prepare_post","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"X-Agent-User-JWT","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Agent-User-Jwt"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v2/commerce/reap/purchases":{"post":{"tags":["agent-commerce-reap"],"summary":"Start Reap Purchase","description":"Open a purchase and answer at once. MAKES NO PARTNER CALL — the poller does that.","operationId":"start_reap_purchase_agent_v2_commerce_reap_purchases_post","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"X-Agent-User-JWT","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Agent-User-Jwt"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["agent-commerce-reap"],"summary":"List Reap Purchases","operationId":"list_reap_purchases_agent_v2_commerce_reap_purchases_get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"X-Agent-User-JWT","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Agent-User-Jwt"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v2/commerce/reap/purchases/{purchase_id}/resume":{"post":{"tags":["agent-commerce-reap"],"summary":"Resume Reap Purchase","description":"Explicit contact re-entry for one owner/request/attempt; never a replacement/recovery write.\n\nThe original canonical request (including the original contact) is required. Its key already\nmaps to this purchase. Terminal and legacy/unknown dispatch rows cannot be rehydrated.\nRepeated accepted submissions return the same view without renewing the contact clock.","operationId":"resume_reap_purchase_agent_v2_commerce_reap_purchases__purchase_id__resume_post","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"purchase_id","in":"path","required":true,"schema":{"type":"string","title":"Purchase Id"}},{"name":"X-Agent-User-JWT","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Agent-User-Jwt"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v2/commerce/reap/purchases/recover":{"post":{"tags":["agent-commerce-reap"],"summary":"Recover Reap Purchase","description":"Read-only exact-attempt lookup, available while create is disabled.\n\nTakes the original create body so the existing canonical fingerprint can be checked.\nReads only: no merchant/catalog lookup, identity/consent write, provider call or key refresh.\nMissing/uncertain mapping must never be interpreted as permission to create another attempt.","operationId":"recover_reap_purchase_agent_v2_commerce_reap_purchases_recover_post","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"X-Agent-User-JWT","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Agent-User-Jwt"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v2/commerce/reap/purchases/{purchase_id}":{"get":{"tags":["agent-commerce-reap"],"summary":"Get Reap Purchase","operationId":"get_reap_purchase_agent_v2_commerce_reap_purchases__purchase_id__get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"purchase_id","in":"path","required":true,"schema":{"type":"string","title":"Purchase Id"}},{"name":"X-Agent-User-JWT","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Agent-User-Jwt"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/health":{"get":{"tags":["agent-sdk"],"summary":"Health Check","description":"Health check endpoint","operationId":"health_check_agent_v1_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/agent/v1/auth":{"post":{"tags":["agent-sdk"],"summary":"Generate Api Key","description":"Generate or retrieve agent API key","operationId":"generate_api_key_agent_v1_auth_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentAuthRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/merchants":{"get":{"tags":["agent-sdk"],"summary":"List Merchants","description":"List connected merchants - FIXED to only query existing columns","operationId":"list_merchants_agent_v1_merchants_get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","default":"active","title":"Status"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/products/search":{"get":{"tags":["agent-sdk"],"summary":"Search Products","description":"Delegate to optimized `/agent/v1/products/search` implementation in `agent_api`.\n\nReason:\nthis router is registered earlier than `agent_api` in `main.py`, so this path\nis the effective handler in production. Delegation keeps route compatibility\nwhile using the lower-latency implementation.","operationId":"search_products_agent_v1_products_search_get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"merchant_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Merchant Id"}},{"name":"merchant_ids","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"List of merchant IDs to search","title":"Merchant Ids"},"description":"List of merchant IDs to search"},{"name":"search_all_merchants","in":"query","required":false,"schema":{"type":"boolean","description":"Opt-in cross-merchant search","default":false,"title":"Search All Merchants"},"description":"Opt-in cross-merchant search"},{"name":"query","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Query"}},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"}},{"name":"catalog_surface","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional search surface. Set to 'beauty' for beauty-only candidate filtering.","title":"Catalog Surface"},"description":"Optional search surface. Set to 'beauty' for beauty-only candidate filtering."},{"name":"min_price","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Min Price"}},{"name":"max_price","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Max Price"}},{"name":"in_stock","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"In Stock"}},{"name":"in_stock_only","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"In Stock Only"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":20,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"allow_external_seed","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Allow External Seed"}},{"name":"allow_stale_cache","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Allow Stale Cache"}},{"name":"external_seed_strategy","in":"query","required":false,"schema":{"type":"string","default":"legacy","title":"External Seed Strategy"}},{"name":"fast_mode","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Fast Mode"}},{"name":"market","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Market"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/sdk/orders":{"get":{"tags":["agent-sdk"],"summary":"List Orders","description":"List orders (SDK legacy).\n\nDeprecated: use `/agent/v1/orders` from `routes/agent_api.py` instead.","operationId":"list_orders_agent_v1_sdk_orders_get","deprecated":true,"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"merchant_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Merchant Id"}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/openapi.json":{"get":{"tags":["agent-sdk"],"summary":"Get Openapi Spec","description":"Return runtime-derived agent OpenAPI specification for SDK generation","operationId":"get_openapi_spec_agent_v1_openapi_json_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/agent/v1/payments":{"post":{"tags":["agent-payments"],"summary":"Create Payment","description":"Create payment for an order\n\nFlow:\n1. Validate order exists and not already paid\n2. Get merchant PSP configuration\n3. Create payment intent with PSP\n4. Handle 3DS if required\n5. Return payment status\n\nFeatures:\n- Automatic PSP failover\n- 3DS authentication support\n- Idempotency protection\n- Payment retry logic","operationId":"create_payment_agent_v1_payments_post","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"X-HIL-Approval","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Hil-Approval"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/payments/authorize":{"post":{"tags":["agent-payments"],"summary":"Authorize Payment","description":"Mint a constrained authorization token for future agentic payments (skeleton; no PSP charge).\n\nSecurity:\n- Agent can only authorize against mandates belonging to its own agent_id.\n- Only stores token hash (never stores raw token).","operationId":"authorize_payment_agent_v1_payments_authorize_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthorizePaymentRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthorizePaymentResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}]}},"/agent/v1/payments/{payment_id}":{"get":{"tags":["agent-payments"],"summary":"Get Payment Status","description":"Get payment status\n\nReturns current status of payment including:\n- Payment status (requires_action, processing, succeeded, failed)\n- PSP used\n- Amount and currency\n- Next action if required","operationId":"get_payment_status_agent_v1_payments__payment_id__get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"payment_id","in":"path","required":true,"schema":{"type":"string","title":"Payment Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/products/merchants/{merchant_id}":{"get":{"tags":["Agent Products"],"summary":"Get Merchant Products","description":"Get merchant products via hybrid query (cache or realtime merchant API)\n\nAutomatically decides between:\n- Cached products (fast, <100ms)\n- Realtime merchant API (if configured, <1s)\n\nReturns unified format regardless of source","operationId":"get_merchant_products_agent_v1_products_merchants__merchant_id__get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"merchant_id","in":"path","required":true,"schema":{"type":"string","title":"Merchant Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":250,"default":50,"title":"Limit"}},{"name":"market","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Market"}},{"name":"psp","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Psp"}},{"name":"payment_method_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Payment Method Type"}},{"name":"card_network","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Card Network"}},{"name":"issuer_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Issuer Name"}},{"name":"wallet_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Wallet Type"}},{"name":"installment_provider","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Installment Provider"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/products/merchants/{merchant_id}/product/{product_id}":{"get":{"tags":["Agent Products"],"summary":"Get Product Details","description":"Get detailed information about a specific product","operationId":"get_product_details_agent_v1_products_merchants__merchant_id__product__product_id__get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"merchant_id","in":"path","required":true,"schema":{"type":"string","title":"Merchant Id"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string","title":"Product Id"}},{"name":"market","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Market"}},{"name":"psp","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Psp"}},{"name":"payment_method_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Payment Method Type"}},{"name":"card_network","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Card Network"}},{"name":"issuer_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Issuer Name"}},{"name":"wallet_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Wallet Type"}},{"name":"installment_provider","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Installment Provider"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/products/merchants/{merchant_id}/variant/{variant_id}":{"get":{"tags":["Agent Products"],"summary":"Get Product Details By Variant","description":"Resolve a platform variant_id to its parent product and return product details.","operationId":"get_product_details_by_variant_agent_v1_products_merchants__merchant_id__variant__variant_id__get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"merchant_id","in":"path","required":true,"schema":{"type":"string","title":"Merchant Id"}},{"name":"variant_id","in":"path","required":true,"schema":{"type":"string","title":"Variant Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/products/merchants/{merchant_id}/product/{product_id}/related":{"get":{"tags":["Agent Products"],"summary":"Get Related Products","description":"Recommend related products for a given product.\n\nStrategy:\n- Fetch products via hybrid query (cache or realtime)\n- Compute similarity based on vendor, product_type, tags, and title tokens\n- Return top-N related items (excluding the current product)","operationId":"get_related_products_agent_v1_products_merchants__merchant_id__product__product_id__related_get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"merchant_id","in":"path","required":true,"schema":{"type":"string","title":"Merchant Id"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string","title":"Product Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":10,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/products/recommendations":{"get":{"tags":["Agent Products"],"summary":"Get Product Recommendations","description":"Recommend related products for a given Shopify product.\n\nStrategy:\n- Target is resolved from products_cache (platform='shopify').\n- Primary candidates: same recommendation_meta.group_id.\n- Secondary candidates: facet-similar products from products_cache using\n  recommendation_meta.tags prefilter + Python reranking.","operationId":"get_product_recommendations_agent_v1_products_recommendations_get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"merchant_id","in":"query","required":true,"schema":{"type":"string","title":"Merchant Id"}},{"name":"platform_product_id","in":"query","required":true,"schema":{"type":"string","title":"Platform Product Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":20,"minimum":1,"default":8,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/analytics/funnel":{"get":{"tags":["agent-analytics"],"summary":"Get Conversion Funnel","description":"Get order conversion funnel for this agent","operationId":"get_conversion_funnel_agent_v1_analytics_funnel_get","parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":90,"minimum":1,"default":7,"title":"Days"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Conversion Funnel Agent V1 Analytics Funnel Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/analytics/queries":{"get":{"tags":["agent-analytics"],"summary":"Get Query Analytics","description":"Get query analytics (product searches, inventory checks, price queries)\nBased on agent_usage_logs for this agent","operationId":"get_query_analytics_agent_v1_analytics_queries_get","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Query Analytics Agent V1 Analytics Queries Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/buyers/merge":{"post":{"tags":["agent-api"],"summary":"Agent Merge Buyer Refs","description":"Merge (alias) a source buyer_ref into a canonical target buyer_ref (agent-scoped).\n\nIntended usage:\n- user logs in: merge guest:{uuid} -> user:{public_id}\n- later order lookups with buyer_ref=user:{public_id} include both","operationId":"agent_merge_buyer_refs_agent_v1_buyers_merge_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyerRefMergeRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}]}},"/agent/v1/checkout/acp-session":{"post":{"tags":["agent-api"],"summary":"Agent Create Acp Checkout Session","description":"Create an ACP-hosted checkout session for a merchant.\n\nThis keeps users on a Pivota-controlled checkout surface (ACP) instead of redirecting to merchant storefront URLs.","operationId":"agent_create_acp_checkout_session_agent_v1_checkout_acp_session_post","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"X-Buyer-Ref","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Buyer-Ref"}},{"name":"X-Agent-User-JWT","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Agent-User-Jwt"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Payload"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/debug/shopify/webhooks/events":{"get":{"tags":["agent-api"],"summary":"Agent Get Shopify Webhook Events","description":"Metadata-only view of ingested Shopify webhook events for a merchant.\n\nWhy this exists:\n- Production debugging often has no easy way to obtain a Bearer login token.\n- Agent API keys already have merchant scoping via AgentContext.\n\nSecurity:\n- Requires X-API-Key (AgentContext).\n- Enforces merchant access via context.can_access_merchant().\n- Never returns raw payload_json / PII.","operationId":"agent_get_shopify_webhook_events_agent_v1_debug_shopify_webhooks_events_get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"merchant_id","in":"query","required":true,"schema":{"type":"string","title":"Merchant Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":20,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/beauty/products/search":{"get":{"tags":["agent-api"],"summary":"Agent Search Products Beauty","description":"Beauty-only alias for agent product search.\nForces catalog_surface=beauty while preserving existing search behavior.\n\nBehind AGENT_BEAUTY_SEARCH_VIA_GATEWAY this is served by the gateway's implementation of the\nsame search (ADR-021: one external door) -- see services/agent_search_gateway_proxy.py.\nOff (the default), nothing below the local call changes.","operationId":"agent_search_products_beauty_agent_v1_beauty_products_search_get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"merchant_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Merchant Id"}},{"name":"merchant_ids","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"List of merchant IDs to search","title":"Merchant Ids"},"description":"List of merchant IDs to search"},{"name":"search_all_merchants","in":"query","required":false,"schema":{"type":"boolean","description":"Opt-in cross-merchant search (requires explicit intent to avoid irrelevant results)","default":false,"title":"Search All Merchants"},"description":"Opt-in cross-merchant search (requires explicit intent to avoid irrelevant results)"},{"name":"query","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Query"}},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"}},{"name":"min_price","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Min Price"}},{"name":"max_price","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Max Price"}},{"name":"in_stock_only","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"In Stock Only"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":20,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"allow_external_seed","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Allow External Seed"}},{"name":"allow_stale_cache","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Allow Stale Cache"}},{"name":"external_seed_strategy","in":"query","required":false,"schema":{"type":"string","default":"legacy","title":"External Seed Strategy"}},{"name":"fast_mode","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Fast Mode"}},{"name":"market","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Market"}},{"name":"psp","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Psp"}},{"name":"payment_method_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Payment Method Type"}},{"name":"card_network","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Card Network"}},{"name":"issuer_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Issuer Name"}},{"name":"wallet_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Wallet Type"}},{"name":"installment_provider","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Installment Provider"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/products/resolve":{"get":{"tags":["agent-api"],"summary":"Agent Resolve Products","description":"Resolve a stable product reference for PDP flows.\n\nResolution order:\n1) products_cache exact aliases (product_id / sku_id)\n2) scoped / global agent search fallback\n3) canonical product_group mapping (when available)","operationId":"agent_resolve_products_agent_v1_products_resolve_get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"merchant_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional merchant scope","title":"Merchant Id"},"description":"Optional merchant scope"},{"name":"product_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Product id / canonical ref / PDP URL","title":"Product Id"},"description":"Product id / canonical ref / PDP URL"},{"name":"sku_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"SKU / variant id","title":"Sku Id"},"description":"SKU / variant id"},{"name":"query","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Fallback free-text query","title":"Query"},"description":"Fallback free-text query"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"default":10,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/product-groups/resolve":{"get":{"tags":["agent-api"],"summary":"Agent Resolve Product Group","description":"Resolve a merchant product into a curated product_group_id, and return its members.\n\nThis powers the gateway's \"one product + many seller offers\" flow.","operationId":"agent_resolve_product_group_agent_v1_product_groups_resolve_get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"merchant_id","in":"query","required":true,"schema":{"type":"string","description":"Anchor merchant ID","title":"Merchant Id"},"description":"Anchor merchant ID"},{"name":"product_id","in":"query","required":true,"schema":{"type":"string","description":"Merchant-scoped platform product_id (platform_product_id)","title":"Product Id"},"description":"Merchant-scoped platform product_id (platform_product_id)"},{"name":"platform","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional platform filter (shopify/wix/...)","title":"Platform"},"description":"Optional platform filter (shopify/wix/...)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Agent Resolve Product Group Agent V1 Product Groups Resolve Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/product-groups/resolve-by-product-id":{"get":{"tags":["agent-api"],"summary":"Agent Resolve Product Group By Product Id","description":"Resolve a product group when the caller only has a product_id (platform_product_id).\n\nThis enables PDP links without a merchant_id by mapping product_id -> product_group_id\nvia product_group_members, then returning the group members.","operationId":"agent_resolve_product_group_by_product_id_agent_v1_product_groups_resolve_by_product_id_get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"product_id","in":"query","required":true,"schema":{"type":"string","description":"Any member product_id (platform_product_id)","title":"Product Id"},"description":"Any member product_id (platform_product_id)"},{"name":"platform","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional platform filter (shopify/wix/...)","title":"Platform"},"description":"Optional platform filter (shopify/wix/...)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Agent Resolve Product Group By Product Id Agent V1 Product Groups Resolve By Product Id Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/product-groups/{product_group_id}":{"get":{"tags":["agent-api"],"summary":"Agent Get Product Group","description":"Fetch product-group members by product_group_id.","operationId":"agent_get_product_group_agent_v1_product_groups__product_group_id__get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"product_group_id","in":"path","required":true,"schema":{"type":"string","title":"Product Group Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Agent Get Product Group Agent V1 Product Groups  Product Group Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/products/{merchant_id}/{product_id}":{"get":{"tags":["agent-api"],"summary":"Agent Get Product","description":"获取单个产品详情","operationId":"agent_get_product_agent_v1_products__merchant_id___product_id__get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"merchant_id","in":"path","required":true,"schema":{"type":"string","title":"Merchant Id"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string","title":"Product Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/cart/validate":{"post":{"tags":["agent-api"],"summary":"Agent Validate Cart","description":"验证购物车并计算价格\n\n功能：\n- 库存验证\n- 价格更新\n- 运费计算\n- 税费估算","operationId":"agent_validate_cart_agent_v1_cart_validate_post","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"merchant_id","in":"query","required":true,"schema":{"type":"string","title":"Merchant Id"}},{"name":"shipping_country","in":"query","required":false,"schema":{"type":"string","default":"US","title":"Shipping Country"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true},"title":"Items"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/orders/payment-offer-evidence":{"post":{"tags":["agent-api"],"summary":"Agent Record Payment Offer Evidence","description":"Record card/wallet/PSP evidence without changing order totals, PSP amounts,\nor Shopify discount fields.","operationId":"agent_record_payment_offer_evidence_agent_v1_orders_payment_offer_evidence_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordPaymentOfferEvidenceRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}]}},"/agent/v1/orders/create":{"post":{"tags":["agent-api"],"summary":"Agent Create Order","description":"创建订单（代理标准订单创建流程）\n\n自动添加 Agent 追踪信息\n集成 Agent Governance 治理检查","operationId":"agent_create_order_agent_v1_orders_create_post","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"X-Buyer-Ref","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Buyer-Ref"}},{"name":"X-Agent-User-JWT","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Agent-User-Jwt"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrderRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/orders/{order_id}/confirm-payment":{"post":{"tags":["agent-api"],"summary":"Agent Confirm Payment","description":"确认支付并触发 Shopify 订单创建（Agent 调用）","operationId":"agent_confirm_payment_agent_v1_orders__order_id__confirm_payment_post","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","title":"Order Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/orders/events":{"get":{"tags":["agent-api"],"summary":"Agent List Order Events","operationId":"agent_list_order_events_agent_v1_orders_events_get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"after_id","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"After Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"wait_ms","in":"query","required":false,"schema":{"type":"integer","maximum":25000,"minimum":0,"default":0,"title":"Wait Ms"}},{"name":"merchant_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Merchant Id"}},{"name":"order_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Order Id"}},{"name":"buyer_ref","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Buyer Ref"}},{"name":"X-Agent-User-JWT","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Agent-User-Jwt"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/orders/{order_id}":{"get":{"tags":["agent-api"],"summary":"Agent Get Order","description":"获取订单状态","operationId":"agent_get_order_agent_v1_orders__order_id__get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","title":"Order Id"}},{"name":"buyer_ref","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Buyer Ref"}},{"name":"X-Agent-User-JWT","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Agent-User-Jwt"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/orders/{order_id}/reviews/invitations":{"post":{"tags":["agent-api"],"summary":"Agent Issue Review Invitations From Order","description":"Mint browser-safe invitation_token(s) for a paid order.\n\nThis endpoint is intended for checkout/order detail UIs to offer \"Write a review\"\nwithout exposing internal issuer keys to browsers. Tokens are single-use via the\nexchange endpoint and can be minted per line-item (product/variant).","operationId":"agent_issue_review_invitations_from_order_agent_v1_orders__order_id__reviews_invitations_post","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","title":"Order Id"}},{"name":"buyer_ref","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Buyer Ref"}},{"name":"X-Agent-User-JWT","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Agent-User-Jwt"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssueOrderReviewInvitationsRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/orders":{"get":{"tags":["agent-api"],"summary":"Agent List Orders","description":"列出 Agent 创建的订单\n\n可以按商户或状态过滤","operationId":"agent_list_orders_agent_v1_orders_get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"merchant_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Merchant Id"}},{"name":"buyer_ref","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Buyer Ref"}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"default":20,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"X-Agent-User-JWT","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Agent-User-Jwt"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/orders/{order_id}/refund":{"post":{"tags":["agent-api"],"summary":"Agent Refund Order","description":"Proxy refund to admin refund API, but enforce agent ownership.","operationId":"agent_refund_order_agent_v1_orders__order_id__refund_post","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","title":"Order Id"}},{"name":"buyer_ref","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Buyer Ref"}},{"name":"X-Agent-User-JWT","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Agent-User-Jwt"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/orders/{order_id}/cancel":{"post":{"tags":["agent-api"],"summary":"Agent Cancel Order","description":"Cancel an order owned by the agent (defensive - no optional columns).","operationId":"agent_cancel_order_agent_v1_orders__order_id__cancel_post","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","title":"Order Id"}},{"name":"buyer_ref","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Buyer Ref"}},{"name":"X-Agent-User-JWT","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Agent-User-Jwt"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/orders/{order_id}/track":{"get":{"tags":["agent-api"],"summary":"Agent Track Order","description":"Return fulfillment tracking info for the order if owned by agent.","operationId":"agent_track_order_agent_v1_orders__order_id__track_get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","title":"Order Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/analytics/summary":{"get":{"tags":["agent-api"],"summary":"Agent Get Analytics","description":"获取 Agent 自己的分析数据\n\n包括：\n- 请求统计\n- 订单转化率\n- GMV\n- 热门商户","operationId":"agent_get_analytics_agent_v1_analytics_summary_get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":365,"default":30,"title":"Days"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/commissions":{"get":{"tags":["agent-api"],"summary":"Get Agent Commissions","description":"获取 Agent 的佣金列表\n\n返回所有与此 Agent 相关的订单佣金","operationId":"get_agent_commissions_agent_v1_commissions_get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"返回数量","default":50,"title":"Limit"},"description":"返回数量"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"偏移量","default":0,"title":"Offset"},"description":"偏移量"},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"状态过滤: pending, paid","title":"Status"},"description":"状态过滤: pending, paid"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v2/products/search":{"post":{"tags":["agent-v2"],"summary":"Search Products V2","operationId":"search_products_v2_agent_v2_products_search_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchProductsRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}]}},"/agent/v2/quotes/preview":{"post":{"tags":["agent-v2"],"summary":"Preview Quote V2","operationId":"preview_quote_v2_agent_v2_quotes_preview_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuotePreviewBody"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}]}},"/agent/v2/quotes/{quote_id}":{"get":{"tags":["agent-v2"],"summary":"Get Quote V2","operationId":"get_quote_v2_agent_v2_quotes__quote_id__get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"quote_id","in":"path","required":true,"schema":{"type":"string","title":"Quote Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v2/orders":{"post":{"tags":["agent-v2"],"summary":"Create Order V2","operationId":"create_order_v2_agent_v2_orders_post","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"X-Agent-User-JWT","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Agent-User-Jwt"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrderBody"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v2/orders/{order_id}":{"get":{"tags":["agent-v2"],"summary":"Get Order V2","operationId":"get_order_v2_agent_v2_orders__order_id__get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","title":"Order Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v2/payments/checkout-sessions":{"post":{"tags":["agent-v2"],"summary":"Create Checkout Session V2","operationId":"create_checkout_session_v2_agent_v2_payments_checkout_sessions_post","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"X-Agent-User-JWT","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Agent-User-Jwt"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCheckoutSessionBody"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v2/merchants/capabilities":{"get":{"tags":["agent-v2"],"summary":"List Merchant Capabilities V2","operationId":"list_merchant_capabilities_v2_agent_v2_merchants_capabilities_get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"merchant_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Merchant Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v2/orders/{order_id}/tracking":{"get":{"tags":["agent-v2"],"summary":"Track Order V2","operationId":"track_order_v2_agent_v2_orders__order_id__tracking_get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","title":"Order Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v2/orders/{order_id}/refunds":{"post":{"tags":["agent-v2"],"summary":"Create Refund V2","operationId":"create_refund_v2_agent_v2_orders__order_id__refunds_post","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","title":"Order Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundCreateBody"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/after-sales/cases":{"post":{"tags":["agent-after-sales"],"summary":"Create After Sales Case","description":"Create an after-sales case. This is the canonical entrypoint for:\n- refund_without_return (full or partial)\n- refund_with_return (RMA/label flow; label_url is a placeholder for now)","operationId":"create_after_sales_case_agent_v1_after_sales_cases_post","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"buyer_ref","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Buyer Ref"}},{"name":"X-Buyer-Ref","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Buyer-Ref"}},{"name":"X-Agent-User-JWT","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Agent-User-Jwt"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Payload"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/after-sales/cases/{case_id}":{"get":{"tags":["agent-after-sales"],"summary":"Get After Sales Case","operationId":"get_after_sales_case_agent_v1_after_sales_cases__case_id__get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"case_id","in":"path","required":true,"schema":{"type":"string","title":"Case Id"}},{"name":"buyer_ref","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Buyer Ref"}},{"name":"X-Buyer-Ref","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Buyer-Ref"}},{"name":"X-Agent-User-JWT","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Agent-User-Jwt"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/after-sales/orders/{order_id}/cases":{"get":{"tags":["agent-after-sales"],"summary":"List After Sales Cases For Order","operationId":"list_after_sales_cases_for_order_agent_v1_after_sales_orders__order_id__cases_get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","title":"Order Id"}},{"name":"buyer_ref","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Buyer Ref"}},{"name":"X-Buyer-Ref","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Buyer-Ref"}},{"name":"X-Agent-User-JWT","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Agent-User-Jwt"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/after-sales/cases/{case_id}/labels":{"post":{"tags":["agent-after-sales"],"summary":"Issue Return Label Placeholder","operationId":"issue_return_label_placeholder_agent_v1_after_sales_cases__case_id__labels_post","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"case_id","in":"path","required":true,"schema":{"type":"string","title":"Case Id"}},{"name":"buyer_ref","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Buyer Ref"}},{"name":"X-Buyer-Ref","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Buyer-Ref"}},{"name":"X-Agent-User-JWT","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Agent-User-Jwt"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/after-sales/cases/{case_id}/refund":{"post":{"tags":["agent-after-sales"],"summary":"Process Case Refund","operationId":"process_case_refund_agent_v1_after_sales_cases__case_id__refund_post","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"case_id","in":"path","required":true,"schema":{"type":"string","title":"Case Id"}},{"name":"buyer_ref","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Buyer Ref"}},{"name":"X-Buyer-Ref","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Buyer-Ref"}},{"name":"X-Agent-User-JWT","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Agent-User-Jwt"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/recommendations/roles/normalize":{"post":{"tags":["agent-recommendations"],"summary":"Normalize Role Hints","operationId":"normalize_role_hints_agent_v1_recommendations_roles_normalize_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NormalizeRolesRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}]}},"/agent/v1/recommendations/feed":{"post":{"tags":["agent-recommendations"],"summary":"Get Recommendations Feed","operationId":"get_recommendations_feed_agent_v1_recommendations_feed_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}]}},"/agent/v1/events/product-click":{"post":{"tags":["agent-events"],"summary":"Track Product Click","description":"Track a product click explicitly from Agent Gateway / UI.\n\n用途：\n- 当对话 UI 中用户点击某个搜索结果卡片时，由 Gateway 调用此接口；\n- 不依赖后端是否调用商品详情接口，便于覆盖更多点击场景。","operationId":"track_product_click_agent_v1_events_product_click_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductClickEvent"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}]}},"/agent/v1/events/offer-selected":{"post":{"tags":["agent-events"],"summary":"Track Offer Selected","operationId":"track_offer_selected_agent_v1_events_offer_selected_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfferInteractionEvent"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}]}},"/agent/v1/events/offer-cited":{"post":{"tags":["agent-events"],"summary":"Track Offer Cited","operationId":"track_offer_cited_agent_v1_events_offer_cited_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfferInteractionEvent"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}]}},"/agent/v1/outcomes":{"post":{"tags":["card-rail-outcomes"],"summary":"Report Card Rail Outcome","description":"Record what actually happened to one handoff.\n\nIdempotent on `recommendation_id`: a re-report corrects the row rather than appending, so the\nquestion this table exists to answer (\"of what we recommended, what completed\") stays a single\nscan instead of a windowing query.","operationId":"report_card_rail_outcome_agent_v1_outcomes_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardRailOutcome"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Report Card Rail Outcome Agent V1 Outcomes Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}]}},"/agent/v1/cards":{"post":{"tags":["agent-cards"],"summary":"Issue Card","operationId":"issue_card_agent_v1_cards_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardIssueRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Issue Card Agent V1 Cards Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}]}},"/agent/v1/cards/{card_id}":{"get":{"tags":["agent-cards"],"summary":"Get Card Status","operationId":"get_card_status_agent_v1_cards__card_id__get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"card_id","in":"path","required":true,"schema":{"type":"string","title":"Card Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Card Status Agent V1 Cards  Card Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/shop/v1/attribution/external-seed-links":{"post":{"tags":["Shopping Gateway"],"summary":"External Seed Links Endpoint","description":"Credentialed only: the gateway calls this with its internal key. Anonymous callers get\nthe same 401 every other agent route gives them — a mint is not a public read.","operationId":"external_seed_links_endpoint_agent_shop_v1_attribution_external_seed_links_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalSeedLinksRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response External Seed Links Endpoint Agent Shop V1 Attribution External Seed Links Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}]}},"/agent/shop/v1/dev/similar":{"get":{"tags":["Shopping Gateway"],"summary":"Debug Similar Products","description":"Dev-only endpoint to inspect similar products.","operationId":"debug_similar_products_agent_shop_v1_dev_similar_get","parameters":[{"name":"product_id","in":"query","required":true,"schema":{"type":"string","title":"Product Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":6,"title":"Limit"}},{"name":"strategy","in":"query","required":false,"schema":{"type":"string","default":"auto","title":"Strategy"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/shop/v1/dev/queue-status":{"get":{"tags":["Shopping Gateway"],"summary":"Debug Queue Status","description":"Dev-only endpoint to inspect the agent task queue state.","operationId":"debug_queue_status_agent_shop_v1_dev_queue_status_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Debug Queue Status Agent Shop V1 Dev Queue Status Get"}}}}}}},"/agent/shop/v1/creator/tasks":{"post":{"tags":["Shopping Gateway"],"summary":"Create Creator Task","description":"Async task creation endpoint for Creator Agent workloads.\n\nThis provides an explicit queue-based API:\n  - POST /agent/shop/v1/creator/tasks -> {task_id, status=\"queued\"}\n  - GET  /agent/shop/v1/creator/tasks/{task_id} -> status + result/error","operationId":"create_creator_task_agent_shop_v1_creator_tasks_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatorTaskCreateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatorTaskStatus"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/shop/v1/creator/tasks/{task_id}":{"get":{"tags":["Shopping Gateway"],"summary":"Get Creator Task Status","description":"Poll task status and (when ready) result for creator tasks.","operationId":"get_creator_task_status_agent_shop_v1_creator_tasks__task_id__get","parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"string","title":"Task Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatorTaskStatus"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/shop/v1/invoke":{"post":{"tags":["Shopping Gateway"],"summary":"Invoke Shop Operation","description":"Unified entrypoint for Shopping AI frontend & LLM agents.\n\nSupported operations:\n- find_products\n- get_product_detail\n- get_review_summary\n- list_sku_reviews\n- list_group_reviews\n- list_group_merchants\n- list_seller_feedback\n- list_review_entrypoints\n- resolve_review_intent\n- create_order       (demo-only)\n- create_payment_link (guest hosted checkout → /agent/v2/payments/checkout-sessions; no charge)\n- submit_payment     (demo-only)\n- find_similar_products","operationId":"invoke_shop_operation_agent_shop_v1_invoke_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShopGatewayRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Invoke Shop Operation Agent Shop V1 Invoke Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/shop/v1/review-media/{public_id}":{"get":{"tags":["Shopping Gateway"],"summary":"Get Review Media","description":"Serves imported review media by unguessable public_id.\nRequires exp+sig query params (HMAC) and applies IP rate limiting.","operationId":"get_review_media_agent_shop_v1_review_media__public_id__get","parameters":[{"name":"public_id","in":"path","required":true,"schema":{"type":"string","title":"Public Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/fulfillment/track/{order_id}":{"get":{"tags":["agent-fulfillment"],"summary":"Track Order Fulfillment","description":"Get fulfillment and tracking information for an order\n\nReturns:\n- Fulfillment status\n- Tracking number (if available)\n- Carrier information\n- Estimated delivery (if available)\n- Shipment timeline","operationId":"track_order_fulfillment_agent_v1_fulfillment_track__order_id__get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","title":"Order Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/fulfillment/orders/in-transit":{"get":{"tags":["agent-fulfillment"],"summary":"Get In Transit Orders","description":"Get all orders that are currently in transit\n\nUseful for agents to track active deliveries","operationId":"get_in_transit_orders_agent_v1_fulfillment_orders_in_transit_get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"merchant_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Merchant Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/metrics/summary":{"get":{"tags":["Agent Metrics V1"],"summary":"Get Metrics Summary V1","operationId":"get_metrics_summary_v1_agent_v1_metrics_summary_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Get Metrics Summary V1 Agent V1 Metrics Summary Get"}}}}}}},"/agent/v1/metrics/recent":{"get":{"tags":["Agent Metrics V1"],"summary":"Get Recent Activity V1","operationId":"get_recent_activity_v1_agent_v1_metrics_recent_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"default":20,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"agent_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Recent Activity V1 Agent V1 Metrics Recent Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/metrics/timeline":{"get":{"tags":["Agent Metrics V1"],"summary":"Get Metrics Timeline V1","operationId":"get_metrics_timeline_v1_agent_v1_metrics_timeline_get","parameters":[{"name":"hours","in":"query","required":false,"schema":{"type":"integer","default":24,"title":"Hours"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Metrics Timeline V1 Agent V1 Metrics Timeline Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"AgentAuthRequest":{"properties":{"agent_name":{"type":"string","title":"Agent Name"},"agent_email":{"type":"string","title":"Agent Email"},"company":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company","default":"Independent"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"}},"type":"object","required":["agent_name","agent_email"],"title":"AgentAuthRequest"},"AuthorizePaymentRequest":{"properties":{"mandate_id":{"type":"string","title":"Mandate Id","description":"Buyer mandate id"},"amount":{"type":"number","exclusiveMinimum":0.0,"title":"Amount","description":"Amount to authorize"},"currency":{"type":"string","minLength":1,"title":"Currency","description":"Currency (e.g., USD)"},"agent_user_ref":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent User Ref","description":"Agent-scoped user reference (opaque)"},"merchant_context":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Merchant Context","description":"Merchant context for allowlist checks"},"shipping_address_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Shipping Address Id","description":"Buyer address id (optional)"}},"type":"object","required":["mandate_id","amount","currency"],"title":"AuthorizePaymentRequest","description":"Agentic payment authorization request (PSP integration is not wired yet)."},"AuthorizePaymentResponse":{"properties":{"authorization_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization Token"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At"},"requires_user_confirmation":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Requires User Confirmation"},"confirm_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Confirm Url"}},"type":"object","title":"AuthorizePaymentResponse"},"AuthorizedSignal":{"properties":{"signal_type":{"type":"string","title":"Signal Type"},"actor":{"additionalProperties":true,"type":"object","title":"Actor"},"proof":{"additionalProperties":true,"type":"object","title":"Proof"}},"type":"object","required":["signal_type","actor","proof"],"title":"AuthorizedSignal"},"BeautyExtension":{"properties":{"skin_type":{"type":"string","enum":["oily","dry","combo","sensitive","normal","unknown"],"title":"Skin Type","default":"unknown"},"barrier_status":{"type":"string","enum":["strong","impaired","unknown"],"title":"Barrier Status","default":"unknown"},"concerns":{"items":{"type":"string","enum":["acne","closed_comedones","aging","dark_spots","redness","rough_texture","dryness","oil_control","unknown"]},"type":"array","title":"Concerns"},"sensitive_skin":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Sensitive Skin"},"routine_preferences":{"$ref":"#/components/schemas/BeautyRoutinePreferences"}},"type":"object","title":"BeautyExtension"},"BeautyRoutinePreferences":{"properties":{"split_am_pm":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Split Am Pm","default":true}},"type":"object","title":"BeautyRoutinePreferences"},"BriefAgentRef":{"properties":{"agent_id":{"type":"string","title":"Agent Id"},"partner_app_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Partner App Id"},"integration_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Integration Id"}},"type":"object","required":["agent_id"],"title":"BriefAgentRef"},"BriefAppliedRule":{"properties":{"rule_id":{"type":"string","title":"Rule Id"},"reason":{"type":"string","title":"Reason"}},"type":"object","required":["rule_id","reason"],"title":"BriefAppliedRule"},"BriefAssumption":{"properties":{"id":{"type":"string","title":"Id"},"text":{"type":"string","title":"Text"},"confidence":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Confidence"}},"type":"object","required":["id","text","confidence"],"title":"BriefAssumption"},"BriefAvailabilityConstraint":{"properties":{"in_stock_only":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"In Stock Only","default":true}},"type":"object","title":"BriefAvailabilityConstraint"},"BriefBudgetConstraint":{"properties":{"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency"},"max":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Max"}},"type":"object","title":"BriefBudgetConstraint"},"BriefBuildRequest":{"properties":{"raw_query":{"type":"string","title":"Raw Query"},"answers":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Answers"},"market":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Market"},"locale":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Locale"},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency"},"telemetry":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Telemetry"}},"type":"object","required":["raw_query"],"title":"BriefBuildRequest"},"BriefBuildResponse":{"properties":{"status":{"type":"string","const":"success","title":"Status","default":"success"},"confidence":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Confidence"},"brief":{"$ref":"#/components/schemas/ShoppingBriefV0"}},"type":"object","required":["confidence","brief"],"title":"BriefBuildResponse"},"BriefClarifyRequest":{"properties":{"raw_query":{"type":"string","title":"Raw Query"},"partial_brief":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Partial Brief"},"market":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Market"},"locale":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Locale"},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency"}},"type":"object","required":["raw_query"],"title":"BriefClarifyRequest"},"BriefClarifyResponse":{"properties":{"status":{"type":"string","const":"success","title":"Status","default":"success"},"suggested_vertical":{"type":"string","const":"beauty","title":"Suggested Vertical","default":"beauty"},"missing_fields":{"items":{"type":"string"},"type":"array","title":"Missing Fields"},"questions":{"items":{"$ref":"#/components/schemas/BriefQuestion"},"type":"array","title":"Questions"}},"type":"object","title":"BriefClarifyResponse"},"BriefCompatibilityRequest":{"properties":{"brief":{"$ref":"#/components/schemas/ShoppingBriefV0"},"candidate_items":{"items":{"$ref":"#/components/schemas/CompatibilityCandidateItem"},"type":"array","title":"Candidate Items"}},"type":"object","required":["brief","candidate_items"],"title":"BriefCompatibilityRequest"},"BriefCompatibilityResponse":{"properties":{"status":{"type":"string","const":"success","title":"Status","default":"success"},"results":{"items":{"$ref":"#/components/schemas/CompatibilityResult"},"type":"array","title":"Results"}},"type":"object","required":["results"],"title":"BriefCompatibilityResponse"},"BriefConstraints":{"properties":{"budget":{"$ref":"#/components/schemas/BriefBudgetConstraint"},"availability":{"$ref":"#/components/schemas/BriefAvailabilityConstraint"},"merchants":{"$ref":"#/components/schemas/BriefMerchantsConstraint"}},"type":"object","title":"BriefConstraints"},"BriefEvidence":{"properties":{"retrieved_at":{"type":"string","format":"date-time","title":"Retrieved At"},"retrieval_sources":{"items":{"$ref":"#/components/schemas/BriefEvidenceSource"},"type":"array","title":"Retrieval Sources"},"applied_rules":{"items":{"$ref":"#/components/schemas/BriefAppliedRule"},"type":"array","title":"Applied Rules"}},"type":"object","required":["retrieved_at"],"title":"BriefEvidence"},"BriefEvidenceSource":{"properties":{"type":{"type":"string","title":"Type"},"source":{"type":"string","title":"Source"},"captured_at":{"type":"string","format":"date-time","title":"Captured At"},"details":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Details"}},"type":"object","required":["type","source","captured_at"],"title":"BriefEvidenceSource"},"BriefExtensions":{"properties":{"beauty":{"anyOf":[{"$ref":"#/components/schemas/BeautyExtension"},{"type":"null"}]}},"type":"object","title":"BriefExtensions"},"BriefMarket":{"properties":{"market":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Market"},"locale":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Locale"},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency"}},"type":"object","title":"BriefMarket"},"BriefMerchantsConstraint":{"properties":{"allowed_merchant_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Allowed Merchant Ids"}},"type":"object","title":"BriefMerchantsConstraint"},"BriefProposedItem":{"properties":{"role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Role"},"quantity":{"type":"integer","minimum":1.0,"title":"Quantity","default":1},"standard_product_ref":{"$ref":"#/components/schemas/StandardProductRef"}},"type":"object","required":["standard_product_ref"],"title":"BriefProposedItem"},"BriefQuestion":{"properties":{"id":{"type":"string","title":"Id"},"text":{"type":"string","title":"Text"},"type":{"type":"string","enum":["number","single_choice","multi_choice","text"],"title":"Type"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unit"},"choices":{"anyOf":[{"items":{"$ref":"#/components/schemas/BriefQuestionChoice"},"type":"array"},{"type":"null"}],"title":"Choices"}},"type":"object","required":["id","text","type"],"title":"BriefQuestion"},"BriefQuestionChoice":{"properties":{"value":{"type":"string","title":"Value"},"label":{"type":"string","title":"Label"}},"type":"object","required":["value","label"],"title":"BriefQuestionChoice"},"BriefRawIntent":{"properties":{"text":{"type":"string","title":"Text"},"lang":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lang"},"captured_at":{"type":"string","format":"date-time","title":"Captured At"}},"type":"object","required":["text","captured_at"],"title":"BriefRawIntent"},"BriefTelemetry":{"properties":{"trace_id":{"type":"string","title":"Trace Id"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Request Id"}},"type":"object","required":["trace_id"],"title":"BriefTelemetry"},"BuyerContext":{"properties":{"customer_email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Customer Email"},"customer_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Customer Name"},"shipping_address":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Shipping Address"},"buyer_ref":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Buyer Ref"},"agent_user_ref":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent User Ref"}},"type":"object","title":"BuyerContext"},"BuyerRefMergeRequest":{"properties":{"source_buyer_ref":{"type":"string","title":"Source Buyer Ref"},"target_buyer_ref":{"type":"string","title":"Target Buyer Ref"}},"type":"object","required":["source_buyer_ref","target_buyer_ref"],"title":"BuyerRefMergeRequest"},"CardIssueRequest":{"properties":{"merchant_domain":{"type":"string","maxLength":255,"minLength":4,"title":"Merchant Domain"},"checkout_id":{"type":"string","maxLength":255,"minLength":1,"title":"Checkout Id"},"recommendation_id":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Recommendation Id"}},"additionalProperties":false,"type":"object","required":["merchant_domain","checkout_id"],"title":"CardIssueRequest"},"CardRailOutcome":{"properties":{"recommendation_id":{"type":"string","maxLength":64,"minLength":1,"title":"Recommendation Id"},"outcome":{"type":"string","title":"Outcome"},"recommendation_set_id":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Recommendation Set Id"},"trace_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Trace Id"},"click_id":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Click Id"},"merchant_domain":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Merchant Domain"},"product_key":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Product Key"},"variant_id":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Variant Id"},"rail":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Rail"},"quoted_item_total":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Quoted Item Total"},"quoted_grand_total":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Quoted Grand Total"},"quoted_currency":{"anyOf":[{"type":"string","maxLength":8},{"type":"null"}],"title":"Quoted Currency"},"quoted_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Quoted At"},"spec_expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Spec Expires At"},"actual_item_total":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Actual Item Total"},"actual_grand_total":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Actual Grand Total"},"actual_currency":{"anyOf":[{"type":"string","maxLength":8},{"type":"null"}],"title":"Actual Currency"},"failure_reason":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Failure Reason"},"latency_ms":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Latency Ms"},"auth_outcome":{"anyOf":[{"type":"string","maxLength":48},{"type":"null"}],"title":"Auth Outcome"},"reported_by":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Reported By"},"occurred_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Occurred At"}},"type":"object","required":["recommendation_id","outcome"],"title":"CardRailOutcome","description":"One handoff's result, as the acting agent saw it.\n\nDeliberately NOT including `agent_id`: it is stamped from the authenticated context. An agent\nthat could name itself in the body could attribute its own failures to a competitor, and this\ntable is meant to be evidence."},"CheckoutIntentItem":{"properties":{"product_id":{"type":"string","title":"Product Id","description":"Platform product id"},"variant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Variant Id","description":"Platform variant id (preferred when available)"},"sku":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sku"},"merchant_id":{"type":"string","title":"Merchant Id","description":"Merchant id"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"quantity":{"type":"integer","minimum":1.0,"title":"Quantity","default":1},"unit_price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Unit Price"},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency"},"image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Url"}},"type":"object","required":["product_id","merchant_id"],"title":"CheckoutIntentItem"},"CheckoutRefundBody":{"properties":{"amount":{"anyOf":[{"type":"number","exclusiveMinimum":0.0},{"type":"null"}],"title":"Amount"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason"},"restore_inventory":{"type":"boolean","title":"Restore Inventory","default":true},"idempotency_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency Key"}},"type":"object","title":"CheckoutRefundBody"},"CheckoutReturnBody":{"properties":{"api_version":{"anyOf":[{"type":"string","maxLength":16},{"type":"null"}],"title":"Api Version","default":"2025-10"},"limit":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Limit","default":20}},"type":"object","title":"CheckoutReturnBody"},"CommerceCheckoutItem":{"properties":{"product_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Product Id"},"variant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Variant Id"},"canonical_product_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Canonical Product Id"},"canonical_variant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Canonical Variant Id"},"sku":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sku"},"quantity":{"type":"integer","maximum":20.0,"minimum":1.0,"title":"Quantity","default":1},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"unit_price":{"anyOf":[{"type":"number","exclusiveMinimum":0.0},{"type":"null"}],"title":"Unit Price"},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency"}},"type":"object","title":"CommerceCheckoutItem"},"CommerceShippingAddress":{"properties":{"name":{"type":"string","minLength":1,"title":"Name"},"address_line1":{"type":"string","minLength":1,"title":"Address Line1"},"city":{"type":"string","minLength":1,"title":"City"},"postal_code":{"type":"string","minLength":1,"title":"Postal Code"},"country":{"type":"string","maxLength":2,"minLength":2,"title":"Country"},"address_line2":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address Line2"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone"}},"type":"object","required":["name","address_line1","city","postal_code","country"],"title":"CommerceShippingAddress"},"CompatibilityCandidateItem":{"properties":{"merchant_id":{"type":"string","title":"Merchant Id"},"platform":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Platform"},"product_id":{"type":"string","title":"Product Id"},"variant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Variant Id"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Price"},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency"},"in_stock":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"In Stock"},"orderable":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Orderable"},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Tags"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata"}},"type":"object","required":["merchant_id","product_id"],"title":"CompatibilityCandidateItem"},"CompatibilityResult":{"properties":{"candidate":{"$ref":"#/components/schemas/StandardProductRef"},"fit_score":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Fit Score"},"reasons":{"items":{"type":"string"},"type":"array","title":"Reasons"},"required_changes":{"items":{"type":"string"},"type":"array","title":"Required Changes"},"risk_tags":{"items":{"type":"string"},"type":"array","title":"Risk Tags"},"evidence":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Evidence"}},"type":"object","required":["candidate","fit_score"],"title":"CompatibilityResult"},"CompleteAcpCheckoutRequest":{"properties":{"payment_data":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Payment Data"},"payment_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Payment Token"},"idempotency_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency Key"}},"type":"object","title":"CompleteAcpCheckoutRequest"},"CreateAcpCheckoutRequest":{"properties":{"items":{"items":{"$ref":"#/components/schemas/CheckoutIntentItem"},"type":"array","title":"Items"},"shipping_address":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Shipping Address"},"customer_email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Customer Email"},"pvt_click_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pvt Click Id","description":"Attribution click id to thread through the ACP session"},"pvt_surface":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pvt Surface","description":"Origin surface (e.g. chatgpt)"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source"},"store_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Store Id","description":"Connected store_id to check out against (overrides primary store)"},"platform":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Platform","description":"Connected store platform to check out against, e.g. 'wix' (overrides primary store; store_id wins if both given)"}},"type":"object","required":["items"],"title":"CreateAcpCheckoutRequest"},"CreateCheckoutIntentRequest":{"properties":{"items":{"items":{"$ref":"#/components/schemas/CheckoutIntentItem"},"type":"array","title":"Items"},"return_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Return Url"},"order_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Order Id"},"quote_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Quote Id"},"buyer_ref":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Buyer Ref"},"agent_user_ref":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent User Ref"},"brief_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brief Id"},"brief_schema_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brief Schema Version"},"requested_scopes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Requested Scopes"},"job_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Id"},"market":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Market"},"locale":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Locale"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source"},"customer_email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Customer Email"},"shipping_address":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Shipping Address"}},"type":"object","required":["items"],"title":"CreateCheckoutIntentRequest"},"CreateCheckoutSessionBody":{"properties":{"order_id":{"type":"string","title":"Order Id"},"return_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Return Url"},"buyer_ref":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Buyer Ref"},"requested_scopes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Requested Scopes"},"market":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Market"},"locale":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Locale"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source"},"customer_email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Customer Email"},"shipping_address":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Shipping Address"},"request_context":{"anyOf":[{"$ref":"#/components/schemas/RequestContext"},{"type":"null"}]}},"type":"object","required":["order_id"],"title":"CreateCheckoutSessionBody"},"CreateCommerceCheckoutRequest":{"properties":{"merchant_id":{"type":"string","minLength":1,"title":"Merchant Id"},"interaction_id":{"type":"string","minLength":1,"title":"Interaction Id"},"customer_email":{"type":"string","format":"email","title":"Customer Email"},"customer_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Customer Name"},"buyer_ref":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Buyer Ref"},"brief_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brief Id"},"brief_schema_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brief Schema Version"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source"},"currency":{"type":"string","maxLength":8,"minLength":3,"title":"Currency","default":"USD"},"preferred_psp":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Preferred Psp"},"idempotency_key":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Idempotency Key"},"shipping_address":{"$ref":"#/components/schemas/CommerceShippingAddress"},"items":{"items":{"$ref":"#/components/schemas/CommerceCheckoutItem"},"type":"array","title":"Items"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata"}},"type":"object","required":["merchant_id","interaction_id","customer_email","shipping_address","items"],"title":"CreateCommerceCheckoutRequest"},"CreateDraftPackRequest":{"properties":{"merchant_id":{"type":"string","title":"Merchant Id"},"pack_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pack Id"},"session_id":{"type":"string","title":"Session Id"},"language":{"type":"string","title":"Language","default":"en"},"geo":{"$ref":"#/components/schemas/Geo"},"surface":{"type":"string","title":"Surface","default":"unknown"},"recommendations":{"items":{"$ref":"#/components/schemas/RecommendationItem"},"type":"array","title":"Recommendations"}},"type":"object","required":["merchant_id","session_id","geo","recommendations"],"title":"CreateDraftPackRequest"},"CreateOrderBody":{"properties":{"quote_id":{"type":"string","title":"Quote Id"},"buyer_context":{"$ref":"#/components/schemas/BuyerContext"},"request_context":{"anyOf":[{"$ref":"#/components/schemas/RequestContext"},{"type":"null"}]},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata"},"preferred_psp":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Preferred Psp"},"selected_payment_offer_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Selected Payment Offer Id"},"payment_method_evidence":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Payment Method Evidence"},"idempotency_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency Key"}},"type":"object","required":["quote_id","buyer_context"],"title":"CreateOrderBody"},"CreateOrderRequest":{"properties":{"merchant_id":{"type":"string","title":"Merchant Id"},"customer_email":{"type":"string","title":"Customer Email"},"customer_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Customer Name"},"quote_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Quote Id"},"brief_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brief Id"},"brief_schema_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brief Schema Version"},"discount_codes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Discount Codes"},"selected_delivery_option":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Selected Delivery Option"},"items":{"items":{"$ref":"#/components/schemas/OrderItem"},"type":"array","title":"Items"},"shipping_address":{"$ref":"#/components/schemas/ShippingAddress"},"currency":{"type":"string","title":"Currency","default":"USD"},"agent_session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Session Id"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata"},"preferred_psp":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Preferred Psp"},"selected_payment_offer_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Selected Payment Offer Id"},"payment_method_evidence":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Payment Method Evidence"},"idempotency_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency Key"}},"type":"object","required":["merchant_id","customer_email","items","shipping_address"],"title":"CreateOrderRequest","description":"创建订单请求"},"CreatorTaskCreateRequest":{"properties":{"operation":{"type":"string","title":"Operation"},"payload":{"additionalProperties":true,"type":"object","title":"Payload"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Request Id"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id"}},"type":"object","required":["operation","payload"],"title":"CreatorTaskCreateRequest","description":"Request body for async creator tasks.\n\n- operation / payload / metadata mirror ShopGatewayRequest\n- request_id: optional idempotency key supplied by caller\n- session_id: optional explicit session identifier; when omitted,\n  the gateway derives a session id from metadata and payload."},"CreatorTaskStatus":{"properties":{"task_id":{"type":"string","title":"Task Id"},"status":{"type":"string","title":"Status"},"result":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Result"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"}},"type":"object","required":["task_id","status"],"title":"CreatorTaskStatus"},"DebugConfig":{"properties":{"includeMapping":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Includemapping"},"includeFilterReasons":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Includefilterreasons"}},"type":"object","title":"DebugConfig"},"DiversityConfig":{"properties":{"domainCapPerRole":{"anyOf":[{"type":"integer","maximum":50.0,"minimum":1.0},{"type":"null"}],"title":"Domaincapperrole"},"domainCapGlobal":{"anyOf":[{"type":"integer","maximum":200.0,"minimum":1.0},{"type":"null"}],"title":"Domaincapglobal"},"dedupe":{"anyOf":[{"type":"string","enum":["global","perRole"]},{"type":"null"}],"title":"Dedupe"}},"type":"object","title":"DiversityConfig"},"EvidencePointer":{"properties":{"type":{"type":"string","title":"Type"},"ref":{"additionalProperties":true,"type":"object","title":"Ref"}},"type":"object","required":["type"],"title":"EvidencePointer"},"ExternalSeedLinkCandidate":{"properties":{"external_seed_id":{"type":"string","maxLength":128,"minLength":1,"title":"External Seed Id"},"destination_url":{"type":"string","maxLength":2048,"minLength":1,"title":"Destination Url"},"external_product_id":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"External Product Id"},"canonical_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Canonical Url"},"market":{"anyOf":[{"type":"string","maxLength":16},{"type":"null"}],"title":"Market"},"tool":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Tool"},"utm_template":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Utm Template"},"domain":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Domain"},"attached_product_key":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Attached Product Key"},"attached_variant_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Attached Variant Id"},"seller_ref":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Seller Ref"},"seed_kind":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Seed Kind"},"variant_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Variant Id"},"seed_data":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Seed Data"}},"type":"object","required":["external_seed_id","destination_url"],"title":"ExternalSeedLinkCandidate","description":"One card the gateway built itself and wants attributed. Field names are the seed row's."},"ExternalSeedLinksRequest":{"properties":{"market":{"anyOf":[{"type":"string","maxLength":16},{"type":"null"}],"title":"Market"},"tool":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Tool"},"candidates":{"items":{"$ref":"#/components/schemas/ExternalSeedLinkCandidate"},"type":"array","maxItems":50,"minItems":1,"title":"Candidates"}},"type":"object","required":["candidates"],"title":"ExternalSeedLinksRequest"},"FeedRequest":{"properties":{"market":{"type":"string","enum":["US","JP"],"title":"Market"},"locale":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Locale"},"requestId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Requestid"},"roleIds":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Roleids"},"roleHints":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Rolehints"},"maxOffersPerRole":{"anyOf":[{"type":"integer","maximum":10.0,"minimum":1.0},{"type":"null"}],"title":"Maxoffersperrole"},"maxTotalOffers":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":1.0},{"type":"null"}],"title":"Maxtotaloffers"},"diversity":{"anyOf":[{"$ref":"#/components/schemas/DiversityConfig"},{"type":"null"}]},"context":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Context"},"debug":{"anyOf":[{"$ref":"#/components/schemas/DebugConfig"},{"type":"null"}]},"resolve":{"anyOf":[{"type":"string","enum":["none","inline","deferred"]},{"type":"null"}],"title":"Resolve"}},"type":"object","required":["market"],"title":"FeedRequest"},"GenerateDraftPackRequest":{"properties":{"merchant_id":{"type":"string","title":"Merchant Id"},"session_id":{"type":"string","title":"Session Id"},"language":{"type":"string","title":"Language","default":"en"},"geo":{"$ref":"#/components/schemas/Geo"},"surface":{"type":"string","title":"Surface","default":"unknown"},"platform":{"type":"string","title":"Platform","default":"shopify"},"limit":{"type":"integer","title":"Limit","default":3},"platform_product_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Platform Product Ids"}},"type":"object","required":["merchant_id","session_id","geo"],"title":"GenerateDraftPackRequest"},"Geo":{"properties":{"country":{"type":"string","maxLength":2,"minLength":2,"title":"Country"},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Postal Code"},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"City"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State"}},"type":"object","required":["country"],"title":"Geo"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"IssueOrderReviewInvitationsRequest":{"properties":{"platform_product_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Platform Product Id"},"variant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Variant Id"},"ttl_seconds":{"type":"integer","maximum":604800.0,"minimum":300.0,"title":"Ttl Seconds","default":86400}},"type":"object","title":"IssueOrderReviewInvitationsRequest"},"NextAction":{"properties":{"type":{"type":"string","title":"Type"},"redirect_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Redirect Url"},"qr_code_data":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Qr Code Data"}},"type":"object","required":["type"],"title":"NextAction","description":"Next action for 3DS or additional verification"},"NormalizeRolesRequest":{"properties":{"roleHints":{"items":{"type":"string"},"type":"array","minItems":1,"title":"Rolehints"},"maxSuggestions":{"anyOf":[{"type":"integer","maximum":10.0,"minimum":0.0},{"type":"null"}],"title":"Maxsuggestions"},"market":{"anyOf":[{"type":"string","enum":["US","JP"]},{"type":"null"}],"title":"Market"}},"type":"object","required":["roleHints"],"title":"NormalizeRolesRequest"},"OfferInteractionEvent":{"properties":{"merchant_id":{"type":"string","title":"Merchant Id"},"offer_id":{"type":"string","title":"Offer Id"},"quote_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Quote Id"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id"},"geo":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Geo"},"surface":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Surface"},"adapter":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Adapter"},"risk_tier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Risk Tier"},"idempotency_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency Key"}},"type":"object","required":["merchant_id","offer_id"],"title":"OfferInteractionEvent","description":"Minimal event payload emitted by gateways/UIs when an offer is selected or cited.\n\nThis is intentionally metadata-only (no PII, no payment credentials)."},"OfferPreflightRequest":{"properties":{"quote_id":{"type":"string","title":"Quote Id"},"merchant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Merchant Id"},"shipping_address":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Shipping Address"},"brief_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brief Id"},"brief_schema_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brief Schema Version"}},"type":"object","required":["quote_id"],"title":"OfferPreflightRequest"},"OrderItem":{"properties":{"product_id":{"type":"string","title":"Product Id"},"product_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Product Title"},"variant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Variant Id"},"variant_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Variant Title"},"sku":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sku"},"quantity":{"type":"integer","title":"Quantity"},"unit_price":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Unit Price"},"subtotal":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Subtotal"}},"type":"object","required":["product_id","quantity"],"title":"OrderItem","description":"订单项（单个产品）"},"PaymentIntentRequest":{"properties":{"preferred_psps":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Preferred Psps"}},"type":"object","title":"PaymentIntentRequest"},"PaymentMethod":{"properties":{"type":{"type":"string","title":"Type","description":"card, bank_transfer, wallet"},"token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token","description":"Payment token from PSP (e.g., Stripe token)"},"card_last4":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Card Last4","description":"Last 4 digits of card"},"brand":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brand","description":"Card brand (visa, mastercard)"}},"type":"object","required":["type"],"title":"PaymentMethod","description":"Payment method details"},"PaymentRequest":{"properties":{"order_id":{"type":"string","title":"Order Id","description":"Order ID to create payment for"},"payment_method":{"$ref":"#/components/schemas/PaymentMethod"},"return_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Return Url","description":"URL for 3DS redirect callback"},"idempotency_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency Key","description":"Prevent duplicate payments"},"save_payment_method":{"type":"boolean","title":"Save Payment Method","description":"Save for future use","default":false},"expected_amount":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Expected Amount","description":"Client-expected order total (major units) for drift detection"},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency","description":"Client-expected currency for drift detection"},"quote_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Quote Id","description":"Quote id the client priced against (telemetry / drift detection)"}},"type":"object","required":["order_id","payment_method"],"title":"PaymentRequest","description":"Unified payment request"},"PaymentResponse":{"properties":{"status":{"type":"string","title":"Status"},"payment_id":{"type":"string","title":"Payment Id"},"payment_intent_id":{"type":"string","title":"Payment Intent Id"},"client_secret":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Client Secret"},"amount":{"type":"number","title":"Amount"},"currency":{"type":"string","title":"Currency"},"psp_used":{"type":"string","title":"Psp Used"},"psp":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Psp"},"payment_action":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Payment Action"},"commerce_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Commerce Path"},"execution_policy":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Execution Policy"},"legacy_or_fallback":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Legacy Or Fallback"},"validation_authority":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Validation Authority"},"next_action":{"anyOf":[{"$ref":"#/components/schemas/NextAction"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"},"created_at":{"type":"string","title":"Created At"}},"type":"object","required":["status","payment_id","payment_intent_id","amount","currency","psp_used","created_at"],"title":"PaymentResponse","description":"Unified payment response"},"PivotPaymentContext":{"properties":{"psp":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Psp"},"payment_method_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Payment Method Type"},"card_network":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Card Network"},"issuer_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Issuer Name"},"wallet_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Wallet Type"},"installment_provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Installment Provider"}},"type":"object","title":"PivotPaymentContext"},"ProductClickEvent":{"properties":{"merchant_id":{"type":"string","title":"Merchant Id"},"platform":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Platform"},"platform_product_id":{"type":"string","title":"Platform Product Id"},"query":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Query"},"position":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Position"},"ranking_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ranking Score"},"quality_content_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Quality Content Score"},"quality_model_readiness":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Quality Model Readiness"},"event_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Event Type"}},"type":"object","required":["merchant_id","platform_product_id"],"title":"ProductClickEvent","description":"Lightweight click tracking payload for Agent / UI gateway."},"PromotionAllocation":{"properties":{"target_type":{"type":"string","enum":["line_item","shipping","order"],"title":"Target Type"},"target_id":{"type":"string","title":"Target Id"},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount"}},"type":"object","required":["target_type","target_id","amount"],"title":"PromotionAllocation"},"PromotionLine":{"properties":{"id":{"type":"string","title":"Id"},"source":{"type":"string","title":"Source","default":"store"},"source_ref":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Ref"},"discount_class":{"type":"string","enum":["product","order","shipping"],"title":"Discount Class"},"method":{"type":"string","enum":["automatic","code","app","manual_adjustment"],"title":"Method"},"label":{"type":"string","title":"Label"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"},"amount":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount"},"allocations":{"anyOf":[{"items":{"$ref":"#/components/schemas/PromotionAllocation"},"type":"array"},{"type":"null"}],"title":"Allocations"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata"}},"type":"object","required":["id","discount_class","method","label","amount"],"title":"PromotionLine"},"QuoteItemInput":{"properties":{"product_id":{"type":"string","title":"Product Id"},"variant_id":{"type":"string","title":"Variant Id"},"quantity":{"type":"integer","minimum":1.0,"title":"Quantity"}},"type":"object","required":["product_id","variant_id","quantity"],"title":"QuoteItemInput"},"QuoteLineItem":{"properties":{"product_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Product Id"},"variant_id":{"type":"string","title":"Variant Id"},"quantity":{"type":"integer","title":"Quantity"},"unit_price_original":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Unit Price Original"},"unit_price_effective":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Unit Price Effective"},"line_discount_total":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Line Discount Total"},"compare_at_savings":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Compare At Savings","default":"0"}},"type":"object","required":["variant_id","quantity","unit_price_original","unit_price_effective","line_discount_total"],"title":"QuoteLineItem"},"QuoteOfferRef":{"properties":{"offer_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Offer Id"},"product_id":{"type":"string","title":"Product Id"},"variant_id":{"type":"string","title":"Variant Id"},"quantity":{"type":"integer","minimum":1.0,"title":"Quantity","default":1}},"type":"object","required":["product_id","variant_id"],"title":"QuoteOfferRef"},"QuotePreviewBody":{"properties":{"merchant_id":{"type":"string","title":"Merchant Id"},"offer_refs":{"items":{"$ref":"#/components/schemas/QuoteOfferRef"},"type":"array","title":"Offer Refs"},"discount_codes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Discount Codes"},"buyer_context":{"anyOf":[{"$ref":"#/components/schemas/BuyerContext"},{"type":"null"}]},"selected_delivery_option":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Selected Delivery Option"},"payment_context":{"anyOf":[{"$ref":"#/components/schemas/PivotPaymentContext"},{"type":"null"}]},"request_context":{"anyOf":[{"$ref":"#/components/schemas/RequestContext"},{"type":"null"}]},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata"}},"type":"object","required":["merchant_id","offer_refs"],"title":"QuotePreviewBody"},"QuotePreviewRequest":{"properties":{"merchant_id":{"type":"string","title":"Merchant Id"},"items":{"items":{"$ref":"#/components/schemas/QuoteItemInput"},"type":"array","title":"Items"},"discount_codes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Discount Codes"},"customer_email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Customer Email"},"shipping_address":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Shipping Address"},"selected_delivery_option":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Selected Delivery Option"},"payment_context":{"anyOf":[{"$ref":"#/components/schemas/PivotPaymentContext"},{"type":"null"}]},"brief_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brief Id"},"brief_schema_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brief Schema Version"}},"type":"object","required":["merchant_id","items"],"title":"QuotePreviewRequest"},"QuotePreviewResponse":{"properties":{"quote_id":{"type":"string","title":"Quote Id"},"expires_at":{"type":"string","format":"date-time","title":"Expires At"},"engine":{"type":"string","enum":["shopify_rest_checkout","shopify_storefront_cart"],"title":"Engine"},"engine_ref":{"type":"string","title":"Engine Ref"},"checkout_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Checkout Url"},"currency":{"type":"string","title":"Currency"},"presentment_currency":{"type":"string","title":"Presentment Currency"},"charge_currency":{"type":"string","title":"Charge Currency"},"settlement_currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Settlement Currency"},"pricing":{"$ref":"#/components/schemas/QuotePricing"},"availability_status":{"type":"string","enum":["available_confirmed","available_estimated","low_stock_confirmed","unavailable_confirmed","unknown_requires_validation","stale_requires_refresh"],"title":"Availability Status","default":"available_confirmed"},"available_quantity":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Available Quantity"},"is_final":{"type":"boolean","title":"Is Final","default":true},"source_updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Source Updated At"},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings"},"promotion_lines":{"items":{"$ref":"#/components/schemas/PromotionLine"},"type":"array","title":"Promotion Lines"},"discount_evidence":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Discount Evidence"},"payment_offer_evidence":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Payment Offer Evidence"},"payment_pricing":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Payment Pricing"},"savings_presentation":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Savings Presentation"},"line_items":{"items":{"$ref":"#/components/schemas/QuoteLineItem"},"type":"array","title":"Line Items"},"delivery_options":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Delivery Options"},"debug_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Debug Id"},"attempts":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Attempts"},"brief_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brief Id"},"brief_schema_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brief Schema Version"}},"type":"object","required":["quote_id","expires_at","engine","engine_ref","currency","presentment_currency","charge_currency","pricing","promotion_lines","line_items"],"title":"QuotePreviewResponse"},"QuotePricing":{"properties":{"subtotal":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Subtotal"},"discount_total":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Discount Total"},"shipping_fee":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Shipping Fee"},"tax":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Tax"},"total":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Total"}},"type":"object","required":["subtotal","discount_total","shipping_fee","tax","total"],"title":"QuotePricing"},"RecommendationClaim":{"properties":{"claim":{"type":"string","title":"Claim"},"confidence":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Confidence"},"evidence":{"items":{"$ref":"#/components/schemas/EvidencePointer"},"type":"array","title":"Evidence"}},"type":"object","required":["claim","confidence"],"title":"RecommendationClaim"},"RecommendationDisclosures":{"properties":{"sponsored":{"type":"boolean","title":"Sponsored","default":false},"affiliate":{"type":"boolean","title":"Affiliate","default":false},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes"}},"type":"object","title":"RecommendationDisclosures"},"RecommendationItem":{"properties":{"offer_id":{"type":"string","title":"Offer Id"},"title":{"type":"string","title":"Title"},"narrative":{"type":"string","title":"Narrative"},"claims":{"items":{"$ref":"#/components/schemas/RecommendationClaim"},"type":"array","title":"Claims"},"authorized_signals":{"items":{"$ref":"#/components/schemas/AuthorizedSignal"},"type":"array","title":"Authorized Signals"},"disclosures":{"$ref":"#/components/schemas/RecommendationDisclosures"}},"type":"object","required":["offer_id","title","narrative"],"title":"RecommendationItem"},"RecordPaymentOfferEvidenceRequest":{"properties":{"order_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Order Id"},"quote_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Quote Id"},"merchant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Merchant Id"},"selected_payment_offer_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Selected Payment Offer Id"},"payment_method_evidence":{"additionalProperties":true,"type":"object","title":"Payment Method Evidence"},"payment_offer_evidence":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Payment Offer Evidence"},"surface":{"type":"string","title":"Surface","default":"checkout"},"event_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Event Type"},"idempotency_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency Key"}},"type":"object","title":"RecordPaymentOfferEvidenceRequest","description":"Display-only payment-offer evidence captured after checkout UI state changes."},"RefundCreateBody":{"properties":{"amount":{"anyOf":[{"type":"number","exclusiveMinimum":0.0},{"type":"null"}],"title":"Amount"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason"},"restore_inventory":{"type":"boolean","title":"Restore Inventory","default":true},"idempotency_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency Key"}},"type":"object","title":"RefundCreateBody"},"RequestContext":{"properties":{"tenant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tenant Id"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Request Id"},"channel":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Channel"},"locale":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Locale"},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country"},"delivery_region":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Delivery Region"},"user_constraints":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"User Constraints"},"consent_context":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Consent Context"}},"type":"object","title":"RequestContext"},"SearchProductsRequest":{"properties":{"merchant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Merchant Id"},"merchant_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Merchant Ids"},"search_all_merchants":{"type":"boolean","title":"Search All Merchants","default":false},"query":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Query"},"market":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Market"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"},"catalog_surface":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Catalog Surface"},"min_price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Min Price"},"max_price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Max Price"},"in_stock_only":{"type":"boolean","title":"In Stock Only","default":false},"limit":{"type":"integer","maximum":200.0,"minimum":1.0,"title":"Limit","default":20},"offset":{"type":"integer","minimum":0.0,"title":"Offset","default":0},"allow_external_seed":{"type":"boolean","title":"Allow External Seed","default":true},"external_seed_only":{"type":"boolean","title":"External Seed Only","default":false},"allow_stale_cache":{"type":"boolean","title":"Allow Stale Cache","default":true},"external_seed_strategy":{"type":"string","title":"External Seed Strategy","default":"legacy"},"fast_mode":{"type":"boolean","title":"Fast Mode","default":false},"payment_context":{"anyOf":[{"$ref":"#/components/schemas/PivotPaymentContext"},{"type":"null"}]},"request_context":{"anyOf":[{"$ref":"#/components/schemas/RequestContext"},{"type":"null"}]}},"type":"object","title":"SearchProductsRequest"},"ShippingAddress":{"properties":{"name":{"type":"string","title":"Name"},"address_line1":{"type":"string","title":"Address Line1"},"address_line2":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address Line2"},"city":{"type":"string","title":"City"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State"},"postal_code":{"type":"string","title":"Postal Code"},"country":{"type":"string","title":"Country"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone"}},"type":"object","required":["name","address_line1","city","postal_code","country"],"title":"ShippingAddress","description":"收货地址"},"ShopGatewayRequest":{"properties":{"operation":{"type":"string","title":"Operation"},"payload":{"additionalProperties":true,"type":"object","title":"Payload"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata"}},"type":"object","required":["operation","payload"],"title":"ShopGatewayRequest"},"ShoppingBriefV0":{"properties":{"schema_version":{"type":"string","const":"0.1.0","title":"Schema Version","default":"0.1.0"},"brief_id":{"type":"string","title":"Brief Id"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"agent":{"$ref":"#/components/schemas/BriefAgentRef"},"market":{"$ref":"#/components/schemas/BriefMarket"},"raw_intent":{"$ref":"#/components/schemas/BriefRawIntent"},"vertical":{"type":"string","const":"beauty","title":"Vertical","default":"beauty"},"constraints":{"$ref":"#/components/schemas/BriefConstraints"},"proposed_items":{"items":{"$ref":"#/components/schemas/BriefProposedItem"},"type":"array","title":"Proposed Items"},"assumptions":{"items":{"$ref":"#/components/schemas/BriefAssumption"},"type":"array","title":"Assumptions"},"evidence":{"$ref":"#/components/schemas/BriefEvidence"},"risk_tags":{"items":{"type":"string"},"type":"array","title":"Risk Tags"},"telemetry":{"$ref":"#/components/schemas/BriefTelemetry"},"extensions":{"$ref":"#/components/schemas/BriefExtensions"}},"type":"object","required":["brief_id","created_at","agent","market","raw_intent","evidence","telemetry"],"title":"ShoppingBriefV0"},"StandardProductRef":{"properties":{"merchant_id":{"type":"string","title":"Merchant Id"},"platform":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Platform"},"product_id":{"type":"string","title":"Product Id"},"variant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Variant Id"}},"type":"object","required":["merchant_id","product_id"],"title":"StandardProductRef"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"APIKeyHeader":{"type":"apiKey","in":"header","name":"X-Checkout-Token"},"HTTPBearer":{"type":"http","scheme":"bearer"},"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key"}}},"security":[{"ApiKeyAuth":[]}],"servers":[{"url":"https://api.pivota.cc"}]}