API Overview
The ReBattery Supplier API lets approved suppliers sync battery inventory directly into ReBattery, so listings can be routed towards resale, reuse, or recycling through verified partners and managed compliance workflows. This is not a simple marketplace listing tool — it is an integration layer that feeds inventory into a managed supply chain with routing logic based on battery condition, chemistry, and regulatory requirements.
The API is intended for supplier ERP integrations, ingestion scripts, and automated partner feeds. It is designed to be predictable, with JSON request bodies and standard HTTP response codes.
Base URL
All API requests should be directed to the following base URL:
https://rebattery.io/api/v1
Sandbox and test environment URLs are provided by your ReBattery contact during onboarding.
Authentication
The ReBattery Supplier API uses Bearer token authentication. All requests must include an Authorization header with a valid API key:
Authorization: Bearer <your-api-key>
API keys are created and managed from Settings → API Keys in your ReBattery account. Only the account owner can generate keys. Each key is shown exactly once at creation — copy and store it securely, as it cannot be retrieved again.
If a token is invalid, missing, or expired, the API returns a generic 401 response with no additional detail. This prevents token enumeration.
All requests must be made over HTTPS. Unencrypted HTTP requests are rejected.
[!WARNING] Store your API keys in a secure secrets manager or environment variable. Never commit them to version control or expose them in client-side code.
Scopes
Each API key must include the scope required by the endpoint it calls:
| Scope | Description |
|---|---|
listings:write | Create new listings and submit inventory to the ReBattery routing workflow. |
Rate Limits
The API enforces a limit of 100 requests per 60-second window per API key.
If you exceed the limit, the API returns a 429 Too Many Requests response with the following headers:
| Header | Description |
|---|---|
Retry-After | Seconds to wait before retrying. |
X-RateLimit-Limit | Maximum requests allowed per window. |
X-RateLimit-Remaining | Requests remaining in the current window. |
X-RateLimit-Reset | Unix timestamp when the current window resets. |
[!TIP] Implement exponential backoff with jitter in your integration to handle rate-limit responses gracefully. A typical approach retries after 1, 2, 4, 8, and 16 seconds.
Idempotency
To safely retry requests without duplicating side effects, include an Idempotency-Key header with a unique string between 1 and 255 characters:
Idempotency-Key: <unique-key>
If the same key and request body are resent within a 24-hour window, the API returns the original response without reprocessing. If the same key is reused with a different request body, the request is rejected with 409 Conflict. If a request with that key is still being processed, the API returns 425 Too Early.
[!NOTE] We recommend using UUIDs as idempotency keys. Most programming languages include a standard library function to generate v4 UUIDs securely.
Request Limits
- Maximum request body size: 40 MB
- Request body: JSON object
Requests that exceed the body limit receive 413 Payload Too Large. Malformed JSON receives 400 Invalid JSON body.
Versioning
The current API is v1, accessible at /api/v1. Breaking changes will be introduced under a new versioned path (e.g., /api/v2). Non-breaking changes, such as additional optional fields in existing responses, may be added to v1 without prior notice. Your integration should ignore unknown fields rather than fail on them.