{ "name": "nemahBites Agent Commerce API", "version": "v1", "commerce_config": { "schema_version": "1.0", "currency": "BDT", "business_clock": { "business_timezone": "Asia/Dhaka", "business_day_reset": "06:00" }, "business_location": { "name": "nemahBites", "address": "Road-6, Gudaraghat, Dhaka 1212, Bangladesh", "phone": "01575558436", "telephone": "+8801575558436", "whatsapp_url": "https://wa.me/8801575558436", "postal_address": { "@type": "PostalAddress", "streetAddress": "Road-6, Gudaraghat", "addressLocality": "Dhaka", "postalCode": "1212", "addressCountry": "BD" }, "timezone": "Asia/Dhaka", "opens": "08:00", "closes": "23:00", "days": [ "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday" ], "page": "/dhaka", "maps_search_url": "https://www.google.com/maps/search/?api=1&query=Road-6%2C%20Gudaraghat%2C%20Dhaka%201212%2C%20Bangladesh", "maps_pin_verified": false, "pickup_availability": "confirm_with_support", "walk_in_availability": "confirm_with_support" }, "retail_delivery": { "scope": "retail", "confirmation": "checkout_destination_specific", "free_delivery_comparison": "greater_than_or_equal", "free_delivery_basis": "eligible_merchandise_after_discounts", "coverage": "All 64 districts of Bangladesh.", "zones": [ { "id": "inside_dhaka", "label": "Inside Dhaka", "fee": 60, "transit_days": { "min": 0, "max": 1 } }, { "id": "outside_dhaka", "label": "Outside Dhaka", "fee": 120, "transit_days": { "min": 2, "max": 3 } } ], "free_delivery_over": 2500, "same_day_cutoff_local": "13:00", "handling_days": { "min": 0, "max": 1 }, "timezone": "Asia/Dhaka" }, "wholesale_delivery": { "scope": "wholesale", "confirmation": "after_quote", "delivery_fee": null, "currency": "BDT", "retail_rates_apply_automatically": false, "retail_free_delivery_applies_automatically": false, "note": { "en": "For wholesale orders, delivery charge is confirmed after the quote and before you approve the order. Retail delivery rates and the retail free-delivery threshold do not apply automatically. Stock and delivery timing are confirmed separately.", "bn": "পাইকারি অর্ডারে কোটেশন দেওয়ার পরে, আপনার অর্ডার অনুমোদনের আগে ডেলিভারি চার্জ নিশ্চিত করা হয়। খুচরা ডেলিভারি চার্জ ও ফ্রি ডেলিভারির সীমা স্বয়ংক্রিয়ভাবে প্রযোজ্য নয়। মজুত ও ডেলিভারির সময় আলাদাভাবে নিশ্চিত করা হয়।" } }, "wholesale": { "enabled": true, "minimum_quantity_per_line": 20, "quantity_basis": "sellable_outer_pack_per_product_id", "discount_basis": "retail_price_after_promotions", "rounding": "whole_bdt_each_pricing_step", "tiers": [ { "min_quantity": 20, "percent_off_retail": 10, "label": "20+ units", "label_bangla": "২০+ ইউনিট" }, { "min_quantity": 50, "percent_off_retail": 12, "label": "50+ units", "label_bangla": "৫০+ ইউনিট" }, { "min_quantity": 100, "percent_off_retail": 15, "label": "100+ units", "label_bangla": "১০০+ ইউনিট" } ], "workflow": { "checkout_mode": "merchant_approved_quote", "automatic_checkout": false, "points_redemption_supported": false, "points_earning_supported": false, "next_step": "submit_enquiry_for_stock_delivery_and_final_quote" } }, "rewards": { "enabled": true, "earn_points_per_100_bdt": 3, "bdt_per_100_points": 100, "credited_when": "order_delivered", "expires_after_days": 180, "expiry_scope": "each_earning_transaction", "redemption_order": "earliest_expiring_first", "max_percent_of_order_redeemable": 20, "min_redeem_points": 10, "signup_points": 50, "approved_review_points": 20, "wholesale_orders": { "earning_supported": false, "redemption_supported": false, "checkout_mode": "merchant_approved_quote" }, "daily_checkin": { "business_timezone": "Asia/Dhaka", "business_day_reset": "06:00", "configured_points": 2, "available": true, "status": "available_to_signed_in_customer", "intended_frequency": "once_per_day", "customer_page": "/account", "status_endpoint": "/api/loyalty/checkin" }, "agent_operations": { "read_public_rules": true, "read_customer_balance": true, "redeem_points": true, "redeem_via": "checkout_confirm", "claim_checkin": false, "claim_checkin_reason": "reserved_for_human_sessions" } }, "revision": "27d6a17846c50a1ce38dffb715cece5abce7b54b72ae438f525c7ec12f01b8ea", "freshness": { "live_endpoint": "/api/commerce/config", "cache_policy": "no-store", "static_content": "SSG snapshots require a rebuild after admin changes. Quotes are estimates; order confirmation revalidates prices and rewards." } }, "description": "Search, price and order imported chocolate, snacks and groceries for delivery in Bangladesh. Provider-neutral: the same API serves MCP clients, A2A agents and any HTTP client.", "store": { "name": "nemahBites", "website": "https://nemahbites.com", "country": "BD", "currency": "BDT", "languages": [ "en", "bn" ] }, "openapi": "https://nemahbites.com/api/agent/v1/openapi.json", "documentation": "https://nemahbites.com/developers", "mcp_endpoint": "https://nemahbites.com/api/mcp", "endpoints": { "commerce_config": { "method": "GET", "url": "https://nemahbites.com/api/commerce/config", "auth": "none" }, "reward_balance": { "method": "GET", "url": "https://nemahbites.com/api/agent/v1/loyalty", "auth": "loyalty.read", "customer_link_required": true }, "reward_redemption_preview": { "method": "POST", "url": "https://nemahbites.com/api/agent/v1/loyalty/preview", "auth": "loyalty.read", "customer_link_required": true, "read_only": true }, "capabilities": { "method": "GET", "url": "https://nemahbites.com/api/agent/v1/capabilities", "auth": "none" }, "whoami": { "method": "GET", "url": "https://nemahbites.com/api/agent/v1/whoami", "auth": "none" }, "search_products": { "method": "GET", "url": "https://nemahbites.com/api/agent/v1/products?q=", "auth": "none" }, "get_product": { "method": "GET", "url": "https://nemahbites.com/api/agent/v1/products/{id}", "auth": "none" }, "availability": { "method": "GET", "url": "https://nemahbites.com/api/agent/v1/products/{id}/availability", "auth": "none" }, "catalog_feed": { "method": "GET", "url": "https://nemahbites.com/api/agent/v1/catalog", "auth": "none" }, "categories": { "method": "GET", "url": "https://nemahbites.com/api/agent/v1/categories", "auth": "none" }, "brands": { "method": "GET", "url": "https://nemahbites.com/api/agent/v1/brands", "auth": "none" }, "shipping_quote": { "method": "POST", "url": "https://nemahbites.com/api/agent/v1/shipping/quote", "auth": "none" }, "policies": { "method": "GET", "url": "https://nemahbites.com/api/agent/v1/policies", "auth": "none" }, "wholesale_search": { "method": "GET", "url": "https://nemahbites.com/api/agent/v1/wholesale/products?q={query}&quantity={quantity}", "auth": "none" }, "wholesale_eligibility": { "method": "GET", "url": "https://nemahbites.com/api/agent/v1/wholesale/eligibility?product_id={id}&quantity={quantity}", "auth": "none" }, "wholesale_stock": { "method": "GET", "url": "https://nemahbites.com/api/agent/v1/wholesale/stock?product_id={id}&quantity={quantity}", "auth": "none" }, "wholesale_quote": { "method": "POST", "url": "https://nemahbites.com/api/agent/v1/wholesale/quote", "auth": "none" }, "wholesale_enquiry": { "method": "POST", "url": "https://nemahbites.com/api/agent/v1/wholesale/enquiry", "auth": "checkout.write", "confirmation_required": true, "idempotency_required": true }, "create_checkout": { "method": "POST", "url": "https://nemahbites.com/api/agent/v1/checkouts", "auth": "checkout.write" }, "get_checkout": { "method": "GET", "url": "https://nemahbites.com/api/agent/v1/checkouts/{checkout_id}", "auth": "checkout.write" }, "confirm_order": { "method": "POST", "url": "https://nemahbites.com/api/agent/v1/checkouts/{checkout_id}/confirm", "auth": "checkout.write", "body": { "confirmation": true } }, "order_status": { "method": "GET", "url": "https://nemahbites.com/api/agent/v1/orders/by-number/{order_number}", "auth": "checkout.write" }, "cancel_order": { "method": "POST", "url": "https://nemahbites.com/api/agent/v1/orders/{order_number}/cancel", "auth": "checkout.write" } }, "authentication": { "how": "POST {\"type\":\"anonymous\",\"agent_name\":\"Your Agent\"} to https://nemahbites.com/api/agent/identity, then exchange the identity_assertion at https://nemahbites.com/api/oauth/token with grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer.", "recipe": "https://nemahbites.com/auth.md", "authorization_server": "https://nemahbites.com/.well-known/oauth-authorization-server", "protected_resource": "https://nemahbites.com/.well-known/oauth-protected-resource", "scopes": { "catalog.read": "Read the catalog (also available with no token at all).", "checkout.write": "Quote a basket and place a cash-on-delivery order for a named customer.", "orders.read": "Read a specific customer's own order history (needs their browser approval).", "profile.read": "Read a specific customer's contact details (needs their browser approval).", "loyalty.read": "Read only the linked customer’s balance and redemption estimates.", "loyalty.write": "Request points at customer-approved checkout confirmation; no standalone debit." }, "server_to_server": "Long-lived integrations may present X-API-Key instead. Contact the store to be issued one." }, "agent_identity": { "web_bot_auth": { "verifies_inbound": true, "signs_outbound": true, "algorithm": "ed25519", "tag": "web-bot-auth", "components": [ "@authority", "signature-agent" ], "our_directory": "https://nemahbites.com/.well-known/http-message-signatures-directory", "note": "Send Signature-Agent, Signature-Input and Signature (RFC 9421) and this origin will fetch your published key and verify them. Nothing is gated behind it yet; it exists so you are never mistaken for something impersonating you." }, "verified_operators": "OpenAI, Perplexity, Google and Microsoft are additionally verified against the address ranges they publish. A request carrying one of their crawler names from outside those ranges is refused.", "check_yourself": "https://nemahbites.com/api/agent/v1/whoami" }, "ordering_flow": [ "1. GET /products?q=… to find the item and its numeric id.", "2. GET /products/{id}/availability to confirm the quantity is in stock.", "3. POST /checkouts with items, customer name and phone, and the delivery address. This creates NO order.", "4. Show the customer the returned totals and ask whether to place the order.", "5. Only after they agree, POST /checkouts/{id}/confirm with {\"confirmation\": true}.", "6. GET /orders/by-number/{order_number} to track it afterwards. The response carries a `cancellation` block saying whether it can still be cancelled.", "7. POST /orders/{order_number}/cancel if the customer changes their mind, within the window GET /policies publishes." ], "wholesale_flow": [ "Search /wholesale/products with q and quantity; select the exact outer-pack SKU.", "Check /wholesale/eligibility and /wholesale/stock with product_id and quantity.", "POST /wholesale/quote with items. This is merchandise only, not a reservation or delivery commitment.", "Show the quote and contact details; obtain permission before POST /wholesale/enquiry with checkout.write, confirmation=true and Idempotency-Key.", "The shop must approve bulk stock, delivery and final quote before customer order approval. Automatic wholesale checkout and points redemption are not supported." ], "rules": [ "Prices, stock, delivery and totals are always computed by this server. Values sent by a client are ignored.", "An order is never created without an explicit {\"confirmation\": true} from a customer who has seen the total.", "If the basket changed since it was quoted, confirmation fails with PRICE_CHANGED and reports what moved.", "Send an Idempotency-Key header on every POST; retrying with the same key replays the original result instead of ordering twice." ], "payment_methods": [ { "slug": "cod", "name": "Cash on Delivery", "type": "manual", "capability": "agent_checkout", "note": "An agent can place this order end to end. The customer pays the courier on delivery." }, { "slug": "eps", "name": "Card / Mobile Banking", "type": "eps", "capability": "browser_only", "note": "Pay using local digital payment methods (mobile banking, cards or internet banking) through EPS in the customer's own browser at https://nemahbites.com/checkout. EPS supports bKash, Nagad, Rocket, Visa and Mastercard; use any method available on the EPS screen for this transaction. Payment is confirmed only after gateway verification. Never ask for an OTP, PIN or card security details." } ], "customer_order_tracking": { "url": "https://nemahbites.com/track-order", "requires": "Private tracking code from order success or account order details", "returns": "Current status and recorded placed, confirmed, processing, shipped and delivered times", "privacy": "No customer name, phone or address in public lookup. Never publish tracking codes." }, "delivery": { "country": "Bangladesh", "coverage": "All 64 districts of Bangladesh.", "inside_dhaka_fee": 60, "outside_dhaka_fee": 120, "free_shipping_over": 2500, "currency": "BDT", "zones": [ { "id": "inside_dhaka", "label": "Inside Dhaka", "fee": 60, "transit_days": { "min": 0, "max": 1 } }, { "id": "outside_dhaka", "label": "Outside Dhaka", "fee": 120, "transit_days": { "min": 2, "max": 3 } } ], "same_day_cutoff_local": "13:00" }, "policies": "https://nemahbites.com/api/agent/v1/policies", "limits": { "catalog_reads_per_minute": 120, "checkouts_per_hour": 30, "confirmations_per_hour": 10, "checkout_expiry_minutes": 15, "max_products_per_checkout": 40, "max_quantity_per_line": 99 }, "error_codes": [ "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" ] }