> For the complete documentation index, see [llms.txt](https://docs.silkline.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.silkline.ai/configuration/integrations/epsilon3.md).

# Epsilon3

Connect Silkline to Epsilon3 to sync purchase orders both ways, read receiving from Epsilon3 shipments, and import vendors, parts, users and locations

## Overview

Silkline's Epsilon3 integration syncs purchasing data between Silkline and the Epsilon3 Builds module. **Purchase orders flow both ways**: orders created in Epsilon3 are imported into Silkline, and orders created in Silkline are written to Epsilon3 automatically. Epsilon3 owns receiving — Silkline reads each order's received quantities from Epsilon3 shipments. Vendors, users, and locations are read into Silkline from Epsilon3 (**read-only**). Parts are read into Silkline too, and a part an order needs that is missing from Epsilon3 is created there when the order is written.

## Directionality

| Epsilon3             | Silkline                   | Direction                                                                                                            |
| -------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| Purchase Orders      | Orders                     | Two-way (create/edit both sides)                                                                                     |
| Shipments (receipts) | Order received quantities  | Read only (Epsilon3 → Silkline)                                                                                      |
| Vendors              | Suppliers                  | Read only (Epsilon3 → Silkline)                                                                                      |
| Parts                | Materials                  | Import, plus create-only writeback (missing parts are created on order writeback; existing parts are never modified) |
| Users                | Users                      | Read only (Epsilon3 → Silkline)                                                                                      |
| Locations            | Locations                  | Read only (Epsilon3 → Silkline)                                                                                      |
| Custom Field options | Configurable Field options | Read only (Epsilon3 → Silkline)                                                                                      |
| Custom Field values  | Configurable Field values  | Two-way (on orders)                                                                                                  |

Order **writeback is automatic**: creating or editing an order in Silkline pushes it to Epsilon3 with no manual step (when writeback is enabled). Everything else is read from Epsilon3 on a regular schedule, and any synced record can be pulled on demand from its page.

## Prerequisites

To complete your Epsilon3 integration, you will need:

* **Administrator** access to your Epsilon3 workspace
* An Epsilon3 **workspace API key**, created by an Epsilon3 administrator under **Settings → Integrations → API**. The key determines which Epsilon3 workspace the integration syncs. API keys are an Epsilon3 Pro feature
* For a workspace on Epsilon3's **FedRAMP** deployment: Epsilon3 must allowlist Silkline's IP addresses for your specific workspace (see [FedRAMP workspaces](#fedramp-workspaces))
* Optionally, your Epsilon3 **Team ID** — the id in your Epsilon3 URLs (`app.epsilon3.io/app/team/<team-id>/…`). It enables "view in Epsilon3" links on synced records; syncing works without it

## Instructions

{% stepper %}
{% step %}

#### Create an API key in Epsilon3

As an Epsilon3 administrator, go to **Settings → Integrations → API** and generate a workspace API key. Epsilon3's [Generate API key](https://support.epsilon3.io/en/articles/8779712-generate-api-key) guide walks through it.

Use a **workspace** key, not a personal key from your Epsilon3 profile, which carries only its creator's permissions.

{% hint style="warning" %}
Epsilon3 shows the key only once. Copy it before you click **Dismiss** — it cannot be retrieved later.
{% endhint %}
{% endstep %}

{% step %}

#### Create the Integration in Silkline

Follow the [Managing Integrations](https://docs.silkline.ai/configuration/integrations/managing-integrations.md) guide to create a new Epsilon3 integration in Silkline.
{% endstep %}

{% step %}

#### Add Credentials

Open the integration and navigate to the **Secrets** section. Enter the **API Key** from Step 1.

You can verify the key from the integration page with the **Test Connection** button.
{% endstep %}

{% step %}

#### Connection settings

In the integration's connection settings:

* **Region** — **Standard** for most workspaces; **FedRAMP** for a workspace on Epsilon3's FedRAMP deployment (see [FedRAMP workspaces](#fedramp-workspaces)).
* **Team ID** (optional) — paste the team id from your Epsilon3 URL to enable "view in Epsilon3" links on synced orders, parts, and vendors.
* **Create Purchase Orders At** (optional) — the Silkline order status at which the Epsilon3 purchase order is first created (see below).
  {% endstep %}
  {% endstepper %}

## Configuration

### Purchase order creation timing

By default, Silkline creates the Epsilon3 purchase order when the Silkline order reaches **Open**, and updates it on every change from then on.

To create it earlier, set **Create Purchase Orders At** in the integration's connection settings to **Draft**, **Review**, **Approved**, or **Open**. An order that hasn't reached that status is not pushed. Once the purchase order exists in Epsilon3, every subsequent Silkline change syncs to it. A purchase order created before the order is Open stays in Draft in Epsilon3 until the order is Open (see [Order state](#order-state)). An order that is canceled or closed before ever reaching the threshold is never pushed.

### Deep links (Team ID)

With a **Team ID** configured, synced orders, parts, and vendors show a "view in Epsilon3" link that opens the matching record in the Epsilon3 app. Without one, records still sync — the link just doesn't render.

### FedRAMP workspaces

Epsilon3 serves FedRAMP workspaces from a separate deployment with its own API address. Set **Region** to **FedRAMP** so Silkline connects to it.

A FedRAMP workspace accepts API requests only from IP addresses allowlisted for that workspace. Epsilon3 allowlists per workspace, so every FedRAMP workspace needs its own request, even when other workspaces already sync with Silkline. Before you click **Test Connection**, ask Epsilon3 to allowlist Silkline's IP addresses for your workspace — the list is on [Network Allowlist](https://docs.silkline.ai/configuration/network-allowlist.md). Until they are allowlisted, every request fails with an authentication error, even with a valid API key.

## Order state

Epsilon3 purchase orders and Silkline orders each have their own lifecycle. They map as follows.

**Reading from Epsilon3** (for orders created in Epsilon3):

| Epsilon3 state                                  | Silkline order state |
| ----------------------------------------------- | -------------------- |
| Draft                                           | Draft                |
| In Review                                       | Review               |
| Submitted / Partially Received / Fully Received | Open                 |
| Closed                                          | Closed               |
| Canceled                                        | Canceled             |

**Writing to Epsilon3** (for the order's Epsilon3 PO): the only state change Silkline makes is Draft → **Submitted**, when the Silkline order is **Open**. A Silkline order in **Draft**, **Review**, or **Approved** leaves its purchase order in **Draft**. Silkline never moves a purchase order backward, and never sets Epsilon3's In Review, receiving, or terminal states — reviews, receiving progress, closure, and cancellation are owned in Epsilon3.

**Silkline states that aren't written** stay as they are when the order syncs back: a **Review** or **Approved** order keeps its state while its purchase order is Draft or In Review, and an order closed or canceled in Silkline stays Closed or Canceled while its purchase order is still open in Epsilon3.

{% hint style="info" %}
Epsilon3 does not close a purchase order automatically when it is fully received. Closing it explicitly in Epsilon3 closes the matching Silkline order on the next sync.
{% endhint %}

## Receiving

Silkline reads receiving from Epsilon3 **shipments**: each shipment item's **accepted** units count toward the matching order line's received quantity. Rejected units are not counted — Epsilon3 may show a purchase order as "Fully Received" once every unit is dispositioned, while Silkline reports only the accepted units as received.

Shipment items reference the purchase order by **part revision**, not by line. When several lines carry the same part revision, accepted units fill those lines in line order, each up to its ordered quantity, with any overflow (including over-receipt) landing on the last matching line. A line's received date is the earliest accepted receipt for its part.

A Silkline line with no part is written to Epsilon3 as a part-less line. Receiving matches by part revision, so such a line never shows as received in Silkline, even after Epsilon3 receives it.

## Requirements for writing an order

Silkline creates the Epsilon3 purchase order only when the order meets these conditions. An order that does not is reported in its Sync Status and written on the order's next change or a manual push.

* **The buyer is linked to an active Epsilon3 user.** Epsilon3 records the purchase order's creator from the Silkline buyer, so the buyer must be a user imported from Epsilon3. Assign a buyer who exists in Epsilon3, run user sync if they are missing, then push the order.
* **The order has a supplier.** The supplier does not have to exist in Epsilon3 (see below), but the order cannot be written without one.
* **Every line has a quantity and a unit cost.**

## Orders with suppliers or parts not in Epsilon3

An order that meets the requirements above is written to Epsilon3 even when its supplier or some of its materials have no Epsilon3 counterpart:

* **Supplier not in Epsilon3** — the purchase order is created without a vendor, and the supplier is named in the purchase order's notes. If the supplier is later matched to an Epsilon3 vendor, the next update attaches the vendor to the purchase order.
* **Material not in Epsilon3** — the part is created in Epsilon3 automatically (or the line links to an existing part with the same part number), so the line carries a real part reference and can be received. When part creation is disabled for the integration, lines whose items are not in Epsilon3 are left off the Epsilon3 purchase order, and the order's Sync Status reports the missing line until the item is linked or part creation is re-enabled.

## What Gets Synchronized

* **Purchase Orders ↔ Orders** — two-way. Orders created in Epsilon3 import into Silkline; orders created in Silkline are written to Epsilon3 (header and lines). Received quantities are read back from shipments.
* **Vendors → Suppliers** — read only.
* **Parts → Materials** — Epsilon3 parts import into Silkline. Writeback creates an Epsilon3 part when an order line's part is missing there; existing Epsilon3 parts are never modified from Silkline.
* **Users → Users** — read only. Only **active** Epsilon3 users are imported.
* **Locations → Locations** — read only.
* **Custom Fields ↔ Configurable Fields** — a Silkline Configurable Field can be linked to an Epsilon3 custom field (Text, Number, Checkbox, Date, or Ad Hoc List). A linked list field's options fill from Epsilon3 and stay synced (options removed in Epsilon3 are deleted in Silkline), and order values flow both ways: values set in Silkline are written to the Epsilon3 purchase order, and values set in Epsilon3 import into Silkline. The Epsilon3 field must be on the Purchase Order form (Settings > Forms) for values to be written.

## Search and import

Alongside the scheduled reads, you can search Epsilon3 for a specific record and import it on demand. On the integration page, open **Search & Import**, choose a tab, and type to search:

* **Purchase Orders** — by PO code or vendor name
* **Suppliers** — by vendor name
* **Parts** — by exact part number (case-insensitive); Epsilon3 does not search parts by partial number or name

Each result shows whether it is already in Silkline. Select the records you want and import them; each imported record is created or updated in Silkline just as a scheduled read would.

## Keeping data current

Epsilon3 sends no webhooks, so Silkline learns about changes in Epsilon3 on its scheduled reads. Each scheduled read re-reads every record of its type, including records already in Silkline, so new purchase orders, receiving progress, and state changes all arrive on the same schedule. Order writeback is immediate: creating or editing an order in Silkline pushes it to Epsilon3 right away.

## Detailed Data Mappings

### Purchase Order Mapping

| Epsilon3 Field                 | Silkline Field         | Notes                                                                                                                                                                                                                                                      |
| ------------------------------ | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ID                             | External ID            | Epsilon3's unique purchase order identifier                                                                                                                                                                                                                |
| Code                           | Order Number           | **Read only.** Epsilon3 assigns the PO number (e.g. `PO-3`) — including for orders Silkline creates — and Silkline displays it as the order number                                                                                                         |
| Vendor                         | Supplier               | Resolved to/from the matching Silkline supplier. Orders whose supplier is not in Epsilon3 are still written — see [Orders with suppliers or parts not in Epsilon3](#orders-with-suppliers-or-parts-not-in-epsilon3)                                        |
| Created By                     | Buyer                  | Resolved to the matching Silkline user. On import, set only when the Epsilon3 creator is an **active** user; on writeback, the Silkline buyer's Epsilon3 user is written as the creator                                                                    |
| State                          | Order State            | See [Order state](#order-state)                                                                                                                                                                                                                            |
| Delivery Date                  | Estimated Arrival Date | On writeback, Epsilon3's single order-level date comes from the order's line dates (supplier ETA first, then need date), and from the Estimated Arrival Date only when no line has a date                                                                  |
| Notes                          | Notes                  | Set only when the record is first created, in each direction: writeback sends notes (plain text, capped at 4096 characters) when the Epsilon3 purchase order is created and never on update; import fills Silkline notes only when the order first imports |
| Vendor Payment Terms           | Payment Terms          | **Read only.** The imported order's payment terms fill from its Epsilon3 vendor's payment terms                                                                                                                                                            |
| Discount                       | Order Adjustment       | **Read only.** A purchase order's percentage discount imports as a negative "Vendor Discount" adjustment on the order                                                                                                                                      |
| Ship To Name / Ship To Address | Ship-To Address        | On import, the name becomes the first line of the address block. On writeback, the block's first line is sent as the ship-to name and the remaining lines as the address; a one-line block is sent as the address only                                     |
| Created At                     | Created At             | Set once when the record is first imported and never overwritten — an order created in Silkline keeps its own creation date                                                                                                                                |

### Purchase Order Line Mapping

| Epsilon3 Line Field            | Silkline Order Item Field      | Notes                                                                                                                                                                                                                                                                                                                         |
| ------------------------------ | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ID                             | External ID                    | Unique line identifier                                                                                                                                                                                                                                                                                                        |
| Part (revision)                | Part                           | Lines reference a specific part revision; Silkline resolves it to the matching material. On writeback, the part's **current revision** in Epsilon3 is used. Lines whose material is not in Epsilon3 are still written — see [Orders with suppliers or parts not in Epsilon3](#orders-with-suppliers-or-parts-not-in-epsilon3) |
| Quantity                       | Units                          | Number of units ordered                                                                                                                                                                                                                                                                                                       |
| Unit Amount                    | Unit Cost                      | Converted between Epsilon3's cents and Silkline's currency amount                                                                                                                                                                                                                                                             |
| Description                    | Description                    | Free-text line description. Written to Epsilon3 on every sync; imported into Silkline only when the line first imports                                                                                                                                                                                                        |
| Product                        | Supplier PN                    | **Read only.** Set when the line was created from Epsilon3's product catalog (the vendor's part number)                                                                                                                                                                                                                       |
| Accepted units (via shipments) | Units Received / Received Date | **Read only.** Silkline locks the received quantity on these orders. See [Receiving](#receiving)                                                                                                                                                                                                                              |

### Custom Field Mapping

A Silkline Configurable Field links to one Epsilon3 custom field; values flow both ways on orders, and the Epsilon3 field must be on the Purchase Order form (Settings > Forms) for values to be written. The link picker offers only the Epsilon3 fields whose type pairs with the Silkline field's type, so a value keeps its shape in both directions.

| Epsilon3 field type | Silkline field type      | Notes                                                                                                                                             |
| ------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Text                | Text                     |                                                                                                                                                   |
| Number              | Text                     | Number values transfer as text                                                                                                                    |
| Checkbox            | Boolean                  |                                                                                                                                                   |
| Date                | Date                     | The calendar date transfers; Epsilon3 displays it in UTC                                                                                          |
| Ad Hoc List         | Select or Labeled Select | The option list also stays synced from Epsilon3. Silkline's link picker labels these fields **Custom List**, the Epsilon3 API's name for the type |

Time, Date Time, Records, and Predefined List fields cannot be linked — Silkline has no matching field types (or, for Predefined List, the options are not readable via the Epsilon3 API).

{% hint style="warning" %}
An Epsilon3 option with a leading or trailing space (e.g. `Urgent` ) cannot be set through the Epsilon3 API — Epsilon3 rejects the value no matter how it is sent. If a sync reports this, rename the option in Epsilon3 to remove the spaces, then re-pull the linked field's options.
{% endhint %}

### Vendor Mapping

Epsilon3 **Vendors** are read into Silkline **Suppliers** (read only).

| Epsilon3 Vendor Field | Silkline Supplier Field     | Notes                                                                                                                           |
| --------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| ID                    | External ID                 | Unique vendor identifier                                                                                                        |
| Name                  | Name                        | Required — a vendor without a name fails to sync                                                                                |
| Address               | Primary Address             | Set once, when the supplier is created, and only when the free text ends in a recognizable US city/state/ZIP                    |
| Contact               | Primary Phone / Description | A phone number found in the free-text contact becomes the supplier's phone; any prose around it is preserved in the description |
| Notes                 | Description                 | Vendor notes                                                                                                                    |
| Payment Terms         | Default Payment Terms       | The vendor's payment terms text                                                                                                 |
| Emails                | Contacts                    | Each vendor email becomes a Silkline contact (email only — Epsilon3 attaches no names to them)                                  |
| Archived              | Is Archived                 | Archived vendors are archived in Silkline                                                                                       |

### Part Mapping

Epsilon3 **Parts** are read into Silkline **Materials**. Writeback only creates a part an order line needs that is missing from Epsilon3 (see [Orders with suppliers or parts not in Epsilon3](#orders-with-suppliers-or-parts-not-in-epsilon3)); existing Epsilon3 parts are never modified from Silkline.

| Epsilon3 Part Field | Silkline Material Field | Notes                                                                             |
| ------------------- | ----------------------- | --------------------------------------------------------------------------------- |
| ID                  | External ID             | Unique part identifier                                                            |
| Part Number         | Material Number         | Required — a part without one fails to sync                                       |
| Name                | Name                    | Falls back to the part number                                                     |
| Revision            | Revision                | The part's revision label                                                         |
| Description         | Description             | Part description                                                                  |
| Units               | Unit of Measure         | Unit type (EA, etc.)                                                              |
| Tracking            | Tracking Level          | `serial` or `lot`; untracked parts have none                                      |
| Created At          | Created At              | Set once when the material is first imported and never overwritten by later reads |

When Silkline creates a part in Epsilon3, it fills what Epsilon3 requires and the material lacks: the revision defaults to `A`, tracking defaults to none, and the name falls back to the part number. An existing Epsilon3 part with the same part number is linked instead of created.

### User Mapping

Epsilon3 **Users** are read into Silkline **Users** (read only). Only **active** users are imported — pending invitations and deactivated accounts are skipped.

| Epsilon3 User Field | Silkline User Field | Notes                                                                                        |
| ------------------- | ------------------- | -------------------------------------------------------------------------------------------- |
| ID                  | External ID         | Unique user identifier                                                                       |
| Email               | Username / Email    | Required — a user without an email fails to sync. Matches an existing Silkline user by email |
| First / Last Name   | First / Last Name   | User's name                                                                                  |
| Job Title           | Title               | Shown on the user and their contact                                                          |
| Phone               | Phone               | Set on the user's contact                                                                    |

### Location Mapping

Epsilon3 **Locations** are read into Silkline **Locations** (read only), for use as predefined ship-to locations.

| Epsilon3 Location Field | Silkline Location Field | Notes                                                             |
| ----------------------- | ----------------------- | ----------------------------------------------------------------- |
| ID                      | External ID             | Unique location identifier                                        |
| Name / Code             | Name                    | The name, falling back to the code                                |
| —                       | Address                 | Epsilon3 locations carry no address data, so the address is empty |

## Custom Fields

A Silkline **Configurable Field** can be linked to an Epsilon3 **custom field**. Once linked, values on orders flow both ways, and a list field's options fill from Epsilon3 and stay synced. See [Custom Field Mapping](#custom-field-mapping) for which field types pair.

{% stepper %}
{% step %}
**Open the field's integration link**

In **Settings → Configurable Fields**, open (or create) a field whose type pairs with the Epsilon3 field, and open its integration link for the Epsilon3 integration.
{% endstep %}

{% step %}
**Choose the Epsilon3 custom field**

Select the **Custom Field** link type and pick the Epsilon3 field from the list. The list offers only the Epsilon3 fields whose type pairs with the Silkline field's type.
{% endstep %}

{% step %}
**Pull**

For a list field, run a pull on the link. The field's options fill from Epsilon3 and stay synced on every scheduled read: options removed in Epsilon3 are deleted in Silkline. When the Epsilon3 field's option list is empty, the Silkline options are left as they are.
{% endstep %}
{% endstepper %}

Make sure the Epsilon3 field is on the **Purchase Order form** (Epsilon3 **Settings → Forms**). A value for a field that is not on the form fails the order's writeback, and the Sync Status names the field.

## Sync checks and data sync protection

After Silkline writes a purchase order to Epsilon3, it runs a **sync check**: the purchase order is read back from Epsilon3 and compared, field by field, against the Silkline order. The result drives a protection called the **sync lock**:

* **No differences** — the two systems agree, and scheduled reads from Epsilon3 continue to update the order normally.
* **Differences remain** — Epsilon3 did not accept every change. The order is **locked**: scheduled reads stop updating it, so the Silkline version is preserved until you resolve the mismatch.

Fields Epsilon3 owns or that writeback cannot set are never compared, so they cannot lock an order: the PO code, the order state, the Estimated Arrival Date, Created At, payment terms and notes on the order, and the line number, supplier part number, received quantity, received date and description on each line.

An order's sync sidebar gives you both surfaces:

* The **Sync Check** tab runs the comparison on demand and lists exactly which fields differ between Epsilon3 and Silkline.
* The **Data Sync Protection** card shows whether the order is locked and lets you clear the lock. Clearing it lets the next read from Epsilon3 update the order again — use it once the mismatch is resolved, or when Epsilon3's version is the one you want.

{% hint style="warning" %}
A locked order also stops receiving updates: received quantities, closure, and cancellation recorded in Epsilon3 do not reach Silkline until the lock is cleared. A locked order shows a lock badge on the order and in order tables.
{% endhint %}

## Known Limitations

### Orders carry a single user

An Epsilon3 purchase order records one user (its creator), which maps to the Silkline **buyer**. The Silkline **requester** is not set on imported orders, so they show a "requester" validation warning until one is assigned in Silkline.

### Rejected units are not counted as received

Epsilon3 considers a purchase order "Fully Received" once every unit is dispositioned — accepted **or** rejected. Silkline counts only accepted units, so an order with rejections shows as partially received in Silkline while Epsilon3 shows it fully received.

### Vendor addresses are imported once

Epsilon3 stores a vendor's address as a single free-text value. When Silkline creates a supplier from a vendor, it imports that address when the value ends in a recognizable US city/state/ZIP. Other formats (including international addresses) are not imported. Later syncs leave supplier addresses unchanged, so maintain them in Silkline.

### Deactivated Epsilon3 users are not archived

Only active Epsilon3 users are imported. A user who is later deactivated in Epsilon3 stops syncing but is not automatically archived in Silkline — archive them in Silkline directly if needed.

## Frequently Asked Questions

### How often does the data sync?

**Order writeback is automatic** — editing an order in Silkline pushes it to Epsilon3 (when writeback is enabled). Data from Epsilon3 — orders, receiving progress, vendors, parts, users, locations — is pulled **on a regular schedule**, and any individual record can be pulled on demand from its page in Silkline.

### Who assigns purchase order numbers?

Epsilon3 does. When Silkline creates a purchase order in Epsilon3, Epsilon3 assigns its PO code (e.g. `PO-17`), and Silkline displays that code as the order number.

### What happens when an order is closed or canceled in Epsilon3?

The matching Silkline order moves to **Closed** or **Canceled** on the next sync. Silkline never closes or cancels the Epsilon3 purchase order itself.

### Which system is the source of truth?

Orders can be created in either system. Orders created in Silkline are written to Epsilon3 and updated there on every Silkline change; orders created in Epsilon3 import into Silkline and pick up Epsilon3 changes on each scheduled pull. Receiving, closure, and cancellation always flow **from** Epsilon3. Vendors, parts, users, and locations are owned by Epsilon3 — Silkline reads them and never modifies them. The one exception is a part an order needs that is missing from Epsilon3, which Silkline creates.
