Engineering guide

SignalOps now supports a Commerce Ingestion API.

Non-Shopify merchants can now connect custom storefronts, marketplaces, ERPs, OMS tools, or warehouse exports directly to the same leak detection and recovery agent pipeline used by SignalOps connectors.

Published for developers building server-to-server commerce data integrations.

Why this exists

Many serious ecommerce businesses do not run everything through Shopify. Some sell through custom storefronts, marketplaces, regional commerce platforms, wholesale order systems, or internal ERPs. Those brands still have the same operational leaks: refund pressure, damaged product variants, weak repeat purchase behavior, bad campaign-to-SKU fit, and customer segments that need recovery.

The ingestion API lets those teams send normalized order events into SignalOps without waiting for a native connector. Once the batch is accepted, SignalOps can create an import record, run the analysis engine, generate agent recommendations, and attach the data to the merchant workspace.

How the flow works

Create an ingestion API key from a Pro SignalOps account.
Send canonical order JSON to POST /api/v1/ingest/orders.
SignalOps validates customers, order dates, totals, refunds, and line items.
The payload is converted into normalized commerce events.
If run_analysis is true, the same leak detection engine runs immediately.
The agent recommendation queue is refreshed from the new run.

This is not a separate reporting lane. API-ingested data lands in the same import history, analysis history, and action workflow used by CSV uploads and platform connectors.

Authentication

Use a merchant-scoped ingestion key. The key can be sent as a bearer token or through the dedicated header.

Authorization: Bearer sig_ingest_live_...

# or

x-signalops-ingest-key: sig_ingest_live_...

Keys are stored hashed by SignalOps. The full key is only shown once when it is created. Revoke and rotate keys from the merchant workspace or through the API key endpoints.

Canonical payload

{
  "source": "custom-storefront",
  "source_name": "Acme Commerce API",
  "segment": "shopify-5k-25k",
  "run_analysis": true,
  "orders": [
    {
      "external_order_id": "ORD-10045",
      "ordered_at": "2026-07-16T10:42:00Z",
      "currency": "USD",
      "order_total": 129.98,
      "refund_total": 64.99,
      "customer": {
        "external_customer_id": "cust_8841",
        "email": "buyer@example.com",
        "first_name": "Ada"
      },
      "line_items": [
        {
          "sku": "SHOE-BLK-42",
          "product_id": "prod_shoe",
          "variant_id": "var_black_42",
          "product_name": "Runner Shoe",
          "variant_name": "Black / 42",
          "quantity": 2,
          "unit_price": 64.99,
          "refund_total": 64.99,
          "refunded_quantity": 1
        }
      ],
      "campaign_id": "google:campaign:8172",
      "campaign_name": "July performance push",
      "campaign_source": "google_ads",
      "tags": ["first_purchase"],
      "metadata": {
        "warehouse": "Lagos DC",
        "source_order_status": "partially_refunded"
      }
    }
  ]
}

Field guide

Field	Required	Purpose
`external_order_id`	Yes	Deduplicates and traces each order back to the merchant system.
`ordered_at`	Yes	Powers cohort, trend, and follow-up run comparison.
`customer.external_customer_id` or `email`	Yes	Required for repeat purchase and customer segment detection.
`order_total`	No	If absent, SignalOps sums line-item revenue.
`refund_total`	No	If absent, SignalOps sums line-item refund amounts.
`line_items`	No	Required for product, SKU, and variant-level leak detection.
`campaign_id`	No	Useful for attribution and evidence when recommendations are tied to paid or lifecycle campaigns.

Response shape

{
  "status": "accepted",
  "message": "Commerce data ingested and analyzed.",
  "import_run": {
    "import_id": 42,
    "source_name": "Acme Commerce API",
    "source_type": "api",
    "order_count": 1842,
    "customer_count": 991,
    "product_count": 128,
    "linked_analysis_run_id": 77
  },
  "analysis": {
    "run_id": 77,
    "summary": "Refund rate increased while repeat purchase rate weakened..."
  },
  "recommendations_synced": true
}

Operational guidance

Batching

Send batches by time window, not by single order. Hourly, six-hour, or daily batches usually give the agent enough context to detect movement without creating noise.

Idempotency

SignalOps hashes the request payload and reuses a matching analysis result for the same merchant, segment, and payload. Keep retries byte-stable when possible.

Privacy

Payment card details, passwords, and unnecessary profile fields should never be sent. For retention analysis, SignalOps needs stable customer identity, timestamps, order value, refund value, and product/variant context.

Missing connectors

If a merchant does not use Shopify, this API becomes the commerce connector. If they do not use Google Ads or Klaviyo, SignalOps still analyzes the commerce data and can use whatever connectors are present for execution and follow-up.

For best product-level recovery, include line items with SKU or variant IDs. Order-only ingestion can still detect store-level leakage, but it cannot isolate faulty products with the same confidence.