Cubbie API

Build integrations that feed Cubbie, extend Cubbie, and distribute Cubbie-powered partner surfaces without replacing the Cubbie dashboard.

Dashboard-first API strategy

Cubbie APIs are designed to make the Cubbie workspace more useful, not to white-label the full marketplace somewhere else. Use the API to ingest stack data, automate partner and vendor operations, send signed events, and deep-link users back into Cubbie for comparison, redemption, renewal, and procurement workflows.

API Surfaces

Buyer stack ingestion

Send subscriptions, usage, seat, renewal, and spend signals into Cubbie so the Cubbie dashboard remains the source of truth.

Advisor + renewal outputs

Trigger analyses and read recommendation summaries for notifications, while deep-linking users back into Cubbie for decisions.

Partner-program distribution

Install Cubbie-powered hosted pages, widgets, and custom-domain surfaces without hiding that Cubbie powers the perks experience.

Vendor + partner webhooks

Subscribe systems to signed events such as redemptions, orders, payouts, referrals, and account updates.

What We Intentionally Do Not Expose

Cubbie does not provide an unrestricted public API to clone the entire catalog, deals marketplace, rankings, or recommendation experience off-platform. Partner surfaces return Cubbie-hosted URLs, embeds, scripts, and attribution-safe JSON where appropriate, with Cubbie branding and links back to the workspace.

Current Launch Surface

The developer platform is intentionally split by use case: public v1 REST for stack ingestion and Cubbie workspace workflows, partner-program APIs for perks distribution, and vendor webhook tooling for event automation.

Surface	Route	Status	What It Does
Public v1 REST	`/api/v1/*`	Available	API-key authenticated buyer stack, advisor, renewal, and partner-program discovery. Credits endpoints use separate ck_ tokens.
OpenAPI contract	`/api/v1/openapi.json`	Available	Machine-readable OpenAPI 3.1 schema for the public v1 REST surface.
Partner programs	`/api/partner-programs/*`	Available	Dashboard-created perks programs with hosted pages, embeds, custom domains, public JSON, referrals, and click tracking.
Vendor webhooks	`/api/vendor/webhooks/*`	Dashboard authenticated	Self-serve vendor endpoint registration, signed deliveries, retries, delivery logs, and secret rotation.
OAuth client credentials	`/api/oauth/token`	Infrastructure ready	Server-to-server token issuance exists for approved clients; public app registration is not exposed yet.

Authentication

Public v1 stack, advisor, renewal, and partner-program endpoints require a cb_live_... API key. You can create one from your Buyer Dashboard under the "API Keys" section. Cubbie Credits endpoints use separate ck_... credit tokens, and vendor webhooks are managed inside the authenticated vendor dashboard.

Getting an API Key

Scroll to the "API Keys" section and click "Create New Key."
Copy the key immediately -- it is shown only once.

Authenticating Requests

Pass the key in the Authorization header:

Authorization: Bearer cb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys follow the format cb_live_ followed by 32 hex characters. Keep your keys secret and never commit them to source control.

Scopes

API keys are scope-limited. Create the narrowest key possible for each integration.

Scope	Purpose
`subscriptions:read`	Read the buyer organization's Cubbie stack registry.
`subscriptions:write`	Create, update, delete, or bulk import stack registry records.
`usage:write`	Send utilization, seat, and activity signals into Cubbie.
`renewals:read`	Read upcoming renewal windows for notifications and deep links.
`advisor:read`	Read current Cubbie advisor recommendations.
`advisor:write`	Trigger Cubbie advisor analyses.
`partner_programs:read`	Read partner-program surfaces, URLs, and install snippets.
`partner_programs:write`	Reserved for programmatic partner-program administration.
`webhooks:read`	Reserved for reading webhook endpoint and delivery status.
`webhooks:write`	Reserved for creating and managing webhook endpoints.

Base URLs

Surface	Base
Public v1 REST	`https://cubbie.com/api/v1`
Partner-program public surfaces	`https://cubbie.com/api/partner-programs/public/:slug`
Vendor webhook management	`https://cubbie.com/api/vendor/webhooks`
OAuth token issuance	`https://cubbie.com/api/oauth/token`

