Developer

API Reference

Product API

Create and update your product catalog programmatically. Send up to 500 categorized products in a single request — ideal for syncing from an ERP, POS, or inventory system.

Overview

The Product API accepts a batch of products and upserts them into your InstaSupply catalog. Products are matched by sku within your supplier account: a new SKU is inserted, an existing SKU is updated. Every product in the batch is always assigned to the supplier account that owns the API key.

Requests are all-or-nothing. If any product in the batch fails validation, the API returns 422 with a per-product error list and nothing is saved.

Authentication

Authenticate with an API key sent in the x-api-key header. Keys are created in the supplier app under Profile → Developer and look like isk_live_….

! The full key is shown once, at creation time. Store it in a secret manager. If a key is lost or exposed, revoke it in the app and generate a new one — revoked keys stop working immediately.
Headers 
x-api-key: isk_live_YOUR_API_KEY
Content-Type: application/json

Endpoint

POST https://acsrhvxnmnkkchxviycn.supabase.co/functions/v1/product-api

Only POST is supported with an API key. Any other method returns 405 Method not allowed.

Request body

The body is a JSON object with a single products array containing between 1 and 500 items.

FieldTypeDescription
products array<Product> Required 1–500 product objects. SKUs must be unique within the request.

Product fields

FieldTypeDescription
sku string Required Your unique product identifier. Used to match existing products for updates.
name string Required Product display name.
category object Required Category assignment. See Categories.
price.selling number Required Selling price. Must be greater than 0.
price.cost number Optional Your cost price, for margin reporting.
price.currency string Optional Only USD is accepted. Defaults to USD.
inventory.quantity integer Required Stock on hand. Non-negative integer; 0 marks the product out of stock.
inventory.unit string Optional Stock unit, e.g. bag, case. Defaults to Unit.
brand string Optional Brand name.
description string Optional Product description.
moq number Optional Minimum order quantity.
barcode string Optional UPC / EAN barcode.
images array<string> Optional Public image URLs.
tags array<string> Optional Search keywords.
colors array<string> Optional Available color variants.
pack_sizes array<number> Optional Available pack sizes.
eligible_for_return boolean Optional Whether buyers can return this product. Defaults to true.

Categories

Every product must be assigned to an InstaSupply category. Reference categories by name (case-insensitive) or by id — id takes precedence when both are sent. Subcategory and level-3 are optional, but each level must belong to its parent. Browse the full list of valid names and ids on the Category taxonomy page.

FieldTypeDescription
category.name or category.id string Required Top-level category. Must match the InstaSupply taxonomy.
category.subcategory or category.subcategory_id string Optional Subcategory within the category.
category.level3 or category.level3_id string Optional Third-level category within the subcategory. Requires a subcategory.
i Unknown category names, or a subcategory / level-3 that does not belong to its parent, fail validation for that product and reject the whole batch with 422.

Example request

cURL 
curl -X POST \
  https://acsrhvxnmnkkchxviycn.supabase.co/functions/v1/product-api \
  -H "x-api-key: isk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @products.json
products.json 
{
  "products": [{
    "sku": "COFFEE-1KG",
    "name": "Arabica Coffee Beans",
    "brand": "Highland Roasters",
    "category": {
      "name": "Food & Beverage",
      "subcategory": "Beverages"
    },
    "price": {
      "selling": 24.99,
      "cost": 16.50,
      "currency": "USD"
    },
    "inventory": {
      "quantity": 100,
      "unit": "bag"
    },
    "images": ["https://example.com/coffee.jpg"],
    "tags": ["coffee", "arabica"]
  }]
}

Responses

A successful request reports how many products were received, inserted, and updated. The API returns 201 when every product was new, and 200 when at least one existing product was updated.

200 OK / 201 Created 
{
  "received": 1,
  "inserted": 1,
  "updated": 0
}

Errors

StatusMeaningHow to fix
200 / 201 Batch saved. —
400 products is missing, empty, or has more than 500 items. Send 1–500 products per request; split larger catalogs into batches.
401 Invalid or revoked API key. Check the x-api-key header, or generate a new key in the app.
405 Method not allowed. Use POST.
422 One or more products failed validation. Nothing was saved. Fix every item listed in errors and resend the full batch.
500 Products could not be saved. Retry; if it persists, contact InstaSupply support with the detail message.

Validation failures include the zero-based index of each failing product so you can map errors back to your source rows:

422 Unprocessable Entity 
{
  "error": "Validation failed",
  "errors": [
    { "index": 0, "sku": "COFFEE-1KG", "message": "Unknown subcategory: Bevrages" }
  ]
}