Skip to main content
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: 
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
{
  "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
{
  "errors": [
    {
      "title": "Invalid value",
      "source": {
        "pointer": "/data/attributes/order_number"
      },
      "detail": "order_number is required"
    }
  ]
}

​
Common Error Codes

Status CodeDescriptionPossible Solution
400Bad RequestVerify the request payload format and required fields
401UnauthorizedCheck your API key is valid and properly included in the header
404Not FoundConfirm the resource ID exists and is accessible to your account
422Unprocessable EntityReview the error details to fix validation issues
429Rate LimitedReduce request frequency or implement backoff strategies
500Server ErrorContact 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 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 Shipment

Create a new return shipment with customer and package details

Get Shipment

Retrieve details of an existing shipment by ID

Update Shipment

Update an existing shipment’s details

Cancel Shipment

Cancel an existing shipment by ID

Batch Create

Create multiple shipments in a single request for efficiency

Audit History

View the complete audit trail for a shipment

​
Availability

Check for available pickup time slots.

Get Availability

Retrieve available pickup time slots for a given zip code.

​
Webhooks

Set up and manage real-time notifications for your integration.

List Webhooks

View all configured webhook endpoints for your account

Create Webhook

Register a new webhook endpoint to receive event notifications

Show Webhook

Get details of a specific webhook endpoint

Update Webhook

Update an existing webhook configuration

Delete Webhook

Remove an existing webhook configuration

Disable Webhook

Temporarily disable a webhook endpoint

Enable Webhook

Re-enable a disabled webhook endpoint

Event Types

List all available webhook event types

Test Webhook

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.