Glue API: Manage returns

Last updated: September 2, 2021

Edit on GitHub

The Return Management API allows developers to retrieve return information and create returns. The list of retrievable information includes:

Sales order items that a customer can return.
Returns per customer.
Predefined reasons stored in the database.

In your development, the API can help you:

View order details, including returnable or non-returnable items.
Create returns for the returnable items.
View return details of a specific customer.
Specify reasons for returning the sales order items.

Installation

For details on the modules that provide the API functionality and how to install them, see Install the Return Management Glue API

Create a return

To create a return for a registered user, send the request:

POST /returns

Request

HEADER KEY	HEADER VALUE	REQUIRED	DESCRIPTION
Authorization	string	✓	Alphanumeric string that authorizes the customer to send requests to protected resources. Get it by authenticating as a customer.

QUERY PARAMETER	DESCRIPTION	POSSIBLE VALUES
offset	Offset of the order at which to begin the response. Works only together with `page[limit]`. To work correctly, the value should be devisable by the value of `page[limit]`. The default value is `0`.	From `0` to any.
limit	Maximum number of entries to return. Works only together with `page[offset]`. The default value is `10`.	From `1` to any.

Request sample: create a return

POST https://glue.mysprykershop.com/returns

{
    "data": {
        "type": "returns",
        "attributes": {
            "store": "DE",
			"returnItems": [
				{
					"salesOrderItemUuid": "b39c7e1c-12ba-53d3-8d81-5c363d5307e9",
					"reason": "0"
				},
				{
					"salesOrderItemUuid": "b189d4f2-da12-59f3-8e05-dfb4d95b1781",
					"reason": "Custom reason"
				}
			]
        }
    }
}

ATTRIBUTE	TYPE	REQUIRED	DESCRIPTION
store	String	✓	Store in which the order has been placed.
returnItems	cell	✓	Set of return items.
salesOrderItemUuid	String	✓	UUID of the sales order item included in the return.
reason	String		Reason to return the item.

Response

Response sample: create a return

{
    "data": {
        "type": "returns",
        "id": "DE--1-R3",
        "attributes": {
            "returnReference": "DE--1-R3",
            "store": "DE",
            "customerReference": "DE--1",
            "returnTotals": {
                "refundTotal": 0,
                "remunerationTotal": 49798
            },
            "returnItems": [
                {
                    "uuid": "3071bef7-f26f-5be4-b9e7-bef1d670a94b",
                    "reason": "0",
                    "orderItem": {
                        "name": "Sony Xperia Z3 Compact",
                        "sku": "078_24602396",
                        "sumPrice": 25584,
                        "quantity": 1,
                        "unitGrossPrice": 25584,
                        "sumGrossPrice": 25584,
                        "taxRate": "19.00",
                        "unitNetPrice": 0,
                        "sumNetPrice": 0,
                        "unitPrice": 25584,
                        "unitTaxAmountFullAggregation": 3676,
                        "sumTaxAmountFullAggregation": 3676,
                        "refundableAmount": 23026,
                        "canceledAmount": 0,
                        "sumSubtotalAggregation": 25584,
                        "unitSubtotalAggregation": 25584,
                        "unitProductOptionPriceAggregation": 0,
                        "sumProductOptionPriceAggregation": 0,
                        "unitExpensePriceAggregation": 0,
                        "sumExpensePriceAggregation": null,
                        "unitDiscountAmountAggregation": 2558,
                        "sumDiscountAmountAggregation": 2558,
                        "unitDiscountAmountFullAggregation": 2558,
                        "sumDiscountAmountFullAggregation": 2558,
                        "unitPriceToPayAggregation": 23026,
                        "sumPriceToPayAggregation": 23026,
                        "taxRateAverageAggregation": "19.00",
                        "taxAmountAfterCancellation": null,
                        "orderReference": "DE--8",
                        "uuid": "b39c7e1c-12ba-53d3-8d81-5c363d5307e9",
                        "isReturnable": false,
                        "metadata": {
                            "superAttributes": [],
                            "image": "https://images.icecat.biz/img/norm/medium/24602396-8292.jpg"
                        },
                        "calculatedDiscounts": [],
                        "productOptions": []
                    }
                },
                {
                    "uuid": "b3c46290-2eaa-5b37-bba2-60171638fabb",
                    "reason": "Custom reason",
                    "orderItem": {
                        "name": "Canon PowerShot N",
                        "sku": "035_17360369",
                        "sumPrice": 29747,
                        "quantity": 1,
                        "unitGrossPrice": 29747,
                        "sumGrossPrice": 29747,
                        "taxRate": "19.00",
                        "unitNetPrice": 0,
                        "sumNetPrice": 0,
                        "unitPrice": 29747,
                        "unitTaxAmountFullAggregation": 4275,
                        "sumTaxAmountFullAggregation": 4275,
                        "refundableAmount": 26772,
                        "canceledAmount": 0,
                        "sumSubtotalAggregation": 29747,
                        "unitSubtotalAggregation": 29747,
                        "unitProductOptionPriceAggregation": 0,
                        "sumProductOptionPriceAggregation": 0,
                        "unitExpensePriceAggregation": 0,
                        "sumExpensePriceAggregation": null,
                        "unitDiscountAmountAggregation": 2975,
                        "sumDiscountAmountAggregation": 2975,
                        "unitDiscountAmountFullAggregation": 2975,
                        "sumDiscountAmountFullAggregation": 2975,
                        "unitPriceToPayAggregation": 26772,
                        "sumPriceToPayAggregation": 26772,
                        "taxRateAverageAggregation": "19.00",
                        "taxAmountAfterCancellation": null,
                        "orderReference": "DE--9",
                        "uuid": "b189d4f2-da12-59f3-8e05-dfb4d95b1781",
                        "isReturnable": false,
                        "metadata": {
                            "superAttributes": [],
                            "image": "https://images.icecat.biz/img/gallery_mediums/17360369_3328.jpg"
                        },
                        "calculatedDiscounts": [],
                        "productOptions": []
                    }
                }
            ]
        },
        "links": {
            "self": "http://glue.myspykershop.com/returns/DE--1-R2"
        }
    }
}

ATTRIBUTE	TYPE	DESCRIPTION
returnReference	String	Unique identifier of the return in the system. You can get it when creating the return.
store	String	Store for which the return was created.
customerReference	String	Unique identifier of the customer in the system.
returnTotals	Object	List of totals to return.
refundTotal	Integer	Total sum of refunds.
remunerationTotal	Integer	Total sum of remuneration.
returnItems	Array	Set of return items.
uuid	String	Unique identifier of the returned item.
reason	String	Predefined reason why the return was created.
orderItem	Object	Information about the returned item.
name	String	Product name.
sku	String	SKU of the product.
sumPrice	Integer	Sum of the prices.
quantity	Integer	Number of the sales order items.
unitGrossPrice	Integer	Single item gross price.
sumGrossPrice	Integer	Sum of items gross price.
taxRate	Integer	Current tax rate in percentage.
unitNetPrice	Integer	Single item net price.
sumNetPrice	Integer	Sum of items’ net price.
unitPrice	Integer	Single item price without assuming if it is new or gross, this value should be used everywhere the price is displayed, it allows switching tax mode without side effects.
unitTaxAmountFullAggregation	Integer	Total tax amount for a given item with additions.
sumTaxAmountFullAggregation	Integer	Total tax amount for a given sum of items with additions.
refundableAmount	Integer	Available refundable amount for an item.
canceledAmount	Integer	Total canceled amount for this item.
sumSubtotalAggregation	Integer	Sum of subtotals of the items.
unitSubtotalAggregation	Integer	Subtotal for the given item.
unitProductOptionPriceAggregation	Integer	Item total product option price.
sumProductOptionPriceAggregation	Integer	Item total of product options for the given sum of items.
unitExpensePriceAggregation	Integer	Item expense total for a given item.
sumExpensePriceAggregation	Integer	Sum of item expense totals for the items.
unitDiscountAmountAggregation	Integer	Item total discount amount.
sumDiscountAmountAggregation	Integer	Sum of item total discount amounts.
unitDiscountAmountFullAggregation	Integer	Item total discount amount.
sumDiscountAmountFullAggregation	Integer	Item total discount amount with additions.
unitPriceToPayAggregation	Integer	Item total price to pay after discounts with additions.
sumPriceToPayAggregation	Integer	Sum of item total price to pay after discounts with additions.
taxRateAverageAggregation	Integer	Item tax rate average, with additions used when recalculating tax amount after cancellation.
taxAmountAfterCancellation	Integer	Tax amount after cancellation, recalculated using tax average.
orderReference	String	Order reference number.
uuid	String	Unique identifier of the order.
isReturnable	Boolean	Specifies whether a sales order item is returnable or not.
calculatedDiscounts	Array	Specifies the list of calculated discounts.
productOptions	Array	Set of product options applied to the product.

Retrieve returns

To retrieve returns, send the request:

GET /returns

Request

HEADER KEY	HEADER VALUE	REQUIRED	DESCRIPTION
Authorization	string	✓	Alphanumeric string that authorizes the customer to send requests to protected resources. Get it by authenticating as a customer.

QUERY PARAMETER	DESCRIPTION	POSSIBLE VALUES
offset	Ofset of the order at which to begin the response. Works only together with `page[limit]`. To work correctly, the value should be devisable by the value of `page[limit]`. The default value is `0`.	From `0` to any.
limit	Maximum number of entries to return. Works only together with `page[offset]`. The default value is `10`.	From `1` to any.

Request sample: retrieve returns

GET https://glue.mysprykershop.com/returns

Response

Response sample: retrieve returns

{
    "data": [
        {
            "type": "returns",
            "id": "DE--1-R3",
            "attributes": {
                "returnReference": "DE--1-R3",
                "store": "DE",
                "customerReference": "DE--1",
                "returnTotals": {
                    "refundTotal": 0,
                    "remunerationTotal": 49798
                }
            },
            "links": {
                "self": "https://glue.mysprykershop.com/returns/DE--1-R3"
            }
        },
        {
            "type": "returns",
            "id": "DE--1-R2",
            "attributes": {
                "returnReference": "DE--1-R2",
                "store": "DE",
                "customerReference": "DE--1",
                "returnTotals": {
                    "refundTotal": 0,
                    "remunerationTotal": 35418
                }
            },
            "links": {
                "self": "https://glue.mysprykershop.com/returns/DE--1-R2"
            }
        },
        {
            "type": "returns",
            "id": "DE--1-R1",
            "attributes": {
                "returnReference": "DE--1-R1",
                "store": "DE",
                "customerReference": "DE--1",
                "returnTotals": {
                    "refundTotal": 0,
                    "remunerationTotal": 31050
                }
            },
            "links": {
                "self": "https://glue.mysprykershop.com/returns/DE--1-R1"
            }
        }
    ],
    "links": {
        "self": "https://glue.mysprykershop.com/returns"
    }
}

ATTRIBUTE	TYPE	DESCRIPTION
returnReference	String	Unique identifier of the return in the system. You can get it when creating the return.
store	String	Store for which the return was created.
customerReference	String	Unique identifier of the customer in the system.
returnTotals	Object	List of totals to return.
refundTotal	Integer	Total sum of refunds.
remunerationTotal	Integer	Total sum of remuneration.

Retrieve a return

To retrieve a return, send the request:

GET /returns/{{returnID}}

PATH PARAMETER	DESCRIPTION
{{returnID}}	Unique identifier of a return to retrieve.

Request

HEADER KEY	HEADER VALUE	REQUIRED	DESCRIPTION
Authorization	string	✓	Alphanumeric string that authorizes the customer to send requests to protected resources. Get it by authenticating as a customer.

QUERY PARAMETER	DESCRIPTION	POSSIBLE VALUES
offset	Ofset of the order at which to begin the response. Works only together with `page[limit]`. To work correctly, the value should be devisable by the value of `page[limit]`. The default value is `0`.	From `0` to any.
limit	Maximum number of entries to return. Works only together with `page[offset]`. The default value is `10`.	From `1` to any.

Request sample: retrieve a return

GET http://glue.mysprykershop.com/returns/DE--1-R3

Response

Response sample: retrieve a return

{
    "data": {
        "type": "returns",
        "id": "DE--1-R3",
        "attributes": {
            "returnReference": "DE--1-R3",
            "store": "DE",
            "customerReference": "DE--1",
            "returnTotals": {
                "refundTotal": 0,
                "remunerationTotal": 49798
            },
            "returnItems": [
                {
                    "uuid": "3071bef7-f26f-5be4-b9e7-bef1d670a94b",
                    "reason": "0",
                    "orderItem": {
                        "name": "Sony Xperia Z3 Compact",
                        "sku": "078_24602396",
                        "sumPrice": 25584,
                        "quantity": 1,
                        "unitGrossPrice": 25584,
                        "sumGrossPrice": 25584,
                        "taxRate": "19.00",
                        "unitNetPrice": 0,
                        "sumNetPrice": 0,
                        "unitPrice": 25584,
                        "unitTaxAmountFullAggregation": 3676,
                        "sumTaxAmountFullAggregation": 3676,
                        "refundableAmount": 23026,
                        "canceledAmount": 0,
                        "sumSubtotalAggregation": 25584,
                        "unitSubtotalAggregation": 25584,
                        "unitProductOptionPriceAggregation": 0,
                        "sumProductOptionPriceAggregation": 0,
                        "unitExpensePriceAggregation": 0,
                        "sumExpensePriceAggregation": null,
                        "unitDiscountAmountAggregation": 2558,
                        "sumDiscountAmountAggregation": 2558,
                        "unitDiscountAmountFullAggregation": 2558,
                        "sumDiscountAmountFullAggregation": 2558,
                        "unitPriceToPayAggregation": 23026,
                        "sumPriceToPayAggregation": 23026,
                        "taxRateAverageAggregation": "19.00",
                        "taxAmountAfterCancellation": null,
                        "orderReference": "DE--8",
                        "uuid": "b39c7e1c-12ba-53d3-8d81-5c363d5307e9",
                        "isReturnable": false,
                        "metadata": {
                            "superAttributes": [],
                            "image": "https://images.icecat.biz/img/norm/medium/24602396-8292.jpg"
                        },
                        "calculatedDiscounts": [],
                        "productOptions": []
                    }
                },
                {
                    "uuid": "b3c46290-2eaa-5b37-bba2-60171638fabb",
                    "reason": "Custom reason",
                    "orderItem": {
                        "name": "Canon PowerShot N",
                        "sku": "035_17360369",
                        "sumPrice": 29747,
                        "quantity": 1,
                        "unitGrossPrice": 29747,
                        "sumGrossPrice": 29747,
                        "taxRate": "19.00",
                        "unitNetPrice": 0,
                        "sumNetPrice": 0,
                        "unitPrice": 29747,
                        "unitTaxAmountFullAggregation": 4275,
                        "sumTaxAmountFullAggregation": 4275,
                        "refundableAmount": 26772,
                        "canceledAmount": 0,
                        "sumSubtotalAggregation": 29747,
                        "unitSubtotalAggregation": 29747,
                        "unitProductOptionPriceAggregation": 0,
                        "sumProductOptionPriceAggregation": 0,
                        "unitExpensePriceAggregation": 0,
                        "sumExpensePriceAggregation": null,
                        "unitDiscountAmountAggregation": 2975,
                        "sumDiscountAmountAggregation": 2975,
                        "unitDiscountAmountFullAggregation": 2975,
                        "sumDiscountAmountFullAggregation": 2975,
                        "unitPriceToPayAggregation": 26772,
                        "sumPriceToPayAggregation": 26772,
                        "taxRateAverageAggregation": "19.00",
                        "taxAmountAfterCancellation": null,
                        "orderReference": "DE--9",
                        "uuid": "b189d4f2-da12-59f3-8e05-dfb4d95b1781",
                        "isReturnable": false,
                        "metadata": {
                            "superAttributes": [],
                            "image": "https://images.icecat.biz/img/gallery_mediums/17360369_3328.jpg"
                        },
                        "calculatedDiscounts": [],
                        "productOptions": []
                    }
                }
            ]
        },
        "links": {
            "self": "https://glue.mysprykershop.com/returns/DE--1-R3"
        }
    }
}

ATTRIBUTE	TYPE	DESCRIPTION
returnReference	String	Unique identifier of the return in the system. You can get it when creating the return.
store	String	Store for which the return was created.
customerReference	String	Unique identifier of the customer in the system.
returnTotals	Object	List of totals to return.
refundTotal	Integer	Total sum of refunds.
remunerationTotal	Integer	Total sum of remuneration.
returnItems	Array	Set of return items.
uuid	String	Unique identifier of the returned item.
reason	String	Predefined reason why the return was created.
orderItem	Object	Information about the returned item.
name	String	Product name.
sku	String	SKU of the product.
sumPrice	Integer	Sum of the prices.
quantity	Integer	Number of the sales order items.
unitGrossPrice	Integer	Single item gross price.
sumGrossPrice	Integer	Sum of items gross price.
taxRate	Integer	Current tax rate in percentage.
unitNetPrice	Integer	Single item net price.
sumNetPrice	Integer	Sum of items’ net price.
unitPrice	Integer	Single item price without assuming if it is new or gross, this value should be used everywhere the price is displayed, it allows switching tax mode without side effects.
unitTaxAmountFullAggregation	Integer	Total tax amount for a given item with additions.
sumTaxAmountFullAggregation	Integer	Total tax amount for a given sum of items with additions.
refundableAmount	Integer	Available refundable amount for an item.
canceledAmount	Integer	Total canceled amount for this item.
sumSubtotalAggregation	Integer	Sum of subtotals of the items.
unitSubtotalAggregation	Integer	Subtotal for the given item.
unitProductOptionPriceAggregation	Integer	Item total product option price.
sumProductOptionPriceAggregation	Integer	Item total of product options for the given sum of items.
unitExpensePriceAggregation	Integer	Item expense total for a given item.
sumExpensePriceAggregation	Integer	Sum of item expense totals for the items.
unitDiscountAmountAggregation	Integer	Item total discount amount.
sumDiscountAmountAggregation	Integer	Sum of item total discount amounts.
unitDiscountAmountFullAggregation	Integer	Item total discount amount.
sumDiscountAmountFullAggregation	Integer	Item total discount amount with additions.
unitPriceToPayAggregation	Integer	Item total price to pay after discounts with additions.
sumPriceToPayAggregation	Integer	Sum of item total price to pay after discounts with additions.
taxRateAverageAggregation	Integer	Item tax rate average, with additions used when recalculating tax amount after cancellation.
taxAmountAfterCancellation	Integer	Tax amount after cancellation, recalculated using tax average.
orderReference	String	Order reference number.
uuid	String	Unique identifier of the order.
isReturnable	Boolean	Specifies whether a sales order item is returnable or not.
calculatedDiscounts	Array	Specifies the list of calculated discounts.
productOptions	Array	Set of product options applied to the product.

Possible errors

CODE	REASON
001	Access token is invalid.
002	Access token is missing.
3601	Return can’t be created.
3602	Can’t find return by the given return reference.
3603	Return contains items from different merchants.

Was this article helpful?

Tell us what could be better

Name (Optional)

Email (Optional) Invalid email format.

Type your thoughts here

We appreciate the time you took to share the feedback
and will consider it as soon as possible.

Thank you!

For submitting the form