# Stock

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

Stock adjustments are used to keep track of inventory changes over time. Each record represents a single change of 1 or more quantities. When adjustments are made, product and variant stock levels are updated automatically. Stock adjustments are children of [products](https://developers.swell.is/backend-api/products).

## The stock model

### Fields

- `id` (objectId): Unique identifier for the stock adjustment.
- `date_created` (date, auto): Date and time the stock adjustment was created.
- `date_updated` (date, auto): Date and time the stock adjustment was last updated.
- `description` (string): A brief description of the stock entry.
- `level` (int): New stock level after the adjustment is applied.
- `location` (string): Location associated to the stock entry, if applicable.
- `transfer_location` (string): Second location used in a transfer operation.
- `referenced_transfer_id` (objectId): ID of the referenced transfer operation that removed stock.
- `cancelation_group_id` (string): Identifier used to restore all archived stock entries as a group.
- `number` (string, auto): Auto-incremented stock adjustment number.
- `order` (Order): Expandable link to an order, if applicable to the stock adjustment.
- `order_id` (objectId): ID of an order when the stock adjustment was either reduced by the sale of a product, or increased by cancelling an order. Adjustments from orders are created automatically when stock tracking is enabled.
- `parent` (Product): Expandable link to the parent product.
- `parent_id` (objectId, required): ID of the parent product.
- `prev` (Stock): Link to the previous stock adjustment.
- `prev_id` (objectId): ID of the previous stock adjustment.
- `quantity` (int, required): Quantity of the adjustment. A positive number means stock was increased, and a negative number means stock was decreased.
- `reason` (enum): Enumerated reason for the stock adjustment. Can be `received`, `returned`, `canceled`, `sold`, `missing`, `damaged`, `transfer_remove`, or `transfer_add`. Possible values: `received`, `returned`, `canceled`, `sold`, `missing`, `damaged`, `transfer_remove`, `transfer_add`.
- `reason_message` (string): A brief description of the reason for the stock adjustment. Default: `{"$formula":"description"}`.
- `variant` (Product variant): Expandable link to the parent variant, if applicable.
- `variant_id` (objectId): ID of the parent variant, if applicable. Default: `null`.

### Example response

```json
{
  "id": "60f199509111e7000000005f",
  "parent_id": "60f199509111e70000000062",
  "date_created": "2021-07-16T14:36:00.321Z",
  "date_updated": "2021-07-16T14:36:00.321Z",
  "level": 20,
  "number": 1029376,
  "reason": "received",
  "reason_message": "Restock - PO #47362",
  "variant_id": "60f199509111e70000000061"
}
```


## Create stock adjustments

Create a new stock adjustment. Normally, stock adjustments are automatically created when stock tracking is enabled and orders are placed or canceled.

### Arguments

- `parent_id` (objectId, required): The id of the parent product.
- `quantity` (int, required): Quantity of the adjustment. A positive number means the stock was increased, and a negative number means the stock was decreased.
- `reason` (string): Enumerated reason for the stock adjustment. Can be `received`, `returned`, `canceled`, `sold`, `missing`, or `damaged`.
- `reason_message` (string): A brief description of the reason for the stock adjustment.
- `order_id` (objectId): The id of an order when the stock adjustment was either reduced by the sale of a product or increased by canceling an order. Adjustments from orders are created automatically when stock tracking is enabled.
- `variant_id` (objectId): The id of the parent variant, if applicable.

### Example request

`POST /products:stock`

**cURL**

```bash
$ curl https://api.swell.store/products:stock \
  -u store-id:secret-key \
  -d parent_id=5ca24abb9c077817e5fe2b3b
  -d quantity=10
  -d reason=received
  -d reason_message="Restock - PO #47362"
```

**Node**

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

await swell.post('/products:stock', {
  parent_id: '5ca24abb9c077817e5fe2b3b',
  quantity: 10,
  reason: 'received',
  reason_message: 'Restock - PO #47362',
});
```

**PHP**

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

$swell->post('/products:stock', [
  'parent_id' => '5ca24abb9c077817e5fe2b3b',
  'quantity' => 10,
  'reason_message' => 'Restock - PO #47362'
]);
```

### Example response

```json
{
  "id": "5ca24abb9c077817e5fe2b3b",
  "parent_id": "5ca7d6c68f749692da37c985",
  "quantity": 10,
  "level": 10,
  "number": "100184",
  "reason": "received"
  "reason_message": "Restock - PO #47362",
  "date_created": "2019-04-01T00:00:00.000Z"
}
```


## Retrieve stock adjustment

Retrieve an existing stock adjustment using the id that was returned when created.

### Arguments

- `id` (objectId, required): The id of the stock adjustment 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 stock adjustment `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 /products:stock/:id`

**cURL**

```bash
$ curl https://api.swell.store/products:stock/5ca24abb9c077817e5fe2b3b \
  -u store-id:secret-key
```

**Node**

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

await swell.get('/products:stock/{id}', {
  id: '5ca24abb9c077817e5fe2b3b',
});
```

**PHP**

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

$swell->get('/products:stock/{id}', [
  'id' => '5ca24abb9c077817e5fe2b3b',
]);
```

### Example response

```json
{
  "id": "5ca24abb9c077817e5fe2b3b",
  "parent_id": "5ca7d6c68f749692da37c985",
  "quantity": 10,
  "level": 10,
  "number": "100184",
  "reason": "received"
  "reason_message": "Restock - PO #47362",
  "date_created": "2019-04-01T00:00:00.000Z"
  "date_updated": "2019-04-01T00:00:00.000Z",
}
```


## List all stock adjustments

Return a list of product stock adjustments.

### 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 /products:stock`

**cURL**

```bash
$ curl https://api.swell.store/products:stock?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('/products:stock', {
  limit: 25,
  page: 1
});
```

**PHP**

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

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

### Example response

```json
{
  "count": 51,
  "results": [
    {
      "id": "60f199509111e7000000005f",
      "parent_id": "60f199509111e70000000066",
      "date_created": "2021-07-16T14:36:00.321Z",
      "date_updated": "2021-07-16T14:36:00.321Z",
      "level": 20,
      "number": 1029376,
      "reason": "received",
      "reason_message": "Restock - PO #47362",
      "variant_id": "60f199509111e70000000061"
    },
    {...},
    {...}
  ],
  "page": 1,
  "page_count": 3,
  "limit": 25,
  "pages": {
    "1": {
      "start": 1,
      "end": 25
    },
    "2": {
      "start": 26,
      "end": 50
    },
    "3": {
      "start": 51,
      "end": 51
    }
  }
}
```