# Gift card debits

Source: https://developers.swell.is/backend-api/gift-card-debits

Gift card debits keep a record of transactions for which a gift card is used for payment in order to ensure that a gift card balance is updated with each use. These debit collections are stored on the gift card entry and associated each transaction to the parent gift card and payment entries.

## The gift card debit model

### Fields

- `id` (objectId, auto): Unique identifier for the gift card debit.
- `parent_id` (objectId, required): The `id` of the parent gift card.
- `parent` (Gift Card): Link to the parent gift card.
- `date_created` (date, auto): Date the debit is created.
- `date_updated` (date, auto): Date the debit was last updated.
- `amount` (currency, required): Amount of the debit transaction.
- `payment_id` (objectId): The id of the related payment.
- `payment` (Payment): Link to the associated payment.
- `refund_id` (objectId): The `id` for the associated refund, if applicable.
- `refund` (Refund): Link to the associated refund, if applicable.
- `currency` (string): Three-letter ISO currency code in uppercase. Defaults to your store's base currency.

### Example response

```json
{
  "parent_id": "5fd21b2b53c2be21778d1f7e",
  "payment_id": "5fd21b5353c2be21778d3293",
  "amount": 35,
  "currency": "USD",
  "date_created": "2020-12-10T12:57:55.651Z",
  "id": "5fd21b5353c2be21778d337d"
}
```


## Create a gift card debit

Create a new gift card debit.

### Arguments

- `id` (objectId): The ID of the gift card debit.
- `amount` (currency, required): Initial gift card debit value. Minimum of 0.01.
- `parent_id` (objectId, required): ID of the parent gift card.
- `currency` (string): Three-letter ISO currency code in uppercase. Defaults to the store's base currency.
- `date_created` (date): Date and time the gift card debit was created.
- `date_updated` (date): Date and time the gift card debit was last updated.
- `parent` (Gift Card)
- `payment` (Payment): Expandable link to the payment.
- `payment_id` (objectId)
- `refund` (Refund)
- `refund_id` (objectId): Unique identifier for the refund.

### Example request

`POST /giftcards:debits`

**cURL**

```sh
$ curl https://api.swell.store/giftcards:debits \
  -u store-id:secret-key \
	-d parent_id=5fd21b2b53c2be21778d1f7e \
  -d amount=10.99 \
	-d currency="USD" \
```

**Node**

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

await swell.post('/giftcards:debits', {
	parent_id: 5fd21b2b53c2be21778d1f7e,
  amount: 10.99,
	currency: 'USD'
});
```

**PHP**

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

$swell->post('/giftcards:debits', [
	'parent_id' => '5fd21b2b53c2be21778d1f7e',
  'amount' => 10.99,
	'currency' => 'USD'
]);
```

### Example response

```json
{
  "parent_id": "5fd21b2b53c2be21778d1f7e",
  "payment_id": "5fd21b5353c2be21778d3293",
  "amount": 35,
  "currency": "USD",
  "date_created": "2020-12-10T12:57:55.651Z",
  "id": "5fd21b5353c2be21778d337d"
}
```


## Retrieve a gift card debit

Retrieve an existing gift card debit using the ID that was returned when created.

### Arguments

- `id` (objectId, required): ID of the gift card debit to be retrieved.

### Example request

`GET /giftcards:debits/:id`

**cURL**

```sh
$ curl https://api.swell.store/giftcards:debits/{id} \
  -u store-id:secret-key \
	-G
```

**Node**

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

await swell.get('/giftcards:debits/{id}', {
});
```

**PHP**

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

$swell->get('/giftcards:debits/{id}', [
]);
```

### Example response

```json
{
  "parent_id": "5fd21b2b53c2be21778d1f7e",
  "payment_id": "5fd21b5353c2be21778d3293",
  "amount": 35,
  "currency": "USD",
  "date_created": "2020-12-10T12:57:55.651Z",
  "id": "5fd21b5353c2be21778d337d"
}
```


## Update a gift card debit

Update an existing gift card debit using the ID that was returned when created.

### Arguments

- `id` (objectId, required): Unique identifier for the gift card debit.
- `currency` (string)
- `amount` (currency)

### Example request

`PUT /giftcards:debits/:id`

**cURL**

