rmaOrderCreate

Creates a new RMA order. By default the order is created in NEW processing status. Pass accept: true to automatically accept the return on creation, skipping the submit and accept steps.

Required scope: create_rma_orders

Mutation

graphql

mutation RmaOrderCreate($input: RmaOrderInput!) {
  rmaOrderCreate(input: $input) {
    id
    returnNumber
    returnReference
    processingStatus
    deliveryStatus
    financialStatus
    fulfillmentStatus
    expectedResolution
    returnSlipUrl
    lines {
      label
      sku
      reference
      quantity
      reason
      productState
    }
    sender {
      fullname
      email
    }
    deliveryContact {
      fullname
      email
    }
  }
}

Input: `RmaOrderInput`

Field	Type	Required	Description
`id`	ID	❌	Optional UUID — if omitted, one is auto-generated
`locationId`	String	❌	Fulfillment location UUID where returns will be received
`expectedResolution`	RmaOrderExpectedResolution	✅	Expected resolution: `NONE`, `VOUCHER`, `REPLACE`, or `REFUND`
`lines`	[RmaOrderLineInput!]	✅	Return lines — at least one required
`sender`	RmaOrderContactInput	✅	Sender (customer) contact details
`deliveryContact`	RmaOrderContactInput	✅	Delivery (warehouse) contact details
`externalId`	String	❌	External system ID for cross-referencing
`externalReference`	String	❌	External reference string
`comment`	String	❌	Free-text comment about the return
`meta`	JSON	❌	Additional metadata as JSON
`autoGenerateFinancialResolution`	Boolean	❌	Auto-generate financial resolution on completion (default: `false`)
`autoExecuteFinancialResolution`	Boolean	❌	Auto-execute financial resolution without review (default: `false`)
`retainedAmountForShipping`	Float	❌	Amount to retain for return shipping costs (default: `0.0`)
`accept`	Boolean	❌	Auto-accept the return on creation (default: `false`)
`linkedOrders`	[RmaOrderLinkedOrderInput]	❌	Original orders linked to this return

RmaOrderLineInput

Field	Type	Required	Description
`label`	String	✅	Human-readable product name
`productState`	RmaOrderProductState	✅	Product condition: `BRAND_NEW_WITH_LABEL`, `BRAND_NEW_WITHOUT_LABEL`, `WORE`, `DAMAGED`, or `DEFECTIVE`
`productVariantId`	String	❌	Product variant UUID from the catalog
`stockReferenceId`	String	❌	Stock reference UUID
`reference`	String	✅	Product reference identifier
`sku`	String	✅	Stock-Keeping Unit identifier
`orderLineNumber`	String	❌	Line number from the original order
`quantity`	Int	✅	Quantity being returned (must be > 0)
`reason`	RmaOrderReturnReason	✅	Return reason: `WRONG_ITEM`, `NOT_RECEIVED`, `SIZE_PROBLEM`, `COLOR_PROBLEM`, `DEFECTIVE`, `DAMAGED_PRODUCT`, `UNSATISFIED`, or `ITEMS_NOT_SOLD`
`orderLineId`	String	❌	Original order line UUID
`orderId`	String	❌	Original order UUID
`meta`	JSON	❌	Additional line metadata

RmaOrderContactInput

Field	Type	Required	Description
`fullname`	String	✅	Full name of the contact
`email`	String	✅	Email address
`address`	String	✅	Street address line 1
`addressComplement`	String	❌	Street address line 2 (apartment, suite, etc.)
`zipcode`	String	✅	Postal / ZIP code
`city`	String	✅	City
`country`	String	✅	ISO 3166-1 alpha-2 country code (e.g. `FR`, `US`)
`state`	String	❌	State or province
`phone`	String	❌	Phone number
`mobile`	String	❌	Mobile phone number
`comments`	String	❌	Additional comments
`metadata`	JSON	❌	Additional contact metadata
`taxId`	String	❌	Tax identification number
`form`	String	❌	Legal form (e.g. `SARL`, `SAS`)
`capital`	String	❌	Share capital
`companyId`	String	❌	Company identifier (e.g. SIRET)
`registration`	String	❌	Registration number (e.g. RCS)

RmaOrderLinkedOrderInput

Field	Type	Required	Description
`orderId`	String	✅	UUID of the original order

Example Variables

json

{
  "input": {
    "locationId": "loc-uuid-001",
    "expectedResolution": "REFUND",
    "externalId": "RET-2024-001",
    "externalReference": "EXT-RET-001",
    "comment": "Customer reports wrong size received",
    "autoGenerateFinancialResolution": true,
    "autoExecuteFinancialResolution": false,
    "retainedAmountForShipping": 4.99,
    "accept": false,
    "lines": [
      {
        "label": "Classic T-Shirt - Small Blue",
        "productState": "BRAND_NEW_WITH_LABEL",
        "reference": "REF-TSHIRT-001",
        "sku": "TSHIRT-S-BLUE",
        "quantity": 1,
        "reason": "SIZE_PROBLEM",
        "orderId": "order-uuid-001",
        "orderLineId": "order-line-uuid-001"
      }
    ],
    "sender": {
      "fullname": "John Doe",
      "email": "john.doe@example.com",
      "address": "123 Main Street",
      "addressComplement": "Apt 4B",
      "zipcode": "75001",
      "city": "Paris",
      "country": "FR",
      "phone": "+33612345678"
    },
    "deliveryContact": {
      "fullname": "Warehouse Central",
      "email": "warehouse@example.com",
      "address": "456 Warehouse Ave",
      "zipcode": "69001",
      "city": "Lyon",
      "country": "FR",
      "phone": "+33698765432"
    },
    "linkedOrders": [
      {
        "orderId": "order-uuid-001"
      }
    ]
  }
}

