rmaConfigurationCreate

Creates an RMA configuration for a location. The configuration controls how returns are handled, including return portal settings, auto-acceptance rules, allowed reasons, and financial resolution behaviour.

Required scope: create_rma_configurations

Mutation

graphql

mutation RmaConfigurationCreate($input: RmaConfigurationCreateInput!) {
  rmaConfigurationCreate(input: $input) {
    id
    locationId
    portalIsActive
    autoAccept
    acceptMulti
    needsPictures
    requestProductState
    authorizationDelay
    maxAuthorizationDelay
    reasonLines
    expectedResolutions
    emailContact
    shopUrl
    domain
    autoGenerateFinancialResolution
    autoExecuteFinancialResolution
    retainedAmountForShipping
    refundShippingOnPartialReturn
    refundShippingOnCompleteReturn
  }
}

Input: `RmaConfigurationCreateInput`

Field	Type	Required	Description
`locationId`	String	✅	Location UUID this configuration applies to
`portalIsActive`	Boolean	✅	Enable the customer-facing return portal
`domain`	String	❌	Custom domain for the return portal
`organizationId`	String	❌	Organization UUID
`tpAppIds`	[String]	❌	Third-party application IDs
`needsPictures`	Boolean	❌	Require customers to upload photos of returned items
`authorizationDelay`	Int	❌	Number of days after purchase within which returns are authorized
`maxAuthorizationDelay`	Int	❌	Maximum number of days for return authorization
`autoAccept`	Boolean	❌	Automatically accept return requests without manual review
`acceptMulti`	Boolean	❌	Allow multiple returns per original order
`requestProductState`	Boolean	❌	Require customers to specify product condition
`reasonLines`	[RmaOrderReturnReason]	❌	Allowed return reasons: `WRONG_ITEM`, `NOT_RECEIVED`, `SIZE_PROBLEM`, `COLOR_PROBLEM`, `DEFECTIVE`, `DAMAGED_PRODUCT`, `UNSATISFIED`, `ITEMS_NOT_SOLD`
`expectedResolutions`	[RmaOrderExpectedResolution]	❌	Allowed resolution types: `NONE`, `VOUCHER`, `REPLACE`, `REFUND`
`emailContact`	String	❌	Contact email displayed on the return portal
`shopUrl`	String	❌	Shop URL for linking back to the store
`customCss`	String	❌	Custom CSS to style the return portal
`titleColor`	String	❌	Title color for the return portal (hex code)
`backgroundColor`	String	❌	Background color for the return portal (hex code)
`headline`	String	❌	Headline text displayed on the return portal
`metaDescription`	String	❌	Meta description for SEO
`metaTitle`	String	❌	Meta title for SEO
`autoGenerateFinancialResolution`	Boolean	❌	Auto-generate financial resolution when return is completed
`autoExecuteFinancialResolution`	Boolean	❌	Auto-execute financial resolution without manual review
`retainedAmountForShipping`	Float	❌	Default amount to retain for return shipping costs
`refundShippingOnPartialReturn`	Boolean	❌	Refund original shipping cost on partial returns
`refundShippingOnCompleteReturn`	Boolean	❌	Refund original shipping cost on complete returns

Example Variables

json

{
  "input": {
    "locationId": "loc-uuid-001",
    "portalIsActive": true,
    "domain": "returns.mystore.com",
    "autoAccept": false,
    "acceptMulti": true,
    "needsPictures": true,
    "requestProductState": true,
    "authorizationDelay": 30,
    "maxAuthorizationDelay": 60,
    "reasonLines": [
      "WRONG_ITEM",
      "SIZE_PROBLEM",
      "COLOR_PROBLEM",
      "DEFECTIVE",
      "DAMAGED_PRODUCT",
      "UNSATISFIED"
    ],
    "expectedResolutions": [
      "REFUND",
      "VOUCHER",
      "REPLACE"
    ],
    "emailContact": "returns@mystore.com",
    "shopUrl": "https://mystore.com",
    "headline": "Return your order",
    "titleColor": "#333333",
    "backgroundColor": "#FFFFFF",
    "autoGenerateFinancialResolution": true,
    "autoExecuteFinancialResolution": false,
    "retainedAmountForShipping": 4.99,
    "refundShippingOnPartialReturn": false,
    "refundShippingOnCompleteReturn": true
  }
}

Example Response

json

{
  "data": {
    "rmaConfigurationCreate": {
      "id": "config-uuid-001",
      "locationId": "loc-uuid-001",
      "portalIsActive": true,
      "autoAccept": false,
      "acceptMulti": true,
      "needsPictures": true,
      "requestProductState": true,
      "authorizationDelay": 30,
      "maxAuthorizationDelay": 60,
      "reasonLines": [
        "WRONG_ITEM",
        "SIZE_PROBLEM",
        "COLOR_PROBLEM",
        "DEFECTIVE",
        "DAMAGED_PRODUCT",
        "UNSATISFIED"
      ],
      "expectedResolutions": [
        "REFUND",
        "VOUCHER",
        "REPLACE"
      ],
      "emailContact": "returns@mystore.com",
      "shopUrl": "https://mystore.com",
      "domain": "returns.mystore.com",
      "autoGenerateFinancialResolution": true,
      "autoExecuteFinancialResolution": false,
      "retainedAmountForShipping": 4.99,
      "refundShippingOnPartialReturn": false,
      "refundShippingOnCompleteReturn": true
    }
  }
}

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 RmaConfigurationCreate($input: RmaConfigurationCreateInput!) { rmaConfigurationCreate(input: $input) { id locationId portalIsActive autoAccept reasonLines expectedResolutions } }",
    "variables": {
      "input": {
        "locationId": "loc-uuid-001",
        "portalIsActive": true,
        "autoAccept": false,
        "acceptMulti": true,
        "needsPictures": true,
        "requestProductState": true,
        "authorizationDelay": 30,
        "reasonLines": ["WRONG_ITEM", "SIZE_PROBLEM", "DEFECTIVE", "DAMAGED_PRODUCT", "UNSATISFIED"],
        "expectedResolutions": ["REFUND", "VOUCHER", "REPLACE"],
        "emailContact": "returns@mystore.com",
        "shopUrl": "https://mystore.com",
        "autoGenerateFinancialResolution": true,
        "retainedAmountForShipping": 4.99,
        "refundShippingOnCompleteReturn": true
      }
    }
  }'

