Frequently Asked Questions
Common questions and answers
Getting Started
Q: How long does order processing take?
A: Typically 1-30 seconds end-to-end:
- API validation & acceptance: <150ms
- Job queue processing: 1-30s (depends on system load)
- Order finalization: 100-500ms
- Total: 1-35 seconds (typical: 5-15 seconds)
Q: How do I track order status?
A: Use the job tracking API with the jobId returned when you create an order:
GET /e9v3/jobs/{jobId}Status values: pending → processing → completed or failed
Q: Can I create orders without an API key?
A: No. All API requests require OAuth 2.0 authentication with a valid API key.
Q: What's the difference between /send and /receive and /sync?
A:
/send- Quick way to create send orders (requires customerId)/receive- Quick way to create receive orders (requires supplierId)/sync- Generic endpoint for any order type (specify orderType)
Authentication
Q: How often do I need to refresh my token?
A: Tokens last 1 hour. Refresh when they expire (check expires_in field).
Q: Should I request a new token for every API call?
A: No! Cache tokens and reuse for up to 1 hour. Only request new ones when expired.
Q: What if my API key expires?
A: You’ll get HTTP 403 "api key expired". Create a new API key in the admin console.
Q: Can I have multiple API keys?
A: Yes. Create multiple keys for different integrations, environments, or businesses. A key is bound to one business unless you opt in to a multi-business key at mint time.
Q: I manage several businesses — can one key access all of them?
A: Yes, if you own those businesses and select them when generating the key. Classic keys stay one business (existing keys never require a header). Multi-business keys must send X-Business-ID on /e9v3; it must be one of the businesses bound at create time. You can still mint one key per business from the Integrations picker.
Q: How do I revoke an API key?
A: Delete it via the admin console or API. All requests with that key will immediately fail with 403.
Rate Limiting
Q: What’s the rate limit?
A: 1 order/second per API key with a burst capacity of 10 orders.
Q: Can I exceed the rate limit with a burst?
A: Yes, you can create up to 10 orders immediately (burst). After that, you’re limited to 1/second steady-state.
Q: Do rate limits reset daily?
A: No. It’s a token bucket: tokens refill at 1/second continuously. Max capacity is 10 tokens.
Q: What do I do when I get a 429 error?
A: Wait the amount specified in the Retry-After header, then retry.
Q: Can I get a higher rate limit?
A: Contact support if you need higher limits for high-volume integrations.
Q: How do I avoid hitting rate limits?
A: Queue orders and process serially, or limit concurrency to 1-5 requests.
Orders
Q: What order types are supported?
A: Four types: send (to customer), receive (from supplier), return (from location), transfer (to agent). Use dedicated endpoints for send and receive; use the /sync endpoint for return and transfer.
Q: What’s the difference between reference1, reference2, reference3?
A: Optional fields for tracking. Common usage:
reference1= Purchase Order numberreference2= Sales Order numberreference3= External ID (for reconciliation)
Q: Can I update an order after creation?
A: Orders are created as drafts. Edit them in the Equos UI before finalizing.
Q: Can I bulk create orders?
A: Not via a single API call. Submit orders individually and queue them.
Q: What happens if I create a duplicate order?
A: Each API request creates a unique job with a different jobId (based on Unix nanoseconds). The API is NOT idempotent — submitting the same request twice will create two separate jobs and orders. Use the sourceRecordId field to track your orders on your side and prevent duplicates in your application.
Q: Can I specify a custom order ID?
A: No. Order IDs are auto-generated. Use reference1 for tracking.
Error Handling
Q: What should I do about 400 errors?
A: Fix your request. 400 errors won’t succeed with retries.
Q: Should I retry 401/403 errors?
A: No. These are permanent auth issues. Fix your token/key and retry.
Q: How should I handle 500 errors?
A: Use exponential backoff. Server errors are usually transient.
Q: What validation errors are most common?
A:
- Missing
customerIdorsupplierId - Quantity <= 0
- Multiple contact fields
- Empty
itemsarray
Integration
Q: How do I integrate with Shopify?
A: See the Examples section for a Shopify webhook handler.
Q: Can I call this API from the browser?
A: Not directly (CORS). Call from your backend server instead.
Q: Can I use this API with scheduled jobs?
A: Yes! Great for periodic imports from databases or other systems.
Monitoring & Operations
Q: How do I monitor my API usage?
A: Use the job tracking API to monitor order processing status and errors. If you use webhooks, monitor the webhook failure count — if it reaches 10, the webhook will be auto-disabled. Re-enable it via the webhooks API.
Q: What should I alert on?
A:
- 429 response rate > 20%
- Error rate > 1%
- Orders stuck in "pending" > 30 seconds
Q: Can I see API usage logs?
A: Contact support for detailed API usage logs and analytics. We provide monthly usage reports for all integrations.
Q: Is there a status page?
A: Contact support for current system status. Any status page is informational only and is not a service-level commitment.
Troubleshooting
Q: I’m getting "missing or invalid Authorization header"
A: Include the header correctly:
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...Note the space between "Bearer" and the token.
Q: I’m getting "token not valid"
A: Your token has expired. Get a new one from EQUOS ID.
Q: I’m getting "api key revoked"
A: Your API key was deleted. Create a new one.
Q: All my requests are getting 429
A: You’re making too many concurrent requests. Reduce concurrency or queue orders.
Q: Orders are stuck in "pending" status
A: This is unusual. Contact support if jobs don't progress within 30 seconds.
Q: How do I debug what went wrong?
A: Check the job status API response. The error field will have details about what failed.
Feature Requests & Support
Q: Can I request a new feature?
A: Contact your account manager or sales team.
Q: What’s your SLA?
A: There is no uptime SLA and no service credits. Equos.one is provided as is and as available by EQUOS 9 PROPRIETARY LTD. See the Terms of Service.
Q: Who do I contact for support?
A: Email api-support@equosnine.com or contact your account manager.
Q: Is there a community slack/discord?
A: Currently email support. We’re building a community platform.
Q: Can I report a bug?
A: Email api-support@equosnine.com with details and logs.
Pricing & Limits
Q: Is the API free?
A: API access is included with Equos. Data limits depend on your plan.
Q: Are there usage-based costs?
A: Not per API call. Costs are based on order count and storage.
Q: What’s the maximum order size?
A: Up to 10,000 line items per order. Contact support for larger orders.
Q: How long are orders retained?
A: Indefinitely. Archive or delete manually as needed.
Didn’t find what you’re looking for? Email api-support@equosnine.com