API Documentation

Integrate LedgerSpear into your Shopify app to check real-time subscription status and revenue health for any store. One API call gives you the subscription state, recent transactions, and earnings summary.

Base URL: https://api.ledgerspear.com/api/v1

Authentication

All API requests require a Bearer token passed in the Authorization header. Tokens are issued when you connect your LedgerSpear account.

curl -X GET https://api.ledgerspear.com/api/v1/apps/{appId}/stores/{domain}/health \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json"

Endpoints

GET/apps/{appId}/stores/{domain}/health

Returns the full health profile for a store — current subscription status, risk state, recent transactions, and earnings breakdown. Use this to check any store's subscription health from within your Shopify app.

Path Parameters

Parameter	Type	Description
`appId`	string	Your Shopify app ID
`domain`	string	The store's myshopify.com domain

Response

The response includes three sections: subscription details, recent transactions, and an earnings summary.

{
  "subscription": {
    "shop_name": "Cool Store",
    "plan_name": "Pro",
    "risk_state": "SAFE",
    "status": "ACTIVE"
  },
  "transactions": [ ... ],
  "earnings": {
    "pending_cents": 0,
    "available_cents": 3920,
    "paid_out_cents": 35280
  }
}

Key Fields

subscription.risk_state

The current risk classification for this store's subscription:

SAFEAT_RISKCRITICALCHURNED

subscription.status

Shopify subscription status: ACTIVE, FROZEN, CANCELLED, DECLINED

transactions[].charge_type

Type of charge: RECURRING, USAGE, ONE_TIME, REFUND

earnings

Revenue breakdown in cents — pending (not yet cleared), available (ready to pay out), and paid out (already received).

Rate Limits & Versioning

Rate Limits

Requests100 req/min
Burst limit20 req/sec

Versioning

The API is versioned via URL path. The current version is v1.

Existing versions remain supported for at least 12 months after deprecation notice.