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#

GET Admin Sync-engine#

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

Response#

Success:

{
  success,
  providers,
  metrics,
}

Error (500):

{
  success,
  error,
}

Example Request#

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:

{
  success,
  date_range,
  provider_id,
  validation_rules,
  report,
  results,
}

Error (500):

{
  success,
  error,
}

Example Request#

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#

Response#

Success:

{
  success,
  order_id,
  provider_id,
  provider_order,
  medusa_order,
  medusa_order_id,
  comparison,
  field_mapping,
}

Error (500):

{
  success,
  error,
}

Example Request#

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#

Response#

Success:

{
  success,
  order_id,
  summary,
  timeline,
  jobs,
  errors,
}

Error (500):

{
  success,
  error,
}

Example Request#

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:

{
  success,
  errors,
  pagination,
}

Error (500):

{
  success,
  error,
}

Example Request#

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#

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:

{
  success,
  error_id,
}

Error (500):

{
  success,
  error,
}

Example Request#

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:

{
  success,
  jobs,
  pagination,
}

Error (500):

{
  success,
  error,
}

Example Request#

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#

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:

{
  success,
  job,
}

Error (500):

{
  success,
  error,
}

Example Request#

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#

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:

{
  success,
  job,
}

Error (500):

{
  success,
  error,
}

Example Request#

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:

{
  success,
  providers,
}

Error (500):

{
  success,
  error,
}

Example Request#

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:

{
  success,
  provider,
  validation,
}

Error (400):

{
  success,
  error,
}

Error (404):

{
  success,
  error,
}

Error (500):

{
  success,
  error,
}

Example Request#

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#

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:

{
  success,
  provider_id,
  summary,
}

Error (404):

{
  success,
  error,
}

Error (500):

{
  success,
  error,
}

Example Request#

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#

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:

{
  success,
  provider_id,
  is_valid,
}

Error (404):

{
  success,
  error,
}

Error (500):

{
  success,
  error,
}

Example Request#

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:

{
  success,
  message,
  provider_id,
  timestamp,
}

Error (500):

{
  success,
  error,
}

Error (404):

{
  success,
  error,
}

Error (500):

{
  success,
  error,
}

Error (500):

{
  success,
  error,
}

Example Request#

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:

{
  success,
  order_id,
  provider_id,
  job_id,
  mode,
  sync_result,
}

Also returns:

{
  success,
  order_id,
  provider_id,
  mode,
  sync_result,
  updated_metadata,
}

Error (400):

{
  success,
  error,
}

Error (500):

{
  success,
  error,
}

Error (404):

{
  success,
  error,
}

Error (500):

{
  success,
  error,
}

Error (409):

{
  success,
  error,
  enqueue_result,
}

Error (500):

{
  success,
  error,
  job_id,
}

Error (500):

{
  success,
  error,
}

Error (404):

{
  success,
  error,
}

Error (400):

{
  success,
  error,
  konnektive_status,
}

Error (500):

{
  success,
  error,
  stack,
}

Error (500):

{
  success,
  error,
}

Example Request#

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