1. Overview
This API Usage Policy (“Policy”) supplements the CartOS Developer Terms of Service and governs your use of the CartOS REST API. It establishes technical guidelines, rate limits, data handling requirements, and acceptable use standards designed to ensure the stability, security, and performance of the CartOS platform for all Merchants and developers.
All developers with active API keys are expected to comply with this Policy. Failure to comply may result in rate limiting, API key suspension, or account termination.
2. Rate Limits
API requests are rate limited per API key to ensure fair usage and platform stability. Rate limits are applied on a sliding window basis.
2.1 Standard Limits
Standard Tier
Up to 2 requests per second and 10,000 requests per day per API key.
Growth Tier
Up to 5 requests per second and 50,000 requests per day per API key.
Professional Tier
Up to 10 requests per second and 200,000 requests per day per API key.
Enterprise Tier
Custom limits negotiated per agreement. Contact developers@cart-os.com.
2.2 Rate Limit Headers
Every API response includes rate limit information in the following headers:
| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum requests allowed in the current window |
X-RateLimit-Remaining | Number of requests remaining in the current window |
X-RateLimit-Reset | Unix timestamp when the rate limit window resets |
Retry-After | Seconds to wait before retrying (only present on 429 responses) |
2.3 Rate Limit Responses
When you exceed your rate limit, the API returns a 429 Too Many Requests response. Your application must respect the Retry-After header and implement exponential backoff. Repeatedly ignoring rate limits may result in temporary or permanent API key suspension.
X-RateLimit-Remaining header and throttle your requests proactively rather than waiting for 429 responses. This ensures a smoother experience for your integration and for the Merchants you serve.2.4 Burst Allowance
Short bursts that briefly exceed the per-second limit are tolerated within reason (up to 2x the per-second limit for 5 seconds). Sustained traffic above the limit will trigger rate limiting. Do not rely on burst allowance for normal operations.
3. Authentication Requirements
3.1 Transport Security
All API requests must be made over HTTPS (TLS 1.2 or higher). Requests made over plain HTTP will be rejected. We do not support TLS 1.0 or 1.1.
3.2 API Key Security
You must treat API keys as sensitive credentials. You are required to store API keys in environment variables or secure credential stores — never hardcode them in source code. You must not expose API keys in client-side code (JavaScript, mobile apps, or browser extensions), commit API keys to version control systems (even private repositories), or share API keys via unencrypted channels such as email, Slack, or chat.
3.3 Key Rotation
We recommend rotating your API keys periodically (at minimum every 12 months). If you suspect a key has been compromised, immediately contact us at security@cart-os.com to revoke the key and issue a replacement. We reserve the right to force-rotate keys that appear compromised.
4. Scope & Access Control
4.1 Principle of Least Privilege
Request only the API scopes your integration genuinely needs. A fulfillment integration that only reads orders and updates shipping status should not request customers:write or products:write scopes. We review scope requests during the application process and may deny or narrow scope requests that appear excessive for the stated use case.
4.2 Scope Changes
If your integration’s requirements change and you need additional scopes, submit a scope expansion request through the developer portal with a written justification. Scope changes are reviewed within 5 business days.
4.3 Per-Merchant Authorization
Merchants control which Developer Applications have access to their store data. If a Merchant revokes your access, your API key will no longer function for that store. You must handle authorization revocation gracefully in your application and must not attempt to circumvent a Merchant’s access decisions.
5. Data Handling Requirements
5.1 Data Minimization
Collect only the data fields your integration requires. If you only need product titles and prices, do not store full product descriptions, images, or metadata. Use API query parameters and field selectors to limit the data you retrieve.
5.2 Storage Requirements
If your integration stores Merchant Data locally (cached or persisted), you must encrypt data at rest using AES-256 or equivalent, implement access controls limiting who within your organization can view the data, maintain logs of data access for audit purposes, and store data in infrastructure that meets SOC 2 Type II or equivalent security standards, or implement equivalent controls.
5.3 Data Deletion
You must delete Merchant Data when it is no longer necessary for your integration’s functionality, within 30 days when a Merchant uninstalls your Developer Application, within 30 days when a Merchant revokes your API access, promptly upon receiving a deletion request from a Merchant or from Salloq, and upon termination of your developer account. Exceptions apply only where data retention is required by applicable law, in which case you must document the legal basis and retention period.
5.4 Customer Personal Data
Customer personal data accessed through the API (names, emails, addresses, phone numbers, purchase history) is subject to heightened protection requirements. You must not use customer personal data for marketing or advertising purposes unless you have obtained direct, explicit consent from the individual. You must not aggregate customer data across multiple Merchants to build profiles or datasets. You must honor data subject access requests (DSARs) and deletion requests in accordance with applicable privacy laws.
6. Acceptable Use
6.1 Request Efficiency
Design your integration for efficiency. Use pagination to retrieve large datasets incrementally rather than requesting all records at once. Use webhook subscriptions for real-time event notification instead of polling endpoints for changes. Cache responses locally where appropriate (see Caching Policy). Use bulk endpoints when available rather than making individual requests per record. Set reasonable per_page values — requesting the maximum (100) when you only need 10 records wastes resources.
6.2 Error Handling
Your integration must handle API errors gracefully. Implement exponential backoff with jitter for retries on 429 and 5xx responses. Do not retry 4xx client errors (except 429) as these indicate issues with your request that retrying will not resolve. Set a maximum retry count (we recommend 3 attempts) to avoid infinite retry loops. Log errors for debugging without exposing sensitive data in logs.
6.3 User-Agent Header
Include a descriptive User-Agent header in all API requests identifying your application. This helps us provide better support and troubleshoot issues.
User-Agent: YourAppName/1.0.0 (contact@yourcompany.com)7. Prohibited Activities
The following activities are strictly prohibited and may result in immediate API key revocation and account termination:
- Competitive data harvesting: Systematically collecting Merchant Data (product catalogs, pricing, customer lists) to benefit a competing e-commerce platform or to resell as datasets.
- Credential stuffing or brute force: Attempting to guess or brute-force API keys, authentication tokens, or any other credentials.
- API abuse for denial of service: Intentionally sending high volumes of requests to degrade platform performance for others.
- Circumventing rate limits: Creating multiple developer accounts, rotating API keys, or using distributed systems to circumvent rate limit enforcement.
- Unauthorized scope escalation: Exploiting vulnerabilities to access API endpoints or data beyond your granted scopes.
- Data exfiltration: Bulk downloading Merchant Data for purposes unrelated to your Developer Application’s stated functionality.
- Injecting malicious content: Using write endpoints to inject malicious code, scripts, or content into Merchant stores.
- Impersonation: Making API requests that impersonate another developer, Merchant, or Salloq.
- Shadow integrations: Using a Merchant’s own API credentials to operate a third-party integration without the Merchant’s informed consent.
8. Webhook Requirements
8.1 Endpoint Requirements
Webhook receiver endpoints must be served over HTTPS with a valid TLS certificate, respond with a 2xx status code within 10 seconds to acknowledge receipt, and be idempotent — capable of safely receiving the same webhook event more than once.
8.2 Signature Verification
All webhook payloads include an X-CartOS-Signature header containing an HMAC-SHA256 signature. You must verify this signature before processing any webhook data to ensure the request originated from CartOS and has not been tampered with. Failing to verify webhook signatures is a security vulnerability.
8.3 Retry Behavior
If your endpoint fails to respond with a 2xx status within 10 seconds, CartOS will retry delivery with exponential backoff for up to 24 hours. After repeated failures (more than 48 hours of consecutive failures), we may disable the webhook subscription and notify you via email.
8.4 Processing Best Practices
Acknowledge webhooks immediately by returning a 200 response, then process the payload asynchronously. Do not perform long-running operations (database writes, external API calls, email sending) synchronously within the webhook handler. Use a queue to process webhook payloads reliably.
9. Caching Policy
9.1 What to Cache
Caching API responses locally reduces load on the platform and improves your application’s performance. We encourage caching product catalog data, collection data, and other relatively static data. Always cache full API responses along with their timestamp.
9.2 Cache Durations
| Data Type | Recommended TTL | Notes |
|---|---|---|
| Product catalog | 5–15 minutes | Use webhooks for real-time updates |
| Collection data | 15–30 minutes | Collections change infrequently |
| Order data | 1–2 minutes | Orders may update frequently during fulfillment |
| Customer data | 5 minutes | Ensure freshness for support workflows |
| Inventory levels | 30–60 seconds | Critical for availability accuracy |
9.3 Cache Invalidation
Use webhook events to invalidate cached data in real-time rather than relying solely on TTL-based expiration. For example, when you receive an order.updated webhook, immediately invalidate any cached data for that order.
10. API Versioning & Deprecation
10.1 Versioning
The CartOS API may introduce new versions over time. When breaking changes are necessary, we will release a new API version and maintain the previous version for a deprecation period. Non-breaking changes (new fields, new endpoints, new optional parameters) may be added to the current version without a version bump.
10.2 Deprecation Policy
When an API version or endpoint is deprecated, we will provide at least 6 months’ notice before removal, announce the deprecation in the developer portal and via email, include a Sunset header in responses from deprecated endpoints indicating the removal date, and provide migration guides to help you update your integration.
10.3 Your Responsibility
You are responsible for monitoring deprecation notices and migrating your integration to supported API versions within the deprecation period. After the removal date, deprecated endpoints will return 410 Gone responses.
11. Monitoring & Enforcement
11.1 Usage Monitoring
We monitor API usage patterns for security, performance, and compliance purposes. Monitoring includes request volumes and rate limit compliance, error rates and response patterns, data access patterns and scope utilization, and geographic distribution of requests.
11.2 Enforcement Actions
Violations of this Policy may result in graduated enforcement actions:
- Warning: Email notification identifying the violation and requesting corrective action within a specified timeframe.
- Rate limit reduction: Temporary reduction of your rate limits while the issue is addressed.
- Temporary suspension: API key suspension for a defined period (typically 24–72 hours) for repeated or serious violations.
- Permanent revocation: API key and developer account termination for severe or persistent violations.
We reserve the right to skip graduated steps and take immediate action for severe violations that threaten platform security or stability.
11.3 Appeals
If you believe an enforcement action was taken in error, you may appeal by emailing developers@cart-os.com with a detailed explanation within 14 days of the action. Appeals are reviewed within 5 business days.
12. Reporting Issues
12.1 Security Vulnerabilities
If you discover a security vulnerability in the CartOS API, please report it responsibly to security@cart-os.com. Do not publicly disclose vulnerabilities before they have been addressed. We appreciate responsible disclosure and will acknowledge your contribution.
12.2 Abuse Reports
If you become aware of another developer or integration misusing the API or violating this Policy, please report it to developers@cart-os.com.
12.3 Support
For technical questions about API usage, rate limits, or this Policy, contact us at developers@cart-os.com. For general API questions, consult the API Reference first.