API Reference

ReturnMate provides a REST API for programmatic access to your returns data. Use the API to integrate with custom systems, build reporting dashboards, or automate workflows.

Getting Started

Base URL

All API requests use the base URL:

https://api.returnmate.io/v1

Authentication

Authenticate using API keys in the request header:

curl -X GET "https://api.returnmate.io/v1/rmas" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Creating an API Key

1. Go to Settings → Integrations → API
2. Click Create API Key
3. Name the key (e.g., "Reporting Dashboard")
4. Select permissions
5. Copy the key (shown only once)

API Key Permissions

When creating keys, select only required permissions:

Rate Limits

Rate limit headers are included in responses:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 115
X-RateLimit-Reset: 1704067200

Response Format

All responses are JSON:

{
  "success": true,
  "data": { ... },
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 150
  }
}

Error responses:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid order number format",
    "details": { ... }
  }
}

Endpoints

RMAs

List RMAs

GET /v1/rmas

Query parameters:

Example:

curl -X GET "https://api.returnmate.io/v1/rmas?status=pending&per_page=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "success": true,
  "data": [
    {
      "id": "rma_abc123",
      "rma_number": "RMA-2024-001234",
      "status": "pending",
      "order_number": "#1001",
      "customer": {
        "email": "customer@example.com",
        "name": "John Smith"
      },
      "items": [...],
      "created_at": "2024-12-30T10:30:00Z"
    }
  ],
  "meta": { "page": 1, "per_page": 50, "total": 150 }
}

Get RMA

GET /v1/rmas/{id}

Returns full RMA details including items, shipments, and timeline.

Create RMA

POST /v1/rmas

Request body:

{
  "order_number": "#1001",
  "customer_email": "customer@example.com",
  "items": [
    {
      "sku": "PROD-001",
      "quantity": 1,
      "reason": "defective",
      "notes": "Screen not working"
    }
  ],
  "return_type": "refund"
}

Update RMA

PATCH /v1/rmas/{id}

Request body:

{
  "status": "approved",
  "notes": "Approved for full refund"
}

Add Note to RMA

POST /v1/rmas/{id}/notes

{
  "content": "Customer contacted about delay",
  "internal": true
}

Shipments

List Shipments

GET /v1/shipments

Get Shipment

GET /v1/shipments/{id}

Create Shipping Label

POST /v1/rmas/{id}/shipments

{
  "carrier": "australia_post",
  "service": "express_post",
  "direction": "return"
}

Response includes label URL and tracking number.

Track Shipment

GET /v1/shipments/{id}/tracking

Returns tracking events from the carrier.

Customers

Get Customer Returns

GET /v1/customers/{email}/rmas

Customer Return History

GET /v1/customers/{email}/stats

Response:

{
  "total_returns": 5,
  "total_refunded": 450.00,
  "return_rate": 12.5,
  "last_return": "2024-12-15T08:00:00Z"
}

Reports

Returns Summary

GET /v1/reports/returns

Query parameters:

Response:

{
  "data": {
    "total_rmas": 150,
    "total_refunded": 12500.00,
    "by_status": {
      "completed": 120,
      "pending": 20,
      "rejected": 10
    },
    "by_reason": {
      "defective": 45,
      "wrong_size": 60,
      "changed_mind": 45
    }
  }
}

Reason Analytics

GET /v1/reports/reasons

Carrier Performance

GET /v1/reports/carriers

Pagination

List endpoints support pagination:

GET /v1/rmas?page=2&per_page=25

Response includes pagination metadata:

{
  "meta": {
    "page": 2,
    "per_page": 25,
    "total": 150,
    "total_pages": 6
  }
}

Filtering

Most list endpoints support filters:

# Multiple filters with AND logic
GET /v1/rmas?status=pending&created_after=2024-12-01

# Multiple values for same filter with OR logic
GET /v1/rmas?status[]=pending&status[]=approved

Sorting

Use sort and order parameters:

GET /v1/rmas?sort=created_at&order=desc

Error Codes

SDKs

Official SDKs available:

Node.js Example

const ReturnMate = require('@returnmate/sdk');

const client = new ReturnMate({
  apiKey: 'YOUR_API_KEY'
});

// List recent RMAs
const rmas = await client.rmas.list({
  status: 'pending',
  perPage: 50
});

// Create new RMA
const newRma = await client.rmas.create({
  orderNumber: '#1001',
  customerEmail: 'customer@example.com',
  items: [{
    sku: 'PROD-001',
    quantity: 1,
    reason: 'defective'
  }]
});

Python Example

from returnmate import ReturnMate

client = ReturnMate(api_key='YOUR_API_KEY')

# List RMAs
rmas = client.rmas.list(status='pending', per_page=50)

# Get specific RMA
rma = client.rmas.get('rma_abc123')

# Update RMA status
client.rmas.update('rma_abc123', status='approved')

Testing

Use sandbox mode for development:

Base URL: https://api.sandbox.returnmate.io/v1

Sandbox mode:

• Uses test data
• Labels aren't real
• No carrier charges
• Safe for development

Best Practices

• Use minimal permissions for API keys
• Store keys securely (environment variables)
• Handle rate limits gracefully with backoff
• Implement error handling for all requests
• Use pagination for large datasets
• Cache responses where appropriate
• Monitor API usage via dashboard

Related Articles

• Webhooks Reference
• Integrations Overview
• Workflow Automations