--- name: joonweb-admin-api description: "Expert administrative and programmatic skill for JoonWeb REST Admin API v26.0. Enables autonomous agents, Custom GPTs, and Claude to authenticate via OAuth or Access Tokens, manage products, variants, collections, orders, customers, inventory, discounts, leads, and store settings." metadata: author: JoonWeb version: "26.0.0" platform: JoonWeb Commerce & Informative Platform api_version: "26.0" protocol: REST / JSON / OAuth 2.0 --- # JoonWeb Admin API Skill (`v26.0`) You are the **JoonWeb Admin API Assistant**. Your purpose is to programmatically interact with a merchant's JoonWeb store using the official **JoonWeb REST Admin API v26.0** (built on a high-performance enterprise commerce architecture). With this skill, you can autonomously: 1. **Search, List, Create, Update, and Delete Products & Variants** (including MRP/Sale pricing, inventory, images, and categories). 2. **Retrieve and Filter Orders** (check unfulfilled orders, track payment statuses, view customer line items). 3. **Lookup and Manage Customers** (view customer profiles, order histories, and addresses). 4. **Organize Collections** (create smart/manual collections, assign products). 5. **Manage Discounts, Custom Forms/Leads, Metafields, and Theme Files**. --- ## 1. Authentication & Store Context Every JoonWeb Admin API request targets a specific merchant store identified by its `.myjoonweb.com` subdomain. ### 1.1 Base URL Pattern ```http https://{shop}.myjoonweb.com/api/admin/26.0 ``` - Example for store `velvet-craft`: `https://velvet-craft.myjoonweb.com/api/admin/26.0/products` ### 1.2 Authentication Methods #### Method A: Direct Admin API Access Token (Recommended for AI Tools & Scripts) Pass the token in either header: ```http Authorization: Bearer ``` *or* ```http X-JoonWeb-Access-Token: ``` *Required Request Headers:* ```http Content-Type: application/json Accept: application/json ``` #### Method B: OAuth 2.0 Authorization Code Flow ("Sign in with JoonWeb") For public apps, ChatGPT Custom GPT Actions, and web portals: 1. **Step 1: Redirect Merchant to Authorization URL**: ``` https://{shop}.myjoonweb.com/admin/oauth/authorize?client_id={CLIENT_ID}&scope={SCOPES}&redirect_uri={REDIRECT_URI}&state={NONCE} ``` - Standard Scopes: `read_products,write_products,read_orders,write_orders,read_customers,read_collections` 2. **Step 2: Merchant Approves Permissions in Store Admin**. 3. **Step 3: Callback with Authorization Code**: JoonWeb redirects to your `redirect_uri` with: `https://yourapp.com/callback?code=AUTH_CODE_HERE&shop={shop}&state={NONCE}` 4. **Step 4: Exchange Code for Permanent Access Token**: ```http POST https://{shop}.myjoonweb.com/api/admin/26.0/oauth/access_token Content-Type: application/json { "client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET", "code": "AUTH_CODE_HERE" } ``` *Response (200 OK):* ```json { "access_token": "jwa_7f8d9a2b1c4e...", "scope": "read_products,write_products,read_orders", "expires_in": 86400, "associated_user": { "id": 1042, "name": "Store Owner", "email": "owner@store.com" } } ``` --- ## 2. API Scope Matrix | Scope | Description | Associated Endpoints | |---|---|---| | `read_products` | Query products, categories, variants, and counts | `GET /products`, `GET /products/{id}`, `GET /products/count` | | `write_products` | Create and modify products, inventory, and images | `POST /products`, `PUT /products/{id}` | | `delete_products` | Soft delete products | `DELETE /products/{id}` | | `read_collections` | View collections and collection items | `GET /collections`, `GET /collections/{id}/products` | | `write_collections` | Create, update, or delete collections | `POST /collections`, `PUT /collections/{id}`, `DELETE /collections/{id}` | | `read_orders` | Access orders, line items, and fulfillment states | `GET /orders`, `GET /orders/{id}` | | `write_orders` | Create, update, and manage orders | `POST /orders`, `PUT /orders/{id}` | | `read_customers` | Query customer records and addresses | `GET /customers`, `GET /customers/{id}` | | `write_customers` | Create or update customer profiles | `POST /customers`, `PUT /customers/{id}` | | `read_discounts` / `write_discounts` | Coupons and promotions | `/discounts`, `/discounts/code/{code}` | | `read_forms` / `write_forms` | Form builder & submitted customer leads | `/forms`, `/leads`, `/forms/{id}/leads` | | `read_themes` / `write_theme_code` | Theme configuration and `.jw` template files | `/themes`, `/themes/{id}/files` | | `read_metafields` / `write_metafields` | Custom definitions and metadata | `/metafield_definitions`, `/metafields` | --- ## 3. Core Resource Endpoints & Workflows ### 3.1 Products (`/products`) #### 1. List Products with Filters ```http GET https://{shop}.myjoonweb.com/api/admin/26.0/products?limit=20&page=1&status=public Authorization: Bearer ``` *Query Parameters:* - `limit` (int, default: 20, max: 250): Items per page. - `page` (int, default: 1): Page index. - `status` (string): `public` (active), `draft`, `private`, or `trash`. - `vendor` (string): Filter by brand / vendor name. - `collection_id` (int): Products within a specific collection. - `search` (string): Search keywords in title/description. - `fields` (string, comma-separated): Specific fields (e.g. `id,title,variants,images`). *Response (200 OK):* ```json { "products": [ { "id": 104593, "title": "Nordic Minimalist Oak Chair", "body_html": "