const mutation = `
  mutation RmaConfigurationCreate($input: RmaConfigurationCreateInput!) {
    rmaConfigurationCreate(input: $input) {
      id
      locationId
      portalIsActive
      autoAccept
      reasonLines
      expectedResolutions
    }
  }
`;

const variables = {
  input: {
    locationId: 'loc-uuid-001',
    portalIsActive: true,
    autoAccept: false,
    acceptMulti: true,
    needsPictures: true,
    requestProductState: true,
    authorizationDelay: 30,
    reasonLines: ['WRONG_ITEM', 'SIZE_PROBLEM', 'DEFECTIVE', 'DAMAGED_PRODUCT', 'UNSATISFIED'],
    expectedResolutions: ['REFUND', 'VOUCHER', 'REPLACE'],
    emailContact: 'returns@mystore.com',
    shopUrl: 'https://mystore.com',
    autoGenerateFinancialResolution: true,
    retainedAmountForShipping: 4.99,
    refundShippingOnCompleteReturn: true,
  },
};

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.rmaConfigurationCreate);

python

import os
import requests

mutation = """
mutation RmaConfigurationCreate($input: RmaConfigurationCreateInput!) {
  rmaConfigurationCreate(input: $input) {
    id
    locationId
    portalIsActive
    autoAccept
    reasonLines
    expectedResolutions
  }
}
"""

variables = {
    "input": {
        "locationId": "loc-uuid-001",
        "portalIsActive": True,
        "autoAccept": False,
        "acceptMulti": True,
        "needsPictures": True,
        "requestProductState": True,
        "authorizationDelay": 30,
        "reasonLines": ["WRONG_ITEM", "SIZE_PROBLEM", "DEFECTIVE", "DAMAGED_PRODUCT", "UNSATISFIED"],
        "expectedResolutions": ["REFUND", "VOUCHER", "REPLACE"],
        "emailContact": "returns@mystore.com",
        "shopUrl": "https://mystore.com",
        "autoGenerateFinancialResolution": True,
        "retainedAmountForShipping": 4.99,
        "refundShippingOnCompleteReturn": True,
    }
}

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['rmaConfigurationCreate'])

php

<?php
$mutation = <<<'GQL'
mutation RmaConfigurationCreate($input: RmaConfigurationCreateInput!) {
  rmaConfigurationCreate(input: $input) {
    id
    locationId
    portalIsActive
    autoAccept
    reasonLines
    expectedResolutions
  }
}
GQL;

$variables = [
    'input' => [
        'locationId'                      => 'loc-uuid-001',
        'portalIsActive'                  => true,
        'autoAccept'                      => false,
        'acceptMulti'                     => true,
        'needsPictures'                   => true,
        'requestProductState'             => true,
        'authorizationDelay'              => 30,
        'reasonLines'                     => ['WRONG_ITEM', 'SIZE_PROBLEM', 'DEFECTIVE', 'DAMAGED_PRODUCT', 'UNSATISFIED'],
        'expectedResolutions'             => ['REFUND', 'VOUCHER', 'REPLACE'],
        'emailContact'                    => 'returns@mystore.com',
        'shopUrl'                         => 'https://mystore.com',
        'autoGenerateFinancialResolution' => true,
        'retainedAmountForShipping'       => 4.99,
        'refundShippingOnCompleteReturn'  => true,
    ],
];

$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']['rmaConfigurationCreate']);

package main

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

func main() {
	mutation := `
		mutation RmaConfigurationCreate($input: RmaConfigurationCreateInput!) {
			rmaConfigurationCreate(input: $input) {
				id
				locationId
				portalIsActive
				autoAccept
				reasonLines
				expectedResolutions
			}
		}`

	variables := map[string]any{
		"input": map[string]any{
			"locationId":                      "loc-uuid-001",
			"portalIsActive":                  true,
			"autoAccept":                      false,
			"acceptMulti":                     true,
			"needsPictures":                   true,
			"requestProductState":             true,
			"authorizationDelay":              30,
			"reasonLines":                     []string{"WRONG_ITEM", "SIZE_PROBLEM", "DEFECTIVE", "DAMAGED_PRODUCT", "UNSATISFIED"},
			"expectedResolutions":             []string{"REFUND", "VOUCHER", "REPLACE"},
			"emailContact":                    "returns@mystore.com",
			"shopUrl":                         "https://mystore.com",
			"autoGenerateFinancialResolution": true,
			"retainedAmountForShipping":       4.99,
			"refundShippingOnCompleteReturn":  true,
		},
	}

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

rmaConfigurationCreate ​

Mutation ​

Input: RmaConfigurationCreateInput ​

Example Variables ​