# Coupon uses

Source: https://developers.swell.is/backend-api/coupon-uses

The coupon uses collection tracks each use of a coupon to ensure that coupon restrictions such as usage limits are maintained. Each coupon use relates the account and order to the coupon.

## The coupon use model

### Fields

- `id` (objectId): Unique identifier for the coupon use.
- `parent_id` (objectId, required): ID of the parent coupon.
- `parent` (Coupon): Expandable link to the parent coupon.
- `date_created` (date, auto): Date and time the coupon use was created.
- `date_updated` (date, auto): Date and time the coupon use was last updated.
- `code` (string, required): The coupon code that was used.
- `code_id` (objectId, required): ID of the coupon code that was used.
- `account_id` (objectId): ID of the customer's account.
- `order_id` (objectId): ID of the order that used the coupon.
- `order` (Order): Expandable link to the order the coupon was applied to.
- `subscription_id` (objectId): ID of the subscription that spawned the coupon use, if applicable.
- `subscription` (Subscription): Expandable link to the subscription that spawned the coupon use, if applicable.

### Example response

```json
{
  "parent_id": "59c189016094a888436aee7f",
   "code": "DAGOTHWAVE",
   "code_id": "59c2c4a4c339b09853c6799c",
   "account_id": "60d61bd6575eaa344eab5c83",
   "order_id": "624319a0178e7f6c57bb3c49",
   "date_created": "2022-05-11T18:00:43.894Z",
   "id": "627bf9cb6d9c840012204a8a"
},
```


## Create a coupon use

Create a new coupon use.

### Arguments

- `id` (objectId): Unique identifier for the coupon use.
- `order_id` (objectId): Unique identifier for the order.
- `subscription_id` (objectId): ID of the subscription that spawned the order, if applicable.
- `account_id` (objectId): Unique identifier for the account.
- `parent_id` (objectId, required): ID of the parent coupon.
- `code` (string, required): Coupon code applied to the use.
- `code_id` (objectId, required): The ID of the coupon code.
- `date_created` (date): Date and time the coupon use was created.
- `date_updated` (date): Date and time the coupon use was last updated.
- `order` (Order): Expandable link to the order.
- `parent` (Coupon): Expandable link to the coupon.
- `subscription` (Subscription): Expandable link to the subscription.

### Example request

`POST /coupons:uses`

**cURL**

```sh
$ curl https://api.swell.store/coupons:uses \
  -u store-id:secret-key \
  -d parent_id=59c189016094a888436aee7f \
  -d code=WELLMET \
  -d code_id=59c2c4a4c339b09853c6799c \
  -d account_id=6081ae962717ed7a555e0d29 \
  -d subscription_id=623b3c95e75dd3013d6eac48
```

**Node**

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

await swell.post('/coupons:uses', {
  parent_id: '59c189016094a888436aee7f',
  code: 'WELLMET',
  code_id: '59c2c4a4c339b09853c6799c',
  account_id: '6081ae962717ed7a555e0d29',
  subscription_id: '623b3c95e75dd3013d6eac48'
});
```

**PHP**

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

$swell->post('/coupons:uses', [
  'parent_id' => '59c189016094a888436aee7f',
  'code' => 'WELLMET',
  'code_id' => '59c2c4a4c339b09853c6799c',
  'account_id' => '6081ae962717ed7a555e0d29',
  'subscription_id' => '623b3c95e75dd3013d6eac48'
]);
```

### Example response

```json
{
  "parent_id": "59c189016094a888436aee7f",
   "code": "DAGOTHWAVE",
   "code_id": "59c2c4a4c339b09853c6799c",
   "account_id": "60d61bd6575eaa344eab5c83",
   "order_id": "624319a0178e7f6c57bb3c49",
   "date_created": "2022-05-11T18:00:43.894Z",
   "id": "627bf9cb6d9c840012204a8a"
},
```


## Retrieve a coupon use

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

### Arguments

- `id` (objectId, required): The ID of the coupon use to retrieve.

### Example request

`GET /coupons:uses/:id`

**cURL**

```sh
$ curl https://api.swell.store/coupons:uses/62855442ff7baa0019e12f3c \
  -u store-id:secret-key
```

**Node**

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