Example Response

json

{
  "data": {
    "rmaOrderCreate": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "returnNumber": 1001,
      "returnReference": "RMA-2024-1001",
      "processingStatus": "NEW",
      "deliveryStatus": "PENDING",
      "financialStatus": "NONE",
      "fulfillmentStatus": "PENDING",
      "expectedResolution": "REFUND",
      "returnSlipUrl": null,
      "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"
        }
      ],
      "sender": {
        "fullname": "John Doe",
        "email": "john.doe@example.com"
      },
      "deliveryContact": {
        "fullname": "Warehouse Central",
        "email": "warehouse@example.com"
      }
    }
  }
}

Code Examples

bash

curl -X POST https://api-v3.happycolis.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "query": "mutation RmaOrderCreate($input: RmaOrderInput!) { rmaOrderCreate(input: $input) { id returnNumber returnReference processingStatus expectedResolution lines { label sku quantity reason } } }",
    "variables": {
      "input": {
        "locationId": "loc-uuid-001",
        "expectedResolution": "REFUND",
        "externalId": "RET-2024-001",
        "comment": "Customer reports wrong size received",
        "autoGenerateFinancialResolution": true,
        "retainedAmountForShipping": 4.99,
        "lines": [
          {
            "label": "Classic T-Shirt - Small Blue",
            "productState": "BRAND_NEW_WITH_LABEL",
            "reference": "REF-TSHIRT-001",
            "sku": "TSHIRT-S-BLUE",
            "quantity": 1,
            "reason": "SIZE_PROBLEM",
            "orderId": "order-uuid-001"
          }
        ],
        "sender": {
          "fullname": "John Doe",
          "email": "john.doe@example.com",
          "address": "123 Main Street",
          "zipcode": "75001",
          "city": "Paris",
          "country": "FR",
          "phone": "+33612345678"
        },
        "deliveryContact": {
          "fullname": "Warehouse Central",
          "email": "warehouse@example.com",
          "address": "456 Warehouse Ave",
          "zipcode": "69001",
          "city": "Lyon",
          "country": "FR"
        },
        "linkedOrders": [
          { "orderId": "order-uuid-001" }
        ]
      }
    }
  }'

const mutation = `
  mutation RmaOrderCreate($input: RmaOrderInput!) {
    rmaOrderCreate(input: $input) {
      id
      returnNumber
      returnReference
      processingStatus
      expectedResolution
      lines {
        label
        sku
        quantity
        reason
      }
    }
  }
`;

const variables = {
  input: {
    locationId: 'loc-uuid-001',
    expectedResolution: 'REFUND',
    externalId: 'RET-2024-001',
    comment: 'Customer reports wrong size received',
    autoGenerateFinancialResolution: true,
    retainedAmountForShipping: 4.99,
    lines: [
      {
        label: 'Classic T-Shirt - Small Blue',
        productState: 'BRAND_NEW_WITH_LABEL',
        reference: 'REF-TSHIRT-001',
        sku: 'TSHIRT-S-BLUE',
        quantity: 1,
        reason: 'SIZE_PROBLEM',
        orderId: 'order-uuid-001',
      },
    ],
    sender: {
      fullname: 'John Doe',
      email: 'john.doe@example.com',
      address: '123 Main Street',
      zipcode: '75001',
      city: 'Paris',
      country: 'FR',
      phone: '+33612345678',
    },
    deliveryContact: {
      fullname: 'Warehouse Central',
      email: 'warehouse@example.com',
      address: '456 Warehouse Ave',
      zipcode: '69001',
      city: 'Lyon',
      country: 'FR',
    },
    linkedOrders: [
      { orderId: 'order-uuid-001' },
    ],
  },
};

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: mutation, variables }),
});

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

python

import os
import requests

mutation = """
mutation RmaOrderCreate($input: RmaOrderInput!) {
  rmaOrderCreate(input: $input) {
    id
    returnNumber
    returnReference
    processingStatus
    expectedResolution
    lines {
      label
      sku
      quantity
      reason
    }
  }
}
"""