All endpoints return JSON with the shape { "ok": true, "data": ... } on success or { "ok": false, "error": { "message": "..." } } on failure.

Partner Programs

Partner programs are the API-backed perks surfaces companies create from Cubbie to power pages like perks.example.com, dashboard embeds, and curated sponsorship panels. The Cubbie dashboard remains the setup workspace: partners create the program, select perks, configure branding, add allowed embed origins, and connect custom domains.

The public API exposes installable outputs for those programs: hosted page URLs, iframe URLs, script snippets, and attribution-safe JSON URLs. This gives partners distribution without turning Cubbie into an invisible white-label catalog.

Endpoint	Purpose
`POST /api/v1/partner-programs`	Create a Cubbie-powered perks, referral, or hybrid partner program.
`PATCH /api/v1/partner-programs/:id`	Update branding, audience copy, access mode, embedded layout, and curated selection rules.
`POST /api/v1/partner-programs/:id/domains`	Attach a custom perks subdomain and return the DNS verification instructions.
`POST /api/v1/partner-programs/:id/assets`	Publish FAQs, announcements, benefits, and resources into the partner surface.
`GET /api/v1/partner-programs/:id/referrals`	Read partner referral leads captured by hosted pages and embeds.

Vendor Webhooks

Vendors can register webhook endpoints from the vendor dashboard to receive signed event deliveries. Cubbie signs each delivery with HMAC-SHA256 and sends X-Cubbie-Signature, X-Cubbie-Timestamp, and X-Cubbie-Event-Id headers.

Failed deliveries retry after 1 minute, 5 minutes, 30 minutes, 2 hours, and 12 hours. After repeated failures, endpoints are temporarily disabled to protect both systems.

Supported vendor events

deal.created
deal.redeemed
deal.expired
order.completed
order.refunded
subscription.cancelled
subscription.renewed
payout.released
payout.failed
review.received
vendor.account_updated

OpenAPI

Use the OpenAPI schema to generate typed clients, validate requests in tests, or import the API into tools like Postman and Scalar.

https://cubbie.com/api/v1/openapi.json

Prefer a ready-to-import collection? Use https://cubbie.com/api/v1/postman.json.

API Explorer

Test public v1 calls from your browser. Keys stay in this page state and are not stored.

RequestAPI Key

GET /api/v1/health

Endpoints

GET/api/v1/health

Health check. No authentication required.

Example Request

curl https://cubbie.com/api/v1/health

Example Response

{
  "ok": true,
  "data": {
    "status": "ok",
    "version": "1.0.0",
    "timestamp": "2026-03-29T12:00:00.000Z"
  }
}

GET/api/v1/openapi.json

OpenAPI 3.1 contract for the public v1 API. No authentication required.

Example Request

curl https://cubbie.com/api/v1/openapi.json

Example Response

{
  "openapi": "3.1.0",
  "info": {
    "title": "Cubbie Public API",
    "version": "1.0.0"
  }
}

GET/api/v1/subscriptions

List all subscriptions for your organization.

Example Request

curl -H "Authorization: Bearer cb_live_xxxx" \
  https://cubbie.com/api/v1/subscriptions

Example Response

{
  "ok": true,
  "data": {
    "items": [
      {
        "id": "uuid",
        "vendor_name": "Slack",
        "product_name": "Slack Business+",
        "annualized_spend_cents": 1440000,
        "renewal_date": "2027-01-15",
        "status": "active"
      }
    ]
  }
}

POST/api/v1/subscriptions

Add a subscription to your stack registry.

Example Request

curl -X POST \
  -H "Authorization: Bearer cb_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"vendor_name":"Slack","product_name":"Slack Business+","annualized_spend_cents":1440000,"renewal_date":"2027-01-15"}' \
  https://cubbie.com/api/v1/subscriptions

Example Response

{
  "ok": true,
  "data": {
    "id": "uuid",
    "vendor_name": "Slack",
    "product_name": "Slack Business+",
    "annualized_spend_cents": 1440000,
    "status": "active"
  }
}

