MoneyBug Shopify Billing Integrity API

Catch Shopify usage-billing mistakes before they become merchant disputes or lost revenue.

Use it when your app sends Shopify App Events for usage billing and you need a machine-readable answer to either:

1. Is this billing event safe to send?
2. Does my accepted-event ledger match Shopify's current-cycle usage?

No Shopify credentials. No repo upload. No database. No paid AI dependency.

Two billable operations

1) event_preflight — $0.005

Validate one Shopify billing event before send.

Checks include:

• exact meter-handle match
• timestamp and billing-cycle boundaries
• retry / idempotency identity
• post-uninstall timing
• attribute limits and scalar values
• quoted fractional billing values
• zero-value mistakes
• PII and secret-like field risk

Typical result:

{
  "operation": "event_preflight",
  "status": "PASS",
  "findingCount": 0
}

2) reconcile_cycle — $0.02

Compare your immutable app-side accepted-event ledger with Shopify current-cycle aggregate usage.

Returns:

• MATCH
• UNDER_REPORTED
• OVER_REPORTED
• DUPLICATE_RISK
• CYCLE_DRIFT

If the totals differ but public Shopify evidence cannot identify the exact rejected event, MoneyBug returns UNLOCATABLE_PLATFORM_GAP instead of guessing.

Typical result:

{
  "operation": "reconcile_cycle",
  "status": "PASS",
  "reconciliationStatus": "MATCH",
  "expectedQuantity": 3,
  "shopifyQuantity": 3,
  "delta": 0
}

Quick start: preflight one event

{
  "mode": "event_preflight",
  "apiVersion": "2026-10",
  "meterHandles": ["api_calls"],
  "event": {
    "shop_id": "gid://shopify/Shop/12345",
    "event_handle": "api_calls",
    "timestamp": "2026-10-09T09:00:00Z",
    "idempotency_key": "usage-0001",
    "attributes": {
      "value": 1
    }
  }
}

Quick start: reconcile one cycle

{
  "mode": "reconcile_cycle",
  "meterHandle": "api_calls",
  "currentBillingCycle": {
    "startTime": "2026-10-01T00:00:00Z",
    "endTime": "2026-11-01T00:00:00Z"
  },
  "sentEvents": [
    {
      "logicalEventId": "usage-001",
      "idempotencyKeyHash": "hash-001",
      "timestamp": "2026-10-05T10:00:00Z",
      "value": 1,
      "transportAccepted": true
    },
    {
      "logicalEventId": "usage-002",
      "idempotencyKeyHash": "hash-002",
      "timestamp": "2026-10-06T10:00:00Z",
      "value": 2,
      "transportAccepted": true
    }
  ],
  "shopifyUsage": {
    "quantity": 3,
    "cost": 0.3,
    "currency": "USD"
  }
}

Good fits

• Shopify apps using usage-based or percentage billing
• CI / release checks before billing changes
• retry and idempotency regression tests
• merchant billing support investigations
• automated finance / billing reconciliation jobs
• AI agents that need a bounded PASS / WARNING / FAIL before emitting a billing event

Pricing

• event_preflight: $0.005 per usable preflight
• reconcile_cycle: $0.02 per usable shop + meter + billing-cycle reconciliation
• Platform usage included
• Invalid top-level input is not charged

Privacy and safety

• No Shopify credentials required
• No repository upload
• No persistence beyond normal Apify run artifacts
• Raw idempotency keys are never echoed; output uses a short SHA-256-derived hash
• Obvious credential-shaped attributes are blocked
• PII detection is conservative and heuristic
• MoneyBug never claims Shopify accepted, rejected, or billed an individual event unless the caller supplies evidence that proves it

Assurance boundary

MoneyBug does not:

• call Shopify on your behalf
• scrape Dev Dashboard
• resend events
• auto-correct billing
• claim Shopify certification
• claim that a PASS proves Shopify billed an event

Current deterministic test record: 55 / 55 PASS.

This Actor is intentionally separate from MoneyBug App Events Guard and the Shopify Monetization Fingerprint Actor.