External References - Threadify Documentation

References link threads to external system identifiers like order IDs, customer IDs, or support tickets. They enable you to query threads using identifiers from your existing systems.

Reference Types

Type	Example Use Case
Order IDs	E-commerce order numbers
Custom IDs	Any business-relevant identifier

Reference Properties

Property	Description
Key	The reference type (e.g., “order_id”)
Value	The actual identifier (e.g., “ORD-789”)
Thread association	Links to a specific thread
Queryable	Can be used to find threads

Adding References

Link workflows to external systems (Stripe, Shopify, etc.):

// Add references to an existing thread
await thread.addRefs({
  stripe_payment_id: payment.id,
  stripe_customer_id: payment.customer,
  order_id: 'ORD-12345'
});

await thread.step('process_payment')
  .addContext({ amount: 299.99, currency: 'USD' })
  .success();

// Add references to an existing thread
err = thread.AddRefs(ctx, map[string]string{
    "stripe_payment_id":   payment.ID,
    "stripe_customer_id": payment.Customer,
    "order_id":           "ORD-12345",
})
if err != nil {
    log.Fatal(err)
}

_, err = thread.Step("process_payment").
    AddContext(map[string]any{"amount": 299.99, "currency": "USD"}).
    Success(ctx)
if err != nil {
    log.Fatal(err)
}

# Add references to an existing thread
await thread.add_refs({
    "stripe_payment_id": payment.id,
    "stripe_customer_id": payment.customer,
    "order_id": "ORD-12345"
})

await (
    thread.step("process_payment")
    .add_context({"amount": 299.99, "currency": "USD"})
    .success()
)

Querying by Reference

const threads = await threadify.getThreadsByRef({
  refKey: 'stripe_payment_id',
  refValue: 'pi_1234567890'
});

threads, err := conn.GetThreadsByRef(ctx, &threadify.RefQuery{
    RefKey:   "stripe_payment_id",
    RefValue: "pi_1234567890",
})
if err != nil {
    log.Fatal(err)
}

from threadify.models import RefQuery

threads = await conn.get_threads_by_ref(
    RefQuery(ref_key="stripe_payment_id", ref_value="pi_1234567890")
)

Next Steps

Sub-steps

Break down complex operations

Getting Threads

Query workflow data