> ## Documentation Index
> Fetch the complete documentation index at: https://chariow.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Products

> Learn how to retrieve and work with products via the Chariow API

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

<Note>
  The Public API only returns **published** products. Draft and archived products are not accessible via the API.
</Note>

## Listing Products

Retrieve all published products for your store with optional filtering:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.chariow.com/v1/products?per_page=20&type=course" \
    -H "Authorization: Bearer sk_live_your_api_key"
  ```

  ```javascript JavaScript theme={null}
  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
  ```

  ```python Python theme={null}
  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']
  ```
</CodeGroup>

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

```javascript theme={null}
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

```json theme={null}
{
  "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:

<CodeGroup>
  ```bash cURL (by ID) theme={null}
  curl -X GET "https://api.chariow.com/v1/products/prd_abc123" \
    -H "Authorization: Bearer sk_live_your_api_key"
  ```

  ```bash cURL (by slug) theme={null}
  curl -X GET "https://api.chariow.com/v1/products/web-development-course" \
    -H "Authorization: Bearer sk_live_your_api_key"
  ```

  ```javascript JavaScript theme={null}
  // 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);
  ```

  ```python Python theme={null}
  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']
  ```
</CodeGroup>

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

<AccordionGroup>
  <Accordion title="One-Time Payment" icon="credit-card">
    A fixed price that customers pay once to access the product. This is the most common pricing type.

    ```json theme={null}
    {
      "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
      }
    }
    ```
  </Accordion>

  <Accordion title="Pay What You Want" icon="hand-holding-dollar">
    Customers choose how much to pay, with an optional minimum and suggested price. Useful for donations, tip-ware, or customer-driven pricing.

    ```json theme={null}
    {
      "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
      }
    }
    ```
  </Accordion>

  <Accordion title="Free" icon="gift">
    Products available at no cost, often used for lead generation, freebies, or sample content.

    ```json theme={null}
    {
      "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
    }
    ```
  </Accordion>

  <Accordion title="Sale Pricing" icon="tag">
    Products can have temporary sale prices with an expiration date. The `current_price` reflects the active price.

    ```json theme={null}
    {
      "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"
    }
    ```
  </Accordion>
</AccordionGroup>

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

```json theme={null}
{
  "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%"
    }
  }
}
```

<Note>
  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.
</Note>

## Working with Product Data

### Filtering Products

You can combine multiple filters to refine your product queries:

```javascript theme={null}
// 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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`)

```javascript theme={null}
// 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

```javascript theme={null}
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

```javascript theme={null}
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

```javascript theme={null}
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

<AccordionGroup>
  <Accordion title="Use Cursor Pagination" icon="arrows-rotate">
    Always use cursor-based pagination instead of fetching all products at once. This ensures efficient data retrieval and prevents timeouts.
  </Accordion>

  <Accordion title="Cache Product Data" icon="database">
    Product data doesn't change frequently. Consider caching products locally and refreshing periodically to reduce API calls.
  </Accordion>

  <Accordion title="Handle Missing Images" icon="image">
    Not all products have thumbnail or cover images. Always check for `null` values before displaying images.
  </Accordion>

  <Accordion title="Display Formatted Prices" icon="sterling-sign">
    Use the `formatted` field from price objects for display purposes. This ensures proper currency formatting and symbols.
  </Accordion>

  <Accordion title="Check Sale Expiration" icon="clock">
    When displaying sale prices, verify that `on_sale_until` is in the future to avoid showing expired sales.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="List Products" icon="list" href="/api-reference/products/list-products">
    View the List Products API reference
  </Card>

  <Card title="Get Product" icon="box" href="/api-reference/products/get-product">
    View the Get Product API reference
  </Card>

  <Card title="Checkout Guide" icon="shopping-cart" href="/en/guides/checkout">
    Learn how to create checkout sessions
  </Card>

  <Card title="Authentication" icon="key" href="/en/introduction/authentication">
    Learn about API authentication
  </Card>
</CardGroup>