Products

Products are the core of your Chariow store. This guide covers how to retrieve and work with products through the Public API.

Product Types

Chariow supports several product types:

Type	Description
`downloadable`	Digital files that customers can download after purchase
`course`	Online courses with structured chapters and lessons
`license`	Software licenses with activation and validation management
`service`	Digital services, consultations, or custom work
`bundle`	A collection of multiple products sold together at a discounted price
`coaching`	Coaching or mentoring sessions

A creator can change the type of a product that has never been sold. Do not treat type as permanent if you cache products.

Product Categories

Products are organised into the following categories:

Category	Value
Creative Arts	`creative_arts`
Technology	`technology`
Business and Finance	`business_and_finance`
Personal Development	`personal_development`
Education and Learning	`education_and_learning`
Entertainment	`entertainment`
Health and Wellness	`health_and_wellness`
Literature and Publishing	`literature_and_publishing`
Media and Communication	`media_and_communication`
Miscellaneous	`miscellaneous`

Product States

Products can be in different states:

Draft (draft): not visible to customers, still being edited
Published (published): available for purchase on your store
Suspended (suspended): suspended and not available for purchase

The Public API returns your products whatever their status, drafts included. Check status and only show products whose status is published to buyers.

Listing Products

Retrieve the products of your store, newest first, with optional filtering:

curl -X GET "https://api.chariow.com/v1/products?per_page=20&type=course" \
  -H "Authorization: Bearer sk_live_your_api_key"

const response = await fetch('https://api.chariow.com/v1/products?per_page=20&type=course', {
  headers: {
    'Authorization': 'Bearer sk_live_your_api_key'
  }
});

const result = await response.json();
console.log(result.data); // Array of products

import requests

response = requests.get(
    'https://api.chariow.com/v1/products',
    params={'per_page': 20, 'type': 'course'},
    headers={'Authorization': 'Bearer sk_live_your_api_key'}
)
products = response.json()['data']

Query Parameters

Parameter	Type	Description
`per_page`	integer	Number of products per page (default: 10, max: 100)
`cursor`	string	Pagination cursor from previous response
`search`	string	Search by public ID, name, slug, category or type
`category`	string	Filter by category (e.g., `technology`, `education_and_learning`)
`type`	string	Filter by type (e.g., `course`, `license`, `bundle`)

Pagination

The API uses cursor-based pagination for efficient data retrieval:

let allProducts = [];
let cursor = null;

do {
  const url = cursor
    ? `https://api.chariow.com/v1/products?cursor=${cursor}`
    : 'https://api.chariow.com/v1/products';

  const response = await fetch(url, {
    headers: { 'Authorization': 'Bearer sk_live_your_api_key' }
  });

  const result = await response.json();
  allProducts.push(...result.data);
  cursor = result.pagination.next_cursor;
} while (cursor);

console.log(`Retrieved ${allProducts.length} products`);

Example Response

{
  "data": [
    {
      "id": "prd_abc123",
      "name": "Complete Web Development Course",
      "slug": "web-development-course",
      "description": "A comprehensive course covering modern web development...",
      "type": "course",
      "category": {
        "value": "education_and_learning",
        "label": "Education and Learning"
      },
      "status": "published",
      "is_free": false,
      "pictures": {
        "thumbnail": "https://cdn.chariow.com/products/thumb.jpg",
        "cover": "https://cdn.chariow.com/products/cover.jpg"
      },
      "pricing": {
        "type": "one_time",
        "price": {
          "value": 99,
          "formatted": "$99.00",
          "short": "99",
          "currency": "USD"
        },
        "current_price": {
          "value": 99,
          "formatted": "$99.00",
          "short": "99",
          "currency": "USD"
        },
        "effective": {
          "value": 99,
          "formatted": "$99.00",
          "short": "99",
          "currency": "USD"
        },
        "sale_price": null,
        "minimum_price": {
          "value": 0,
          "formatted": "$0.00",
          "short": "0",
          "currency": "USD"
        },
        "suggested_price": {
          "value": 0,
          "formatted": "$0.00",
          "short": "0",
          "currency": "USD"
        },
        "price_off": null,
        "tracking": {
          "currency": "USD",
          "value": 99
        }
      },
      "has_variant_pricing": false,
      "quantity": null,
      "settings": {
        "is_shipping_address_required": false
      },
      "rating": {
        "total_ratings": {
          "value": 245,
          "formatted": "245",
          "short": "245",
          "short_plus": "245+"
        },
        "thumbs_up_count": 236,
        "thumbs_up_percentage": "96%"
      },
      "on_sale_until": null,
      "sales_count": {
        "value": 1250,
        "formatted": "1,250",
        "short": "1K",
        "short_plus": "1K+"
      },
      "seo": null,
      "custom_cta_text": {
        "value": null,
        "label": null
      },
      "fields": null,
      "store": null,
      "bundle": null,
      "coaching": null
    }
  ],
  "pagination": {
    "count": 20,
    "path": "https://api.chariow.com/v1/products",
    "per_page": 20,
    "next_cursor": "eyJpZCI6NTB9",
    "next_page_url": "https://api.chariow.com/v1/products?cursor=eyJpZCI6NTB9",
    "prev_cursor": null,
    "prev_page_url": null,
    "has_more_pages": true,
    "has_pages": true
  }
}

