API Documentation - Tracee Production Tracking

Introduction

Tracee is a production tracking platform that helps businesses provide real-time visibility into their production processes. Whether you're running a 3D printing shop, manufacturing facility, or any production-based business, Tracee lets your customers track their orders from start to finish.

Why Use Tracee?

Reduce support inquiries - Customers can self-serve order status
Build trust - Transparency increases customer confidence
Simple integration - Just 3 API calls to get started
White-label ready - Embed tracking directly in your site

✨ Pro Tip: Most integrations only need 2 API calls: one to create a tracker and one to update status!

Quick Start

Get up and running in 5 minutes with these simple steps:

Get Your API Key
Log into your Tracee dashboard and navigate to Settings → API Keys. Generate a new key and copy it securely.
Create Your First Tracker
When a customer places an order, create a tracker:

curl -X POST https://tracee.app/api/v1/trackers/ \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "Order #1234", "template": "3d-printing"}'
Share the Tracking Link
The response includes a tracking_url - send this to your customer via email or SMS!
Update Status as You Work
As the order progresses, update the status:

curl -X POST https://tracee.app/api/v1/trackers/123/status/ \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"process": "3D Printing", "action": "complete"}'

💡 That's it! Your customer can now track their order in real-time.

Key Concepts

Trackers

A Tracker represents a single item or order being tracked. Each tracker has:

A unique ID and tracking token
A customer-friendly name (e.g., "Order #1234 - Blue Vase")
A list of process steps (from a template)
Current status and history

Processes

Processes are the individual steps in your workflow. For example:

Design Review → 3D Printing → Quality Check → Packaging → Shipped

Each process can be marked as "started" or "completed", and you control which processes are visible to customers.

Templates

Templates are pre-defined workflows that automatically create process steps when you create a tracker. This saves time and ensures consistency.

Authentication

All API requests require authentication using an API key. Include your key in the request header:

X-API-Key: tk_live_your_api_key_here

⚠️ Keep your API key secret! Never expose it in client-side code, public repositories, or browser requests.

Generating API Keys

Log into your Tracee dashboard
Go to Settings → API Keys
Click "Generate New Key"
Give it a descriptive name (e.g., "Production Server")
Copy and store the key securely - it won't be shown again!

Create Tracker

Create a new tracker when a customer places an order.

POST /api/v1/trackers/

Request Body

Parameter	Type	Required	Description
name	string	Required	Display name for the tracker (e.g., "Order #1234")
template	string	Optional	Template slug to use (e.g., "3d-printing")

Example Request

curl -X POST https://tracee.app/api/v1/trackers/ \
  -H "X-API-Key: tk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order #5678 - Custom Chess Set",
    "template": "3d-printing"
  }'
            

Example Response

{
  "id": 42,
  "number": 5678,
  "name": "Order #5678 - Custom Chess Set",
  "tracking_url": "https://tracee.app/track/a1b2c3d4-e5f6-...",
  "api_url": "https://tracee.app/api/v1/trackers/42/",
  "embed_code": "<iframe src=\"https://tracee.app/embed/a1b2c3d4-e5f6-...\" ...>",
  "qr_code_url": "https://tracee.app/api/v1/trackers/42/qr/",
  "tracking_token": "a1b2c3d4-e5f6-..."
}
            

✅ Success! Send the tracking_url to your customer so they can track their order.

Update Status

Update the status of a tracker as the order progresses through your workflow.

POST /api/v1/trackers/{tracker_id}/status/

Request Body

Parameter	Type	Required	Description
process	string	Required	Name of the process step (e.g., "3D Printing")
action	string	Required	Either "start" or "complete"

Example: Start Printing

curl -X POST https://tracee.app/api/v1/trackers/42/status/ \
  -H "X-API-Key: tk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"process": "3D Printing", "action": "start"}'
            

Example: Complete Printing

curl -X POST https://tracee.app/api/v1/trackers/42/status/ \
  -H "X-API-Key: tk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"process": "3D Printing", "action": "complete"}'
            

Get Tracker Details

Retrieve full details about a tracker, including its current status and history.

GET /api/v1/trackers/{tracker_id}/

Example Response

