API Documentation
Use this API to retrieve and update design approvals.
Authentication
Get your API key from the app settings page. Include this header in all requests:
Authorization: Bearer YOUR_API_KEY
Rate Limits
- All
/api/v1endpoints are limited to 60 requests per minute per API client. POST /api/v1/orders/bulk-statusis additionally limited to 5 requests per minute.
Endpoint Summary
| Method | Endpoint | Description |
|---|---|---|
| POST | /orders/{order}/status | Update an order status. |
| POST | /orders/bulk-status | Queue a bulk status update for up to 50 orders. |
| POST | /orders/{order}/comment | Add a comment to the order. |
| POST | /orders/{order}/due-date | Set a due date on the order, with optional due date range support. |
| GET | /orders/{order} | Retrieve details of a specific order. |
| GET | /orders | Retrieve a paginated list of orders. |
| GET | /statuses | Get all defined statuses for your account. |
| GET | /orders/lookup | Retrieve an order by order number and customer email. |
| GET | /orders/{order}/viable-statuses | Get viable statuses for an order based on its tags, excluding its current status. |
Common Response Codes
| Status | Description |
|---|---|
| 200 | Success. The request was successful. |
| 201 | Created. The resource was successfully created. |
| 202 | Accepted. The request has been accepted for asynchronous processing. |
| 400 | Bad Request. The request was malformed or missing required headers. |
| 404 | Not Found. The requested resource does not exist. |
| 422 | Unprocessable Entity. The request was well-formed but contains invalid data or failed validation. |
| 429 | Too Many Requests. The request was rate limited. Wait before retrying. |
| 500 | Internal Server Error. An unexpected error occurred. |
POST
/orders/{order}/status
POST
https://app.approvepro.com/api/v1/orders/{order}/status
Update an order status.
| Name | Type | Required | Description |
|---|---|---|---|
| order | integer | Yes | The ID of the order (passed as a URL parameter). |
| status_code | string | Yes | Code identifying the new status to apply to the order. |
| comment | string | No | An optional comment to be associated with the status change. |
| public | boolean | No | Whether the comment should be visible to the customer. Defaults to false. |
| email_customer | boolean | No | Whether the customer should be notified by email about this status change. Defaults to true. |
| email_additional | boolean | No | Whether to notify additional recipients by email (if configured). Defaults to true. |
Request Example
{
"status_code": "st000002",
"comment": "This is a comment",
"public": true,
"email_customer": true,
"email_additional": true
}
Response Example
{
"message": "Order status updated successfully!"
}
POST
/orders/bulk-status
POST
https://app.approvepro.com/api/v1/orders/bulk-status
Queue a bulk status update for up to 50 orders.
| Name | Type | Required | Description |
|---|---|---|---|
| order_ids | array<integer> | Yes | Order IDs to update (1-50). |
| status_code | string | Yes | Code identifying the new status to apply. |
| comment | string | No | Optional comment to associate with each status change. |
| public | boolean | No | Whether the comment should be visible to the customer. Defaults to false. |
| email_customer | boolean | No | Whether customers should receive status emails. Defaults to true. |
| email_additional | boolean | No | Whether additional recipients should receive status emails. Defaults to true. |
| send_at | integer | No | Optional Unix timestamp to schedule status emails. |
| due_date | string | No | Optional due date in YYYY-MM-DD format to apply during the bulk update. |
Request Example
{
"order_ids": [
6110375248088,
6110375248089
],
"status_code": "st000003",
"comment": "Batch moved to shipped",
"public": false,
"email_customer": true,
"email_additional": false
}
Response Example
{
"message": "Bulk status update queued.",
"count": 2,
"limit": 50
}
POST
/orders/{order}/comment
POST
https://app.approvepro.com/api/v1/orders/{order}/comment
Add a comment to the order.
| Name | Type | Required | Description |
|---|---|---|---|
| order | integer | Yes | The ID of the order (passed as a URL parameter). |
| comment | string | Yes | The comment to add to the order. Plain text only (3-1000 chars). |
| public | boolean | No | Whether the comment should be visible to the customer. Defaults to false. |
Request Example
{
"comment": "This is a comment",
"public": true
}
Response Example
{
"message": "Order comment added!"
}
POST
/orders/{order}/due-date
POST
https://app.approvepro.com/api/v1/orders/{order}/due-date
Set a due date on the order, with optional due date range support.
| Name | Type | Required | Description |
|---|---|---|---|
| order | integer | Yes | The ID of the order (passed as a URL parameter). |
| due_date | string | Yes | Due date in YYYY-MM-DD format. Send null to clear. |
| due_date_to | string | No | Optional end date in YYYY-MM-DD format. Must be after due_date and requires due date range to be enabled. |
Request Example
{
"due_date": "2026-02-10",
"due_date_to": "2026-02-12"
}
Response Example
{
"message": "Order due date set!"
}
GET
/orders/{order}
GET
https://app.approvepro.com/api/v1/orders/{order}
Retrieve details of a specific order.
| Name | Type | Required | Description |
|---|---|---|---|
| order | integer | Yes | The ID of the order (passed as a URL parameter). |
Response Example
{
"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",
"public": true,
"set_at": "2025-05-22T19:04:36+00:00",
"auto_change_at": null,
"translations": {
"fr": {
"name": "En cours de fabrication",
"description": "Votre commande est actuellement fabriqu\u00e9e \u00e0 la main dans notre atelier"
}
}
},
"history": [
{
"event": "STATUS_CHANGE",
"status": {
"code": "st000002",
"name": "In Production",
"public_name": "Crafting With Care",
"description": "Order being handcrafted in the workshop",
"public": true,
"translations": {
"fr": {
"name": "En cours de fabrication",
"description": "Votre commande est actuellement fabriqu\u00e9e \u00e0 la main dans notre atelier"
}
}
},
"comment": "We have received parts and commenced production.",
"comment_is_public": true,
"created_at": "2025-05-22T19:04:36+00:00",
"mail_log": {
"from": "no-reply@orderapprovepro.com",
"to": "jon@example.com",
"subject": "Order #1188 in production",
"delivery_status": "Sent"
}
},
{
"event": "COMMENT",
"status": null,
"comment": "Contacted supplier for parts",
"comment_is_public": false,
"created_at": "2025-05-22T19:04:06+00:00",
"mail_log": null
},
{
"event": "STATUS_CHANGE",
"status": {
"code": "st000001",
"name": "Order Received",
"public_name": null,
"description": "Getting ready to start work on your order!",
"public": true,
"translations": {
"fr": {
"name": "Commande re\u00e7ue",
"description": "Nous nous appr\u00eatons \u00e0 commencer la pr\u00e9paration de votre commande!"
}
}
},
"comment": null,
"comment_is_public": false,
"created_at": "2025-05-22T19:03:25+00:00",
"mail_log": null
}
],
"public_progress_timeline": [
{
"name": "Order Received",
"description": "Getting ready to start work on your order!",
"progress": "Complete",
"timestamp": "22 May 20:03"
},
{
"name": "Crafting With Care",
"description": "Order being handcrafted in the workshop",
"progress": "Current",
"timestamp": "22 May 20:04"
},
{
"name": "Shipped",
"description": "Safely packed and dispatched",
"progress": "Incomplete",
"timestamp": null
}
],
"due_date": "2025-05-21T23:00:00+00:00"
}
GET
/orders
GET
https://app.approvepro.com/api/v1/orders
Retrieve a paginated list of orders.
| Name | Type | Required | Description |
|---|---|---|---|
| search | string | No | Filter by partial match against order name, order number, customer name, or customer email. |
| status_code | string | No | Filter by a single status code like st000002. |
| tags | array<string> | No | Filter by tags that must all be present using repeated query params such as tags[]=commercial&tags[]=commercial-lease. |
| tags_any | array<string> | No | Filter by tags where any listed tag may be present using repeated query params such as tags_any[]=commercial&tags_any[]=commercial-flooring. |
| financial_status | array<string> | No | 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. |
| fulfillment_status | array<string> | No | Filter by one or more fulfillment statuses using repeated query params such as fulfillment_status[]=fulfilled. Accepted values: unfulfilled, partial, restocked, fulfilled. |
| exclude_cancelled | boolean | No | When true, excludes orders where cancelled_at is set. |
| due_date_from | string | No | Filter to orders with a due date on or after this YYYY-MM-DD date. |
| due_date_to | string | No | Filter to orders with a due date on or before this YYYY-MM-DD date. |
| per_page | integer | No | Number of orders to return per page. Defaults to 15. Maximum 100. |
Request Example
{
"tags": [
"commercial",
"commercial-lease"
],
"tags_any": [
"commercial-flooring",
"commercial-rental"
],
"financial_status": [
"partially_paid",
"pending",
"unpaid"
],
"fulfillment_status": [
"fulfilled"
],
"exclude_cancelled": true,
"status_code": "st000002",
"due_date_from": "2026-03-14",
"due_date_to": "2026-03-16",
"per_page": 15
}
Response 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
}
}
GET
/statuses
GET
https://app.approvepro.com/api/v1/statuses
Get all defined statuses for your account.
Response 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"
}
]
GET
/orders/lookup
GET
https://app.approvepro.com/api/v1/orders/lookup
Retrieve an order by order number and customer email.
| Name | Type | Required | Description |
|---|---|---|---|
| number | string | Yes | Order number or name (for example: 1188 or #1188). |
| string | Yes | Customer email address. |
Request Example
{
"number": "1188",
"email": "jon@example.com"
}
Response Example
{
"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",
"public": true,
"set_at": "2025-05-22T19:04:36+00:00",
"auto_change_at": null,
"translations": {
"fr": {
"name": "En cours de fabrication",
"description": "Votre commande est actuellement fabriqu\u00e9e \u00e0 la main dans notre atelier"
}
}
},
"history": [
{
"event": "STATUS_CHANGE",
"status": {
"code": "st000002",
"name": "In Production",
"public_name": "Crafting With Care",
"description": "Order being handcrafted in the workshop",
"public": true,
"translations": {
"fr": {
"name": "En cours de fabrication",
"description": "Votre commande est actuellement fabriqu\u00e9e \u00e0 la main dans notre atelier"
}
}
},
"comment": "We have received parts and commenced production.",
"comment_is_public": true,
"created_at": "2025-05-22T19:04:36+00:00",
"mail_log": {
"from": "no-reply@orderapprovepro.com",
"to": "jon@example.com",
"subject": "Order #1188 in production",
"delivery_status": "Sent"
}
},
{
"event": "COMMENT",
"status": null,
"comment": "Contacted supplier for parts",
"comment_is_public": false,
"created_at": "2025-05-22T19:04:06+00:00",
"mail_log": null
},
{
"event": "STATUS_CHANGE",
"status": {
"code": "st000001",
"name": "Order Received",
"public_name": null,
"description": "Getting ready to start work on your order!",
"public": true,
"translations": {
"fr": {
"name": "Commande re\u00e7ue",
"description": "Nous nous appr\u00eatons \u00e0 commencer la pr\u00e9paration de votre commande!"
}
}
},
"comment": null,
"comment_is_public": false,
"created_at": "2025-05-22T19:03:25+00:00",
"mail_log": null
}
],
"public_progress_timeline": [
{
"name": "Order Received",
"description": "Getting ready to start work on your order!",
"progress": "Complete",
"timestamp": "22 May 20:03"
},
{
"name": "Crafting With Care",
"description": "Order being handcrafted in the workshop",
"progress": "Current",
"timestamp": "22 May 20:04"
},
{
"name": "Shipped",
"description": "Safely packed and dispatched",
"progress": "Incomplete",
"timestamp": null
}
],
"due_date": "2025-05-21T23:00:00+00:00"
}
GET
/orders/{order}/viable-statuses
GET
https://app.approvepro.com/api/v1/orders/{order}/viable-statuses
Get viable statuses for an order based on its tags, excluding its current status.
| Name | Type | Required | Description |
|---|---|---|---|
| order | integer | Yes | The ID of the order (passed as a URL parameter). |
Response 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"
}
]