AI Agent Integration Guidelines
Best practices for AI agents to integrate with ZaLinkAI without being blocked or throttled.
Welcome AI Developers
This guide helps you integrate AI shopping assistants with ZaLinkAI-connected stores. Follow these guidelines to ensure your agent provides the best experience for customers while respecting store resources.
Key Principle: Customer-First Requests
ZaLinkAI is designed for customer shopping experiences, not catalog indexing. Request what customers need, when they need it.
Best Practices
Request Specific Products
Ask for products by ID, name, or search query based on customer intent.
Cache Responses Locally
Store product details, categories, and prices to avoid repeated identical requests.
Follow Customer Navigation
Only browse categories or catalogs when the customer explicitly asks to explore.
Respect Rate Limits
Check X-RateLimit headers and back off when approaching limits.
Use Discovery Sparingly
Catalog browsing has daily caps. Use for initial exploration, not ongoing indexing.
What to Avoid
Catalog Enumeration
Do not iterate through all products, categories, or pages programmatically.
Repeated Identical Queries
Do not make the same request multiple times. Cache and reuse responses.
High-Frequency Polling
Do not check for updates more than once per minute unless necessary.
Bulk Data Extraction
Do not attempt to download entire product catalogs or price lists.
Ignoring Classification Headers
Do not ignore X-Request-Classification or X-Crawl-Warning headers.
Understanding Request Classification
Every request receives a classification that affects billing:
Response Headers to Monitor
Check these headers in every response:
| Header | Description |
|---|---|
X-Request-Classification | How this request was classified (PREMIUM, STANDARD, DISCOVERY, etc.) |
X-Billing-Multiplier | The billing multiplier applied (1.0, 0.5, 0.0) |
X-Crawl-Warning | Warning message if crawling patterns detected. Take corrective action! |
X-RateLimit-Remaining | Number of requests remaining in the current window. |
X-Discovery-Remaining | Discovery requests remaining today for this store. |
Crawl Detection Thresholds
Crossing these thresholds in a session triggers warnings or blocks:
Example Integration Pattern
Good Pattern
// Customer asks: "Show me blue sneakers under 300 SAR"
const products = await zalink.searchProducts({
query: "blue sneakers",
maxPrice: 300,
limit: 10
});
// Cache results for this session
sessionCache.set('blue-sneakers', products);
// Customer selects a product - fetch details
const product = await zalink.getProduct(products[0].id);
// Add to cart based on customer action
await zalink.addToCart(product.id, 1);Bad Pattern
// BAD: Trying to index entire catalog
for (let page = 1; page <= 1000; page++) {
const products = await zalink.listProducts({ page });
database.store(products); // Don't do this!
}
// BAD: Polling for changes every second
setInterval(async () => {
const products = await zalink.listProducts();
}, 1000);Need Help?
If you believe your agent is being incorrectly flagged:
- Review the X-Crawl-Warning header message for specific guidance
- Check your request patterns against the thresholds above
- Implement proper caching to reduce duplicate requests
- Contact support with your agent ID if issues persist