{
    "openapi": "3.1.0",
    "info": {
        "title": "Sarim Tools Reseller API",
        "version": "1.0.0",
        "summary": "Sell Sarim Tools products on your own website, paid from your Sarim Tools wallet.",
        "description": "Read the catalog (products, prices, stock, images) and buy for your customers. Orders are paid from your wallet on https://sarimtools.com/ and delivered by us; ready accounts come back in the order response.\n\n- **Key:** create one under Account → Reseller API and send it in the `X-API-Key` header (or `Authorization: Bearer`). Keep it on your server.\n- **Prices** are in Pakistani rupees (PKR). `price` is what you pay, `shop_price` is our public price.\n- **Money:** an order is charged to your wallet when it is placed. Items that cannot be delivered are refunded to your wallet automatically.\n- **Retries:** send your own order number as `reference`. The same reference never creates a second order, so a retried request is never charged twice.\n- **Limits:** 120 requests and 30 orders a minute per key. Allow up to 2 minutes for `POST /order`.\n\nHuman docs with examples: https://sarimtools.com/reseller-api",
        "contact": {
            "name": "Sarim Tools",
            "url": "https://sarimtools.com/contact",
            "email": "support@sarimtools.com"
        },
        "termsOfService": "https://sarimtools.com/terms"
    },
    "servers": [
        {
            "url": "https://sarimtools.com/api/v1",
            "description": "Sarim Tools"
        }
    ],
    "security": [
        {
            "apiKey": []
        },
        {
            "bearer": []
        }
    ],
    "tags": [
        {
            "name": "Account"
        },
        {
            "name": "Catalog"
        },
        {
            "name": "Orders"
        }
    ],
    "paths": {
        "/balance": {
            "get": {
                "tags": [
                    "Account"
                ],
                "operationId": "getBalance",
                "summary": "Your wallet balance",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "ok",
                                        "balance",
                                        "currency"
                                    ],
                                    "properties": {
                                        "ok": {
                                            "const": true
                                        },
                                        "balance": {
                                            "type": "number"
                                        },
                                        "currency": {
                                            "const": "PKR"
                                        },
                                        "top_up": {
                                            "type": "string",
                                            "format": "uri"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    },
                    "503": {
                        "$ref": "#/components/responses/Off"
                    }
                }
            }
        },
        "/brands": {
            "get": {
                "tags": [
                    "Catalog"
                ],
                "operationId": "listBrands",
                "summary": "Brands with logos and stock counts",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "ok",
                                        "count",
                                        "brands"
                                    ],
                                    "properties": {
                                        "ok": {
                                            "const": true
                                        },
                                        "count": {
                                            "type": "integer"
                                        },
                                        "brands": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/Brand"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    },
                    "503": {
                        "$ref": "#/components/responses/Off"
                    }
                }
            }
        },
        "/products": {
            "get": {
                "tags": [
                    "Catalog"
                ],
                "operationId": "listProducts",
                "summary": "Products with prices, stock and images, or one product by id",
                "description": "Stock and prices are at most 5 minutes old. Prices follow our prices and the dollar rate: read this again at least every few hours.",
                "parameters": [
                    {
                        "name": "id",
                        "in": "query",
                        "required": false,
                        "description": "One product. The answer then has `product` instead of `products`.",
                        "schema": {
                            "type": "string",
                            "pattern": "^p_[a-f0-9]{12}$"
                        }
                    },
                    {
                        "name": "brand",
                        "in": "query",
                        "required": false,
                        "description": "Only this brand (its `slug` from /brands), e.g. `chatgpt`.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "in_stock",
                        "in": "query",
                        "required": false,
                        "description": "Only products in stock.",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "1"
                            ]
                        }
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "description": "Words in the product or brand name.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "type": "object",
                                            "required": [
                                                "ok",
                                                "count",
                                                "products"
                                            ],
                                            "properties": {
                                                "ok": {
                                                    "const": true
                                                },
                                                "count": {
                                                    "type": "integer"
                                                },
                                                "discount_percent": {
                                                    "type": "number"
                                                },
                                                "products": {
                                                    "type": "array",
                                                    "items": {
                                                        "$ref": "#/components/schemas/Product"
                                                    }
                                                }
                                            }
                                        },
                                        {
                                            "type": "object",
                                            "required": [
                                                "ok",
                                                "product"
                                            ],
                                            "properties": {
                                                "ok": {
                                                    "const": true
                                                },
                                                "product": {
                                                    "$ref": "#/components/schemas/Product"
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    },
                    "503": {
                        "$ref": "#/components/responses/Off"
                    }
                }
            }
        },
        "/order": {
            "post": {
                "tags": [
                    "Orders"
                ],
                "operationId": "createOrder",
                "summary": "Buy a product, paid from your wallet",
                "description": "Charges your wallet and buys the product while you wait. Ready accounts come back with their login in `items[].delivery`. Invite and upgrade plans answer `processing`: poll GET /order until `completed`.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/OrderRequest"
                            }
                        },
                        "application/x-www-form-urlencoded": {
                            "schema": {
                                "$ref": "#/components/schemas/OrderRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Order placed",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "ok",
                                        "order",
                                        "balance"
                                    ],
                                    "properties": {
                                        "ok": {
                                            "const": true
                                        },
                                        "order": {
                                            "$ref": "#/components/schemas/Order"
                                        },
                                        "balance": {
                                            "type": "number"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "200": {
                        "description": "An order with this reference already exists: it is returned and nothing is charged",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "ok",
                                        "duplicate",
                                        "order"
                                    ],
                                    "properties": {
                                        "ok": {
                                            "const": true
                                        },
                                        "duplicate": {
                                            "const": true
                                        },
                                        "order": {
                                            "$ref": "#/components/schemas/Order"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad input: `bad_quantity`, `bad_reference`, `missing_details` or `order_failed`. The message says what to fix.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "402": {
                        "description": "`insufficient_balance`: includes `balance`, `needed` and a `top_up` link",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "409": {
                        "description": "`out_of_stock`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    },
                    "503": {
                        "$ref": "#/components/responses/Off"
                    }
                }
            },
            "get": {
                "tags": [
                    "Orders"
                ],
                "operationId": "getOrder",
                "summary": "One order with its status and logins",
                "parameters": [
                    {
                        "name": "id",
                        "in": "query",
                        "required": false,
                        "description": "Our order id, e.g. `ST3F9A1C2B7D`.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "reference",
                        "in": "query",
                        "required": false,
                        "description": "Your reference from POST /order.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "ok",
                                        "order"
                                    ],
                                    "properties": {
                                        "ok": {
                                            "const": true
                                        },
                                        "order": {
                                            "$ref": "#/components/schemas/Order"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    },
                    "503": {
                        "$ref": "#/components/responses/Off"
                    }
                }
            }
        },
        "/orders": {
            "get": {
                "tags": [
                    "Orders"
                ],
                "operationId": "listOrders",
                "summary": "Your latest orders, newest first (without logins)",
                "parameters": [
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "description": "Orders per page.",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100,
                            "default": 20
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Page number.",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "default": 1
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "ok",
                                        "page",
                                        "orders"
                                    ],
                                    "properties": {
                                        "ok": {
                                            "const": true
                                        },
                                        "page": {
                                            "type": "integer"
                                        },
                                        "orders": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/Order"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    },
                    "503": {
                        "$ref": "#/components/responses/Off"
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "apiKey": {
                "type": "apiKey",
                "in": "header",
                "name": "X-API-Key",
                "description": "Your key from Account → Reseller API (starts with st_)."
            },
            "bearer": {
                "type": "http",
                "scheme": "bearer",
                "description": "The same key as a bearer token."
            }
        },
        "responses": {
            "Unauthorized": {
                "description": "`missing_key` or `invalid_key`",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "RateLimited": {
                "description": "`rate_limited`: 120 requests and 30 orders a minute per key",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "Off": {
                "description": "`api_off`: the API is paused for maintenance",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "NotFound": {
                "description": "`not_found`",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            }
        },
        "schemas": {
            "Error": {
                "type": "object",
                "required": [
                    "ok",
                    "error",
                    "message"
                ],
                "properties": {
                    "ok": {
                        "const": false
                    },
                    "error": {
                        "type": "string",
                        "enum": [
                            "missing_key",
                            "invalid_key",
                            "rate_limited",
                            "api_off",
                            "not_found",
                            "method_not_allowed",
                            "bad_quantity",
                            "bad_reference",
                            "missing_details",
                            "order_failed",
                            "insufficient_balance",
                            "out_of_stock"
                        ]
                    },
                    "message": {
                        "type": "string",
                        "description": "What went wrong and how to fix it, in plain English."
                    },
                    "balance": {
                        "type": "number"
                    },
                    "needed": {
                        "type": "number"
                    },
                    "top_up": {
                        "type": "string",
                        "format": "uri"
                    }
                }
            },
            "Brand": {
                "type": "object",
                "required": [
                    "slug",
                    "name",
                    "logo",
                    "url"
                ],
                "properties": {
                    "slug": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    },
                    "logo": {
                        "type": "string",
                        "format": "uri"
                    },
                    "products": {
                        "type": "integer"
                    },
                    "in_stock": {
                        "type": "integer"
                    },
                    "url": {
                        "type": "string",
                        "format": "uri"
                    }
                }
            },
            "Product": {
                "type": "object",
                "required": [
                    "id",
                    "name",
                    "brand",
                    "price",
                    "currency",
                    "in_stock",
                    "delivery",
                    "requires"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "pattern": "^p_[a-f0-9]{12}$",
                        "description": "Use as product_id in POST /order. Stable for as long as we sell the product."
                    },
                    "name": {
                        "type": "string"
                    },
                    "brand": {
                        "type": "object",
                        "properties": {
                            "slug": {
                                "type": "string"
                            },
                            "name": {
                                "type": "string"
                            }
                        }
                    },
                    "price": {
                        "type": "number",
                        "description": "What you pay per unit, in PKR."
                    },
                    "shop_price": {
                        "type": "number",
                        "description": "Our public price on the website, in PKR."
                    },
                    "currency": {
                        "const": "PKR"
                    },
                    "in_stock": {
                        "type": "boolean"
                    },
                    "stock": {
                        "type": [
                            "integer",
                            "null"
                        ],
                        "description": "null means available without a count."
                    },
                    "max_quantity": {
                        "type": "integer",
                        "description": "Most units in one order."
                    },
                    "delivery": {
                        "type": "string",
                        "enum": [
                            "ready_account",
                            "invite_to_email",
                            "upgrade_on_account"
                        ],
                        "description": "ready_account: login in the order response. invite_to_email: invite sent to `email`. upgrade_on_account: the customer's own account (`accounts`) is upgraded, usually within a few hours."
                    },
                    "duration": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "examples": [
                            "1 month"
                        ]
                    },
                    "warranty": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "examples": [
                            "Full warranty"
                        ]
                    },
                    "requires": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "enum": [
                                "email",
                                "accounts",
                                "months"
                            ]
                        },
                        "description": "Fields POST /order needs for this product."
                    },
                    "months_options": {
                        "type": [
                            "array",
                            "null"
                        ],
                        "items": {
                            "type": "integer"
                        }
                    },
                    "description": {
                        "type": "string"
                    },
                    "image": {
                        "type": "string",
                        "format": "uri"
                    },
                    "banner": {
                        "type": "string",
                        "format": "uri",
                        "description": "1200×630 share image with name and price."
                    },
                    "url": {
                        "type": "string",
                        "format": "uri",
                        "description": "The product page on our website."
                    }
                }
            },
            "OrderRequest": {
                "type": "object",
                "required": [
                    "product_id"
                ],
                "properties": {
                    "product_id": {
                        "type": "string",
                        "pattern": "^p_[a-f0-9]{12}$"
                    },
                    "quantity": {
                        "type": "integer",
                        "minimum": 1,
                        "default": 1
                    },
                    "reference": {
                        "type": "string",
                        "pattern": "^[A-Za-z0-9_.:\\-]{1,64}$",
                        "description": "Your own order number. Strongly recommended: the same reference never creates a second order."
                    },
                    "email": {
                        "type": "string",
                        "format": "email",
                        "description": "Needed when the product `requires` email (invite plans)."
                    },
                    "accounts": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "description": "Needed when the product `requires` accounts: one account per unit of quantity."
                    },
                    "months": {
                        "type": "integer",
                        "description": "Needed when the product `requires` months: one of `months_options`."
                    }
                }
            },
            "DeliveryAccount": {
                "type": "object",
                "properties": {
                    "login": {
                        "type": "string"
                    },
                    "password": {
                        "type": "string"
                    },
                    "recovery_email": {
                        "type": "string"
                    },
                    "expires": {
                        "type": "string"
                    },
                    "notes": {
                        "type": "string"
                    }
                }
            },
            "OrderItem": {
                "type": "object",
                "required": [
                    "product_id",
                    "name",
                    "quantity",
                    "amount",
                    "status"
                ],
                "properties": {
                    "product_id": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    },
                    "quantity": {
                        "type": "integer"
                    },
                    "amount": {
                        "type": "number",
                        "description": "What this item cost you, in PKR."
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "pending",
                            "processing",
                            "completed",
                            "review",
                            "failed",
                            "refunded"
                        ],
                        "description": "review: we are checking it with our supplier and will deliver or refund. failed: refunded to your wallet."
                    },
                    "status_label": {
                        "type": "string"
                    },
                    "email": {
                        "type": "string"
                    },
                    "accounts": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "delivery": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/DeliveryAccount"
                        },
                        "description": "Logins once the item is completed (ready accounts). Not included in GET /orders."
                    },
                    "refunded": {
                        "type": "number",
                        "description": "Amount returned to your wallet when the item failed."
                    }
                }
            },
            "Order": {
                "type": "object",
                "required": [
                    "id",
                    "status",
                    "total",
                    "currency",
                    "created_at",
                    "items"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "examples": [
                            "ST3F9A1C2B7D"
                        ]
                    },
                    "reference": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "processing",
                            "completed",
                            "review",
                            "failed",
                            "partial"
                        ]
                    },
                    "status_label": {
                        "type": "string"
                    },
                    "total": {
                        "type": "number",
                        "description": "Charged to your wallet, in PKR."
                    },
                    "currency": {
                        "const": "PKR"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "items": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/OrderItem"
                        }
                    }
                }
            }
        }
    }
}