> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trackstarhq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Returns

> Learn how to create RMAs and track disposition data using the Trackstar API

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](/api-reference/wms-api/returns/post) to create Return Merchandise Authorizations for customer return requests.

<Tip>For a full list of fields that need to be passed in, see the [Programmatic Writes guide](/how-to-guides/programmatic-writes).</Tip>

### Create the Return

<CodeGroup>
  ```bash cURL theme={null}
  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}
      ]
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://production.trackstarhq.com/wms/returns"

  headers = {
      "Content-Type": "application/json",
      "x-trackstar-api-key": "YOUR_API_KEY",
      "x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
  }

  payload = {
      "warehouse_id": "warehouse_main",
      "order_id": "order_abc123",
      "line_items": [
          {"sku": "WIDGET-001", "quantity": 1},
          {"sku": "GADGET-002", "quantity": 2}
      ]
  }

  response = requests.post(url, headers=headers, json=payload)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const url = "https://production.trackstarhq.com/wms/returns";

  const payload = {
    warehouse_id: "warehouse_main",
    order_id: "order_abc123",
    line_items: [
      { sku: "WIDGET-001", quantity: 1 },
      { sku: "GADGET-002", quantity: 2 }
    ]
  };

  fetch(url, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-trackstar-api-key": "YOUR_API_KEY",
      "x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
    },
    body: JSON.stringify(payload)
  })
  .then(response => response.json())
  .then(data => console.log(data));
  ```

  ```php PHP theme={null}
  <?php
  $url = "https://production.trackstarhq.com/wms/returns";

  $payload = [
      "warehouse_id" => "warehouse_main",
      "order_id" => "order_abc123",
      "line_items" => [
          ["sku" => "WIDGET-001", "quantity" => 1],
          ["sku" => "GADGET-002", "quantity" => 2]
      ]
  ];

  $options = [
      "http" => [
          "header" =>
              "Content-Type: application/json\r\n" .
              "x-trackstar-api-key: YOUR_API_KEY\r\n" .
              "x-trackstar-access-token: YOUR_ACCESS_TOKEN\r\n",
          "method" => "POST",
          "content" => json_encode($payload)
      ]
  ];

  $context = stream_context_create($options);
  $response = file_get_contents($url, false, $context);
  echo $response;
  ?>
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "encoding/json"
      "fmt"
      "net/http"
  )

  type LineItem struct {
      SKU      string `json:"sku"`
      Quantity int    `json:"quantity"`
  }

  type ReturnRequest struct {
      WarehouseID string     `json:"warehouse_id"`
      OrderID     string     `json:"order_id"`
      LineItems   []LineItem `json:"line_items"`
  }

  func main() {
      url := "https://production.trackstarhq.com/wms/returns"

      reqBody := ReturnRequest{
          WarehouseID: "warehouse_main",
          OrderID:     "order_abc123",
          LineItems: []LineItem{
              {SKU: "WIDGET-001", Quantity: 1},
              {SKU: "GADGET-002", Quantity: 2},
          },
      }

      jsonData, _ := json.Marshal(reqBody)

      req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
      req.Header.Set("Content-Type", "application/json")
      req.Header.Set("x-trackstar-api-key", "YOUR_API_KEY")
      req.Header.Set("x-trackstar-access-token", "YOUR_ACCESS_TOKEN")

      client := &http.Client{}
      resp, err := client.Do(req)
      if err != nil {
          panic(err)
      }
      defer resp.Body.Close()

      fmt.Println("Response Status:", resp.Status)
  }
  ```

  ```java Java theme={null}
  import java.io.IOException;
  import java.net.URI;
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;

  public class TrackstarCreateReturnExample {
      public static void main(String[] args) throws IOException, InterruptedException {
          String url = "https://production.trackstarhq.com/wms/returns";

          String jsonPayload = """
          {
            "warehouse_id": "warehouse_main",
            "order_id": "order_abc123",
            "line_items": [
              {"sku": "WIDGET-001", "quantity": 1},
              {"sku": "GADGET-002", "quantity": 2}
            ]
          }
          """;

          HttpClient client = HttpClient.newHttpClient();
          HttpRequest request = HttpRequest.newBuilder()
              .uri(URI.create(url))
              .header("Content-Type", "application/json")
              .header("x-trackstar-api-key", "YOUR_API_KEY")
              .header("x-trackstar-access-token", "YOUR_ACCESS_TOKEN")
              .POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
              .build();

          HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
          System.out.println("Status: " + response.statusCode());
          System.out.println("Body: " + response.body());
      }
  }
  ```

  ```ruby Ruby theme={null}
  require 'net/http'
  require 'json'
  require 'uri'

  url = URI('https://production.trackstarhq.com/wms/returns')

  payload = {
    warehouse_id: "warehouse_main",
    order_id: "order_abc123",
    line_items: [
      { sku: "WIDGET-001", quantity: 1 },
      { sku: "GADGET-002", quantity: 2 }
    ]
  }

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true

  request = Net::HTTP::Post.new(url)
  request['Content-Type'] = 'application/json'
  request['x-trackstar-api-key'] = 'YOUR_API_KEY'
  request['x-trackstar-access-token'] = 'YOUR_ACCESS_TOKEN'
  request.body = payload.to_json

  response = http.request(request)
  puts "Status: #{response.code}"
  puts "Response: #{response.body}"
  ```
