TypeScript SDK - FlexPrice

Installation

Install the FlexPrice TypeScript SDK using npm:

npm install @flexprice/sdk

Alternative package managers:

pnpm add @flexprice/sdk

Requirements:

Node.js 18 or higher
Supports ESM and CommonJS

Quick Start

Initialize the client and create a customer:

import { FlexPrice } from "@flexprice/sdk";

// Initialize client (server URL must include /v1)
const flexPrice = new FlexPrice({
  serverURL: "https://us.api.flexprice.io/v1",
  apiKeyAuth: process.env.FLEXPRICE_API_KEY ?? "YOUR_API_KEY",
});

async function main() {
  // Create a customer
  const customer = await flexPrice.customers.createCustomer({
    externalId: "customer-123",
    email: "user@example.com",
    name: "Example Customer",
  });
  console.log(customer);

  // Ingest an event
  const eventResult = await flexPrice.events.ingestEvent({
    eventName: "api_request",
    externalCustomerId: "customer-123",
    properties: { endpoint: "/api/resource", method: "POST" },
    source: "typescript_app",
  });
  console.log(eventResult);
}

main();

Initialization

Create a FlexPrice client with your API key:

import { FlexPrice } from "@flexprice/sdk";

const flexPrice = new FlexPrice({
  serverURL: "https://us.api.flexprice.io/v1",
  apiKeyAuth: process.env.FLEXPRICE_API_KEY!,
});

The server URL must include /v1 and have no trailing slash: https://us.api.flexprice.io/v1

Importing Types and Enums

All types, enums, and errors are re-exported from the package root:

import {
  FlexPrice,
  FeatureType,
  Status,
  FlexpriceError,
  CreateCustomerRequest,
  createPageIterator,
} from "@flexprice/sdk";

// No need for deep imports like:
// import { FeatureType } from "@flexprice/sdk/dist/sdk/models/shared";

Creating a Customer

const customer = await flexPrice.customers.createCustomer({
  externalId: "customer-123",
  email: "user@example.com",
  name: "Example Customer",
  metadata: {
    plan: "enterprise",
    region: "us-west",
  },
});

console.log(`Created customer: ${customer.id}`);

Ingesting Events

Single Event

const result = await flexPrice.events.ingestEvent({
  eventName: "file_upload",
  externalCustomerId: "customer-123",
  properties: {
    file_size_bytes: 1048576,
    file_type: "pdf",
  },
  source: "upload_service",
});

console.log(result);

Batch Event Ingestion

For high-volume event ingestion, batch multiple events:

const events = [
  {
    eventName: "api_request",
    externalCustomerId: "customer-123",
    properties: { endpoint: "/api/data", method: "GET" },
  },
  {
    eventName: "api_request",
    externalCustomerId: "customer-456",
    properties: { endpoint: "/api/users", method: "POST" },
  },
];

// Send events concurrently
const results = await Promise.all(
  events.map(event => flexPrice.events.ingestEvent(event))
);

console.log(`Ingested ${results.length} events`);

Error Handling

import { FlexpriceError } from "@flexprice/sdk";

try {
  const customer = await flexPrice.customers.createCustomer({
    externalId: "customer-123",
    email: "user@example.com",
  });
} catch (error) {
  if (error instanceof FlexpriceError) {
    console.error(`API Error: ${error.message}`);
    console.error(`Status: ${error.statusCode}`);
  } else {
    console.error(`Unexpected error: ${error}`);
  }
}

Common Operations

const customers = await flexPrice.customers.listCustomers({
  pageSize: 50,
  page: 1,
});

for (const customer of customers.customers) {
  console.log(`Customer: ${customer.name} (${customer.externalId})`);
}

TypeScript Types

The SDK provides full TypeScript support:

import { FlexPrice, CreateCustomerRequest } from "@flexprice/sdk";

const flexPrice = new FlexPrice({
  serverURL: "https://us.api.flexprice.io/v1",
  apiKeyAuth: process.env.FLEXPRICE_API_KEY!,
});

