> ## Documentation Index > Fetch the complete documentation index at: https://docs.returnqueen.dev/llms.txt > Use this file to discover all available pages before exploring further. # Overview The ReturnQueen Platform API is a RESTful interface that allows partners to programmatically integrate with the ReturnQueen platform. This API follows industry standard practices and uses JSON for request and response payloads. Our API enables you to: * **Manage Shipments:** Create, retrieve, update, and track return shipments individually or in batches * **Check Availability:** Query available pickup time slots for specific locations * **Configure Webhooks:** Set up real-time notifications for important shipment events * **Audit Changes:** Track the complete history of changes to shipments This reference documentation is based on OpenAPI 3.0 specification and provides detailed information about each endpoint, including request parameters, response structures, and examples. ## Authentication ### API Keys All ReturnQueen Platform API requests require authentication using an API key. Include your unique key in the `X-API-KEY` HTTP header with every request: ```bash theme={null} X-API-KEY: your_api_key_here ``` **Security Best Practices** * Store your API key securely in environment variables or a secure key management system * Never expose your API key in client-side code, public repositories, or browser-accessible files * Implement proper key rotation procedures in your production environment * Contact support immediately if you suspect your key has been compromised You can manage your API keys through the ReturnQueen partner dashboard. Each key has specific permissions and can be scoped to certain operations as needed. ## Base URL All API requests should be made to the following base URL: ``` https://platform.returnqueen.dev/api ``` ## Request Format The API accepts request bodies formatted as JSON with the appropriate `Content-Type` header: ``` Content-Type: application/json ``` ## Response Format All API responses are returned in JSON format. A successful response will have: * An appropriate HTTP status code (200, 201, etc.) * A JSON response body containing the requested data ```json theme={null} { "id": "37b99b40-7f9c-4dad-be80-a9619a468efa", "order_number": "RQ-12345", // Additional properties... } ``` ## Error Handling When an error occurs, the API returns: * An appropriate HTTP status code (4xx for client errors, 5xx for server errors) * A JSON response body with details about the error ```json theme={null} { "errors": [ { "title": "Invalid value", "source": { "pointer": "/data/attributes/order_number" }, "detail": "order_number is required" } ] } ``` ### Common Error Codes | Status Code | Description | Possible Solution | | ----------- | -------------------- | ---------------------------------------------------------------- | | 400 | Bad Request | Verify the request payload format and required fields | | 401 | Unauthorized | Check your API key is valid and properly included in the header | | 404 | Not Found | Confirm the resource ID exists and is accessible to your account | | 422 | Unprocessable Entity | Review the error details to fix validation issues | | 429 | Rate Limited | Reduce request frequency or implement backoff strategies | | 500 | Server Error | Contact support with request details for assistance | ## Rate Limiting The ReturnQueen Platform API implements rate limiting to ensure platform stability. Current limits are: * **Standard tier:** 60 requests per minute * **Enterprise tier:** 300 requests per minute If you exceed these limits, you'll receive a `429 Too Many Requests` response. Implement appropriate retry logic with exponential backoff in your integration. ## Webhooks Webhooks allow your application to receive real-time notifications about events within the ReturnQueen platform. To receive webhooks: 1. Create a webhook endpoint in your application that can process incoming POST requests 2. Register your endpoint URL using the Partner Webhooks API 3. Implement signature verification to validate incoming webhooks See the [Webhooks](/api-reference/webhooks/create) section for detailed implementation guidance. ## Available Endpoints The ReturnQueen Platform API provides the following endpoints, organized by resource type. Click on any card to access detailed documentation for that specific endpoint. ### Shipments Manage return shipments for your customers. Create a new return shipment with customer and package details Retrieve details of an existing shipment by ID Update an existing shipment's details Cancel an existing shipment by ID Create multiple shipments in a single request for efficiency View the complete audit trail for a shipment ### Availability Check for available pickup time slots. Retrieve available pickup time slots for a given zip code. ### Webhooks Set up and manage real-time notifications for your integration. View all configured webhook endpoints for your account Register a new webhook endpoint to receive event notifications Get details of a specific webhook endpoint Update an existing webhook configuration Remove an existing webhook configuration Temporarily disable a webhook endpoint Re-enable a disabled webhook endpoint List all available webhook event types Send a test event to verify webhook configuration *** Each endpoint page provides comprehensive details including required parameters, request body schemas, response formats, and example usage.