GET/api/v1/subscriptions/:id

Retrieve a single subscription by its ID.

Example Request

curl -H "Authorization: Bearer cb_live_xxxx" \
  https://cubbie.com/api/v1/subscriptions/UUID

Example Response

{
  "ok": true,
  "data": {
    "id": "uuid",
    "vendor_name": "Slack",
    "product_name": "Slack Business+",
    "annualized_spend_cents": 1440000,
    "renewal_date": "2027-01-15",
    "status": "active"
  }
}

PATCH/api/v1/subscriptions/:id

Update fields on an existing subscription.

Example Request

curl -X PATCH \
  -H "Authorization: Bearer cb_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"annualized_spend_cents":1600000}' \
  https://cubbie.com/api/v1/subscriptions/UUID

Example Response

{
  "ok": true,
  "data": {
    "id": "uuid",
    "vendor_name": "Slack",
    "product_name": "Slack Business+",
    "annualized_spend_cents": 1600000,
    "status": "active"
  }
}

DELETE/api/v1/subscriptions/:id

Delete a subscription from your stack registry.

Example Request

curl -X DELETE \
  -H "Authorization: Bearer cb_live_xxxx" \
  https://cubbie.com/api/v1/subscriptions/UUID

Example Response

{
  "ok": true,
  "data": { "deleted": true }
}

POST/api/v1/subscriptions/bulk

Bulk import up to 500 subscriptions at once.

Example Request

curl -X POST \
  -H "Authorization: Bearer cb_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"vendor_name":"Slack","product_name":"Slack Business+","annualized_spend_cents":1440000}]}' \
  https://cubbie.com/api/v1/subscriptions/bulk

Example Response

{
  "ok": true,
  "data": { "created": 1, "failed": 0, "errors": [] }
}

POST/api/v1/advisor/analyze

Trigger a full stack analysis for your organization. Returns gap analysis, benchmarks, and recommendations.

Example Request

curl -X POST \
  -H "Authorization: Bearer cb_live_xxxx" \
  https://cubbie.com/api/v1/advisor/analyze

Example Response

{
  "ok": true,
  "data": {
    "id": "uuid",
    "gaps": [...],
    "recommendations": [...]
  }
}

GET/api/v1/advisor/recommendations

Retrieve current recommendations. Supports optional query params: status, priority.

Example Request

curl -H "Authorization: Bearer cb_live_xxxx" \
  https://cubbie.com/api/v1/advisor/recommendations

Example Response

{
  "ok": true,
  "data": {
    "items": [
      {
        "id": "uuid",
        "type": "add",
        "category": "project-management",
        "priority": "high",
        "title": "Add a project management tool",
        "rationale": "..."
      }
    ]
  }
}

POST/api/v1/usage

Report usage data for a subscription (active users, licensed seats, utilization).

Example Request

curl -X POST \
  -H "Authorization: Bearer cb_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"subscription_id":"UUID","active_users":42,"total_licensed_seats":50,"utilization_pct":84}' \
  https://cubbie.com/api/v1/usage

Example Response

{
  "ok": true,
  "data": {
    "id": "uuid",
    "created_at": "2026-03-29T12:00:00.000Z"
  }
}

GET/api/v1/renewals/upcoming

Renewal calendar — upcoming subscription renewals in a configurable window. Sorted ascending so the earliest-due rows surface first.

Example Request

curl -H "Authorization: Bearer cb_live_xxxx" \
  "https://cubbie.com/api/v1/renewals/upcoming?days=90&status=active&includePast=false"

Example Response

{
  "ok": true,
  "data": {
    "window": {
      "startsAt": "2026-05-08T00:00:00.000Z",
      "endsAt": "2026-08-06T23:59:59.999Z",
      "days": 90,
      "includePast": false
    },
    "items": [
      {
        "id": "uuid",
        "vendor_name": "Acme",
        "product_name": "Acme Pro",
        "renewal_date": "2026-06-01",
        "days_until_renewal": 24,
        "annualized_spend_cents": 1200000,
        "status": "active",
        "source": "sso"
      }
    ],
    "totals": { "count": 1, "total_annualized_spend_cents": 1200000 }
  }
}

