Error

A valid request URL is required to generate request examples

{
  "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"
          }
        ]
      },
      "vendorSku": "APL-MK183LL/A",
      "vendorCode": "APPLE",
      "serialNumber": "C02XL0AAJG5L",
      "justification": "Need higher RAM for local development workflows",
      "purchaseOrderNumber": "PO-US-LAPTOPS-001"
    }
  ],
  "statusHistory": [
    {
      "status": "APPROVED",
      "timestamp": "2023-01-01T12:00:00Z"
    }
  ],
  "personId": "d7d0d906-425f-402f-bde1-39031c67c40b",
  "officeId": "d7d0d906-425f-402f-bde1-39031c67c40b",
  "shippingAddress": {
    "countryCode": "US",
    "addressLine1": 123,
    "addressLine2": "Suite 103",
    "administrativeArea": "NY",
    "locality": "New York City",
    "postalCode": 10123
  },
  "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,
      "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"
}

{
  "errors": [
    {
      "detail": "Invalid request",
      "source": "request"
    }
  ]
}

{
  "errors": [
    {
      "detail": "Invalid request",
      "source": "request"
    }
  ]
}

{
  "errors": [
    {
      "detail": "Invalid request",
      "source": "request"
    }
  ]
}

{
  "errors": [
    {
      "detail": "Invalid request",
      "source": "request"
    }
  ]
}

Orders

Modify an existing order

Partially update an existing order. Allowed before fulfilment. Modifiable fields: products, shippingAddress, deliverToPersonId, deliverToOfficeId, status (CANCELLED only). 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.

PATCH

api

orders

{orderId}

Error

A valid request URL is required to generate request examples

{
  "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"
          }
        ]
      },
      "vendorSku": "APL-MK183LL/A",
      "vendorCode": "APPLE",
      "serialNumber": "C02XL0AAJG5L",
      "justification": "Need higher RAM for local development workflows",
      "purchaseOrderNumber": "PO-US-LAPTOPS-001"
    }
  ],
  "statusHistory": [
    {
      "status": "APPROVED",
      "timestamp": "2023-01-01T12:00:00Z"
    }
  ],
  "personId": "d7d0d906-425f-402f-bde1-39031c67c40b",
  "officeId": "d7d0d906-425f-402f-bde1-39031c67c40b",
  "shippingAddress": {
    "countryCode": "US",
    "addressLine1": 123,
    "addressLine2": "Suite 103",
    "administrativeArea": "NY",
    "locality": "New York City",
    "postalCode": 10123
  },
  "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,
      "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"
}

{
  "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

Authorization

string

header

required

Prefix the value with "ApiKey" to indicate the custom authorization type

Path Parameters

orderId

string<uuid>

required

Body

application/json

Request body for modifying an existing order. All fields are optional. Omit a field to leave it unchanged. 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.

products

object

required

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

shippingAddress

object

required

New shipping address (full replace).

Show child attributes

deliverToPersonId

object

required

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.

Show child attributes

deliverToOfficeId

object

required

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.

Show child attributes

status

object

required

New status. Only CANCELLED is accepted. Omit the field to leave status unchanged; explicit null is invalid.

Show child attributes

Response

Order updated

string<uuid>

required

Order's ID

Example:

"123E4567-E89B-12D3-A456-426614174000"

status

enum<string>

required

Order's status

Available options:

AWAITING_APPROVAL,

ORDERED,

PROCESSING,

ORDERED_NOT_SHIPPED,

SHIPPED,

COMPLETED,

PARTIALLY_SHIPPED,

DECLINED,

AWAITING_DELIVERY_SCHEDULING,

DELIVERY_SCHEDULED,

DELIVERED,

NONE,

APPROVED,

AWAITING_FULFILLMENT,

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

Example:

"COMPLETED"

orderItems

object[]

required

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

statusHistory

object[]

required

Chronological history of status changes

Show child attributes

orderType

enum<string>

required

Type of order based on lifecycle context

Available options:

ONE_OFF,

ONBOARDING,

REPLACEMENT

personId

string<uuid>

The ID of the Person

Example:

"d7d0d906-425f-402f-bde1-39031c67c40b"

officeId

string<uuid>

The ID of the Office

Example:

"d7d0d906-425f-402f-bde1-39031c67c40b"

shippingAddress

object

Order item's shipping address

Show child attributes

submittedBy

string

Name of the person who submitted the order

Example:

"John S. (Firstbase)"

approvedBy

string

Name of the person who approved the order

Example:

"Jane Smith"

approvedAt

string<date>

Date when the order was approved

Example:

"2026-02-26"

deliverToOffice

object

Office to which the order is delivered, when different from the assigned office

Show child attributes

deliverToPerson

object

Person to whom the order is delivered, when different from the assigned person

Show child attributes

createdAt

string<date-time>

UTC ISO-8601 timestamp when the order was created.

Example:

"2026-02-26T14:15:22.123Z"

updatedAt

string<date-time>

UTC ISO-8601 timestamp when the order was last updated.

Example:

"2026-03-15T09:00:00.000Z"

expectedBy

string<date>

Date by which the order is expected to be delivered (calendar date, no time component).

Example:

"2026-03-10"

packageSlug

string

Slug of the product package this order was created from, if any.

Example:

"engineering-onboarding"

deliveryLocation

enum<string>

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.

Available options:

PERSON,

OFFICE

Get a single order by ID Send new joiner reminder

⌘I

People

Shipment Notices V1

Returns

Replacements

People — Lifecycle

Packages

Orders

New Joiners

ITAD

Inventory

Inventory Orders

Inventory Levels

Assets

Return Orders

Offices

Warehouses V1

Shipment

Regions V1

Categories

Catalog

Brands

Modify an existing order

Authorizations

Path Parameters

Body

Response