> ## Documentation Index
> Fetch the complete documentation index at: https://docs.threadify.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# External References

> Link your workflows to external systems like Stripe, Shopify, and more

**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.):

<CodeGroup>
  ```javascript JavaScript theme={null}
  // 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();
  ```

  ```go Go theme={null}
  // 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)
  }
  ```

  ```python Python theme={null}
  # 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()
  )
  ```
</CodeGroup>

### Querying by Reference

<CodeGroup>
  ```javascript JavaScript theme={null}
  const threads = await threadify.getThreadsByRef({
    refKey: 'stripe_payment_id',
    refValue: 'pi_1234567890'
  });
  ```

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

  ```python Python theme={null}
  from threadify.models import RefQuery

  threads = await conn.get_threads_by_ref(
      RefQuery(ref_key="stripe_payment_id", ref_value="pi_1234567890")
  )
  ```
</CodeGroup>

### Next Steps

<CardGroup cols={2}>
  <Card title="Sub-steps" icon="list-tree" href="/core-concepts/sub-steps">
    Break down complex operations
  </Card>

  <Card title="Getting Threads" icon="database" href="/core-concepts/data-retrieval/getting-threads">
    Query workflow data
  </Card>
</CardGroup>