Skip to main content

Build an Adapter

Adapters are how providers plug into the Subscriberbot network. This guide walks through the developer experience for building one. Read the Adapter Framework overview first.

When to build an adapter​

You build an adapter when you want your service to be a first-class citizen of the network — enabling one-click subscribe/cancel, real-time relationship sync, and inbox integration — rather than relying only on AI-assisted discovery.

1. Declare your adapter​

An adapter is a small package that declares which capabilities it supports.

// adapter.json
{
  "adapter": "acme",
  "provider": "Acme Inc.",
  "version": "1.0.0",
  "capabilities": [
    "identity.link",
    "relationship.sync",
    "lifecycle.cancel",
    "lifecycle.changePlan",
    "billing.invoices",
    "comms.inbox"
  ]
}

2. Implement the contract​

Each declared capability maps to a handler. The platform calls your handlers; your handlers translate to and from your provider's own API.

import { defineAdapter } from "@subscriberbot/adapter-sdk";

export default defineAdapter({
  // Link a Subscriberbot identity to an Acme account.
  async linkIdentity({ identity, credentials }) {
    const account = await acme.connect(credentials);
    return { providerAccountId: account.id };
  },

  // Report the user's active relationships.
  async syncRelationships({ providerAccountId }) {
    const subs = await acme.listSubscriptions(providerAccountId);
    return subs.map((s) => ({
      externalId: s.id,
      plan: { name: s.plan, price: s.price, interval: s.interval },
      renewalDate: s.renewsAt,
      entitlements: s.features,
    }));
  },

  // Execute a cancellation first-party.
  async cancel({ externalId }) {
    await acme.cancel(externalId);
    return { status: "CANCELLED" };
  },
});

3. Map to domain entities​

Your job as an adapter author is to express your service in Subscriberbot's vocabulary — Provider, Relationship, Plan, Entitlement, Payment Instrument, Communication Channel. The platform handles the graph, the events, and the AI from there.

4. Graceful degradation​

Declare only the capabilities you actually support. If you omit relationship.sync, the Discovery Agent falls back to AI-assisted discovery; if you omit lifecycle.cancel, the Concierge guides the user through manual cancellation. Adapters never have to be all-or-nothing.

5. Publish​

Once validated, your adapter is published to the network and your service becomes available for one-click management and richer discovery. Catalog metadata you publish (plans, features) flows into the Discovery Marketplace.

Environment selection

Adapter development can target production, alpha, or local gateways. Set BURDENOFF_ENV=local|alpha when testing against non-prod endpoints. See Environment Selection for endpoint details.