variables = {
    "input": {
        "locationId": "loc-uuid-001",
        "expectedResolution": "REFUND",
        "externalId": "RET-2024-001",
        "comment": "Customer reports wrong size received",
        "autoGenerateFinancialResolution": True,
        "retainedAmountForShipping": 4.99,
        "lines": [
            {
                "label": "Classic T-Shirt - Small Blue",
                "productState": "BRAND_NEW_WITH_LABEL",
                "reference": "REF-TSHIRT-001",
                "sku": "TSHIRT-S-BLUE",
                "quantity": 1,
                "reason": "SIZE_PROBLEM",
                "orderId": "order-uuid-001",
            }
        ],
        "sender": {
            "fullname": "John Doe",
            "email": "john.doe@example.com",
            "address": "123 Main Street",
            "zipcode": "75001",
            "city": "Paris",
            "country": "FR",
            "phone": "+33612345678",
        },
        "deliveryContact": {
            "fullname": "Warehouse Central",
            "email": "warehouse@example.com",
            "address": "456 Warehouse Ave",
            "zipcode": "69001",
            "city": "Lyon",
            "country": "FR",
        },
        "linkedOrders": [
            {"orderId": "order-uuid-001"}
        ],
    }
}

response = requests.post(
    'https://api-v3.happycolis.com/graphql',
    headers={'Authorization': f'Bearer {os.environ["ACCESS_TOKEN"]}'},
    json={'query': mutation, 'variables': variables},
)

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

php

<?php
$mutation = <<<'GQL'
mutation RmaOrderCreate($input: RmaOrderInput!) {
  rmaOrderCreate(input: $input) {
    id
    returnNumber
    returnReference
    processingStatus
    expectedResolution
    lines {
      label
      sku
      quantity
      reason
    }
  }
}
GQL;

$variables = [
    'input' => [
        'locationId'                      => 'loc-uuid-001',
        'expectedResolution'              => 'REFUND',
        'externalId'                      => 'RET-2024-001',
        'comment'                         => 'Customer reports wrong size received',
        'autoGenerateFinancialResolution' => true,
        'retainedAmountForShipping'       => 4.99,
        'lines' => [
            [
                'label'        => 'Classic T-Shirt - Small Blue',
                'productState' => 'BRAND_NEW_WITH_LABEL',
                'reference'    => 'REF-TSHIRT-001',
                'sku'          => 'TSHIRT-S-BLUE',
                'quantity'     => 1,
                'reason'       => 'SIZE_PROBLEM',
                'orderId'      => 'order-uuid-001',
            ],
        ],
        'sender' => [
            'fullname' => 'John Doe',
            'email'    => 'john.doe@example.com',
            'address'  => '123 Main Street',
            'zipcode'  => '75001',
            'city'     => 'Paris',
            'country'  => 'FR',
            'phone'    => '+33612345678',
        ],
        'deliveryContact' => [
            'fullname' => 'Warehouse Central',
            'email'    => 'warehouse@example.com',
            'address'  => '456 Warehouse Ave',
            'zipcode'  => '69001',
            'city'     => 'Lyon',
            'country'  => 'FR',
        ],
        'linkedOrders' => [
            ['orderId' => 'order-uuid-001'],
        ],
    ],
];

$ch = curl_init('https://api-v3.happycolis.com/graphql');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode(['query' => $mutation, 'variables' => $variables]),
    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']['rmaOrderCreate']);

package main

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

func main() {
	mutation := `
		mutation RmaOrderCreate($input: RmaOrderInput!) {
			rmaOrderCreate(input: $input) {
				id
				returnNumber
				returnReference
				processingStatus
				expectedResolution
				lines {
					label
					sku
					quantity
					reason
				}
			}
		}`

	variables := map[string]any{
		"input": map[string]any{
			"locationId":                      "loc-uuid-001",
			"expectedResolution":              "REFUND",
			"externalId":                      "RET-2024-001",
			"comment":                         "Customer reports wrong size received",
			"autoGenerateFinancialResolution": true,
			"retainedAmountForShipping":       4.99,
			"lines": []map[string]any{
				{
					"label":        "Classic T-Shirt - Small Blue",
					"productState": "BRAND_NEW_WITH_LABEL",
					"reference":    "REF-TSHIRT-001",
					"sku":          "TSHIRT-S-BLUE",
					"quantity":     1,
					"reason":       "SIZE_PROBLEM",
					"orderId":      "order-uuid-001",
				},
			},
			"sender": map[string]any{
				"fullname": "John Doe",
				"email":    "john.doe@example.com",
				"address":  "123 Main Street",
				"zipcode":  "75001",
				"city":     "Paris",
				"country":  "FR",
				"phone":    "+33612345678",
			},
			"deliveryContact": map[string]any{
				"fullname": "Warehouse Central",
				"email":    "warehouse@example.com",
				"address":  "456 Warehouse Ave",
				"zipcode":  "69001",
				"city":     "Lyon",
				"country":  "FR",
			},
			"linkedOrders": []map[string]any{
				{"orderId": "order-uuid-001"},
			},
		},
	}

	body, _ := json.Marshal(map[string]any{
		"query":     mutation,
		"variables": variables,
	})

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

rmaOrderCreate ​

Mutation ​

Input: RmaOrderInput ​

RmaOrderLineInput ​

RmaOrderContactInput ​

RmaOrderLinkedOrderInput ​

Example Variables ​

Example Response ​

Code Examples ​