Tray.ai (Tray.io) Integration Capabilities for Complex ERP Orchestration

TL;DR

• Bottom line: Tray.ai is a developer-oriented iPaaS with three build experiences (Tray Code, Tray Build, Tray Chat) and 700+ connectors, best suited for complex multi-system ERP orchestration where workflow logic goes beyond simple point-to-point mapping.
• Key limit: 6 MB data payload limit between workflow steps; 30 req/s API rate limit (1,800/min) with burst to 50 req/s; 1,000 max concurrent Call Connector requests.
• Watch out for: No pre-built SAP ERP connector — you must use HTTP Client or build a custom connector via the CDK; task credit consumption scales with step count, not workflow count.
• Best for: Complex orchestration across 3+ systems with branching logic, conditional routing, data transformation, and error handling that exceeds what recipe-based tools can express.
• Authentication: OAuth 2.0 (Authorization Code + Client Credentials), API Key, Basic Auth, Custom Service Auth — centralized credential store with auto-refresh.

System Profile

Tray.ai (rebranded from Tray.io in 2024) is a cloud-native iPaaS built on the Universal Automation Cloud (UAC) architecture. It targets technical teams that need full control over integration logic while also enabling business technologists through low-code and AI-assisted build experiences. Unlike MuleSoft's API-led connectivity model or Workato's recipe-centric approach, Tray takes a workflow-first approach with deep support for branching, looping, conditional logic, and parallel execution.

The platform operates across three tiers: Pro (entry-level), Team (mid-market), and Enterprise (full governance). All tiers share the same runtime engine but differ in task credits, workspace count, log retention, and governance controls. Tray does NOT offer an on-premise deployment option — it is cloud-only, hosted on AWS.

API Surfaces & Capabilities

Tray.ai exposes multiple API surfaces for building integrations, managing workflows programmatically, and embedding integration capabilities into external products.

Rate Limits & Quotas

Per-Request Limits

Rolling / Daily Limits

Timeout Limits

Authentication

Tray.ai provides a centralized authentication store that manages credentials for all connected services. Workflows reference stored auth objects rather than embedding credentials directly.

Authentication Gotchas

• OAuth tokens are stored per-workspace — moving a workflow between workspaces requires re-authentication of all connected services. [src1]
• Tray automatically refreshes tokens on 401/403 responses with 3 retries (1st immediate, 2nd-3rd with ~20s delay) — if all fail, the workflow step errors. [src1]
• For embedded (white-label) deployments, OAuth redirect URLs use the format <org_name>.integration-authentication.com/oauth2/token — you must register this URL with each OAuth provider. [src3]
• Connector-level auth is separate from Tray platform API auth — the platform APIs use user tokens obtained via GraphQL mutations. [src2]

Constraints

• 6 MB step payload limit: Data passed between workflow steps cannot exceed 6 MB. For large datasets, use CSV connectors (up to 1 GB), Data Storage, or file-based intermediaries. This is the #1 constraint developers hit on data-intensive ERP integrations.
• No native SAP connector: SAP ERP, S/4HANA, and SAP BTP do not have pre-built connectors. You must use the HTTP Client connector with custom authentication or build a connector via the CDK.
• Task credits are per-step, not per-workflow: Each connector operation, data transformation, boolean, and loop iteration consumes a task credit. A 20-step workflow processing 1,000 records via a loop consumes 20,000+ credits per execution.
• Cloud-only deployment: No on-premise or hybrid option. All data transits through Tray's AWS infrastructure.
• Webhook rate limiting: Webhook triggers using "Validate and respond" or "Await workflow and respond" mode are rate-limited at high volume. Only "Auto respond with status 200" mode is unthrottled.
• Log retention is plan-dependent: Pro gets 7 days, Enterprise up to 30 days. No long-term log archival built in.
• Generated file TTL: Files created during workflow execution are automatically deleted after 6 hours. Download URLs also expire at 6 hours.

Integration Pattern Decision Tree

