Create customer return

curl --request POST \
  --url https://{companyName}.api.joinluminous.com/external/api/v1/returns \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "sales_order_id": 123,
  "items": [
    {
      "sales_order_item_id": 123,
      "quantity": 1.001,
      "uom_id": 123,
      "location_id": 123,
      "lot_id": 123,
      "lot_number": "<string>",
      "lot_name": "<string>"
    }
  ],
  "order_date": "2023-12-25",
  "restock": true
}
'

import requests

url = "https://{companyName}.api.joinluminous.com/external/api/v1/returns"

payload = {
    "sales_order_id": 123,
    "items": [
        {
            "sales_order_item_id": 123,
            "quantity": 1.001,
            "uom_id": 123,
            "location_id": 123,
            "lot_id": 123,
            "lot_number": "<string>",
            "lot_name": "<string>"
        }
    ],
    "order_date": "2023-12-25",
    "restock": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    sales_order_id: 123,
    items: [
      {
        sales_order_item_id: 123,
        quantity: 1.001,
        uom_id: 123,
        location_id: 123,
        lot_id: 123,
        lot_number: '<string>',
        lot_name: '<string>'
      }
    ],
    order_date: '2023-12-25',
    restock: true
  })
};

fetch('https://{companyName}.api.joinluminous.com/external/api/v1/returns', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{companyName}.api.joinluminous.com/external/api/v1/returns",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'sales_order_id' => 123,
    'items' => [
        [
                'sales_order_item_id' => 123,
                'quantity' => 1.001,
                'uom_id' => 123,
                'location_id' => 123,
                'lot_id' => 123,
                'lot_number' => '<string>',
                'lot_name' => '<string>'
        ]
    ],
    'order_date' => '2023-12-25',
    'restock' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://{companyName}.api.joinluminous.com/external/api/v1/returns"

	payload := strings.NewReader("{\n  \"sales_order_id\": 123,\n  \"items\": [\n    {\n      \"sales_order_item_id\": 123,\n      \"quantity\": 1.001,\n      \"uom_id\": 123,\n      \"location_id\": 123,\n      \"lot_id\": 123,\n      \"lot_number\": \"<string>\",\n      \"lot_name\": \"<string>\"\n    }\n  ],\n  \"order_date\": \"2023-12-25\",\n  \"restock\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{companyName}.api.joinluminous.com/external/api/v1/returns")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"sales_order_id\": 123,\n  \"items\": [\n    {\n      \"sales_order_item_id\": 123,\n      \"quantity\": 1.001,\n      \"uom_id\": 123,\n      \"location_id\": 123,\n      \"lot_id\": 123,\n      \"lot_number\": \"<string>\",\n      \"lot_name\": \"<string>\"\n    }\n  ],\n  \"order_date\": \"2023-12-25\",\n  \"restock\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{companyName}.api.joinluminous.com/external/api/v1/returns")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"sales_order_id\": 123,\n  \"items\": [\n    {\n      \"sales_order_item_id\": 123,\n      \"quantity\": 1.001,\n      \"uom_id\": 123,\n      \"location_id\": 123,\n      \"lot_id\": 123,\n      \"lot_number\": \"<string>\",\n      \"lot_name\": \"<string>\"\n    }\n  ],\n  \"order_date\": \"2023-12-25\",\n  \"restock\": true\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "id": 123,
    "sales_order_id": 123,
    "status": "Pending",
    "restock": true,
    "order_date": "2023-12-25",
    "refund_amount": 123,
    "refunded_shipping": 123,
    "tax_amount": 123,
    "amount_paid": 123,
    "product_total": 123,
    "refund_date": "2023-12-25",
    "transaction_type": "return-only",
    "refund_id": 123,
    "refund_total": 123,
    "refund_tax": 123,
    "refund_shipping": 123,
    "refunded_at": "2023-11-07T05:31:56Z",
    "is_deleted": true,
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "items": [
      {
        "id": 123,
        "sales_order_item_id": 123,
        "sku": "<string>",
        "quantity": 123,
        "unit_price": 123,
        "refunded_shipping": 123,
        "tax_amount": 123,
        "discount": 123,
        "refund_date": "2023-12-25",
        "refund_amount": 123,
        "location_id": 123,
        "lot_id": 123,
        "external_restock_location_id": "<string>",
        "lot_number": "<string>",
        "lot_name": "<string>"
      }
    ]
  }
}

{
  "message": "<string>"
}

{
  "message": "<string>",
  "code": "idempotency_conflict"
}

{
  "message": "<string>"
}

Customer Returns

Create customer return

Create a new customer return against an existing sales order. Use transaction_type to control whether a refund order is generated alongside the return:

return-only (default): just the return order
refund-only: refund only, no return order
return-and-refund: both, linked

Returns are created in Pending status. Call PATCH /returns/{id}/receive to mark them received and (optionally) restock inventory.

Retries and idempotency

This endpoint accepts an optional Idempotency-Key request header, so a client that retries after a network timeout does not create the same return twice. Without the header, the request behaves as normal.

Same key, same body: the first response is replayed as-is (status, body, and an Idempotent-Replay: true response header). Only one return is created, however many times the request is resent.
Same key, different body: 409 with code: idempotency_conflict. Nothing is created.
Same key, first request still in progress: 409 until the first request finishes.

Keys are kept for 24 hours and are scoped to your API token. The stored response is replayed whatever its status, including a 422. After you fix a rejected request, resend it with a new key; reusing the old key returns the stored failure. Use one key per logical create (for example, your source system’s order number) and keep it the same across retries.

POST

returns

Create customer return

