# Attributes

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

Product attributes are additional characteristics of a product that can be used in different ways. Attributes can be made visible on your detail page with the `visible` flag or hidden from view. Visible attributes are typically used to display a list of specifications on a detail page. Hidden attributes are typically used as internal data points or to affect the behavior of products in your store theme.

## The attribute model

### Fields

- `id` (string, required, auto): Unique identifier for the attribute. Defaults to attribute `name` underscored. Default: `{"$formula":"underscore(name)"}`.
- `name` (string, required): A human-friendly name for the attribute.
- `date_created` (date, auto): Date and time the attribute was created.
- `date_updated` (date, auto): Date and time the attribute was last updated.
- `collection` (string): Collection to look up when the attribute type is `lookup`. Required when type is `lookup`.
- `default` (mixed): Default value used when entering a value for the attribute.
- `filterable` (boolean): Indicates if the category is available in the storefront category page filters. Default: `false`.
- `localized` (boolean): Indicates if this attribute supports localized content. Default: `false`.
- `manual` (boolean): Indicates the variant attribute values are edited manually.
- `multi` (boolean): When attribute `type=image` is indicated, the attribute contains multiple images.
- `name_pattern` (string): Pattern for resolving the display label from a target collection record (e.g. `{name}`). Defaults to the target model's name field.
- `products` (Product): Expandable list of products using the attribute.
- `required` (boolean): Indicates the attribute requires a value when assigned to a product. Default: `false`.
- `searchable` (boolean): Indicates if this attribute is searchable on the backend. Default: `false`.
- `type` (enum): Input type used when entering a value for the attribute. Possible values: `short_text`, `long_text`, `asset`, `lookup`, `boolean`, `select`, `number`, `date`, `tags`, `icon`, `collection`, `field_group`, `field_row`, `text`, `textarea`, `dropdown`, `checkbox`, `radio`, `image`, `file`, `currency`.
- `values` (array of child_scalar): List of the attribute's associated select options used with attribute `type` of `checkbox`, `radio`, or `select`.
- `variant` (boolean): Indicates if this attribute is a variant.
- `visible` (boolean): Indicates the attribute is visible to customers. Default: `false`.

### Example response

```json
{
  "id": "material",
  "name": "Color",
  "date_created": "2021-07-16T14:35:59.968Z",
  "date_updated": "2021-07-16T14:35:59.968Z",
  "default": null,
  "required": false,
  "type": "text",
  "values": [
    "Red",
    "White",
    "Blue",
    "Green",
    "Yellow",
    "Black"
  ],
  "visible": true
}
```


## Create an attribute

Create a new attribute.

### Arguments

- `name` (string, required): A human-friendly name for the attribute.
- `required` (boolean): Indicates the attribute requires a value when assigned to a product. Default: `false`.
- `type` (enum): Input type used when entering a value for the attribute. Possible values: `short_text`, `long_text`, `asset`, `lookup`, `boolean`, `select`, `number`, `date`, `tags`, `icon`, `collection`, `field_group`.
- `values` (array of child_scalar): List of the attribute's associated select options used with attribute `type` of `checkbox`, `radio`, or `select`.
- `visible` (boolean): Indicates the attribute is visible to customers. Default: `false`.
- `default` (mixed): Default value used when entering a value for the attribute.
- `filterable` (boolean): Indicates if the category is available in the storefront category page filters. Default: `false`.
- `localized` (boolean): Indicates if this attribute supports localized content. Default: `false`.
- `multi` (boolean): When attribute `type=image` is indicated, the attribute contains multiple images.
- `products` (Product): Expandable list of products using the attribute.
- `searchable` (boolean): Indicates if this attribute is searchable on the backend. Default: `false`.
- `variant` (boolean): Indicates if this attribute is a variant.

### Example request

`POST /attributes`

**cURL**

```bash
$ curl https://api.swell.store/attributes \
  -u store-id:secret-key \
  -d name=Material \
  -d visible=true \
  -d type=dropdown \
  -d values[0]=Cotton \
  -d values[1]=Polyester \
  -d values[2]=Wool
```

**Node**

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

await swell.post('/attributes', {
  name: 'Material',
  visible: true,
  type: 'dropdown',
  values: [
    'Cotton',
    'Polyester',
    'Wool'
  ],
});
```

**PHP**

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

$swell->post('/attributes', [
  'name' => 'Material',
  'visible' => true,
  'type' => 'dropdown',
  'values' => [
    'Cotton',
    'Polyester',
    'Wool'
  ],
]);
```

### Example response