{
  "id": 42,
  "name": "Order #5678 - Custom Chess Set",
  "tracking_url": "https://tracee.app/track/a1b2c3d4-...",
  "current_process": "3D Printing",
  "is_completed": false,
  "history": [
    {
      "process": "Preparing/Slicing",
      "status": "completed",
      "started_at": "2026-01-31T10:00:00Z",
      "completed_at": "2026-01-31T10:30:00Z"
    },
    {
      "process": "3D Printing",
      "status": "in_progress",
      "started_at": "2026-01-31T10:35:00Z",
      "completed_at": null
    }
  ]
}
            

QR Code

Get a QR code image that links to the tracking page. Perfect for printing on packing slips or labels!

GET /api/v1/trackers/{tracker_id}/qr/

Returns a PNG image of the QR code. You can embed this directly in your documents:

<img src="https://tracee.app/api/v1/trackers/42/qr/?api_key=YOUR_KEY" alt="Track Order">
            

Process Templates

Templates define the workflow steps for your trackers. When you create a tracker with a template, it automatically sets up all the process steps.

Available Templates

GET /api/v1/templates/

Example: 3D Printing Template

{
  "slug": "3d-printing",
  "name": "3D Printing Workflow",
  "steps": [
    {"name": "Preparing/Slicing", "order": 1, "visible": true},
    {"name": "3D Printing", "order": 2, "visible": true},
    {"name": "Post-Processing", "order": 3, "visible": true},
    {"name": "Quality Check", "order": 4, "visible": false},
    {"name": "Packaging", "order": 5, "visible": true},
    {"name": "Ready for Shipping", "order": 6, "visible": true}
  ]
}
            

💡 Note: Steps with visible: false are internal steps that won't appear on the customer tracking page.

Custom Templates

Contact us to create custom templates for your specific workflow. We can set up templates for:

Manufacturing processes
Food preparation
Print shops
Repair services
Any custom workflow!

E-commerce Integration

Here's a typical integration flow for an e-commerce platform:

// When order is placed and payment confirmed
async function onOrderConfirmed(order) {
  // 1. Create tracker in Tracee
  const tracker = await fetch('https://tracee.app/api/v1/trackers/', {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.TRACEE_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: `Order #${order.id} - ${order.productName}`,
      template: '3d-printing',
    }),
  }).then(r => r.json());

  // 2. Store tracking URL in your order
  await db.orders.update(order.id, {
    traceeTrackingUrl: tracker.tracking_url,
    traceeTrackerId: tracker.id,
  });

  // 3. Include tracking link in confirmation email
  await sendEmail({
    to: order.customerEmail,
    subject: 'Order Confirmed!',
    body: `Track your order: ${tracker.tracking_url}`,
  });
}

// When order status changes
async function onOrderStatusChange(order, newStatus) {
  if (!order.traceeTrackerId) return;

  // Map your status to Tracee process updates
  const statusMap = {
    'printing': { process: '3D Printing', action: 'start' },
    'shipped': { process: 'Ready for Shipping', action: 'complete' },
  };

  const update = statusMap[newStatus];
  if (update) {
    await fetch(`https://tracee.app/api/v1/trackers/${order.traceeTrackerId}/status/`, {
      method: 'POST',
      headers: {
        'X-API-Key': process.env.TRACEE_API_KEY,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(update),
    });
  }
}
            

Firebase / Node.js Integration

Here's a complete Firebase Cloud Functions integration:

// traceeIntegration.ts
import * as functions from "firebase-functions";

const TRACEE_API_KEY = functions.config().tracee?.api_key;
const TRACEE_BASE_URL = "https://tracee.app";

export interface TraceeTracker {
  id: number;
  tracking_url: string;
  qr_code_url: string;
}

export const createTracker = async (orderName: string): Promise<TraceeTracker | null> => {
  if (!TRACEE_API_KEY) {
    console.warn("Tracee API key not configured");
    return null;
  }

  const response = await fetch(`${TRACEE_BASE_URL}/api/v1/trackers/`, {
    method: "POST",
    headers: {
      "X-API-Key": TRACEE_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: orderName,
      template: "3d-printing",
    }),
  });

  if (!response.ok) {
    throw new Error(`Tracee API error: ${response.status}`);
  }

  return response.json();
};

export const updateStatus = async (
  trackerId: number,
  process: string,
  action: "start" | "complete"
): Promise<void> => {
  await fetch(`${TRACEE_BASE_URL}/api/v1/trackers/${trackerId}/status/`, {
    method: "POST",
    headers: {
      "X-API-Key": TRACEE_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ process, action }),
  });
};
            

