RefCampaign API
REST API for affiliate management, conversion attribution, and commissions.
The RefCampaign API powers the shipped public merchant surface: campaigns, affiliates, applications, commissions, conversion attribution, and dashboard summaries.
Endpoints are versioned under /api/v1/* and authenticated with a Bearer token (prefixed rc_live_ / rc_test_) issued from the dashboard. Responses follow a consistent envelope, errors return machine-readable codes, and the spec is published as OpenAPI 3.1.
Where to start
- Getting started — sign up, generate an API key, send your first request.
- Authentication — how API keys work, header format, and rotation.
- Integration / SDK — drop the official
@refcampaign/sdkpackage into a JS / TS app. - Integration / S2S postback — track conversions directly from your backend without the SDK.
- Error handling — error envelope, codes, retries.
- API reference — auto-generated, every endpoint with try-it-out.
Stability and versioning
The current public API version is v1. The URL prefix is the version contract:
public merchant API endpoints live under /api/v1/*, and the OpenAPI
document lists the supported operations. Responses do not currently include a
dedicated RefCampaign-API-Version header because the route prefix is the
authoritative version signal.
Deprecations are announced with a Deprecation HTTP header at least 90 days
before removal whenever a shipped v1 operation needs to be retired.
Public route boundaries
The public integration surface is the documented /api/v1/* merchant API plus
the explicitly documented SDK/browser endpoints and merchant webhook delivery
docs. Dashboard, admin, internal, auth, and provider webhook implementation
routes are application routes, not public API promises.
No endpoint is considered public just because it exists in the codebase. To be public, a route must be intentionally exposed, covered by the OpenAPI registry, and documented in the API reference.
Breaking changes
Breaking changes require a new version prefix or an explicit deprecation window. Examples include:
- Removing or renaming an endpoint.
- Removing a response field or changing its type or meaning.
- Renaming request fields, changing required fields, or rejecting a payload that was previously valid.
- Changing authentication, authorization, pagination, idempotency, or status-code semantics for an existing operation.
Non-breaking changes
v1 can receive compatible additions without a new version prefix. Examples
include:
- Adding a new optional request field.
- Adding a new response field.
- Adding a new endpoint under
/api/v1/*. - Adding a new error code for a new validation path while keeping the existing error envelope.
- Tightening documentation, examples, rate-limit explanations, or generated OpenAPI metadata without changing runtime behavior.
SDK compatibility
The @refcampaign/sdk SDK v1 targets API v1. Any breaking API change requires
an SDK compatibility plan before release: supported SDK versions, migration
notes, and whether old SDK versions continue to work during the deprecation
window.
Guardrails
The OpenAPI registry is the source of truth for public v1 route documentation,
and spec tests compare the documented operations with the implemented
/api/v1/* handlers. Those tests are the guardrail that prevents dashboard,
admin, internal, auth, or provider webhook implementation routes from being
documented as public by accident.
Need help?
Open an issue on the SDK repo or contact us through the merchant dashboard.