Getting a Single Product

Retrieve detailed information about a specific product by its public ID or slug:

curl -X GET "https://api.chariow.com/v1/products/prd_abc123" \
  -H "Authorization: Bearer sk_live_your_api_key"

curl -X GET "https://api.chariow.com/v1/products/web-development-course" \
  -H "Authorization: Bearer sk_live_your_api_key"

// By public ID
const response = await fetch('https://api.chariow.com/v1/products/prd_abc123', {
  headers: {
    'Authorization': 'Bearer sk_live_your_api_key'
  }
});

const product = (await response.json()).data;
console.log(product.name, product.pricing);

import requests

# By public ID
response = requests.get(
    'https://api.chariow.com/v1/products/prd_abc123',
    headers={'Authorization': 'Bearer sk_live_your_api_key'}
)
product = response.json()['data']

Product Details

The single product endpoint returns comprehensive information including:

Pricing: Current price, base price, effective price, sale price (if applicable), minimum price, suggested price, and discount percentage (price_off)
Images: Thumbnail and cover images via pictures
Category: Product category with value and label
Variant Pricing: Whether the product has variant pricing (has_variant_pricing)
Ad tracking price: The current price converted to USD via pricing.tracking, for ad trackers such as the Meta Pixel
Ratings: Number of ratings and share of positive ratings via rating
Sales: Exact sales count via sales_count, or null when the product hides it (new products hide it by default)
Quantity: Exact stock information (if product has limited quantity)
Settings: Product settings such as is_shipping_address_required
Sale Expiration: on_sale_until datetime for temporary sale pricing
Custom CTA Text: Custom call-to-action text via custom_cta_text
Bundle: Savings information for bundle products
Coaching: Session duration, format, time zone and buffer for coaching products via coaching
Description: description is HTML, sanitised by Chariow to strip unsafe markup

The fields, seo and store keys are present but always null on the public API.

Pricing Types

Products can have different pricing models:

One-Time Payment

A fixed price that customers pay once to access the product. This is the most common pricing type.

{
  "pricing": {
    "type": "one_time",
    "price": {
      "value": 49,
      "formatted": "$49.00",
      "short": "49",
      "currency": "USD"
    },
    "current_price": {
      "value": 49,
      "formatted": "$49.00",
      "short": "49",
      "currency": "USD"
    },
    "effective": {
      "value": 49,
      "formatted": "$49.00",
      "short": "49",
      "currency": "USD"
    },
    "sale_price": null,
    "minimum_price": {
      "value": 0,
      "formatted": "$0.00",
      "short": "0",
      "currency": "USD"
    },
    "suggested_price": {
      "value": 0,
      "formatted": "$0.00",
      "short": "0",
      "currency": "USD"
    },
    "price_off": null
  }
}

Pay What You Want

Customers choose how much to pay, with an optional minimum and suggested price. Useful for donations, tip-ware, or customer-driven pricing.

{
  "pricing": {
    "type": "what_you_want",
    "price": {
      "value": 0,
      "formatted": "$0.00",
      "short": "0",
      "currency": "USD"
    },
    "current_price": {
      "value": 0,
      "formatted": "$0.00",
      "short": "0",
      "currency": "USD"
    },
    "effective": {
      "value": 0,
      "formatted": "$0.00",
      "short": "0",
      "currency": "USD"
    },
    "sale_price": null,
    "minimum_price": {
      "value": 5,
      "formatted": "$5.00",
      "short": "5",
      "currency": "USD"
    },
    "suggested_price": {
      "value": 25,
      "formatted": "$25.00",
      "short": "25",
      "currency": "USD"
    },
    "price_off": null
  }
}

Free

Products available at no cost, often used for lead generation, freebies, or sample content.

