{
 "openapi": "3.0.3",
 "info": {
  "title": "ArabyBot store API",
  "version": "1.0.0",
  "description": "Read the store's orders and products and update order status, tracking, stock and price. As it runs on 2026-11-16. Store key (abst_…, read or write) from the store settings. Docs: https://arabybot.com/developers"
 },
 "servers": [
  {
   "url": "https://app.arabybot.com"
  }
 ],
 "security": [
  {
   "StoreKey": []
  }
 ],
 "components": {
  "securitySchemes": {
   "StoreKey": {
    "type": "http",
    "scheme": "bearer",
    "description": "The store key (abst_…). Also accepted in the X-Api-Key header. Addresses that change data need a key with write access."
   }
  }
 },
 "paths": {
  "/store_api/v1/store": {
   "get": {
    "summary": "ArabyBot store API: store details and key test",
    "description": "With a GET request to the store address of the store API and the store key in the header. The response returns the store's name, currency, country, status and public address. It is the first request to try after creating the key in the store settings, because it changes nothing. Reference: https://arabybot.com/guides/store-api-store",
    "operationId": "store_api_store",
    "responses": {
     "200": {
      "description": "Success"
     },
     "401": {
      "description": "unauthorized: The key is missing, wrong or revoked."
     },
     "402": {
      "description": "store_plan_closed: The store plan has ended; renew it."
     },
     "429": {
      "description": "More than 120 requests in a minute."
     },
     "500": {
      "description": "server_error: A failure on our side; try again."
     }
    }
   }
  },
  "/store_api/v1/orders": {
   "get": {
    "summary": "Store API: the orders list by status and date",
    "description": "With a GET request to the orders address of the store API. The response returns the orders, newest first, fifty a page, and you can filter them by status and by a start date. Every order comes back with its full details: the customer, the address, the items, the amounts and the shipping. The has_more field says whether there is a next page. Reference: https://arabybot.com/guides/store-api-orders",
    "operationId": "store_api_orders",
    "responses": {
     "200": {
      "description": "Success"
     },
     "422": {
      "description": "bad_status: The status value is not one of the seven statuses. | bad_since: The since value is not a date that can be read."
     },
     "401": {
      "description": "unauthorized: The key is missing, wrong or revoked."
     },
     "402": {
      "description": "store_plan_closed: The store plan has ended; renew it."
     },
     "429": {
      "description": "More than 120 requests in a minute."
     },
     "500": {
      "description": "server_error: A failure on our side; try again."
     }
    },
    "parameters": [
     {
      "name": "status",
      "in": "query",
      "required": false,
      "description": "One status: new, confirmed, preparing, shipped, delivered, returned or cancelled.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "since",
      "in": "query",
      "required": false,
      "description": "A start date, e.g. 2026-11-01; orders created from then on come back.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "page",
      "in": "query",
      "required": false,
      "description": "The page number, starting at 1. A page holds 50 orders.",
      "schema": {
       "type": "integer"
      }
     }
    ]
   }
  },
  "/store_api/v1/orders/{number}": {
   "get": {
    "summary": "Store API: one order with all its fields",
    "description": "A GET request to the orders address followed by the order number returns the whole order: its status, the payment method and payment status, the amounts from subtotal, discount, shipping and VAT to the total, the customer and their phone, the shipping address, the tracking details, the order's source, and the items with each line's price and quantity. It is the same shape that arrives in the store's webhooks. Reference: https://arabybot.com/guides/store-api-order",
    "operationId": "store_api_order",
    "responses": {
     "200": {
      "description": "Success"
     },
     "404": {
      "description": "not_found: No order with this number in this store."
     },
     "401": {
      "description": "unauthorized: The key is missing, wrong or revoked."
     },
     "402": {
      "description": "store_plan_closed: The store plan has ended; renew it."
     },
     "429": {
      "description": "More than 120 requests in a minute."
     },
     "500": {
      "description": "server_error: A failure on our side; try again."
     }
    },
    "parameters": [
     {
      "name": "number",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ]
   }
  },
  "/store_api/v1/orders/{number}/status": {
   "post": {
    "summary": "Store API: change order status and allowed moves",
    "description": "With a POST request to the status address under the order number, carrying the new status and an optional note, with a key that has write access. The order moves by the same rules as the panel: a new order is confirmed or cancelled, a confirmed one is prepared, shipped or cancelled, a shipped one is delivered or returned. A move that is not allowed is refused with status 409. The change fires the same notifications a change from the panel fires. Reference: https://arabybot.com/guides/store-api-order-status",
    "operationId": "store_api_order_status",
    "responses": {
     "200": {
      "description": "Success"
     },
     "403": {
      "description": "read_only_key: The key can read only; create a key with write access in the store settings."
     },
     "409": {
      "description": "transition_not_allowed: The move from the current status to the requested one is not allowed. | out_of_stock / stock_back_gone: The stock does not allow this move."
     },
     "422": {
      "description": "bad_status: The status written is not one of the seven."
     },
     "404": {
      "description": "not_found: No order with this number in this store."
     },
     "401": {
      "description": "unauthorized: The key is missing, wrong or revoked."
     },
     "402": {
      "description": "store_plan_closed: The store plan has ended; renew it."
     },
     "429": {
      "description": "More than 120 requests in a minute."
     },
     "500": {
      "description": "server_error: A failure on our side; try again."
     }
    },
    "parameters": [
     {
      "name": "number",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "status": {
          "type": "string",
          "description": "The new status: new, confirmed, preparing, shipped, delivered, returned or cancelled."
         },
         "note": {
          "type": "string",
          "description": "A note of up to 200 characters, written in the order's log with the key's name."
         }
        },
        "required": [
         "status"
        ]
       }
      }
     }
    }
   }
  },
  "/store_api/v1/orders/{number}/tracking": {
   "post": {
    "summary": "Store API: add a tracking number to an order",
    "description": "With a POST request to the tracking address under the order number, carrying the carrier's name, the tracking number and the tracking link if there is one, with a key that has write access. The tracking is saved on the order and the response returns the updated order. The tracking link must start with http or https. Reference: https://arabybot.com/guides/store-api-order-tracking",
    "operationId": "store_api_order_tracking",
    "responses": {
     "200": {
      "description": "Success"
     },
     "403": {
      "description": "read_only_key: The key can read only; create a key with write access in the store settings."
     },
     "422": {
      "description": "bad_url: The tracking link is not a valid address starting with http or https."
     },
     "404": {
      "description": "not_found: No order with this number in this store."
     },
     "401": {
      "description": "unauthorized: The key is missing, wrong or revoked."
     },
     "402": {
      "description": "store_plan_closed: The store plan has ended; renew it."
     },
     "429": {
      "description": "More than 120 requests in a minute."
     },
     "500": {
      "description": "server_error: A failure on our side; try again."
     }
    },
    "parameters": [
     {
      "name": "number",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "carrier": {
          "type": "string",
          "description": "The carrier's name."
         },
         "url": {
          "type": "string",
          "description": "The link of the tracking page, starting with http or https."
         }
        }
       }
      }
     }
    }
   }
  },
  "/store_api/v1/products": {
   "get": {
    "summary": "Store API: the products list and stock",
    "description": "With a GET request to the products address of the store API. The response returns the products, a hundred a page, each with its name, SKU, price, compare-at price, stock, link and picture, and its sizes or colours, each with its own price and stock. The has_more field says whether there is a next page. Reference: https://arabybot.com/guides/store-api-products",
    "operationId": "store_api_products",
    "responses": {
     "200": {
      "description": "Success"
     },
     "401": {
      "description": "unauthorized: The key is missing, wrong or revoked."
     },
     "402": {
      "description": "store_plan_closed: The store plan has ended; renew it."
     },
     "429": {
      "description": "More than 120 requests in a minute."
     },
     "500": {
      "description": "server_error: A failure on our side; try again."
     }
    },
    "parameters": [
     {
      "name": "page",
      "in": "query",
      "required": false,
      "description": "The page number, starting at 1. A page holds 100 products.",
      "schema": {
       "type": "integer"
      }
     }
    ]
   }
  },
  "/store_api/v1/products/{id}/stock": {
   "post": {
    "summary": "Store API: update stock from your system",
    "description": "With a POST request to the stock address under the product id, with a key that has write access. You send either the new quantity in the stock field, or the difference up or down in the delta field. A product with sizes needs the size's id, because the product's own stock is the sum of its sizes. The change is written in the product's stock history as «via API». Reference: https://arabybot.com/guides/store-api-product-stock",
    "operationId": "store_api_product_stock",
    "responses": {
     "200": {
      "description": "Success"
     },
     "403": {
      "description": "read_only_key: The key can read only; create a key with write access in the store settings."
     },
     "422": {
      "description": "stock_required: Neither stock nor delta was sent. | bad_stock: The difference is larger than a million units."
     },
     "409": {
      "description": "variant_required: The product has sizes; send variant_id."
     },
     "404": {
      "description": "not_found: No product with this id in the store, or the variant is not one of its own."
     },
     "401": {
      "description": "unauthorized: The key is missing, wrong or revoked."
     },
     "402": {
      "description": "store_plan_closed: The store plan has ended; renew it."
     },
     "429": {
      "description": "More than 120 requests in a minute."
     },
     "500": {
      "description": "server_error: A failure on our side; try again."
     }
    },
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "stock": {
          "type": "integer",
          "description": "The new quantity as it is. Send this field or delta."
         },
         "delta": {
          "type": "integer",
          "description": "The difference: a positive number to add, a negative one to take away."
         },
         "variant_id": {
          "type": "integer",
          "description": "The variant id. Required for a product that has sizes."
         }
        }
       }
      }
     }
    }
   }
  },
  "/store_api/v1/products/{id}/price": {
   "post": {
    "summary": "Store API: update price and compare-at price",
    "description": "With a POST request to the price address under the product id, carrying the new price, with a key that has write access. The compare-at price can be sent with it, and is kept only if it is greater than the price. If you send a variant id, only that size's price changes. The new price shows in the store straight away. Reference: https://arabybot.com/guides/store-api-product-price",
    "operationId": "store_api_product_price",
    "responses": {
     "200": {
      "description": "Success"
     },
     "403": {
      "description": "read_only_key: The key can read only; create a key with write access in the store settings."
     },
     "422": {
      "description": "bad_price: The price is missing, not a number, negative or above the ceiling."
     },
     "404": {
      "description": "not_found: No product with this id in the store, or the variant is not one of its own."
     },
     "401": {
      "description": "unauthorized: The key is missing, wrong or revoked."
     },
     "402": {
      "description": "store_plan_closed: The store plan has ended; renew it."
     },
     "429": {
      "description": "More than 120 requests in a minute."
     },
     "500": {
      "description": "server_error: A failure on our side; try again."
     }
    },
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "price": {
          "type": "number",
          "description": "The new price, a non-negative number, rounded to two decimal places."
         },
         "compare_at_price": {
          "type": "number",
          "description": "The compare-at price. Kept if greater than the price, otherwise cleared. For the product, not for a variant."
         },
         "variant_id": {
          "type": "integer",
          "description": "The variant id; if sent, only that size's price changes."
         }
        },
        "required": [
         "price"
        ]
       }
      }
     }
    }
   }
  }
 }
}