START -- User needs to integrate ERP systems using Tray.ai
|-- What's the integration pattern?
|   |-- Real-time (individual records, <1s latency)
|   |   |-- Target system has native Tray connector?
|   |   |   |-- YES --> Use native connector in workflow with webhook trigger
|   |   |   |-- NO --> Use HTTP Client connector with custom auth
|   |   |-- Data payload < 6 MB per step?
|   |   |   |-- YES --> Direct step-to-step data passing
|   |   |   |-- NO --> Use Data Storage or file intermediary
|   |   |-- Need synchronous response?
|   |       |-- YES --> Webhook with "Await workflow and respond" (5-min timeout)
|   |       |-- NO --> Webhook with "Auto respond 200" + async processing
|   |-- Batch/Bulk (scheduled, high volume)
|   |   |-- Data volume < 1,000 records?
|   |   |   |-- YES --> Loop connector with native connector steps
|   |   |   |-- NO --> CSV connector (up to 1 GB) + callable workflow for parallel
|   |   |-- Need to stay within task credit budget?
|   |       |-- YES --> Minimize loop iterations; use bulk API calls
|   |       |-- NO --> Standard loop + individual record operations
|   |-- Event-driven (webhook, CDC)
|   |   |-- Source system can push webhooks?
|   |   |   |-- YES --> Webhook trigger on Tray workflow
|   |   |   |-- NO --> Scheduled polling workflow
|   |   |-- Need guaranteed delivery?
|   |       |-- YES --> Add Data Storage queue + dead letter workflow
|   |       |-- NO --> Direct webhook trigger processing
|   |-- File-based (CSV/XML import/export)
|       |-- File size < 1 GB?
|       |   |-- YES --> CSV/File connector with 60-min timeout
|       |   |-- NO --> Split files externally before ingestion
|       |-- Need transformation?
|           |-- YES --> CSV Editor step (8 KB/row, 4,096 col max)
|           |-- NO --> Direct file pass-through
|-- Which direction?
|   |-- Inbound --> Check target system rate limits + Tray 30 req/s limit
|   |-- Outbound --> Check source system pagination + 6 MB step limit
|   |-- Bidirectional --> Design conflict resolution in workflow logic FIRST
|-- Error tolerance?
    |-- Zero-loss required --> Data Storage queue + callable retry + error workflow
    |-- Best-effort --> Standard retry policy (3 retries, 40s interval)

Quick Reference

Platform Capability Comparison

Step-by-Step Integration Guide

1. Create a Tray.ai Workflow with Webhook Trigger

Set up the workflow entry point that will receive events from an ERP system. [src3]

// In Tray Build: Create new workflow
// 1. Click "Create Workflow"
// 2. Select "Webhook" trigger
// 3. Choose "Auto respond with status 200" for high-volume
//    or "Await workflow and respond" for sync responses
// 4. Copy the generated webhook URL

const webhookUrl = "https://YOUR_TRAY_WEBHOOK_URL";

const response = await fetch(webhookUrl, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    event: "order_created",
    order_id: "ORD-12345",
    customer: { name: "Acme Corp", erp_id: "CUST-001" },
    line_items: [
      { sku: "WIDGET-A", qty: 100, unit_price: 25.00 }
    ]
  })
});

Verify: Check Tray workflow logs for the incoming event --> expected: trigger received with payload visible in step output.

2. Add Connector Steps for ERP Read/Write Operations

Configure the target ERP connector (e.g., NetSuite, Salesforce) to process the incoming data. [src5]

// In Tray Build: Add connector step after trigger
// 1. Search connector library for target system (e.g., "NetSuite")
// 2. Select operation (e.g., "Create Record" or "Search Records")
// 3. Map input fields from trigger payload using JSONPath:
//    $.steps.trigger.body.customer.erp_id --> NetSuite Customer Internal ID
//    $.steps.trigger.body.line_items --> Loop connector input

// For systems without native connector (e.g., SAP):
// Use HTTP Client connector:
// - Method: POST
// - URL: https://your-sap-instance.com/sap/opu/odata/sap/API_SALES_ORDER_SRV/A_SalesOrder
// - Headers: { "Authorization": "Bearer {auth.token}" }
// - Body: Map from trigger payload with Data Mapper

Verify: Step output shows the created/updated record ID from the target ERP system.

3. Implement Error Handling with Boolean and Branch Steps

Add conditional logic to handle partial failures and route errors. [src1]

// In Tray Build: Add error handling
// 1. After each connector step, add a "Boolean" step
//    Condition: $.steps.previous.error IS NOT NULL
// 2. TRUE branch: Route to error handler
//    - Log error to Data Storage (for dead letter queue)
//    - Send alert via Slack/email connector
// 3. FALSE branch: Continue to next step

// For retry logic:
// - Use "Callable Workflow" trigger for the retry workflow
// - Store failed records in Data Storage with key = record_id
// - Scheduled workflow polls Data Storage every 15 min for retries
// - Max 3 retries before routing to manual review queue

Verify: Trigger a test failure (invalid record ID) --> expected: error branch executes, record stored in Data Storage.

4. Handle High-Volume Data with Loop and Chunking

Process bulk records while staying within Tray platform limits. [src1]