curl --request POST \
  --url https://{companyName}.api.joinluminous.com/external/api/v1/returns \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "sales_order_id": 123,
  "items": [
    {
      "sales_order_item_id": 123,
      "quantity": 1.001,
      "uom_id": 123,
      "location_id": 123,
      "lot_id": 123,
      "lot_number": "<string>",
      "lot_name": "<string>"
    }
  ],
  "order_date": "2023-12-25",
  "restock": true
}
'

import requests

url = "https://{companyName}.api.joinluminous.com/external/api/v1/returns"

payload = {
    "sales_order_id": 123,
    "items": [
        {
            "sales_order_item_id": 123,
            "quantity": 1.001,
            "uom_id": 123,
            "location_id": 123,
            "lot_id": 123,
            "lot_number": "<string>",
            "lot_name": "<string>"
        }
    ],
    "order_date": "2023-12-25",
    "restock": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    sales_order_id: 123,
    items: [
      {
        sales_order_item_id: 123,
        quantity: 1.001,
        uom_id: 123,
        location_id: 123,
        lot_id: 123,
        lot_number: '<string>',
        lot_name: '<string>'
      }
    ],
    order_date: '2023-12-25',
    restock: true
  })
};

fetch('https://{companyName}.api.joinluminous.com/external/api/v1/returns', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{companyName}.api.joinluminous.com/external/api/v1/returns",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'sales_order_id' => 123,
    'items' => [
        [
                'sales_order_item_id' => 123,
                'quantity' => 1.001,
                'uom_id' => 123,
                'location_id' => 123,
                'lot_id' => 123,
                'lot_number' => '<string>',
                'lot_name' => '<string>'
        ]
    ],
    'order_date' => '2023-12-25',
    'restock' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://{companyName}.api.joinluminous.com/external/api/v1/returns"

	payload := strings.NewReader("{\n  \"sales_order_id\": 123,\n  \"items\": [\n    {\n      \"sales_order_item_id\": 123,\n      \"quantity\": 1.001,\n      \"uom_id\": 123,\n      \"location_id\": 123,\n      \"lot_id\": 123,\n      \"lot_number\": \"<string>\",\n      \"lot_name\": \"<string>\"\n    }\n  ],\n  \"order_date\": \"2023-12-25\",\n  \"restock\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{companyName}.api.joinluminous.com/external/api/v1/returns")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"sales_order_id\": 123,\n  \"items\": [\n    {\n      \"sales_order_item_id\": 123,\n      \"quantity\": 1.001,\n      \"uom_id\": 123,\n      \"location_id\": 123,\n      \"lot_id\": 123,\n      \"lot_number\": \"<string>\",\n      \"lot_name\": \"<string>\"\n    }\n  ],\n  \"order_date\": \"2023-12-25\",\n  \"restock\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{companyName}.api.joinluminous.com/external/api/v1/returns")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"sales_order_id\": 123,\n  \"items\": [\n    {\n      \"sales_order_item_id\": 123,\n      \"quantity\": 1.001,\n      \"uom_id\": 123,\n      \"location_id\": 123,\n      \"lot_id\": 123,\n      \"lot_number\": \"<string>\",\n      \"lot_name\": \"<string>\"\n    }\n  ],\n  \"order_date\": \"2023-12-25\",\n  \"restock\": true\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "id": 123,
    "sales_order_id": 123,
    "status": "Pending",
    "restock": true,
    "order_date": "2023-12-25",
    "refund_amount": 123,
    "refunded_shipping": 123,
    "tax_amount": 123,
    "amount_paid": 123,
    "product_total": 123,
    "refund_date": "2023-12-25",
    "transaction_type": "return-only",
    "refund_id": 123,
    "refund_total": 123,
    "refund_tax": 123,
    "refund_shipping": 123,
    "refunded_at": "2023-11-07T05:31:56Z",
    "is_deleted": true,
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "items": [
      {
        "id": 123,
        "sales_order_item_id": 123,
        "sku": "<string>",
        "quantity": 123,
        "unit_price": 123,
        "refunded_shipping": 123,
        "tax_amount": 123,
        "discount": 123,
        "refund_date": "2023-12-25",
        "refund_amount": 123,
        "location_id": 123,
        "lot_id": 123,
        "external_restock_location_id": "<string>",
        "lot_number": "<string>",
        "lot_name": "<string>"
      }
    ]
  }
}

{
  "message": "<string>"
}

{
  "message": "<string>",
  "code": "idempotency_conflict"
}

{
  "message": "<string>"
}

Authorizations

Authorization

string

header

required

Authenticate using a bearer token. To create a token, navigate to /settings/api-tokens and click Create API Token.

Headers

Idempotency-Key

string

Optional idempotency token. A retry with the same key and body replays the original stored response (with an Idempotent-Replay: true header) instead of creating a second return. Reusing the key with a different body returns 409. Omit it to disable the guard.

Body

application/json

sales_order_id

integer

required

items

object[]

required

Minimum array length: 1

Show child attributes

order_date

string<date> | null

is_posted

enum<integer> | null

Optional. When 1, the return is created already received.

Available options:

0,

1

restock

boolean | null

When true, inventory is restocked on receive (default behavior).

transaction_type

enum<string> | null

Available options:

return-only,

refund-only,

return-and-refund

Response

Created

data

object

A customer return for a sales order — return-only, refund-only, or return-and-refund. Status is Pending until received, then Received.

Show child attributes

Products & Catalog

Companies & Contacts

Inventory & Warehousing

Purchasing

Sales & Fulfillment

Manufacturing

Accounts Payable

Reports & Analytics

Drive

Configuration

Integrations

Create customer return

Retries and idempotency

Authorizations

Headers

Body

Response