> ## Documentation Index
> Fetch the complete documentation index at: https://developer.cashbackhive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Types

> Cashback Hive SDK TypeScript reference: the Offer, Member and ActivityItem data shapes, plus a ready-to-use declaration file for window.CashbackHive.

## Offer

A cashback offer from a retailer.

**slug** `string`

Stable identifier, e.g. `"nike"`. Use it for `offers.get()`, `openOffer()` and `trackingUrl()`.

**name** `string`

Display name, e.g. `"Nike"`.

**domain** `string | null`

Retailer's domain, e.g. `"nike.com"`. Searched by `offers.list({ search })`.

**category** `string | null`

Category label, e.g. `"Fashion and Apparel"`. Filterable with `offers.list({ category })`.

**country** `string | null`

ISO 3166-1 alpha-2 country code the offer applies to, e.g. `"US"`.

**logoUrl** `string | null`

URL of the retailer's logo, or `null` if none is available.

**cashback** `Cashback | null`

The cashback rate, or `null` if the offer currently has no cashback.

**pinned** `boolean`

Whether you've featured this offer in the publisher portal. Pinned offers are returned first by `offers.list()`.

**supportsDeeplinking** `boolean`

Whether the `deeplink` tracking option is honoured for this offer.

**clickUrl** `string | null`

Tracked-link template with `{PublisherClickID}`, `{SubId}` and `{DeepLink}` placeholders, or `null` if click tracking isn't available. Don't use this directly; use `openOffer()` or `trackingUrl()`.

## Cashback

**type** `"percentage" | "flat"`

Whether `amount` is a percentage of the sale or a fixed amount.

**amount** `number`

The rate. For `"percentage"`, a value like `3.2` means 3.2%. For `"flat"`, a currency amount.

**currency** `string`

ISO 4217 currency code. Present for `"flat"` cashback.

## Member

A signed-in Cashback Hive member.

**id** `string`

Stable member identifier.

**email** `string`

The member's email address.

**displayName** `string | null`

Display name, if set.

**balances** `object`

**properties**

**pending** `number`

Cashback tracked but not yet confirmed by the retailer.

**confirmed** `number`

Cashback confirmed and awaiting payout.

**paid** `number`

Lifetime cashback paid out.

**currency** `string`

ISO 4217 currency code for all three balances.

**createdAt** `string`

ISO 8601 timestamp of account creation.

## ActivityItem

A single cashback transaction.

**id** `string`

Transaction identifier.

**offerSlug** `string`

Slug of the offer the purchase was made through.

**brandName** `string`

Retailer display name at the time of the transaction.

**status** `"pending" | "confirmed" | "paid" | "declined"`

Where the transaction is in its lifecycle.

**saleAmount** `number`

The purchase amount reported by the retailer.

**cashback** `number`

Cashback earned. `0` for declined transactions.

**currency** `string`

ISO 4217 currency code.

**occurredAt** `string`

ISO 8601 timestamp of the purchase.

## TypeScript declarations

The SDK is a plain script and doesn't ship its own types. Copy this file into your project (for example `types/cashback-hive.d.ts`) and ensure it's included by your `tsconfig.json`. It declares `window.CashbackHive`, `window.onCashbackHiveReady`, and the `cbh:ready` event.

```ts types/cashback-hive.d.ts theme={null}
export interface CbhCashback {
  type: "percentage" | "flat";
  amount: number;
  currency?: string;
}

export interface CbhOffer {
  slug: string;
  name: string;
  domain: string | null;
  category: string | null;
  country: string | null;
  logoUrl: string | null;
  cashback: CbhCashback | null;
  pinned: boolean;
  supportsDeeplinking: boolean;
  clickUrl: string | null;
}

export interface CbhOfferListParams {
  search?: string;
  category?: string;
  limit?: number;
  offset?: number;
}

export interface CbhOfferListResult {
  offers: CbhOffer[];
  total: number;
}

export interface CbhMember {
  id: string;
  email: string;
  displayName: string | null;
  balances: {
    pending: number;
    confirmed: number;
    paid: number;
    currency: string;
  };
  createdAt: string;
}

export interface CbhActivityItem {
  id: string;
  offerSlug: string;
  brandName: string;
  status: "pending" | "confirmed" | "paid" | "declined";
  saleAmount: number;
  cashback: number;
  currency: string;
  occurredAt: string;
}

export interface CbhActivityResult {
  activity: CbhActivityItem[];
  total: number;
}

export interface CbhTrackingOptions {
  clickId?: string;
  subId?: string;
  deeplink?: string;
}

export interface CbhOpenOfferOptions extends CbhTrackingOptions {
  /** Defaults to true. */
  newTab?: boolean;
}

export interface CbhInitOptions {
  key: string;
  apiBase?: string;
  mock?: boolean;
  debug?: boolean;
}

export interface CbhEventMap {
  ready: { version: string };
  click: { slug: string; url: string };
  "auth:change": { member: CbhMember | null };
}

export interface CashbackHiveSdk {
  readonly version: string;
  readonly initialized: boolean;
  readonly ready: Promise<void>;

  init(options: CbhInitOptions): CashbackHiveSdk;

  offers: {
    list(params?: CbhOfferListParams): Promise<CbhOfferListResult>;
    get(slug: string): Promise<CbhOffer | null>;
  };

  member: {
    current(): CbhMember | null;
    get(): Promise<CbhMember | null>;
    activity(params?: { limit?: number; offset?: number }): Promise<CbhActivityResult>;
  };

  auth: {
    isSignedIn(): boolean;
    signIn(): Promise<CbhMember>;
    signOut(): void;
  };

  trackingUrl(offer: string | CbhOffer, opts?: CbhTrackingOptions): string;
  openOffer(offer: string | CbhOffer, opts?: CbhOpenOfferOptions): void;

  on<K extends keyof CbhEventMap>(
    event: K,
    handler: (payload: CbhEventMap[K]) => void,
  ): () => void;
  off<K extends keyof CbhEventMap>(
    event: K,
    handler: (payload: CbhEventMap[K]) => void,
  ): void;
}

export type CbhReadyEvent = CustomEvent<{ sdk: CashbackHiveSdk }>;

declare global {
  interface Window {
    CashbackHive?: CashbackHiveSdk;
    onCashbackHiveReady?: (sdk: CashbackHiveSdk) => void;
  }

  interface WindowEventMap {
    "cbh:ready": CbhReadyEvent;
  }
}
```

With this in place, `window.addEventListener("cbh:ready", e => …)` infers `e` as `CbhReadyEvent`, and `window.CashbackHive` is typed as `CashbackHiveSdk | undefined`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.