GET/api/v1/partner-programs

List Cubbie-powered partner program surfaces: hosted page URLs, embed URLs, script snippets, JSON URLs, state, and perk counts.

Example Request

curl -H "Authorization: Bearer cb_live_xxxx" \
  https://cubbie.com/api/v1/partner-programs

Example Response

{
  "ok": true,
  "data": {
    "items": [
      {
        "id": "uuid",
        "name": "50Pros Agency Perks",
        "slug": "50pros-agency-perks",
        "state": "active",
        "perk_count": 24,
        "urls": {
          "hostedPageUrl": "https://perks.50pros.com",
          "embedWidgetUrl": "https://perks.50pros.com/embed",
          "jsonApiUrl": "https://www.cubbie.com/api/partner-programs/public/50pros-agency-perks"
        }
      }
    ]
  }
}

GET/api/v1/credits/balance

Cubbie Credits wallet — current balance, pending credits awaiting reward fulfillment, and lifetime totals.

Example Request

curl -H "Authorization: Bearer ck_xxxx" \
  https://cubbie.com/api/v1/credits/balance

Example Response

{
  "ok": true,
  "data": {
    "available_cents": 12500,
    "pending_cents": 3400,
    "lifetime_earned_cents": 38900,
    "lifetime_redeemed_cents": 0
  }
}

GET/api/v1/credits/ledger

Cubbie Credits ledger — append-only history of every credit issued, redeemed, expired, or adjusted.

Example Request

curl -H "Authorization: Bearer ck_xxxx" \
  "https://cubbie.com/api/v1/credits/ledger?limit=50"

Example Response

{
  "ok": true,
  "data": {
    "entries": [
      {
        "id": "uuid",
        "kind": "earn",
        "amount_cents": 1200,
        "balance_after_cents": 12500,
        "source_type": "order",
        "source_id": "uuid",
        "created_at": "2026-05-01T17:32:00.000Z"
      }
    ],
    "next_cursor": null
  }
}

Error Handling

Errors return a non-2xx status code and a JSON body with the error details:

{
  "ok": false,
  "error": {
    "message": "Unauthorized",
    "details": null
  }
}

Status	Meaning
`400`	Invalid request body or parameters
`401`	Missing or invalid API key
`403`	Valid key but insufficient permissions
`404`	Resource not found
`429`	Rate limit exceeded
`500`	Internal server error

Rate Limits

Default public v1 limits are 10 requests per second, 600 requests per minute, and 25,000 requests per day per API key. When a limit is exceeded, the API returns a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait before retrying. Higher quotas are available on request -- email api@cubbie.com with your use case.

SDKs

REST is the stable public interface today. JavaScript, TypeScript, Python, Ruby, Go, PHP, and Java can all use the same HTTP API now; official packaged SDKs should be generated from the OpenAPI contract as the public developer platform matures. If you need an official package ahead of public release, email api@cubbie.com.

JavaScript / TypeScript quick start

const response = await fetch("https://cubbie.com/api/v1/subscriptions", {
  headers: {
    Authorization: `Bearer ${process.env.CUBBIE_API_KEY}`
  }
});

if (!response.ok) {
  throw new Error(await response.text());
}

console.log(await response.json());

Python quick start

import os
import requests

response = requests.get(
    "https://cubbie.com/api/v1/subscriptions",
    headers={"Authorization": f"Bearer {os.environ['CUBBIE_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Ruby quick start

require "json"
require "net/http"
require "uri"

uri = URI("https://cubbie.com/api/v1/subscriptions")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch('CUBBIE_API_KEY')}"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

raise response.body unless response.is_a?(Net::HTTPSuccess)
puts JSON.parse(response.body)

Language	Status
Node.js / TypeScript	REST available now; official SDK planned
Python	REST available now; official SDK planned
Ruby	REST available now; official SDK planned
Go / PHP / Java	REST available now; official SDK planned
HTTP (any client)	Available now