@ratio-mcp/dev-server 1.5.1 → 1.6.0

package/dist/schemas/orders.json

@@ -1,11 +1,16 @@
 {
   "resource": "orders",
-  "base_url": "https://gkx.gokwik.co/aes",
   "auth": {
     "type": "bearer",
     "header": "Authorization",
     "format": "Bearer <access_token>"
   },
+  "common_headers": {
+    "merchant-mid": "Merchant ID for filtering orders",
+    "Gk-Request-Id": "Request ID for tracing",
+    "Gk-Customer-Id": "Customer ID for authorization"
+  },
+  "_generated": "by scripts/sync-schemas.mjs from backend OpenAPI (x-required-scope). Do not hand-edit.",
   "endpoints": [
     {
       "method": "GET",
@@ -13,155 +18,645 @@
       "controller_order": 1,
       "handler_name": "getOrders",
       "required_scope": "read_orders",
-      "summary": "List orders with pagination and filtering",
-      "description": "Retrieve a paginated list of orders from the merchant's store. Supports filtering by status, financial status, fulfillment status, and search.",
+      "summary": "Get a list of orders.",
       "query_params": [
-        { "name": "limit", "type": "number", "required": false, "default": 50, "description": "Number of orders per page (max 100)" },
-        { "name": "page", "type": "number", "required": false, "default": 1, "description": "Page number for pagination" },
-        { "name": "status", "type": "string", "required": false, "enum": ["any", "open", "cancelled", "archived"], "description": "Filter by order status" },
-        { "name": "financial_status", "type": "string", "required": false, "enum": ["pending", "authorized", "partially_paid", "paid", "partially_refunded", "refunded", "voided"], "description": "Filter by payment/financial status" },
-        { "name": "fulfillment_status", "type": "string", "required": false, "enum": ["unfulfilled", "fulfilled", "partial", "partially_fulfilled", "restocked", "pending", "refunded", "returned"], "description": "Filter by fulfillment/shipping status" },
-        { "name": "sort_field", "type": "string", "required": false, "enum": ["created_at", "updated_at", "processed_at", "order_number", "total_price", "items", "financial_status", "fulfillment_status"], "description": "Field to sort by" },
-        { "name": "sort_direction", "type": "string", "required": false, "enum": ["asc", "desc"], "description": "Sort direction" },
-        { "name": "search", "type": "string", "required": false, "description": "Search by order number, email, or phone" }
+        {
+          "name": "limit",
+          "type": "number",
+          "required": false
+        },
+        {
+          "name": "page",
+          "type": "number",
+          "required": false
+        },
+        {
+          "name": "status",
+          "type": "string",
+          "required": false
+        },
+        {
+          "name": "fulfillment_status",
+          "type": "string",
+          "required": false
+        },
+        {
+          "name": "financial_status",
+          "type": "string",
+          "required": false
+        },
+        {
+          "name": "sort_field",
+          "type": "string",
+          "required": false
+        },
+        {
+          "name": "sort_direction",
+          "type": "string",
+          "required": false,
+          "enum": [
+            "asc",
+            "desc"
+          ]
+        },
+        {
+          "name": "search",
+          "type": "string",
+          "required": false
+        }
       ],
-      "request_body": null,
-      "response_schema": "OrderListResponse"
-    },
-    {
-      "method": "GET",
-      "path": "/api/v1/orders/:id",
-      "controller_order": 2,
-      "handler_name": "getOrderById",
-      "required_scope": "read_orders",
-      "summary": "Get a single order by ID",
-      "description": "Retrieve the full details of a single order including line items, customer info, addresses, and payment status.",
-      "path_params": [
-        { "name": "id", "type": "string", "required": true, "description": "The order ID" }
-      ],
-      "request_body": null,
-      "response_schema": "Order"
+      "request_body": null
     },
     {
       "method": "POST",
       "path": "/api/v1/orders",
-      "controller_order": 3,
+      "controller_order": 2,
       "handler_name": "createOrder",
-      "required_scope": "write_orders",
-      "summary": "Create a new order",
-      "description": "Create an order in the merchant's store.",
+      "required_scope": "order-create",
+      "summary": "Create a new order.",
       "request_body": {
         "content_type": "application/json",
         "fields": [
-          { "name": "payment_gateway_names", "type": "string[]", "required": true, "description": "Payment gateways used" },
-          { "name": "financial_status", "type": "string", "required": true, "enum": ["pending", "authorized", "partially_paid", "paid", "partially_refunded", "refunded", "voided"], "description": "Payment status" },
-          { "name": "currency", "type": "string", "required": true, "description": "Currency code (e.g. INR)" },
-          { "name": "test", "type": "boolean", "required": true, "description": "Whether this is a test order" },
-          { "name": "note", "type": "string", "required": false, "description": "Internal note for the order" },
-          { "name": "tags", "type": "string", "required": false, "description": "Comma-separated tags" },
-          { "name": "email", "type": "string", "required": false, "description": "Customer email" },
-          { "name": "phone", "type": "string", "required": false, "description": "Customer phone" },
-          { "name": "customer", "type": "object", "required": true, "description": "Customer details (id, email, first_name, last_name, state, phone, currency)" },
-          { "name": "line_items", "type": "array", "required": true, "description": "Array of line items (variant_id, product_id, title, quantity, sku, price, taxable, requires_shipping, image)" },
-          { "name": "billing_address", "type": "object", "required": true, "description": "Billing address (address1, city, country, first_name, last_name, phone, province, zip)" },
-          { "name": "shipping_address", "type": "object", "required": true, "description": "Shipping address (same structure as billing_address)" }
+          {
+            "name": "draft_id",
+            "type": "string",
+            "required": false,
+            "description": "The draft order ID to convert to an order"
+          },
+          {
+            "name": "order_id",
+            "type": "string",
+            "required": false,
+            "description": "The order ID  order"
+          },
+          {
+            "name": "checkout_id",
+            "type": "number",
+            "required": false,
+            "description": "The checkout ID"
+          },
+          {
+            "name": "cart_token",
+            "type": "string",
+            "required": false,
+            "description": "The cart token"
+          },
+          {
+            "name": "email",
+            "type": "string",
+            "required": false,
+            "description": "The email of the customer"
+          },
+          {
+            "name": "phone",
+            "type": "string",
+            "required": false,
+            "description": "The phone of the customer"
+          },
+          {
+            "name": "user_id",
+            "type": "number",
+            "required": false,
+            "description": "The user ID"
+          },
+          {
+            "name": "customer_locale",
+            "type": "string",
+            "required": false,
+            "description": "The customer locale"
+          },
+          {
+            "name": "landing_site",
+            "type": "string",
+            "required": false,
+            "description": "The landing site"
+          },
+          {
+            "name": "landing_site_ref",
+            "type": "string",
+            "required": false,
+            "description": "The landing site reference"
+          },
+          {
+            "name": "referring_site",
+            "type": "string",
+            "required": false,
+            "description": "The referring site"
+          },
+          {
+            "name": "source_identifier",
+            "type": "string",
+            "required": false,
+            "description": "The source identifier"
+          },
+          {
+            "name": "source_name",
+            "type": "string",
+            "required": false,
+            "description": "The source name"
+          },
+          {
+            "name": "source_url",
+            "type": "string",
+            "required": false,
+            "description": "The source URL"
+          },
+          {
+            "name": "merchant_business_entity_id",
+            "type": "string",
+            "required": false,
+            "description": "The merchant business entity ID"
+          },
+          {
+            "name": "merchant_of_record_app_id",
+            "type": "number",
+            "required": false,
+            "description": "The merchant of record agent ID"
+          },
+          {
+            "name": "note_attributes",
+            "type": "object",
+            "required": false,
+            "description": "The note attributes of the order"
+          },
+          {
+            "name": "tags",
+            "type": "string",
+            "required": false,
+            "description": "The tags of the order"
+          },
+          {
+            "name": "tag_ids",
+            "type": "string[]",
+            "required": false,
+            "description": "Array of tag IDs to associate with the order"
+          },
+          {
+            "name": "payment_gateway_names",
+            "type": "string[]",
+            "required": true,
+            "description": "The payment gateway names"
+          },
+          {
+            "name": "confirmed",
+            "type": "boolean",
+            "required": false,
+            "description": "Whether the order is confirmed (defaults to true)"
+          },
+          {
+            "name": "order_number",
+            "type": "object",
+            "required": false,
+            "description": "The order number (will be generated if not provided)"
+          },
+          {
+            "name": "fulfillment_status",
+            "type": "string",
+            "required": false,
+            "description": "The fulfillment status of the order (defaults to UNFULFILLED)",
+            "enum": [
+              "fulfilled",
+              "unfulfilled",
+              "partially_fulfilled",
+              "restocked",
+              "pending_fulfillment"
+            ]
+          },
+          {
+            "name": "status",
+            "type": "string",
+            "required": false,
+            "description": "The status of the order (defaults to OPEN)",
+            "enum": [
+              "open",
+              "closed",
+              "cancelled"
+            ]
+          },
+          {
+            "name": "financial_status",
+            "type": "string",
+            "required": true,
+            "description": "The financial status of the order",
+            "enum": [
+              "pending",
+              "paid",
+              "partially_paid",
+              "refunded",
+              "voided",
+              "partially_refunded",
+              "authorized"
+            ]
+          },
+          {
+            "name": "presentment_currency",
+            "type": "string",
+            "required": false,
+            "description": "The presentment currency"
+          },
+          {
+            "name": "customer",
+            "type": "string",
+            "required": false,
+            "description": "The customer object"
+          },
+          {
+            "name": "test",
+            "type": "boolean",
+            "required": true,
+            "description": "Whether the order is a test order"
+          },
+          {
+            "name": "billing_address",
+            "type": "string",
+            "required": false,
+            "description": "The billing address"
+          },
+          {
+            "name": "shipping_address",
+            "type": "string",
+            "required": false,
+            "description": "The shipping address"
+          },
+          {
+            "name": "discount_codes",
+            "type": "array",
+            "required": false,
+            "description": "The discount codes"
+          },
+          {
+            "name": "discount_applications",
+            "type": "array",
+            "required": false,
+            "description": "The discount applications"
+          },
+          {
+            "name": "name",
+            "type": "string",
+            "required": false,
+            "description": "The name of the order (will be generated if not provided)"
+          },
+          {
+            "name": "note",
+            "type": "string",
+            "required": false,
+            "description": "The note of the order"
+          },
+          {
+            "name": "line_items",
+            "type": "array",
+            "required": true,
+            "description": "The line items of the order"
+          },
+          {
+            "name": "subtotal_price",
+            "type": "string",
+            "required": false,
+            "description": "The subtotal price of the order"
+          },
+          {
+            "name": "total_line_items_price",
+            "type": "string",
+            "required": false,
+            "description": "The total line items price of the order"
+          },
+          {
+            "name": "total_line_items_price_set",
+            "type": "string",
+            "required": false,
+            "description": "The total line items price set of the order"
+          },
+          {
+            "name": "total_outstanding",
+            "type": "number",
+            "required": false,
+            "description": "The total outstanding of the order"
+          },
+          {
+            "name": "total_weight",
+            "type": "number",
+            "required": false,
+            "description": "The total weight of the order in grams"
+          },
+          {
+            "name": "total_tip_received",
+            "type": "number",
+            "required": false,
+            "description": "The total tip received for the order"
+          },
+          {
+            "name": "current_total_discounts",
+            "type": "number",
+            "required": false,
+            "description": "The current total discounts of the order"
+          },
+          {
+            "name": "total_discounts",
+            "type": "number",
+            "required": false,
+            "description": "The total discounts of the order"
+          },
+          {
+            "name": "estimated_taxes",
+            "type": "boolean",
+            "required": false,
+            "description": "Whether taxes are estimated"
+          },
+          {
+            "name": "total_price",
+            "type": "number",
+            "required": false,
+            "description": "The total price of the order"
+          },
+          {
+            "name": "total_price_set",
+            "type": "string",
+            "required": false,
+            "description": "The total price set of the order"
+          },
+          {
+            "name": "subtotal_price_set",
+            "type": "string",
+            "required": false,
+            "description": "The subtotal price set of the order"
+          },
+          {
+            "name": "current_total_tax",
+            "type": "number",
+            "required": false,
+            "description": "The current total tax of the order"
+          },
+          {
+            "name": "current_total_tax_set",
+            "type": "string",
+            "required": false,
+            "description": "The current total tax set of the order"
+          },
+          {
+            "name": "total_tax_set",
+            "type": "string",
+            "required": false,
+            "description": "The total tax set of the order"
+          },
+          {
+            "name": "taxes_included",
+            "type": "boolean",
+            "required": false,
+            "description": "Whether taxes are included"
+          },
+          {
+            "name": "tax_exempt",
+            "type": "boolean",
+            "required": false,
+            "description": "Whether the order is tax exempt"
+          },
+          {
+            "name": "tax_lines",
+            "type": "array",
+            "required": false,
+            "description": "The tax lines of the order"
+          },
+          {
+            "name": "total_tax",
+            "type": "number",
+            "required": false,
+            "description": "The total tax of the order"
+          },
+          {
+            "name": "duties_included",
+            "type": "boolean",
+            "required": false,
+            "description": "Whether duties are included in the order"
+          },
+          {
+            "name": "current_total_price_set",
+            "type": "string",
+            "required": false,
+            "description": "The current total price set of the order"
+          },
+          {
+            "name": "currency",
+            "type": "string",
+            "required": true,
+            "description": "The currency of the order"
+          },
+          {
+            "name": "payment_details",
+            "type": "string",
+            "required": false,
+            "description": "The payment details"
+          },
+          {
+            "name": "shipping_lines",
+            "type": "array",
+            "required": false,
+            "description": "The shipping lines of the order"
+          },
+          {
+            "name": "external_order_id",
+            "type": "string",
+            "required": false,
+            "description": "The external order ID"
+          }
         ]
-      },
-      "response_schema": "Order"
+      }
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/orders/:id",
+      "controller_order": 3,
+      "handler_name": "getOrderById",
+      "required_scope": "read_orders",
+      "summary": "Get a single order by id.",
+      "path_params": [
+        {
+          "name": "id",
+          "type": "string",
+          "required": true
+        }
+      ],
+      "request_body": null
     },
     {
       "method": "PATCH",
       "path": "/api/v1/orders/:id",
       "controller_order": 4,
       "handler_name": "updateOrder",
-      "required_scope": "write_orders",
-      "summary": "Update an existing order",
-      "description": "Update order fields. Only provided fields are modified.",
+      "required_scope": "order-create",
+      "summary": "Update an existing order.",
       "path_params": [
-        { "name": "id", "type": "string", "required": true, "description": "The order ID to update" }
+        {
+          "name": "id",
+          "type": "string",
+          "required": true
+        }
       ],
       "request_body": {
         "content_type": "application/json",
         "fields": [
-          { "name": "email", "type": "string", "required": false, "description": "Updated customer email" },
-          { "name": "phone", "type": "string", "required": false, "description": "Updated customer phone" },
-          { "name": "note", "type": "string", "required": false, "description": "Updated order note" },
-          { "name": "tags", "type": "string", "required": false, "description": "Updated tags (comma-separated)" },
-          { "name": "status", "type": "string", "required": false, "enum": ["open", "closed", "cancelled"], "description": "Order status" },
-          { "name": "financial_status", "type": "string", "required": false, "enum": ["pending", "authorized", "partially_paid", "paid", "partially_refunded", "refunded", "voided"] },
-          { "name": "fulfillment_status", "type": "string", "required": false, "enum": ["fulfilled", "partial", "partially_fulfilled", "unfulfilled", "restocked", "pending", "refunded", "returned"] },
-          { "name": "shipping_address", "type": "object", "required": false, "description": "Updated shipping address" },
-          { "name": "line_items", "type": "array", "required": false, "description": "Updated line items" }
+          {
+            "name": "buyer_accepts_marketing",
+            "type": "boolean",
+            "required": false,
+            "description": "Whether the buyer accepts marketing"
+          },
+          {
+            "name": "email",
+            "type": "string",
+            "required": false,
+            "description": "The email of the order"
+          },
+          {
+            "name": "phone",
+            "type": "string",
+            "required": false,
+            "description": "The phone of the order"
+          },
+          {
+            "name": "note",
+            "type": "string",
+            "required": false,
+            "description": "The note of the order"
+          },
+          {
+            "name": "tags",
+            "type": "string",
+            "required": false,
+            "description": "The tags of the order"
+          },
+          {
+            "name": "tag_ids",
+            "type": "string[]",
+            "required": false,
+            "description": "Array of tag IDs to associate with the order"
+          },
+          {
+            "name": "status",
+            "type": "string",
+            "required": false,
+            "description": "The status of the order",
+            "enum": [
+              "open",
+              "closed",
+              "cancelled"
+            ]
+          },
+          {
+            "name": "financial_status",
+            "type": "string",
+            "required": false,
+            "description": "The financial status of the order",
+            "enum": [
+              "pending",
+              "authorized",
+              "partially_paid",
+              "paid",
+              "partially_refunded",
+              "refunded",
+              "voided"
+            ]
+          },
+          {
+            "name": "fulfillment_status",
+            "type": "string",
+            "required": false,
+            "description": "The fulfillment status of the order",
+            "enum": [
+              "fulfilled",
+              "partial",
+              "partially_fulfilled",
+              "unfulfilled",
+              "restocked",
+              "pending",
+              "refunded",
+              "returned"
+            ]
+          },
+          {
+            "name": "metafields",
+            "type": "array",
+            "required": false,
+            "description": "The metafields of the order"
+          },
+          {
+            "name": "shipping_address",
+            "type": "string",
+            "required": false,
+            "description": "The shipping address of the order"
+          },
+          {
+            "name": "billing_address",
+            "type": "string",
+            "required": false,
+            "description": "The billing address of the order"
+          },
+          {
+            "name": "customer",
+            "type": "string",
+            "required": false,
+            "description": "The customer information for the order"
+          },
+          {
+            "name": "total_outstanding",
+            "type": "object",
+            "required": false,
+            "description": "The total outstanding amount on the order"
+          },
+          {
+            "name": "line_items",
+            "type": "array",
+            "required": false,
+            "description": "The line items of the order. Can include existing items with updated quantities or new items. Set to an empty array [] to remove all line items."
+          }
         ]
-      },
-      "response_schema": "Order"
+      }
     },
     {
       "method": "PATCH",
       "path": "/api/v1/orders/:id/cancel",
       "controller_order": 5,
       "handler_name": "cancelOrder",
-      "required_scope": "write_orders",
-      "summary": "Cancel an existing order",
-      "description": "Cancel an existing order with optional reason and restock settings.",
+      "required_scope": "order-create",
+      "summary": "Cancel an existing order.",
       "path_params": [
-        { "name": "id", "type": "string", "required": true, "description": "The order ID to cancel" }
+        {
+          "name": "id",
+          "type": "string",
+          "required": true
+        }
       ],
       "request_body": {
         "content_type": "application/json",
-        "fields": [
-          { "name": "cancel_reason", "type": "string", "required": false, "description": "Reason for cancellation" },
-          { "name": "staff_note", "type": "string", "required": false, "description": "Internal note about the cancellation" },
-          { "name": "restock_inventory", "type": "boolean", "required": false, "description": "Whether to restock inventory" },
-          { "name": "send_notification", "type": "boolean", "required": false, "description": "Whether to send notification to customer" }
-        ]
-      },
-      "response_schema": "Order"
+        "fields": []
+      }
     },
     {
       "method": "PATCH",
       "path": "/api/v1/orders/:id/external-id",
       "controller_order": 6,
       "handler_name": "updateOrderExternalId",
-      "required_scope": "write_orders",
-      "summary": "Update external ID for an order",
-      "description": "Updates the external_order_id field for a single order. Useful for syncing with external systems.",
+      "required_scope": "order-create",
+      "summary": "Update external ID for a specific order",
+      "description": "Updates the external_order_id field for a single order. This is useful for syncing with external systems or correcting mismatches.",
       "path_params": [
-        { "name": "id", "type": "string", "required": true, "description": "The order ID" }
+        {
+          "name": "id",
+          "type": "string",
+          "required": true,
+          "description": "Order ID"
+        }
       ],
       "request_body": {
         "content_type": "application/json",
         "fields": [
-          { "name": "external_id", "type": "string", "required": true, "description": "External reference ID from your system" }
+          {
+            "name": "external_id",
+            "type": "string",
+            "required": true,
+            "description": "The external ID to sync with"
+          }
         ]
-      },
-      "response_schema": "Order"
-    }
-  ],
-  "schemas": {
-    "Order": {
-      "id": "string — unique order identifier",
-      "order_number": "number — sequential order number",
-      "email": "string | null — customer email",
-      "phone": "string | null — customer phone",
-      "financial_status": "'pending' | 'authorized' | 'partially_paid' | 'paid' | 'partially_refunded' | 'refunded' | 'voided'",
-      "fulfillment_status": "'unfulfilled' | 'partial' | 'fulfilled' | 'partially_fulfilled' | 'restocked' | 'pending' | 'refunded' | 'returned'",
-      "status": "'open' | 'closed' | 'cancelled' | 'archived'",
-      "currency": "string — currency code (e.g. 'INR')",
-      "total_price": "number — final total price",
-      "subtotal_price": "number — subtotal before tax and discounts",
-      "total_tax": "number — total tax amount",
-      "total_discounts": "number — total discount amount",
-      "line_items": "LineItem[] — items in the order",
-      "customer": "Customer object",
-      "shipping_address": "Address | null",
-      "billing_address": "Address | null",
-      "note": "string | null — internal note",
-      "tags": "string — comma-separated tags",
-      "created_at": "string — ISO 8601 timestamp",
-      "updated_at": "string — ISO 8601 timestamp",
-      "cancelled_at": "string | null — ISO 8601 timestamp if cancelled"
+      }
     }
-  },
-  "statuses": ["pending", "confirmed", "processing", "shipped", "delivered", "cancelled", "refunded"]
+  ]
 }