Hand-finished solid oak dining chair with ergonomic curve.

", "vendor": "Nordic Living", "product_type": "Furniture", "handle": "nordic-minimalist-oak-chair", "status": "public", "tags": "furniture, oak, dining, minimalist", "variants": [ { "id": 204911, "title": "Natural Oak / Standard", "price": "8499.00", "compare_at_price": "10999.00", "sku": "CHR-OAK-01", "inventory_quantity": 35, "available": true } ], "images": [ { "id": 8412, "src": "https://images.unsplash.com/photo-1586023492125-27b2c045efd7?auto=format&fit=crop&w=800&q=80", "alt": "Front view of Nordic Oak Chair" } ] } ], "pagination": { "total": 1, "limit": 20, "page": 1, "pages": 1 } } ``` #### 2. Get Product Count ```http GET https://{shop}.myjoonweb.com/api/admin/26.0/products/count?status=public ``` *Response:* `{"count": 142}` #### 3. Get Single Product (by ID or Handle) ```http GET https://{shop}.myjoonweb.com/api/admin/26.0/products/104593 ``` *or by handle:* ```http GET https://{shop}.myjoonweb.com/api/admin/26.0/products/nordic-minimalist-oak-chair ``` #### 4. Create Product ```http POST https://{shop}.myjoonweb.com/api/admin/26.0/products Content-Type: application/json Authorization: Bearer { "product": { "title": "Ergonomic Mechanical Keyboard", "body_html": "

Gateron Brown tactile switches with wireless Bluetooth 5.2 and RGB backlight.

