{"openapi":"3.1.0","info":{"title":"UrbanChat IMS — Urbanchat API","version":"1.3.0","description":"Browse the catalogue and stock, place orders and look up customers for one company. The API key decides the company. Money and quantities are decimal strings."},"servers":[{"url":"https://www.chatcom.in/api/v1/urbanchat"}],"security":[{"apiKey":[]},{"bearer":[]}],"paths":{"/catalog/products":{"get":{"operationId":"browseCatalog","summary":"Browse and search products, grouped with their variants","parameters":[{"name":"search","in":"query","description":"Words from a name or description, a SKU, a barcode or an option such as a colour","schema":{"default":"","description":"Words from a name or description, a SKU, a barcode or an option such as a colour","type":"string","maxLength":100}},{"name":"category","in":"query","description":"A category id, slug or name; includes its sub-categories","schema":{"default":"","description":"A category id, slug or name; includes its sub-categories","type":"string","maxLength":80}},{"name":"brand","in":"query","description":"A brand id, slug or name","schema":{"default":"","description":"A brand id, slug or name","type":"string","maxLength":80}},{"name":"in_stock","in":"query","description":"Only products with a variant available to order now","schema":{"description":"Only products with a variant available to order now","type":["boolean","string"]}},{"name":"limit","in":"query","schema":{"default":20,"type":"integer","minimum":1,"maximum":50}},{"name":"offset","in":"query","schema":{"default":0,"type":"integer","minimum":0,"maximum":10000}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"count":{"type":"integer"},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"has_more":{"type":"boolean"}},"required":["data","count","total","limit","offset","has_more"]}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}}}},"/catalog/products/{id}":{"get":{"operationId":"getCatalogProduct","summary":"One product in full, by product id or SKU, or a variant sku, id or barcode","parameters":[{"name":"id","in":"path","required":true,"description":"Product id or SKU, or a variant sku, id or barcode","schema":{"type":"string","maxLength":64}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/Product"},{"type":"object","properties":{"matched_variant_id":{"type":["string","null"]},"images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"alt":{"type":["string","null"]},"variant_id":{"type":["string","null"]}},"required":["url","alt","variant_id"]}}},"required":["matched_variant_id","images"]}]}},"required":["data"]}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}}},"/catalog/categories":{"get":{"operationId":"listCategories","summary":"Categories and brands, with product counts","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"parent_id":{"type":["string","null"]},"product_count":{"type":"integer"}},"required":["id","name","slug","parent_id","product_count"]}},"brands":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"product_count":{"type":"integer"}},"required":["id","name","slug","product_count"]}}},"required":["categories","brands"]}},"required":["data"]}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}}}},"/orders":{"post":{"operationId":"createOrder","summary":"Create and confirm an order. Idempotent on external_reference","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderRequest"}}}},"responses":{"200":{"description":"Already placed with this external_reference","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Order"},"duplicate":{"const":true}},"required":["data","duplicate"]}}}},"201":{"description":"Created and confirmed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Order"}},"required":["data"]}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"409":{"$ref":"#/components/responses/E409"},"413":{"$ref":"#/components/responses/E413"},"415":{"$ref":"#/components/responses/E415"},"422":{"$ref":"#/components/responses/E422"},"429":{"$ref":"#/components/responses/E429"},"500":{"$ref":"#/components/responses/E500"}}}},"/orders/{reference}":{"get":{"operationId":"getOrder","summary":"One order by order number, order_id or external_reference","parameters":[{"name":"reference","in":"path","required":true,"description":"Order number, order_id or external_reference","schema":{"type":"string","maxLength":100}},{"name":"phone","in":"query","description":"The customer's phone. When given, the order is returned only if it is theirs","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/OrderSummary"},{"type":"object","properties":{"customer":{"type":"object","properties":{"name":{"type":"string"},"phone":{"type":["string","null"]}},"required":["name","phone"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/OrderLine"}},"shipment":{"oneOf":[{"type":"object","properties":{"awb":{"type":["string","null"]},"courier":{"type":["string","null"]},"status":{"type":"string"},"status_label":{"type":"string"},"tracking_url":{"type":["string","null"]},"delivered_at":{"type":["string","null"]}},"required":["awb","courier","status","status_label","tracking_url","delivered_at"]},{"type":"null"}]},"invoice":{"oneOf":[{"type":"object","properties":{"invoice_number":{"type":"string"},"payment_status":{"type":"string"},"total":{"type":"string","description":"A decimal, as a string"},"amount_due":{"type":"string","description":"A decimal, as a string"}},"required":["invoice_number","payment_status","total","amount_due"]},{"type":"null"}]}},"required":["customer","items","shipment","invoice"]}]}},"required":["data"]}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}}},"/customers":{"get":{"operationId":"findCustomer","summary":"Find a customer by phone","parameters":[{"name":"phone","in":"query","required":true,"schema":{"type":"string","minLength":7,"maxLength":20}},{"name":"recent_orders","in":"query","schema":{"default":5,"type":"integer","minimum":1,"maximum":20}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"customer_id":{"type":"string"},"name":{"type":"string"},"phone":{"type":["string","null"]},"email":{"type":["string","null"]},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"pincode":{"type":["string","null"]},"shipping_address":{"type":["string","null"]},"whatsapp_opted_out":{"type":"boolean"},"recent_orders":{"type":"array","items":{"$ref":"#/components/schemas/OrderSummary"}}},"required":["customer_id","name","phone","email","city","state","pincode","shipping_address","whatsapp_opted_out","recent_orders"]}},"required":["data"]}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"X-API-KEY"},"bearer":{"type":"http","scheme":"bearer","description":"The same ucik_ key"}},"schemas":{"Product":{"type":"object","properties":{"product_id":{"type":"string"},"sku":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"category":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"parent":{"type":["string","null"]}},"required":["id","name","slug","parent"]},{"type":"null"}]},"brand":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},{"type":"null"}]},"unit":{"type":"string"},"hsn_code":{"type":["string","null"]},"tax_rate":{"type":"string","description":"A decimal, as a string"},"currency":{"const":"INR"},"price_range":{"type":"object","properties":{"min":{"type":"string","description":"A decimal, as a string"},"max":{"type":"string","description":"A decimal, as a string"}},"required":["min","max"]},"options":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"available":{"type":"string","description":"A decimal, as a string"},"available_total":{"type":"string","description":"A decimal, as a string"},"in_stock":{"type":"boolean"},"image_url":{"type":["string","null"]},"variants":{"type":"array","items":{"$ref":"#/components/schemas/Variant"}}},"required":["product_id","sku","name","description","category","brand","unit","hsn_code","tax_rate","currency","price_range","options","available","available_total","in_stock","image_url","variants"]},"Variant":{"type":"object","properties":{"variant_id":{"type":"string"},"sku":{"type":"string","description":"Send as items[].product_id to place an order"},"barcode":{"type":["string","null"]},"name":{"type":"string"},"attributes":{"type":"object","additionalProperties":{"type":"string"}},"selling_price":{"type":"string","description":"A decimal, as a string"},"mrp":{"type":"string","description":"A decimal, as a string"},"available":{"type":"string","description":"Units that can be ordered now"},"available_total":{"type":"string","description":"A decimal, as a string"},"in_stock":{"type":"boolean"},"image_url":{"type":["string","null"],"description":"Signed, valid 10 minutes"}},"required":["variant_id","sku","barcode","name","attributes","selling_price","mrp","available","available_total","in_stock","image_url"]},"OrderRequest":{"type":"object","properties":{"customer":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"phone":{"type":"string","minLength":7,"maxLength":20},"email":{"description":"Optional. Saved only when the customer is new","type":"string","maxLength":254,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"required":["name","phone"]},"items":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"product_id":{"type":"string","minLength":1,"maxLength":64},"quantity":{"type":["number","string"]}},"required":["product_id","quantity"]}},"external_reference":{"type":"string","minLength":1,"maxLength":100},"notes":{"type":"string","maxLength":500},"delivery_address":{"type":"object","properties":{"name":{"description":"Recipient, if not the customer","type":"string","maxLength":160},"line1":{"type":"string","minLength":1,"maxLength":200,"description":"House, street and area"},"line2":{"description":"Landmark, second line","type":"string","maxLength":200},"city":{"type":"string","minLength":1,"maxLength":80},"state":{"description":"Optional: worked out from the PIN","type":"string","maxLength":80},"pincode":{"type":"string","pattern":"^\\d{6}$","description":"6-digit Indian PIN code"},"phone":{"description":"Phone for the courier, if not the customer's","type":"string","maxLength":20}},"required":["line1","city","pincode"],"description":"Where to deliver. Leave out to use the customer's address on file."},"payment":{"description":"cod: the courier collects payment on delivery. prepaid (default): already paid.","type":"string","enum":["cod","prepaid"]},"payment_reference":{"description":"Optional. The payment's own reference, e.g. a UPI transaction id, for a prepaid order","type":"string","maxLength":100}},"required":["customer","items","external_reference"]},"Order":{"type":"object","properties":{"order_id":{"type":"string"},"order_number":{"type":"string"},"order_status":{"type":"string"},"amount":{"type":"string","description":"A decimal, as a string"},"currency":{"const":"INR"},"created_at":{"type":"string","format":"date-time"},"external_reference":{"type":"string"},"items":{"type":"array","items":{"$ref":"#/components/schemas/OrderLine"}},"payment":{"enum":["cod","prepaid"]},"delivery_address":{"oneOf":[{"$ref":"#/components/schemas/DeliveryAddress"},{"type":"null"}]}},"required":["order_id","order_number","order_status","amount","currency","created_at","external_reference","items","payment","delivery_address"]},"OrderSummary":{"type":"object","properties":{"order_id":{"type":"string"},"order_number":{"type":"string"},"order_status":{"type":"string"},"status_label":{"type":"string"},"amount":{"type":"string","description":"A decimal, as a string"},"currency":{"const":"INR"},"order_date":{"type":"string","format":"date-time"},"external_reference":{"type":["string","null"]}},"required":["order_id","order_number","order_status","status_label","amount","currency","order_date","external_reference"]},"OrderLine":{"type":"object","properties":{"sku":{"type":"string"},"name":{"type":"string"},"quantity":{"type":"string","description":"A decimal, as a string"},"unit_price":{"type":"string","description":"A decimal, as a string"},"line_total":{"type":"string","description":"A decimal, as a string"}},"required":["sku","name","quantity","unit_price","line_total"]},"DeliveryAddress":{"type":"object","properties":{"name":{"type":["string","null"]},"line1":{"type":"string"},"line2":{"type":["string","null"]},"city":{"type":"string"},"state":{"type":"string"},"pincode":{"type":"string"},"phone":{"type":["string","null"]}},"required":["line1","city","state","pincode"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}},"responses":{"E400":{"description":"validation_failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E409":{"description":"insufficient_stock","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E413":{"description":"validation_failed — body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E415":{"description":"validation_failed — not JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E422":{"description":"unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E429":{"description":"rate_limited — see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E500":{"description":"internal — safe to retry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}