# Create a return

Source: https://developers.swell.is/backend-api/returns/create-a-return

Create a new return.

## Arguments

- `items` (array of object, required): List of line items describing the products returned.
  - `order_item_id` (objectId, required): ID of the order item returned.
  - `product_id` (objectId, required)
  - `bundle_item_id` (objectId): ID of the order bundle item returned, if applicable.
  - `options` (array of object): Options from the order item returned, if applicable.
    - `id` (string): Unique identifier for the object.
    - `name` (string): Name of the product option.
    - `value` (string): Name value of the product option.
  - `quantity` (int): Quantity of the item returned. Defaults to 1.
  - `quantity_received` (int): Quantity of the item received in a return shipment. Default: `0`.
  - `quantity_restocked` (int): Quantity of the item restocked to product inventory. Default: `0`.
  - `variant_id` (objectId): ID of the item variant, if applicable.
  - `id` (objectId, auto): Unique identifier for the return item.
  - `product` (product): Expandable link to the item product.
  - `quantity_receivable` (int): Quantity of the item that can still be received in a return shipment.
  - `quantity_restockable` (int): Quantity of the item that can still be restocked to product inventory.
  - `variant` (variant): Expandable link to the item variant, if applicable.
- `order_id` (objectId, required): ID of the order this return was created for.
- `notes` (string): Internal admin notes, not visible to the customer.
- `canceled` (boolean): Indicates the return was canceled.
- `carrier` (string): ID of a 3rd party carrier offering the service, if applicable.
- `carrier_name` (string): Name of a 3rd party carrier offering the service, if applicable.
- `currency` (string): Three-letter ISO currency code in uppercase. Defaults to the store's base currency.
- `date_estimated` (date): Date the expected return shipment is meant to arrive at a warehouse, if applicable.
- `destination` (object): The intended return destination.
  - `location` (string): ID of the intended return destination, if applicable. Default: `"default"`.
- `extra_credit` (currency): Arbitrary amount to apply to the order as compensation for their inconvenience.
- `origin` (object): The customer's location of origin for the return shipment.
  - `address1` (string): Origin address line 1: street address/PO box/company name.
  - `address2` (string): Origin address line 2: apartment/suite/unit/building.
  - `city` (string): Origin city/district/suburb/town/village.
  - `country` (string): Two-letter ISO country code.
  - `name` (string): Origin customer name.
  - `phone` (string): Origin phone number.
  - `state` (string): Origin state/county/province/region.
  - `zip` (string): Origin zip/postal code.
- `reason_code` (string): Code indicating the reason for the return.
- `restock_fee` (currency): Amount to charge the customer for re-stocking the returned items.
- `service` (string): ID of a shipping service as configured in shipment settings.
- `service_name` (string): Name of the return shipping service.
- `shipment_total` (currency): Amount to apply to the order as a credit as compensation for the original shipping price.
- `tracking_code` (string): Tracking code used to identify the return shipment, if applicable.
- `credit_tax` (currency, auto): Total amount of taxes credited to the order for the returned items.
- `credit_total` (currency, auto): Total amount of additional credit applied to the order.
- `item_quantity_receivable` (int, auto): Total quantity of line items that can still be received in a return shipment.
- `item_quantity_received` (int, auto): Total quantity of line items that have been received in a return shipment.
- `item_quantity_restockable` (int, auto): Total quantity of line items that can still be restocked to product inventory.
- `item_quantity_restocked` (int, auto): Total quantity of line items that have been restocked to product inventory.
- `notifications` (Notification): Expandable list of notifications sent on behalf of the products returned.
- `number` (string, auto): Unique incremental return number, assigned automatically.
- `order` (Order): Expandable link to the order.
- `received` (boolean, auto): Indicates that all items have been received in a return shipment. Default: `false`.
- `shipment_tax` (currency, auto): Amount to apply to the order as a credit as compensation for the original shipping tax.

## Example request

`POST /returns`

**cURL**

```bash
$ curl https://api.swell.store/returns \
  -u store-id:secret-key \
  -d order_id=5a9ea7ba3f95740a914267f1 \
  -d items[0][order_item_id]=5a9ea7ba3f95740a914267f2 \
  -d items[0][product_id]=5cad15bc9b14d1990724663a \
  -d items[0][quantity]=2 \
  -d notes=Damaged in transit
```

**Node**

```javascript
const { swell } = require('swell-node');
swell.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',
});
```

**PHP**

```php
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->post('/returns', [
  'order_id' => '5a9ea7ba3f95740a914267f1',
  'items' => [
    [
      'order_item_id' => '5a9ea7ba3f95740a914267f2',
      'product_id' => '5cad15bc9b14d1990724663a',
      'quantity' => 2,
    ]
  ],
  'notes' => 'Damaged in transit'
]);
```

## Example response

```json
{
  "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",
  ...
}
```