{ "openapi": "3.1.0", "info": { "title": "NBOX NOW Seller API", "version": "1.0.0", "description": "The NBOX NOW Seller API enables e-commerce platforms to integrate shipping,\norder management, and tracking into their storefronts.\n\n## Authentication\n\n### Step 1: Login\nCall `POST /api/login` with your seller credentials to obtain a shop token.\n\n### Step 2: Use Token\nInclude the token in all subsequent requests:\n```\nx-nbox-token: \nx-nbox-shop-domain: \n```\n\n## Base URLs\n\n| Environment | URL |\n|-------------|-----|\n| Production | `https://nbox.now/api` |\n| Staging | `https://staging.nbox.now/api` |\n\n## Response Format\n\n**Success:**\n```json\n{\n \"status\": \"success\",\n \"message\": \"...\",\n \"data\": { ... }\n}\n```\n\n**Error:**\n```json\n{\n \"status\": \"failed\",\n \"message\": \"Human-readable error\",\n \"code\": \"ERROR_CODE\"\n}\n```\n", "x-logo": { "url": "/images/nbox-logo-blue.png", "altText": "NBOX NOW" }, "contact": { "name": "NBOX Systems", "email": "support@nbox.qa" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://nbox.now/api", "description": "Production" }, { "url": "https://staging.nbox.now/api", "description": "Staging" } ], "tags": [ { "name": "Authentication", "description": "Login and shop activation" }, { "name": "Locations", "description": "Shop pickup location management" }, { "name": "Rates", "description": "Shipping rate calculation" }, { "name": "Orders", "description": "Order creation, updates, fulfillment, and cancellation" }, { "name": "Returns", "description": "Return shipment creation and eligibility" }, { "name": "Webhooks", "description": "Webhook endpoint management" }, { "name": "Labels", "description": "AWB label generation" } ], "paths": { "/api/activation": { "post": { "operationId": "activateShop", "tags": [ "Authentication" ], "summary": "Activate or deactivate a shop", "security": [ { "ShopTokenAuth": [] }, { "ShopDomainAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivationRequest" } } } }, "responses": { "200": { "description": "Activation status updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "enum": [ "activated", "deactivated" ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "unauthorized" }, "message": { "type": "string" } } } } } } } } }, "/api/awb/{id}": { "get": { "operationId": "downloadAwb", "tags": [ "Labels" ], "summary": "Download an AWB label as PDF", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Unified reference ID (e.g., ORD-SHOP-1001)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "AWB label PDF", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Record not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Record not found" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } } } }, "/api/fulfilled": { "post": { "operationId": "fulfillOrder", "tags": [ "Orders" ], "summary": "Mark an order as fulfilled", "security": [ { "ShopTokenAuth": [] }, { "ShopDomainAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FulfilledRequest" } } } }, "responses": { "200": { "description": "Order fulfilled successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "failed" ] }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized — invalid token or shop domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/locations/{method}": { "post": { "operationId": "manageLocations", "tags": [ "Locations" ], "summary": "Add or update shop locations", "security": [ { "ShopDomainAuth": [] } ], "parameters": [ { "name": "method", "in": "path", "required": true, "description": "add or update", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "locations": { "type": "array", "items": { "$ref": "#/components/schemas/LocationAddress" } } } } } } }, "responses": { "200": { "description": "Locations updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Locations Updated" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequest" } } } } } } }, "/api/login": { "post": { "operationId": "loginSeller", "tags": [ "Authentication" ], "summary": "Authenticate seller and obtain a shop token", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } } }, "responses": { "200": { "description": "Login successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "token": { "type": "string", "description": "Shop authentication token" } } } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "message": { "type": "string", "example": "Invalid username or password" } } } } } } } } }, "/api/order/{id}/update": { "put": { "operationId": "updateOrder", "tags": [ "Orders" ], "summary": "Update an existing order", "security": [ { "ShopTokenAuth": [] }, { "ShopDomainAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order reference or shipment ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrderRequest" } } } }, "responses": { "200": { "description": "Order updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "order": { "type": "object" }, "updatedFields": { "type": "array", "items": { "type": "string" } } } }, "warnings": { "type": "array" } } } } } }, "400": { "description": "Bad request — validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized — invalid token or shop domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Order not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Update blocked — order in non-updatable state", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "code": { "type": "string", "example": "UPDATE_BLOCKED" }, "message": { "type": "string" } } } } } } } } }, "/api/order/cancelled": { "post": { "operationId": "cancelOrder", "tags": [ "Orders" ], "summary": "Cancel an order", "security": [ { "ShopTokenAuth": [] }, { "ShopDomainAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelRequest" } } } }, "responses": { "200": { "description": "Cancellation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success", "failed", "ignored" ] }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized — invalid token or shop domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/order": { "post": { "operationId": "createOrder", "tags": [ "Orders" ], "summary": "Create a new order", "security": [ { "ShopTokenAuth": [] }, { "ShopDomainAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrderRequest" } } } }, "responses": { "200": { "description": "Order created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCreatedResponse" } } } }, "400": { "description": "Bad request — validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized — invalid token or shop domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/rates": { "post": { "operationId": "calculateRates", "tags": [ "Rates" ], "summary": "Calculate shipping rates for given products and destination", "security": [ { "ShopTokenAuth": [] }, { "ShopDomainAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateRequest" } } } }, "responses": { "200": { "description": "Rates calculated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "rates": { "type": "array", "items": { "$ref": "#/components/schemas/RateOption" } }, "calculationMethod": { "type": "string" }, "productMetrics": { "type": "object" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequest" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "unauthorized" }, "message": { "type": "string" } } } } } } } } }, "/api/return-shipment": { "get": { "operationId": "checkReturnEligibility", "tags": [ "Returns" ], "summary": "Check return shipment eligibility", "security": [ { "ShopTokenAuth": [] }, { "ShopDomainAuth": [] } ], "parameters": [ { "name": "shipment_id", "in": "query", "required": true, "description": "Unified reference ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Eligibility check result", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "eligible": { "type": "boolean" }, "reason": { "type": "string" } } } } } }, "400": { "description": "Bad request — missing shipment_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized — invalid token or shop domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Original shipment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "createReturnShipment", "tags": [ "Returns" ], "summary": "Create a return shipment", "security": [ { "ShopTokenAuth": [] }, { "ShopDomainAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnShipmentRequest" } } } }, "responses": { "201": { "description": "Return shipment created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnCreatedResponse" } } } }, "400": { "description": "Bad request — validation failed or not eligible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized — invalid token or shop domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Original shipment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/webhooks": { "get": { "operationId": "listSellerWebhooks", "tags": [ "Webhooks" ], "summary": "List all webhook endpoints", "security": [ { "ShopTokenAuth": [] }, { "ShopDomainAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "description": "Webhook ID to retrieve a single webhook", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook list retrieved", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/SellerWebhookEndpoint" } }, "count": { "type": "integer" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized — invalid token or shop domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Webhook not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "createSellerWebhook", "tags": [ "Webhooks" ], "summary": "Create a new webhook endpoint", "security": [ { "ShopTokenAuth": [] }, { "ShopDomainAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSellerWebhookRequest" } } } }, "responses": { "201": { "description": "Webhook created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string" }, "webhook": { "$ref": "#/components/schemas/SellerWebhookEndpoint" } } } } } }, "400": { "description": "Bad request — validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized — invalid token or shop domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "operationId": "updateSellerWebhook", "tags": [ "Webhooks" ], "summary": "Update a webhook endpoint", "security": [ { "ShopTokenAuth": [] }, { "ShopDomainAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": true, "description": "Webhook ID to update", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSellerWebhookRequest" } } } }, "responses": { "200": { "description": "Webhook updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string" }, "webhook": { "$ref": "#/components/schemas/SellerWebhookEndpoint" } } } } } }, "400": { "description": "Bad request — validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized — invalid token or shop domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Webhook not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "deleteSellerWebhook", "tags": [ "Webhooks" ], "summary": "Delete a webhook endpoint", "security": [ { "ShopTokenAuth": [] }, { "ShopDomainAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": true, "description": "Webhook ID to delete", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized — invalid token or shop domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Webhook not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "securitySchemes": { "ShopTokenAuth": { "type": "apiKey", "in": "header", "name": "x-nbox-token", "description": "Shop token obtained from the login endpoint" }, "ShopDomainAuth": { "type": "apiKey", "in": "header", "name": "x-nbox-shop-domain", "description": "Shop domain identifier" } }, "responses": { "Unauthorized": { "description": "Missing or invalid shop token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "failed", "message": "Unauthorized" } } } }, "BadRequest": { "description": "Invalid or missing parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "failed", "message": "Invalid parameters" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "failed", "message": "Not found" } } } }, "InternalError": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "failed", "message": "Internal server error" } } } } }, "schemas": { "ErrorResponse": { "type": "object", "properties": { "status": { "type": "string", "const": "failed" }, "message": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "status", "message" ] }, "LoginRequest": { "type": "object", "required": [ "email", "password", "shopId" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string" }, "shopId": { "type": "string", "description": "Unique shop identifier (or shopDomain)" }, "shopName": { "type": "string", "description": "Shop display name" }, "platform": { "type": "string", "description": "E-commerce platform (e.g., shopify, woocommerce, custom)" }, "url": { "type": "string", "format": "uri", "description": "Shop URL" }, "locations": { "type": "array", "items": { "$ref": "#/components/schemas/LocationAddress" }, "description": "Shop pickup locations to register" } } }, "ActivationRequest": { "type": "object", "required": [ "activate" ], "properties": { "activate": { "type": "boolean", "description": "true to activate, false to deactivate" }, "locations": { "type": "array", "items": { "$ref": "#/components/schemas/LocationAddress" } } } }, "LocationAddress": { "type": "object", "properties": { "address": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "countryCode": { "type": "string" }, "zip": { "type": "string" }, "lat": { "type": "number", "format": "double" }, "lng": { "type": "number", "format": "double" } } }, "RateRequest": { "type": "object", "required": [ "destination", "products" ], "properties": { "origin": { "$ref": "#/components/schemas/LocationAddress" }, "destination": { "$ref": "#/components/schemas/LocationAddress" }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/ProductItem" } } } }, "ProductItem": { "type": "object", "properties": { "name": { "type": "string" }, "price": { "type": "number", "format": "double" }, "quantity": { "type": "integer" }, "currency": { "type": "string" }, "grams": { "type": "number", "format": "double", "description": "Weight in grams" }, "length": { "type": "number", "format": "double", "description": "Length in cm" }, "width": { "type": "number", "format": "double" }, "height": { "type": "number", "format": "double" }, "volume": { "type": "number", "format": "double", "description": "Volume in cm³" } } }, "RateOption": { "type": "object", "properties": { "service_code": { "type": "string", "description": "Carrier code (e.g., ARAMEX, FEDEX, NBOX)" }, "service_name": { "type": "string" }, "actualRate": { "type": "number", "format": "double", "description": "Business rate charged by NBox" }, "displayRate": { "type": "number", "format": "double", "description": "Customer-facing rate" }, "hasDisplayRule": { "type": "boolean" }, "distanceKm": { "type": [ "number", "null" ], "format": "double" }, "baseRate": { "type": [ "number", "null" ], "format": "double" }, "discountAmount": { "type": [ "number", "null" ], "format": "double" }, "appliedRules": { "type": "array", "items": { "type": "object" } } } }, "CreateOrderRequest": { "type": "object", "required": [ "order", "customer", "destination", "products" ], "properties": { "order": { "type": "object", "required": [ "orderNumber", "orderReference", "total", "currency" ], "properties": { "orderNumber": { "type": "string", "description": "Unique order number per shop" }, "orderReference": { "type": "string", "description": "Unique order identifier" }, "total": { "type": "number", "format": "double" }, "subTotal": { "type": "number", "format": "double" }, "currency": { "type": "string", "description": "Currency code (e.g., QAR)" }, "carrier": { "type": "string", "description": "Carrier code or \"auto\" for cheapest" }, "paymentStatus": { "type": "string", "enum": [ "prepaid", "postpaid" ], "description": "prepaid = paid online, postpaid = COD" }, "paymentMethod": { "type": "string", "maxLength": 50 }, "shippingFee": { "type": "number", "format": "double", "description": "What customer pays for shipping" }, "tax": { "type": "number", "format": "double" }, "discount": { "type": "number", "format": "double" }, "collectionAmount": { "type": "number", "format": "double", "description": "COD amount to collect" } } }, "customer": { "$ref": "#/components/schemas/Customer" }, "destination": { "$ref": "#/components/schemas/LocationAddress" }, "origin": { "$ref": "#/components/schemas/LocationAddress" }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/ProductItem" } } } }, "Customer": { "type": "object", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" } } }, "OrderCreatedResponse": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" }, "orderReference": { "type": "string" }, "shipment_id": { "type": "string", "description": "Format: ORD-SHOP-orderRef" }, "awb": { "type": "string" }, "tracking_url": { "type": "string", "format": "uri" }, "nbox": { "type": "object", "properties": { "shipment_detail_id": { "type": "string" }, "shop_id": { "type": "string" } } }, "carrier": { "type": "string" }, "carrierName": { "type": "string" }, "carrierWasAutoSelected": { "type": "boolean" }, "actualRate": { "type": "number", "format": "double" }, "displayRate": { "type": "number", "format": "double" }, "hasDisplayRule": { "type": "boolean" } } }, "UpdateOrderRequest": { "type": "object", "description": "At least one field required. Some fields blocked after pickup.", "properties": { "customer": { "type": "object", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string", "format": "email" } } }, "destinationAddress": { "type": "object", "properties": { "address": { "type": "string" }, "city": { "type": "string" }, "countryCode": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" }, "lat": { "type": "number", "format": "double" }, "lng": { "type": "number", "format": "double" } } }, "orderPaymentStatus": { "type": "string", "enum": [ "prepaid", "postpaid" ] }, "collectionAmount": { "type": "number", "format": "double" }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/ProductItem" } } } }, "FulfilledRequest": { "type": "object", "properties": { "order_id": { "type": "string", "description": "Order ID (Shopify) or order reference" }, "orderNumber": { "type": "string", "description": "Order number (non-Shopify)" }, "location_id": { "type": "string", "description": "Shopify location ID" }, "destination": { "type": "object", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone": { "type": "string" } } }, "email": { "type": "string", "format": "email" } } }, "CancelRequest": { "type": "object", "properties": { "orderNumber": { "type": "string", "description": "Order number or ID to cancel" }, "id": { "type": "string", "description": "Fallback order identifier" } } }, "ReturnShipmentRequest": { "type": "object", "required": [ "shipment_id" ], "properties": { "shipment_id": { "type": "string", "description": "Unified reference ID (e.g., ORD-SHOP-1001)" }, "returnReason": { "type": "string" }, "carrier": { "type": "string", "description": "Carrier code (defaults to original)" }, "notes": { "type": "string" }, "pickupContactInfo": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "string" } } }, "returnContactInfo": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "string" } } } } }, "ReturnCreatedResponse": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" }, "shipment_id": { "type": "string", "description": "Return shipment ID (e.g., RET-SHOP-1002)" }, "original_shipment_id": { "type": "string" }, "awb": { "type": "string" }, "tracking_url": { "type": "string", "format": "uri" }, "carrier": { "type": "string" }, "carrierName": { "type": "string" }, "actualRate": { "type": "number", "format": "double" }, "displayRate": { "type": "number", "format": "double" } } }, "SellerWebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "secret": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "stats": { "type": "object", "properties": { "total_deliveries": { "type": "integer" }, "total_failures": { "type": "integer" }, "consecutive_failures": { "type": "integer" }, "last_triggered_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_failure_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "disabled_reason": { "type": [ "string", "null" ] }, "disabled_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "CreateSellerWebhookRequest": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Must use HTTPS" }, "events": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "description": { "type": "string" } } }, "UpdateSellerWebhookRequest": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "isActive": { "type": "boolean" } } } } } }