# Sync Engine

**Category:** Admin
**Base URL:** `/admin/sync-engine`
**Authentication:** Required
**Routes:** 14 routes documented

## Overview

This section documents 14 API routes for sync engine.

> ⚠️ **These endpoints operate on your live store.** `POST`/`PUT`/`DELETE` operations here — including sync, push, resync, and cache operations — modify or delete production data, and some trigger downstream effects such as warehouse orders or customer emails. `DELETE` operations are generally irreversible. Verify IDs and parameters carefully before calling them from scripts.

## Quick Reference

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/admin/sync-engine` | No description |
| POST | `/admin/sync-engine/audit/batch-validate` | POST /admin/sync-engine/audit/batch-validate Validate a batc... |
| GET | `/admin/sync-engine/audit/compare/:orderId` | GET /admin/sync-engine/audit/compare/:orderId Compare provid... |
| GET | `/admin/sync-engine/audit/history/:orderId` | GET /admin/sync-engine/audit/history/:orderId Retrieve compl... |
| GET | `/admin/sync-engine/errors` | No description |
| POST | `/admin/sync-engine/errors/:id/resolve` | No description |
| GET | `/admin/sync-engine/jobs` | No description |
| POST | `/admin/sync-engine/jobs/:id/cancel` | No description |
| POST | `/admin/sync-engine/jobs/:id/retry` | No description |
| GET | `/admin/sync-engine/providers` | No description |
| POST | `/admin/sync-engine/providers` | No description |
| POST | `/admin/sync-engine/providers/:id/sync` | No description |
| POST | `/admin/sync-engine/providers/:id/validate` | No description |
| POST | `/admin/sync-engine/reset-circuit-breaker` | POST /admin/sync-engine/reset-circuit-breaker Reset the circ... |
| POST | `/admin/sync-engine/sync-order` | POST /admin/sync-engine/sync-order Sync a single order by pr... |

---

## GET Admin Sync-engine

**Endpoint:** `GET /admin/sync-engine`
**Authentication:** Admin (Required)

### Response

**Success:**
```typescript
{
  success,
  providers,
  metrics,
}
```

**Error (500):**
```typescript
{
  success,
  error,
}
```

### Example Request

```bash
curl -X GET 'https://your-store.omnicart.cc/admin/sync-engine' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'
```

---

## POST Admin Sync-engine Audit Batch-validate

**Endpoint:** `POST /admin/sync-engine/audit/batch-validate`
**Authentication:** Admin (Required)

### Description

POST /admin/sync-engine/audit/batch-validate Validate a batch of synced orders within a date range. Performs automated validation checks and generates report. Request body: { start_date: "2024-01-01", end_date: "2024-01-31", provider_id: "konnektive", validation_rules: ["totals_match", "required_fields", "status_valid"] }

### Request Body

This route does not declare a validation schema, so the accepted fields are not derivable from the source. Check the handler before relying on a particular body.

### Response

**Success:**
```typescript
{
  success,
  date_range,
  provider_id,
  validation_rules,
  report,
  results,
}
```

**Error (500):**
```typescript
{
  success,
  error,
}
```

### Example Request

```bash
curl -X POST 'https://your-store.omnicart.cc/admin/sync-engine/audit/batch-validate' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'
```

---

## GET Admin Sync-engine Audit Compare :orderId

**Endpoint:** `GET /admin/sync-engine/audit/compare/:orderId`
**Authentication:** Admin (Required)

### Description

GET /admin/sync-engine/audit/compare/:orderId Compare provider order data with synced OmniCart order data. Shows side-by-side comparison for validation and troubleshooting.

### URL Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `orderId` | string | Yes | OrderId identifier |

### Response

**Success:**
```typescript
{
  success,
  order_id,
  provider_id,
  provider_order,
  medusa_order,
  medusa_order_id,
  comparison,
  field_mapping,
}
```

**Error (500):**
```typescript
{
  success,
  error,
}
```

### Example Request

```bash
curl -X GET 'https://your-store.omnicart.cc/admin/sync-engine/audit/compare/:orderId' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'
```

---

## GET Admin Sync-engine Audit History :orderId

**Endpoint:** `GET /admin/sync-engine/audit/history/:orderId`
**Authentication:** Admin (Required)

### Description

GET /admin/sync-engine/audit/history/:orderId Retrieve complete sync history for a specific order across all sync attempts. Shows timeline of all jobs and errors related to this order.

### URL Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `orderId` | string | Yes | OrderId identifier |

### Response

**Success:**
```typescript
{
  success,
  order_id,
  summary,
  timeline,
  jobs,
  errors,
}
```

**Error (500):**
```typescript
{
  success,
  error,
}
```

### Example Request

```bash
curl -X GET 'https://your-store.omnicart.cc/admin/sync-engine/audit/history/:orderId' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'
```

---

## GET Admin Sync-engine Errors

**Endpoint:** `GET /admin/sync-engine/errors`
**Authentication:** Admin (Required)

### Response

**Success:**
```typescript
{
  success,
  errors,
  pagination,
}
```

**Error (500):**
```typescript
{
  success,
  error,
}
```

### Example Request

```bash
curl -X GET 'https://your-store.omnicart.cc/admin/sync-engine/errors' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'
```

---

## POST Admin Sync-engine Errors :id Resolve

**Endpoint:** `POST /admin/sync-engine/errors/:id/resolve`
**Authentication:** Admin (Required)

### URL Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Id identifier |

### Request Body

This route does not declare a validation schema, so the accepted fields are not derivable from the source. Check the handler before relying on a particular body.

### Response

**Success:**
```typescript
{
  success,
  error_id,
}
```

**Error (500):**
```typescript
{
  success,
  error,
}
```

### Example Request

```bash
curl -X POST 'https://your-store.omnicart.cc/admin/sync-engine/errors/:id/resolve' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'
```

---

## GET Admin Sync-engine Jobs

**Endpoint:** `GET /admin/sync-engine/jobs`
**Authentication:** Admin (Required)

### Response

**Success:**
```typescript
{
  success,
  jobs,
  pagination,
}
```

**Error (500):**
```typescript
{
  success,
  error,
}
```

### Example Request

```bash
curl -X GET 'https://your-store.omnicart.cc/admin/sync-engine/jobs' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'
```

---

## POST Admin Sync-engine Jobs :id Cancel

**Endpoint:** `POST /admin/sync-engine/jobs/:id/cancel`
**Authentication:** Admin (Required)

### URL Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Id identifier |

### Request Body

This route does not declare a validation schema, so the accepted fields are not derivable from the source. Check the handler before relying on a particular body.

### Response

**Success:**
```typescript
{
  success,
  job,
}
```

**Error (500):**
```typescript
{
  success,
  error,
}
```

### Example Request

```bash
curl -X POST 'https://your-store.omnicart.cc/admin/sync-engine/jobs/:id/cancel' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'
```

---

## POST Admin Sync-engine Jobs :id Retry

**Endpoint:** `POST /admin/sync-engine/jobs/:id/retry`
**Authentication:** Admin (Required)

### URL Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Id identifier |

### Request Body

This route does not declare a validation schema, so the accepted fields are not derivable from the source. Check the handler before relying on a particular body.

### Response

**Success:**
```typescript
{
  success,
  job,
}
```

**Error (500):**
```typescript
{
  success,
  error,
}
```

### Example Request

```bash
curl -X POST 'https://your-store.omnicart.cc/admin/sync-engine/jobs/:id/retry' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'
```

---

## GET Admin Sync-engine Providers

**Endpoint:** `GET /admin/sync-engine/providers`
**Authentication:** Admin (Required)

### Response

**Success:**
```typescript
{
  success,
  providers,
}
```

**Error (500):**
```typescript
{
  success,
  error,
}
```

### Example Request

```bash
curl -X GET 'https://your-store.omnicart.cc/admin/sync-engine/providers' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'
```

---

## POST Admin Sync-engine Providers

**Endpoint:** `POST /admin/sync-engine/providers`
**Authentication:** Admin (Required)

### Request Body

This route does not declare a validation schema, so the accepted fields are not derivable from the source. Check the handler before relying on a particular body.

### Response

**Success:**
```typescript
{
  success,
  provider,
  validation,
}
```

**Error (400):**
```typescript
{
  success,
  error,
}
```
**Error (404):**
```typescript
{
  success,
  error,
}
```
**Error (500):**
```typescript
{
  success,
  error,
}
```

### Example Request

```bash
curl -X POST 'https://your-store.omnicart.cc/admin/sync-engine/providers' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'
```

---

## POST Admin Sync-engine Providers :id Sync

**Endpoint:** `POST /admin/sync-engine/providers/:id/sync`
**Authentication:** Admin (Required)

### URL Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Id identifier |

### Request Body

This route does not declare a validation schema, so the accepted fields are not derivable from the source. Check the handler before relying on a particular body.

### Response

**Success:**
```typescript
{
  success,
  provider_id,
  summary,
}
```

**Error (404):**
```typescript
{
  success,
  error,
}
```
**Error (500):**
```typescript
{
  success,
  error,
}
```

### Example Request

```bash
curl -X POST 'https://your-store.omnicart.cc/admin/sync-engine/providers/:id/sync' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'
```

---

## POST Admin Sync-engine Providers :id Validate

**Endpoint:** `POST /admin/sync-engine/providers/:id/validate`
**Authentication:** Admin (Required)

### URL Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Id identifier |

### Request Body

This route does not declare a validation schema, so the accepted fields are not derivable from the source. Check the handler before relying on a particular body.

### Response

**Success:**
```typescript
{
  success,
  provider_id,
  is_valid,
}
```

**Error (404):**
```typescript
{
  success,
  error,
}
```
**Error (500):**
```typescript
{
  success,
  error,
}
```

### Example Request

```bash
curl -X POST 'https://your-store.omnicart.cc/admin/sync-engine/providers/:id/validate' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'
```

---

## POST Admin Sync-engine Reset-circuit-breaker

**Endpoint:** `POST /admin/sync-engine/reset-circuit-breaker`
**Authentication:** Admin (Required)

### Description

POST /admin/sync-engine/reset-circuit-breaker Reset the circuit breaker for a provider (for debugging/recovery)

### Request Body

This route does not declare a validation schema, so the accepted fields are not derivable from the source. Check the handler before relying on a particular body.

### Response

**Success:**
```typescript
{
  success,
  message,
  provider_id,
  timestamp,
}
```

**Error (500):**
```typescript
{
  success,
  error,
}
```
**Error (404):**
```typescript
{
  success,
  error,
}
```
**Error (500):**
```typescript
{
  success,
  error,
}
```
**Error (500):**
```typescript
{
  success,
  error,
}
```

### Example Request

```bash
curl -X POST 'https://your-store.omnicart.cc/admin/sync-engine/reset-circuit-breaker' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'
```

---

## POST Admin Sync-engine Sync-order

**Endpoint:** `POST /admin/sync-engine/sync-order`
**Authentication:** Admin (Required)

### Description

POST /admin/sync-engine/sync-order Sync a single order by provider order ID. By default, performs a live sync directly without job queue. Request body: { provider_id: "konnektive", order_id: "12345678", force_resync: false,  // Delete existing OmniCart order and resync update_existing: true, // Update existing order if found (default: true) use_queue: false       // Use job queue instead of live sync (default: false) }

### Request Body

This route does not declare a validation schema, so the accepted fields are not derivable from the source. Check the handler before relying on a particular body.

### Response

**Success:**
```typescript
{
  success,
  order_id,
  provider_id,
  job_id,
  mode,
  sync_result,
}
```
**Also returns:**
```typescript
{
  success,
  order_id,
  provider_id,
  mode,
  sync_result,
  updated_metadata,
}
```

**Error (400):**
```typescript
{
  success,
  error,
}
```
**Error (500):**
```typescript
{
  success,
  error,
}
```
**Error (404):**
```typescript
{
  success,
  error,
}
```
**Error (500):**
```typescript
{
  success,
  error,
}
```
**Error (409):**
```typescript
{
  success,
  error,
  enqueue_result,
}
```
**Error (500):**
```typescript
{
  success,
  error,
  job_id,
}
```
**Error (500):**
```typescript
{
  success,
  error,
}
```
**Error (404):**
```typescript
{
  success,
  error,
}
```
**Error (400):**
```typescript
{
  success,
  error,
  konnektive_status,
}
```
**Error (500):**
```typescript
{
  success,
  error,
  stack,
}
```
**Error (500):**
```typescript
{
  success,
  error,
}
```

### Example Request

```bash
curl -X POST 'https://your-store.omnicart.cc/admin/sync-engine/sync-order' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'
```

---