Listings

A listing is the marketplace representation of a channel. It wraps a channel with metadata, pricing, documentation, and analytics that help consumers discover and evaluate your data.

Listing lifecycle

Every listing moves through a defined set of states.

State	Description
Draft	The listing is being prepared. Not visible to anyone outside your organization.
Pending review	Submitted for review by the npayload marketplace team.
Published	Live and visible according to the listing's visibility setting (public, unlisted, or invite-only).
Archived	Removed from the marketplace. Existing subscribers continue to receive messages until they cancel.

import NPayload from '@npayload/node';

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

// Create a draft listing
const listing = await npayload.marketplace.listings.create({
  channel: 'sensor-readings',
  title: 'Industrial Sensor Readings',
  description: 'Temperature, pressure, and vibration data from 10,000+ industrial sensors',
  category: 'iot',
  pricing: { model: 'usage-based', tiers: [
    { upTo: 50000, unitPrice: 0.0005 },
    { upTo: null, unitPrice: 0.0002 },
  ]},
  visibility: 'public',
});

// Submit for review
await npayload.marketplace.listings.submit(listing.id);

// Archive a listing
await npayload.marketplace.listings.archive(listing.id);

Marketplace review typically completes within 48 hours. Listings are reviewed for completeness, accurate descriptions, and compliance with the marketplace terms of service.

Listing metadata

Every listing requires a title and description. The optional fields significantly improve discoverability and conversion.

Field	Required	Description
`title`	Yes	Short, descriptive name (max 100 characters)
`description`	Yes	What the channel provides, who it is for, and what format the data uses
`category`	Yes	Primary category for search and filtering
`tags`	No	Up to 10 keywords for additional discoverability
`icon`	No	Custom icon URL for the listing card
`website`	No	Link to external documentation or product page
`supportEmail`	No	Contact email for subscriber support

await npayload.marketplace.listings.update(listing.id, {
  tags: ['sensors', 'industrial', 'temperature', 'iot'],
  website: 'https://docs.example.com/sensor-api',
  supportEmail: 'data-support@example.com',
});

Category	Slug	Example listings
AI and ML	`ai-ml`	Model predictions, training events, inference logs
Financial Data	`financial-data`	Market prices, transaction events, payment notifications
IoT	`iot`	Sensor readings, device telemetry, location tracking
Analytics	`analytics`	Clickstream data, funnel events, product metrics
Commerce	`commerce`	Order events, inventory updates, shipping notifications
Social	`social`	Activity feeds, engagement events, content updates
Infrastructure	`infrastructure`	Health checks, deployment events, system metrics

Schema documentation

Attach an event catalogue schema to your listing so consumers can see the exact message format before subscribing.

// Attach a schema
await npayload.marketplace.listings.update(listing.id, {
  schemaId: 'sch_sensor_reading_v3',
});

When a schema is attached, consumers see:

Field names and types
Required and optional fields
Example values
Version history

Changing the schema on a published listing does not break existing subscribers, but you should communicate breaking changes through versioning. Attach a new schema version rather than modifying the existing one.

Sample data

Provide representative messages so consumers can evaluate the data format without subscribing.

await npayload.marketplace.listings.update(listing.id, {
  sampleData: [
    {
      key: 'sensor-4821',
      payload: {
        sensorId: 'sensor-4821',
        type: 'temperature',
        value: 72.4,
        unit: 'fahrenheit',
        timestamp: '2026-03-07T10:15:00Z',
      },
    },
    {
      key: 'sensor-4821',
      payload: {
        sensorId: 'sensor-4821',
        type: 'pressure',
        value: 14.7,
        unit: 'psi',
        timestamp: '2026-03-07T10:15:00Z',
      },
    },
    {
      key: 'sensor-9033',
      payload: {
        sensorId: 'sensor-9033',
        type: 'vibration',
        value: 0.003,
        unit: 'g',
        timestamp: '2026-03-07T10:15:01Z',
      },
    },
  ],
});

Include at least 3 sample messages that cover the range of data shapes consumers can expect.

Versioning

Update your listing without breaking existing subscribers.

// Update metadata (safe, no subscriber impact)
await npayload.marketplace.listings.update(listing.id, {
  description: 'Updated description with more detail',
});

// Update schema version (notify subscribers)
await npayload.marketplace.listings.update(listing.id, {
  schemaId: 'sch_sensor_reading_v4',
  changeNote: 'Added humidity field. All existing fields remain unchanged.',
});

When you update the schema version, subscribers receive a notification with the change note. This allows them to update their integration before the new format takes effect.

Analytics

Track how your listing is performing.

const analytics = await npayload.marketplace.listings.analytics(listing.id, {
  period: 'last-30-days',
});

console.log(analytics.views);            // 1240
console.log(analytics.uniqueVisitors);   // 890
console.log(analytics.subscriptions);    // 23
console.log(analytics.cancellations);    // 2
console.log(analytics.revenue);          // 4521.30
console.log(analytics.averageRating);    // 4.6
console.log(analytics.conversionRate);   // 0.026 (2.6%)

Metric	Description
`views`	Total listing page views
`uniqueVisitors`	Unique organizations that viewed the listing
`subscriptions`	New subscriptions in the period
`cancellations`	Subscriptions cancelled in the period
`revenue`	Total revenue earned in the period
`averageRating`	Current average star rating
`conversionRate`	Ratio of subscriptions to unique visitors

Featured listings

Featured listings appear prominently in the marketplace home page and category pages. Listings are selected for featuring based on:

High average rating (4.5 or above)
Consistent uptime and low latency
Complete documentation (schema, sample data, SLA)
Active publisher engagement (responding to reviews, regular updates)

There is no paid placement. Featured status is earned through quality and reliability.

Next steps

Publishing for the end-to-end publishing workflow
Reviews and ratings to understand how subscribers rate your listings
Channels for channel types and configuration options

Was this page helpful?