# Account cards

Source: https://developers.swell.is/backend-api/account-cards

The account cards collection houses a customer's card information used for payments and transactions—allowing for storing multiple cards on a customer account.

## The account cards model

### Fields

- `id` (objectId, auto): The unique identifier for the card.
- `parent_id` (objectId, required): The ID of the parent account.
- `token` (string, required): Link to the associated payment token.
- `active` (boolean): Indicated whether this card is active and available for use. Default: `true`.
- `address_check` (string): Indicates results of the address check for the card: `unchecked`, `pass`, or `fail`. Possible values: `unchecked`, `pass`, `fail`.
- `billing` (object): The customer's billing details. Defaults to `account.billing`. Updating billing will also update the corresponding account billing object.
  - `name` (string): Billing full name. If `first_name` or `last_name` are updated, then `name` will be automatically updated as a combination of first/last.
  - `email` (string): Customer's email address.
  - `company` (string): Customer's company, if applicable.
  - `first_name` (string): Billing first name. If `name` is updated, then `first_name` will be automatically updated as the first word of the name.
  - `last_name` (string): Billing last name. If `name` is updated, then `last_name` will be automatically updated as the last word of the name.
  - `phone` (string): Billing phone number.
  - `address1` (string): Billing address line 1: street address/PO box/company name.
  - `address2` (string): Billing address line 2: apartment/suite/unit/building.
  - `city` (string): Billing city/district/suburb/town/village.
  - `state` (string): Billing state/county/province/region.
  - `zip` (string): Billing zip/postal code.
  - `country` (string): Two-letter [ISO country code](https://www.iso.org/iso-3166-country-codes.html).
  - `vat_number` (string): VAT number for tax purposes, if applicable.
- `brand` (string): Name of card issuer. E.g., `"visa"`.
- `display_brand` (string): Brand of the card displayed to the customer, if different from the underlying brand (for example, co-branded cards).
- `cvc_check` (string): Indicates results of the CVC check for the card: `unchecked`, `pass`, or `fail`. Possible values: `unchecked`, `pass`, `fail`.
- `date_created` (date, auto): The date the card entry was created.
- `date_updated` (date, auto): Date the card entry was last updated.
- `exp_month` (int): The expiration month on the card, `1` through `12`.
- `exp_year` (int): Four-digit card expiration year.
- `fingerprint` (string): A hashed fingerprint generated using `client_id`, `brand`, and `last4`.
- `gateway` (string): Name of the payment gateway.
- `last4` (string): The last four digits of the card number.
- `parent` (Account): Link to the parent account.
- `test` (boolean): Indicated the card is for testing purposes.
- `zip_check` (string): Indicates results of the zip check for the card: `unchecked`, `pass`, or `fail`. Possible values: `unchecked`, `pass`, `fail`.

### Example response

```json
{
  "parent_id": "627308bc32db26001276f091",
  "billing": {
    "name": "Glarthir",
    "first_name": "Glarthir",
    "last_name": null,
    "address1": "Glarthir's House",
    "address2": null,
    "city": "Skingrad",
    "state": "CA",
    "zip": "95051",
    "country": "US",
    "phone": null,
    "company": null
    },
  "brand": "Visa",
  "last4": "4242",
  "exp_month": 2,
  "exp_year": 2024,
  "token": "card_mgLMIJrqdFKjapNnKQXzbGSg",
  "address_check": "pass",
  "zip_check": "pass",
  "cvc_check": "pass",
  "fingerprint": "011778e5080632a4701cb5628266007d",
  "date_created": "2022-05-19T17:17:31.167Z",
  "active": true,
  "id": "62867bab67e544001a6a3218"
},
```


## Create an account card

Create a new customer account card.

### Arguments

- `id` (objectId, auto): The unique identifier for the card.
- `parent_id` (objectId, required): The ID of the parent account.
- `token` (link, required): Link to the associated payment token.
- `active` (boolean): Indicates whether this card is active and available for use. Default: `true`.
- `address_check` (enum): Indicates results of the address check for the card: `unchecked`, `pass`, or `fail`. Possible values: `"unchecked"`, `"pass"`, `"fail"`.
- `billing` (object): The customer's billing details. Defaults to `account.billing`. Updating billing will also update the corresponding account billing object.
  - `name` (string): Billing full name. If `first_name` or `last_name` are updated, then `name` will be automatically updated as a combination of first/last.
  - `email` (string): Customer's email address.
  - `company` (string): Customer's company, if applicable.
  - `first_name` (string): Billing first name. If `name` is updated, then `first_name` will be automatically updated as the first word of the name.
  - `last_name` (string): Billing last name. If `name` is updated, then `last_name` will be automatically updated as the last word of the name.
  - `phone` (string): Billing phone number.
  - `address1` (string)
  - `address2` (string)
  - `city` (string)
  - `state` (string)
  - `zip` (string)
  - `country` (string)
  - `vat_number` (string)
- `brand` (string): Name of card issuer. E.g., `"visa"`.
- `cvc_check` (enum): Indicates results of the CVC check for the card: `unchecked`, `pass`, or `fail`. Possible values: `"unchecked"`, `"pass"`, `"fail"`.
- `date_created` (date, auto): The date the card entry was created.
- `date_updated` (date, auto): Date the card entry was last updated.
- `exp_month` (int): The expiration month on the card, `1` through `12`.
- `exp_year` (int): Four-digit card expiration year.
- `fingerprint` (string): A hashed fingerprint generated using `client_id`, `brand`, and `last4`.
- `gateway` (string): Name of the payment gateway.
- `last4` (string): The last four digits of the card number.
- `parent` (Account): Link to the parent account.
- `test` (boolean): Indicated the card is for testing purposes.
- `zip_check` (enum): Indicates results of the zip check for the card: `unchecked`, `pass`, or `fail`. Possible values: `"unchecked"`, `"pass"`, `"fail"`.

### Example request

`POST /accounts:cards`

**cURL**

```sh
$ curl https://api.swell.store/accounts:cards \
  -u store-id:secret-key \
  -d first_name="Jarl" \
  -d last_name="Balgruff" \
  -d address1= "543 Castle Way" \
	-d city= "Whiterun" \  
	-d state= "CA" \ 
	-d country= "US" \ 
	-d brand= "Visa" \ 
	-d last4= "1234" \ 
	-d exp_month= 10 \ 
	-d exp_year= 2023 \
```

**Node**

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

await swell.post('/accounts:cards', {
  first_name: 'Jarl',
	last_name: 'Balgruff',
	address1: '543 Castle Way',
	city: 'Whiterun',
	state: 'CA',
	country: 'US',
	brand: 'Visa',
	last4: '1234',
	exp_month: 10,
	exp_year: 2023,
});
```

**PHP**

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

$swell->post('/accounts:cards', [
  'first_name' => 'Jarl',
  'last_name' => 'Balgruff'
  'address1' => '543 Castle Way'
	'city' => 'Whiterun'
	'state' => 'CA'
	'country' => 'US'
	'brand' => 'Visa'
	'last4' => '1234'
	'exp_month' => '10'
	'exp_year' => '2023'
]);
```

### Example response

```json
{
      "parent_id": "621e53a6213eaf013d1fa6b2",
      "billing": {
        "name": "Jarl Balgruff",
        "first_name": "Jarl",
        "last_name": "Balgruff",
        "address1": "543 Castle Way",
        "address2": null,
        "city": "Whiterun",
        "state": "CA",
        "zip": null,
        "country": "US",
        "phone": null,
        "company": null
      },
      "brand": "Visa",
      "last4": "1234",
      "exp_month": 10,
      "exp_year": 2023,
      "token": "card_QD5rOXP3I4bOmUCKlmLo7AzC",
      "address_check": "unchecked",
      "zip_check": "unchecked",
      "cvc_check": "unchecked",
      "fingerprint": "3628a7581fec797682e06740213c08f1",
      "date_created": "2022-07-13T15:52:53.253Z",
      "active": true,
      "id": "64ceea552fa37600132711f4"
    }
```


## Retrieve an account card

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

### Arguments

- `id` (objectId, required): ID of the customer account card 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 customer account card `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 /accounts:cards/:id`

**cURL**

```sh
$ curl https://api.swell.store/accounts:cards/64ceea552fa37600131711f3 \
  -u store-id:secret-key
```

**Node**

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

await swell.get('/accounts:cards/{id}', {
  id: '64ceea552fa37600131711f3'
});
```

**PHP**

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

$swell->get('/accounts:cards/{id}', [
  'id' => '64ceea552fa37600131711f3'
]);
```

### Example response

```json
{
  "parent_id": "621e53a6213eaf013d1fa6b2",
  "billing": {
    "name": "Jarl Balgruff",
    "first_name": "Jarl",
    "last_name": "Balgruff",
    "address1": "543 Castle Way",
    "address2": null,
    "city": "Whiterun",
    "state": "CA",
    "zip": null,
    "country": "US",
    "phone": null,
    "company": null
  },
  "brand": "Visa",
  "last4": "1234",
  "exp_month": 10,
  "exp_year": 2023,
  "token": "card_QD5rOXP3I4bOmUCKlmLo7BzC",
  "address_check": "unchecked",
  "zip_check": "unchecked",
  "cvc_check": "unchecked",
  "fingerprint": "3628a7581fec797682e06740213c08f1",
  "date_created": "2022-07-13T15:52:53.253Z",
  "active": true,
  "id": "64ceea552fa37600131711f3"
}
```


## Update an account card

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

### Arguments

- `id` (objectId, required): Unique identifier for the account card.
- `name` (string): Full name of the customer. If `first_name` or `last_name` are updated, then `name` will be automatically updated as a combination of first/last.
- `first_name` (string): Customer's first name. If `name` is updated, then `first_name` will be automatically updated as the first word of the name.
- `last_name` (string): If `name` is updated, then `last_name` will be automatically updated as the last words of the name.
- `address1` (string): Billing address line 1: street address/PO box/company name.
- `address2` (string): Billing address line 2: apartment/suite/unit/building.
- `city` (string): Billing city/district/suburb/town/village.
- `state` (string): Billing state/county/province/region.
- `zip` (string): Billing zip/postal code.
- `country` (string): Two-letter ISO country code.
- `brand` (string): Credit card brand. Can be `American Express`, `Diners Club`, `Discover`, `JCB`, `MasterCard`, `UnionPay`, `Visa`, or `Unknown`.
- `exp_month` (int): Two-digit number representing the credit card expiration month.
- `exp_year` (int): Four-digit number representing the credit card expiration year.
- `last4` (string): Last four digits of the card number.

### Example request

`PUT /accounts:cards/:id`

**cURL**

```sh
$ curl https://api.swell.store/accounts:cards/62ceea552fa37600132911f6 \
  -u store-id:secret-key \
  -d exp_month=11 \
  -d exp_year=2025 \
  -X PUT
```

**Node**

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

await swell.put('/accounts:cards/{id}', {
  id: '62ceea552fa37600132911f6',
  exp_month: 11,
  exp_year: 2025
});
```

**PHP**

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

$swell->put('/accounts:cards/{id}', [
  'id' => '62ceea552fa37600132911f6',
  'exp_month' => 11,
  'exp_year' => 2025
]);
```

### Example response

```json
{
  "parent_id": "621e53a6213eaf013d1fa6b2",
  "billing": {
    "name": "Jarl Balgruff",
    "first_name": "Jarl",
    "last_name": "Balgruff",
    "address1": "543 Castle Way",
    "address2": null,
    "city": "Whiterun",
    "state": "CA",
    "zip": null,
    "country": "US",
    "phone": null,
    "company": null
  },
  "brand": "Visa",
  "last4": "1234",
  "exp_month": 11,
  "exp_year": 2025,
  "token": "card_QD4rOXP3I5bOmUCKlmLo8AzC",
  "address_check": "unchecked",
  "zip_check": "unchecked",
  "cvc_check": "unchecked",
  "fingerprint": "3618a9581fec797682e06740212c08f3",
  "date_created": "2022-07-13T15:52:53.253Z",
  "active": true,
  "date_updated": "2022-07-18T20:00:49.662Z",
  "id": "62ceea552fa37600132911f6"
}
```


## List all account cards

Return a list of customer account cards.

### 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 /accounts:cards`

**cURL**

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

**PHP**

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

$swell->get('/accounts:cards', [
  'where' => [
    'order_count' => [
      '$gt' => 1
    ]
  ],
  'limit' => 25,
  'page' => 1
]);
```

### Example response

```json
{
  "count": 51,
  "results": [
    {
      "parent_id": "621e53a6213eaf013d1fa6b2",
      "billing": {
        "name": "Jarl Balgruff",
        "first_name": "Jarl",
        "last_name": "Balgruff",
        "address1": "543 Castle Way",
        "address2": null,
        "city": "Whiterun",
        "state": "CA",
        "zip": null,
        "country": "US",
        "phone": null,
        "company": null
      },
      "brand": "Visa",
      "last4": "1234",
      "exp_month": 10,
      "exp_year": 2023,
      "token": "card_QD5rOXP3I4bOmUCKlmLo7BzC",
      "address_check": "unchecked",
      "zip_check": "unchecked",
      "cvc_check": "unchecked",
      "fingerprint": "3628a7581fec797682e06740213c08f1",
      "date_created": "2022-07-13T15:52:53.253Z",
      "active": true,
      "id": "64ceea552fa37600131711f3"
    },
    {...},
    {...}
  ],
  "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 account card

Delete a customer account card.

### Arguments

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

### Example request

`DELETE /accounts:cards/:id`

**cURL**

```sh
$ curl https://api.swell.store/accounts:cards/62ceea552fa37600132911f6 \
  -u store-id:secret-key \
  -X DELETE
```

**Node**

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

await swell.delete('/accounts:cards/{id}', {
  id: '62ceea552fa37600132911f6'
});
```

**PHP**

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

$swell->delete('/accounts:cards/{id}', [
  'id' => '62ceea552fa37600132911f6'
]);
```

### Example response

```json
{
  "parent_id": "627308bc32db26001276f091",
  "billing": {
    "name": "Glarthir",
    "first_name": "Glarthir",
    "last_name": null,
    "address1": "Glarthir's House",
    "address2": null,
    "city": "Skingrad",
    "state": "CA",
    "zip": "95051",
    "country": "US",
    "phone": null,
    "company": null
    },
  "brand": "Visa",
  "last4": "4242",
  "exp_month": 2,
  "exp_year": 2024,
  "token": "card_mgLMIJrqdFKjapNnKQXzbGSg",
  "address_check": "pass",
  "zip_check": "pass",
  "cvc_check": "pass",
  "fingerprint": "011778e5080632a4701cb5628266007d",
  "date_created": "2022-05-19T17:17:31.167Z",
  "active": true,
  "id": "62867bab67e544001a6a3218"
},
```