Returns

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:

Creating RMAs for customer return requests
Tracking return status and disposition data
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}
    ]
  }'

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())

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
$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;
?>

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)
}

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());
    }
}

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}"

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"

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())

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
$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);
?>

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))
}

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());
  }
}

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}"

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.

Overview

Creating RMAs

Create the Return

Sample Response

Tracking Return Disposition Data

Fetch the Return

Sample Response

Real-time Updates

Return Status Workflow

Best Practices

Return Creation

Disposition Tracking

​Overview

​Creating RMAs

​Create the Return

​Sample Response

​Tracking Return Disposition Data

​Fetch the Return

​Sample Response

​Real-time Updates

​Return Status Workflow

​Best Practices

​Return Creation

​Disposition Tracking

Overview

Creating RMAs

Create the Return

Sample Response

Tracking Return Disposition Data

Fetch the Return

Sample Response

Real-time Updates

Return Status Workflow

Best Practices

Return Creation

Disposition Tracking