{"openapi":"3.2.0","jsonSchemaDialect":"https://spec.openapis.org/oas/3.2/dialect/2025-09-17","info":{"title":"VialAPI Partner API","summary":"Source-safe catalog, ordering, customer, event, and webhook APIs for partner storefronts","version":"1.7.0","contact":{"name":"VialAPI Integrations","url":"https://vialapi.com/developers"},"license":{"name":"Proprietary","identifier":"LicenseRef-VialAPI-Proprietary"},"description":"Fulfillment middleware API for partner brands. Authenticate with your tenant API key as a bearer token. Order creation is asynchronous: every live order is invoiced and held until VialAPI confirms full cleared payment; only then can fulfillment submission begin. New orders return 202 Accepted and progress via webhooks and polling.\n\n## Sandbox mode\nKeys prefixed `vial_test_` create sandboxed orders: they run the full lifecycle against a fake supplier (shipped after ~2 minutes, delivered after ~4), are excluded from billing and reports, carry `\"livemode\": false` in webhook payloads, and are purged after 30 days.\n\n## Webhook event catalog\nAlways-on order lifecycle events: `order.created`, `order.status_changed`, `order.approved`, `order.label_created`, `order.shipped`, `order.delivered`, and `order.cancelled`, plus `order.awaiting_payment` for every new payment-gated live order. Opt-in events (configure via `PUT /api/v1/webhook-endpoint`): `order.needs_review`, `inventory.low_stock`. Test deliveries use `ping`. Every delivery uses Standard Webhooks headers: `webhook-id`, `webhook-timestamp`, and `webhook-signature: v1,<base64 HMAC-SHA256>` over `{id}.{timestamp}.{exact raw body}` using the decoded key bytes from the `whsec_<base64>` endpoint secret. Legacy `X-VialAPI-*` headers remain additive during the v1 migration window. Delivery is at least once and ordering is not guaranteed.\n\n## Scopes\n`orders:read`, `orders:validate`, `orders:write`, `catalog:read`, `customers:read`, `webhooks:manage`. An empty scope list grants no access; every credential must carry explicit least-privilege scopes.\n\n## Versioning and deprecation\nThe `/api/v1` path is the compatibility boundary. Additive fields and operations may ship within v1. A breaking change requires a new path version. A deprecated operation is marked in this document and will return standards-based `Deprecation` and `Sunset` headers for at least 180 days before removal."},"externalDocs":{"description":"Authoritative machine-readable contract","url":"https://vialapi.com/api/v1/openapi.json"},"servers":[{"url":"https://vialapi.com","description":"Production and sandbox behavior are selected by the API key prefix"}],"tags":[{"name":"Catalog","description":"Published product identity, prices, and order availability"},{"name":"Orders","description":"Dry-run validation and the complete order lifecycle"},{"name":"Customers","description":"Tenant-scoped customer directory"},{"name":"Webhooks","description":"Endpoint configuration, delivery testing, and event history"},{"name":"System","description":"Public service readiness"}],"security":[{"bearerAuth":[]}],"x-key-modes":{"live":{"prefix":"vial_live_","behavior":"Creates live, financially governed orders. New orders may remain awaiting payment before fulfillment."},"test":{"prefix":"vial_test_","behavior":"Creates isolated sandbox orders against the fake supplier; excluded from billing and operational reports and purged after 30 days."},"credentials":"Raw keys are revealed once through an approved secure channel and never appear in this document. There are no magic sandbox SKUs; use the catalog returned for the key."},"x-sandbox-certification":{"orderScenarioField":"metadata.vialapiSandboxScenario","orderScenarios":["standard","needs_review","provider_failure","shipped","delivered"],"virtualWebhookRetryReceiver":"https://sandbox-webhooks.vialapi.example/retry-once","virtualReceiverPolicy":"Accepted only when configured by a test credential and intercepted only for customer-free synthetic webhook test events. It deterministically returns 503 with Retry-After."},"x-pagination-policy":{"ordering":"Orders, customers, and events use createdAt DESC + id DESC. Catalog, products, and inventory use createdAt ASC + id ASC.","cursor":"Opaque authenticated snapshot cursor bound to the resource, principal, channel, filters, direction, createdAt, and immutable ID tie-breaker. Never construct or inspect it.","limits":{"/api/v1/orders":{"default":50,"maximum":200},"/api/v1/customers":{"default":50,"maximum":200},"/api/v1/events":{"default":50,"maximum":200},"/api/v1/catalog":{"default":500,"maximum":500},"/api/v1/products":{"default":500,"maximum":500},"/api/v1/inventory":{"default":500,"maximum":500},"/api/v1/shipping-methods":{"pagination":false}},"malformedLimit":"A missing limit uses the endpoint default. A positive integer above the maximum is clamped; zero, negative, fractional, or non-numeric values return 400 invalid_request.","concurrentChanges":"The first page freezes a snapshot. Later inserts are excluded from that traversal; deleting the prior cursor row does not invalidate the next page.","termination":"nextCursor is null on the final page; invalid, tampered, expired-context, or cross-filter cursors return 400 invalid_cursor"},"x-idempotency-policy":{"header":"Idempotency-Key","requiredOperations":["POST /api/v1/orders","PATCH /api/v1/orders/{id}","POST /api/v1/orders/{id}/cancel","PUT /api/v1/webhook-endpoint","POST /api/v1/webhook-endpoint/test","MCP order_create"],"format":"1-200 characters: letters, numbers, dot, underscore, colon, slash, or hyphen; first character must be alphanumeric","scope":"authenticated principal + bound sales channel + operation + key; credential rotation does not create a new command namespace","retentionHours":48,"identicalReplay":"Returns the stored status code and response body","changedPayload":"409 idempotency_conflict","concurrentRequest":"409 idempotency_in_progress with Retry-After and idempotencyExpiresAt","replayHeader":"Idempotency-Replayed is true for a stored replay and false for the first completed execution","externalOrderId":"Also deduplicates within a sales channel. A duplicate external order ID returns the existing order with HTTP 200."},"x-versioning-policy":{"pathVersion":"v1","contractVersion":"1.7.0","responseHeader":"VialAPI-Version","compatibility":"Backward-compatible additions remain in v1 and advance the semantic contract version","breakingChanges":"A breaking change requires a new path version","deprecationNoticeDays":180,"deprecationHeaders":["Deprecation","Sunset","Link"],"sunsetBehavior":"A sunset date never disables a route automatically. Usage is escalated and removal requires an explicit major-version release after migration evidence.","currentlyDeprecatedOperations":[]},"x-error-catalog":{"unauthorized":{"status":401,"retryable":false},"forbidden":{"status":403,"retryable":false},"certification_required":{"status":403,"retryable":false},"not_found":{"status":404,"retryable":false},"conflict":{"status":409,"retryable":false},"ambiguous_external_order_id":{"status":409,"retryable":false},"idempotency_conflict":{"status":409,"retryable":false},"idempotency_in_progress":{"status":409,"retryable":true,"defaultRetryAfterSeconds":2},"invalid_request":{"status":400,"retryable":false},"invalid_signature":{"status":401,"retryable":false},"invalid_cursor":{"status":400,"retryable":false},"invalid_idempotency_key":{"status":400,"retryable":false},"idempotency_key_required":{"status":400,"retryable":false},"payload_too_large":{"status":413,"retryable":false},"request_timeout":{"status":408,"retryable":true,"defaultRetryAfterSeconds":1},"unsupported_media_type":{"status":415,"retryable":false},"invalid_attribution":{"status":422,"retryable":false},"rate_limited":{"status":429,"retryable":true,"defaultRetryAfterSeconds":1},"needs_review":{"status":422,"retryable":false},"pricing_blocked":{"status":422,"retryable":false},"order_locked":{"status":409,"retryable":false},"payment_recorded":{"status":409,"retryable":false},"invalid_transition":{"status":409,"retryable":false},"submission_in_progress":{"status":409,"retryable":true,"defaultRetryAfterSeconds":2},"no_webhook_endpoint":{"status":409,"retryable":false},"webhook_not_configured":{"status":503,"retryable":true,"defaultRetryAfterSeconds":60},"webhook_configuration_conflict":{"status":409,"retryable":true,"defaultRetryAfterSeconds":1},"invalid_url":{"status":400,"retryable":false},"account_unavailable":{"status":409,"retryable":false},"channel_unavailable":{"status":409,"retryable":false},"channel_mismatch":{"status":409,"retryable":false},"provider_unavailable":{"status":503,"retryable":true,"defaultRetryAfterSeconds":15},"assistant_unavailable":{"status":503,"retryable":true,"defaultRetryAfterSeconds":15},"server_error":{"status":500,"retryable":true,"defaultRetryAfterSeconds":5}},"x-order-status-matrix":[{"status":"received","meaning":"Accepted internally before asynchronous processing begins","terminal":false},{"status":"processing","meaning":"Validated and queued; may be waiting on payment","terminal":false},{"status":"awaiting_fulfillment","meaning":"Released and waiting for or accepted by fulfillment","terminal":false},{"status":"needs_review","meaning":"Created order requires operator resolution","terminal":false},{"status":"awaiting_tracking","meaning":"Fulfillment accepted; tracking is not available yet","terminal":false},{"status":"shipped","meaning":"Carrier tracking is available","terminal":false},{"status":"delivered","meaning":"Carrier or fulfillment reports delivery","terminal":true},{"status":"cancelled","meaning":"Order was cancelled and applicable financials reversed","terminal":true},{"status":"failed","meaning":"Order cannot progress without corrective action or replacement","terminal":true}],"x-webhook-event-matrix":[{"event":"ping","payloadVersion":1,"delivery":"explicit_test","modes":["test"],"purpose":"Endpoint and signature verification"},{"event":"order.created","payloadVersion":1,"delivery":"always","modes":["test","live"],"purpose":"Order was durably accepted by VialAPI"},{"event":"order.awaiting_payment","payloadVersion":1,"delivery":"when_applicable","modes":["test","live"],"purpose":"Order is held at the payment gate"},{"event":"order.status_changed","payloadVersion":1,"delivery":"always","modes":["test","live"],"purpose":"Order moved to a new lifecycle status"},{"event":"order.approved","payloadVersion":1,"delivery":"always","modes":["test","live"],"purpose":"Fulfillment accepted the order"},{"event":"order.label_created","payloadVersion":1,"delivery":"always","modes":["test","live"],"purpose":"A shipping label was created"},{"event":"order.shipped","payloadVersion":1,"delivery":"always","modes":["test","live"],"purpose":"Shipment departed and tracking is available"},{"event":"order.delivered","payloadVersion":1,"delivery":"always","modes":["test","live"],"purpose":"Shipment delivery was confirmed"},{"event":"order.cancelled","payloadVersion":1,"delivery":"always","modes":["test","live"],"purpose":"Order was cancelled"},{"event":"order.needs_review","payloadVersion":1,"delivery":"opt_in","modes":["test","live"],"purpose":"Order requires human review"},{"event":"inventory.low_stock","payloadVersion":1,"delivery":"opt_in","modes":["test","live"],"purpose":"Published inventory crossed its low-stock threshold"}],"x-webhook-retry-policy":{"guarantee":"at_least_once","ordering":"not_guaranteed","attempts":16,"maxManualReplays":10,"backoff":"Exponential from 30 seconds with deterministic ±25% jitter, capped at 12 hours; valid Retry-After up to 24 hours is honored","timeoutSeconds":15,"maxResponseBytes":65536,"success":"Any HTTP 2xx response","retryable":"Transport failures, 408, 409, 425, 429, and 5xx","terminal":"3xx is never followed; permanent 4xx and exhausted retries enter the dead letter state","deliveryIdentity":"webhook-id remains stable across retries and manual replay; receivers must deduplicate it","observability":"GET /api/v1/events exposes normalized last-attempt detail; receiver bodies and secrets are not retained"},"x-webhook-signature-test-vector":{"algorithm":"HMAC-SHA256","secret":"whsec_AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8=","webhookId":"evt_test_01JEXAMPLE","timestamp":"1784380800","body":"{\"id\":\"evt_test_01JEXAMPLE\",\"event\":\"ping\",\"payloadVersion\":1,\"createdAt\":\"2026-07-18T13:20:00.000Z\",\"livemode\":false,\"data\":{\"synthetic\":true,\"message\":\"VialAPI webhook certification event\"},\"synthetic\":true,\"message\":\"VialAPI webhook certification event\"}","signedPayload":"evt_test_01JEXAMPLE.1784380800.{\"id\":\"evt_test_01JEXAMPLE\",\"event\":\"ping\",\"payloadVersion\":1,\"createdAt\":\"2026-07-18T13:20:00.000Z\",\"livemode\":false,\"data\":{\"synthetic\":true,\"message\":\"VialAPI webhook certification event\"},\"synthetic\":true,\"message\":\"VialAPI webhook certification event\"}","signature":"v1,IyV7EUDfuw073Vgy4W+8SVw0LiVe7ny7DJkzZnLWWHc=","legacySignature":"sha256=4ca23d8d07684f8ab24d2c97735ff2b2405655f1e0da2d48c3693b90fd1331f0","note":"Synthetic public vector only; never configure this secret on an actual endpoint"},"paths":{"/api/v1/orders":{"post":{"summary":"Create an order","description":"Persists, prices, and queues the order for supplier submission. Duplicate `externalOrderId` returns the existing order with 200. `lineItems[].sku` accepts the immutable `vialApiSku` or the deliberate `channelSku` returned by the catalog, case-insensitively. Send an a required `Idempotency-Key` header. Reuse the exact key and body after timeouts; keep `externalOrderId` as the business reference.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:/-]*$"},"description":"Required stable identity for this logical command. Identical retries replay; changed payloads conflict. Retained for 48 hours."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrderRequest"}}}},"responses":{"200":{"description":"Duplicate externalOrderId — existing order returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"},"examples":{"replay":{"summary":"Existing order returned safely","value":{"id":"ord_01JEXAMPLE000000000000000","externalOrderId":"AS-ORDER-1001","tenant":"atlas-supply","status":"processing","mode":"test","items":[{"sku":"PA-KPV-10MG","vialApiSku":"VIAL-KPV-10MG","channelSku":"PA-KPV-10MG","name":"KPV 10 mg","quantity":2,"unitPriceCents":4500,"lineTotalCents":9000,"currency":"USD"}],"pricing":{"productSubtotalCents":9000,"shippingCents":1200,"totalCents":10200,"currency":"USD"},"shipping":{"method":"ground","label":"Ground","chargeCents":1200},"fulfillment":{"status":null,"orderId":null,"orderNumber":null},"tracking":null,"review":null,"createdAt":"2026-07-18T12:00:00.000Z","updatedAt":"2026-07-18T12:00:00.000Z"}}}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"202":{"description":"Order accepted and queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"},"examples":{"accepted":{"summary":"Sandbox order accepted","value":{"id":"ord_01JEXAMPLE000000000000000","externalOrderId":"AS-ORDER-1001","tenant":"atlas-supply","status":"processing","mode":"test","items":[{"sku":"PA-KPV-10MG","vialApiSku":"VIAL-KPV-10MG","channelSku":"PA-KPV-10MG","name":"KPV 10 mg","quantity":2,"unitPriceCents":4500,"lineTotalCents":9000,"currency":"USD"}],"pricing":{"productSubtotalCents":9000,"shippingCents":1200,"totalCents":10200,"currency":"USD"},"shipping":{"method":"ground","label":"Ground","chargeCents":1200},"fulfillment":{"status":null,"orderId":null,"orderNumber":null},"tracking":null,"review":null,"createdAt":"2026-07-18T12:00:00.000Z","updatedAt":"2026-07-18T12:00:00.000Z"}}}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"408":{"description":"The request body exceeded the bounded read deadline; retry the same logical command safely","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"409":{"description":"Idempotency-Key conflict or still in progress","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"413":{"description":"The request body exceeds the documented byte limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"415":{"description":"Send identity-encoded application/json; compressed or non-JSON request bodies are not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"422":{"description":"The request was not created: an SKU is unmapped (`needs_review`) or pricing is unsafe (`pricing_blocked`). Pricing blockers include unpriced, below-floor, stale/missing required cost, currency mismatch, ambiguous overrides, and unapproved zero price.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"needsReview":{"summary":"No order created because a public SKU is unknown","value":{"error":"needs_review","message":"Unmapped SKU: UNKNOWN-SKU","requestId":"req_01JEXAMPLE","retryable":false,"unmappedSkus":["UNKNOWN-SKU"]}},"pricingBlocked":{"summary":"No order created because current pricing evidence is unsafe","value":{"error":"pricing_blocked","message":"The order could not be accepted because one or more lines are not safely priced","requestId":"req_01JEXAMPLE","retryable":false,"blockers":[{"code":"stale_cost","message":"The price is temporarily unavailable"}]}}}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Unexpected server failure; retry after Retry-After with the same idempotency key for writes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"A required provider or dependency is unavailable; retry after Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"operationId":"createOrder","tags":["Orders"],"x-required-scopes":["orders:write"],"x-rate-limit-policy":"orderWrite","x-key-modes":["test","live"],"x-idempotency-required":true},"get":{"summary":"List orders","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200},"description":"Page size; clamped to the endpoint maximum"},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from the previous page's nextCursor"}],"responses":{"200":{"description":"Paginated orders, newest first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrdersResponse"},"example":{"orders":[{"id":"ord_01JEXAMPLE000000000000000","externalOrderId":"AS-ORDER-1001","tenant":"atlas-supply","status":"processing","mode":"test","items":[{"sku":"PA-KPV-10MG","vialApiSku":"VIAL-KPV-10MG","channelSku":"PA-KPV-10MG","name":"KPV 10 mg","quantity":2,"unitPriceCents":4500,"lineTotalCents":9000,"currency":"USD"}],"pricing":{"productSubtotalCents":9000,"shippingCents":1200,"totalCents":10200,"currency":"USD"},"shipping":{"method":"ground","label":"Ground","chargeCents":1200},"fulfillment":{"status":null,"orderId":null,"orderNumber":null},"tracking":null,"review":null,"createdAt":"2026-07-18T12:00:00.000Z","updatedAt":"2026-07-18T12:00:00.000Z"}],"nextCursor":null}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Unexpected server failure; retry after Retry-After with the same idempotency key for writes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"A required provider or dependency is unavailable; retry after Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"operationId":"listOrders","tags":["Orders"],"description":"List orders visible to this storefront in stable newest-first order.","x-required-scopes":["orders:read"],"x-rate-limit-policy":"apiRead","x-key-modes":["test","live"],"x-pagination":{"sort":"createdAt DESC, id DESC","maximumPageSize":200,"snapshotStable":true}}},"/api/v1/orders/validate":{"post":{"summary":"Validate and price an order without creating it","description":"Resolves immutable VialAPI SKUs and channel aliases, applies the same pricing and shipping query used by creation, and makes no writes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateOrderRequest"}}}},"responses":{"200":{"description":"Validation result. Unknown or ambiguous SKUs return valid=false with issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderValidation"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"400":{"description":"The request shape is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"408":{"description":"The request body exceeded the bounded read deadline; retry the same logical command safely","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"413":{"description":"The request body exceeds the documented byte limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"415":{"description":"Send identity-encoded application/json; compressed or non-JSON request bodies are not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Unexpected server failure; retry after Retry-After with the same idempotency key for writes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"A required provider or dependency is unavailable; retry after Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"operationId":"validateOrder","tags":["Orders"],"x-required-scopes":["orders:validate"],"x-rate-limit-policy":"apiRead","x-key-modes":["test","live"]}},"/api/v1/orders/{id}":{"get":{"summary":"Get an order by VialAPI id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":240,"pattern":"^[A-Za-z0-9._:-]+$"}}],"responses":{"200":{"description":"Order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Unexpected server failure; retry after Retry-After with the same idempotency key for writes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"A required provider or dependency is unavailable; retry after Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"operationId":"getOrder","tags":["Orders"],"description":"Retrieve one source-safe order by its VialAPI ID.","x-required-scopes":["orders:read"],"x-rate-limit-policy":"apiRead","x-key-modes":["test","live"]},"patch":{"summary":"Edit an order before supplier submission","description":"Editable while the order is still `processing`/`needs_review` and not yet claimed for supplier submission. Provide any of `customer`, `shipTo`, `lineItems`, `shippingMethod`; omitted fields keep their current values. The merged order fully re-validates and re-prices exactly like intake.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":240,"pattern":"^[A-Za-z0-9._:-]+$"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:/-]*$"},"description":"Required stable identity for this logical command. Identical retries replay; changed payloads conflict. Retained for 48 hours."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditOrderRequest"}}}},"responses":{"200":{"description":"Updated, fully re-priced order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"408":{"description":"The request body exceeded the bounded read deadline; retry the same logical command safely","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"409":{"description":"Order locked — already submitted to the supplier or financially posted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"413":{"description":"The request body exceeds the documented byte limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"415":{"description":"Send identity-encoded application/json; compressed or non-JSON request bodies are not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"422":{"description":"Unmapped SKU","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Unexpected server failure; retry after Retry-After with the same idempotency key for writes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"A required provider or dependency is unavailable; retry after Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"operationId":"editOrder","tags":["Orders"],"x-required-scopes":["orders:write"],"x-rate-limit-policy":"orderWrite","x-key-modes":["test","live"],"x-idempotency-required":true}},"/api/v1/orders/{id}/cancel":{"post":{"summary":"Cancel an order","description":"State-machine-guarded and idempotent: cancelling a cancelled order returns 200 unchanged. Orders already submitted upstream are cancelled at the supplier; posted financials reverse automatically.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":240,"pattern":"^[A-Za-z0-9._:-]+$"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:/-]*$"},"description":"Required stable identity for this logical command. Identical retries replay; changed payloads conflict. Retained for 48 hours."}],"responses":{"200":{"description":"Cancelled order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"409":{"description":"Not cancellable from the current status (`{ error: \"invalid_transition\", status }`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Unexpected server failure; retry after Retry-After with the same idempotency key for writes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"502":{"description":"The supplier could not cancel; retry shortly","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"503":{"description":"A required provider or dependency is unavailable; retry after Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"operationId":"cancelOrder","tags":["Orders"],"x-required-scopes":["orders:write"],"x-rate-limit-policy":"orderWrite","x-key-modes":["test","live"],"x-idempotency-required":true}},"/api/v1/webhook-endpoint":{"get":{"summary":"Read your webhook endpoint configuration","description":"Requires the `webhooks:manage` scope.","responses":{"200":{"description":"Endpoint URL, event opt-ins, and whether a signing secret exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Unexpected server failure; retry after Retry-After with the same idempotency key for writes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"A required provider or dependency is unavailable; retry after Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"operationId":"getWebhookEndpoint","tags":["Webhooks"],"x-required-scopes":["webhooks:manage"],"x-rate-limit-policy":"apiRead","x-key-modes":["test","live"]},"put":{"summary":"Configure your webhook endpoint","description":"Set the HTTPS URL (null clears it) and optional event opt-ins. The signing secret is returned once per logical create/rotate command. An exact retry with the same Idempotency-Key replays the encrypted command response during the 48-hour idempotency window; it is never available from GET or a different command.","parameters":[{"name":"rotate","in":"query","required":false,"schema":{"type":"boolean"},"description":"true rotates the signing secret; both current and previous secrets sign deliveries during a 24-hour overlap"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:/-]*$"},"description":"Required stable identity for this logical command. Identical retries replay; changed payloads conflict. Retained for 48 hours."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":["string","null"],"description":"HTTPS endpoint; null disables deliveries"},"events":{"type":"object","additionalProperties":false,"properties":{"order.needs_review":{"type":"boolean"},"inventory.low_stock":{"type":"boolean"}}}}}}}},"responses":{"200":{"description":"Updated configuration (plus `secret` exactly once when minted)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"400":{"description":"Invalid URL or payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"408":{"description":"The request body exceeded the bounded read deadline; retry the same logical command safely","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"409":{"description":"A concurrent secret rotation changed the endpoint (`webhook_configuration_conflict`), or the idempotency key conflicts/is still in progress. Follow the error code and `Retry-After`.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body exceeds the documented byte limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"415":{"description":"Send identity-encoded application/json; compressed or non-JSON request bodies are not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Unexpected server failure; retry after Retry-After with the same idempotency key for writes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"A required provider or dependency is unavailable; retry after Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"operationId":"putWebhookEndpoint","tags":["Webhooks"],"x-required-scopes":["webhooks:manage"],"x-rate-limit-policy":"orderWrite","x-key-modes":["test","live"],"x-idempotency-required":true}},"/api/v1/webhook-endpoint/test":{"post":{"summary":"Send a deterministic signed scenario to your endpoint","description":"Emits a customer-free synthetic event without creating an order. The strict tenant-and-target budget prevents use as an arbitrary upstream status oracle; the response exposes only normalized outcome categories.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"scenario":{"type":"string","enum":["ping","order.created","order.awaiting_payment","order.status_changed","order.approved","order.needs_review","order.label_created","order.shipped","order.delivered","order.cancelled","inventory.low_stock"],"default":"ping"}}},"example":{"scenario":"order.shipped"}}}},"responses":{"200":{"description":"Delivery outcome","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTestResponse"},"example":{"category":"delivered","scenario":"order.shipped","eventId":"evt_01JEXAMPLE000000000000000","deliveryId":"evt_01JEXAMPLE000000000000000","nextRetryAt":null}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"408":{"description":"The request body exceeded the bounded read deadline; retry the same logical command safely","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"409":{"description":"No webhook URL is configured, or the idempotency key conflicts/is still in progress","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"413":{"description":"The request body exceeds the documented byte limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"415":{"description":"Send identity-encoded application/json; compressed or non-JSON request bodies are not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Unexpected server failure; retry after Retry-After with the same idempotency key for writes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"A required provider or dependency is unavailable; retry after Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"operationId":"testWebhookEndpoint","tags":["Webhooks"],"x-required-scopes":["webhooks:manage"],"x-rate-limit-policy":"orderWrite","x-key-modes":["test","live"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:/-]*$"},"description":"Required stable identity for this logical command. Identical retries replay; changed payloads conflict. Retained for 48 hours."}],"x-idempotency-required":true}},"/api/v1/shipping-methods":{"get":{"summary":"Active shipping methods for your tenant","description":"Charge preview for the `shippingMethod` key on order creation.","responses":{"200":{"description":"Shipping methods","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShippingMethodsResponse"},"example":{"shippingMethods":[{"key":"ground","label":"Ground","chargeCents":1200,"isDefault":true}]}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Unexpected server failure; retry after Retry-After with the same idempotency key for writes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"A required provider or dependency is unavailable; retry after Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"operationId":"listShippingMethods","tags":["Catalog"],"x-required-scopes":["catalog:read"],"x-rate-limit-policy":"apiRead","x-key-modes":["test","live"]}},"/api/v1/events":{"get":{"summary":"Webhook delivery history","description":"Requires `orders:read`. Cursor-paginated log of deliveries to your endpoint — event, status, attempt count, replay count, next retry, terminal timestamps, and a normalized last-attempt summary. Webhook payloads, response bodies, signing secrets, and network addresses are not returned.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200},"description":"Page size; clamped to the endpoint maximum"},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from the previous page's nextCursor"}],"responses":{"200":{"description":"Deliveries, newest first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventsResponse"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"400":{"description":"Invalid cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Unexpected server failure; retry after Retry-After with the same idempotency key for writes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"A required provider or dependency is unavailable; retry after Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"operationId":"listWebhookEvents","tags":["Webhooks"],"x-required-scopes":["orders:read"],"x-rate-limit-policy":"apiRead","x-key-modes":["test","live"],"x-pagination":{"sort":"createdAt DESC, id DESC","maximumPageSize":200,"snapshotStable":true}}},"/api/v1/orders/by-external-id/{externalOrderId}":{"get":{"summary":"Get an order by your external order id","parameters":[{"name":"externalOrderId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Unexpected server failure; retry after Retry-After with the same idempotency key for writes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"A required provider or dependency is unavailable; retry after Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"operationId":"getOrderByExternalId","tags":["Orders"],"description":"Recover an order using the storefront's external order ID after a timeout or uncertain retry.","x-required-scopes":["orders:read"],"x-rate-limit-policy":"apiRead","x-key-modes":["test","live"]}},"/api/v1/customers":{"get":{"summary":"List customers","description":"Returns active customers visible to this storefront, newest first. Customer records are tenant-scoped and never reveal another account or channel.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200},"description":"Page size; clamped to the endpoint maximum"},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from the previous page's nextCursor"}],"responses":{"200":{"description":"Cursor-paginated customer directory","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomersResponse"},"example":{"customers":[{"id":"cus_01JEXAMPLE000000000000000","name":"Morgan Lee","firstName":"Morgan","lastName":"Lee","company":"Atlas Supply Co.","email":"morgan.lee@example.com","phone":"+1-202-555-0142","tags":["wholesale"],"ordersCount":3,"lastOrderAt":"2026-07-17T16:30:00.000Z","defaultShipTo":{"recipientName":"Morgan Lee","address1":"100 Example Avenue","city":"Atlanta","state":"GA","postalCode":"30309","country":"US","residential":true},"createdAt":"2026-06-10T09:00:00.000Z"}],"nextCursor":null}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"400":{"description":"Invalid cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Unexpected server failure; retry after Retry-After with the same idempotency key for writes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"A required provider or dependency is unavailable; retry after Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"operationId":"listCustomers","tags":["Customers"],"x-required-scopes":["customers:read"],"x-rate-limit-policy":"apiRead","x-key-modes":["test","live"],"x-pagination":{"sort":"createdAt DESC, id DESC","maximumPageSize":200,"snapshotStable":true}}},"/api/v1/customers/{id}":{"get":{"summary":"Get a customer","description":"Returns one customer inside the credential's storefront boundary. Unknown and foreign IDs both return the same 404 response.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Customer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"},"example":{"id":"cus_01JEXAMPLE000000000000000","name":"Morgan Lee","firstName":"Morgan","lastName":"Lee","company":"Atlas Supply Co.","email":"morgan.lee@example.com","phone":"+1-202-555-0142","tags":["wholesale"],"ordersCount":3,"lastOrderAt":"2026-07-17T16:30:00.000Z","defaultShipTo":{"recipientName":"Morgan Lee","address1":"100 Example Avenue","city":"Atlanta","state":"GA","postalCode":"30309","country":"US","residential":true},"createdAt":"2026-06-10T09:00:00.000Z"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"404":{"description":"Customer not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Unexpected server failure; retry after Retry-After with the same idempotency key for writes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"A required provider or dependency is unavailable; retry after Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"operationId":"getCustomer","tags":["Customers"],"x-required-scopes":["customers:read"],"x-rate-limit-policy":"apiRead","x-key-modes":["test","live"]}},"/api/v1/catalog":{"get":{"summary":"Published, priced catalog for your account","description":"Supported. Returns only account-owned identifiers, the account price, explicit order eligibility, and a source-safe inventory state. `inventoryStatus` distinguishes confirmed stock, low stock, confirmation-required, and temporary unavailability. Supplier identifiers and exact inventory quantities are never part of this contract.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200},"description":"Page size; clamped to the endpoint maximum"},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from the previous page's nextCursor"}],"responses":{"200":{"description":"Published account catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogResponse"},"example":{"catalog":[{"sku":"PA-KPV-10MG","vialApiSku":"VIAL-KPV-10MG","channelSku":"PA-KPV-10MG","name":"KPV 10 mg","status":"active","priceCents":4500,"currency":"USD","tiers":[{"minQuantity":10,"unitPriceCents":4200}],"orderEligibility":"eligible","inventoryStatus":"stock_confirmation_required","inventoryConfirmedAt":null,"availability":"available_to_order"}],"nextCursor":null}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"400":{"description":"Invalid cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Unexpected server failure; retry after Retry-After with the same idempotency key for writes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"A required provider or dependency is unavailable; retry after Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"operationId":"listCatalog","tags":["Catalog"],"x-required-scopes":["catalog:read"],"x-rate-limit-policy":"apiRead","x-key-modes":["test","live"],"x-pagination":{"sort":"createdAt ASC, id ASC","maximumPageSize":500,"snapshotStable":true}}},"/api/v1/products":{"get":{"summary":"Your mapped product SKUs","description":"The authoritative order-ready SKU allowlist. Submit either `vialApiSku` or `channelSku`; matching is case-insensitive.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200},"description":"Page size; clamped to the endpoint maximum"},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from the previous page's nextCursor"}],"responses":{"200":{"description":"Mapped products","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductsResponse"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"400":{"description":"Invalid cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Unexpected server failure; retry after Retry-After with the same idempotency key for writes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"A required provider or dependency is unavailable; retry after Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"operationId":"listProducts","tags":["Catalog"],"x-required-scopes":["catalog:read"],"x-rate-limit-policy":"apiRead","x-key-modes":["test","live"],"x-pagination":{"sort":"createdAt ASC, id ASC","maximumPageSize":500,"snapshotStable":true}}},"/api/v1/inventory":{"get":{"summary":"Source-safe order availability","description":"For business-account tenants, returns the same account-owned, priced items as `/catalog`; `orderEligibility` answers whether the item may be submitted and `inventoryStatus` separately states what is known about stock. The deprecated `availability` field remains for v1 compatibility and is not a stock guarantee. Exact supplier inventory and supplier identifiers are never exposed.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200},"description":"Page size; clamped to the endpoint maximum"},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from the previous page's nextCursor"}],"responses":{"200":{"description":"Source-safe inventory page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryResponse"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"400":{"description":"Invalid cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}}},"429":{"description":"Rate limited; respect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"description":"Unexpected server failure; retry after Retry-After with the same idempotency key for writes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"A required provider or dependency is unavailable; retry after Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"VialAPI-Version":{"$ref":"#/components/headers/VialAPIVersion"},"VialAPI-Duration-Ms":{"$ref":"#/components/headers/DurationMs"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"operationId":"listInventory","tags":["Catalog"],"x-required-scopes":["catalog:read"],"x-rate-limit-policy":"apiRead","x-key-modes":["test","live"],"x-pagination":{"sort":"createdAt ASC, id ASC","maximumPageSize":500,"snapshotStable":true}}},"/api/health":{"get":{"summary":"Readiness probe","security":[],"responses":{"200":{"description":"Service is ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Readiness"}}},"headers":{}},"429":{"description":"Public readiness-check budget exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"Service is degraded or a required dependency is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Readiness"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"operationId":"getReadiness","tags":["System"],"description":"Read the public service readiness state and stable, non-sensitive reason codes.","x-required-scopes":[],"x-rate-limit-policy":"publicHealth","x-key-modes":[]}}},"webhooks":{"partnerEvent":{"post":{"operationId":"receiveVialApiWebhook","tags":["Webhooks"],"summary":"Receive a signed VialAPI event","description":"VialAPI sends this at-least-once request to the HTTPS URL configured by `PUT /api/v1/webhook-endpoint`. Ordering is not guaranteed. Decode the Base64 portion of the `whsec_` endpoint secret and verify the HMAC over `{webhook-id}.{webhook-timestamp}.{exact raw body}` before parsing JSON, reject timestamps outside five minutes, and deduplicate the stable `webhook-id`. Return any 2xx only after durable acceptance. During secret rotation, `webhook-signature` contains two space-delimited `v1,<base64>` values; accept a match against either configured secret.","security":[],"parameters":[{"name":"webhook-id","in":"header","required":true,"schema":{"type":"string"},"description":"Stable event identity across automatic retries and manual replay; use as the dedupe key"},{"name":"webhook-timestamp","in":"header","required":true,"schema":{"type":"string","pattern":"^[0-9]+$"},"description":"Unix timestamp in seconds included in the signed content"},{"name":"webhook-signature","in":"header","required":true,"schema":{"type":"string","pattern":"^v1,[A-Za-z0-9+/]+={0,2}( v1,[A-Za-z0-9+/]+={0,2})*$"},"description":"One or more space-delimited `v1,<base64 HMAC-SHA256>` values; multiple values support rotation overlap"},{"name":"X-VialAPI-Event","in":"header","required":false,"deprecated":true,"schema":{"type":"string"},"description":"Legacy additive routing header; prefer the signed body `event` field"},{"name":"X-VialAPI-Delivery","in":"header","required":false,"deprecated":true,"schema":{"type":"string"},"description":"Legacy alias for `webhook-id`"},{"name":"X-VialAPI-Timestamp","in":"header","required":false,"deprecated":true,"schema":{"type":"string","pattern":"^[0-9]+$"},"description":"Legacy alias for `webhook-timestamp`"},{"name":"X-VialAPI-Signature","in":"header","required":false,"deprecated":true,"schema":{"type":"string","pattern":"^sha256=[a-f0-9]{64}$"},"description":"Legacy HMAC over `{timestamp}.{exactRawBody}`; migrate to `webhook-signature`"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/PingWebhook"},{"$ref":"#/components/schemas/OrderWebhook"},{"$ref":"#/components/schemas/InventoryLowStockWebhook"}]},"examples":{"ping":{"value":{"id":"evt_test_01JEXAMPLE","event":"ping","payloadVersion":1,"createdAt":"2026-07-18T13:20:00.000Z","livemode":false,"data":{"synthetic":true,"message":"VialAPI webhook certification event"},"synthetic":true,"message":"VialAPI webhook certification event"}},"orderShipped":{"value":{"id":"evt_test_01JEXAMPLE","event":"order.shipped","payloadVersion":1,"createdAt":"2026-07-18T13:20:00.000Z","data":{"vialapiOrderId":"ord_01JEXAMPLE000000000000000","externalOrderId":"AS-ORDER-1001","status":"shipped","tracking":{"trackingNumber":"1Z999AA10123456784","service":"Ground","carrier":"UPS","trackingUrl":"https://www.ups.com/track?tracknum=1Z999AA10123456784","shippedAt":"2026-07-18T14:00:00.000Z"}},"vialapiOrderId":"ord_01JEXAMPLE000000000000000","externalOrderId":"AS-ORDER-1001","status":"shipped","livemode":false,"tracking":{"trackingNumber":"1Z999AA10123456784","service":"Ground","carrier":"UPS","trackingUrl":"https://www.ups.com/track?tracknum=1Z999AA10123456784","shippedAt":"2026-07-18T14:00:00.000Z"}}}}}}},"responses":{"200":{"description":"Event accepted"},"202":{"description":"Event durably queued for asynchronous handling"},"204":{"description":"Event accepted with no response body"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Tenant API key (`vial_live_...` or sandbox-only `vial_test_...`)"}},"schemas":{"Error":{"type":"object","additionalProperties":false,"required":["error","message","requestId","retryable"],"properties":{"error":{"type":"string","enum":["unauthorized","forbidden","certification_required","not_found","conflict","ambiguous_external_order_id","idempotency_conflict","idempotency_in_progress","invalid_request","invalid_signature","invalid_cursor","invalid_idempotency_key","idempotency_key_required","payload_too_large","request_timeout","unsupported_media_type","invalid_attribution","rate_limited","needs_review","pricing_blocked","order_locked","payment_recorded","invalid_transition","submission_in_progress","no_webhook_endpoint","webhook_not_configured","webhook_configuration_conflict","invalid_url","account_unavailable","channel_unavailable","channel_mismatch","provider_unavailable","assistant_unavailable","server_error"],"description":"Stable machine-readable error code"},"message":{"type":"string"},"requestId":{"type":"string","description":"Correlation id — include when contacting support"},"retryable":{"type":"boolean","description":"Whether the caller may retry after the Retry-After delay without changing the request"},"issues":{"type":"array","items":{"type":"object"},"description":"Validation issues (invalid_request only)"},"blockers":{"type":"array","items":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"description":"Source-safe commercial rule failures (pricing_blocked only)"},"unmappedSkus":{"type":"array","items":{"type":"string"},"description":"Unknown public SKU values (needs_review only)"},"status":{"type":"string","description":"Current resource status when relevant to the error"}}},"Order":{"type":"object","additionalProperties":false,"required":["id","externalOrderId","tenant","status","mode","items","pricing","shipping","fulfillment","tracking","review","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"externalOrderId":{"type":"string"},"tenant":{"type":"string"},"mode":{"type":"string","enum":["test","live"]},"items":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["sku","vialApiSku","channelSku","name","quantity","unitPriceCents","lineTotalCents","currency"],"properties":{"sku":{"type":"string","description":"Preferred public SKU for this credential family"},"vialApiSku":{"type":["string","null"],"description":"Immutable VialAPI product identity"},"channelSku":{"type":"string","description":"Deliberate storefront compatibility alias"},"name":{"type":["string","null"]},"quantity":{"type":"integer","minimum":1},"unitPriceCents":{"type":"integer","minimum":0},"lineTotalCents":{"type":"integer","minimum":0},"currency":{"type":"string","enum":["USD"]}}}},"status":{"type":"string","enum":["received","processing","awaiting_fulfillment","needs_review","awaiting_tracking","shipped","delivered","cancelled","failed"]},"pricing":{"type":"object","additionalProperties":false,"required":["productSubtotalCents","shippingCents","totalCents","currency"],"properties":{"productSubtotalCents":{"type":"integer"},"shippingCents":{"type":"integer"},"totalCents":{"type":"integer"},"currency":{"type":"string"}}},"shipping":{"type":"object","additionalProperties":false,"required":["method","label","chargeCents"],"properties":{"method":{"type":["string","null"]},"label":{"type":["string","null"]},"chargeCents":{"type":"integer"}}},"fulfillment":{"type":"object","additionalProperties":false,"required":["status","orderId","orderNumber"],"properties":{"status":{"type":["string","null"],"enum":[null,"processing","integration_error","cancelled","delivered","shipped","needs_review","fulfillment_error"]},"orderId":{"type":["string","null"]},"orderNumber":{"type":["string","null"]}}},"tracking":{"type":["object","null"],"additionalProperties":false,"properties":{"trackingNumber":{"type":"string"},"service":{"type":["string","null"]},"carrier":{"type":["string","null"]},"trackingUrl":{"type":["string","null"]},"shippedAt":{"type":["string","null"],"format":"date-time"}}},"review":{"description":"Review reasons keyed to your SKUs when the order needs attention; otherwise null","oneOf":[{"type":"null"},{"type":"string"},{"type":"array","maxItems":200,"items":{"$ref":"#/components/schemas/OrderReviewReason"}},{"type":"object","additionalProperties":false,"properties":{"unmappedSkus":{"type":"array","maxItems":200,"items":{"type":"string"}},"insufficientSkus":{"type":"array","maxItems":200,"items":{"type":"string"}},"reviewReasons":{"type":"array","maxItems":200,"items":{"$ref":"#/components/schemas/OrderReviewReason"}},"code":{"type":"string"},"sku":{"type":"string"},"requestedQuantity":{"type":"integer","minimum":1,"maximum":10000},"message":{"type":"string"}}}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"warnings":{"type":"array","items":{"type":"string"},"description":"Sandbox-only diagnostics; production orders never accept an unpriced line"},"payment":{"type":"object","additionalProperties":false,"description":"Present only for payment-gated storefronts (sprint 6.3): the order holds before supplier submission until payment is recorded. status: unpaid | paid.","properties":{"required":{"type":"boolean"},"status":{"type":"string","enum":["unpaid","paid"]}}}}},"OrderReviewReason":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","maxLength":100},"sku":{"type":"string"},"requestedQuantity":{"type":"integer","minimum":1,"maximum":10000},"message":{"type":"string"}}},"CreateOrderRequest":{"type":"object","additionalProperties":true,"x-unknown-field-policy":"strip","required":["externalOrderId","shipTo","lineItems"],"properties":{"externalOrderId":{"type":"string","maxLength":64,"description":"Your order id; used for idempotent deduplication"},"sourceCompany":{"type":"string","maxLength":120,"description":"Optional public source label for attribution; never changes tenant isolation"},"customer":{"type":"object","additionalProperties":true,"x-unknown-field-policy":"strip","properties":{"firstName":{"type":"string","maxLength":120},"lastName":{"type":"string","maxLength":120},"company":{"type":"string","maxLength":120},"email":{"type":"string","maxLength":254},"phone":{"type":"string","maxLength":32}}},"shipTo":{"type":"object","additionalProperties":true,"x-unknown-field-policy":"strip","required":["recipientName","address1","city","state","postalCode"],"properties":{"recipientName":{"type":"string","maxLength":140},"recipientCompany":{"type":"string","maxLength":140},"address1":{"type":"string","maxLength":200},"address2":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":100},"state":{"type":"string","maxLength":50},"postalCode":{"type":"string","maxLength":20},"country":{"type":"string","minLength":2,"maxLength":56,"default":"US"},"residential":{"type":"boolean","default":true}}},"lineItems":{"type":"array","minItems":1,"maxItems":200,"items":{"type":"object","additionalProperties":true,"x-unknown-field-policy":"strip","required":["sku","quantity"],"properties":{"sku":{"type":"string","maxLength":64,"description":"Public channel SKU returned by catalog, or the immutable vialApiSku; supplier identifiers are rejected"},"quantity":{"type":"integer","minimum":1,"maximum":10000}}}},"shippingMethod":{"type":"string","maxLength":64,"description":"Key of a configured shipping method; omitted = your default. Unknown keys are rejected."},"metadata":{"type":"object","maxProperties":50,"additionalProperties":true,"x-max-json-bytes":16384,"description":"Free-form metadata; at most 50 keys and 16 KiB when UTF-8 encoded after serialization. Test keys may set vialapiSandboxScenario to one of the documented fixed outcomes. Live keys ignore that certification control."}}},"ValidateOrderRequest":{"type":"object","additionalProperties":true,"x-unknown-field-policy":"strip","required":["lineItems"],"properties":{"lineItems":{"type":"array","minItems":1,"maxItems":200,"items":{"type":"object","additionalProperties":true,"x-unknown-field-policy":"strip","required":["sku","quantity"],"properties":{"sku":{"type":"string","maxLength":64,"description":"Public channel SKU returned by catalog, or the immutable vialApiSku; supplier identifiers are rejected"},"quantity":{"type":"integer","minimum":1,"maximum":10000}}}},"shippingMethod":{"type":"string","maxLength":64,"description":"Key of a configured shipping method; omitted = your default. Unknown keys are rejected."}}},"OrderValidation":{"type":"object","additionalProperties":false,"required":["contractVersion","valid","issues","lines","shipping","totals"],"properties":{"contractVersion":{"type":"string","const":"2026-07-18"},"valid":{"type":"boolean"},"issues":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["code","sku","message"],"properties":{"code":{"type":"string","enum":["unknown_sku","ambiguous_sku","unavailable","unpriced","invalid_quantity"]},"sku":{"type":"string"},"message":{"type":"string"}}}},"lines":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["sku","vialApiSku","channelSku","name","orderEligibility","inventoryStatus","inventoryConfirmedAt","availability","quantity","unitPriceCents","lineTotalCents","currency"],"properties":{"sku":{"type":"string","description":"Preferred public SKU for this credential family"},"vialApiSku":{"type":["string","null"],"description":"Immutable VialAPI product identity"},"channelSku":{"type":"string","description":"Deliberate storefront compatibility alias"},"name":{"type":["string","null"]},"quantity":{"type":"integer","minimum":1},"unitPriceCents":{"type":"integer","minimum":0},"lineTotalCents":{"type":"integer","minimum":0},"currency":{"type":"string","enum":["USD"]},"orderEligibility":{"type":"string","enum":["eligible"]},"inventoryStatus":{"type":"string","enum":["in_stock","low_stock","stock_confirmation_required","temporarily_unavailable"]},"inventoryConfirmedAt":{"type":["string","null"],"format":"date-time"},"availability":{"type":"string","enum":["available_to_order"],"deprecated":true,"description":"Compatibility alias for order eligibility; not an inventory guarantee."}}}},"shipping":{"type":"object","additionalProperties":false,"required":["methodKey","label","chargeCents"],"properties":{"methodKey":{"type":"string"},"label":{"type":"string"},"chargeCents":{"type":"integer","minimum":0}}},"totals":{"type":"object","additionalProperties":false,"required":["productSubtotalCents","shippingCents","totalCents","currency"],"properties":{"productSubtotalCents":{"type":"integer"},"shippingCents":{"type":"integer"},"totalCents":{"type":"integer"},"currency":{"type":"string"}}}}},"EditOrderRequest":{"type":"object","additionalProperties":false,"minProperties":1,"description":"All fields optional; omitted fields keep their current values","properties":{"customer":{"type":"object","additionalProperties":true,"x-unknown-field-policy":"strip","properties":{"firstName":{"type":"string","maxLength":120},"lastName":{"type":"string","maxLength":120},"company":{"type":"string","maxLength":120},"email":{"type":"string","maxLength":254},"phone":{"type":"string","maxLength":32}}},"shipTo":{"type":"object","additionalProperties":true,"x-unknown-field-policy":"strip","required":["recipientName","address1","city","state","postalCode"],"properties":{"recipientName":{"type":"string","maxLength":140},"recipientCompany":{"type":"string","maxLength":140},"address1":{"type":"string","maxLength":200},"address2":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":100},"state":{"type":"string","maxLength":50},"postalCode":{"type":"string","maxLength":20},"country":{"type":"string","minLength":2,"maxLength":56,"default":"US"},"residential":{"type":"boolean","default":true}}},"lineItems":{"type":"array","minItems":1,"maxItems":200,"items":{"type":"object","additionalProperties":true,"x-unknown-field-policy":"strip","required":["sku","quantity"],"properties":{"sku":{"type":"string","maxLength":64,"description":"Public channel SKU returned by catalog, or the immutable vialApiSku; supplier identifiers are rejected"},"quantity":{"type":"integer","minimum":1,"maximum":10000}}}},"shippingMethod":{"type":"string","maxLength":64,"description":"Key of a configured shipping method; omitted = your default. Unknown keys are rejected."}}},"Customer":{"type":"object","additionalProperties":false,"required":["id","name","firstName","lastName","company","email","phone","tags","ordersCount","lastOrderAt","defaultShipTo","createdAt"],"properties":{"id":{"type":"string"},"name":{"type":"string","description":"Display name derived from the current customer snapshot"},"firstName":{"type":["string","null"]},"lastName":{"type":["string","null"]},"company":{"type":["string","null"]},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"ordersCount":{"type":"integer","minimum":0},"lastOrderAt":{"type":["string","null"],"format":"date-time"},"defaultShipTo":{"description":"Saved default shipping-address snapshot, or null when none is configured","oneOf":[{"$ref":"#/components/schemas/ShipTo"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"}},"example":{"id":"cus_01JEXAMPLE000000000000000","name":"Morgan Lee","firstName":"Morgan","lastName":"Lee","company":"Atlas Supply Co.","email":"morgan.lee@example.com","phone":"+1-202-555-0142","tags":["wholesale"],"ordersCount":3,"lastOrderAt":"2026-07-17T16:30:00.000Z","defaultShipTo":{"recipientName":"Morgan Lee","address1":"100 Example Avenue","city":"Atlanta","state":"GA","postalCode":"30309","country":"US","residential":true},"createdAt":"2026-06-10T09:00:00.000Z"}},"CustomersResponse":{"type":"object","additionalProperties":false,"required":["customers","nextCursor"],"properties":{"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}},"nextCursor":{"type":["string","null"]}}},"ShipTo":{"type":"object","additionalProperties":false,"required":["recipientName","address1","city","state","postalCode","country"],"properties":{"recipientName":{"type":"string"},"recipientCompany":{"type":["string","null"]},"address1":{"type":"string"},"address2":{"type":["string","null"]},"city":{"type":"string"},"state":{"type":"string"},"postalCode":{"type":"string"},"country":{"type":"string"},"residential":{"type":"boolean"}}},"AccountCatalogItem":{"type":"object","additionalProperties":false,"required":["sku","vialApiSku","channelSku","name","status","priceCents","currency","tiers","orderEligibility","inventoryStatus","inventoryConfirmedAt","availability"],"properties":{"sku":{"type":"string","description":"Credential-preferred public SKU"},"vialApiSku":{"type":"string","description":"Immutable VialAPI product identity"},"channelSku":{"type":["string","null"],"description":"Optional channel compatibility alias"},"name":{"type":"string"},"status":{"type":"string","enum":["active"]},"priceCents":{"type":"integer","minimum":0},"currency":{"type":"string","enum":["USD"]},"tiers":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["minQuantity","unitPriceCents"],"properties":{"minQuantity":{"type":"integer","minimum":1},"unitPriceCents":{"type":"integer","minimum":0}}}},"orderEligibility":{"type":"string","enum":["eligible"],"description":"The credential may submit this priced item."},"inventoryStatus":{"type":"string","enum":["in_stock","low_stock","stock_confirmation_required","temporarily_unavailable"]},"inventoryConfirmedAt":{"type":["string","null"],"format":"date-time","description":"Last source-safe inventory confirmation time; null when confirmation is required."},"availability":{"type":"string","enum":["available_to_order"],"deprecated":true,"description":"Compatibility alias for order eligibility; not an inventory guarantee."}}},"CatalogItem":{"$ref":"#/components/schemas/AccountCatalogItem"},"CatalogResponse":{"type":"object","additionalProperties":false,"required":["catalog","nextCursor"],"properties":{"catalog":{"type":"array","items":{"$ref":"#/components/schemas/CatalogItem"}},"nextCursor":{"type":["string","null"]}}},"InventoryItem":{"$ref":"#/components/schemas/AccountCatalogItem"},"ProductItem":{"type":"object","additionalProperties":false,"required":["sku","vialApiSku","channelSku","name","status"],"properties":{"sku":{"type":"string"},"vialApiSku":{"type":"string"},"channelSku":{"type":["string","null"]},"name":{"type":"string"},"status":{"type":"string","enum":["active"]}}},"ProductsResponse":{"type":"object","required":["products","nextCursor"],"properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/ProductItem"}},"nextCursor":{"type":["string","null"]}}},"InventoryResponse":{"type":"object","additionalProperties":false,"required":["inventory","nextCursor"],"properties":{"inventory":{"type":"array","items":{"$ref":"#/components/schemas/InventoryItem"}},"nextCursor":{"type":["string","null"]}}},"OrdersResponse":{"type":"object","additionalProperties":false,"required":["orders","nextCursor"],"properties":{"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"nextCursor":{"type":["string","null"]}}},"ShippingMethod":{"type":"object","additionalProperties":false,"required":["key","label","chargeCents","isDefault"],"properties":{"key":{"type":"string"},"label":{"type":"string"},"chargeCents":{"type":"integer","minimum":0},"isDefault":{"type":"boolean"}}},"ShippingMethodsResponse":{"type":"object","additionalProperties":false,"required":["shippingMethods"],"properties":{"shippingMethods":{"type":"array","items":{"$ref":"#/components/schemas/ShippingMethod"}}}},"WebhookEvent":{"type":"object","additionalProperties":false,"required":["id","event","payloadVersion","status","attempts","replayCount","lastStatusCode","orderId","nextRetryAt","deliveredAt","deadLetteredAt","attemptHistory","lastAttempt","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"event":{"type":"string"},"payloadVersion":{"type":"integer","minimum":0,"description":"1 for canonical events; 0 only for retained pre-1.7 delivery history"},"status":{"type":"string","enum":["pending","sent","failed","dead_lettered"]},"attempts":{"type":"integer","minimum":0},"replayCount":{"type":"integer","minimum":0},"lastStatusCode":{"type":["integer","null"]},"orderId":{"type":["string","null"]},"nextRetryAt":{"type":["string","null"],"format":"date-time"},"deliveredAt":{"type":["string","null"],"format":"date-time"},"deadLetteredAt":{"type":["string","null"],"format":"date-time"},"attemptHistory":{"type":"array","maxItems":50,"items":{"$ref":"#/components/schemas/WebhookAttemptSummary"},"description":"Newest first; normalized and redacted"},"lastAttempt":{"oneOf":[{"$ref":"#/components/schemas/WebhookAttemptSummary"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"WebhookAttemptSummary":{"type":"object","additionalProperties":false,"required":["number","trigger","outcome","statusCode","category","contentType","responseBytes","durationMs","retryAt","startedAt","completedAt"],"properties":{"number":{"type":"integer","minimum":1},"trigger":{"type":"string","enum":["automatic","manual","test"]},"outcome":{"type":"string","enum":["in_progress","delivered","retry_scheduled","rejected","unreachable","superseded"]},"statusCode":{"type":["integer","null"]},"category":{"type":["string","null"]},"contentType":{"type":["string","null"],"maxLength":200},"responseBytes":{"type":["integer","null"],"minimum":0,"maximum":65536},"durationMs":{"type":["integer","null"],"minimum":0},"retryAt":{"type":["string","null"],"format":"date-time"},"startedAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}},"EventsResponse":{"type":"object","additionalProperties":false,"required":["events","nextCursor"],"properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEvent"}},"nextCursor":{"type":["string","null"]}}},"WebhookTestResponse":{"type":"object","additionalProperties":false,"required":["category","scenario","eventId","deliveryId","nextRetryAt"],"properties":{"category":{"type":"string","enum":["delivered","retry_scheduled","rejected","unreachable"]},"scenario":{"type":"string","enum":["ping","order.created","order.awaiting_payment","order.status_changed","order.approved","order.needs_review","order.label_created","order.shipped","order.delivered","order.cancelled","inventory.low_stock"]},"eventId":{"type":"string"},"deliveryId":{"type":"string"},"nextRetryAt":{"type":["string","null"],"format":"date-time"}}},"WebhookEndpoint":{"type":"object","additionalProperties":false,"required":["url","hasSecret","signatureVersion","deliveryGuarantee","orderingGuaranteed","previousSecretValidUntil","events"],"properties":{"url":{"type":["string","null"]},"hasSecret":{"type":"boolean"},"signatureVersion":{"type":"string","const":"v1"},"deliveryGuarantee":{"type":"string","const":"at_least_once"},"orderingGuaranteed":{"type":"boolean","const":false},"previousSecretValidUntil":{"type":["string","null"],"format":"date-time"},"events":{"type":"object","properties":{"order.needs_review":{"type":"boolean"},"inventory.low_stock":{"type":"boolean"}}},"secret":{"type":"string","description":"Present exactly once — when the signing secret is first created or rotated"}}},"PingWebhook":{"type":"object","additionalProperties":false,"required":["id","event","payloadVersion","createdAt","livemode","data","synthetic","message"],"properties":{"id":{"type":"string"},"event":{"type":"string","const":"ping"},"payloadVersion":{"type":"integer","const":1},"createdAt":{"type":"string","format":"date-time"},"livemode":{"type":"boolean","const":false},"data":{"type":"object"},"synthetic":{"type":"boolean","const":true},"message":{"type":"string"}}},"OrderWebhook":{"type":"object","description":"The versioned data object is authoritative. Additive top-level compatibility fields may mirror data during the v1 migration window.","required":["id","event","payloadVersion","createdAt","livemode","data","vialapiOrderId","externalOrderId","status"],"properties":{"id":{"type":"string"},"event":{"type":"string","enum":["order.created","order.awaiting_payment","order.status_changed","order.approved","order.label_created","order.shipped","order.delivered","order.cancelled","order.needs_review"]},"payloadVersion":{"type":"integer","const":1},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object"},"vialapiOrderId":{"type":"string"},"externalOrderId":{"type":"string"},"status":{"type":"string","enum":["received","processing","awaiting_fulfillment","needs_review","awaiting_tracking","shipped","delivered","cancelled","failed"]},"livemode":{"type":"boolean"},"tracking":{"type":["object","null"],"additionalProperties":false,"properties":{"trackingNumber":{"type":"string"},"service":{"type":["string","null"]},"carrier":{"type":["string","null"]},"trackingUrl":{"type":["string","null"]},"shippedAt":{"type":["string","null"],"format":"date-time"}}}}},"InventoryLowStockWebhook":{"type":"object","additionalProperties":false,"required":["id","event","payloadVersion","createdAt","livemode","data","sku","availability"],"properties":{"id":{"type":"string"},"event":{"type":"string","const":"inventory.low_stock"},"payloadVersion":{"type":"integer","const":1},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object"},"sku":{"type":"string","description":"Public channel SKU; never a supplier identifier"},"name":{"type":["string","null"]},"availability":{"type":"string","const":"low_stock"},"livemode":{"type":"boolean"},"synthetic":{"type":"boolean"}}},"Readiness":{"type":"object","additionalProperties":false,"required":["status","checkedAt","reasonCodes"],"properties":{"status":{"type":"string","enum":["ready","not_ready"]},"checkedAt":{"type":"string","format":"date-time"},"reasonCodes":{"type":"array","items":{"type":"string"}}}}},"headers":{"VialAPIVersion":{"description":"Semantic version of the VialAPI partner contract that produced this response","schema":{"type":"string","const":"1.7.0"}},"RequestId":{"description":"Stable correlation ID for this response; include it in support requests","schema":{"type":"string"}},"DurationMs":{"description":"Total VialAPI route processing duration in milliseconds","schema":{"type":"number","minimum":0}},"RateLimitLimit":{"description":"Current request budget for the most restrictive credential, tenant, or IP layer","schema":{"type":"integer","minimum":1}},"RateLimitRemaining":{"description":"Requests remaining in the current window","schema":{"type":"integer","minimum":0}},"RateLimitReset":{"description":"Seconds until the current window permits the full budget again","schema":{"type":"integer","minimum":0}},"RetryAfter":{"description":"Seconds to wait before retrying","schema":{"type":"integer","minimum":1}},"IdempotencyReplayed":{"description":"true when this response was replayed from the durable command ledger; false on first execution","schema":{"type":"boolean"}}}}}