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

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 - Not visible to customers, still being edited
Published - Available for purchase on your store
Archived - No longer available but kept for records

The Public API only returns published products. Draft and archived products are not accessible via the API.

Listing Products

Retrieve all published products for your store 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 product name or slug
`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
      },
      "has_variant_pricing": false,
      "quantity": null,
      "settings": {
        "is_shipping_address_required": false
      },
      "rating": {
        "average": 4.8,
        "count": 245
      },
      "on_sale_until": null,
      "sales_count": {
        "raw": 1250,
        "formatted": "1,250"
      },
      "seo": null,
      "custom_cta_text": {
        "value": null,
        "label": null
      },
      "fields": null,
      "store": null,
      "bundle": null
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6NTB9",
    "prev_cursor": null,
    "has_more": 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)
Ratings: Average rating and number of reviews via rating
Sales: Sales count (if not hidden) via sales_count
Quantity: 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
Custom Fields: Additional product fields via fields (when loaded)
SEO: SEO metadata via seo (when loaded)
Store: Store information (when loaded)

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": "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

Products include rating information with the average score and total count:

{
  "rating": {
    "average": 4.8,
    "count": 245
  }
}

average: Rating from 0 to 5
count: Total number of ratings received

Stock Quantity

For products with limited stock, the quantity field provides detailed information:

{
  "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);
    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(minRating = 4.5, minReviews = 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.rating.average >= minRating && p.rating.count >= minReviews)
    .sort((a, b) => b.rating.average - a.rating.average);
}

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