REST API Reference

1. Basics

The API serves Sublyra's local mirror of your subscription data — Shopify remains the source of truth, and inbound Shopify webhooks keep the mirror in step. Reads are fast, consistent and never rate-limited by Shopify's own API.

2. Pagination

All three endpoints share the same cursor pagination:

Every response carries a page object:

{
  "data": [ … ],
  "page": {
    "limit": 50,
    "nextCursor": "2026-08-01T12:00:00.000Z~clx9k2m4p0001…"
  }
}

When nextCursor is null, you're on the last page. When it's a string, pass it back as ?cursor= to get the next page:

curl "https://app.sublyra.com/api/v1/subscriptions?limit=250&cursor=2026-08-01T12%3A00%3A00.000Z~clx9k2m4p0001" \
  -H "Authorization: Bearer cad_pk_your_key_here"

Pages are ordered newest-first by each resource's date field (startedAt for subscriptions, createdAt for customers, billedAt for orders). The cursor is compound — <ISO date>~<id> — so rows that share a timestamp are never skipped or duplicated between pages.

3. GET /api/v1/subscriptions

Lists your subscription contracts, newest startedAt first.

curl "https://app.sublyra.com/api/v1/subscriptions?limit=50" \
  -H "Authorization: Bearer cad_pk_your_key_here"

Response

{
  "data": [
    {
      "id": "clx9k2m4p0001abcd",
      "shopifyId": "gid://shopify/SubscriptionContract/1001",
      "customerId": "clx9k2m4p0002efgh",
      "status": "ACTIVE",
      "interval": "MONTH",
      "intervalCount": 1,
      "sellingPlanId": "gid://shopify/SellingPlan/2001",
      "lines": [
        {
          "variantId": "gid://shopify/ProductVariant/3001",
          "productId": "gid://shopify/Product/4001",
          "title": "House Blend — 1kg",
          "quantity": 2,
          "unitPriceCents": 2100
        }
      ],
      "nextBillingDate": "2026-09-01T00:00:00.000Z",
      "cyclesCompleted": 3,
      "startedAt": "2026-06-01T09:30:00.000Z",
      "cancelledAt": null
    }
  ],
  "page": { "limit": 50, "nextCursor": null }
}

Fields

4. GET /api/v1/customers

Lists customers known to Sublyra — your subscribers and their loyalty state — newest createdAt first.

curl "https://app.sublyra.com/api/v1/customers?limit=50" \
  -H "Authorization: Bearer cad_pk_your_key_here"

Response

{
  "data": [
    {
      "id": "clx9k2m4p0002efgh",
      "shopifyId": "gid://shopify/Customer/5001",
      "email": "jane@example.com",
      "firstName": "Jane",
      "lastName": "Doe",
      "marketingConsent": true,
      "creditsCents": 750,
      "loyaltyTier": 1,
      "subscriptionCount": 2,
      "createdAt": "2026-06-01T09:28:00.000Z"
    }
  ],
  "page": { "limit": 50, "nextCursor": null }
}

Fields

5. GET /api/v1/orders

Lists subscription orders — both checkout (first) orders and recurring renewals — newest billedAt first.

curl "https://app.sublyra.com/api/v1/orders?limit=50" \
  -H "Authorization: Bearer cad_pk_your_key_here"

Response

{
  "data": [
    {
      "id": "clx9k2m4p0003ijkl",
      "shopifyId": "gid://shopify/Order/6001",
      "contractId": "clx9k2m4p0001abcd",
      "customerId": "clx9k2m4p0002efgh",
      "source": "recurring",
      "cycleNumber": 3,
      "status": "PAID",
      "lines": [
        {
          "variantId": "gid://shopify/ProductVariant/3001",
          "productId": "gid://shopify/Product/4001",
          "title": "House Blend — 1kg",
          "quantity": 2,
          "unitPriceCents": 2100
        }
      ],
      "subtotalCents": 4200,
      "discountCents": 420,
      "creditsCents": 0,
      "totalCents": 3780,
      "billedAt": "2026-08-01T00:01:00.000Z"
    }
  ],
  "page": { "limit": 50, "nextCursor": null }
}

Fields

6. Errors

Every error — including unexpected server failures — is JSON with a stable, machine-readable code:

{
  "error": {
    "code": "bad_cursor",
    "message": "Malformed cursor. Pass the nextCursor value from the previous page verbatim."
  }
}

7. Read-only by design

The public API has no write surface at all — there is no POST to create a contract and no DELETE to cancel one. That's deliberate:

• Shopify is the source of truth. Subscriptions are created in checkout and changed through the customer portal or the Sublyra admin, so every change flows through Shopify's own billing and notification machinery.
• A leaked key can't hurt your store. The worst case of a compromised read-only key is data exposure, not fraudulent subscriptions or mass cancellations.

To react to changes instead of polling, subscribe to outbound webhooks; to automate inside Shopify, use the Flow triggers.