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 Delhivery 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 Agency → 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 agency account. Requires an active Agency 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.

Agency 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.

Outbound webhooks — where PayTrace POSTs results to your endpoint on job completion — are planned for release alongside the batch endpoint.

When webhooks ship, the payload schema will look like this:

{
  "event": "reconciliation.complete",
  "job_id": "recon_a7f2c1d9_1712345678",
  "brand": "brand_nykaa_01",
  "results": [ /* same as /reconcile response results array */ ],
  "signature": "sha256=abc123..."  // HMAC-SHA256 of payload body using your API key
}

White-label reports.

Agency plan accounts can configure a white-label profile. Your agency name and email appear on all exported Excel reports and dispute letters instead of "PayTrace". Set it once via the dashboard or via API.