{
  "pricing": {
    "type": "free",
    "price": {
      "value": 0,
      "formatted": "$0.00",
      "short": "0",
      "currency": "USD"
    },
    "current_price": {
      "value": 0,
      "formatted": "$0.00",
      "short": "0",
      "currency": "USD"
    },
    "effective": {
      "value": 0,
      "formatted": "$0.00",
      "short": "0",
      "currency": "USD"
    },
    "sale_price": null,
    "minimum_price": {
      "value": 0,
      "formatted": "$0.00",
      "short": "0",
      "currency": "USD"
    },
    "suggested_price": {
      "value": 0,
      "formatted": "$0.00",
      "short": "0",
      "currency": "USD"
    },
    "price_off": null
  },
  "is_free": true
}

Sale Pricing

Products can have temporary sale prices with an expiration date. The current_price reflects the active price.

{
  "pricing": {
    "type": "one_time",
    "price": {
      "value": 149,
      "formatted": "$149.00",
      "short": "149",
      "currency": "USD"
    },
    "current_price": {
      "value": 99,
      "formatted": "$99.00",
      "short": "99",
      "currency": "USD"
    },
    "effective": {
      "value": 99,
      "formatted": "$99.00",
      "short": "99",
      "currency": "USD"
    },
    "sale_price": {
      "value": 99,
      "formatted": "$99.00",
      "short": "99",
      "currency": "USD"
    },
    "minimum_price": {
      "value": 0,
      "formatted": "$0.00",
      "short": "0",
      "currency": "USD"
    },
    "suggested_price": {
      "value": 0,
      "formatted": "$0.00",
      "short": "0",
      "currency": "USD"
    },
    "price_off": "34%"
  },
  "on_sale_until": "2025-02-28T23:59:59Z"
}

Product Bundles

Bundles combine multiple products at a discounted price. When retrieving a bundle product, you’ll receive information about the total bundle value and savings:

{
  "id": "prd_bundle123",
  "name": "Complete Developer Bundle",
  "slug": "developer-bundle",
  "type": "bundle",
  "pricing": {
    "type": "one_time",
    "price": {
      "value": 199,
      "formatted": "$199.00",
      "short": "199",
      "currency": "USD"
    },
    "current_price": {
      "value": 199,
      "formatted": "$199.00",
      "short": "199",
      "currency": "USD"
    },
    "effective": {
      "value": 199,
      "formatted": "$199.00",
      "short": "199",
      "currency": "USD"
    },
    "sale_price": null,
    "minimum_price": {
      "value": 0,
      "formatted": "$0.00",
      "short": "0",
      "currency": "USD"
    },
    "suggested_price": {
      "value": 0,
      "formatted": "$0.00",
      "short": "0",
      "currency": "USD"
    },
    "price_off": null
  },
  "bundle": {
    "value": {
      "value": 297,
      "formatted": "$297.00",
      "short": "297",
      "currency": "USD"
    },
    "savings": {
      "amount": {
        "value": 98,
        "formatted": "$98.00",
        "short": "98",
        "currency": "USD"
      },
      "percentage": {
        "value": 33,
        "formatted": "33%"
      }
    }
  }
}

The bundle.value shows the total value if all products were purchased separately, whilst the pricing.current_price shows the discounted bundle price. The bundle.savings shows how much customers save by purchasing the bundle.

Working with Product Data

Filtering Products

You can combine multiple filters to refine your product queries:

// Get all free courses
const response = await fetch(
  'https://api.chariow.com/v1/products?type=course&category=education_and_learning',
  {
    headers: { 'Authorization': 'Bearer sk_live_your_api_key' }
  }
);

// Search for products
const searchResponse = await fetch(
  'https://api.chariow.com/v1/products?search=web+development',
  {
    headers: { 'Authorization': 'Bearer sk_live_your_api_key' }
  }
);

Understanding Ratings

Buyers rate a product with a thumbs up or down. Products include the number of ratings and the share of positive ones:

{
  "rating": {
    "total_ratings": {
      "value": 245,
      "formatted": "245",
      "short": "245",
      "short_plus": "245+"
    },
    "thumbs_up_count": 236,
    "thumbs_up_percentage": "96%"
  }
}

total_ratings: Number of ratings received, with formatted and abbreviated versions
thumbs_up_count: Number of positive ratings
thumbs_up_percentage: Share of positive ratings, as a string (e.g., 96%)

Stock Quantity

For products with limited stock, the quantity field provides the exact stock of the product (percentages are whole numbers):

{
  "quantity": {
    "value": 100,
    "remaining": {
      "value": 35,
      "percent": 35
    },
    "sold": {
      "value": 65,
      "percent": 65
    },
    "total": 100
  }
}