```sh
$ curl https://api.swell.store/giftcards:debits/62ced9a991f00e001279a07e \
  -u store-id:secret-key \
  -d currency=JPY \
  -X PUT
```

**Node**

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

await swell.put('/giftcards:debits/{id}', {
  id: '62ced9a991f00e001279a07e',
  currency: 'JPY'
});
```

**PHP**

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

$swell->put('/giftcards:debits/{id}', [
  'id' => '62ced9a991f00e001279a07e',
  'currency' => 'JPY'
]);
```

### Example response

```json
{
  "parent_id": "5fd21b2b53c2be21778d1f7e",
  "payment_id": "5fd21b5353c2be21778d3293",
  "amount": 35,
  "currency": "USD",
  "date_created": "2020-12-10T12:57:55.651Z",
  "id": "5fd21b5353c2be21778d337d"
}
```


## List all gift card debits

Return a list of gift card debits.

### 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 /giftcards:debits`

**cURL**

```sh
$ curl https://api.swell.store/giftcards:debits \
  -u store-id:secret-key \
	-G
```

**Node**

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

await swell.get('/giftcards:debits', {
});
```

**PHP**

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

$swell->get('/giftcards:debits', [
]);
```

### Example response

```json
{
  "count": 7,
  "results": [
    {
      "parent_id": "5fd21b2b53c2be21778d1f7e",
      "amount": 10.99,
      "currency": "USD",
      "date_created": "2022-07-13T14:41:45.874Z",
      "date_updated": "2022-07-13T14:48:39.499Z",
      "id": "62ced9a991f00e001279a07e"
    },
    {
      "parent_id": "5fd21b2b53c2be21778d1f7e",
      "amount": 1,
      "currency": "USD",
      "date_created": "2022-07-13T14:27:27.045Z",
      "id": "62ced64f0ccd350013e18f11"
    },
    {
      "parent_id": "5fd21b2b53c2be21778d1f7e",
      "payment_id": "5fd21b5353c2be21778d3293",
      "amount": 35,
      "currency": "USD",
      "date_created": "2020-12-10T12:57:55.651Z",
      "id": "5fd21b5353c2be21778d337d"
    },
    {
      "parent_id": "5f7479067fe13016a3d19f2b",
      "payment_id": "5fd217a1c92b493a66953c26",
      "amount": 25,
      "currency": "USD",
      "date_created": "2020-12-10T12:42:09.540Z",
      "id": "5fd217a1c92b493a66953c9f"
    },
    {
      "parent_id": "5bb3a1c26ad5eb383ea8fbe0",
      "payment_id": "5bd38d068639d9796268d344",
      "amount": 5,
      "currency": "USD",
      "date_created": "2018-10-26T21:54:14.955Z",
      "id": "5bd38d068639d9796268d363"
    },
    {
      "parent_id": "5bb3a1c26ad5eb383ea8fbe0",
      "refund_id": "5bd38cf18639d9796268ccf3",
      "amount": -5,
      "currency": "USD",
      "date_created": "2018-10-26T21:53:53.098Z",
      "id": "5bd38cf18639d9796268cd04"
    },
    {
      "parent_id": "5bb3a1c26ad5eb383ea8fbe0",
      "payment_id": "5bd365a7ab9dbb69612569bb",
      "amount": 10,
      "currency": "USD",
      "date_created": "2018-10-26T19:06:15.695Z",
      "id": "5bd365a7ab9dbb69612569da"
    }
  ],
  "page": 1,
  "page_count": 1,
  "limit": 15
}
```


## Delete a gift card debit

Delete a gift card debit permanently.

### Arguments

- `id` (objectId, required): The ID of the gift card debit to delete.

### Example request

`DELETE /giftcards:debits/:id`

**cURL**

```sh
$ curl https://api.swell.store/giftcards:debits/{id} \
  -u store-id:secret-key \
  -X DELETE
```

**Node**

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

await swell.delete('/giftcards:debits/{id}', {
});
```

**PHP**

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

$swell->delete('/giftcards:debits/{id}', [
]);
```

### Example response

```json
{
  "parent_id": "5fd21b2b53c2be21778d1f7e",
  "payment_id": "5fd21b5353c2be21778d3293",
  "amount": 35,
  "currency": "USD",
  "date_created": "2020-12-10T12:57:55.651Z",
  "id": "5fd21b5353c2be21778d337d"
}
```