{ "openapi": "3.0.3", "info": { "title": "JoonWeb Admin API", "description": "Programmatic interface for managing products, collections, orders, customers, and inventory on the JoonWeb commerce platform.", "version": "26.0.0" }, "servers": [ { "url": "https://{shop}.myjoonweb.com/api/admin/26.0", "description": "Merchant Store Admin API Server", "variables": { "shop": { "default": "store", "description": "Merchant's JoonWeb store subdomain (e.g., yourstore)" } } } ], "paths": { "/products": { "get": { "summary": "List products", "description": "Retrieve products with optional filtering by status, vendor, search keywords, or collection.", "operationId": "listProducts", "parameters": [ { "name": "limit", "in": "query", "description": "Number of results to return (max 250)", "schema": { "type": "integer", "default": 20 } }, { "name": "page", "in": "query", "description": "Page number", "schema": { "type": "integer", "default": 1 } }, { "name": "status", "in": "query", "description": "Product status (public, draft, private)", "schema": { "type": "string" } }, { "name": "vendor", "in": "query", "description": "Filter by vendor or brand name", "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Search keyword in title or description", "schema": { "type": "string" } }, { "name": "collection_id", "in": "query", "description": "Filter by collection ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List of products and pagination details" } } }, "post": { "summary": "Create a product", "description": "Add a new product with title, description, pricing, variants, and stock.", "operationId": "createProduct", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "object", "required": ["title"], "properties": { "title": { "type": "string", "example": "Handcrafted Leather Wallet" }, "body_html": { "type": "string", "example": "

100% full-grain leather with RFID protection.

" }, "vendor": { "type": "string", "example": "Craftsman Co." }, "product_type": { "type": "string", "example": "Accessories" }, "status": { "type": "string", "enum": ["public", "draft", "private"], "default": "public" }, "tags": { "type": "string", "example": "leather, wallet, mens" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "example": "Vintage Tan" }, "price": { "type": "string", "example": "1499.00" }, "compare_at_price": { "type": "string", "example": "1999.00" }, "sku": { "type": "string", "example": "WAL-TAN-01" }, "inventory_quantity": { "type": "integer", "example": 50 } } } }, "images": { "type": "array", "items": { "type": "object", "properties": { "src": { "type": "string", "example": "https://images.unsplash.com/photo-1627123424574-724758594e93" } } } } } } } } } } }, "responses": { "201": { "description": "Product created successfully" } } } }, "/products/{id}": { "get": { "summary": "Get product details", "description": "Retrieve comprehensive details of a single product by numeric ID or URL handle.", "operationId": "getProduct", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Product ID or Handle", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Product details" } } }, "put": { "summary": "Update product", "description": "Modify existing product attributes, pricing, or stock.", "operationId": "updateProduct", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Product ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "object" } } } } } }, "responses": { "200": { "description": "Product updated successfully" } } }, "delete": { "summary": "Delete product", "description": "Move a product to trash.", "operationId": "deleteProduct", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Product ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Product deleted" } } } }, "/products/count": { "get": { "summary": "Count products", "description": "Get total count of products matching criteria.", "operationId": "countProducts", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Product count" } } } }, "/orders": { "get": { "summary": "List orders", "description": "Retrieve orders with status and date filters.", "operationId": "listOrders", "parameters": [ { "name": "status", "in": "query", "description": "Order status (open, closed, cancelled, any)", "schema": { "type": "string" } }, { "name": "financial_status", "in": "query", "description": "Payment status (paid, pending, refunded)", "schema": { "type": "string" } }, { "name": "fulfillment_status", "in": "query", "description": "Shipping status (unfulfilled, fulfilled)", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } } ], "responses": { "200": { "description": "List of orders" } } } }, "/orders/{id}": { "get": { "summary": "Get order details", "description": "Retrieve single order with line items, shipping address, and customer information.", "operationId": "getOrder", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Order details" } } } }, "/customers": { "get": { "summary": "List customers", "description": "Query customers registered on the store.", "operationId": "listCustomers", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "search", "in": "query", "description": "Name or email query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of customers" } } } }, "/collections": { "get": { "summary": "List collections", "description": "Retrieve store product collections.", "operationId": "listCollections", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "List of collections" } } } }, "/discounts": { "get": { "summary": "List discount codes", "description": "List promotional discount vouchers and coupon codes.", "operationId": "listDiscounts", "responses": { "200": { "description": "List of discounts" } } } }, "/leads": { "get": { "summary": "List submitted form leads", "description": "Retrieve customer inquiries and leads captured through native site forms.", "operationId": "listLeads", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "List of leads" } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Direct JoonWeb Admin API Access Token" }, "JoonwebOAuth": { "type": "oauth2", "description": "Sign in with JoonWeb OAuth 2.0 Flow", "flows": { "authorizationCode": { "authorizationUrl": "https://{shop}.myjoonweb.com/admin/oauth/authorize", "tokenUrl": "https://{shop}.myjoonweb.com/api/admin/26.0/oauth/access_token", "scopes": { "read_products": "Read products, variants, and stock", "write_products": "Create, modify, and delete products", "read_orders": "Read store orders and customer addresses", "write_orders": "Modify orders and fulfillments", "read_customers": "Read customer profiles and purchase history", "read_collections": "View collections and categories" } } } } } }, "security": [ { "BearerAuth": [] }, { "JoonwebOAuth": ["read_products", "write_products", "read_orders", "read_customers"] } ] }