For Developers
API Documentation
Integrate your application with the Talio Square marketplace. Use our sandbox environment to build and test safely, then switch to production when you're ready to go live.
Overview
Getting Started
The Talio Square API is a RESTful, JSON-based interface built on the Django REST Framework. It gives you programmatic access to products, categories, vendors, and orders.
API version
The current stable version of the API is v1. All endpoints are prefixed with /api/. Responses are returned as JSON. Every request should send an Accept: application/json header.
Environments
Sandbox & Production
Talio Square separates its API into two environments so you can build and test without affecting live data. Each environment has a distinct base URL and its own API keys.
Sandbox Environment
Use sandbox for development, testing, and validating integrations. It returns realistic mock data so your integration behaves exactly as it will in production — without touching real products or orders.
https://sandbox.taliosquare.international/api/
Sandbox credentials never expire credentials. You can obtain a sandbox API key at any time to start building immediately — no approval required.
Production Environment
When your integration is tested and ready, apply for a production API key. Production exposes real marketplace data and enforces the live rate limits. Keep production keys secret and rotate them regularly.
https://api.taliosquare.international/api/
A production key is issued after your sandbox integration passes review. Never commit production keys to source control.
Security
Authentication
Authenticate by sending your API key in the Authorization header. Public endpoints (products, categories, vendors) can be called without a key, but rate limits are higher for authenticated requests.
Bearer token authentication
Authorization: Token YOUR_API_KEY
| Endpoint type | Auth required | Notes |
|---|---|---|
| Products | No (public, read) | Returns approved products |
| Categories | No (public, read) | Returns active categories |
| Vendors | No (public, read) | Returns approved, active stores |
| Orders | Yes | Scoped to the authenticated user's own orders |
Reference
Endpoints
The following endpoints are available in both sandbox and production. They are identical in behaviour; only the base URL and keys differ.
| Method | Path | Description |
|---|---|---|
| GET | /api/products/ | List approved products. Detail: /api/products/{slug}/ |
| GET | /api/products/hot/ | Top products this week by view count |
| GET | /api/products/new/ | Newest products |
| GET | /api/categories/ | List active categories. Detail: /api/categories/{slug}/ |
| GET | /api/vendors/ | List approved stores. Detail: /api/vendors/{store_slug}/ |
| GET | /api/vendors/featured-stores/ | Random selection of featured stores |
| GET | /api/orders/ | List the authenticated user's orders |
Representative response
Product object
{
"id": 42,
"title": "Premium Leather Backpack",
"slug": "premium-leather-backpack",
"product_type": "physical",
"price": "14900.00",
"commission_rate": "8.00",
"category": {"id": 3, "name": "Accessories"},
"status": "approved"
}
Platform Layer
Foundation Platforms
Talio Square is a tenant on the Talio Foundation — the underlying platform that powers identity, logistics, payments, media, and AI generation across every Talio application. These platform APIs are separate from the marketplace endpoints above: they are served from the same production host, path-routed to the Foundation service.
Base URL & routing
Foundation platform requests share the marketplace's production domain; nginx routes each path prefix below to the Foundation service.
https://taliosquare.international{platform-prefix}
| Platform | Prefix | Status |
|---|---|---|
| TSI — Identity | /identity/ | Live |
| TSL — Logistics | /logistics/ | Live |
| TSM — Media | /tsm/media/ | Live |
| TSAI — AI Generation | /ai/ | Live |
| TSP — Payments | /payments/ | Live |
| TSSys — Systems | — | Coming Soon |
| TSSec — Security | — | Coming Soon |
TSSys and TSSec have no application and no routes in the Foundation today — there is nothing to call yet. They are listed here so integrators know they're planned, not to be confused with a live-but-undocumented endpoint.
Authentication
Every Foundation platform endpoint requires a platform API key sent as the X-API-Key header. Foundation keys are issued internally by the platform team, separately from the marketplace's own /api/ keys documented above — contact support to request access.
X-API-Key: YOUR_FOUNDATION_API_KEY
Sandbox access
Foundation platforms do not currently have a separate sandbox deployment of their own — there is one production Foundation service today. This is different from the marketplace's own /api/ sandbox above, and different again from TradeSafe's payment sandbox, which Talio Square's payments integration uses internally and does not expose to third-party API consumers. If you need to test against Foundation platform endpoints without affecting live data, talk to support about a scoped test key rather than assuming a sandbox. host exists for these prefixes.
| Method | Path | Platform | Description |
|---|---|---|---|
| POST | /identity/login/ | TSI | Authenticate and start a session |
| POST | /identity/create/ | TSI | Create an identity |
| GET | /identity/{id}/ | TSI | Fetch an identity by ID |
| GET | /identity/audit/ | TSI | Query audit events (actor / target / time range filters) |
| POST | /logistics/rates/ | TSL | Compare live carrier rates (Courier Guy, Fastway, Courier IT) |
| POST | /logistics/shipments/ | TSL | Create a shipment |
| GET | /logistics/shipments/track/{tracking_number}/ | TSL | Track a shipment by tracking number |
| POST | /tsm/media/upload/ | TSM | Upload a media file |
| GET | /tsm/media/{id}/ | TSM | Fetch media metadata |
| POST | /ai/generate/ | TSAI | Generate content (AI Store Builder, product copy, etc.) |
| POST | /payments/create/ | TSP | Create a payment held in escrow |
| GET | /payments/{id}/ | TSP | Fetch payment status (pending / escrow / released / refunded) |
| POST | /payments/wallets/create/ | TSP | Create a wallet |
This is a representative subset, not the full route list. Payment and identity endpoints in particular are used server-to-server by Talio Square's own backend today — treat direct third-party integration against /payments/ and /identity/ as coordinated access, not self-service signup.
Policy
Rate Limits
To keep the API fast and fair, requests are rate-limited per key and per IP. Recommended and enforced limits are documented below.
| Environment | Authenticated | Anonymous |
|---|---|---|
| Sandbox | 120 requests / minute | 30 requests / minute |
| Production | 120 requests / minute | 30 requests / minute |
Responses include the X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers so you can handle throttling gracefully.
Handling
Errors & Pagination
Errors are returned as JSON with a standard shape. Lists are paginated; inspect the response for a next/previous link to page through results.
{
"detail": "Authenticated request required."
}
| Code | Meaning | Action |
|---|---|---|
| 200 | OK | Request succeeded |
| 401 | Unauthorized | Check your API key or environment |
| 404 | Not Found | Check the resource slug / path |
| 429 | Too Many Requests | Slow down; respect rate limits |
Samples
Code Examples
A few quick examples to get you started in curl and Python.
curl — list approved products (sandbox)
https://sandbox.taliosquare.international/api/products/
Python — fetch a product
API = "https://sandbox.taliosquare.international/api"
headers = {"Accept": "application/json"}
r = requests.get(f"{API}/products/premium-leather-backpack/", headers=headers)
product = r.json()
print(product["title"], product["price"])
Python — authenticated order lookup
API = "https://api.taliosquare.international/api"
headers = {
"Accept": "application/json",
"Authorization": "Token YOUR_PRODUCTION_API_KEY"
}
r = requests.get(f"{API}/orders/", headers=headers)
orders = r.json()