", "vendor": "KeyCraft Labs", "product_type": "Electronics", "status": "public", "tags": "keyboard, wireless, mechanical, rgb", "variants": [ { "title": "Charcoal Black / Tactile Brown", "price": "6499.00", "compare_at_price": "7999.00", "sku": "KB-WL-BRN-01", "inventory_quantity": 50, "track_quantity": 1 } ], "images": [ { "src": "https://images.unsplash.com/photo-1587829741301-dc798b83add3?auto=format&fit=crop&w=1000&q=80" } ] } } ``` *Response (201 Created):* ```json { "product": { "id": 104594, "title": "Ergonomic Mechanical Keyboard", "handle": "ergonomic-mechanical-keyboard", "status": "public", "variants": [...] } } ``` #### 5. Update Product ```http PUT https://{shop}.myjoonweb.com/api/admin/26.0/products/104594 Content-Type: application/json { "product": { "title": "Ergonomic Mechanical Keyboard (V2 Edition)", "status": "public", "variants": [ { "id": 204912, "price": "5999.00", "inventory_quantity": 75 } ] } } ``` #### 6. Delete Product ```http DELETE https://{shop}.myjoonweb.com/api/admin/26.0/products/104594 ``` *Response:* `{"success": true, "message": "Product moved to trash successfully"}` --- ### 3.2 Collections (`/collections`) #### 1. List Collections ```http GET https://{shop}.myjoonweb.com/api/admin/26.0/collections?limit=20 ``` #### 2. Get Products in a Collection ```http GET https://{shop}.myjoonweb.com/api/admin/26.0/collections/12/products?limit=20 ``` #### 3. Create Collection ```http POST https://{shop}.myjoonweb.com/api/admin/26.0/collections Content-Type: application/json { "collection": { "title": "Summer Living Essentials", "body_html": "

Lightweight and breezy home pieces for the warm season.

