{ "openapi": "3.1.0", "info": { "title": "The Spirit of Mithila API", "version": "2026-05-01", "summary": "Access to Mithila accounts, the marketplace catalog, orders and seller fulfilment.", "description": "Authenticate with an API key (`Authorization: Bearer mth_live_…` or `mth_test_…`) or an OAuth 2.0 access token.\n\nEvery response carries `X-Request-Id`. Errors use one shape: `{\"error\": {\"code\", \"message\", \"request_id\"}}`. Lists are paginated with `page` and `per_page` and return `meta` and `links`.", "contact": { "name": "Mithila developer support", "url": "https://support.vaxhost.com/tickets/create?category=technical" }, "termsOfService": "https://vaxhost.com/p/terms" }, "servers": [ { "url": "https://developers.vaxhost.com/api/v1", "description": "Production (live and test keys)" } ], "security": [ { "apiKey": [] }, { "oauth2": [] } ], "tags": [ { "name": "Account", "description": "The account a credential acts for." }, { "name": "Platform", "description": "Public information about the Mithila ecosystem." }, { "name": "Catalog", "description": "Marketplace categories and products (active listings from approved sellers). Amounts are integer paise (INR)." }, { "name": "Orders", "description": "Orders the account placed as a customer." }, { "name": "Seller", "description": "Orders placed with the store the account owns or works for (approved sellers only)." } ], "paths": { "/me": { "get": { "operationId": "getMe", "tags": [ "Account" ], "summary": "Get the current account", "description": "Returns the profile of the user who owns the API key, or who authorised the OAuth access token.", "security": [ { "apiKey": [] }, { "oauth2": [ "profile.read" ] } ], "x-scope": "profile.read", "responses": { "200": { "description": "The account.", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Quote this when contacting support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Me" }, "meta": { "type": "object", "properties": { "livemode": { "type": "boolean", "description": "false for test (sandbox) keys" } } } } }, "example": { "data": { "id": "42", "name": "Sita Devi", "email": "sita@example.com", "email_verified": true, "phone_verified": true, "locale": "hi", "avatar_url": null, "created_at": "2026-05-01T10:00:00+05:30" }, "meta": { "livemode": true } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/apps": { "get": { "operationId": "listApps", "tags": [ "Platform" ], "summary": "List Mithila apps", "description": "Public, enabled apps (marketplace, music, video, learning…) with their URLs. No credentials needed.", "security": [ {} ], "parameters": [ { "name": "page", "in": "query", "description": "Page number, from 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page (1–100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "A page of apps.", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Quote this when contacting support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/App" } }, "meta": { "$ref": "#/components/schemas/PageMeta" }, "links": { "$ref": "#/components/schemas/PageLinks" } } }, "example": { "data": [ { "key": "music", "name": "Mithila Music", "short_name": "Music", "description": "Stream songs, albums and playlists from independent artists.", "url": "https://music.vaxhost.com/", "installable": true, "maintenance": false, "accent_color": "#E0177A", "icon": "https://music.vaxhost.com/icons/music/icon-192.png" } ], "meta": { "page": 1, "per_page": 20, "total": 10, "last_page": 1 }, "links": { "next": null, "prev": null } } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/status": { "get": { "operationId": "getStatus", "tags": [ "Platform" ], "summary": "API health", "description": "Use for uptime checks. Returns 503 when a dependency is down. No credentials needed.", "security": [ {} ], "responses": { "200": { "description": "Healthy.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Status" } } }, "example": { "data": { "status": "ok", "api_version": "2026-05-01", "time": "2026-05-01T10:00:00+05:30", "components": { "api": "ok", "database": "ok" } } } } } }, "503": { "description": "Degraded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Status" } } } } } } } } }, "/categories": { "get": { "operationId": "listCategories", "tags": [ "Catalog" ], "summary": "List categories", "description": "Active marketplace categories, parents before children. Build the tree with `parent_id`.", "security": [ { "apiKey": [] }, { "oauth2": [ "catalog.read" ] } ], "x-scope": "catalog.read", "parameters": [ { "name": "parent", "in": "query", "description": "Only children of this category slug; `root` for top-level categories.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number, from 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page (1–100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } } ], "responses": { "200": { "description": "A page of categories.", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Quote this when contacting support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } }, "meta": { "$ref": "#/components/schemas/PageMeta" }, "links": { "$ref": "#/components/schemas/PageLinks" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/products": { "get": { "operationId": "listProducts", "tags": [ "Catalog" ], "summary": "Search products", "description": "Active products from approved sellers. Prices are integer paise, GST inclusive.", "security": [ { "apiKey": [] }, { "oauth2": [ "catalog.read" ] } ], "x-scope": "catalog.read", "parameters": [ { "name": "q", "in": "query", "description": "Search words.", "schema": { "type": "string", "maxLength": 120 } }, { "name": "category", "in": "query", "description": "Category slug (includes its sub-categories).", "schema": { "type": "string" } }, { "name": "seller", "in": "query", "description": "Store slug.", "schema": { "type": "string" } }, { "name": "min_price", "in": "query", "description": "Minimum price in paise.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "max_price", "in": "query", "description": "Maximum price in paise.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "in_stock", "in": "query", "description": "Only products in stock.", "schema": { "type": "boolean" } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "popular", "newest", "price_asc", "price_desc", "rating", "discount", "relevance" ] } }, { "name": "page", "in": "query", "description": "Page number, from 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page (1–100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "A page of products.", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Quote this when contacting support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "meta": { "$ref": "#/components/schemas/PageMeta" }, "links": { "$ref": "#/components/schemas/PageLinks" } } } } } }, "404": { "description": "Not found (or not yours).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/products/{slug}": { "get": { "operationId": "getProduct", "tags": [ "Catalog" ], "summary": "Get a product", "description": "One active product with images and variants.", "security": [ { "apiKey": [] }, { "oauth2": [ "catalog.read" ] } ], "x-scope": "catalog.read", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The product.", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Quote this when contacting support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProductDetail" } } } } } }, "404": { "description": "Not found (or not yours).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/orders": { "get": { "operationId": "listOrders", "tags": [ "Orders" ], "summary": "List your orders", "description": "Orders the account placed as a customer, newest first.", "security": [ { "apiKey": [] }, { "oauth2": [ "orders.read" ] } ], "x-scope": "orders.read", "parameters": [ { "name": "status", "in": "query", "description": "Only orders in this status.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number, from 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page (1–100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "A page of orders.", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Quote this when contacting support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "meta": { "$ref": "#/components/schemas/PageMeta" }, "links": { "$ref": "#/components/schemas/PageLinks" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/orders/{number}": { "get": { "operationId": "getOrder", "tags": [ "Orders" ], "summary": "Get one of your orders", "description": "Items, per-seller parts, shipment tracking and delivery address. 404 for orders of other accounts.", "security": [ { "apiKey": [] }, { "oauth2": [ "orders.read" ] } ], "x-scope": "orders.read", "parameters": [ { "name": "number", "in": "path", "required": true, "description": "Order number, e.g. MTH-2605-00042.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The order.", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Quote this when contacting support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/OrderDetail" } } } } } }, "404": { "description": "Not found (or not yours).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/seller/orders": { "get": { "operationId": "listSellerOrders", "tags": [ "Seller" ], "summary": "List your store's orders", "description": "Orders with the store the account owns, or works for with an orders role. Returns `403 not_a_seller` for other accounts. The delivery address is included until the order is delivered or cancelled.", "security": [ { "apiKey": [] }, { "oauth2": [ "seller.orders.read" ] } ], "x-scope": "seller.orders.read", "parameters": [ { "name": "status", "in": "query", "description": "Only orders in this status.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number, from 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page (1–100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "A page of store orders.", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Quote this when contacting support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SellerOrder" } }, "meta": { "$ref": "#/components/schemas/PageMeta" }, "links": { "$ref": "#/components/schemas/PageLinks" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/seller/orders/{id}/ship": { "patch": { "operationId": "shipSellerOrder", "tags": [ "Seller" ], "summary": "Mark a store order shipped", "description": "Records the courier and AWB and moves a confirmed or packed order to shipped; the customer is notified. Needs a live key (test keys get `403 live_key_required`). `409 invalid_state` if the order cannot be shipped now.", "security": [ { "apiKey": [] }, { "oauth2": [ "seller.orders.write" ] } ], "x-scope": "seller.orders.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Store order id or number (the `id` or `number` of a SellerOrder).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "courier_name", "awb" ], "properties": { "courier_name": { "type": "string", "maxLength": 100 }, "awb": { "type": "string", "maxLength": 64, "pattern": "^[A-Za-z0-9-]+$" }, "tracking_url": { "type": "string", "format": "uri", "maxLength": 500 } } }, "example": { "courier_name": "India Post", "awb": "EK123456789IN", "tracking_url": "https://www.indiapost.gov.in/" } } } }, "responses": { "200": { "description": "The shipped order.", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Quote this when contacting support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SellerOrder" } } } } } }, "404": { "description": "Not found (or not yours).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The order is not in a state that can be shipped.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "mth_live_… / mth_test_…", "description": "API key created at https://developers.vaxhost.com/keys" }, "oauth2": { "type": "oauth2", "description": "Authorization code flow. PKCE (S256) is required for public clients.", "flows": { "authorizationCode": { "authorizationUrl": "https://account.vaxhost.com/oauth/authorize", "tokenUrl": "https://account.vaxhost.com/oauth/token", "refreshUrl": "https://account.vaxhost.com/oauth/token", "scopes": { "openid": "Know who you are (your Mithila account ID)", "profile": "See your name and profile photo", "email": "See your email address", "profile.read": "Read your profile: name, email and photo", "orders.read": "See your orders", "seller.orders.read": "See your store's orders", "seller.orders.write": "Mark your store's orders as shipped" } } } } }, "schemas": { "Me": { "type": "object", "required": [ "id", "name", "email" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "email_verified": { "type": "boolean" }, "phone_verified": { "type": "boolean" }, "locale": { "type": "string", "enum": [ "en", "hi", "mai" ] }, "avatar_url": { "type": [ "string", "null" ], "format": "uri" }, "created_at": { "type": "string", "format": "date-time" } } }, "App": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "short_name": { "type": "string" }, "description": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "installable": { "type": "boolean" }, "maintenance": { "type": "boolean" }, "accent_color": { "type": "string" }, "icon": { "type": "string", "format": "uri" } } }, "Status": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "degraded" ] }, "api_version": { "type": "string" }, "time": { "type": "string", "format": "date-time" }, "components": { "type": "object", "additionalProperties": { "type": "string" } } } }, "PageMeta": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "last_page": { "type": "integer" } } }, "PageLinks": { "type": "object", "properties": { "next": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] } } }, "Category": { "type": "object", "properties": { "id": { "type": "integer" }, "slug": { "type": "string" }, "name": { "type": "string" }, "parent_id": { "type": [ "integer", "null" ] }, "depth": { "type": "integer" }, "position": { "type": "integer" }, "is_featured": { "type": "boolean" }, "url": { "type": "string", "format": "uri" } } }, "Product": { "type": "object", "properties": { "id": { "type": "integer" }, "slug": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "simple", "variable", "bundle" ] }, "short_description": { "type": [ "string", "null" ] }, "currency": { "type": "string", "const": "INR" }, "price": { "type": "integer", "description": "Paise (INR)." }, "mrp": { "type": "integer", "description": "Paise (INR)." }, "discount_percent": { "type": "integer" }, "in_stock": { "type": "boolean" }, "rating": { "type": "object", "properties": { "average": { "type": "number" }, "count": { "type": "integer" } } }, "category": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "slug": { "type": "string" }, "name": { "type": "string" } } }, "brand": { "type": [ "object", "null" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" } } }, "seller": { "type": [ "object", "null" ], "properties": { "store": { "type": "string" }, "name": { "type": "string" }, "is_official": { "type": "boolean" } } }, "image": { "type": "string", "format": "uri" }, "url": { "type": "string", "format": "uri" }, "published_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ProductDetail": { "type": "object", "properties": { "id": { "type": "integer" }, "slug": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "simple", "variable", "bundle" ] }, "short_description": { "type": [ "string", "null" ] }, "currency": { "type": "string", "const": "INR" }, "price": { "type": "integer", "description": "Paise (INR)." }, "mrp": { "type": "integer", "description": "Paise (INR)." }, "discount_percent": { "type": "integer" }, "in_stock": { "type": "boolean" }, "rating": { "type": "object", "properties": { "average": { "type": "number" }, "count": { "type": "integer" } } }, "category": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "slug": { "type": "string" }, "name": { "type": "string" } } }, "brand": { "type": [ "object", "null" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" } } }, "seller": { "type": [ "object", "null" ], "properties": { "store": { "type": "string" }, "name": { "type": "string" }, "is_official": { "type": "boolean" } } }, "image": { "type": "string", "format": "uri" }, "url": { "type": "string", "format": "uri" }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "highlights": { "type": "array", "items": { "type": "string" } }, "gst_rate": { "type": "number" }, "hsn_code": { "type": [ "string", "null" ] }, "is_returnable": { "type": "boolean" }, "return_window_days": { "type": [ "integer", "null" ] }, "cod_allowed": { "type": "boolean" }, "images": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "alt": { "type": [ "string", "null" ] } } } }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "sku": { "type": "string" }, "options": { "type": "object", "additionalProperties": { "type": "string" } }, "label": { "type": [ "string", "null" ] }, "price": { "type": "integer", "description": "Paise (INR)." }, "mrp": { "type": "integer", "description": "Paise (INR)." }, "in_stock": { "type": "boolean" }, "is_default": { "type": "boolean" } } } } } }, "OrderItem": { "type": "object", "properties": { "sku": { "type": "string" }, "name": { "type": "string" }, "option": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unit_price": { "type": "integer", "description": "Paise (INR)." }, "line_total": { "type": "integer", "description": "Paise (INR)." }, "discount": { "type": "integer", "description": "Paise (INR)." }, "tax_amount": { "type": "integer", "description": "Paise (INR)." }, "quantity_returned": { "type": "integer" } } }, "Shipment": { "type": [ "object", "null" ], "properties": { "courier": { "type": [ "string", "null" ] }, "awb": { "type": [ "string", "null" ] }, "tracking_url": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "shipped_at": { "type": [ "string", "null" ], "format": "date-time" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Order": { "type": "object", "properties": { "number": { "type": "string" }, "status": { "type": "string" }, "payment_method": { "type": "string", "enum": [ "cod", "razorpay", "credit" ] }, "payment_status": { "type": "string" }, "currency": { "type": "string", "const": "INR" }, "subtotal": { "type": "integer", "description": "Paise (INR)." }, "discount": { "type": "integer", "description": "Paise (INR)." }, "shipping_total": { "type": "integer", "description": "Paise (INR)." }, "cod_fee": { "type": "integer", "description": "Paise (INR)." }, "tax_total": { "type": "integer", "description": "Paise (INR)." }, "grand_total": { "type": "integer", "description": "Paise (INR)." }, "amount_refunded": { "type": "integer", "description": "Paise (INR)." }, "item_count": { "type": "integer" }, "placed_at": { "type": [ "string", "null" ], "format": "date-time" }, "url": { "type": "string", "format": "uri" } } }, "OrderDetail": { "type": "object", "properties": { "number": { "type": "string" }, "status": { "type": "string" }, "payment_method": { "type": "string", "enum": [ "cod", "razorpay", "credit" ] }, "payment_status": { "type": "string" }, "currency": { "type": "string", "const": "INR" }, "subtotal": { "type": "integer", "description": "Paise (INR)." }, "discount": { "type": "integer", "description": "Paise (INR)." }, "shipping_total": { "type": "integer", "description": "Paise (INR)." }, "cod_fee": { "type": "integer", "description": "Paise (INR)." }, "tax_total": { "type": "integer", "description": "Paise (INR)." }, "grand_total": { "type": "integer", "description": "Paise (INR)." }, "amount_refunded": { "type": "integer", "description": "Paise (INR)." }, "item_count": { "type": "integer" }, "placed_at": { "type": [ "string", "null" ], "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "coupon_code": { "type": [ "string", "null" ] }, "amount_payable": { "type": "integer", "description": "Paise (INR)." }, "credits": { "type": "object", "properties": { "gift_card": { "type": "integer", "description": "Paise (INR)." }, "store_credit": { "type": "integer", "description": "Paise (INR)." }, "points": { "type": "integer", "description": "Paise (INR)." } } }, "shipping_address": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "line1": { "type": [ "string", "null" ] }, "line2": { "type": [ "string", "null" ] }, "landmark": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "district": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "pincode": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] } } }, "sub_orders": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "string" }, "status": { "type": "string" }, "store": { "type": [ "object", "null" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" } } }, "grand_total": { "type": "integer", "description": "Paise (INR)." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrderItem" } }, "shipment": { "$ref": "#/components/schemas/Shipment" }, "shipped_at": { "type": [ "string", "null" ], "format": "date-time" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "cancelled_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } }, "SellerOrder": { "type": "object", "properties": { "id": { "type": "integer" }, "number": { "type": "string" }, "order": { "type": "string", "description": "Customer order number." }, "status": { "type": "string", "enum": [ "placed", "confirmed", "packed", "shipped", "out_for_delivery", "delivered", "cancelled", "return_requested", "returned", "refunded" ] }, "payment_method": { "type": "string" }, "currency": { "type": "string", "const": "INR" }, "subtotal": { "type": "integer", "description": "Paise (INR)." }, "discount": { "type": "integer", "description": "Paise (INR)." }, "shipping_total": { "type": "integer", "description": "Paise (INR)." }, "cod_fee": { "type": "integer", "description": "Paise (INR)." }, "grand_total": { "type": "integer", "description": "Paise (INR)." }, "collect_on_delivery": { "type": "integer", "description": "Paise (INR)." }, "invoice_number": { "type": [ "string", "null" ] }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrderItem" } }, "shipment": { "$ref": "#/components/schemas/Shipment" }, "shipping_address": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "line1": { "type": [ "string", "null" ] }, "line2": { "type": [ "string", "null" ] }, "landmark": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "district": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "pincode": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] } } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "confirmed_at": { "type": [ "string", "null" ], "format": "date-time" }, "shipped_at": { "type": [ "string", "null" ], "format": "date-time" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "cancelled_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "examples": [ "unauthenticated", "invalid_token", "insufficient_scope", "rate_limited", "validation_failed", "not_found", "server_error" ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "object", "description": "Field errors for validation_failed." } } } } } }, "responses": { "Unauthenticated": { "description": "Missing, invalid, expired or revoked credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_token", "message": "This API key is invalid, expired or revoked.", "request_id": "req_8f2k3m9x1q4w7e5r6t0y" } } } } }, "InsufficientScope": { "description": "The credential lacks the scope this endpoint needs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "insufficient_scope", "message": "This credential lacks the required scope: profile.read.", "request_id": "req_8f2k3m9x1q4w7e5r6t0y" } } } } }, "RateLimited": { "description": "Too many requests. Wait for Retry-After seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Quote this when contacting support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ValidationFailed": { "description": "Invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }