{"openapi":"3.1.0","info":{"title":"Kiuki Agentic Commerce API","description":"Kiuki Agentic Commerce API enables safe, autonomous shopping across multiple vendors using a simple checkout flow and tokenized payments.","version":"1.0.0","contact":{"name":"Kiuki API Support","url":"https://api.kiuki.com","email":"support@kiuki.com"}},"servers":[{"url":"https://api.kiuki.com/v1","description":"Production API Server"}],"security":[{"ApiKeyAuthSecret":[]}],"tags":[{"name":"Products","description":"Product discovery, search, and catalog management"},{"name":"Inventory","description":"Product availability and stock information"},{"name":"Checkout","description":"Manage checkout sessions for shopping carts"},{"name":"Payment","description":"Process payments and create payment intents"},{"name":"Webhooks","description":"Subscribe to real-time event notifications"}],"paths":{"/products":{"get":{"tags":["Products"],"summary":"List Products","operationId":"listProducts","parameters":[{"name":"category","in":"query","schema":{"type":"string"},"description":"Filter by product category"},{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Number of products per page"},{"name":"page","in":"query","schema":{"type":"integer","minimum":0,"default":0},"description":"Offset for pagination"}],"responses":{"200":{"description":"Products retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductFeedSpecList"}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/products/search":{"get":{"tags":["Products"],"summary":"Search Products (returns ProductFeedSpecList)","description":"Advanced product search for conversational AI.","operationId":"searchProducts","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Search query (supports natural language)"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":10}},{"name":"include_substitutes","in":"query","schema":{"type":"boolean","default":true}}],"responses":{"200":{"description":"Search results (ProductFeedSpecList)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductFeedSpecList"}}}},"400":{"description":"Invalid search query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/products/{id}":{"get":{"tags":["Products"],"summary":"Get Product Details","operationId":"getProduct","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Unique product identifier"}],"responses":{"200":{"description":"Product details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductFeedSpec"}}}},"404":{"description":"Product not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/products/{id}/availability":{"get":{"tags":["Inventory"],"summary":"Get Product Availability","operationId":"getProductAvailability","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"postal_code","in":"query","schema":{"type":"string"}},{"name":"quantity","in":"query","schema":{"type":"integer","minimum":1,"default":1}}],"responses":{"200":{"description":"Availability information retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvailabilityResponse"}}}},"404":{"description":"Product not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/checkouts":{"post":{"tags":["Checkout"],"summary":"Create Checkout Session","operationId":"createCheckoutSession","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCheckoutRequest"}}}},"responses":{"200":{"description":"Checkout session successfully created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutSessionResponse"}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/checkouts/{id}":{"get":{"tags":["Checkout"],"summary":"Get Checkout Session","operationId":"getCheckoutSession","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Checkout session details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutSessionResponse"}}}},"404":{"description":"Checkout session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Checkout"],"summary":"Update Checkout Session","operationId":"updateCheckoutSession","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCheckoutRequest"}}}},"responses":{"200":{"description":"Checkout session updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutSessionResponse"}}}},"400":{"description":"Invalid update parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Checkout session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/checkouts/{id}/complete":{"post":{"tags":["Checkout"],"summary":"Complete Checkout","operationId":"completeCheckout","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteCheckoutRequest"}}}},"responses":{"200":{"description":"Checkout completed and order created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteCheckoutResponse"}}}},"400":{"description":"Payment processing failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Checkout session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/checkouts/{id}/cancel":{"post":{"tags":["Checkout"],"summary":"Cancel Checkout","operationId":"cancelCheckout","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Checkout session canceled successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelCheckoutResponse"}}}},"404":{"description":"Checkout session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"405":{"description":"Cannot cancel completed session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/payments/intent":{"post":{"tags":["Payment"],"summary":"Create Payment Intent","operationId":"createPaymentIntent","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePaymentIntentRequest"}}}},"responses":{"200":{"description":"Payment intent created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentIntentResponse"}}}},"400":{"description":"Invalid payment intent parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/webhooks/subscribe":{"post":{"tags":["Webhooks"],"summary":"Subscribe to Webhooks","operationId":"subscribeWebhook","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscribeWebhookRequest"}}}},"responses":{"200":{"description":"Webhook subscription created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscribeWebhookResponse"}}}},"400":{"description":"Invalid webhook configuration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/webhooks/unsubscribe/{id}":{"delete":{"tags":["Webhooks"],"summary":"Unsubscribe from Webhooks","operationId":"unsubscribeWebhook","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Webhook unsubscribed successfully"},"404":{"description":"Webhook subscription not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"securitySchemes":{"ApiKeyAuthSecret":{"type":"apiKey","in":"header","name":"X-Api-Secret","description":"Your API secret"}},"schemas":{"ErrorResponse":{"type":"object","properties":{"type":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}},"Pagination":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"has_more":{"type":"boolean"}}},"Image":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"alt":{"type":"string"},"position":{"type":"integer"}}},"Vendor":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"rating":{"type":"number","minimum":0,"maximum":5}}},"ProductSummary":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"price":{"type":"integer"},"currency":{"type":"string"},"stock":{"type":"string"}}},"ProductDetailResponse":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"price":{"type":"integer"},"currency":{"type":"string"},"images":{"type":"array","items":{"$ref":"#/components/schemas/Image"}},"stock":{"type":"string","enum":["in_stock","out_of_stock","low_stock"]},"stock_quantity":{"type":"integer"},"vendor":{"$ref":"#/components/schemas/Vendor"},"tags":{"type":"array","items":{"type":"string"}},"category":{"type":"string"},"nutritional_info":{"type":"object","properties":{"serving_size":{"type":"string"},"calories":{"type":"integer"},"sodium_mg":{"type":"integer"}}},"related_products":{"type":"array","items":{"type":"string"}}}},"ProductListResponse":{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/ProductSummary"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"ProductFeedSpec":{"type":"object","required":["enable_search","enable_checkout","id","title","description","link","product_category","image_link","price","availability","seller_name","seller_url","return_policy","return_window"],"properties":{"enable_search":{"type":"boolean","description":"true or false"},"enable_checkout":{"type":"boolean"},"id":{"type":"string","maxLength":100,"description":"unique, alphanumeric"},"title":{"type":"string","maxLength":150},"description":{"type":"string","maxLength":5000},"link":{"type":"string","format":"uri"},"product_category":{"type":"string"},"image_link":{"type":"string","format":"uri"},"price":{"type":"string","description":"e.g. \"99.99 USD\"","pattern":"^[0-9]+(\\\\.[0-9]{1,2})?\\\\s+[A-Z]{2,3}$"},"availability":{"type":"string","enum":["in_stock","out_of_stock","preorder"]},"seller_name":{"type":"string","maxLength":70},"seller_url":{"type":"string","format":"uri"},"return_policy":{"type":"string","format":"uri"},"return_window":{"type":"integer","minimum":1},"gtin":{"type":"string","pattern":"^[0-9]{8,14}$"},"mpn":{"type":"string","maxLength":70},"condition":{"type":"string","enum":["new","refurbished","used"]},"brand":{"type":"string","maxLength":70},"material":{"type":"string","maxLength":100},"dimensions":{"type":"string"},"length":{"type":"string"},"width":{"type":"string"},"height":{"type":"string"},"weight":{"type":"string"},"age_group":{"type":"string","enum":["infant","toddler","kids","adult"]},"additional_image_link":{"type":"array","items":{"type":"string","format":"uri"}},"video_link":{"type":"string","format":"uri"},"model_3d_link":{"type":"string","format":"uri"},"sale_price":{"type":"string"},"sale_price_effective_date":{"type":"string"},"unit_pricing_measure":{"type":"string"},"base_measure":{"type":"string"},"pricing_trend":{"type":"string","enum":["increasing","decreasing","stable"]},"availability_date":{"type":"string","format":"date"},"inventory_quantity":{"type":"integer","minimum":0},"quantity":{"type":"integer","minimum":0,"description":"Inventory quantity (maps to sample JSON field 'quantity')"},"expiration_date":{"type":"string","format":"date"},"pickup_method":{"type":"string","enum":["in_store","reserve","not_supported"]},"pickup_sla":{"type":"string"},"item_group_id":{"type":"string","maxLength":70},"item_group_title":{"type":"string","maxLength":150},"color":{"type":"string","maxLength":40},"size":{"type":"string","maxLength":20},"size_system":{"type":"string","pattern":"^[A-Z]{2}$"},"gender":{"type":"string","enum":["male","female","unisex"]},"offer_id":{"type":"string"},"Custom_variant1_category":{"type":"string"},"Custom_variant1_option":{"type":"string"},"Custom_variant2_category":{"type":"string"},"Custom_variant2_option":{"type":"string"},"Custom_variant3_category":{"type":"string"},"Custom_variant3_option":{"type":"string"},"shipping":{"type":"string"},"delivery_estimate":{"type":"string","format":"date"},"seller_privacy_policy":{"type":"string","format":"uri"},"seller_tos":{"type":"string","format":"uri"},"popularity_score":{"type":"number","minimum":0,"maximum":5},"return_rate":{"type":"number","minimum":0,"maximum":100},"warning":{"type":"string"},"warning_url":{"type":"string","format":"uri"},"age_restriction":{"type":"integer","minimum":0},"product_review_count":{"type":"integer","minimum":0},"product_review_rating":{"type":"number","minimum":0,"maximum":5},"store_review_count":{"type":"integer","minimum":0},"store_review_rating":{"type":"number","minimum":0,"maximum":5},"q_and_a":{"type":"string"},"raw_review_data":{"type":"string"},"related_product_id":{"type":"string"},"relationship_type":{"type":"string"},"geo_price":{"type":"string"},"geo_availability":{"type":"string"}}},"ProductFeedSpecList":{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/ProductFeedSpec"}}}},"Buyer":{"type":"object","required":["first_name","last_name","email"],"properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string","format":"email"},"phone_number":{"type":"string"}}},"Merchant":{"type":"object","properties":{"name":{"type":"string"},"logo_url":{"type":"string"},"support_email":{"type":"string","format":"email"},"support_url":{"type":"string"}}},"CheckoutItem":{"type":"object","required":["id","quantity"],"properties":{"id":{"type":"string"},"quantity":{"type":"integer","minimum":1}}},"Address":{"type":"object","required":["name","line_one","city","state","country","postal_code"],"properties":{"name":{"type":"string"},"line_one":{"type":"string"},"line_two":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"country":{"type":"string"},"postal_code":{"type":"string"}}},"CreateCheckoutRequest":{"type":"object","required":["buyer","items","fulfillment_address"],"properties":{"buyer":{"$ref":"#/components/schemas/Buyer"},"items":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/CheckoutItem"}},"fulfillment_address":{"$ref":"#/components/schemas/Address"}}},"UpdateCheckoutRequest":{"type":"object","properties":{"buyer":{"$ref":"#/components/schemas/Buyer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/CheckoutItem"}},"fulfillment_address":{"$ref":"#/components/schemas/Address"},"fulfillment_option_id":{"type":"string"}}},"CheckoutSessionResponse":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"currency":{"type":"string"},"buyer":{"$ref":"#/components/schemas/Buyer"},"merchant":{"$ref":"#/components/schemas/Merchant"},"line_items":{"type":"array","items":{"$ref":"#/components/schemas/CheckoutItem"}},"fulfillment_options":{"type":"array","items":{"type":"object"}},"totals":{"type":"array","items":{"type":"object"}}}},"CompleteCheckoutRequest":{"type":"object","required":["payment_data"],"properties":{"payment_data":{"type":"object","required":["token","provider","billing_address"],"properties":{"token":{"type":"string","description":"Stripe Shared Payment token (SPT)"},"provider":{"type":"string"},"billing_address":{"$ref":"#/components/schemas/Address"}}}}},"CompleteCheckoutResponse":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"currency":{"type":"string"},"buyer":{"$ref":"#/components/schemas/Buyer"},"order":{"type":"object","properties":{"id":{"type":"string"},"checkout_session_id":{"type":"string"},"permalink_url":{"type":"string","format":"uri"}}}}},"CancelCheckoutResponse":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"currency":{"type":"string"},"buyer":{"$ref":"#/components/schemas/Buyer"}}},"CreatePaymentIntentRequest":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","format":"int64","description":"Amount in smallest currency unit (e.g., cents)"},"currency":{"type":"string","description":"Currency code in ISO 4217 format (e.g., \"usd\")"},"customer_id":{"type":"string","description":"Optional customer ID"},"metadata":{"type":"object","description":"Optional key-value pairs for storing metadata","additionalProperties":{"type":"string"}}}},"PaymentIntentResponse":{"type":"object","properties":{"intent_id":{"type":"string"},"provider":{"type":"string"},"amount":{"type":"integer","format":"int64"},"currency":{"type":"string"},"status":{"type":"string"},"confirmation_url":{"type":"string","format":"uri"},"client_secret":{"type":"string"},"payment_intent":{"type":"string"}},"required":["intent_id","provider","amount","currency","status","confirmation_url"]},"SubscribeWebhookRequest":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["order.completed","order.failed","checkout.abandoned","inventory.updated","delivery.status"]}},"secret":{"type":"string"}}},"SubscribeWebhookResponse":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["active","inactive"]}}},"AvailabilityResponse":{"type":"object","properties":{"product_id":{"type":"string"},"stock_status":{"type":"string","enum":["in_stock","out_of_stock","low_stock","preorder"]},"quantity_available":{"type":"integer"},"warehouses":{"type":"array","items":{"type":"object","properties":{"warehouse_id":{"type":"string"},"name":{"type":"string"},"distance_km":{"type":"number"},"quantity":{"type":"integer"},"can_fulfill":{"type":"boolean"}}}},"estimated_restock_date":{"type":"string","format":"date-time"},"delivery_options":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["shipping","pickup"]},"available":{"type":"boolean"},"estimated_delivery":{"type":"string","format":"date-time"}}}}}}}}}