curl -sS -X PATCH 'https://apipub.firstbasehq.com/api/v1/orders/{orderId}' \
-H 'Authorization: ApiKey YOUR_API_KEY' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"products": [],
"shippingAddress": {
"addressLine1": "123 Main Street",
"addressLine2": "Apartment B",
"administrativeArea": "California",
"countryCode": "US",
"dependentLocality": "Mission Bay",
"locality": "San Francisco",
"postalCode": "94158",
"sortingCode": "94158-1234",
"phoneNumber": "+1-415-555-1234"
}
}'import requests
url = "https://apipub.firstbasehq.com/api/v1/orders/{orderId}"
payload = {
"products": [],
"shippingAddress": {
"addressLine1": "123 Main Street",
"addressLine2": "Apartment B",
"administrativeArea": "California",
"countryCode": "US",
"dependentLocality": "Mission Bay",
"locality": "San Francisco",
"postalCode": "94158",
"sortingCode": "94158-1234",
"phoneNumber": "+1-415-555-1234"
}
}
headers = {
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
products: [],
shippingAddress: {
addressLine1: '123 Main Street',
addressLine2: 'Apartment B',
administrativeArea: 'California',
countryCode: 'US',
dependentLocality: 'Mission Bay',
locality: 'San Francisco',
postalCode: '94158',
sortingCode: '94158-1234',
phoneNumber: '+1-415-555-1234'
}
})
};
fetch('https://apipub.firstbasehq.com/api/v1/orders/{orderId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "123E4567-E89B-12D3-A456-426614174000",
"status": "COMPLETED",
"orderItems": [
{
"id": "123E4567-E89B-12D3-A456-426614174000",
"skuId": "123E4567-E89B-12D3-A456-426614174000",
"title": "iPad Air - Silver, 64GB, WiFi",
"categoryCode": "COMPUTER",
"status": "PROCESSING",
"statusHistory": [
{
"status": "APPROVED",
"timestamp": "2023-01-01T12:00:00Z"
}
],
"shipment": {
"trackingUrl": "<string>",
"trackingCode": "1Z00000000",
"carrier": "UPS",
"status": "DELIVERED",
"trackingHistory": [
{
"status": "IN_TRANSIT",
"timestamp": "2023-11-07T05:31:56Z"
}
]
},
"fulfillmentMethod": "WAREHOUSE",
"vendorSku": "APL-MK183LL/A",
"vendorCode": "APPLE",
"serialNumber": "C02XL0AAJG5L",
"justification": "Need higher RAM for local development workflows",
"purchaseOrderNumber": "PO-US-LAPTOPS-001",
"type": "PHYSICAL",
"intendedFulfillmentMethod": "WAREHOUSE",
"orderedPricing": null,
"discountedPrice": 899,
"orderedWarrantyItem": null,
"firstbaseManaged": true,
"productGroupId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"productGroupComponentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"productGroupInstanceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"productGroupFriendlyId": "GRP-260914-TEST0001",
"productGroupName": "Laptop Bundle"
}
],
"statusHistory": [
{
"status": "APPROVED",
"timestamp": "2023-01-01T12:00:00Z"
}
],
"orderType": "ONE_OFF",
"personId": "d7d0d906-425f-402f-bde1-39031c67c40b",
"officeId": "d7d0d906-425f-402f-bde1-39031c67c40b",
"shippingAddress": null,
"submittedBy": "John S. (Firstbase)",
"approvedBy": "Jane Smith",
"approvedAt": "2026-02-26",
"deliverToOffice": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "NYC HQ",
"address": {
"countryCode": "US",
"addressLine1": "123 Sesame Street",
"addressLine2": "Suite 103",
"administrativeArea": "NY",
"locality": "New York City",
"postalCode": "10123"
}
},
"deliverToPerson": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"firstName": "Jane",
"lastName": "Smith",
"email": "jane.smith@example.com"
},
"createdAt": "2026-02-26T14:15:22.123Z",
"updatedAt": "2026-03-15T09:00:00.000Z",
"expectedBy": "2026-03-10",
"packageSlug": "engineering-onboarding",
"deliveryLocation": "PERSON"
}{
"errors": [
{
"detail": "Invalid request",
"source": "request"
}
]
}{
"errors": [
{
"detail": "Invalid request",
"source": "request"
}
]
}{
"errors": [
{
"detail": "Invalid request",
"source": "request"
}
]
}{
"errors": [
{
"detail": "Invalid request",
"source": "request"
}
]
}Modify or cancel an existing order
Partially update an existing order. Allowed before fulfilment. All request body fields are optional — omit any field to leave it unchanged.
Cancel an order: send only {"status": "CANCELLED"}. Works for orders in ORDERED, AWAITING_APPROVAL, or DECLINED status (not SHIPPED). This is the correct way to cancel an equipment order; there is no DELETE endpoint for /api/v1/orders.
Other modifiable fields: products, shippingAddress, deliverToPersonId, deliverToOfficeId. Address validation workflow is unchanged by this endpoint (same as logistics modify-order: addressValidationNeeded is not set via PATCH). Each products[] line uses the same preferredCondition rules as create order (skus[]): NEW, USED, or omitted (defaults to NEW-only preference server-side). When products is sent, omitted existing line ids are left unchanged; cancel a line with cancelled: true and its id. New lines omit id. The response orderItems list includes cancelled rows—filter by status for active lines only.
curl -sS -X PATCH 'https://apipub.firstbasehq.com/api/v1/orders/{orderId}' \
-H 'Authorization: ApiKey YOUR_API_KEY' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"products": [],
"shippingAddress": {
"addressLine1": "123 Main Street",
"addressLine2": "Apartment B",
"administrativeArea": "California",
"countryCode": "US",
"dependentLocality": "Mission Bay",
"locality": "San Francisco",
"postalCode": "94158",
"sortingCode": "94158-1234",
"phoneNumber": "+1-415-555-1234"
}
}'import requests
url = "https://apipub.firstbasehq.com/api/v1/orders/{orderId}"
payload = {
"products": [],
"shippingAddress": {
"addressLine1": "123 Main Street",
"addressLine2": "Apartment B",
"administrativeArea": "California",
"countryCode": "US",
"dependentLocality": "Mission Bay",
"locality": "San Francisco",
"postalCode": "94158",
"sortingCode": "94158-1234",
"phoneNumber": "+1-415-555-1234"
}
}
headers = {
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
products: [],
shippingAddress: {
addressLine1: '123 Main Street',
addressLine2: 'Apartment B',
administrativeArea: 'California',
countryCode: 'US',
dependentLocality: 'Mission Bay',
locality: 'San Francisco',
postalCode: '94158',
sortingCode: '94158-1234',
phoneNumber: '+1-415-555-1234'
}
})
};
fetch('https://apipub.firstbasehq.com/api/v1/orders/{orderId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "123E4567-E89B-12D3-A456-426614174000",
"status": "COMPLETED",
"orderItems": [
{
"id": "123E4567-E89B-12D3-A456-426614174000",
"skuId": "123E4567-E89B-12D3-A456-426614174000",
"title": "iPad Air - Silver, 64GB, WiFi",
"categoryCode": "COMPUTER",
"status": "PROCESSING",
"statusHistory": [
{
"status": "APPROVED",
"timestamp": "2023-01-01T12:00:00Z"
}
],
"shipment": {
"trackingUrl": "<string>",
"trackingCode": "1Z00000000",
"carrier": "UPS",
"status": "DELIVERED",
"trackingHistory": [
{
"status": "IN_TRANSIT",
"timestamp": "2023-11-07T05:31:56Z"
}
]
},
"fulfillmentMethod": "WAREHOUSE",
"vendorSku": "APL-MK183LL/A",
"vendorCode": "APPLE",
"serialNumber": "C02XL0AAJG5L",
"justification": "Need higher RAM for local development workflows",
"purchaseOrderNumber": "PO-US-LAPTOPS-001",
"type": "PHYSICAL",
"intendedFulfillmentMethod": "WAREHOUSE",
"orderedPricing": null,
"discountedPrice": 899,
"orderedWarrantyItem": null,
"firstbaseManaged": true,
"productGroupId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"productGroupComponentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"productGroupInstanceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"productGroupFriendlyId": "GRP-260914-TEST0001",
"productGroupName": "Laptop Bundle"
}
],
"statusHistory": [
{
"status": "APPROVED",
"timestamp": "2023-01-01T12:00:00Z"
}
],
"orderType": "ONE_OFF",
"personId": "d7d0d906-425f-402f-bde1-39031c67c40b",
"officeId": "d7d0d906-425f-402f-bde1-39031c67c40b",
"shippingAddress": null,
"submittedBy": "John S. (Firstbase)",
"approvedBy": "Jane Smith",
"approvedAt": "2026-02-26",
"deliverToOffice": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "NYC HQ",
"address": {
"countryCode": "US",
"addressLine1": "123 Sesame Street",
"addressLine2": "Suite 103",
"administrativeArea": "NY",
"locality": "New York City",
"postalCode": "10123"
}
},
"deliverToPerson": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"firstName": "Jane",
"lastName": "Smith",
"email": "jane.smith@example.com"
},
"createdAt": "2026-02-26T14:15:22.123Z",
"updatedAt": "2026-03-15T09:00:00.000Z",
"expectedBy": "2026-03-10",
"packageSlug": "engineering-onboarding",
"deliveryLocation": "PERSON"
}{
"errors": [
{
"detail": "Invalid request",
"source": "request"
}
]
}{
"errors": [
{
"detail": "Invalid request",
"source": "request"
}
]
}{
"errors": [
{
"detail": "Invalid request",
"source": "request"
}
]
}{
"errors": [
{
"detail": "Invalid request",
"source": "request"
}
]
}Authorizations
Prefix the value with "ApiKey" to indicate the custom authorization type
Path Parameters
Body
Request body for modifying or cancelling an existing order. All fields are optional — omit any field to leave it unchanged. To cancel the entire order, send only {"status": "CANCELLED"} (valid when order items are ORDERED, AWAITING_APPROVAL, or DECLINED). Explicit JSON null is honored only where noted on each field; other explicit nulls are ignored or rejected. Deliver-to person/office IDs do not support clear via explicit null—omit those keys to leave deliver-to unchanged.
When present, declares how order lines should look after this update (must contain at least one item). Lines that include id are kept for in-place edits (expedited / preferred condition) unless cancelled is true. Lines without id are treated as additions. Existing lines whose id is omitted from this array are left unchanged. To cancel a line, include its id with cancelled: true. Cancelled rows remain in storage and in GET/PATCH responses.
Show child attributes
Show child attributes
New shipping address (full replace).
Show child attributes
Show child attributes
Deliver-to person ID. Mutually exclusive with deliverToOfficeId when both are non-null. Omit to leave unchanged; explicit null is accepted but does not clear an existing deliver-to target.
Deliver-to office ID. Mutually exclusive with deliverToPersonId when both are non-null. Omit to leave unchanged; explicit null is accepted but does not clear an existing deliver-to target.
Set to CANCELLED to cancel the entire order. Only CANCELLED is accepted. Omit the field to leave status unchanged; explicit null is invalid.
CANCELLED Response
Order updated
Order's ID
"123E4567-E89B-12D3-A456-426614174000"
Order's status
AWAITING_APPROVAL, ORDERED, PROCESSING, ORDERED_NOT_SHIPPED, SHIPPED, COMPLETED, PARTIALLY_SHIPPED, DECLINED, AWAITING_DELIVERY_SCHEDULING, DELIVERY_SCHEDULED, DELIVERED, ACTIVATED, NONE, APPROVED, AWAITING_FULFILLMENT, ACTION_REQUIRED, PENDING, RETURN_KIT_SENT, RETURN_KIT_DELIVERED, RETURN_KIT_SENT_BACK, RECEIVED_IN_WAREHOUSE, RETURNED, NOT_RETURNED, OUT_FOR_DELIVERY, DELIVERY_EXCEPTION, SUBMITTED, CANCELLED, CONFIRMED, NOT_COMPLETED, PARTIALLY_COMPLETED "COMPLETED"
All order item rows on the order, including lines in terminal states such as CANCELLED. Replacing products via PATCH cancels superseded rows rather than deleting them, so consumers should filter by each item's status when they care only about active lines.
Show child attributes
Show child attributes
Chronological history of status changes
Show child attributes
Show child attributes
Type of order based on lifecycle context
ONE_OFF, ONBOARDING, REPLACEMENT The ID of the Person
"d7d0d906-425f-402f-bde1-39031c67c40b"
The ID of the Office
"d7d0d906-425f-402f-bde1-39031c67c40b"
Order item's shipping address
Name of the person who submitted the order
"John S. (Firstbase)"
Name of the person who approved the order
"Jane Smith"
Date when the order was approved
"2026-02-26"
Office to which the order is delivered, when different from the assigned office
Show child attributes
Show child attributes
Person to whom the order is delivered, when different from the assigned person
Show child attributes
Show child attributes
UTC ISO-8601 timestamp when the order was created.
"2026-02-26T14:15:22.123Z"
UTC ISO-8601 timestamp when the order was last updated.
"2026-03-15T09:00:00.000Z"
Date by which the order is expected to be delivered (calendar date, no time component).
"2026-03-10"
Slug of the product package this order was created from, if any.
"engineering-onboarding"
The order's delivery location type (mirrors the FE Orders 'Delivery location' column, where PERSON is shown as 'Employee'). Derived from deliverToOffice / deliverToPerson: OFFICE when deliverToOffice is set, otherwise PERSON when deliverToPerson is set.
PERSON, OFFICE