Products

Manage your product catalog. Products are what the AI agent shows to customers and what appears on your storefront.

Create a Product

POST/v1/products

Parameter	Type	Description
name Required	string	Product name. Max 120 characters.
price Required	integer	Price in the smallest currency unit (e.g., kobo for NGN). 350000 = ₦3,500.
currency Optional	string	ISO 4217 code. Defaults to your account currency (e.g., 'NGN').
description Optional	string	Product description. The AI uses this to answer questions about the product.
category Optional	string	Category name for grouping.
image_url Optional	string	URL to the product image.
in_stock Optional	boolean	Whether the product is available. Default true.
metadata Optional	object	Arbitrary key-value pairs.

curl

curl -X POST https://api.handl-ng.com/v1/products \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jollof Rice (Large)",
    "price": 350000,
    "description": "Party-style jollof with grilled chicken and plantain",
    "category": "Mains",
    "in_stock": true
  }'

javascript

const product = await fetch('https://api.handl-ng.com/v1/products', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Jollof Rice (Large)',
    price: 350000,
    description: 'Party-style jollof with grilled chicken and plantain',
    category: 'Mains',
    in_stock: true,
  }),
}).then(r => r.json());

Response

json

{
  "id": "prod_jollof",
  "object": "product",
  "name": "Jollof Rice (Large)",
  "price": 350000,
  "formatted_price": "₦3,500",
  "currency": "NGN",
  "description": "Party-style jollof with grilled chicken and plantain",
  "category": "Mains",
  "image_url": null,
  "in_stock": true,
  "created_at": "2025-06-15T14:30:00Z",
  "updated_at": "2025-06-15T14:30:00Z"
}

List Products

GET/v1/products

Parameter	Type	Description
category Optional	string	Filter by category name.
in_stock Optional	boolean	Filter by availability.
search Optional	string	Full-text search across name and description.
limit Optional	integer	Number of results (1–100). Default 25.
starting_after Optional	string	Cursor for pagination.

curl

curl "https://api.handl-ng.com/v1/products?category=Mains&in_stock=true" \
  -H "Authorization: Bearer sk_live_..."

Update a Product

PATCH/v1/products/:id

Update any product field. Only the fields you include in the request body will be changed.

curl

curl -X PATCH https://api.handl-ng.com/v1/products/prod_jollof \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "price": 400000, "in_stock": false }'

Delete a Product

DELETE/v1/products/:id

⚠️

Deleting a product removes it from your catalog and storefront. Existing orders that reference this product are not affected — the product snapshot is preserved on the order.

curl

curl -X DELETE https://api.handl-ng.com/v1/products/prod_jollof \
  -H "Authorization: Bearer sk_live_..."

Response

json

{
  "id": "prod_jollof",
  "object": "product",
  "deleted": true
}

💡

The AI agent automatically learns about new and updated products. After creating or modifying a product via the API, the agent can immediately reference it in conversations.