// In Tray Build: Bulk processing pattern
// 1. Use "List Helpers - Chunk" step to split large arrays
//    Input: $.steps.trigger.body.records (e.g., 5,000 items)
//    Chunk size: 200 (to stay well under 6 MB step limit)
//
// 2. Use "Loop" connector over chunks
//    For each chunk:
//      a. Call target ERP connector with batch operation
//      b. Collect results
//      c. Add "Delay" step (1-2 seconds) to avoid target system rate limits
//
// 3. Alternatively: Use "Callable Workflow" for parallel processing
//    Main workflow: chunks data, calls child workflow per chunk
//    Child workflow: processes single chunk, returns results

// IMPORTANT: Each loop iteration = 1 task credit per step inside the loop
// 5,000 records / 200 per chunk = 25 chunks
// 5 steps per chunk = 125 task credits

Verify: Monitor workflow execution logs --> expected: all chunks processed, total task credits match estimate.

Code Examples

Python: Trigger a Tray Workflow via Webhook

# Input:  Webhook URL from Tray workflow, ERP event payload
# Output: HTTP 200 (async) or workflow result (sync)

import requests
import json

TRAY_WEBHOOK_URL = "https://YOUR_TRAY_WEBHOOK_URL"

def trigger_tray_workflow(event_type: str, payload: dict) -> dict:
    """Trigger a Tray.ai workflow via webhook with ERP event data."""
    headers = {"Content-Type": "application/json"}
    response = requests.post(
        TRAY_WEBHOOK_URL,
        headers=headers,
        json={"event": event_type, "data": payload},
        timeout=30
    )
    if response.status_code == 429:
        import time
        time.sleep(2)
        return trigger_tray_workflow(event_type, payload)
    response.raise_for_status()
    return response.json() if response.text else {"status": "accepted"}

result = trigger_tray_workflow("order_created", {
    "order_id": "ORD-12345",
    "customer_id": "CUST-001",
    "total": 2500.00,
    "currency": "USD"
})

JavaScript/Node.js: Use Tray Embedded API (GraphQL)

// Input:  Tray user token, workflow ID
// Output: Workflow list and management

import { GraphQLClient, gql } from "graphql-request"; // v6.x

const client = new GraphQLClient("https://tray.io/graphql", {
  headers: { Authorization: `Bearer ${process.env.TRAY_USER_TOKEN}` },
});

const LIST_WORKFLOWS = gql`
  query {
    viewer {
      workflows {
        edges {
          node { id name enabled triggerUrl }
        }
      }
    }
  }
`;

async function listWorkflows() {
  const data = await client.request(LIST_WORKFLOWS);
  return data.viewer.workflows.edges.map((e) => e.node);
}

const workflows = await listWorkflows();
console.log(`Found ${workflows.length} workflows`);

cURL: Test Webhook Trigger

# Input:  Tray webhook URL
# Output: HTTP 200 + workflow trigger confirmation

# Trigger a workflow via webhook
curl -X POST "https://YOUR_TRAY_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{"event": "invoice_created", "invoice_id": "INV-2026-001", "amount": 5000.00}'

# List workflows via GraphQL API
curl -X POST "https://tray.io/graphql" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TRAY_USER_TOKEN" \
  -d '{"query": "{ viewer { workflows { edges { node { id name enabled } } } } }"}'

Data Mapping

When connecting ERP systems through Tray.ai, field mapping happens in the Data Mapper step, which supports JSONPath expressions, JavaScript transforms, and lookup tables.

Field Mapping Reference

Data Type Gotchas

• Tray.ai Data Mapper outputs JSON strings by default -- numeric ERP fields must be explicitly cast using JavaScript steps or the "Type Converter" helper. [src1]
• Date/time fields lose timezone information when passing through Tray workflow steps unless explicitly preserved -- use ISO 8601 with timezone offset. [src1]
• NetSuite multi-select custom fields serialize as pipe-delimited in SuiteTalk but Tray's NetSuite connector returns them as arrays -- branching on type is needed. [src5]
• Null vs empty string handling differs between connectors -- Salesforce returns null, NetSuite returns "" for empty fields. Normalize before comparison. [src5]

Error Handling & Failure Points

Common Error Codes

Failure Points in Production

• Task credit exhaustion mid-workflow: Workflows stop executing when credits are depleted -- no graceful mid-run handling. Fix: Set credit usage alerts at 80% threshold; design workflows to minimize step count per record. [src7]
• 6 MB step payload overflow: Works in dev with 100 records, fails in production with 10,000. Fix: Use CSV connector for datasets >1,000 records; chunk payloads with List Helpers. [src1]
• OAuth token expiration during long-running bulk workflows: A 60-minute CSV job can outlast the access token. Fix: Pre-refresh tokens at workflow start; use Client Credentials for batch workflows. [src1]
• Webhook replay on platform restarts: During rare maintenance, webhooks can be replayed, creating duplicate records. Fix: Implement idempotency keys; use Data Storage to track processed event IDs. [src1]
• Connector version updates break field mappings: Auto-pushed connector updates can change field names or response structures. Fix: Implement field-existence checks with Boolean steps; test after connector update notifications. [src5]