</CodeGroup>

### Sample Response

```json theme={null}
{
  "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](/api-reference/wms-api/returns/get-item).

### Fetch the Return

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```

  ```python Python theme={null}
  import requests

  url = "https://production.trackstarhq.com/wms/returns/return_abc123"

  headers = {
    "x-trackstar-api-key": "YOUR_API_KEY",
    "x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
  }

  response = requests.get(url, headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const url = "https://production.trackstarhq.com/wms/returns/return_abc123";

  fetch(url, {
    method: "GET",
    headers: {
    "x-trackstar-api-key": "YOUR_API_KEY",
    "x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
    }
  })
  .then(response => response.json())
  .then(data => console.log(data));
  ```

  ```php PHP theme={null}
  <?php
  $url = "https://production.trackstarhq.com/wms/returns/return_abc123";

  $options = [
    "http" => [
      "header" =>
        "x-trackstar-api-key: YOUR_API_KEY\r\n" .
        "x-trackstar-access-token: YOUR_ACCESS_TOKEN\r\n",
      "method" => "GET"
    ]
  ];

  $context = stream_context_create($options);
  $response = file_get_contents($url, false, $context);
  $response === false ? print_r(error_get_last()) : print($response);
  ?>
  ```

  ```go Go theme={null}
  package main

  import (
    "fmt"
    "io"
    "net/http"
  )

  func main() {
    url := "https://production.trackstarhq.com/wms/returns/return_abc123"

    req, _ := http.NewRequest("GET", url, nil)
    req.Header.Set("x-trackstar-api-key", "YOUR_API_KEY")
    req.Header.Set("x-trackstar-access-token", "YOUR_ACCESS_TOKEN")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
      panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
  }
  ```

  ```java Java theme={null}
  import java.io.IOException;
  import java.net.URI;
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;

  public class TrackstarGetReturnExample {
    public static void main(String[] args) throws IOException, InterruptedException {
      String url = "https://production.trackstarhq.com/wms/returns/return_abc123";

      HttpClient client = HttpClient.newHttpClient();
      HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(url))
        .header("x-trackstar-api-key", "YOUR_API_KEY")
        .header("x-trackstar-access-token", "YOUR_ACCESS_TOKEN")
        .GET()
        .build();

      HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
      System.out.println("Status: " + response.statusCode());
      System.out.println("Body: " + response.body());
    }
  }
  ```

  ```ruby Ruby theme={null}
  require 'net/http'
  require 'uri'

  url = URI('https://production.trackstarhq.com/wms/returns/return_abc123')

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true

  request = Net::HTTP::Get.new(url)
  request['x-trackstar-api-key'] = 'YOUR_API_KEY'
  request['x-trackstar-access-token'] = 'YOUR_ACCESS_TOKEN'

  response = http.request(request)
  puts "Status: #{response.code}"
  puts "Response: #{response.body}"
  ```
</CodeGroup>

### Sample Response

```json theme={null}
{
  "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](/how-to-guides/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](/api-reference/wms-api/returns/info).

## 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