// Type-safe request
const customerData: CreateCustomerRequest = {
  externalId: "customer-123",
  email: "user@example.com",
  name: "Example Customer",
};

// Type-safe response
const customer = await flexPrice.customers.createCustomer(customerData);
// customer.id is typed as string
// customer.email is typed as string | undefined

Property Names (snake_case)

The API expects snake_case field names in request bodies. Use the correct case:

✅ Correct: event_name, external_customer_id, page_size
❌ Wrong: eventName, externalCustomerId, pageSize

If you see validation errors, check the API reference for exact field names.

Best Practices

Use environment variables

Store API keys in environment variables:

const apiKey = process.env.FLEXPRICE_API_KEY;
if (!apiKey) throw new Error("FLEXPRICE_API_KEY not set");

Enable TypeScript strict mode

Add to your tsconfig.json:

{
  "compilerOptions": {
    "strict": true
  }
}

Handle promises correctly

Always use async/await or .catch() for error handling:

try {
  await flexPrice.events.ingestEvent({...});
} catch (error) {
  console.error(error);
}

Batch high-volume events

Use Promise.all() for concurrent event ingestion to improve throughput

ESM and CommonJS

The package supports both module systems:

import { FlexPrice } from "@flexprice/sdk";

const flexPrice = new FlexPrice({...});

Framework Integration

Next.js

// app/api/events/route.ts
import { FlexPrice } from "@flexprice/sdk";
import { NextResponse } from "next/server";

const flexPrice = new FlexPrice({
  serverURL: "https://us.api.flexprice.io/v1",
  apiKeyAuth: process.env.FLEXPRICE_API_KEY!,
});

export async function POST(request: Request) {
  const body = await request.json();
  
  try {
    const result = await flexPrice.events.ingestEvent({
      eventName: body.eventName,
      externalCustomerId: body.customerId,
      properties: body.properties,
    });
    return NextResponse.json(result);
  } catch (error) {
    return NextResponse.json({ error }, { status: 500 });
  }
}

Express

import express from "express";
import { FlexPrice } from "@flexprice/sdk";

const app = express();
const flexPrice = new FlexPrice({
  serverURL: "https://us.api.flexprice.io/v1",
  apiKeyAuth: process.env.FLEXPRICE_API_KEY!,
});

app.post("/api/events", async (req, res) => {
  try {
    const result = await flexPrice.events.ingestEvent({
      eventName: req.body.eventName,
      externalCustomerId: req.body.customerId,
      properties: req.body.properties,
    });
    res.json(result);
  } catch (error) {
    res.status(500).json({ error });
  }
});

Troubleshooting

Missing or invalid API key

Ensure FLEXPRICE_API_KEY is set and the key is active. Use server-side only.

Wrong server URL

Use https://us.api.flexprice.io/v1 (include /v1, no trailing slash).

Validation or 4xx errors

Confirm request body field names are in snake_case as documented in the API reference.

Import errors

All types are re-exported from the package root. Use:

import { FlexPrice, FeatureType } from "@flexprice/sdk";

Next Steps

API Reference

Complete FlexPrice API documentation

TypeScript SDK Examples

Sample code and integration examples

NPM Package

View package on npm

Client Libraries

​Installation

​Quick Start

​Initialization

​Importing Types and Enums

​Creating a Customer

​Ingesting Events

​Single Event

​Batch Event Ingestion

​Error Handling

​Common Operations

​TypeScript Types

​Property Names (snake_case)

​Best Practices

​ESM and CommonJS

​Framework Integration

​Next.js

​Express

​Troubleshooting

​Next Steps

API Reference

TypeScript SDK Examples

NPM Package

Installation

Quick Start

Initialization

Importing Types and Enums

Creating a Customer

Ingesting Events

Single Event

Batch Event Ingestion

Error Handling

Common Operations

TypeScript Types

Property Names (snake_case)

Best Practices

ESM and CommonJS

Framework Integration

Next.js

Express

Troubleshooting

Next Steps