Products without limited stock will have quantity: null.

Price Formatting

All price objects include four fields for flexible display:

value: Numeric amount (e.g., 99 for $99.00)
formatted: Ready-to-display string (e.g., $99.00, £99.00, €99.00)
short: Abbreviated human-readable string using forHumans (e.g., 99, 5K, 1.25M)
currency: ISO currency code (e.g., USD, EUR, GBP)

// Using the formatted price
const product = response.data;
console.log(`Buy now for ${product.pricing.current_price.formatted}`);

const price = product.pricing.current_price.value;
if (price < 50) {
  console.log('Affordable option!');
}

Common Use Cases

Building a Product Catalogue

async function buildProductCatalogue(category) {
  const products = [];
  let cursor = null;

  do {
    const params = new URLSearchParams({
      per_page: 50,
      category: category,
      ...(cursor && { cursor })
    });

    const response = await fetch(
      `https://api.chariow.com/v1/products?${params}`,
      {
        headers: { 'Authorization': 'Bearer sk_live_your_api_key' }
      }
    );

    const result = await response.json();
    products.push(...result.data.filter(product => product.status === 'published'));
    cursor = result.pagination.next_cursor;
  } while (cursor);

  return products;
}

// Get all technology products
const techProducts = await buildProductCatalogue('technology');

Displaying Sale Products

async function getSaleProducts() {
  const response = await fetch('https://api.chariow.com/v1/products?per_page=100', {
    headers: { 'Authorization': 'Bearer sk_live_your_api_key' }
  });

  const result = await response.json();

  // Filter products currently on sale
  return result.data.filter(product =>
    product.pricing.sale_price !== null &&
    product.on_sale_until &&
    new Date(product.on_sale_until) > new Date()
  );
}

Finding Popular Products

async function getPopularProducts(minPositiveShare = 90, minRatings = 50) {
  const response = await fetch('https://api.chariow.com/v1/products?per_page=100', {
    headers: { 'Authorization': 'Bearer sk_live_your_api_key' }
  });

  const result = await response.json();

  return result.data
    .filter(p => p.status === 'published')
    .filter(p => parseFloat(p.rating.thumbs_up_percentage) >= minPositiveShare
      && p.rating.total_ratings.value >= minRatings)
    .sort((a, b) => parseFloat(b.rating.thumbs_up_percentage) - parseFloat(a.rating.thumbs_up_percentage));
}

Best Practices

Use Cursor Pagination

Always use cursor-based pagination instead of fetching all products at once. This ensures efficient data retrieval and prevents timeouts.

Cache Product Data

Product data doesn’t change frequently. Consider caching products locally and refreshing periodically to reduce API calls.

Handle Missing Images

Not all products have thumbnail or cover images. Always check for null values before displaying images.

Display Formatted Prices

Use the formatted field from price objects for display purposes. This ensures proper currency formatting and symbols.

Check Sale Expiration

When displaying sale prices, verify that on_sale_until is in the future to avoid showing expired sales.

Next Steps

List Products

View the List Products API reference

Get Product

View the Get Product API reference

Checkout Guide

Learn how to create checkout sessions

Authentication

Learn about API authentication

Introduction

Guides

MCP Integration

n8n Integration

Resources

Product Types

Product Categories

Product States

Listing Products

Query Parameters

Example Response

Getting a Single Product

Product Details

Pricing Types

Product Bundles

Working with Product Data

Filtering Products

Understanding Ratings

Stock Quantity

Price Formatting

Common Use Cases

Building a Product Catalogue

Displaying Sale Products

Finding Popular Products

Best Practices

Next Steps

List Products

Get Product

Checkout Guide

Authentication

​Product Types

​Product Categories

​Product States

​Listing Products

​Query Parameters

​Pagination

​Example Response

​Getting a Single Product

​Product Details

​Pricing Types

​Product Bundles

​Working with Product Data

​Filtering Products

​Understanding Ratings

​Stock Quantity

​Price Formatting

​Common Use Cases

​Building a Product Catalogue

​Displaying Sale Products

​Finding Popular Products

​Best Practices

​Next Steps

List Products

Get Product

Checkout Guide

Authentication

Product Types

Product Categories

Product States

Listing Products

Query Parameters

Pagination

Example Response

Getting a Single Product

Product Details

Pricing Types

Product Bundles

Working with Product Data

Filtering Products

Understanding Ratings

Stock Quantity

Price Formatting

Common Use Cases

Building a Product Catalogue

Displaying Sale Products

Finding Popular Products

Best Practices

Next Steps