Returns management is an essential part of the customer experience and inventory control. This guide shows you how to create Return Merchandise Authorizations (RMAs) and track return disposition data using the Trackstar API.

​
Overview

The returns workflow typically involves:
  1. Creating RMAs for customer return requests
  2. Tracking return status and disposition data
  3. Managing returned inventory

​
Creating RMAs

Use the Create Return endpoint to create Return Merchandise Authorizations for customer return requests.
For a full list of fields that need to be passed in, see the Programmatic Writes guide.

​
Create the Return

curl -X POST https://production.trackstarhq.com/wms/returns \
  -H "Content-Type: application/json" \
  -H "x-trackstar-api-key: YOUR_API_KEY" \
  -H "x-trackstar-access-token: YOUR_ACCESS_TOKEN" \
  -d '{
    "warehouse_id": "warehouse_main",
    "order_id": "order_abc123",
    "line_items": [
      {"sku": "WIDGET-001", "quantity": 1},
      {"sku": "GADGET-002", "quantity": 2}
    ]
  }'

​
Sample Response

{
  "data": {
    "id": "return_abc123",
    "warehouse_customer_id": "customer_12345",
    "created_date": "2024-01-20T10:00:00Z",
    "updated_date": "2024-01-20T10:00:00Z",
    "status": "open",
    "raw_status": "awaiting_return",
    "order_id": "order_abc123",
    "notes": ["Customer reported item too small"],
    "line_items": [
      {
        "inventory_item_id": "inv_widget001_main",
        "sku": "WIDGET-001",
        "expected_quantity": 1,
        "received_quantity": 0,
        "restocked_quantity": 0,
        "return_reason": "Too Small",
        "quantity": 0
      },
      {
        "inventory_item_id": "inv_gadget002_main",
        "sku": "GADGET-002",
        "expected_quantity": 2,
        "received_quantity": 0,
        "restocked_quantity": 0,
        "return_reason": "Defective",
        "quantity": 0
      }
    ],
    "shipments": [],
    "external_system_url": "https://wms.example.com/returns/return_abc123",
    "trackstar_tags": ["priority", {"type": "quality_issue"}],
    "additional_fields": {
      "return_notes": "Handle with care - inspect for defects",
      "customer_tier": "gold"
    }
  }
}

​
Tracking Return Disposition Data

Once RMAs are created, you can track their progress and disposition using the Get Return endpoint.

​
Fetch the Return

curl -X GET https://production.trackstarhq.com/wms/returns/return_abc123 \
  -H "x-trackstar-api-key: YOUR_API_KEY" \
  -H "x-trackstar-access-token: YOUR_ACCESS_TOKEN"

​
Sample Response

{
  "data": {
    "id": "return_abc123",
    "warehouse_customer_id": "customer_12345",
    "created_date": "2024-01-20T10:00:00Z",
    "updated_date": "2024-01-22T15:30:00Z",
    "status": "received",
    "raw_status": "processing_complete",
    "order_id": "order_abc123",
    "notes": ["Customer reported item too small", "Items received and processed"],
    "line_items": [
      {
        "inventory_item_id": "inv_widget001_main",
        "sku": "WIDGET-001",
        "expected_quantity": 1,
        "received_quantity": 1,
        "restocked_quantity": 1,
        "return_reason": "Too Small",
        "quantity": 1
      },
      {
        "inventory_item_id": "inv_gadget002_main",
        "sku": "GADGET-002",
        "expected_quantity": 1,
        "received_quantity": 1,
        "restocked_quantity": 0,
        "return_reason": "Defective",
        "quantity": 1
      }
    ],
    "shipments": [
      {
        "tracking_number": "1Z999AA1234567890",
        "shipped_date": "2024-01-21T09:00:00Z",
        "arrived_date": "2024-01-22T14:00:00Z",
        "warehouse_id": "warehouse_main",
        "carrier": "UPS",
        "shipping_cost": 12.50,
        "measurements": {
          "length": 12.0,
          "width": 8.0,
          "height": 6.0,
          "unit": "in",
          "weight": 3.5,
          "weight_unit": "lb"
        },
        "line_items": [
          {
            "inventory_item_id": "inv_widget001_main",
            "sku": "WIDGET-001",
            "quantity": 1,
            "receiving_details": [
              {
                "quantity": 1,
                "condition": "good",
                "disposition": "restocked"
              }
            ]
          },
          {
            "inventory_item_id": "inv_gadget002_main",
            "sku": "GADGET-002",
            "quantity": 1,
            "receiving_details": [
              {
                "quantity": 1,
                "condition": "damaged",
                "disposition": "scrapped"
              }
            ]
          }
        ]
      }
    ],
    "external_system_url": "https://wms.example.com/returns/return_abc123",
    "trackstar_tags": ["priority", {"type": "quality_issue"}],
    "additional_fields": {
      "return_notes": "Handle with care - inspect for defects",
      "customer_tier": "gold"
    }
  }
}

​
Real-time Updates

Utilize webhooks to get notified each time there is an update to an RMA by subscribing to return.updated events.

​
Return Status Workflow

Returns progress through various stages as they move through the processing system. For detailed information about all available return statuses and their meanings, see the Returns Info page.

​
Best Practices

​
Return Creation

  • Always link returns to the original order using order_id
  • Specify the correct warehouse that will receive the return
  • Validate SKUs and quantities before creating returns
  • Ensure line items match products from the original order

​
Disposition Tracking

  • Regularly fetch return status updates to monitor progress
  • Track individual line item statuses within returns
  • Monitor the overall return workflow from creation to completion