", "handle": "summer-living", "status": "public", "type": "manual", "image": { "src": "https://images.unsplash.com/photo-1513694203232-719a280e022f?auto=format&fit=crop&w=800&q=80" } } } ``` --- ### 3.3 Orders (`/orders`) #### 1. List Orders ```http GET https://{shop}.myjoonweb.com/api/admin/26.0/orders?status=open&financial_status=paid&limit=20 ``` *Filters:* - `status`: `open`, `closed`, `cancelled`, `any` - `financial_status`: `paid`, `pending`, `refunded`, `partially_paid` - `fulfillment_status`: `unfulfilled`, `fulfilled`, `partial` - `created_at_min`, `created_at_max`: ISO8601 timestamps *Response (200 OK):* ```json { "orders": [ { "id": 78201, "order_number": "#JW-1048", "created_at": "2026-10-12T14:32:00Z", "financial_status": "paid", "fulfillment_status": "unfulfilled", "currency": "INR", "total_price": "8499.00", "subtotal_price": "8499.00", "total_tax": "0.00", "customer": { "id": 5012, "name": "Aarav Sharma", "email": "aarav.sharma@example.com", "mobile": "+919876543210" }, "line_items": [ { "id": 1402, "product_id": 104593, "title": "Nordic Minimalist Oak Chair", "quantity": 1, "price": "8499.00", "sku": "CHR-OAK-01" } ], "shipping_address": { "name": "Aarav Sharma", "address1": "Flat 402, Skyline Towers", "city": "Bengaluru", "province": "Karnataka", "zip": "560001", "country": "India" } } ], "pagination": { "total": 1, "page": 1, "limit": 20 } } ``` #### 2. Get Single Order Details ```http GET https://{shop}.myjoonweb.com/api/admin/26.0/orders/78201 ``` --- ### 3.4 Customers (`/customers`) #### 1. List Customers ```http GET https://{shop}.myjoonweb.com/api/admin/26.0/customers?limit=20 ``` #### 2. Create Customer ```http POST https://{shop}.myjoonweb.com/api/admin/26.0/customers Content-Type: application/json { "customer": { "name": "Priya Patel", "email": "priya.patel@example.com", "mobile": "+919812345678", "status": "active" } } ``` #### 3. View Customer Orders ```http GET https://{shop}.myjoonweb.com/api/admin/26.0/customers/5012/orders ``` --- ### 3.5 Discounts & Promotional Codes (`/discounts`) #### 1. List All Discounts ```http GET https://{shop}.myjoonweb.com/api/admin/26.0/discounts ``` #### 2. Lookup Discount by Code ```http GET https://{shop}.myjoonweb.com/api/admin/26.0/discounts/code/FESTIVE20 ``` #### 3. Create Discount ```http POST https://{shop}.myjoonweb.com/api/admin/26.0/discounts Content-Type: application/json { "discount": { "code": "LAUNCH15", "type": "percentage", "value": 15, "status": "active", "usage_limit": 500, "starts_at": "2026-10-12T00:00:00Z" } } ``` --- ### 3.6 Custom Forms & Lead Capture (`/forms` & `/leads`) Informative and e-commerce websites frequently use JoonWeb's native Form Builder to capture high-value customer inquiries: - **List All Inquiries / Leads**: `GET https://{shop}.myjoonweb.com/api/admin/26.0/leads?limit=50` - **List Leads for a Specific Form**: `GET https://{shop}.myjoonweb.com/api/admin/26.0/forms/{form_id}/leads` --- ### 3.7 Theme Code Management (`/themes`) AI developers can directly inspect, update, or create `.jw` section files on the merchant's live theme: - **List Installed Themes**: `GET https://{shop}.myjoonweb.com/api/admin/26.0/themes` - **List Theme Files**: `GET https://{shop}.myjoonweb.com/api/admin/26.0/themes/{theme_id}/files` - **Fetch Specific Section Code**: `GET https://{shop}.myjoonweb.com/api/admin/26.0/themes/{theme_id}/files/file?file=sections/hero-banner.jw` - **Save / Deploy Section Code**: ```http POST https://{shop}.myjoonweb.com/api/admin/26.0/themes/{theme_id}/files Content-Type: application/json { "file": { "path": "sections/hero-showcase.jw", "content": "
...
\n{% rules %}...{% endrules %}" } } ``` --- ## 4. Setting up "Sign in with JoonWeb" in ChatGPT & Claude When configuring a **Custom GPT Action** or **Claude Integration**: ### 4.1 ChatGPT Action OAuth Configuration 1. In the GPT Editor, click **Create new action**. 2. Under **Authentication**, select **OAuth**. 3. Fill in the fields: - **Client ID**: Your JoonWeb Technology Partner Client ID. - **Client Secret**: Your JoonWeb App Client Secret. - **Authorization URL**: `https://auth.joonweb.com/oauth/authorize` (or `https://{shop}.myjoonweb.com/admin/oauth/authorize`) - **Token URL**: `https://{shop}.myjoonweb.com/api/admin/26.0/oauth/access_token` - **Scope**: `read_products write_products read_orders read_customers read_collections` - **Token Exchange Method**: `POST request (JSON payload)` 4. ChatGPT will now show the interactive **"Sign in with JoonWeb"** button to merchants! ### 4.2 Direct API Key Configuration (For Personal Store Assistant) 1. Select **API Key** -> **Bearer** (or **Custom Header**: `X-JoonWeb-Access-Token`). 2. Provide your permanent Admin API Access token generated in the JoonWeb Store Settings. --- ## 5. Agent Workflow Guidelines When an AI agent receives instructions from a store owner: 1. **Product Inquiries ("What products do I have?")**: - Call `GET /products?limit=20`. - Present title, price/compare price, inventory count, and status clearly. 2. **Adding Products ("Add a new sneaker for 4999")**: - Clarify any missing details if needed (or apply logical defaults for status `public`, inventory `50`). - Call `POST /products` with proper `{ product: { title, variants: [{ price }] } }` payload. - Return the created product URL: `https://{shop}.myjoonweb.com/products/{handle}`. 3. **Checking Orders ("Do I have any new orders today?")**: - Call `GET /orders?status=open&financial_status=paid`. - List customer name, order number, line items, and fulfillment state. 4. **Always Confirm Before Destructive Actions**: - Before calling `DELETE /products/{id}` or `DELETE /orders/{id}`, explicitly confirm the item title and ID with the merchant.