Setup

# Configure your API key
firebase functions:config:set tracee.api_key="tk_live_your_key_here"

# Deploy
firebase deploy --only functions
            

Python Integration

Here's a simple Python client for Tracee:

import requests
import os

class TraceeClient:
    def __init__(self, api_key=None, base_url="https://tracee.app"):
        self.api_key = api_key or os.environ.get("TRACEE_API_KEY")
        self.base_url = base_url
        self.headers = {
            "X-API-Key": self.api_key,
            "Content-Type": "application/json"
        }

    def create_tracker(self, name, template=None):
        """Create a new tracker."""
        data = {"name": name}
        if template:
            data["template"] = template
        
        response = requests.post(
            f"{self.base_url}/api/v1/trackers/",
            json=data,
            headers=self.headers
        )
        response.raise_for_status()
        return response.json()

    def update_status(self, tracker_id, process, action):
        """Update tracker status. Action is 'start' or 'complete'."""
        response = requests.post(
            f"{self.base_url}/api/v1/trackers/{tracker_id}/status/",
            json={"process": process, "action": action},
            headers=self.headers
        )
        response.raise_for_status()
        return response.json()

    def get_tracker(self, tracker_id):
        """Get tracker details."""
        response = requests.get(
            f"{self.base_url}/api/v1/trackers/{tracker_id}/",
            headers=self.headers
        )
        response.raise_for_status()
        return response.json()

# Usage
tracee = TraceeClient(api_key="tk_live_...")

# Create tracker
tracker = tracee.create_tracker(
    name="Order #1234 - Blue Vase",
    template="3d-printing"
)
print(f"Tracking URL: {tracker['tracking_url']}")

# Update status
tracee.update_status(tracker["id"], "3D Printing", "start")
tracee.update_status(tracker["id"], "3D Printing", "complete")
            

Embed Widget

Embed the tracking widget directly on your website using an iframe:

<iframe 
  src="https://tracee.app/embed/YOUR_TRACKING_TOKEN/"
  width="100%"
  height="400"
  frameborder="0"
  style="border-radius: 12px; box-shadow: 0 2px 8px rgba(0,0,0,0.1);"
></iframe>
            

The embed code is returned when you create a tracker in the embed_code field.

💡 Tip: The embed widget is compact and designed to fit in sidebars, order detail pages, or email tracking pages.

Webhooks (Coming Soon)

Soon you'll be able to receive real-time notifications when tracker status changes:

tracker.created - New tracker created
tracker.status_changed - Process started or completed
tracker.completed - All processes completed

Contact us if you need webhook support for your integration.

Frequently Asked Questions

How many trackers can I create?

This depends on your plan. Contact us for details on enterprise limits.

Can I customize the tracking page appearance?

Yes! White-label options are available. Contact us for branding customization.

What happens if the API is down?

We recommend handling API errors gracefully - your core business flow should continue even if tracking fails. Store the order data and retry later.

Can customers respond or add notes?

Currently, the public tracking page is read-only. Customer communication features are on our roadmap.

Is there a rate limit?

Yes, API calls are limited to 100 requests per minute per API key. Contact us if you need higher limits.

How do I test the integration?

Use your live API key with test orders. We recommend creating a test order flow in your staging environment.

Need Help?

We're here to help you integrate Tracee into your business. Reach out to us:

Email: support@tracee.app
Documentation issues? Open a GitHub issue
Need custom integration? Contact our solutions team

📚 Tracee Documentation

Introduction

Why Use Tracee?

Quick Start

Key Concepts

Trackers

Processes

Templates

Authentication

Generating API Keys

Create Tracker

Request Body

Example Request

Example Response

Update Status

Request Body

Example: Start Printing

Example: Complete Printing

Get Tracker Details

Example Response

QR Code

Process Templates

Available Templates

Example: 3D Printing Template

Custom Templates

E-commerce Integration

Firebase / Node.js Integration

Setup

Python Integration

Embed Widget

Webhooks (Coming Soon)

Frequently Asked Questions

How many trackers can I create?

Can I customize the tracking page appearance?

What happens if the API is down?

Can customers respond or add notes?

Is there a rate limit?

How do I test the integration?

Need Help?