Integrate COD reconciliation
into your ops stack.

Try it before you subscribe.

The GET /demo endpoint runs a full reconciliation against a real sample dataset: no account, no API key, no credit card required. It uses an anonymised Shopify export and Shiprocket remittance file covering Feb–Mar 2026, with every flag type represented.

Bearer token, nothing else.

Every request must include your API key as a Bearer token in the Authorization header. Live keys are generated post-subscription from the Pro → API panel.

Authorization: Bearer pt_live_your_key_here
Content-Type: application/json

Reconcile in one call.

Pass your Shopify orders export and the courier remittance file as CSV strings. The API parses, matches, and returns a structured array of every order with its reconciliation status.

curl -X POST https://api.paytrace.in/reconcile \
  -H "Authorization: Bearer pt_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "shopify": "Name,Email,Financial Status,Paid at,Fulfillment Status,...\n#1001,...",
    "courier": "AWB No,Order ID,COD Amount,Remitted Amount,Remittance Date,...\nDEL123,...",
    "courierName": "delhivery",
    "brand": "brand_nykaa_01"
  }'

Example response

{
  "results": [
    {
      "awb": "DEL1234567890",
      "order_id": "#1082",
      "cod_amount": 899,
      "remitted": 0,
      "shortfall": 899,
      "days_overdue": 18,
      "flag": "MISSING",
      "flag_reason": "Not remitted",
      "status": "fulfilled",
      "match_mode": "awb"
    },
    {
      "awb": "DEL9876543210",
      "order_id": "#1097",
      "cod_amount": 1499,
      "remitted": 999,
      "shortfall": 500,
      "days_overdue": 0,
      "flag": "SHORT_PAID",
      "flag_reason": "Shortfall detected",
      "status": "fulfilled",
      "match_mode": "awb"
    },
    {
      "awb": "DEL5551234567",
      "order_id": "#1043",
      "cod_amount": 599,
      "remitted": 599,
      "shortfall": 0,
      "days_overdue": 0,
      "flag": "RECONCILED",
      "flag_reason": "Fully remitted",
      "status": "fulfilled",
      "match_mode": "awb"
    }
    // ... remaining results
  ]
}

{
  "error": "Could not detect AWB column in courier CSV. Expected one of: AWB No, Waybill, Tracking ID, AWB Number"
}

POST /reconcile

The primary endpoint. Accepts a Shopify CSV and a courier remittance CSV. Reconciles them order-by-order and returns every flag with shortfall and timeline data.

POST /generate-api-key

Generates a new live API key for your account. Requires an active Pro plan subscription. Any previously issued key for your account is immediately deactivated. There is always only one active key per account.

{
  "key":    "pt_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",  // full key: shown once, store immediately
  "prefix": "pt_live_a1b2c"                             // safe prefix for display / identification
}

POST /reconcile/batch

Process multiple brands in a single call. Results will be delivered via webhook or polled with GET /status/{batch_id}. Ideal for agencies running weekly reconciliations across many brands.

{
  "ok": true,
  "batch_id": "batch_b2f1a9c3_1712345678",
  "jobs": 5,
  "status": "queued",
  "estimated_completion_ms": 12000
}

GET /status/{job_id}

Poll the status of an async batch job. Will return queued, processing, or complete, with the full results payload once done. Available when POST /reconcile/batch launches.

Flag types: what each means.

Every order in the results array carries exactly one flag. Here's what each flag means and what action it implies for your clients.

Error codes.

All errors return a JSON object with a single error field containing a human-readable message string.

{ "error": "Plain English description of what went wrong" }

Rate limits.

Rate limits are per API key, enforced on a rolling 60-second window. Exceeding the limit returns a 429 and blocks the key for 5 minutes.

GET /demo limits

GET /demo is rate-limited per IP: 20 requests/minute, with a 60-second block on breach. No auth required. Returns Retry-After on a 429.

HTTP/1.1 429 Too Many Requests
Retry-After: 300   // seconds blocked (5 minutes on breach)

{ "error": "Rate limit exceeded" }

Supported couriers.

PayTrace auto-detects column names from common export formats. These are the accepted values for the courier parameter and the columns we look for in each report.

Pro integration pattern.

Most agencies integrate PayTrace into their weekly ops cadence: fetching Shopify exports per brand, pulling courier remittances, running reconciliations sequentially and surfacing flags in a Notion or Google Sheet for client review.

import requests, time

PAYTRACE_KEY = "pt_live_your_key_here"
BASE_URL      = "https://api.paytrace.in"

def run_weekly_reconciliation(brands):
    # brands = [{ brand, shopify_csv, courier_csv, courierName }, ...]
    all_flagged = []

    for b in brands:
        resp = requests.post(
            f"{BASE_URL}/reconcile",
            headers={"Authorization": f"Bearer {PAYTRACE_KEY}"},
            json={
                "shopify":     b["shopify_csv"],
                "courier":     b["courier_csv"],
                "courierName": b["courierName"],
                "brand":       b["brand"],
            }
        )
        resp.raise_for_status()
        results = resp.json()["results"]

        # Collect actionable flags for this brand
        flagged = [
            {**r, "brand": b["brand"]}
            for r in results
            if r["flag"] in ("MISSING", "SHORT_PAID", "RTO_ANOMALY", "OVERDUE")
        ]
        all_flagged.extend(flagged)

        # Be a good API citizen: small pause between brands
        time.sleep(0.5)

    return all_flagged

Webhooks.

PayTrace can POST a summary to your endpoint automatically after every reconciliation run — whether that run came from a live POST /reconcile call or from an hourly Shopify autopilot pass. This is a real, shipped feature, not on the roadmap — but it's configured from the dashboard, not from the API request itself, and it's available on the Enterprise plan only (not Pro).

Delivery: one POST per completed run, with a 5-second timeout and one automatic retry. A non-2xx response from your endpoint counts as a failed delivery. The payload is a run summary, not the full results array:

{
  "brand": "brand_nykaa_01",
  "run_at": "2026-09-28T06:00:00.000Z",
  "flagged_count": 14,
  "amount_risk": 18420,
  "run_id": "recon_a7f2c1d9_1712345678"
}

X-PayTrace-Sig: hex-encoded HMAC-SHA256 of the raw request body

White-label reports.

Both Pro and Enterprise accounts can configure a white-label profile. Your agency name and email appear on exported Excel reports and dispute letters instead of "PayTrace". This is a dashboard setting — there is no request field on POST /reconcile that sets or overrides it.