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

# Integration Setup

> Connect Tether to your e-commerce and data systems

# Integration Setup

Integrations connect Tether to your external systems, automatically syncing sales orders, inventory, products, and other data.

<Note>
  Integration setup requires Admin access. Contact your administrator if you need to set up integrations.
</Note>

## Why Integrate?

| Benefit                 | Description                                   |
| ----------------------- | --------------------------------------------- |
| **Automated Data Flow** | No manual data entry                          |
| **Scheduled Sync**      | Data stays current with cron-based scheduling |
| **Reduced Errors**      | Eliminate manual mistakes                     |
| **Time Savings**        | Focus on analysis, not data entry             |

## Supported External Services

Tether connects to external systems through the ingestion service. The following external services are currently supported:

| External Service | Description                                                  |
| ---------------- | ------------------------------------------------------------ |
| **Shopify**      | E-commerce platform for sales orders and products            |
| **BigQuery**     | Google Cloud data warehouse for sales history and other data |
| **Redshift**     | AWS data warehouse for sales history and other data          |
| **TrackStar**    | Warehouse management system for inventory data               |
| **Brewman**      | Brewery management system                                    |

<Note>
  The available external services and their supported capabilities are loaded dynamically from the system metadata. New services may be added without requiring a documentation update.
</Note>

### Data Types (Capabilities)

Each external service supports a subset of the following data types that can be synced:

| Data Type               | Description                         |
| ----------------------- | ----------------------------------- |
| **Sales Orders**        | Individual sales order records      |
| **Sales History**       | Aggregated historical sales data    |
| **Pending Sales**       | Orders not yet completed            |
| **Warehouse Inventory** | Stock levels from warehouse systems |
| **Products**            | Product and SKU information         |
| **Channels**            | Channel configuration data          |
| **Pricing**             | Pricing information                 |
| **Forecast Versions**   | Forecast data                       |
| **Sales Forecast**      | Sales forecast data                 |

When creating an integration, you select which data types (capabilities) to enable based on what the chosen external service supports.

## Setting Up an Integration

### General Setup Flow

<Steps>
  <Step title="Navigate to Integrations">
    Go to **Integrations** in the sidebar
  </Step>

  <Step title="Click Create Integration">
    Click the **Create Integration** button to open the setup dialog
  </Step>

  <Step title="Enter Basic Information">
    | Field                | Required | Description                                     |
    | -------------------- | -------- | ----------------------------------------------- |
    | **Integration Name** | Yes      | A descriptive name (e.g., "Shopify Production") |
    | **External Service** | Yes      | Select from the dropdown of available services  |
  </Step>

  <Step title="Configure Schedule">
    Set the sync schedule:

    | Field               | Default       | Description                                       |
    | ------------------- | ------------- | ------------------------------------------------- |
    | **Cron Expression** | `0 0 0 * * *` | When the sync runs (daily at midnight by default) |
    | **Timezone**        | UTC           | Timezone for the cron schedule                    |
  </Step>

  <Step title="Select Capabilities">
    Check the data types you want to sync. The available options depend on the selected external service. Each capability shows a display name and description.
  </Step>

  <Step title="Enter Credentials">
    Provide the required credentials for the selected service. The credential fields are dynamic — each service defines its own required fields (e.g., API keys, store URLs, access tokens).
  </Step>

  <Step title="Create">
    Click **Create Integration** to save. You will be navigated to the integration detail page.
  </Step>
</Steps>

### Shopify Integration

To connect a Shopify store:

<Steps>
  <Step title="Create Integration">
    Click **Create Integration** and select **Shopify** as the external service
  </Step>

  <Step title="Enter Credentials">
    Provide the required Shopify credentials:

    | Credential                 | Description                                                       |
    | -------------------------- | ----------------------------------------------------------------- |
    | **Store URL**              | Your Shopify store URL (e.g., `your-store.myshopify.com`)         |
    | **Admin API Access Token** | Generated from Shopify Admin → Settings → Apps and sales channels |
  </Step>

  <Step title="Select Capabilities">
    Choose which data types to sync (e.g., sales orders, products)
  </Step>

  <Step title="Set Schedule">
    Configure the cron expression for sync frequency. A daily sync is recommended for most use cases.
  </Step>

  <Step title="Create and Enable">
    Create the integration. It will be enabled by default and begin syncing on the configured schedule.
  </Step>
</Steps>

**Shopify sync details:**

* Uses the Shopify GraphQL Admin API to fetch orders
* Syncs new and updated orders since the last sync
* Filters orders by financial status (paid, partially refunded)
* Maps Shopify SKUs to Tether SKUs via external ID matching

### Data Warehouse Integrations (BigQuery / Redshift)

For importing data from data warehouses:

<Steps>
  <Step title="Create Integration">
    Select **BigQuery** or **Redshift** as the external service
  </Step>

  <Step title="Enter Connection Credentials">
    Provide the required database connection details as prompted by the credential fields
  </Step>

  <Step title="Select Data Types">
    Choose which data types to import (e.g., sales history, products, pricing)
  </Step>

  <Step title="Configure Schedule">
    Set the cron expression for how often to pull data
  </Step>
</Steps>

### Warehouse Integration (TrackStar)

For syncing inventory data from warehouse management systems:

<Steps>
  <Step title="Create Integration">
    Select **TrackStar** as the external service
  </Step>

  <Step title="Enter Credentials">
    Provide the required TrackStar API credentials
  </Step>

  <Step title="Select Capabilities">
    Enable **Warehouse Inventory** and any other supported data types
  </Step>

  <Step title="Configure Schedule">
    Set the sync frequency using a cron expression
  </Step>