await swell.get('/coupons:uses/{id}', {
  id: '62855442ff7baa0019e12f3c'
});
```

**PHP**

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

$swell->get('/coupons:uses/{id}', [
  'id' => '62855442ff7baa0019e12f3c'
]);
```

### Example response

```json
{
  "parent_id": "59c189016094a888436aee7f",
   "code": "DAGOTHWAVE",
   "code_id": "59c2c4a4c339b09853c6799c",
   "account_id": "60d61bd6575eaa344eab5c83",
   "order_id": "624319a0178e7f6c57bb3c49",
   "date_created": "2022-05-11T18:00:43.894Z",
   "id": "627bf9cb6d9c840012204a8a"
},
```


## List all coupon uses

Return a list of coupon uses.

### 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 /coupons:uses`

**cURL**

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

**Node**

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

await swell.get('/coupons:uses', {
});
```

**PHP**

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

$swell->get('/coupons:uses', [
]);
```

### Example response

```json
{
  "count": 23,
  "results": [
    {
      "parent_id": "59c189016094a888436aee7f",
      "code": "DRAINLUCK50",
      "code_id": "59c2c4a4c339b09853c6799c",
      "account_id": "60d61bd6575eaa344eab5c83",
      "order_id": "624319a0178e7f6c57bb3c49",
      "date_created": "2022-05-11T18:00:43.894Z",
      "id": "627bf9cb6d9c840012204a8a"
    },
    {
      "parent_id": "610b18f0fe230d45d759fd94",
      "code": "FORTIFYMAGICKA",
      "code_id": "610b18f0fe230d45d759fd9c",
      "account_id": "61a66e7d513854013d7a2a8c",
      "order_id": "62000832793a88013d157db2",
      "date_created": "2022-02-07T16:16:08.498Z",
      "id": "620145c811d803013d555a13"
    },
    {
      "parent_id": "6164a07f1f39735b268ebc92",
      "code": "MAGESGUILDINITIATE",
      "code_id": "6164a07f1f39735b268ebc9b",
      "account_id": "609a8e85848d793bcfbe6546",
      "order_id": "61c8d271f7f9a54e952ed64a",
      "date_created": "2021-12-26T20:37:06.123Z",
      "id": "61c8d272f7f9a54e952edca9"
    },
    {
      "parent_id": "6164a07f1f39735b268ebc92",
      "code": "BLADEOFWOE",
      "code_id": "6164a07f1f39735b268ebc9b",
      "account_id": "609a8e85848d793bcfbe6546",
      "order_id": "61a1456e72c53e1570135220",
      "date_created": "2021-11-26T20:37:03.198Z",
      "id": "61a1456f72c53e157013587f"
    },
    {
      "parent_id": "6164a07f1f39735b268ebc92",
      "code": "AMULETOFKINGS",
      "code_id": "6164a07f1f39735b268ebc9b",
      "account_id": "609a8e85848d793bcfbe6546",
      "order_id": "617858dfdfd51051a0bc4da2",
      "date_created": "2021-10-26T19:37:04.477Z",
      "id": "617858e0dfd51051a0bc55c0"
    }
  ],
  "page": 1,
  "page_count": 2,
  "limit": 15,
  "pages": {
    "1": {
      "start": 1,
      "end": 15
    },
    "2": {
      "start": 16,
      "end": 23
    }
  }
}
```


## Delete a coupon use

Delete a coupon use permanently.

### Arguments

- `id` (objectId, required): ID of the coupon use.

### Example request

`DELETE /coupons:uses/:id`

**cURL**

```sh
$ curl https://api.swell.store/coupons:uses/62855442ff7baa0019e12f3c \
  -u store-id:secret-key \
  -X DELETE
```

**Node**

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

await swell.delete('/coupons:uses/{id}', {
  id: '62855442ff7baa0019e12f3c'
});
```

**PHP**

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

$swell->delete('/coupons:uses/{id}', [
  'id' => '62855442ff7baa0019e12f3c'
]);
```

### Example response

```json
{
  "parent_id": "59c189016094a888436aee7f",
   "code": "DAGOTHWAVE",
   "code_id": "59c2c4a4c339b09853c6799c",
   "account_id": "60d61bd6575eaa344eab5c83",
   "order_id": "624319a0178e7f6c57bb3c49",
   "date_created": "2022-05-11T18:00:43.894Z",
   "id": "627bf9cb6d9c840012204a8a"
},
```