Operations

Operations represent discrete actions performed on orders and shipments, such as creating a shipment, pushing a fulfillment, or updating order status. They provide an auditable, undoable action layer.

List Operations

GET/api/operations

List all operations with filtering and pagination.

Requiredoperations:read

Returns a paginated list of operations for the current organization.

Query Parameters

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 20, max: 100)
`status`	string	Filter by status: `pending`, `executing`, `completed`, `failed`, `cancelled`, `undone`
`type`	string	Filter by operation type
`order_id`	string	Filter by associated order ID
`sort`	string	Sort field (default: `created_at`)
`order`	string	Sort direction: `asc` or `desc`


curl -X GET "https://api.orderly.dev/api/operations?status=completed&limit=50" \
  -H "Authorization: Bearer ord_sk_..."

Response


{
  "data": [
    {
      "id": "uuid",
      "type": "create_shipment",
      "status": "completed",
      "order_id": "uuid",
      "input": { "carrier": "fedex", "service": "GROUND" },
      "output": { "shipment_id": "uuid", "tracking_number": "794644790132" },
      "executed_at": "2026-01-15T10:30:00Z",
      "created_at": "2026-01-15T10:30:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 245, "totalPages": 5, "hasMore": true }
}

Get Operation

GET/api/operations/:id

Retrieve a single operation by ID.

Requiredoperations:read

Returns the full operation including input parameters, output result, execution logs, and undo information.


curl -X GET "https://api.orderly.dev/api/operations/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer ord_sk_..."

Create Operation

POST/api/operations

Create a new operation for later execution.

Requiredoperations:write

Creates an operation in pending status. The operation is not executed until you call the execute endpoint.

Request Body

Field	Type	Required	Description
`type`	string	Yes	Operation type (e.g., `create_shipment`, `push_fulfillment`)
`order_id`	string	No	Associated order ID
`input`	object	Yes	Operation-specific input parameters


curl -X POST "https://api.orderly.dev/api/operations" \
  -H "Authorization: Bearer ord_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "create_shipment",
    "order_id": "550e8400-e29b-41d4-a716-446655440000",
    "input": {
      "carrier_account_id": "660e8400-e29b-41d4-a716-446655440000",
      "service": "GROUND_HOME_DELIVERY"
    }
  }'

Execute Operation

POST/api/operations/:id/execute

Execute a pending operation.

Requiredoperations:execute

Executes a pending operation. The operation transitions to executing and then to completed or failed. Execution is asynchronous for long-running tasks.


curl -X POST "https://api.orderly.dev/api/operations/550e8400-e29b-41d4-a716-446655440000/execute" \
  -H "Authorization: Bearer ord_sk_..."

Response


{
  "data": {
    "id": "uuid",
    "status": "executing",
    "type": "create_shipment"
  }
}

Cancel Operation

POST/api/operations/:id/cancel

Cancel a pending operation before execution.

Requiredoperations:execute

Cancels an operation that has not yet been executed. Only operations in pending status can be cancelled.


curl -X POST "https://api.orderly.dev/api/operations/550e8400-e29b-41d4-a716-446655440000/cancel" \
  -H "Authorization: Bearer ord_sk_..."

Undo Operation

POST/api/operations/:id/undo

Undo a completed operation, reversing its effects.

Requiredoperations:execute

Reverses a completed operation. Not all operation types support undo. If undo is not available, the request returns a 422 error.


curl -X POST "https://api.orderly.dev/api/operations/550e8400-e29b-41d4-a716-446655440000/undo" \
  -H "Authorization: Bearer ord_sk_..."

Response


{
  "data": {
    "id": "uuid",
    "status": "undone",
    "undo_at": "2026-01-15T11:00:00Z"
  }
}