</Steps>

## Integration Configuration

### Schedule Settings

Integrations use cron expressions for scheduling with timezone support:

| Setting             | Description                    | Example                                    |
| ------------------- | ------------------------------ | ------------------------------------------ |
| **Cron Expression** | Standard 6-field cron format   | `0 0 0 * * *` (daily at midnight)          |
| **Timezone**        | IANA timezone for the schedule | `America/New_York`, `Europe/London`, `UTC` |

Common cron patterns:

| Schedule          | Cron Expression |
| ----------------- | --------------- |
| Daily at midnight | `0 0 0 * * *`   |
| Every 6 hours     | `0 0 */6 * * *` |
| Every hour        | `0 0 * * * *`   |

### Capabilities

Capabilities define which data types the integration syncs. You can enable or disable individual capabilities from the integration detail page after creation.

### Dry Run Mode

Integrations can operate in **dry run mode**, which validates data mapping without saving any data to Tether. This is useful for:

* Verifying field mappings before going live
* Testing new integration configurations
* Debugging data quality issues

## Managing Integrations

### Integration Dashboard

The integrations dashboard shows all configured integrations with:

| Column               | Description                                      |
| -------------------- | ------------------------------------------------ |
| **Name**             | Integration display name                         |
| **External Service** | The connected platform (e.g., Shopify, BigQuery) |
| **Status**           | Enabled or disabled                              |
| **Last Sync**        | When the integration last ran                    |
| **Next Sync**        | When the next scheduled sync will occur          |
| **Capabilities**     | Which data types are configured                  |

### Integration Detail Page

Click on an integration to view its detail page, which includes:

* **Integration info**: Name, external service, enabled status, dry run mode
* **Schedule settings**: Cron expression and timezone (editable)
* **Capabilities**: List of enabled data types (editable)
* **Sync execution history**: Table of past sync runs with status, domain type, duration, and record counts

### Enabling / Disabling an Integration

Toggle the integration's enabled status from the integration detail page or the dashboard. Disabling an integration stops all scheduled syncs but preserves the configuration.

### Triggering a Manual Sync

From the integration detail page, click **Trigger Sync** to run an immediate sync outside the regular schedule.

### Resetting Sync State

<Warning>
  This action is only available to administrators. Resetting sync state deletes all execution history for the integration and forces the next sync to perform a full data fetch.
</Warning>

Use **Reset Sync State** when you need to re-import all data from scratch, such as after fixing a mapping issue.

### Deleting an Integration

To permanently remove an integration:

1. Navigate to the integration detail page
2. Click **Delete Integration**
3. Confirm the deletion

<Warning>
  Deleting an integration removes all its configuration and sync history. Historical data already synced to Tether is preserved.
</Warning>

## Credential Management

Each external service defines its own credential fields. Credentials are entered during integration creation and stored securely.

| Aspect              | Details                                                           |
| ------------------- | ----------------------------------------------------------------- |
| **Dynamic Fields**  | Credential fields vary by service — the form adapts automatically |
| **Field Types**     | Text fields, number fields, with labels and placeholders          |
| **Required Fields** | Marked with an asterisk (\*) in the form                          |
| **Security**        | Credentials are stored securely and not displayed after creation  |

## Integration Best Practices

<AccordionGroup>
  <Accordion title="Use Dry Run First">
    Before enabling a new integration for production use:

    * Run in dry run mode to validate mappings
    * Review the sync execution results for errors
    * Check for unmapped SKUs or channels
  </Accordion>

  <Accordion title="Monitor Initial Syncs">
    After enabling:

    * Watch the first few sync executions
    * Verify data accuracy in Tether
    * Check for failed or skipped records
  </Accordion>

  <Accordion title="Choose Appropriate Schedules">
    Set sync frequency based on your needs:

    * Daily syncs are sufficient for most sales data
    * More frequent syncs for real-time inventory needs
    * Consider API rate limits of the external service
  </Accordion>

  <Accordion title="Regular Review">
    Periodically check:

    * Sync execution history for failures
    * Credential validity
    * Data quality and completeness
  </Accordion>
</AccordionGroup>

## Multiple Integrations

### Managing Multiple Sources

You can create multiple integrations, even for the same external service:

* Each integration has its own schedule and capabilities
* Data flows to appropriate channels based on mapping
* All data is consolidated within Tether

### Integration Architecture Options

Tether supports different integration architectures depending on your needs:

| Pattern                             | Description                                                                 |
| ----------------------------------- | --------------------------------------------------------------------------- |
| **Individual Channel Integrations** | One integration per sales channel (e.g., one Shopify integration per store) |
| **Centralized ERP Integration**     | A single ERP or data warehouse integration that provides all sales data     |
| **Hybrid**                          | Combination of direct channel integrations and centralized data sources     |

See [Sync Sessions](/integrations/sync-sessions) for details on monitoring your integrations.

## Next Steps

<CardGroup cols={2}>
  <Card title="Sync Sessions" icon="rotate" href="/integrations/sync-sessions">
    Monitor sync activity
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/troubleshooting">
    Resolve integration issues
  </Card>

  <Card title="Channels" icon="shopping-cart" href="/channels/overview">
    Manage sales channels
  </Card>

  <Card title="User Access" icon="users" href="/administration/user-access">
    Control integration access
  </Card>
</CardGroup>