Transformations

Transformations are JavaScript functions that modify order or shipment data at specific trigger points in the processing pipeline. Code is executed in a secure WASM sandbox (QuickJS) with no access to network, file system, or host globals.

List Transformations

GET/api/v1/transformations

List all transformations for the organization.

Requiredtransformations:read

Returns a paginated list of transformations ordered by priority (descending).

Query Parameters

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 20, max: 100)
`triggerPoint`	string	Filter by trigger point
`bridgeId`	string	Filter by associated bridge
`isActive`	string	Filter by active status: `true` or `false`


curl -X GET "https://api.orderly-hub.com/api/v1/transformations?triggerPoint=after_sync" \
  -H "Authorization: Bearer oh_..."

Response


{
  "data": [
    {
      "id": "uuid",
      "organizationId": "uuid",
      "name": "Normalize Shopify Addresses",
      "description": "Standardizes address fields from Shopify orders",
      "triggerPoint": "after_sync",
      "bridgeId": "uuid",
      "code": "function transform(data) { ... }",
      "isActive": true,
      "priority": 10,
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-03-01T12:00:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 3, "totalPages": 1, "hasMore": false }
}

Get Transformation

GET/api/v1/transformations/:id

Get a single transformation by ID.

Requiredtransformations:read

Returns the full details of a specific transformation including its code.

Path Parameters

Parameter	Type	Description
`id`	string	Transformation UUID


curl -X GET "https://api.orderly-hub.com/api/v1/transformations/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer oh_..."

Response


{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "organizationId": "uuid",
    "name": "Normalize Shopify Addresses",
    "description": "Standardizes address fields from Shopify orders",
    "triggerPoint": "after_sync",
    "bridgeId": "uuid",
    "code": "function transform(data) {\n  data.shipping_address.state = data.shipping_address.state.toUpperCase();\n  return data;\n}",
    "isActive": true,
    "priority": 10,
    "createdAt": "2026-01-01T00:00:00Z",
    "updatedAt": "2026-03-01T12:00:00Z"
  }
}

Create Transformation

POST/api/v1/transformations

Create a new transformation.

Requiredtransformations:write

Creates a new transformation. The code field should contain a JavaScript function that accepts and returns the data object. Code syntax is validated before saving.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Display name
`description`	string	No	Description of what the transformation does
`triggerPoint`	string	Yes	When to run: `before_sync`, `after_sync`, `before_operation`, `after_operation`
`bridgeId`	string	No	Limit to a specific bridge
`code`	string	Yes	JavaScript transformation function
`isActive`	boolean	No	Whether the transformation is active (default: `true`)
`priority`	number	No	Execution priority (higher runs first, default: 0)


curl -X POST "https://api.orderly-hub.com/api/v1/transformations" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Add shipping tier tag",
    "triggerPoint": "after_sync",
    "code": "function transform(data) { if (data.total > 100) { data.tags.push(\"free-shipping\"); } return data; }",
    "isActive": true,
    "priority": 5
  }'

Response (201)


{
  "data": {
    "id": "uuid",
    "organizationId": "uuid",
    "name": "Add shipping tier tag",
    "triggerPoint": "after_sync",
    "code": "function transform(data) { ... }",
    "isActive": true,
    "priority": 5,
    "createdAt": "2026-01-15T10:00:00Z",
    "updatedAt": "2026-01-15T10:00:00Z"
  }
}

Update Transformation

PATCH/api/v1/transformations/:id

Update a transformation's code, trigger point, or status.

Requiredtransformations:write

Updates a transformation. If code is provided, it is validated for syntax errors before saving. Changes take effect immediately for subsequent data processing.


curl -X PATCH "https://api.orderly-hub.com/api/v1/transformations/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{"isActive": false}'

Delete Transformation

DELETE/api/v1/transformations/:id

Delete a transformation.

Requiredtransformations:write

Permanently deletes a transformation.


curl -X DELETE "https://api.orderly-hub.com/api/v1/transformations/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer oh_..."

Response


{
  "success": true
}

Test Transformation (Unsaved Code)

POST/api/v1/transformations/test

Test transformation code against sample data without saving.

Requiredtransformations:write

Runs arbitrary JavaScript code against sample input data in a secure WASM sandbox and returns the result. Useful for developing and debugging transformations before saving them.

Request Body

Field	Type	Required	Description
`code`	string	Yes	JavaScript transformation function to test
`sampleData`	object	Yes	Sample data to transform


curl -X POST "https://api.orderly-hub.com/api/v1/transformations/test" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "code": "function transform(data) { data.tags.push(\"tested\"); return data; }",
    "sampleData": { "order_number": "1001", "total": 49.99, "tags": [] }
  }'

Response


{
  "success": true,
  "output": { "order_number": "1001", "total": 49.99, "tags": ["tested"] },
  "duration_ms": 3
}

Test Saved Transformation

POST/api/v1/transformations/:id/test

Test a saved transformation against sample data.

Requiredtransformations:write

Runs an existing transformation’s code against the provided sample data in a secure WASM sandbox. This uses the transformation’s saved code rather than requiring you to supply code in the request.

Path Parameters

Parameter	Type	Description
`id`	string	Transformation UUID

Request Body

Field	Type	Required	Description
`sampleData`	object	Yes	Sample data to transform


curl -X POST "https://api.orderly-hub.com/api/v1/transformations/550e8400-e29b-41d4-a716-446655440000/test" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "sampleData": { "order_number": "1001", "total": 49.99, "tags": [] }
  }'

Response


{
  "success": true,
  "output": { "order_number": "1001", "total": 49.99, "tags": ["free-shipping"] },
  "duration_ms": 2
}

Error Responses

Status	Description
`400`	Invalid JavaScript syntax in code
`404`	Transformation not found