rmaOrder

Retrieve a single RMA order by its internal ID or by an external ID from your system.

Required scope: view_rma_orders

---

Query

query GetRmaOrder($id: String, $byExternalId: RmaOrderByExternalIdInput) {
  rmaOrder(id: $id, byExternalId: $byExternalId) {
    id
    returnNumber
    returnReference
    externalId
    externalReference
    processingStatus
    deliveryStatus
    financialStatus
    fulfillmentStatus
    expectedResolution
    returnSlipUrl
    comment
    receivedAt
    issuedAt
    sender {
      fullname
      email
      address
      city
      zipcode
      country
      phone
    }
    deliveryContact {
      fullname
      email
      address
      city
      zipcode
      country
      phone
    }
    lines {
      label
      sku
      reference
      quantity
      reason
      productState
    }
    linkedOrders {
      orderId
    }
    shipments {
      id
    }
    financialResolutions {
      id
    }
  }
}

---

Arguments

You must provide one of the following:

Argument	Type	Description
id	String	The internal UUID of the RMA order
byExternalId	RmaOrderByExternalIdInput	Lookup by your system's external ID

RmaOrderByExternalIdInput

Field	Type	Required	Description
externalId	String	✅	The external ID string (your system's return ID)
tpAppId	String	✅	The third-party application ID that owns the reference

---

Example Variables

Fetch by internal ID:

{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

Fetch by external ID:

{
  "byExternalId": {
    "externalId": "RET-2024-001",
    "tpAppId": "my-ecommerce-app"
  }
}

---

Example Response

{
  "data": {
    "rmaOrder": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "returnNumber": 1001,
      "returnReference": "RMA-2024-1001",
      "externalId": "RET-2024-001",
      "externalReference": "EXT-RET-001",
      "processingStatus": "ACCEPTED",
      "deliveryStatus": "PENDING",
      "financialStatus": "PENDING",
      "fulfillmentStatus": "PENDING",
      "expectedResolution": "REFUND",
      "returnSlipUrl": "https://api-v3.happycolis.com/rma/slip/550e8400.pdf",
      "comment": "Customer reports wrong size",
      "receivedAt": "2024-01-20T14:30:00Z",
      "issuedAt": "2024-01-20T14:30:00Z",
      "sender": {
        "fullname": "John Doe",
        "email": "john.doe@example.com",
        "address": "123 Main Street",
        "city": "Paris",
        "zipcode": "75001",
        "country": "FR",
        "phone": "+33612345678"
      },
      "deliveryContact": {
        "fullname": "Warehouse Central",
        "email": "warehouse@example.com",
        "address": "456 Warehouse Ave",
        "city": "Lyon",
        "zipcode": "69001",
        "country": "FR",
        "phone": "+33698765432"
      },
      "lines": [
        {
          "label": "Classic T-Shirt - Small Blue",
          "sku": "TSHIRT-S-BLUE",
          "reference": "REF-TSHIRT-001",
          "quantity": 1,
          "reason": "SIZE_PROBLEM",
          "productState": "BRAND_NEW_WITH_LABEL"
        }
      ],
      "linkedOrders": [
        {
          "orderId": "order-uuid-001"
        }
      ],
      "shipments": [],
      "financialResolutions": []
    }
  }
}

---

Code Examples

curl

curl -X POST https://api-v3.happycolis.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "query": "query GetRmaOrder($id: String) { rmaOrder(id: $id) { id returnNumber returnReference processingStatus deliveryStatus financialStatus fulfillmentStatus expectedResolution lines { label sku quantity reason productState } } }",
    "variables": {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  }'

Node.js

const response = await fetch('https://api-v3.happycolis.com/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.ACCESS_TOKEN}`,
  },
  body: JSON.stringify({
    query: `
      query GetRmaOrder($id: String) {
        rmaOrder(id: $id) {
          id
          returnNumber
          returnReference
          processingStatus
          deliveryStatus
          financialStatus
          fulfillmentStatus
          expectedResolution
          lines {
            label
            sku
            quantity
            reason
            productState
          }
        }
      }
    `,
    variables: {
      id: '550e8400-e29b-41d4-a716-446655440000',
    },
  }),
});

const { data } = await response.json();
console.log(data.rmaOrder);

Python

import os
import requests

query = """
query GetRmaOrder($id: String) {
  rmaOrder(id: $id) {
    id
    returnNumber
    returnReference
    processingStatus
    deliveryStatus
    financialStatus
    fulfillmentStatus
    expectedResolution
    lines {
      label
      sku
      quantity
      reason
      productState
    }
  }
}
"""

response = requests.post(
    'https://api-v3.happycolis.com/graphql',
    headers={
        'Authorization': f'Bearer {os.environ["ACCESS_TOKEN"]}',
    },
    json={
        'query': query,
        'variables': {
            'id': '550e8400-e29b-41d4-a716-446655440000',
        },
    },
)

data = response.json()['data']
print(data['rmaOrder'])

PHP

<?php
$query = <<<'GQL'
query GetRmaOrder($id: String) {
  rmaOrder(id: $id) {
    id
    returnNumber
    returnReference
    processingStatus
    deliveryStatus
    financialStatus
    fulfillmentStatus
    expectedResolution
    lines {
      label
      sku
      quantity
      reason
      productState
    }
  }
}
GQL;

$payload = json_encode([
    'query'     => $query,
    'variables' => ['id' => '550e8400-e29b-41d4-a716-446655440000'],
]);

$ch = curl_init('https://api-v3.happycolis.com/graphql');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'Authorization: Bearer ' . getenv('ACCESS_TOKEN'),
    ],
]);

$result = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($result['data']['rmaOrder']);

Go

package main

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

func main() {
	query := `
		query GetRmaOrder($id: String) {
			rmaOrder(id: $id) {
				id
				returnNumber
				returnReference
				processingStatus
				deliveryStatus
				financialStatus
				fulfillmentStatus
				expectedResolution
				lines {
					label
					sku
					quantity
					reason
					productState
				}
			}
		}`

	body, _ := json.Marshal(map[string]any{
		"query":     query,
		"variables": map[string]any{"id": "550e8400-e29b-41d4-a716-446655440000"},
	})

	req, _ := http.NewRequest("POST", "https://api-v3.happycolis.com/graphql", bytes.NewBuffer(body))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", "Bearer "+os.Getenv("ACCESS_TOKEN"))

	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()

	var result map[string]any
	json.NewDecoder(resp.Body).Decode(&result)
	fmt.Println(result["data"])
}