# Refunds

Source: https://developers.swell.is/backend-api/refunds

Refunds are issued against a [payment](https://developers.swell.is/backend-api/payments/the-payment-model). The sum of refunds can't exceed the total payment amount. Related orders and invoices are automatically updated with refund totals.

## The refund model

### Fields

- `id` (objectId): Unique identifier for the refund.
- `account_card_id` (objectId): ID of the customer's credit card on file used to make the refund, if applicable.
- `amount` (currency, required): Refund amount denominated in `currency`. Default: `{"$formula":"parent.amount_refundable"}`.
- `async` (boolean, auto): Indicates the refund is processed asynchronously. The refund will be updated in the future while `success` is undefined.
- `card` (object): Credit card details used to make the refund, if applicable.
  - `token` (string, required)
  - `exp_month` (int)
  - `exp_year` (int)
  - `brand` (string)
  - `last4` (string)
  - `test` (boolean)
  - `address_check` (string)
  - `zip_check` (string)
  - `cvc_check` (string)
- `currency` (string): Three-letter ISO currency code in uppercase. Defaults to the store's base currency.
- `currency_rate` (float): Currency percentage used in calculating the fixed refund amount.
- `date_async_update` (date): The date of the next time the payment status will be updated.
- `date_created` (date, auto): Date and time the refund was created.
- `date_updated` (date, auto): Date and time the refund was last updated.
- `error` (object): An object describing an error that occurred while interacting with the payment gateway, if applicable.
  - `code` (string): Unique error code.
  - `message` (string): A message describing the error.
- `gateway` (string): ID of the payment gateway that was used to process the refund.
- `method` (string, required): Method of refund. Can be `card`, `account`, `amazon`, `paypal`, or any one of the manual methods defined in payment settings. Defaults to the original payment method. Default: `{"$formula":"parent.method"}`.
- `number` (string, auto): Unique incremental refund number assigned automatically.
- `order` (Order): Expandable link to the order the refund was applied to, if applicable.
- `order_id` (objectId): ID of the order the refund was applied to, if applicable. Default: `{"$formula":"parent.order_id"}`.
- `parent` (Payment): Expandable link to the payment.
- `parent_id` (objectId, required): ID of the payment the refund was issued for.
- `reason` (string): Reason for which the refund was issued.
- `reason_message` (string): A brief message describing the reason for the refund.
- `status` (enum, auto): Status of the refund. Can be `pending`, which is awaiting async processing, `error`, or `success`. Possible values: `pending`, `void`, `error`, `success`. Default: `"pending"`.
- `subscription` (Subscription): Expandable link to the subscription the refund was applied to, if applicable.
- `subscription_id` (objectId, auto): ID of the subscription the refund was applied to, if applicable. Default: `{"$formula":"parent.subscription_id"}`.
- `success` (boolean): Indicates the refund was successful. When an error occurs with a payment gateway, this value will be `false` and `error` field will be populated.
- `transaction_id` (string, auto): External identifier returned by a payment gateway, if applicable.

### Example response

```json
{
  "id": "60f199509111e70000000042",
  "amount": 20,
  "method": "card",
  "parent_id": "60f199509111e70000000045",
  "async": false,
  "currency": "USD",
  "date_created": "2021-07-16T14:36:00.293Z",
  "date_updated": "2021-07-16T14:36:00.293Z",
  "error": null,
  "number": 102934,
  "order_id": "60f199509111e70000000044",
  "reason_message": "Customer returned EX2001",
  "status": "success",
  "success": true,
  "transaction_id": "re_1XNoXdEAeofUkt5SrbA6Swow"
}
```


## Issue a refund

To issue a refund, create a refund with the `amount` and `method` to return to the customer. A refund can be issued with a different method than the original payment. The total amount refunded can't exceed the total payment amount.

### Arguments

- `amount` (currency, required): Refund amount denominated in `currency`. Default: `{"$formula":"parent.amount_refundable"}`.
- `parent_id` (objectId, required): ID of the payment the refund was issued for.
- `method` (string): Method of refund. Can be `card`, `account`, `amazon`, `paypal`, or any one of the manual methods defined in payment settings. Defaults to the original payment method. Default: `{"$formula":"parent.method"}`.
- `async` (boolean, auto): Indicates the refund is processed asynchronously. The refund will be updated in the future while `success` is undefined.
- `credit` (Credit memo): Expandable link to the credit instance issued for the refund.
- `credit_id` (objectId): ID of the associated credit issued for the refund.
- `currency` (string): Three-letter ISO currency code in uppercase. Defaults to the store's base currency.
- `currency_rate` (float): Currency percentage used in calculating the fixed refund amount.
- `date_async_update` (date): The date of the next time the payment status will be updated.
- `error` (object): An object describing an error that occurred while interacting with the payment gateway, if applicable.
  - `code` (string): Unique error code.
  - `message` (string): A message describing the error.
- `number` (string, auto): Unique incremental refund number assigned automatically.
- `order_id` (objectId): ID of the order the refund was applied to, if applicable. Default: `{"$formula":"parent.order_id"}`.
- `order` (Order): Expandable link to the order the refund was applied to, if applicable.
- `parent` (Payment): Expandable link to the payment.
- `reason` (string): Reason for which the refund was issued.
- `reason_message` (string): A brief message describing the reason for the refund.
- `status` (enum, auto): Status of the refund. Can be `pending`, which is awaiting async processing, `error`, or `success`. Possible values: `pending`, `void`, `error`, `success`. Default: `"pending"`.
- `subscription` (Subscription): Expandable link to the subscription the refund was applied to, if applicable.
- `subscription_id` (objectId, auto): ID of the subscription the refund was applied to, if applicable. Default: `{"$formula":"parent.subscription_id"}`.
- `success` (boolean): Indicates the refund was successful. When an error occurs with a payment gateway, this value will be `false` and `error` field will be populated.
- `transaction_id` (string, auto): External identifier returned by a payment gateway, if applicable.

### Example request

`POST /payments:refunds`

**cURL**

```bash
$ curl https://api.swell.store/payments:refunds \
  -u store-id:secret-key \
  -d amount=20 \
  -d parent_id=60f199509111e7000000004a \
  -d method=card
```

**Node**

```javascript
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

await swell.post('/payments:refunds', {
  amount: 20,
  parent_id: '60f199509111e7000000004a',
  method: 'card'
});
```

**PHP**

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

$swell->post('/payments:refunds', [
  'amount' => 20,
  'parent_id' => '60f199509111e7000000004a',
  'method' => 'card'
]);
```

### Example response

```json
{
  "id": "60f199509111e70000000042",
  "amount": 20,
  "method": "card",
  "parent_id": "60f199509111e7000000004a",
  "async": false,
  "currency": "USD",
  "date_created": "2021-07-16T14:36:00.293Z",
  "date_updated": "2021-07-16T14:36:00.293Z",
  "error": null,
  "number": 102934,
  "order_id": "60f199509111e70000000044",
  "reason_message": "Customer returned EX2001",
  "status": "success",
  "success": true,
  "transaction_id": "re_1XNoXdEAeofUkt5SrbA6Swow"
}
```


## Retrieve a refund

Retrieve an existing refund using the ID that was returned when created.

### Arguments

- `id` (objectId, required): The id of the refund to retrieve.
- `expand` (string): 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 ](https://developers.swell.is/backend-api/querying/expanding)for more details.
- `fields` (string): 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` (string): Include one or more arbitrary queries in the response, possibly related to the main query.

  See [including ](https://developers.swell.is/backend-api/querying/including)for more details.

### Example request

`GET /payments:refunds/:id`

**cURL**

```bash
$ curl https://api.swell.store/payments:refunds/60f199509111e70000000050 \
  -u store-id:secret-key
```

**Node**

```javascript
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

await swell.get('/payments:refunds/{id}', {
  id: '60f199509111e70000000050'
});
```

**PHP**

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

$swell->get('/payments:refunds/{id}', [
  'id' => '60f199509111e70000000050'
]);
```

### Example response

```json
{
  "id": "60f199509111e70000000050",
  "amount": 20,
  "method": "card",
  "parent_id": "60f199509111e70000000051",
  "async": false,
  "currency": "USD",
  "date_created": "2021-07-16T14:36:00.293Z",
  "date_updated": "2021-07-16T14:36:00.293Z",
  "error": null,
  "number": 102934,
  "order_id": "60f199509111e70000000044",
  "reason_message": "Customer returned EX2001",
  "status": "success",
  "success": true,
  "transaction_id": "re_1XNoXdEAeofUkt5SrbA6Swow"
}
```


## List all refunds

Return a list of refunds.

### Arguments

- `expand` (string): 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](https://developers.swell.is/backend-api/querying/expanding) for more details.
- `fields` (string): 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` (object): Include one or more arbitrary queries in the response which are potentially related to the main query.

  See [including](https://developers.swell.is/backend-api/querying/including) for more details.
- `limit` (int): Limit the number of records returned, ranging between `1` and `1000`. Defaults to `15`. Default: `15`.
- `page` (int): The page number of results to return given the specified or default `limit`.
- `search` (string): 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](https://developers.swell.is/backend-api/querying/searching) for more details.
- `sort` (string): 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](https://developers.swell.is/backend-api/querying/sorting) for more details.
- `where` (object): 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](https://developers.swell.is/backend-api/querying) for more details.

### Example request

`GET /payments:refunds`

**cURL**

```bash
$ curl https://api.swell.store/payments:refunds?limit=25&page=1 \
  -u store-id:secret-key \
  -G
```

**Node**

```javascript
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

await swell.get('/payments:refunds', {
  limit: 25,
  page: 1
});
```

**PHP**

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

$swell->get('/payments:refunds', [
  'limit' => 25,
  'page' => 1
]);
```

### Example response

```json
{
  "count": 51,
  "results": [
    {
      "id": "60f199509111e70000000042",
      "amount": 20,
      "method": "card",
      "parent_id": "60f199509111e70000000055",
      "async": false,
      "currency": "USD",
      "date_created": "2021-07-16T14:36:00.293Z",
      "date_updated": "2021-07-16T14:36:00.293Z",
      "error": null,
      "number": 102934,
      "order_id": "60f199509111e70000000044",
      "reason_message": "Customer returned EX2001",
      "status": "success",
      "success": true,
      "transaction_id": "re_1XNoXdEAeofUkt5SrbA6Swow"
    },
    {...},
    {...}
  ],
  "page": 1,
  "page_count": 3,
  "limit": 25,
  "pages": {
    "1": {
      "start": 1,
      "end": 25
    },
    "2": {
      "start": 26,
      "end": 50
    },
    "3": {
      "start": 51,
      "end": 51
    }
  }
}
```