Anti-Patterns

Wrong: Processing large datasets record-by-record in a single loop

// BAD -- each record = N steps = N task credits
// 10K records * 5 steps = 50K credits; likely hits 6 MB payload limit
// Loop over 10,000 items with 4 connector steps per iteration
// Total: 40,000 task credits, likely hits payload limit

Correct: Chunk data and use callable workflows for parallel batch processing

// GOOD -- chunk into 200-record batches, process in parallel callable workflows
// Main: List Helpers Chunk (200) --> 50 chunks --> Loop --> Call child workflow
// Child: Bulk Create/Update (single API call) --> Return results
// Total: ~250 credits (160x more efficient)

Wrong: Synchronous webhook mode for high-volume event streams

// BAD -- "Await workflow and respond" rate-limits at high volume
// Hundreds of events/second triggers 429 errors, dropped events

Correct: Async webhook with queue pattern

// GOOD -- "Auto respond with status 200" (no rate limit) + async queue
// Webhook: Auto-respond 200 --> Data Storage queue --> Done
// Separate scheduled workflow: Read queue --> Process batch --> Cleanup

Wrong: Hardcoding field mappings without null/type checks

// BAD -- assumes all fields exist and have expected types
// target.amount = $.steps.salesforce.Amount  (fails if null)
// target.name = $.steps.salesforce.Account.Name (fails if deleted ref)

Correct: Defensive mapping with Boolean checks and type conversion

// GOOD -- null checks + type conversion + fallback values
// Boolean: Amount not null? --> Type Converter (to Number) : default 0.00
// Boolean: Account not null? --> Map Name : "Unknown Customer" + flag
// Script: const d = steps.sf.CloseDate; return d ? new Date(d).toISOString() : now;

Common Pitfalls

• Task credit math blindsides budget: A 5-step workflow with 50K records/day = 250K credits/day = entire Pro tier in 1 day. Fix: Calculate (steps_per_record * daily_volume * runs_per_day) before deploying; use bulk connector operations. [src7]
• Connector timeouts on slow ERP APIs: SAP and Oracle APIs often respond in 10-30s; 45s connector timeout leaves no margin. Fix: Use HTTP Client connector (15-min timeout) for slow endpoints. [src1]
• Data Storage scope confusion: "Current Run" scope data persists for 30 days, not just the current execution. Fix: Explicitly delete keys at workflow end; use unique run-scoped keys. [src1]
• Workspace isolation breaks cross-team workflows: Auth credentials are workspace-scoped; moved workflows lose authentications. Fix: Plan workspace architecture before building; re-authenticate after moves. [src6]
• CSV connector silently truncates at 8 KB per row: Wide ERP records (200+ fields) can exceed per-row limit with no error. Fix: Split wide records into multiple CSVs; use JSON-based Data Storage instead. [src1]
• Merlin AI generates workflows without error handling: AI-generated workflows lack retry logic and edge case handling. Fix: Always review and augment Merlin-generated workflows manually. [src4]

Diagnostic Commands

# Check Tray API rate limit status (look for 429 responses)
curl -X POST "https://tray.io/graphql" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TRAY_USER_TOKEN" \
  -d '{"query": "{ viewer { name } }"}' \
  -w "\nHTTP Status: %{http_code}\n"

# List all workflows and their status
curl -X POST "https://tray.io/graphql" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TRAY_USER_TOKEN" \
  -d '{"query": "{ viewer { workflows { edges { node { id name enabled triggerUrl } } } } }"}'

# Test a webhook trigger endpoint
curl -X POST "$TRAY_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{"test": true, "timestamp": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}'

# Monitor task credit usage: Settings > Usage > Task Credits in Tray UI
# No API endpoint for credit balance (UI-only as of 2026)

Version History & Compatibility

When to Use / When Not to Use

Cross-System Comparison

Important Caveats

• Task credit pricing is opaque -- Tray does not publicly disclose per-credit costs or overage rates. Negotiate credit volume and overage pricing upfront during contract discussions.
• The 6 MB inter-step payload limit is the most commonly hit constraint in ERP integrations and is not obvious during development with small test datasets.
• No native SAP connector means SAP integrations require significantly more development effort compared to Workato or MuleSoft alternatives.
• Tray.ai is cloud-only with no on-premise option. Organizations in regulated industries must verify data transit through Tray's AWS infrastructure meets compliance requirements.
• Connector updates are pushed automatically -- there is no way to pin a specific connector version. Test critical workflows after any connector update notification.
• Merlin AI workflow generation is a starting point, not production-ready -- always add error handling, logging, and edge case management to AI-generated workflows.