Consuming from the marketplace

The npayload Marketplace lets you discover and subscribe to data streams published by other organizations. Once subscribed, you receive messages through the same delivery mechanisms as any npayload subscription: webhooks, queues, or consumer groups.

Browsing the marketplace

Search and filter listings to find the data you need.

import NPayload from '@npayload/node';

const npayload = new NPayload({ token: process.env.NPAYLOAD_TOKEN });

// Search by keyword
const results = await npayload.marketplace.search({
  query: 'stock prices',
});

// Filter by category and minimum rating
const filtered = await npayload.marketplace.search({
  category: 'financial-data',
  minRating: 4.0,
  pricing: 'free',
  sortBy: 'rating',
});

// Browse all listings in a category
const iotListings = await npayload.marketplace.search({
  category: 'iot',
  sortBy: 'subscribers',
  limit: 20,
});

Filter	Type	Description
`query`	string	Full-text search across title, description, and tags
`category`	string	Filter by category (see Listings for the full list)
`minRating`	number	Minimum average star rating (1.0 to 5.0)
`pricing`	string	Filter by pricing model: `free`, `per-message`, `flat-monthly`, `usage-based`
`sortBy`	string	Sort by `relevance`, `rating`, `subscribers`, or `newest`
`limit`	number	Maximum number of results (default 10, max 100)

Evaluating a listing

Before subscribing, review the listing details to make sure the data meets your needs.

const listing = await npayload.marketplace.listings.get('lst_market_prices');

console.log(listing.title);          // "Real-time Market Prices"
console.log(listing.rating);         // 4.7
console.log(listing.reviewCount);    // 128
console.log(listing.subscriberCount); // 342
console.log(listing.sla);            // { uptimePercent: 99.9, maxLatencyMs: 200 }

What to look for

Signal	Why it matters
Rating and reviews	Real feedback from active subscribers on reliability and data quality
Sample data	Preview the message format before committing
Schema	Typed event catalogue schema for integration confidence
SLA	Uptime and latency guarantees from the publisher
Subscriber count	Higher counts suggest a proven, reliable data source
Verified badge	The publisher's organization has been verified by npayload

// View sample data
const samples = await npayload.marketplace.listings.sampleData('lst_market_prices');

// View the attached schema
const schema = await npayload.marketplace.listings.schema('lst_market_prices');

Subscribing to a listing

Subscribe with a single API call. Messages start flowing immediately.

const subscription = await npayload.marketplace.subscribe({
  listingId: 'lst_market_prices',
  webhook: 'https://api.example.com/webhooks/market-data',
});

You can also subscribe using queue or consumer group delivery:

// Queue delivery (pull-based)
const subscription = await npayload.marketplace.subscribe({
  listingId: 'lst_market_prices',
  delivery: 'queue',
});

// Consumer group (shared processing)
const subscription = await npayload.marketplace.subscribe({
  listingId: 'lst_market_prices',
  consumerGroup: 'price-processors',
  webhook: 'https://api.example.com/webhooks/market-data',
});

Marketplace subscriptions use the same delivery guarantees as standard npayload subscriptions. Messages are delivered at-least-once with configurable retry policies.

Authentication and access

Marketplace subscriptions are scoped to your organization's API credentials. No additional authentication setup is required. Your existing API token automatically grants access to any listing you have subscribed to.

// Your existing token works for marketplace subscriptions
const npayload = new NPayload({ token: process.env.NPAYLOAD_TOKEN });

// Messages from marketplace subscriptions arrive at your webhook
// with the same signature verification as any other npayload webhook

If a publisher revokes your subscription, message delivery stops immediately. You will receive a notification with the reason.

Managing subscriptions

View, pause, and cancel your marketplace subscriptions.

// List all marketplace subscriptions
const subscriptions = await npayload.marketplace.subscriptions.list();

// View usage and cost for a subscription
const usage = await npayload.marketplace.subscriptions.usage('sub_abc123', {
  period: 'current-month',
});

console.log(usage.messageCount);   // 145230
console.log(usage.estimatedCost);  // 14.52

// Pause delivery (you are not billed while paused)
await npayload.marketplace.subscriptions.pause('sub_abc123');

// Resume delivery
await npayload.marketplace.subscriptions.resume('sub_abc123');

// Cancel subscription
await npayload.marketplace.subscriptions.cancel('sub_abc123');

Cost management

Track and control your marketplace spending.

Feature	Description
Usage dashboard	View message counts and costs per subscription, per period
Spending alerts	Set a monthly spending threshold and receive a notification when you approach it
Budget caps	Set a hard cap that pauses delivery when reached

// Set a spending alert
await npayload.marketplace.subscriptions.setAlert('sub_abc123', {
  thresholdAmount: 100.00,
  notifyChannel: 'billing-alerts',
});

// Set a hard budget cap
await npayload.marketplace.subscriptions.setBudget('sub_abc123', {
  monthlyCapAmount: 500.00,
  action: 'pause', // pause delivery when cap is reached
});

Next steps

Listings for details on listing categories and metadata
Reviews and ratings to leave feedback on listings you subscribe to
Subscriptions and delivery for webhook, queue, and consumer group configuration

Was this page helpful?