Developer Docs

Affinsy API Reference

Push order data, trigger MBA or RFM reports, and retrieve results programmatically. Perfect for integrating Affinsy into your data pipeline.

Base URL: https://www.affinsy.com/api/v1OpenAPI Spec (JSON)

Authentication

All endpoints require a Bearer token. Generate API keys in Dashboard → Integrations. API access requires the Max plan or higher.

curl https://www.affinsy.com/api/v1/datasets \
  -H "Authorization: Bearer afn_your_key_here"

Limits & Throughput

Affinsy is built for high-volume ingest — millions of orders per dataset is the expected case. Stay within the limits below and throughput stays predictable.

Limit	Value	Notes
Line items per request	10,000	`POST /data/orders`. Pack whole orders — don’t split a single `order_id`’s line items across requests.
Requests per minute	60	Per user (across all API keys). Headers `X-RateLimit-Limit` / `X-RateLimit-Remaining` on every response. Over quota returns `429` with `Retry-After`.
Concurrent ingest requests	≤ 2	Recommended in-flight requests per API key for `POST /data/orders`. At this concurrency we’ve measured ~1,300 line items/sec sustained with zero errors. Higher concurrency may return `504` while the import still completes — back off and retry.
Stored orders	Plan-based	Free / Pro / Max / Enterprise tiers each have a row-count cap. New inserts may be blocked once exceeded; updates always succeed. Check `warning` field on the response.
Request timeout	30 s	A full 10,000-row batch typically completes in 13–18 s at concurrency ≤ 2.

Loading millions of rows

Batch up to 10,000 line items per call and run two workers in parallel. Upserts are keyed on (order_id, product_name), so re-sending a batch is safe — it updates rather than duplicates. At the recommended concurrency, 1 M line items takes roughly 13 minutes.

Error format

5xx responses include a request_id (UUID). Quote it in any support ticket — the full server-side error is logged against that ID.

{
  "error": "Failed to import data.",
  "request_id": "8b3a1c7e-9d2f-4a5b-b8e1-2f6c0a1d4e7b"
}

Quick Start: The Automation Loop

The full automation flow in 4 steps: push data, trigger a report, receive a webhook, fetch results.

Push order data

curl -X POST https://www.affinsy.com/api/v1/data/orders \
  -H "Authorization: Bearer afn_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "dataset_id": "my-store",
    "orders": [
      {
        "order_id": "ORD-1001",
        "customer_id": "CUST-42",
        "order_date": "2025-03-15T10:30:00Z",
        "line_items": [
          { "product_name": "Running Shoes", "unit_price": 129.99, "quantity": 1 },
          { "product_name": "Sport Socks 3-Pack", "unit_price": 14.99, "quantity": 2 }
        ]
      }
    ]
  }'

Trigger a report

Use a template for pre-configured settings, or specify params manually.

# Using a template (simplest)
curl -X POST https://www.affinsy.com/api/v1/reports \
  -H "Authorization: Bearer afn_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "high_value_baskets",
    "dataset_id": "my-store",
    "webhook_url": "https://your-server.com/hooks/affinsy"
  }'

# Or with full control over parameters
curl -X POST https://www.affinsy.com/api/v1/reports \
  -H "Authorization: Bearer afn_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "report_type": "MBA",
    "name": "Q1 2025 Bundle Analysis",
    "dataset_id": "my-store",
    "webhook_url": "https://your-server.com/hooks/affinsy",
    "filters": {
      "dateRange": { "start": "2025-01-01", "end": "2025-03-31" }
    },
    "params": {
      "min_support": 0.02,
      "min_confidence": 0.15,
      "scope": "order",
      "customer_scope": "high_value"
    }
  }'

# Response: { "report_id": "abc123", "status": "Processing" }

Receive webhook (or poll)

# Affinsy POSTs to your webhook_url:
{
  "event": "report.completed",
  "report_id": "abc123",
  "report_type": "MBA",
  "status": "Completed",
  "timestamp": "2025-03-15T10:32:00Z"
}

Fetch results

curl https://www.affinsy.com/api/v1/reports/abc123 \
  -H "Authorization: Bearer afn_your_key"

# Returns full report with association rules, AI insights, etc.

Report Templates

Templates pre-configure analysis settings for common use cases. Pass a template ID instead of manually setting report_type and params. You can still override any param — explicit values take precedence.

Template ID	Type	Description	Customer Scope
standard_mba	MBA	All orders — full cross-sell & bundling insights	all
first_order	MBA	Gateway products that win new customers	first_order
repeat_purchase	MBA	What keeps customers coming back	repeat
high_value_baskets	MBA	What your top 20% by spend buy together	high_value
churning_analysis	MBA	Win-back campaigns from lapsed customer history	churning
standard_rfm	RFM	Segment all customers by recency, frequency, monetary	all
new_customer_cohort	RFM	Segment customers acquired in last 90 days	new_90d

Endpoints

Webhooks

Webhook: report.completed / report.failed

When a report finishes (or fails), Affinsy POSTs to the webhook_url you provided during report generation. Each request includes an X-Affinsy-Signature header for verification.

// Headers:
//   Content-Type: application/json
//   X-Affinsy-Signature: sha256=<hmac_hex>

{
  "event": "report.completed",
  "report_id": "abc123",
  "report_type": "MBA",
  "status": "Completed",
  "timestamp": "2025-03-15T10:32:00Z"
}

// Verify the signature:
// 1. Get the raw request body as a string
// 2. Compute HMAC-SHA256(body, your_api_key_hash)
// 3. Compare with the value after "sha256=" in the header