{ "openapi": "3.1.0", "info": { "title": "ApprovePro API", "description": "Use this API to retrieve and update design approvals.", "version": "1.0.0", "license": { "name": "Proprietary", "identifier": "LicenseRef-Proprietary" } }, "servers": [ { "url": "https://app.orderapprovepro.com/api/v1", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Orders", "description": "Order retrieval, status updates, comments, due dates, and lookup operations." }, { "name": "Statuses", "description": "Status definition and viable-status listing operations." } ], "paths": { "/orders/{order}/status": { "post": { "tags": [ "Orders" ], "summary": "Update an order status", "description": "Limited to 60 requests per minute.", "operationId": "updateOrderStatus", "parameters": [ { "name": "order", "in": "path", "required": true, "description": "The ID of the order.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrderStatusRequest" }, "example": { "status_code": "st000002", "comment": "This is a comment", "public": true, "email_customer": true, "email_additional": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Order status updated successfully!" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/orders/bulk-status": { "post": { "tags": [ "Orders" ], "summary": "Queue a bulk status update for up to 50 orders", "description": "Limited to 5 requests per minute.", "operationId": "bulkUpdateOrderStatus", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkStatusUpdateRequest" }, "example": { "order_ids": [ 6110375248088, 6110375248089 ], "status_code": "st000003", "comment": "Batch moved to shipped", "public": false, "email_customer": true, "email_additional": false } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkStatusUpdateResponse" }, "example": { "message": "Bulk status update queued.", "count": 2, "limit": 50 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/orders/{order}/comment": { "post": { "tags": [ "Orders" ], "summary": "Add a comment to the order", "description": "Limited to 60 requests per minute.", "operationId": "addOrderComment", "parameters": [ { "name": "order", "in": "path", "required": true, "description": "The ID of the order.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddOrderCommentRequest" }, "example": { "comment": "This is a comment", "public": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Order comment added!" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/orders/{order}/due-date": { "post": { "tags": [ "Orders" ], "summary": "Set a due date on the order", "description": "Limited to 60 requests per minute.", "operationId": "setOrderDueDate", "parameters": [ { "name": "order", "in": "path", "required": true, "description": "The ID of the order.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDueDateRequest" }, "example": { "due_date": "2026-02-10", "due_date_to": "2026-02-12" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "Order due date set!" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/orders": { "get": { "tags": [ "Orders" ], "summary": "Retrieve a paginated list of orders", "description": "Limited to 60 requests per minute.", "operationId": "listOrders", "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Filter by partial match against order name, order number, customer name, or customer email.", "schema": { "type": "string" } }, { "name": "status_code", "in": "query", "required": false, "description": "Filter by a single status code like st000002.", "schema": { "type": "string", "minLength": 8, "maxLength": 8 } }, { "name": "tags[]", "in": "query", "required": false, "description": "Filter by tags that must all be present using repeated query params such as tags[]=commercial&tags[]=commercial-lease.", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true, "examples": { "allTags": { "summary": "Only orders containing every tag", "value": [ "commercial", "commercial-lease" ] } } }, { "name": "tags_any[]", "in": "query", "required": false, "description": "Filter by tags where any listed tag may be present using repeated query params such as tags_any[]=commercial&tags_any[]=commercial-flooring.", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true, "examples": { "anyTags": { "summary": "Orders matching any listed tag", "value": [ "commercial-flooring", "commercial-rental" ] } } }, { "name": "financial_status[]", "in": "query", "required": false, "description": "Filter by one or more financial statuses using repeated query params such as financial_status[]=partially_paid&financial_status[]=pending. Accepted values: paid, partially_paid, partially_refunded, refunded, voided, pending, authorized, unpaid.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "paid", "partially_paid", "partially_refunded", "refunded", "voided", "pending", "authorized", "unpaid" ] } }, "style": "form", "explode": true, "examples": { "dueStatuses": { "summary": "Capture all due orders", "value": [ "partially_paid", "pending", "unpaid" ] } } }, { "name": "fulfillment_status[]", "in": "query", "required": false, "description": "Filter by one or more fulfillment statuses using repeated query params such as fulfillment_status[]=fulfilled. Accepted values: unfulfilled, partial, restocked, fulfilled.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "unfulfilled", "partial", "restocked", "fulfilled" ] } }, "style": "form", "explode": true, "examples": { "fulfilledOnly": { "summary": "Only fulfilled orders", "value": [ "fulfilled" ] } } }, { "name": "exclude_cancelled", "in": "query", "required": false, "description": "When true, excludes orders where cancelled_at is set.", "schema": { "type": "boolean" }, "example": true }, { "name": "due_date_from", "in": "query", "required": false, "description": "Filter to orders with a due date on or after this `YYYY-MM-DD` date.", "schema": { "type": "string", "format": "date" } }, { "name": "due_date_to", "in": "query", "required": false, "description": "Filter to orders with a due date on or before this `YYYY-MM-DD` date.", "schema": { "type": "string", "format": "date" } }, { "name": "per_page", "in": "query", "required": false, "description": "Number of orders to return per page. Defaults to 15. Maximum 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 15 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderListResponse" }, "example": { "data": [ { "id": 6110375248088, "name": "#1188", "order_number": "1188", "customer": { "name": "Jon Smith", "email": "jon@example.com", "locale": "en" }, "status": { "is_set": true, "code": "st000002", "name": "In Production", "public_name": "Crafting With Care", "description": "Order being handcrafted in the workshop", "color": "#F59E0B", "public": true, "set_at": "2026-03-12T10:14:00+00:00", "auto_change_at": null }, "due_date": "2026-03-15T00:00:00+00:00", "due_date_to": "2026-03-17T00:00:00+00:00", "history_count": 4 } ], "meta": { "current_page": 1, "from": 1, "last_page": 1, "per_page": 15, "to": 1, "total": 1 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/orders/{order}": { "get": { "tags": [ "Orders" ], "summary": "Retrieve details of a specific order", "description": "Limited to 60 requests per minute.", "operationId": "getOrder", "parameters": [ { "name": "order", "in": "path", "required": true, "description": "The ID of the order.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/statuses": { "get": { "tags": [ "Statuses" ], "summary": "Get all defined statuses for your account", "description": "Limited to 60 requests per minute.", "operationId": "getStatuses", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StatusDefinition" } }, "example": [ { "name": "Order Received", "description": "We have received your order.", "code": "st000001", "color": "gray" }, { "name": "In Production", "description": "Your order is being handcrafted in the workshop.", "code": "st000002", "color": "pink" }, { "name": "Shipped", "description": "Order has been shipped and is on its way.", "code": "st000003", "color": "green" } ] } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/orders/lookup": { "get": { "tags": [ "Orders" ], "summary": "Retrieve an order by order number and customer email", "description": "Limited to 60 requests per minute.", "operationId": "lookupOrder", "parameters": [ { "name": "number", "in": "query", "required": true, "description": "Order number or name (for example: 1188 or #1188).", "schema": { "type": "string" } }, { "name": "email", "in": "query", "required": true, "description": "Customer email address.", "schema": { "type": "string", "format": "email" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/orders/{order}/viable-statuses": { "get": { "tags": [ "Orders", "Statuses" ], "summary": "Get viable statuses for an order", "description": "Limited to 60 requests per minute.", "operationId": "getViableStatuses", "parameters": [ { "name": "order", "in": "path", "required": true, "description": "The ID of the order.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ViableStatus" } }, "example": [ { "code": "st000002", "name": "In Production", "description": "Order being handcrafted in the workshop", "color": "pink" }, { "code": "st000003", "name": "Shipped", "description": "Safely packed and dispatched", "color": "green" } ] } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key" } }, "responses": { "BadRequest": { "description": "Bad Request. The request was malformed or missing required headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "Not Found. The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "UnprocessableEntity": { "description": "Unprocessable Entity. The request was well-formed but contains invalid data or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "TooManyRequests": { "description": "Too Many Requests. The request was rate limited. Wait before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "InternalServerError": { "description": "Internal Server Error. An unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "ErrorResponse": { "type": "object", "properties": { "message": { "type": "string" } } }, "ValidationErrorResponse": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } }, "MessageResponse": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } }, "UpdateOrderStatusRequest": { "type": "object", "required": [ "status_code" ], "properties": { "status_code": { "type": "string" }, "comment": { "type": "string" }, "public": { "type": "boolean", "default": false }, "email_customer": { "type": "boolean", "default": true }, "email_additional": { "type": "boolean", "default": true } } }, "BulkStatusUpdateRequest": { "type": "object", "required": [ "order_ids", "status_code" ], "properties": { "order_ids": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "integer" } }, "status_code": { "type": "string" }, "comment": { "type": "string" }, "public": { "type": "boolean", "default": false }, "email_customer": { "type": "boolean", "default": true }, "email_additional": { "type": "boolean", "default": true }, "send_at": { "type": "integer", "description": "Unix timestamp to schedule status emails." }, "due_date": { "type": "string", "format": "date" } } }, "BulkStatusUpdateResponse": { "type": "object", "required": [ "message", "count", "limit" ], "properties": { "message": { "type": "string" }, "count": { "type": "integer" }, "limit": { "type": "integer" } } }, "AddOrderCommentRequest": { "type": "object", "required": [ "comment" ], "properties": { "comment": { "type": "string", "minLength": 3, "maxLength": 1000 }, "public": { "type": "boolean", "default": false } } }, "SetDueDateRequest": { "type": "object", "required": [ "due_date" ], "properties": { "due_date": { "type": [ "string", "null" ], "format": "date" }, "due_date_to": { "type": "string", "format": "date" } } }, "Customer": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "locale": { "type": "string" } } }, "LocaleTranslation": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } } }, "Status": { "type": "object", "properties": { "is_set": { "type": "boolean" }, "code": { "type": "string" }, "name": { "type": "string" }, "public_name": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "public": { "type": "boolean" }, "set_at": { "type": [ "string", "null" ], "format": "date-time" }, "auto_change_at": { "type": [ "string", "null" ], "format": "date-time" }, "translations": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/LocaleTranslation" } } } }, "MailLog": { "type": "object", "properties": { "from": { "type": "string", "format": "email" }, "to": { "type": "string", "format": "email" }, "subject": { "type": "string" }, "delivery_status": { "type": "string" } } }, "HistoryItem": { "type": "object", "properties": { "event": { "type": "string" }, "status": { "anyOf": [ { "$ref": "#/components/schemas/Status" }, { "type": "null" } ] }, "comment": { "type": [ "string", "null" ] }, "comment_is_public": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "mail_log": { "anyOf": [ { "$ref": "#/components/schemas/MailLog" }, { "type": "null" } ] } } }, "ProgressTimelineItem": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "progress": { "type": "string" }, "timestamp": { "type": [ "string", "null" ] } } }, "OrderResponse": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "order_number": { "type": "string" }, "customer": { "$ref": "#/components/schemas/Customer" }, "status": { "$ref": "#/components/schemas/Status" }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/HistoryItem" } }, "public_progress_timeline": { "type": "array", "items": { "$ref": "#/components/schemas/ProgressTimelineItem" } }, "due_date": { "type": [ "string", "null" ], "format": "date-time" }, "due_date_to": { "type": [ "string", "null" ], "format": "date-time" } } }, "OrderListItem": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "order_number": { "type": "string" }, "customer": { "$ref": "#/components/schemas/Customer" }, "status": { "$ref": "#/components/schemas/Status" }, "due_date": { "type": [ "string", "null" ], "format": "date-time" }, "due_date_to": { "type": [ "string", "null" ], "format": "date-time" }, "history_count": { "type": "integer" } } }, "OrderListMeta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "from": { "type": [ "integer", "null" ] }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "to": { "type": [ "integer", "null" ] }, "total": { "type": "integer" } } }, "OrderListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrderListItem" } }, "meta": { "$ref": "#/components/schemas/OrderListMeta" } } }, "StatusDefinition": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "code": { "type": "string" }, "color": { "type": "string" } } }, "ViableStatus": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "color": { "type": "string" } } } } } }