```json
{
  "id": "material",
  "name": "Material",
  "date_created": "2019-04-01T00:00:00.000Z",
  "required": false,
  "visible": true,
  "type": "dropdown",
  "values": [
    "Cotton",
    "Polyester",
    "Wool"
  ]
}
```


## Retrieve an attribute

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

### Arguments

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

**cURL**

```bash
$ curl https://api.swell.store/attributes/material \
  -u store-id:secret-key
```

**Node**

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

await swell.get('/attributes/{id}', {
  id: 'material',
});
```

**PHP**

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

$swell->get('/attributes/{id}', [
  'id' => 'material',
]);
```

### Example response

```json
{
  "id": "material",
  "name": "Material",
  "date_created": "2019-04-01T00:00:00.000Z",
  "required": false,
  "visible": true,
  "type": "dropdown",
  "values": [
    "Cotton",
    "Polyester",
    "Wool"
  ]
```


## Update an attribute

Update an existing attribute using the ID, that was returned when created. Updating performs a merge operation. To explicitly override values such as arrays, use the `$set` operator.

### Arguments

- `id` (string, required): Unique identifier for the attribute. Defaults to attribute `name` underscored. Default: `{"$formula":"underscore(name)"}`.
- `name` (string, required): A human-friendly name for the attribute.
- `default` (mixed): Default value used when entering a value for the attribute.
- `localized` (boolean): Indicates if this attribute supports localized content. Default: `false`.
- `multi` (boolean): When attribute `type=image` is indicated, the attribute contains multiple images.
- `products` (Product): Expandable list of products using the attribute.
- `required` (boolean): Set `true` to make the attribute require a value when added to a product. Default: `false`.
- `type` (enum): Input type used when entering a value for the attribute. Possible values: `short_text`, `long_text`, `asset`, `lookup`, `boolean`, `select`, `number`, `date`, `tags`, `icon`, `collection`, `field_group`.
- `values` (array of child_scalar): List of the attribute's associated select options used with attribute `type` of `checkbox`, `radio`, or `select`.
- `visible` (boolean): Indicates the attribute is visible to customers. Default: `false`.
- `variant` (boolean): Indicates if this attribute is a variant.

### Example request

`PUT /attributes/:id`

**cURL**

```bash
$ curl https://api.swell.store/attributes/material \
  -u store-id:secret-key \
  -d required=true \
  -X PUT
```

**Node**

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

await swell.put('/attributes/{id}', {
  id: 'material',
  required: true
});
```

**PHP**

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

$swell->put('/attributes/{id}', [
  'id' => 'material',
  'required' => true
]);
```

### Example response

```json
{
  "id": "material",
  "name": "Material",
  "date_created": "2019-04-01T00:00:00.000Z",
  "date_updated": "2019-04-01T00:00:00.000Z",
  "required": true,
  "visible": true,
  "type": "dropdown",
  "values": [
    "Cotton",
    "Polyester",
    "Wool"
  ]
}
```


## List all attributes

Return a list of product attributes.

### 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 /attributes`

**cURL**

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

**PHP**

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

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

### Example response

```json
{
  "count": 51,
  "results": [
    {
      "id": "material",
      "name": "Color",
      "date_created": "2021-07-16T14:35:59.968Z",
      "date_updated": "2021-07-16T14:35:59.968Z",
      "default": null,
      "required": false,
      "type": "text",
      "values": [
        "Red",
        "White",
        "Blue",
        "Green",
        "Yellow",
        "Black"
      ],
      "visible": true
    },
    {...},
    {...}
  ],
  "page": 1,
  "page_count": 3,
  "limit": 25,
  "pages": {
    "1": {
      "start": 1,
      "end": 25
    },
    "2": {
      "start": 26,
      "end": 50
    },
    "3": {
      "start": 51,
      "end": 51
    }
  }
}
```


## Delete an attribute

Delete an attribute.

### Arguments

- `id` (objectId, required): The id of the attribute to delete.

### Example request

`DELETE /attributes/:id`

**cURL**

```bash
$ curl https://api.swell.store/attributes/material \
  -u store-id:secret-key \
  -X DELETE
```

**Node**

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

await swell.delete('/attributes/{id}', {
  id: 'material',
});
```

**PHP**

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

$swell->delete('/attributes/{id}', [
  'id' => 'material',
]);
```

### Example response

```json
{
  "id": "material",
  "name": "Material",
  "date_created": "2019-04-01T00:00:00.000Z",
  "date_updated": "2019-04-01T00:00:00.000Z",
  "required": true,
  "visible": true,
  "type": "dropdown",
  "values": [
    "Cotton",
    "Polyester",
    "Wool"
  ]
}
```