{ "openapi": "3.1.0", "info": { "title": "nemahBites Agent Commerce API", "version": "1.0.0", "summary": "Search, price and order groceries for delivery in Bangladesh.", "description": "Provider-neutral commerce API for AI agents. The same endpoints serve MCP clients, A2A agents, LangChain tools and plain HTTP callers.\n\n**The order of operations matters.** Search a product, check its availability, create a checkout, show the customer the total, and only place the order after they explicitly agree. `POST /checkouts` never creates an order; only `POST /checkouts/{id}/confirm` with `{\"confirmation\": true}` does.\n\n**The server owns every number.** Price, stock, discount, delivery and total are recomputed from the database at quote time and again, inside a transaction, at confirmation. Values supplied by a client are ignored. If anything changed between the quote and the confirmation, confirmation fails with `PRICE_CHANGED` and lists what moved.\n\n**Idempotency.** Send `Idempotency-Key` on every POST. Retrying with the same key and the same body replays the original response instead of creating a second order; the replay carries `Idempotency-Replayed: true`. Keys are remembered for 24 hours.\n\n**Rate limits.** 120 catalog reads per minute, 30 checkouts per hour and 10 confirmations per hour, per credential (per IP when anonymous). Exceeding one returns `429` with `Retry-After`.\n\n**Payment.** Cash on delivery is the only method an agent can complete end to end. Card and mobile-wallet payments run in the customer's browser; the API says so rather than pretending otherwise.", "contact": { "name": "nemahBites", "url": "https://nemahbites.com/page/contact" }, "license": { "name": "Proprietary", "identifier": "LicenseRef-nemahBites" } }, "servers": [ { "url": "https://nemahbites.com/api/agent/v1", "description": "Production" } ], "security": [ {} ], "tags": [ { "name": "Catalog", "description": "Open. No credential required." }, { "name": "Wholesale", "description": "Public bulk estimates; authenticated, customer-approved enquiry. Not automatic checkout." }, { "name": "Delivery", "description": "Open. Address validation and delivery pricing." }, { "name": "Checkout", "description": "Requires the `checkout.write` scope." }, { "name": "Rewards", "description": "Customer-bound private reads; no public balances." }, { "name": "Orders", "description": "Order status. An agent sees only the orders it placed." } ], "paths": { "/wholesale/products": { "get": { "tags": [ "Wholesale" ], "security": [ {} ], "responses": { "200": { "description": "Separate candidate estimates; select exact SKU if multiple match. Not an order basket.", "content": { "application/json": { "schema": { "type": "object", "required": [ "products", "requires_product_selection" ], "properties": { "products": { "type": "array", "items": { "type": "object" } }, "requires_product_selection": { "type": "boolean" }, "has_more": { "type": "boolean" } } } } } }, "400": { "description": "Typed error (validation, feature disabled, rate limit or authorization).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Typed error (validation, feature disabled, rate limit or authorization).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Typed error (validation, feature disabled, rate limit or authorization).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "searchWholesaleProducts", "summary": "Search eligible wholesale packs with quantity-specific estimates", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "quantity", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 10 } } ] } }, "/wholesale/eligibility": { "get": { "tags": [ "Wholesale" ], "security": [ {} ], "responses": { "200": { "description": "Live estimate only. No order or stock reservation; delivery fee unknown until shop quote.", "content": { "application/json": { "schema": { "type": "object", "required": [ "currency", "lines", "merchandise_total", "quote_complete", "workflow" ], "properties": { "currency": { "const": "BDT" }, "lines": { "type": "array", "items": { "type": "object", "required": [ "product_id", "quantity", "retail", "stock", "line_total" ], "properties": { "product_id": { "type": "integer", "minimum": 1 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 100000 }, "retail": { "type": "object" }, "wholesale": { "type": [ "object", "null" ] }, "line_total": { "type": "number" }, "stock": { "type": "object", "properties": { "available_quantity": { "type": [ "integer", "null" ] }, "reserved": { "const": false }, "status": { "enum": [ "unavailable", "quantity_confirmation_required", "sufficient_at_check", "insufficient_at_check" ] } } } } } }, "merchandise_total": { "type": "number" }, "quote_complete": { "type": "boolean" }, "workflow": { "type": "object", "properties": { "automatic_checkout": { "const": false }, "checkout_mode": { "const": "merchant_approved_quote" } } } } } } } }, "400": { "description": "Typed error (validation, feature disabled, rate limit or authorization).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Typed error (validation, feature disabled, rate limit or authorization).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Typed error (validation, feature disabled, rate limit or authorization).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getWholesaleEligibility", "summary": "Read current wholesale eligibility", "parameters": [ { "name": "product_id", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "quantity", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } } ] } }, "/wholesale/stock": { "get": { "tags": [ "Wholesale" ], "security": [ {} ], "responses": { "200": { "description": "Live estimate only. No order or stock reservation; delivery fee unknown until shop quote.", "content": { "application/json": { "schema": { "type": "object", "required": [ "currency", "lines", "merchandise_total", "quote_complete", "workflow" ], "properties": { "currency": { "const": "BDT" }, "lines": { "type": "array", "items": { "type": "object", "required": [ "product_id", "quantity", "retail", "stock", "line_total" ], "properties": { "product_id": { "type": "integer", "minimum": 1 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 100000 }, "retail": { "type": "object" }, "wholesale": { "type": [ "object", "null" ] }, "line_total": { "type": "number" }, "stock": { "type": "object", "properties": { "available_quantity": { "type": [ "integer", "null" ] }, "reserved": { "const": false }, "status": { "enum": [ "unavailable", "quantity_confirmation_required", "sufficient_at_check", "insufficient_at_check" ] } } } } } }, "merchandise_total": { "type": "number" }, "quote_complete": { "type": "boolean" }, "workflow": { "type": "object", "properties": { "automatic_checkout": { "const": false }, "checkout_mode": { "const": "merchant_approved_quote" } } } } } } } }, "400": { "description": "Typed error (validation, feature disabled, rate limit or authorization).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Typed error (validation, feature disabled, rate limit or authorization).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Typed error (validation, feature disabled, rate limit or authorization).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "checkBulkStock", "summary": "Check bulk stock without reserving it", "parameters": [ { "name": "product_id", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "quantity", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } } ] } }, "/wholesale/quote": { "post": { "tags": [ "Wholesale" ], "security": [ {} ], "responses": { "200": { "description": "Live estimate only. No order or stock reservation; delivery fee unknown until shop quote.", "content": { "application/json": { "schema": { "type": "object", "required": [ "currency", "lines", "merchandise_total", "quote_complete", "workflow" ], "properties": { "currency": { "const": "BDT" }, "lines": { "type": "array", "items": { "type": "object", "required": [ "product_id", "quantity", "retail", "stock", "line_total" ], "properties": { "product_id": { "type": "integer", "minimum": 1 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 100000 }, "retail": { "type": "object" }, "wholesale": { "type": [ "object", "null" ] }, "line_total": { "type": "number" }, "stock": { "type": "object", "properties": { "available_quantity": { "type": [ "integer", "null" ] }, "reserved": { "const": false }, "status": { "enum": [ "unavailable", "quantity_confirmation_required", "sufficient_at_check", "insufficient_at_check" ] } } } } } }, "merchandise_total": { "type": "number" }, "quote_complete": { "type": "boolean" }, "workflow": { "type": "object", "properties": { "automatic_checkout": { "const": false }, "checkout_mode": { "const": "merchant_approved_quote" } } } } } } } }, "400": { "description": "Typed error (validation, feature disabled, rate limit or authorization).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Typed error (validation, feature disabled, rate limit or authorization).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Typed error (validation, feature disabled, rate limit or authorization).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "quoteWholesale", "summary": "Calculate live wholesale merchandise prices", "description": "Tier discount is applied after retail promotion, per exact sellable outer-pack SKU. Mixed SKUs do not combine to reach a tier. Unmanaged bulk stock needs shop confirmation. Retail checkout cannot honour this quote automatically.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "required": [ "product_id", "quantity" ], "properties": { "product_id": { "type": "integer", "minimum": 1 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 100000 } } } } } } } } } } }, "/wholesale/enquiry": { "post": { "tags": [ "Wholesale" ], "operationId": "createWholesaleEnquiry", "summary": "Send a customer-approved bulk enquiry, not an order", "description": "Requires checkout.write, explicit customer consent and an idempotency key. No payment, stock reservation or points redemption. The same actor/key/body replays across REST, MCP and A2A. Shop confirms stock, delivery and final quote before customer approval.", "security": [ { "oauth2": [ "checkout.write" ] }, { "apiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 120 }, "description": "Required here or as body idempotency_key. If both are supplied they must match." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "name", "phone", "delivery_city", "confirmation" ], "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "required": [ "product_id", "quantity" ], "properties": { "product_id": { "type": "integer", "minimum": 1 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 100000 } } } }, "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "phone": { "type": "string", "pattern": "^(?:\\+?88)?01[3-9]\\d{8}$" }, "delivery_city": { "type": "string", "minLength": 1, "maxLength": 120 }, "note": { "type": "string", "maxLength": 2000 }, "confirmation": { "const": true }, "idempotency_key": { "type": "string", "minLength": 8, "maxLength": 120 } } } } } }, "responses": { "200": { "description": "Idempotent replay of the original enquiry." }, "201": { "description": "Enquiry recorded; reference, estimated merchandise total and order_created=false." }, "400": { "description": "Typed error (validation, feature disabled, rate limit or authorization).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Typed error (validation, feature disabled, rate limit or authorization).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Typed error (validation, feature disabled, rate limit or authorization).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Typed error (validation, feature disabled, rate limit or authorization).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Typed error (validation, feature disabled, rate limit or authorization).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Typed error (validation, feature disabled, rate limit or authorization).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/commerce-config": { "get": { "operationId": "getCommerceConfig", "tags": [ "Catalog" ], "summary": "Versioned public commerce rules from admin configuration", "description": "Same contract as GET /api/commerce/config. No-store. No customer records or secret settings.", "responses": { "200": { "description": "Current public rules.", "content": { "application/json": { "schema": { "type": "object", "required": [ "schema_version", "revision", "currency", "business_clock", "wholesale", "rewards", "retail_delivery", "wholesale_delivery", "freshness" ], "properties": { "schema_version": { "const": "1.0" }, "revision": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "currency": { "const": "BDT" }, "business_clock": { "type": "object", "required": [ "business_timezone", "business_day_reset" ], "properties": { "business_timezone": { "type": "string" }, "business_day_reset": { "type": "string", "pattern": "^\\d{2}:\\d{2}$" } } }, "wholesale": { "type": "object", "required": [ "enabled", "minimum_quantity_per_line", "tiers", "workflow" ], "properties": { "enabled": { "type": "boolean" }, "minimum_quantity_per_line": { "type": [ "integer", "null" ], "minimum": 1 }, "quantity_basis": { "const": "sellable_outer_pack_per_product_id" }, "discount_basis": { "const": "retail_price_after_promotions" }, "rounding": { "const": "whole_bdt_each_pricing_step" }, "tiers": { "type": "array", "items": { "type": "object", "required": [ "min_quantity", "percent_off_retail" ], "properties": { "min_quantity": { "type": "integer", "minimum": 1 }, "percent_off_retail": { "type": "number", "minimum": 0, "maximum": 100 }, "label": { "type": [ "string", "null" ] }, "label_bangla": { "type": [ "string", "null" ] } } } }, "workflow": { "type": "object", "properties": { "automatic_checkout": { "const": false }, "checkout_mode": { "const": "merchant_approved_quote" } } } } }, "rewards": { "type": "object", "required": [ "enabled", "earn_points_per_100_bdt", "bdt_per_100_points", "expires_after_days", "max_percent_of_order_redeemable", "min_redeem_points", "daily_checkin" ], "properties": { "enabled": { "type": "boolean" }, "earn_points_per_100_bdt": { "type": "number" }, "bdt_per_100_points": { "type": "number" }, "expires_after_days": { "type": "integer" }, "max_percent_of_order_redeemable": { "type": "number" }, "min_redeem_points": { "type": "integer" }, "redemption_order": { "const": "earliest_expiring_first" }, "expiry_scope": { "const": "each_earning_transaction" }, "daily_checkin": { "type": "object", "required": [ "business_timezone", "business_day_reset", "configured_points", "available" ], "properties": { "business_timezone": { "type": "string" }, "business_day_reset": { "type": "string" }, "configured_points": { "type": "integer" }, "available": { "type": "boolean" } } } } }, "retail_delivery": { "type": "object" }, "wholesale_delivery": { "type": "object" }, "freshness": { "type": "object" } } } } } }, "503": { "description": "Configuration unavailable. Do not assume default discounts.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/loyalty": { "get": { "operationId": "getRewardBalance", "tags": [ "Rewards" ], "summary": "Read only the customer bound to this token", "description": "Requires customer-approved loyalty.read. No customer identifier is accepted as authority. Optional caller-supplied subtotal/discount produces an estimate, not a checkout quote.", "security": [ { "oauth2": [ "loyalty.read" ] }, { "apiKey": [] } ], "parameters": [ { "name": "subtotal", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 1000000000 } }, { "name": "discount", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 1000000000 } } ], "responses": { "200": { "description": "Customer-bound balance and optional illustrative retail preview. No points are moved.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid amounts.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Missing loyalty.read or linked customer.", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Rate limited.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/loyalty/preview": { "post": { "operationId": "previewRewardRedemption", "tags": [ "Rewards" ], "summary": "Preview retail reward redemption without spending points", "description": "Read-only: no idempotency key needed. Requires customer-bound loyalty.read. Caller-supplied amounts are illustrative; final checkout re-prices the basket and requires loyalty.write plus explicit approval. Not wholesale redemption.", "security": [ { "oauth2": [ "loyalty.read" ] }, { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "subtotal" ], "properties": { "subtotal": { "type": "number", "minimum": 0, "maximum": 1000000000 }, "discount": { "type": "number", "minimum": 0, "maximum": 1000000000 } } } } } }, "responses": { "200": { "description": "Customer-bound balance and optional illustrative retail preview. No points are moved.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid amounts.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Missing loyalty.read or linked customer.", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Rate limited.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/capabilities": { "get": { "tags": [ "Catalog" ], "operationId": "getCapabilities", "summary": "What this store can actually do, right now", "description": "Read from live configuration, not hard-coded. Check `capabilities.checkout` before attempting to order, and `capabilities.instant_checkout` before assuming ChatGPT's native purchase flow is available — it is false, because the Agentic Commerce Protocol accepts card payments only and this store settles cash on delivery.", "responses": { "200": { "description": "Current capabilities, payment methods and endpoints." } } } }, "/orders/{id}/cancel": { "post": { "tags": [ "Orders" ], "operationId": "cancelOrder", "summary": "Cancel an order the customer no longer wants", "description": "Three gates, all server-side: the credential must own the order, the published cancellation window must still be open, and the order must not have been dispatched. Read `cancellation` on the order first — it says whether this call will succeed and how many hours are left — rather than calling and handling the refusal.\n\nA 409 with `reason: \"already_dispatched\"` is not retryable: tell the customer to refuse the parcel at the door, or to report a problem after delivery within the returns window.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Order number or numeric id." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Optional, free text from the customer. Recorded on the order history." } } } } } }, "responses": { "200": { "description": "Cancelled. Returns the updated order." }, "404": { "description": "ORDER_NOT_FOUND — no order with that number is visible to this credential." }, "409": { "description": "CANCELLATION_NOT_ALLOWED — outside the window, already dispatched, or already cancelled. `details.reason` says which." } } } }, "/policies": { "get": { "tags": [ "Catalog" ], "operationId": "getPolicies", "summary": "Delivery, payment, returns, refunds and cancellation policy", "description": "The machine-readable version of /page/delivery and /page/return-policy. Read this before answering a customer's question about delivery time, delivery cost, returns or refunds — the answers are here, and guessing them is the single most common way an agent misleads a shopper.\n\nA policy this store has not published is reported as the string `unknown` rather than omitted or guessed. Read the current cancellation policy and the order's cancellation eligibility before offering cancellation; authorization, dispatch status and the configured time window are enforced by the order endpoint.", "responses": { "200": { "description": "Current commerce policy, resolved from live settings." } } } }, "/whoami": { "get": { "tags": [ "Catalog" ], "operationId": "whoami", "summary": "How this site sees you right now", "description": "Diagnostic. Returns the credential you presented, the scopes it carries, whether your claimed agent identity could be verified, and the next call to make. Open, uncached, and it echoes back only what you sent. Start here when a checkout is refused and it is not obvious why.", "responses": { "200": { "description": "The caller's credential, identity and permissions." } } } }, "/products": { "get": { "tags": [ "Catalog" ], "operationId": "searchProducts", "summary": "Search and filter the catalog", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" }, "example": "dark chocolate", "description": "Matches product name, brand, slug or GTIN." }, { "name": "sku", "in": "query", "schema": { "type": "string" }, "description": "Exact match on slug, GTIN or MPN." }, { "name": "brand", "in": "query", "schema": { "type": "string" }, "example": "nestle" }, { "name": "category", "in": "query", "schema": { "type": "string" }, "example": "chocolate", "description": "Slug or id. Includes direct subcategories." }, { "name": "availability", "in": "query", "schema": { "type": "string", "enum": [ "in_stock", "any" ], "default": "any" } }, { "name": "min_price", "in": "query", "schema": { "type": "number" }, "example": 100, "description": "BDT, compared against the discounted price." }, { "name": "max_price", "in": "query", "schema": { "type": "number" }, "example": 500 }, { "name": "min_size", "in": "query", "schema": { "type": "number" }, "example": 100, "description": "Smallest pack size in grams or millilitres. Pack size is derived from the product name and is not known for every product." }, { "name": "max_size", "in": "query", "schema": { "type": "number" }, "example": 500 }, { "name": "size_unit", "in": "query", "schema": { "type": "string", "enum": [ "g", "ml" ] }, "description": "'g' for solids, 'ml' for liquids. They are never compared to each other." }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "relevance", "price_asc", "price_desc", "name_asc", "newest", "rating", "value" ], "default": "relevance" }, "description": "`value` sorts by price per 100g/100ml. Products with an unknown pack size sort last rather than appearing to be infinitely good value." }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "locale", "in": "query", "schema": { "type": "string", "enum": [ "en", "bn" ], "default": "en" } } ], "responses": { "200": { "description": "Matching products.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "currency": { "type": "string", "const": "BDT" } } }, "example": { "data": [ { "id": "412", "name": "Nestle KitKat 4 Finger Dark", "sku": "nestle-kitkat-4-finger-dark", "brand": { "id": "nestle", "name": "Nestle" }, "category": { "id": "chocolate", "name": "Chocolate" }, "price": { "amount": 134, "currency": "BDT", "list_amount": 149, "discount_percent": 10 }, "availability": "in_stock", "stock_quantity": 42, "url": "https://nemahbites.com/product/nestle-kitkat-4-finger-dark" } ], "pagination": { "page": 1, "limit": 20, "total": 1, "total_pages": 1 }, "currency": "BDT" } } } }, "429": { "description": "Rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/products/{id}": { "get": { "tags": [ "Catalog" ], "operationId": "getProduct", "summary": "One product in full", "description": "`id` accepts the numeric product id, internal SKU, existing slug, or known GTIN barcode.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "nestle-kitkat-4-finger-dark" } ], "responses": { "200": { "description": "The product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProductDetail" } } } } } }, "404": { "description": "`PRODUCT_NOT_FOUND` — no active, in-date product matches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/products/{id}/availability": { "get": { "tags": [ "Catalog" ], "operationId": "checkAvailability", "summary": "Live stock for one product", "description": "Never cached. Still advisory — stock is checked again under a row lock when the order is confirmed.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "quantity", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "description": "If given, `can_purchase` answers for this quantity." } ], "responses": { "200": { "description": "Current availability.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Availability" }, "example": { "product_id": "412", "name": "Nestle KitKat 4 Finger Dark", "availability": "in_stock", "stock_quantity": 42, "can_purchase": true, "requested_quantity": 2, "available_quantity": 42 } } } }, "404": { "description": "`PRODUCT_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/catalog": { "get": { "tags": [ "Catalog" ], "operationId": "getCatalogFeed", "summary": "The whole purchasable catalog", "description": "Paginated. Also served at https://nemahbites.com/ai/products/feed.json.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 1000, "default": 500 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Feed page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogFeed" } } } } } } }, "/categories": { "get": { "tags": [ "Catalog" ], "operationId": "listCategories", "summary": "Category tree with product counts", "responses": { "200": { "description": "Categories." } } } }, "/brands": { "get": { "tags": [ "Catalog" ], "operationId": "listBrands", "summary": "Brands with purchasable products", "responses": { "200": { "description": "Brands." } } } }, "/shipping/quote": { "post": { "tags": [ "Delivery" ], "operationId": "quoteShipping", "summary": "Delivery cost and estimate for a basket and address", "description": "Prices the basket first, because the free-shipping threshold is measured after any discount.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "address" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LineItemInput" } }, "address": { "$ref": "#/components/schemas/AddressInput" }, "coupon_code": { "type": "string" } } }, "example": { "items": [ { "product_id": 412, "quantity": 2 } ], "address": { "address_line": "House 12, Block B", "area": "Mirpur 12", "city": "Dhaka" } } } } }, "responses": { "200": { "description": "Current destination-specific delivery quote, recalculated from store settings. Read /api/commerce/config for current retail rules; no fixed example amount is a live price or delivery commitment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "available": { "type": "boolean" }, "delivery_fee": { "type": "number", "minimum": 0 }, "currency": { "type": "string", "const": "BDT" }, "estimated_delivery": { "type": "string" }, "estimated_delivery_text": { "type": "string" }, "zone": { "type": "string", "enum": [ "inside_dhaka", "outside_dhaka" ] }, "free_shipping_threshold": { "type": [ "number", "null" ], "minimum": 0, "description": "Current eligible-merchandise threshold; null when free shipping is disabled." }, "free_shipping_remaining": { "type": [ "number", "null" ], "minimum": 0, "description": "Additional eligible merchandise needed; null when already eligible or free shipping is disabled." }, "basket": { "type": "object", "properties": { "subtotal": { "type": "number", "minimum": 0 }, "discount": { "type": "number", "minimum": 0 }, "delivery_fee": { "type": "number", "minimum": 0 }, "total": { "type": "number", "minimum": 0 } } } } } } } }, "422": { "description": "`INVALID_ADDRESS` or `DELIVERY_UNAVAILABLE` — the address is incomplete, or outside Bangladesh.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/checkouts": { "post": { "tags": [ "Checkout" ], "operationId": "createCheckout", "summary": "Quote a basket. Creates NO order.", "description": "Returns a priced summary that expires in 15 minutes. Show it to the customer and ask for approval before confirming.", "security": [ { "oauth2": [ "checkout.write" ] }, { "apiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "customer", "shipping_address" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LineItemInput" } }, "customer": { "type": "object", "required": [ "name", "phone" ], "properties": { "name": { "type": "string", "example": "Ashikur Rahman" }, "phone": { "type": "string", "example": "01712345678", "description": "Bangladeshi mobile. +880 and 88 prefixes are accepted and normalised." }, "email": { "type": "string", "format": "email" } } }, "shipping_address": { "$ref": "#/components/schemas/AddressInput" }, "payment_method": { "type": "string", "default": "cod", "description": "Only `cod` can be completed by an agent today." }, "coupon_code": { "type": "string" }, "notes": { "type": "string", "maxLength": 500 } } }, "example": { "items": [ { "product_id": 412, "quantity": 2 } ], "customer": { "name": "Ashikur Rahman", "phone": "01712345678" }, "shipping_address": { "address_line": "House 12, Block B", "area": "Mirpur 12", "city": "Dhaka" }, "payment_method": "cod" } } } }, "responses": { "201": { "description": "Checkout created. No order exists yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Checkout" } } } }, "401": { "description": "No credential. The `WWW-Authenticate` header points at the authorization server metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`FORBIDDEN` — the credential lacks `checkout.write`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`OUT_OF_STOCK` or `INSUFFICIENT_STOCK`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`INVALID_ADDRESS`, `DELIVERY_UNAVAILABLE`, `INVALID_PAYMENT_METHOD` or `IDEMPOTENCY_KEY_REUSED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Orders" ], "operationId": "listAgentOrders", "summary": "Orders this agent has placed", "security": [ { "oauth2": [ "checkout.write" ] }, { "apiKey": [] } ], "responses": { "200": { "description": "Orders." } } } }, "/checkouts/{checkout_id}": { "get": { "tags": [ "Checkout" ], "operationId": "getCheckout", "summary": "Review a checkout against live prices and stock", "description": "Re-prices every line before answering. Any difference from the original quote appears in `changes`.", "security": [ { "oauth2": [ "checkout.write" ] }, { "apiKey": [] } ], "parameters": [ { "name": "checkout_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "chk_9f2c…" } ], "responses": { "200": { "description": "Current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Checkout" } } } }, "403": { "description": "`FORBIDDEN` — the checkout belongs to another agent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`CHECKOUT_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "`CHECKOUT_EXPIRED` — create a new checkout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/checkouts/{checkout_id}/confirm": { "post": { "tags": [ "Checkout" ], "operationId": "confirmOrder", "summary": "Place the real order", "description": "**High impact. This creates a real order that will be delivered and paid for.**\n\nCall it only after the customer has seen the checkout summary and explicitly agreed. `confirmation` must be the JSON boolean `true`; the strings `\"true\"` and `\"yes\"` and the number `1` are all rejected with `CONFIRMATION_REQUIRED`, so approval cannot be inferred from vague language.\n\nIf the basket changed since it was quoted, the call fails with `PRICE_CHANGED` and lists what moved. Show the customer the new total, get their approval again, and retry with `accept_changes: true`.", "security": [ { "oauth2": [ "checkout.write" ] }, { "apiKey": [] } ], "parameters": [ { "name": "checkout_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "confirmation" ], "properties": { "confirmation": { "type": "boolean", "const": true, "description": "Must be literally true." }, "accept_changes": { "type": "boolean", "default": false, "description": "Set only after showing the customer a changed total." } } }, "example": { "confirmation": true } } } }, "responses": { "201": { "description": "The order exists in the database.", "content": { "application/json": { "example": { "success": true, "order": { "id": "24", "order_number": "ORD-1788178031995-4425", "status": "pending", "payment_status": "unpaid", "payment_method": "cod", "subtotal": 268, "discount": 0, "delivery_fee": 60, "total": 328, "currency": "BDT", "customer_name": "Ashikur Rahman", "shipping_address": "House 12, Block B, Mirpur 12, Dhaka", "url": "https://nemahbites.com/order/ORD-1788178031995-4425" } } } } }, "409": { "description": "`CHECKOUT_ALREADY_CONFIRMED`, `PRICE_CHANGED`, `INSUFFICIENT_STOCK` or `DUPLICATE_REQUEST`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "`CHECKOUT_EXPIRED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "`CONFIRMATION_REQUIRED` — `confirmation` was not the boolean true.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orders/{id}": { "get": { "tags": [ "Orders" ], "operationId": "getOrder", "summary": "Order status by id or number", "security": [ { "oauth2": [ "checkout.write" ] }, { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Order status." }, "404": { "description": "`ORDER_NOT_FOUND` — including when the order exists but this credential cannot see it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orders/by-number/{order_number}": { "get": { "tags": [ "Orders" ], "operationId": "getOrderByNumber", "summary": "Order status by order number", "security": [ { "oauth2": [ "checkout.write" ] }, { "apiKey": [] } ], "parameters": [ { "name": "order_number", "in": "path", "required": true, "schema": { "type": "string" }, "example": "ORD-1788178031995-4425" } ], "responses": { "200": { "description": "Order status.", "content": { "application/json": { "example": { "order": { "order_number": "ORD-1788178031995-4425", "status": "pending", "payment_status": "unpaid", "fulfillment_status": "awaiting_confirmation", "total": 328, "currency": "BDT", "created_at": "2026-08-31 18:07:11" } } } } }, "404": { "description": "`ORDER_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "example": "agent-req-8f1c2b", "description": "Retrying with the same key and body replays the original response. Strongly recommended on every POST." } }, "securitySchemes": { "oauth2": { "type": "oauth2", "description": "Register in one unauthenticated call at https://nemahbites.com/api/agent/identity, then exchange the assertion at the token endpoint. Full recipe: https://nemahbites.com/auth.md", "flows": { "authorizationCode": { "authorizationUrl": "https://nemahbites.com/authorize", "tokenUrl": "https://nemahbites.com/api/oauth/token", "scopes": { "catalog.read": "Read the catalog", "checkout.write": "Quote a basket and place a cash-on-delivery order", "orders.read": "Read the customer's own orders", "profile.read": "Read the customer's contact details", "loyalty.read": "Read linked customer rewards and previews", "loyalty.write": "Redeem only at approved checkout confirmation" } } } }, "apiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Long-lived server-to-server credential, issued by the store." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "PRODUCT_NOT_FOUND", "OUT_OF_STOCK", "INSUFFICIENT_STOCK", "CHECKOUT_EXPIRED", "CHECKOUT_NOT_FOUND", "CHECKOUT_ALREADY_CONFIRMED", "PRICE_CHANGED", "DELIVERY_UNAVAILABLE", "INVALID_ADDRESS", "INVALID_PAYMENT_METHOD", "CONFIRMATION_REQUIRED", "ORDER_CREATION_FAILED", "ORDER_NOT_FOUND", "INVALID_STATUS_TRANSITION", "CANCELLATION_NOT_ALLOWED", "DUPLICATE_REQUEST", "IDEMPOTENCY_KEY_REUSED", "VALIDATION_ERROR", "UNAUTHORIZED", "INSUFFICIENT_SCOPE", "CUSTOMER_NOT_LINKED", "FORBIDDEN", "RATE_LIMITED", "FEATURE_DISABLED", "INTERNAL_ERROR" ] }, "message": { "type": "string", "description": "Plain language, safe to show a customer." }, "details": { "type": "object", "additionalProperties": true } } } } }, "Pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "Money": { "type": "object", "properties": { "amount": { "type": "number", "description": "What the customer pays per unit, after the product discount." }, "currency": { "type": "string", "const": "BDT" }, "list_amount": { "type": "number", "description": "Price before the discount." }, "discount_percent": { "type": "number" }, "per_unit": { "type": [ "object", "null" ], "description": "Comparable unit price. Null when the pack size is unknown — never compare it against a value you estimated yourself.", "properties": { "amount": { "type": "number" }, "per": { "type": "string", "examples": [ "100g", "100ml" ] } } } } }, "PackSize": { "type": "object", "description": "Derived from the product name (\"Oreo Soft Cake 16g\"), not from a label reading. Null values mean unknown, never zero.", "properties": { "value": { "type": [ "number", "null" ], "description": "Grams for solids, millilitres for liquids." }, "unit": { "type": [ "string", "null" ], "enum": [ "g", "ml", null ] }, "count": { "type": [ "integer", "null" ], "description": "Pieces, bars or sticks, when the name states one." }, "display": { "type": [ "string", "null" ], "examples": [ "148g (4 pieces)", "300ml" ] }, "source": { "type": [ "string", "null" ], "enum": [ "name", "name_multiplier", "name_bonus", "name_count", null ] } } }, "Product": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "sku": { "type": "string", "description": "Internal catalogue SKU; falls back to the stable slug when absent. Slug lookup remains supported." }, "slug": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "brand": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "category": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "categories": { "type": "array", "items": { "type": "object" } }, "price": { "$ref": "#/components/schemas/Money" }, "size": { "$ref": "#/components/schemas/PackSize" }, "availability": { "type": "string", "enum": [ "in_stock", "low_stock", "out_of_stock", "unavailable" ] }, "stock_quantity": { "type": "integer" }, "can_purchase": { "type": "boolean" }, "url": { "type": "string", "format": "uri" }, "image_url": { "type": [ "string", "null" ], "format": "uri" }, "images": { "type": "array", "items": { "type": "string", "format": "uri" }, "description": "Distinct catalogue photo URLs for this product. Related-product photos are excluded." }, "attributes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" }, "source": { "type": "string" } } } }, "vendor": { "type": [ "string", "null" ], "description": "Product brand or explicitly identified store bundle assembler; see brand_role." }, "brand_role": { "type": [ "string", "null" ], "enum": [ "product_brand", "bundle_assembler", null ] }, "is_bundle": { "type": "boolean", "description": "Store-curated selection with component records. This is not Google's main-product bundle flag." }, "components": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "quantity": { "type": "number" }, "brand": { "type": [ "string", "null" ] } } } }, "shipping_measurements": { "type": [ "object", "null" ], "description": "Recorded packed-item measurements, distinct from net product size. Null means not measured; never infer from food net weight.", "properties": { "weight": { "type": [ "object", "null" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "const": "kg" } } }, "dimensions": { "type": [ "object", "null" ], "properties": { "length": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "unit": { "type": "string", "const": "cm" } } } } }, "evidence_gaps": { "type": "object", "properties": { "additional_photos_needed": { "type": "integer" }, "packed_weight_missing": { "type": "boolean" }, "packed_dimensions_missing": { "type": "boolean" }, "brand_missing": { "type": "boolean" } } }, "gtin": { "type": [ "string", "null" ] }, "mpn": { "type": [ "string", "null" ] }, "rating": { "type": [ "number", "null" ], "description": "Null unless genuine customer ratings exist." }, "min_order_quantity": { "type": "integer" }, "max_order_quantity": { "type": "integer" } } }, "ProductDetail": { "allOf": [ { "$ref": "#/components/schemas/Product" }, { "type": "object", "properties": { "country_of_origin": { "type": [ "string", "null" ] }, "manufacturer": { "type": [ "string", "null" ] }, "ingredients": { "type": [ "string", "null" ], "description": "Kept for compatibility. Prefer food_safety." }, "allergen_info": { "type": [ "string", "null" ], "description": "Kept for compatibility. Prefer food_safety — a null here means the label has not been transcribed, NOT that the product is allergen-free." }, "food_safety": { "type": "object", "description": "Authoritative statement of what nemahBites knows about this product's contents. Read `status` before answering any allergen, dietary, religious or medical question. `unknown` means the physical label has never been transcribed: it is not evidence of absence, and an agent must not convert it into a safety claim. When status is not `verified` a `guidance` string spells out what may and may not be said.", "properties": { "status": { "type": "string", "enum": [ "verified", "unknown", "not_applicable" ] }, "ingredients": { "type": [ "string", "null" ] }, "allergens": { "type": [ "string", "null" ] }, "nutrition": { "type": [ "string", "null" ] }, "verified_at": { "type": [ "string", "null" ], "format": "date" }, "source": { "type": [ "string", "null" ] }, "guidance": { "type": "string" } } }, "storage_instructions": { "type": [ "string", "null" ] }, "best_before": { "type": [ "string", "null" ], "format": "date" }, "variants": { "type": "array", "items": {}, "description": "Always empty: each pack size is a separate product." }, "variant_model": { "type": "string" } } } ] }, "Availability": { "type": "object", "properties": { "product_id": { "type": "string" }, "name": { "type": "string" }, "availability": { "type": "string", "enum": [ "in_stock", "low_stock", "out_of_stock", "unavailable" ] }, "stock_quantity": { "type": "integer" }, "can_purchase": { "type": "boolean" }, "requested_quantity": { "type": "integer" }, "available_quantity": { "type": "integer" } } }, "CatalogFeed": { "type": "object", "properties": { "version": { "type": "string" }, "store": { "type": "string" }, "currency": { "type": "string", "const": "BDT" }, "generated_at": { "type": "string", "format": "date-time" }, "total": { "type": "integer" }, "next": { "type": [ "string", "null" ], "format": "uri" }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } } } }, "LineItemInput": { "type": "object", "required": [ "product_id", "quantity" ], "properties": { "product_id": { "type": "integer", "description": "The numeric `id` from the catalog API." }, "quantity": { "type": "integer", "minimum": 1, "maximum": 99 } } }, "AddressInput": { "type": "object", "required": [ "address_line", "city" ], "properties": { "address_line": { "type": "string", "example": "House 12, Block B", "description": "House and road, or a landmark the courier can find." }, "area": { "type": "string", "example": "Mirpur 12" }, "city": { "type": "string", "example": "Dhaka", "description": "City or district. Must be inside Bangladesh." }, "postcode": { "type": "string" }, "country": { "type": "string", "default": "Bangladesh" } } }, "Checkout": { "type": "object", "properties": { "checkout_id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending_confirmation", "confirmed", "expired", "cancelled" ] }, "items": { "type": "array", "items": { "type": "object" } }, "subtotal": { "type": "number" }, "discount": { "type": "number" }, "delivery_fee": { "type": "number" }, "total": { "type": "number" }, "currency": { "type": "string", "const": "BDT" }, "payment_method": { "type": "string" }, "customer": { "type": "object" }, "shipping_address": { "type": "object" }, "delivery": { "type": "object" }, "expires_at": { "type": "string", "format": "date-time" }, "confirmation_required": { "type": "boolean" }, "next_step": { "type": "string" }, "changes": { "type": "array", "items": { "type": "object" }, "description": "Present only when something moved since the quote." } } } } } }