Developers

AIFA Commerce API

One generic commerce API for every vertical — fashion stores, hotels, anything that sells. Your API key selects the tenant: its catalog, AI search index and assistant persona. Every write flows through the same event-driven core that powers AIFA's web, Telegram and WhatsApp channels, so carts, orders and customer preferences stay in sync across all of them.

🔑 Authentication

Pass your key on every request: Authorization: Bearer aifa_sk_… Keys are issued per tenant — contact us to get yours. Rate limit: 120 requests/minute per key.

🚀 Quickstart — browse, cart, checkout

# 1. List categories
curl -H "Authorization: Bearer $AIFA_API_KEY" \
     https://api.aifa-demo.com/v1/categories

# 2. Semantic search — natural language, any phrasing
curl -H "Authorization: Bearer $AIFA_API_KEY" -H "Content-Type: application/json" \
     -d '{"query":"pink sneakers for a summer walk","limit":5}' \
     https://api.aifa-demo.com/v1/search

# 3. Create a cart, add an item, check out
CART=$(curl -s -X POST -H "Authorization: Bearer $AIFA_API_KEY" \
       https://api.aifa-demo.com/v1/carts | jq -r .cart_id)

curl -H "Authorization: Bearer $AIFA_API_KEY" -H "Content-Type: application/json" \
     -d '{"product_id":"sku-0108-shw:green","size":"38","quantity":1}' \
     https://api.aifa-demo.com/v1/carts/$CART/items

curl -H "Authorization: Bearer $AIFA_API_KEY" -H "Content-Type: application/json" \
     -d '{"delivery_info":"1 Main St, Dublin"}' \
     https://api.aifa-demo.com/v1/carts/$CART/checkout

🤖 The AI sales assistant

The assistant understands free text, recommends products, handles sizes, promotions and policies. Reuse your cart token as conversation_id and everything the assistant does lands in that very cart.

# Talk to the AI sales assistant (any language)
curl -H "Authorization: Bearer $AIFA_API_KEY" -H "Content-Type: application/json" \
     -d '{"conversation_id":"'$CART'","message":"what goes well with these boots?"}' \
     https://api.aifa-demo.com/v1/assistant/messages

# Buttons in the reply carry opaque "action" tokens — post one back to run it
curl -H "Authorization: Bearer $AIFA_API_KEY" -H "Content-Type: application/json" \
     -d '{"conversation_id":"'$CART'","action":"<token from a button>"}' \
     https://api.aifa-demo.com/v1/assistant/messages

🔗 Anonymous carts & cross-channel customers

Carts start anonymous — no login required. When the customer identifies (phone number is the canonical AIFA id), claim the cart once and it merges into their cross-channel profile: sizes, address, order history included.

# After the customer logs in (phone = canonical AIFA id):
curl -H "Authorization: Bearer $AIFA_API_KEY" -H "Content-Type: application/json" \
     -d '{"phone":"+353879861927"}' \
     https://api.aifa-demo.com/v1/carts/$CART/claim
# From now on use customer_id from the response as the cart id.
# The same customer on WhatsApp or Telegram sees the same cart.

📐 Data contracts

  • Stable v1: changes are additive only — new optional fields, never breaking
  • Generic products: vertical-specific fields live in attributes (a dress has colour and sizes; a hotel room has capacity and amenities)
  • Errors: conventional HTTP codes; the body carries { detail }

📖 Interactive reference

Full endpoint reference with request/response schemas and try-it-out: