Filter
What would you like to search for?
Backend API
A return is an action normally requested by a customer to return products purchased from a store. They contain information about returning items that were previously fulfilled, the return shipment details if applicable, and return value to apply to an order, which in turn may prompt an administrator to issue a refund.
Fields
Unique identifier for the return.
ID of the order this return was created for.
Indicates the return was canceled.
ID of a third-party carrier offering the service, if applicable.
Name of a third-party carrier offering the service, if applicable.
Total amount of taxes credited to the order for the returned items.
Total amount of additional credit applied to the order.
Three-letter ISO currency code in uppercase. Defaults to the store's base currency.
Date and time the return was created.
Date the expected return shipment is meant to arrive at a warehouse, if applicable.
Date and time the return was last updated.
The intended return destination.
ID of the intended return destination, if applicable.
Arbitrary amount to apply to the order as compensation for their inconvenience.
Total quantity of line items that can still be received in a return shipment.
Total quantity of line items that have been received in a return shipment.
Total quantity of line items that can still be restocked to product inventory.
Total quantity of line items that have been restocked to product inventory.
Internal admin notes, not visible to the customer.
Expandable list of notifications sent on behalf of the products returned.
Unique incremental return number, assigned automatically.
Expandable link to the order.
The customer's location of origin for the return shipment.
Origin customer name.
Two-letter ISO country code in uppercase.
Origin address line 1: street address/PO box/company name.
Origin address line 2: apartment/suite/unit/building.
Origin city/district/suburb/town/village.
Origin state/county/province/region.
Origin zip/postal code.
Origin phone number.
Code indicating the reason for the return.
Indicates that all items have been received in a return shipment.
Amount to charge the customer for re-stocking the returned items.
ID of a shipping service as configured in shipment settings.
Name of the return shipping service.
Amount to apply to the order as a credit as compensation for the original shipping tax.
Amount to apply to the order as a credit as compensation for the original shipping price.
Tracking code used to identify the return shipment, if applicable.
The return model
{
"id": "60f199509111e70000000078",
"items": [
{
"id": "5ca537326a0ec32a521139dd",
"order_item_id": "5a9ea7ba3f95740a914267f2",
"product_id": "5cad15bc9b14d1990724663b",
"quantity": 2,
"quantity_received": 0,
"quantity_receivable": 2,
"quantity_restocked": 0,
"quantity_restockable": 2
}
],
"order_id": "60f199509111e7000000007a",
"currency": "USD",
"date_created": "2021-07-16T14:36:00.399Z",
"date_updated": "2021-07-16T14:36:00.399Z",
"origin": {
"name": "Jon Snow",
"address1": "1 Main Street",
"city": "Brooklyn",
"state": "NY",
"zip": 11201,
"country": "US",
"phone": "(555) 555-5555"
},
"received": false,
"service": "fedex_ground",
"tracking_code": "T192000000XYZ"
}
Create a new return.
Arguments
List of line items describing the products returned.
ID of the order item returned.
ID of the order bundle item returned, if applicable.
Options from the order item returned, if applicable.
Unique identifier for the object.
Name of the product option.
Name value of the product option.
Quantity of the item returned. Defaults to 1.
Quantity of the item received in a return shipment.
Quantity of the item restocked to product inventory.
ID of the item variant, if applicable.
ID of the order this return was created for.
Internal admin notes, not visible to the customer.
Indicates the return was canceled.
ID of a 3rd party carrier offering the service, if applicable.
Name of a 3rd party carrier offering the service, if applicable.
Three-letter ISO currency code in uppercase. Defaults to the store's base currency.
Date the expected return shipment is meant to arrive at a warehouse, if applicable.
The intended return destination.
ID of the intended return destination, if applicable.
Arbitrary amount to apply to the order as compensation for their inconvenience.
The customer's location of origin for the return shipment.
Origin address line 1: street address/PO box/company name.
Origin address line 2: apartment/suite/unit/building.
Origin city/district/suburb/town/village.
Two-letter ISO country code.
Origin customer name.
Origin phone number.
Origin state/county/province/region.
Origin zip/postal code.
Code indicating the reason for the return.
Amount to charge the customer for re-stocking the returned items.
ID of a shipping service as configured in shipment settings.
Name of the return shipping service.
Amount to apply to the order as a credit as compensation for the original shipping price.
Tracking code used to identify the return shipment, if applicable.
const swell = require('swell-node').init('store-id', 'secret-key');
await swell.post('/returns', {
order_id: '5a9ea7ba3f95740a914267f1',
items: [
{
order_item_id: '5a9ea7ba3f95740a914267f2',
product_id: '5cad15bc9b14d1990724663a',
quantity: 2,
}
],
notes: 'Damaged in transit',
});
Response
{
"id": "5cad15bc9b14d1990724663a",
"number": "R10001",
"order_id": "5a9ea7ba3f95740a914267f1",
"items": [
{
"id": "5a9ea7ba3f95740a914267f2",
"order_item_id": "5a9ea7ba3f95740a914267f2",
"product_id": "5cad15bc9b14d1990724663b",
"quantity": 2,
"quantity_received": 0,
"quantity_receivable": 2,
"quantity_restocked": 0,
"quantity_restockable": 2,
...
}
],
"item_quantity_received": 0,
"item_quantity_receivable": 2,
"item_quantity_restocked": 0,
"item_quantity_restockable": 2,
"shipment_total": 0,
"shipment_tax": 0,
"extra_credit": 10,
"restock_fee": 0,
"credit_total": 10,
"credit_tax": 0,
"notes": "Damaged in transit",
...
}
Retrieve an existing return using the ID that was obtained when it was created.
Arguments
The id of the refund to retrieve.
Expanding link fields and child collections is performed using the expand argument.
- For example, expand=account would return a related customer account if one exists.
When the field represents a collection, you can specify the query limit.
- For example, expand=variants:10 would return up to 10 records of the variants collection.
See expanding for more details.
Return only the specified fields in the result. For example fields=name,slug would return only the fields name and slug in the response. Supports nested object and array fields using dot-notation, for example, items.product_id. The category id is always returned.
Include one or more arbitrary queries in the response, possibly related to the main query.
See including for more details.
const swell = require('swell-node').init('store-id', 'secret-key');
await swell.get('/returns/{id}', {
id: '60f199509111e7000000007f'
});
Response
{
"id": "60f199509111e70000000083",
"items": [
{
"id": "5ca537326a0ec32a521139dd",
"order_item_id": "5a9ea7ba3f95740a914267f2",
"product_id": "5cad15bc9b14d1990724663b",
"quantity": 2,
"quantity_received": 0,
"quantity_receivable": 2,
"quantity_restocked": 0,
"quantity_restockable": 2
}
],
"order_id": "60f199509111e70000000084",
"currency": "USD",
"date_created": "2021-07-16T14:36:00.399Z",
"date_updated": "2021-07-16T14:36:00.399Z",
"origin": {
"name": "Jon Snow",
"address1": "1 Main Street",
"city": "Brooklyn",
"state": "NY",
"zip": 11201,
"country": "US",
"phone": "(555) 555-5555"
},
"received": false,
"service": "fedex_ground",
"tracking_code": "T192000000XYZ"
}
Update an existing return using the ID that was obtained when it was created.
Arguments
Unique identifier for the return.
List of line items describing the products returned.
ID of the order item returned.
ID of the order bundle item returned, if applicable.
Options from the order item returned, if applicable.
Unique identifier for the object.
Name of the product option.
Name value of the product option.
Quantity of the item returned. Defaults to 1.
Quantity of the item received in a return shipment.
Quantity of the item restocked to product inventory.
ID of the item variant, if applicable.
ID of the order this return was created for.
ID of a shipping service as configured in shipment settings.
Tracking code used to identify the return shipment, if applicable.
Indicates the return was canceled.
ID of a 3rd party carrier offering the service, if applicable.
Name of a 3rd party carrier offering the service, if applicable.
Three-letter ISO currency code in uppercase. Defaults to the store's base currency.
Date the expected return shipment is meant to arrive at a warehouse, if applicable.
The intended return destination.
ID of the intended return destination, if applicable.
Arbitrary amount to apply to the order as compensation for their inconvenience.
Internal admin notes, not visible to the customer.
The customer's location of origin for the return shipment.
Origin address line 1: street address/PO box/company name.
Origin address line 2: apartment/suite/unit/building.
Origin city/district/suburb/town/village.
Two-letter ISO country code.
Origin customer name.
Origin phone number.
Origin state/county/province/region.
Origin zip/postal code.
Code indicating the reason for the return.
Amount to charge the customer for re-stocking the returned items.
Name of the return shipping service.
Amount to apply to the order as a credit as compensation for the original shipping price.
const swell = require('swell-node').init('store-id', 'secret-key');
await swell.put('/returns/{id}', {
id: '60f199509111e70000000078',
tracking_code: 'T192000000XYZ',
service: 'fedex_ground'
});
Response
{
"id": "60f199509111e70000000078",
"items": [
{
"id": "5ca537326a0ec32a521139dd",
"order_item_id": "5a9ea7ba3f95740a914267f2",
"product_id": "5cad15bc9b14d1990724663b",
"quantity": 2,
"quantity_received": 0,
"quantity_receivable": 2,
"quantity_restocked": 0,
"quantity_restockable": 2
}
],
"order_id": "60f199509111e7000000007d",
"currency": "USD",
"date_created": "2021-07-16T14:36:00.399Z",
"date_updated": "2021-07-16T14:36:00.399Z",
"origin": {
"name": "Jon Snow",
"address1": "1 Main Street",
"city": "Brooklyn",
"state": "NY",
"zip": 11201,
"country": "US",
"phone": "(555) 555-5555"
},
"received": false,
"service": "fedex_ground",
"tracking_code": "T192000000XYZ"
}
Return a list of... returns.
Arguments
Expand link fields and child collections by using the expand argument.
- For example, expand=account would return a related customer account if one exists.
When the field represents a collection, you can specify the query limit.
- For example, expand=variants:10 would return up to 10 records of the variants collection.
See expanding for more details.
Returns only the specified fields in the result.
- For example fields=name,slug would return only the fields name and slug in the response.
Supports nested object and array fields using dot-notation.
- For example, items.product_id. The product id is always returned.
Include one or more arbitrary queries in the response which are potentially related to the main query.
See including for more details.
Limit the number of records returned, ranging between 1 and 1000. Defaults to 15.
The page number of results to return given the specified or default limit.
A text search is performed using the search argument. Searchable fields are defined by the model.
- For example, search=red would return records containing the word "red" anywhere in the defined text fields.
See searching for more details.
Expression to sort results by using a format similar to a SQL sort statement.
- For example, sort=name asc would return records sorted by name ascending.
See sorting for more details.
An object with criteria to filter the result.
- For example, active=true would return records containing a field active with the value true.
It's also possible to use query operators, for example, $eq, $ne, $gt, and more.
See querying for more details.
const swell = require('swell-node').init('store-id', 'secret-key');
await swell.get('/returns/{id}', {
id: '60f199509111e7000000007f'
});
Response
{
"count": 51,
"results": [
{
"id": "60f199509111e70000000078",
"items": [
{
"id": "5ca537326a0ec32a521139dd",
"order_item_id": "5a9ea7ba3f95740a914267f2",
"product_id": "5cad15bc9b14d1990724663b",
"quantity": 2,
"quantity_received": 0,
"quantity_receivable": 2,
"quantity_restocked": 0,
"quantity_restockable": 2
}
],
"order_id": "60f199509111e70000000088",
"currency": "USD",
"date_created": "2021-07-16T14:36:00.399Z",
"date_updated": "2021-07-16T14:36:00.399Z",
"origin": {
"name": "Jon Snow",
"address1": "1 Main Street",
"city": "Brooklyn",
"state": "NY",
"zip": 11201,
"country": "US",
"phone": "(555) 555-5555"
},
"received": false,
"service": "fedex_ground",
"tracking_code": "T192000000XYZ"
},
{...},
{...}
],
"page": 1,
"pages": {
"1": {
"start": 1,
"end": 25
},
"2": {
"start": 26,
"end": 50
},
"2": {
"start": 51,
"end": 51
}
}
}