# Promotion uses

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

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

## The promotion use model

### Fields

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

### Example response

```json
{
  "parent_id": "6285746dd0fc72001a6a2f4e",
  "account_id": "628fb3c90f42a10014f04787",
  "order_id": "62a09d0317f83f001975b491",
  "date_created": "2022-06-08T13:08:10.445Z",
  "id": "62a09f3a17f83f001975b4d1"
},
```


## Create a promotion use

Create a new promotion use.

### Arguments

- `parent_id` (objectId, required): Unique identifier of the parent promotion.
- `id` (objectId): ID of the promotion use.
- `order_id` (objectId): Unique identifier for the order that the promotion use is applied to.
- `subscription_id` (objectId): ID of the subscription plan.
- `account_id` (objectId): ID of the account connected to the promotion use.
- `date_created` (date): Date and time the promotion use was created.
- `date_updated` (date): Date and time the promotion use was last updated.
- `order` (Order)
- `parent` (Promotion)
- `subscription` (Subscription)

### Example request

`POST /promotions:uses`

**cURL**

```sh
$ curl https://api.swell.store/promotions:uses \
  -u store-id:secret-key \
  -d order_id="62bf11bb4b738e00141c51d6" \
```

**Node**

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

await swell.post('/promotions:uses', {
  order_id: '62bf11bb4b738e00141c51d6'
});
```

**PHP**

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

$swell->post('/promotions:uses', [
  'order_id' => '62bf11bb4b738e00141c51d6'
]);
```

### Example response

```json
{
  "parent_id": "6285746dd0fc72001a6a2f4e",
  "account_id": "628fb3c90f42a10014f04787",
  "order_id": "62a09d0317f83f001975b491",
  "date_created": "2022-06-08T13:08:10.445Z",
  "id": "62a09f3a17f83f001975b4d1"
},
```


## Retrieve a promotion use

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

### Arguments

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

### Example request

`GET /promotions:uses/:id`

**cURL**

```sh
$ curl https://api.swell.store/promotions:uses/62a09f3a17f83f001975b4d1 \
  -u store-id:secret-key
```

**Node**

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

await swell.get('/promotions:uses/{id}', {
  id: '62a09f3a17f83f001975b4d1'
});
```

**PHP**

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

$swell->get('/promotions:uses/{id}', [
  'id' => '62a09f3a17f83f001975b4d1'
]);
```

### Example response

```json
{
  "parent_id": "6285746dd0fc72001a6a2f4e",
  "account_id": "628fb3c90f42a10014f04787",
  "order_id": "62a09d0317f83f001975b491",
  "date_created": "2022-06-08T13:08:10.445Z",
  "id": "62a09f3a17f83f001975b4d1"
}
```


## List all promotion uses

Return a list of promotion 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 /promotions:uses`

**cURL**

```sh
$ curl https://api.swell.store/promotions:uses?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('/promotions:uses', {
  where: {
    active: true
  },
  limit: 25,
  page: 1
});
```

**PHP**

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

$swell->get('/promotions:uses', [
  'where' => [
    'active' => true
  ],
  'limit' => 25,
  'page' => 1
]);
```

### Example response

```json
{
  "count": 3,
  "results": [
    {
      "parent_id": "6285746dd0fc72001a6a2f4e",
      "account_id": "628fb3c90f42a10014f04787",
      "order_id": "62a09d0317f83f001975b491",
      "date_created": "2022-06-08T13:08:10.445Z",
      "id": "62a09f3a17f83f001975b4d1"
    },
    {
      "parent_id": "6285746dd0fc72001a6a2f4e",
      "account_id": "6296b0ad8f4d1100129e16c3",
      "order_id": "6296b2aa50a04b0012bc64c6",
      "date_created": "2022-06-01T00:28:26.103Z",
      "id": "6296b2aa50a04b0012bc64c7"
    },
    {
      "parent_id": "6285746dd0fc72001a6a2f4e",
      "account_id": "628fb3c90f42a10014f04787",
      "order_id": "628fb3e10f42a10014f0478d",
      "date_created": "2022-05-26T17:07:45.415Z",
      "id": "628fb3e10f42a10014f0478e"
    }
  ],
  "page": 1,
  "page_count": 1,
  "limit": 25
}
```


## Delete a promotion use

Delete a promotion use permanently.

### Arguments

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

### Example request

`DELETE /promotions:uses/:id`

**cURL**

```sh
$ curl https://api.swell.store/promotions:uses/60f199509111e70000000075 \
  -u store-id:secret-key \
  -X DELETE
```

**Node**

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

await swell.delete('/promotions:uses/{id}', {
  id: '60f199509111e70000000074'
});
```

**PHP**

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

$swell->delete('/promotions:uses/{id}', [
  'id' => '60f199509111e70000000074'
]);
```

### Example response

```json
{
  "parent_id": "6285746dd0fc72001a6a2f4e",
  "account_id": "628fb3c90f42a10014f04787",
  "order_id": "62a09d0317f83f001975b491",
  "date_created": "2022-06-08T13:08:10.445Z",
  "id": "62a09f3a17f83f001975b4d1"
},
```