# Customer

## Customer <a href="#api-customer-customer" id="api-customer-customer"></a>

Set up customer profiles. You will need these profiles to store credit cards and use those credit cards for different payment types.

**BASE URI**

`https://apigateway.payfirma.com/customer-service`

### Create a customer <a href="#api-customer-createacustomer" id="api-customer-createacustomer"></a>

Create a new customer profile using provided information

**HTTPS POST**

`/customer`

| **Request Arguments**       |                                                                                                                                    |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| <p>email</p><p>REQUIRED</p> | The email address associated with the customer that will receive the receipt, if that attribute is set to true.                    |
| first\_name                 | The first name of the customer.                                                                                                    |
| last\_name                  | The customers last name.                                                                                                           |
| **company**                 | Business name associated with customer.                                                                                            |
| bcc\_emails                 | Additional email the receipt should be sent to for expense tracking or accounting needs.                                           |
| **telephone**               | Customer’s telephone number.                                                                                                       |
| **address1**                | First line of the customer address.                                                                                                |
| **address2**                | Second line of the customer address.                                                                                               |
| **city**                    | The city where the customer is.                                                                                                    |
| **province**                | The province where Canadian customer reside. For US Customers, this would be the State of residence.                               |
| **country**                 | The country where the customer is. All country codes should be in ISO 3166 Alpha 2. For Canada, use CA. For United States, use US. |
| **postal\_code**            | The 6 digit address code for Canadian customer. US customers will use a 5-9 digit Zip Code.                                        |
| custom\_id                  | A description field to record any general customer identifying information.                                                        |

| **Response Attributes**          |                                                                                                                                    |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| <p>id</p><p>number</p>           | Internal ID representation.                                                                                                        |
| <p>lookup\_id</p><p>string</p>   | A hashed identifier used to identify and access saved customers, cards, plans and subscriptions.                                   |
| <p>email</p><p>string</p>        | The email address associated with the customer that will receive the receipt, if that attribute is set to true.                    |
| <p>first\_name</p><p>string</p>  | The first name of the customer.                                                                                                    |
| <p>last\_name</p><p>string</p>   | The customers last name.                                                                                                           |
| <p>company</p><p>string</p>      | Business name associated with customer.                                                                                            |
| <p>bcc\_emails</p><p>string</p>  | Additional email the receipt should be sent to for expense tracking or accounting needs.                                           |
| <p>telephone</p><p>string</p>    | Customer’s telephone number.                                                                                                       |
| <p>address1</p><p>string</p>     | First line of the customer address.                                                                                                |
| <p>address2</p><p>string</p>     | Second line of the customer address.                                                                                               |
| <p>city</p><p>string</p>         | The city where the customer is.                                                                                                    |
| <p>province</p><p>string</p>     | The province where Canadian customer reside. For US Customers, this would be the State of residence.                               |
| <p>country</p><p>string</p>      | The country where the customer is. All country codes should be in ISO 3166 Alpha 2. For Canada, use CA. For United States, use US. |
| <p>postal\_code</p><p>string</p> | The 6 digit address code for Canadian customer. US customers will use a 5-9 digit Zip Code.                                        |
| <p>custom\_id</p><p>string</p>   | A description field to record any general customer identifying information.                                                        |
| <p>cards</p><p>array</p>         | All the non-PCI card details stored with a customer profile.                                                                       |
| <p>subscriptions</p><p>array</p> | All the subscription info for the subscriptions stored with a customer profile.                                                    |

Example Request:

```
curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \
     --data-binary "{
  \"email\": \"brandon@stark.com\",
  \"first_name\": \"Brandon\",
  \"last_name\": \"Stark\",
  \"company\": \"Payfirma\",
  \"bcc_emails\": \"john.snow@stark.com\",
  \"telephone\": \"1234567891\",
  \"address1\": \"No. 1 Road\",
  \"address2\": \"Street 2\",
  \"city\": \"Vancouver\",
  \"province\": \"BC\",
  \"country\": \"Canada\",
  \"postal_code\": \"V6E 1B2\",
  \"custom_id\": \"Internal456\"
}" \
"https://apigateway.payfirma.com/customer-service/customer"
```

Example Response Body:

```
{
  'id': 2992429,
  'lookup_id': 'NV0B6eZB06',
  'email': 'brandon@stark.com',
  'first_name': 'Brandon',
  'last_name': 'Stark',
  'company': 'Payfirma',
  'bcc_emails': 'john.snow@stark.com',
  'telephone': '1234567891',
  'address1': 'No. 1 Road',
  'address2': 'Street 2',
  'city': 'Vancouver',
  'province': 'BC',
  'country': 'Canada',
  'postal_code': 'V6E 1B2',
  'custom_id': 'Internal456',
  'cards':[{"id":123456,"lookup_id":"34cvb54564dfc","card_expiry":"01/20","card_prefix":"4111","card_suffix":"1111","is_default":true,"card_description":"test card"}],
  'subscriptions':[{"id":123456,"lookup_id":"34cvb54564dfc","plan_id":987654,"plan_lookup_id":"98Avb98765dfc","name":"Sample Daily Plan","status":"ACTIVE","amount":10.99,"currency":"CAD","frequency":"DAILY","last_success":1467760023000,"last_run":1467760023000,"next_run":1467760023000,"total_cycles":10,"completed_cycles":3,"remaining_cycles":7,"failed_attempts":1,"delinquent_cycles":0,"delinquent_since":1467760023000}],
}
```

### Retrieve a specific customer <a href="#api-customer-retrieveaspecificcustomer" id="api-customer-retrieveaspecificcustomer"></a>

Get all the attributes of a specific customer profile by using their lookup\_id.

**HTTPS GET**

`/customer/{customer_lookup_id}`

| **URI Parameters**   |                                                                                             |
| -------------------- | ------------------------------------------------------------------------------------------- |
| customer\_lookup\_id | A hashed version of the customer\_id used to identify the customer in the customer service. |

| **Response Attributes**          |                                                                                                                                    |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| <p>id</p><p>number</p>           | Internal ID representation.                                                                                                        |
| <p>lookup\_id</p><p>string</p>   | A hashed identifier used to identify and access saved customers, cards, plans and subscriptions.                                   |
| <p>email</p><p>string</p>        | The email address associated with the customer that will receive the receipt, if that attribute is set to true.                    |
| <p>first\_name</p><p>string</p>  | The first name of the customer.                                                                                                    |
| <p>last\_name</p><p>string</p>   | The customers last name.                                                                                                           |
| <p>company</p><p>string</p>      | Business name associated with customer.                                                                                            |
| <p>bcc\_emails</p><p>string</p>  | Additional email the receipt should be sent to for expense tracking or accounting needs.                                           |
| <p>telephone</p><p>string</p>    | Customer’s telephone number.                                                                                                       |
| <p>address1</p><p>string</p>     | First line of the customer address.                                                                                                |
| <p>address2</p><p>string</p>     | Second line of the customer address.                                                                                               |
| <p>city</p><p>string</p>         | The city where the customer is.                                                                                                    |
| <p>province</p><p>string</p>     | The province where Canadian customer reside. For US Customers, this would be the State of residence.                               |
| <p>country</p><p>string</p>      | The country where the customer is. All country codes should be in ISO 3166 Alpha 2. For Canada, use CA. For United States, use US. |
| <p>postal\_code</p><p>string</p> | The 6 digit address code for Canadian customer. US customers will use a 5-9 digit Zip Code.                                        |
| <p>custom\_id</p><p>string</p>   | A description field to record any general customer identifying information.                                                        |
| <p>cards</p><p>array</p>         | All the non-PCI card details stored with a customer profile.                                                                       |
| <p>subscriptions</p><p>array</p> | All the subscription info for the subscriptions stored with a customer profile.                                                    |

Example Request:

```
curl --include \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \
  "https://apigateway.payfirma.com/customer-service/customer/NV0B6eZB06"
```

Example Response Body:

```
{
  'id': 2992429,
  'lookup_id': 'NV0B6eZB06',
  'email': 'brandon@stark.com',
  'first_name': 'Brandon',
  'last_name': 'Stark',
  'company': 'Payfirma',
  'bcc_emails': 'john.snow@stark.com',
  'telephone': '1234567891',
  'address1': 'No. 1 Road',
  'address2': 'Street 2',
  'city': 'Vancouver',
  'province': 'BC',
  'country': 'Canada',
  'postal_code': 'V6E 1B2',
  'custom_id': 'Internal456',
  'cards':[{"id":123456,"lookup_id":"34cvb54564dfc","card_expiry":"01/20","card_prefix":"4111","card_suffix":"1111","is_default":true,"card_description":"test card"}],
  'subscriptions':[{"id":123456,"lookup_id":"34cvb54564dfc","plan_id":987654,"plan_lookup_id":"98Avb98765dfc","name":"Sample Daily Plan","status":"ACTIVE","amount":10.99,"currency":"CAD","frequency":"DAILY","last_success":1467760023000,"last_run":1467760023000,"next_run":1467760023000,"total_cycles":10,"completed_cycles":3,"remaining_cycles":7,"failed_attempts":1,"delinquent_cycles":0,"delinquent_since":1467760023000}],
}
```

### Retrieve all customers for a specific account <a href="#api-customer-retrieveallcustomersforaspecificaccount" id="api-customer-retrieveallcustomersforaspecificaccount"></a>

Requests a list of all customers according to the parameters you specify.

**HTTPS GET**

`/customer{?limit,before,after,email_address,first_name,last_name,company,with_subscription}`

| **URI Parameters** |                                                                                                                     |
| ------------------ | ------------------------------------------------------------------------------------------------------------------- |
| **limit**          | The number of transactions to be displayed within each page.                                                        |
| **before**         | The begginning of the page cursor. One can use this cursor with a query parameter to get the page before this page. |
| **after**          | The end of the page cursor. One can use this cursor with an after query parameter to get the page after this page.  |
| **email\_address** | The email address associated with the customer that will receive the receipt, if that attribute is set to true.     |
| first\_name        | The first name of the customer.                                                                                     |
| **last\_name**     | The customers last name.                                                                                            |
| **company**        | Business name associated with customer.                                                                             |
| with\_subscription | A boolean identity for whether customers have subscriptions.                                                        |

| **Response Attributes**     |                                                                                                                     |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| <p>entities</p><p>array</p> | The stored customer information that was associated with each transaction.                                          |
| <p>paging</p><p>object</p>  | Parameter to view multiple pages on large queries.                                                                  |
| <p>cursors</p><p>object</p> | Set the boundaries for displayed results.                                                                           |
| <p>before</p><p>string</p>  | The begginning of the page cursor. One can use this cursor with a query parameter to get the page before this page. |
| <p>after</p><p>string</p>   | The end of the page cursor. One can use this cursor with an after query parameter to get the page after this page.  |

Example Request:

```
curl --include \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \
  "https://apigateway.payfirma.com/customer-service/customer?limit=100&before=%273X67XWEE%27&after=%27XWERE836%27&email_address=%27brandon%40stark.com%27&first_name=%27Brandon%27&last_name=%27Stark%27&company=Payfirma&with_subscription=true"
```

Example Response Body:

```
{
  'entities':[{"id":2992429,"lookup_id":"NV0B6eZB06","email":"brandon@stark.com","first_name":"Brandon","last_name":"Stark","company":"Payfirma","bcc_emails":"john.snow@stark.com","telephone":"1234567891","address1":"No. 1 Road","address2":"Street 2","city":"Vancouver","province":"BC","country":"Canada","postal_code":"V6E 1B2","custom_id":"Internal456","cards":[{"id":123456,"lookup_id":"34cvb54564dfc","card_expiry":"01/20","card_prefix":"4111","card_suffix":"1111","is_default":true,"card_description":"test card"}],"subscriptions":[{"id":123456,"lookup_id":"34cvb54564dfc","plan_id":987654,"plan_lookup_id":"98Avb98765dfc","name":"Sample Daily Plan","status":"ACTIVE","amount":10.99,"currency":"CAD","frequency":"DAILY","last_success":1467760023000,"last_run":1467760023000,"next_run":1467760023000,"total_cycles":10,"completed_cycles":3,"remaining_cycles":7,"failed_attempts":1,"delinquent_cycles":0,"delinquent_since":1467760023000}]}],
  'paging': {"cursors":{"before":"51pmdq8z5rdbRWoKYrje","after":"xv9Aq54WEy3RyWEBXypK"}},
}
```

### Retrieve plan's customers <a href="#api-customer-retrieveplanscustomers" id="api-customer-retrieveplanscustomers"></a>

Query all customers who subscribed to a given plan lookup Id

**HTTPS GET**

`/customer/plan/{plan_lookup_id}/{?limit,before,after,email_address,first_name,last_name,company}`

| **URI Parameters**     |                                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------- |
| **limit**              | The number of transactions to be displayed within each page.                                                        |
| **before**             | The begginning of the page cursor. One can use this cursor with a query parameter to get the page before this page. |
| **after**              | The end of the page cursor. One can use this cursor with an after query parameter to get the page after this page.  |
| **email\_address**     | The email address associated with the customer that will receive the receipt, if that attribute is set to true.     |
| **first\_name**        | The first name of the customer.                                                                                     |
| last\_name             | The customers last name.                                                                                            |
| **company**            | Business name associated with customer.                                                                             |
| **with\_subscription** | A boolean identity for whether customers have subscriptions.                                                        |

| **Response Attributes**     |                                                                                                                     |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| <p>entities</p><p>array</p> | The stored customer information that was associated with each transaction.                                          |
| <p>paging</p><p>object</p>  | Parameter to view multiple pages on large queries.                                                                  |
| <p>cursors</p><p>object</p> | Set the boundaries for displayed results.                                                                           |
| <p>before</p><p>string</p>  | The begginning of the page cursor. One can use this cursor with a query parameter to get the page before this page. |
| <p>after</p><p>string</p>   | The end of the page cursor. One can use this cursor with an after query parameter to get the page after this page.  |

Example Request:

```
curl --include \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \
  "https://apigateway.payfirma.com/customer-service/customer/plan/99ffb59876mnb?limit=100&before="3X67XWEE"&after="XWERE836"&email_address="brandon@stark.com"&first_name="Brandon"&last_name="Stark"&company=Payfirma"
```

Example Response Body:

```
{
  'entities':[{"id":2992429,"lookup_id":"NV0B6eZB06","email":"brandon@stark.com","first_name":"Brandon","last_name":"Stark","company":"Payfirma","bcc_emails":"john.snow@stark.com","telephone":"1234567891","address1":"No. 1 Road","address2":"Street 2","city":"Vancouver","province":"BC","country":"Canada","postal_code":"V6E 1B2","custom_id":"Internal456","cards":[{"id":123456,"lookup_id":"34cvb54564dfc","card_expiry":"01/20","card_prefix":"4111","card_suffix":"1111","is_default":true,"card_description":"test card"}],"subscriptions":[{"id":123456,"lookup_id":"34cvb54564dfc","plan_id":987654,"plan_lookup_id":"98Avb98765dfc","name":"Sample Daily Plan","status":"ACTIVE","amount":10.99,"currency":"CAD","frequency":"DAILY","last_success":1467760023000,"last_run":1467760023000,"next_run":1467760023000,"total_cycles":10,"completed_cycles":3,"remaining_cycles":7,"failed_attempts":1,"delinquent_cycles":0,"delinquent_since":1467760023000}]}],
  'paging': {"cursors":{"before":"51pmdq8z5rdbRWoKYrje","after":"xv9Aq54WEy3RyWEBXypK"}},
}
```

### Update a customer <a href="#api-customer-updateacustomer" id="api-customer-updateacustomer"></a>

Change the attributes of a customer profile using their customer lookup\_id.

**HTTPS PUT**

`/customer/{customer_lookup_id}`

| **URI Parameters**                         |                                                                                             |
| ------------------------------------------ | ------------------------------------------------------------------------------------------- |
| <p>customer\_lookup\_id</p><p>REQUIRED</p> | A hashed version of the customer\_id used to identify the customer in the customer service. |

| **Request Arguments** |                                                                                                                                    |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| email                 | The email address associated with the customer that will receive the receipt, if that attribute is set to true.                    |
| first\_name           | The first name of the customer.                                                                                                    |
| last\_name            | The customers last name.                                                                                                           |
| **company**           | Business name associated with customer.                                                                                            |
| **bcc\_emails**       | Additional email the receipt should be sent to for expense tracking or accounting needs.                                           |
| **telephone**         | Customer’s telephone number.                                                                                                       |
| **address1**          | First line of the customer address.                                                                                                |
| **address2**          | Second line of the customer address.                                                                                               |
| **city**              | The city where the customer is.                                                                                                    |
| **province**          | The province where Canadian customer reside. For US Customers, this would be the State of residence.                               |
| **country**           | The country where the customer is. All country codes should be in ISO 3166 Alpha 2. For Canada, use CA. For United States, use US. |
| **postal\_code**      | The 6 digit address code for Canadian customer. US customers will use a 5-9 digit Zip Code.                                        |
| **custom\_id**        | A description field to record any general customer identifying information.                                                        |

| **Response Attributes**          |                                                                                                                                    |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| <p>id</p><p>number</p>           | Internal ID representation.                                                                                                        |
| <p>lookup\_id</p><p>string</p>   | A hashed identifier used to identify and access saved customers, cards, plans and subscriptions.                                   |
| <p>email</p><p>string</p>        | The email address associated with the customer that will receive the receipt, if that attribute is set to true.                    |
| <p>first\_name</p><p>string</p>  | The first name of the customer.                                                                                                    |
| <p>last\_name</p><p>string</p>   | The customers last name.                                                                                                           |
| <p>company</p><p>string</p>      | Business name associated with customer.                                                                                            |
| <p>bcc\_emails</p><p>string</p>  | Additional email the receipt should be sent to for expense tracking or accounting needs.                                           |
| <p>telephone</p><p>string</p>    | Customer’s telephone number.                                                                                                       |
| <p>address1</p><p>string</p>     | First line of the customer address.                                                                                                |
| <p>address2</p><p>string</p>     | Second line of the customer address.                                                                                               |
| <p>city</p><p>string</p>         | The city where the customer is.                                                                                                    |
| <p>province</p><p>string</p>     | The province where Canadian customer reside. For US Customers, this would be the State of residence.                               |
| <p>country</p><p>string</p>      | The country where the customer is. All country codes should be in ISO 3166 Alpha 2. For Canada, use CA. For United States, use US. |
| <p>postal\_code</p><p>string</p> | The 6 digit address code for Canadian customer. US customers will use a 5-9 digit Zip Code.                                        |
| <p>custom\_id</p><p>string</p>   | A description field to record any general customer identifying information.                                                        |
| <p>cards</p><p>array</p>         | All the non-PCI card details stored with a customer profile.                                                                       |
| <p>subscriptions</p><p>array</p> | All the subscription info for the subscriptions stored with a customer profile.                                                    |

Example Request:

```
curl --include \
     --request PUT \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \
     --data-binary "{
  \"email\": \"brandon@stark.com\",
  \"first_name\": \"Brandon\",
  \"last_name\": \"Stark\",
  \"company\": \"Payfirma\",
  \"bcc_emails\": \"john.snow@stark.com\",
  \"telephone\": \"1234567891\",
  \"address1\": \"No. 1 Road\",
  \"address2\": \"Street 2\",
  \"city\": \"Vancouver\",
  \"province\": \"BC\",
  \"country\": \"Canada\",
  \"postal_code\": \"V6E 1B2\",
  \"custom_id\": \"Internal456\"
}" \
"https://apigateway.payfirma.com/customer-service/customer/NV0B6eZB06"
```

Example Request Body:

```
{
  'email': 'brandon@stark.com',
  'first_name': 'Brandon',
  'last_name': 'Stark',
  'company': 'Payfirma',
  'bcc_emails': 'john.snow@stark.com',
  'telephone': '1234567891',
  'address1': 'No. 1 Road',
  'address2': 'Street 2',
  'city': 'Vancouver',
  'province': 'BC',
  'country': 'Canada',
  'postal_code': 'V6E 1B2',
  'custom_id': 'Internal456',
}
```

Example Response Body:

```
{
  'id': 2992429,
  'lookup_id': 'NV0B6eZB06',
  'email': 'brandon@stark.com',
  'first_name': 'Brandon',
  'last_name': 'Stark',
  'company': 'Payfirma',
  'bcc_emails': 'john.snow@stark.com',
  'telephone': '1234567891',
  'address1': 'No. 1 Road',
  'address2': 'Street 2',
  'city': 'Vancouver',
  'province': 'BC',
  'country': 'Canada',
  'postal_code': 'V6E 1B2',
  'custom_id': 'Internal456',
  'cards':[{"id":123456,"lookup_id":"34cvb54564dfc","card_expiry":"01/20","card_prefix":"4111","card_suffix":"1111","is_default":true,"card_description":"test card"}],
  'subscriptions':[{"id":123456,"lookup_id":"34cvb54564dfc","plan_id":987654,"plan_lookup_id":"98Avb98765dfc","name":"Sample Daily Plan","status":"ACTIVE","amount":10.99,"currency":"CAD","frequency":"DAILY","last_success":1467760023000,"last_run":1467760023000,"next_run":1467760023000,"total_cycles":10,"completed_cycles":3,"remaining_cycles":7,"failed_attempts":1,"delinquent_cycles":0,"delinquent_since":1467760023000}],
}
```

## Card <a href="#api-customer-card" id="api-customer-card"></a>

Store a credit card with a customer profile and update the card object as needed.

**BASE URI**

`https://apigateway.payfirma.com/customer-service`

### Add a new card <a href="#api-customer-addanewcard" id="api-customer-addanewcard"></a>

Store a new credit card to a customer profile.

**HTTPS POST**

`/customer/{customer_lookup_id}/card`

| **URI Parameters**                         |                                                                                             |
| ------------------------------------------ | ------------------------------------------------------------------------------------------- |
| <p>customer\_lookup\_id</p><p>REQUIRED</p> | A hashed version of the customer\_id used to identify the customer in the customer service. |

| **Request Arguments**                     |                                                                                                                                                                                                                                                                                                                 |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <p>card\_expiry\_month</p><p>REQUIRED</p> | The double-digit month the card expires, e.g. for August, use 08.                                                                                                                                                                                                                                               |
| <p>card\_expiry\_year</p><p>REQUIRED</p>  | Expiry year - in double digits - of the associated credit card number, e.g. for 2017, use 17.                                                                                                                                                                                                                   |
| <p>card\_number</p><p>REQUIRED</p>        | The credit card number (16 digits for most card brands and 15 digits for American Express).                                                                                                                                                                                                                     |
| <p>cvv2</p><p>REQUIRED</p>                | A credit card’s verification code, otherwise known as CVC or CVV; the three or four-digit number on the back of most major cards, and the four digit number found on the front of American Express cards. We strongly recommend that you utilize the cvv2 field to help protect against fraud and charge-backs. |
| **currency**                              | DEFAULT is true for first card and false for the rest.                                                                                                                                                                                                                                                          |

| **Response Attributes**          |                                                                                                                                    |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| <p>id</p><p>number</p>           | Internal ID representation.                                                                                                        |
| <p>lookup\_id</p><p>string</p>   | A hashed identifier used to identify and access saved customers, cards, plans and subscriptions.                                   |
| <p>email</p><p>string</p>        | The email address associated with the customer that will receive the receipt, if that attribute is set to true.                    |
| <p>first\_name</p><p>string</p>  | The first name of the customer.                                                                                                    |
| <p>last\_name</p><p>string</p>   | The customers last name.                                                                                                           |
| <p>company</p><p>string</p>      | Business name associated with customer.                                                                                            |
| <p>bcc\_emails</p><p>string</p>  | Additional email the receipt should be sent to for expense tracking or accounting needs.                                           |
| <p>telephone</p><p>string</p>    | Customer’s telephone number.                                                                                                       |
| <p>address1</p><p>string</p>     | First line of the customer address.                                                                                                |
| <p>address2</p><p>string</p>     | Second line of the customer address.                                                                                               |
| <p>city</p><p>string</p>         | The city where the customer is.                                                                                                    |
| <p>province</p><p>string</p>     | The province where Canadian customer reside. For US Customers, this would be the State of residence.                               |
| <p>country</p><p>string</p>      | The country where the customer is. All country codes should be in ISO 3166 Alpha 2. For Canada, use CA. For United States, use US. |
| <p>postal\_code</p><p>string</p> | The 6 digit address code for Canadian customer. US customers will use a 5-9 digit Zip Code.                                        |
| <p>custom\_id</p><p>string</p>   | A description field to record any general customer identifying information.                                                        |
| <p>cards</p><p>array</p>         | All the non-PCI card details stored with a customer profile.                                                                       |
| <p>subscriptions</p><p>array</p> | All the subscription info for the subscriptions stored with a customer profile.                                                    |

Example Request:

```
curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \
     --data-binary "{
  \"card_expiry_month\": 11,
  \"card_expiry_year\": 16,
  \"card_number\": \"4111111111111111\",
  \"cvv2\": \"595\",
  \"is_default\": true,
  \"card_description\": \"test card\"
}" \
"https://apigateway.payfirma.com/customer-service/customer/NV0B6eZB06/card"
```

Example Request Body:

```
{
  'card_expiry_month': 11,
  'card_expiry_year': 16,
  'card_number': '4111111111111111',
  'cvv2': '595',
  'is_default': true,
  'card_description': 'test card',
}
```

Example Response Body:

```
{
  'id': 2992429,
  'lookup_id': 'NV0B6eZB06',
  'email': 'brandon@stark.com',
  'first_name': 'Brandon',
  'last_name': 'Stark',
  'company': 'Payfirma',
  'bcc_emails': 'john.snow@stark.com',
  'telephone': '1234567891',
  'address1': 'No. 1 Road',
  'address2': 'Street 2',
  'city': 'Vancouver',
  'province': 'BC',
  'country': 'Canada',
  'postal_code': 'V6E 1B2',
  'custom_id': 'Internal456',
  'cards':[{"id":123456,"lookup_id":"34cvb54564dfc","card_expiry":"01/20","card_prefix":"4111","card_suffix":"1111","is_default":true,"card_description":"test card"}],
  'subscriptions':[{"id":123456,"lookup_id":"34cvb54564dfc","plan_id":987654,"plan_lookup_id":"98Avb98765dfc","name":"Sample Daily Plan","status":"ACTIVE","amount":10.99,"currency":"CAD","frequency":"DAILY","last_success":1467760023000,"last_run":1467760023000,"next_run":1467760023000,"total_cycles":10,"completed_cycles":3,"remaining_cycles":7,"failed_attempts":1,"delinquent_cycles":0,"delinquent_since":1467760023000}],
}
```

### Update a card <a href="#api-customer-updateacard" id="api-customer-updateacard"></a>

Update an existing credit card object.

**HTTPS PATCH**

`/customer/{customer_lookup_id}/card/{card_lookup_id}`

| **URI Parameters**                         |                                                                                             |
| ------------------------------------------ | ------------------------------------------------------------------------------------------- |
| <p>customer\_lookup\_id</p><p>REQUIRED</p> | A hashed version of the customer\_id used to identify the customer in the customer service. |
| <p>card\_lookup\_id</p><p>REQUIRED</p>     | Credit card Lookup ID from Customer Vault.                                                  |

| **Request Arguments** |                                                                                       |
| --------------------- | ------------------------------------------------------------------------------------- |
| is\_default           | DEFAULT is true for first card and false for the rest.                                |
| card\_description     | A description you can define for each card to help with card management and tracking. |

| **Response Attributes**          |                                                                                                                                    |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| <p>id</p><p>number</p>           | Internal ID representation.                                                                                                        |
| <p>lookup\_id</p><p>string</p>   | A hashed identifier used to identify and access saved customers, cards, plans and subscriptions.                                   |
| <p>email</p><p>string</p>        | The email address associated with the customer that will receive the receipt, if that attribute is set to true.                    |
| <p>first\_name</p><p>string</p>  | The first name of the customer.                                                                                                    |
| <p>last\_name</p><p>string</p>   | The customers last name.                                                                                                           |
| <p>company</p><p>string</p>      | Business name associated with customer.                                                                                            |
| <p>bcc\_emails</p><p>string</p>  | Additional email the receipt should be sent to for expense tracking or accounting needs.                                           |
| <p>telephone</p><p>string</p>    | Customer’s telephone number.                                                                                                       |
| <p>address1</p><p>string</p>     | First line of the customer address.                                                                                                |
| <p>address2</p><p>string</p>     | Second line of the customer address.                                                                                               |
| <p>city</p><p>string</p>         | The city where the customer is.                                                                                                    |
| <p>province</p><p>string</p>     | The province where Canadian customer reside. For US Customers, this would be the State of residence.                               |
| <p>country</p><p>string</p>      | The country where the customer is. All country codes should be in ISO 3166 Alpha 2. For Canada, use CA. For United States, use US. |
| <p>postal\_code</p><p>string</p> | The 6 digit address code for Canadian customer. US customers will use a 5-9 digit Zip Code.                                        |
| <p>custom\_id</p><p>string</p>   | A description field to record any general customer identifying information.                                                        |
| <p>cards</p><p>array</p>         | All the non-PCI card details stored with a customer profile.                                                                       |
| <p>subscriptions</p><p>array</p> | All the subscription info for the subscriptions stored with a customer profile.                                                    |

Example Request:

```
curl --include \
     --request PATCH \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \
     --data-binary "{
  \"is_default\": true,
  \"card_description\": \"test card\"
}" \
"https://apigateway.payfirma.com/customer-service/customer/NV0B6eZB06/card/34cvb54564dfc"
```

Example Request Body:

```
{
  'is_default': true,
  'card_description': 'test card',
}
```

Example Response Body:

```
{
  'id': 2992429,
  'lookup_id': 'NV0B6eZB06',
  'email': 'brandon@stark.com',
  'first_name': 'Brandon',
  'last_name': 'Stark',
  'company': 'Payfirma',
  'bcc_emails': 'john.snow@stark.com',
  'telephone': '1234567891',
  'address1': 'No. 1 Road',
  'address2': 'Street 2',
  'city': 'Vancouver',
  'province': 'BC',
  'country': 'Canada',
  'postal_code': 'V6E 1B2',
  'custom_id': 'Internal456',
  'cards':[{"id":123456,"lookup_id":"34cvb54564dfc","card_expiry":"01/20","card_prefix":"4111","card_suffix":"1111","is_default":true,"card_description":"test card"}],
  'subscriptions':[{"id":123456,"lookup_id":"34cvb54564dfc","plan_id":987654,"plan_lookup_id":"98Avb98765dfc","name":"Sample Daily Plan","status":"ACTIVE","amount":10.99,"currency":"CAD","frequency":"DAILY","last_success":1467760023000,"last_run":1467760023000,"next_run":1467760023000,"total_cycles":10,"completed_cycles":3,"remaining_cycles":7,"failed_attempts":1,"delinquent_cycles":0,"delinquent_since":1467760023000}],
}
```

### Remove a card <a href="#api-customer-removeacard" id="api-customer-removeacard"></a>

Remove a credit card from a customer’s profile.

**HTTPS DELETE**

`/customer/{customer_lookup_id}/card/{card_lookup_id}`

| **URI Parameters**                         |                                                                                             |
| ------------------------------------------ | ------------------------------------------------------------------------------------------- |
| <p>customer\_lookup\_id</p><p>REQUIRED</p> | A hashed version of the customer\_id used to identify the customer in the customer service. |
| <p>card\_lookup\_id</p><p>REQUIRED</p>     | Credit card Lookup ID from Customer Vault.                                                  |

| **Response Attributes**          |                                                                                                                                    |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| <p>id</p><p>number</p>           | Internal ID representation.                                                                                                        |
| <p>lookup\_id</p><p>string</p>   | A hashed identifier used to identify and access saved customers, cards, plans and subscriptions.                                   |
| <p>email</p><p>string</p>        | The email address associated with the customer that will receive the receipt, if that attribute is set to true.                    |
| <p>first\_name</p><p>string</p>  | The first name of the customer.                                                                                                    |
| <p>last\_name</p><p>string</p>   | The customers last name.                                                                                                           |
| <p>company</p><p>string</p>      | Business name associated with customer.                                                                                            |
| <p>bcc\_emails</p><p>string</p>  | Additional email the receipt should be sent to for expense tracking or accounting needs.                                           |
| <p>telephone</p><p>string</p>    | Customer’s telephone number.                                                                                                       |
| <p>address1</p><p>string</p>     | First line of the customer address.                                                                                                |
| <p>address2</p><p>string</p>     | Second line of the customer address.                                                                                               |
| <p>city</p><p>string</p>         | The city where the customer is.                                                                                                    |
| <p>province</p><p>string</p>     | The province where Canadian customer reside. For US Customers, this would be the State of residence.                               |
| <p>country</p><p>string</p>      | The country where the customer is. All country codes should be in ISO 3166 Alpha 2. For Canada, use CA. For United States, use US. |
| <p>postal\_code</p><p>string</p> | The 6 digit address code for Canadian customer. US customers will use a 5-9 digit Zip Code.                                        |
| <p>custom\_id</p><p>string</p>   | A description field to record any general customer identifying information.                                                        |
| <p>cards</p><p>array</p>         | All the non-PCI card details stored with a customer profile.                                                                       |
| <p>subscriptions</p><p>array</p> | All the subscription info for the subscriptions stored with a customer profile.                                                    |

Example Request:

```
curl --include \
     --request DELETE \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \
  "https://apigateway.payfirma.com/customer-service/customer/NV0B6eZB06/card/34cvb54564dfc"
```

Example Response Body:

```
{
  'id': 2992429,
  'lookup_id': 'NV0B6eZB06',
  'email': 'brandon@stark.com',
  'first_name': 'Brandon',
  'last_name': 'Stark',
  'company': 'Payfirma',
  'bcc_emails': 'john.snow@stark.com',
  'telephone': '1234567891',
  'address1': 'No. 1 Road',
  'address2': 'Street 2',
  'city': 'Vancouver',
  'province': 'BC',
  'country': 'Canada',
  'postal_code': 'V6E 1B2',
  'custom_id': 'Internal456',
  'cards':[{"id":123456,"lookup_id":"34cvb54564dfc","card_expiry":"01/20","card_prefix":"4111","card_suffix":"1111","is_default":true,"card_description":"test card"}],
  'subscriptions':[{"id":123456,"lookup_id":"34cvb54564dfc","plan_id":987654,"plan_lookup_id":"98Avb98765dfc","name":"Sample Daily Plan","status":"ACTIVE","amount":10.99,"currency":"CAD","frequency":"DAILY","last_success":1467760023000,"last_run":1467760023000,"next_run":1467760023000,"total_cycles":10,"completed_cycles":3,"remaining_cycles":7,"failed_attempts":1,"delinquent_cycles":0,"delinquent_since":1467760023000}],
}
```

## Subscription <a href="#api-customer-subscription" id="api-customer-subscription"></a>

Use stored customer profiles and cards to set up subscription payments based off your recurring plans

**BASE URI**

`https://apigateway.payfirma.com/customer-service`

### Add a new subscription <a href="#api-customer-addanewsubscription" id="api-customer-addanewsubscription"></a>

Subscribe a given customer to a plan

**HTTPS POST**

`/customer/{customer_lookup_id}/subscription`

| **Request Arguments**                  |                                                                                                                     |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| <p>plan\_lookup\_id</p><p>REQUIRED</p> | A hashed version of the plan\_id used to identify the plan in the customer & plan service.                          |
| <p>card\_lookup\_id</p><p>REQUIRED</p> | Credit card Lookup ID from Customer Vault.                                                                          |
| **amount**                             | Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.                                               |
| <p>start\_date</p><p>REQUIRED</p>      | UNIX time representation of the start date for a subscription, represented in milliseconds. It should be in future. |
| **email**                              | The email address associated with the customer that will receive the receipt, if that attribute is set to true.     |
| bcc\_emails                            | Additional email the receipt should be sent to for expense tracking or accounting needs.                            |
| **description**                        | An open field to record any information about the payment you want to appear in the customer’s receipt.             |

| **Response Attributes**          |                                                                                                                                    |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| <p>id</p><p>number</p>           | Internal ID representation.                                                                                                        |
| <p>lookup\_id</p><p>string</p>   | A hashed identifier used to identify and access saved customers, cards, plans and subscriptions.                                   |
| <p>email</p><p>string</p>        | The email address associated with the customer that will receive the receipt, if that attribute is set to true.                    |
| <p>first\_name</p><p>string</p>  | The first name of the customer.                                                                                                    |
| <p>last\_name</p><p>string</p>   | The customers last name.                                                                                                           |
| <p>company</p><p>string</p>      | Business name associated with customer.                                                                                            |
| <p>bcc\_emails</p><p>string</p>  | Additional email the receipt should be sent to for expense tracking or accounting needs.                                           |
| <p>telephone</p><p>string</p>    | Customer’s telephone number.                                                                                                       |
| <p>address1</p><p>string</p>     | First line of the customer address.                                                                                                |
| <p>address2</p><p>string</p>     | Second line of the customer address.                                                                                               |
| <p>city</p><p>string</p>         | The city where the customer is.                                                                                                    |
| <p>province</p><p>string</p>     | The province where Canadian customer reside. For US Customers, this would be the State of residence.                               |
| <p>country</p><p>string</p>      | The country where the customer is. All country codes should be in ISO 3166 Alpha 2. For Canada, use CA. For United States, use US. |
| <p>postal\_code</p><p>string</p> | The 6 digit address code for Canadian customer. US customers will use a 5-9 digit Zip Code.                                        |
| <p>custom\_id</p><p>string</p>   | A description field to record any general customer identifying information.                                                        |
| <p>cards</p><p>array</p>         | All the non-PCI card details stored with a customer profile.                                                                       |
| <p>subscriptions</p><p>array</p> | All the subscription info for the subscriptions stored with a customer profile.                                                    |

**Example Request:**

```
curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \
     --data-binary "{
  \"plan_lookup_id\": \"99ffb59876mnb\",
  \"card_lookup_id\": \"34cvb54564dfc\",
  \"amount\": 10.99,
  \"start_date\": 1467760023000,
  \"email\": \"brandon@stark.com\",
  \"bcc_emails\": \"nedd@stark.com, robb@stark.com\",
  \"description\": \"My test plan\"
}" \
"https://apigateway.payfirma.com/customer-service/customer/NV0B6eZB06/subscription"
```

Example Request Body:

```
{
  'plan_lookup_id': '99ffb59876mnb',
  'card_lookup_id': '34cvb54564dfc',
  'amount': 10.99,
  'start_date': 1467760023000,
  'email': 'brandon@stark.com',
  'bcc_emails': 'nedd@stark.com, robb@stark.com',
  'description': 'My test plan',
}
```

Example Response Body:

```
{
  'id': 2992429,
  'lookup_id': 'NV0B6eZB06',
  'email': 'brandon@stark.com',
  'first_name': 'Brandon',
  'last_name': 'Stark',
  'company': 'Payfirma',
  'bcc_emails': 'john.snow@stark.com',
  'telephone': '1234567891',
  'address1': 'No. 1 Road',
  'address2': 'Street 2',
  'city': 'Vancouver',
  'province': 'BC',
  'country': 'Canada',
  'postal_code': 'V6E 1B2',
  'custom_id': 'Internal456',
  'cards':[{"id":123456,"lookup_id":"34cvb54564dfc","card_expiry":"01/20","card_prefix":"4111","card_suffix":"1111","is_default":true,"card_description":"test card"}],
  'subscriptions':[{"id":123456,"lookup_id":"34cvb54564dfc","plan_id":987654,"plan_lookup_id":"98Avb98765dfc","name":"Sample Daily Plan","status":"ACTIVE","amount":10.99,"currency":"CAD","frequency":"DAILY","last_success":1467760023000,"last_run":1467760023000,"next_run":1467760023000,"total_cycles":10,"completed_cycles":3,"remaining_cycles":7,"failed_attempts":1,"delinquent_cycles":0,"delinquent_since":1467760023000}],
}
```

### Update a subscription <a href="#api-customer-updateasubscription" id="api-customer-updateasubscription"></a>

Update a subscription: Update the details of a subscription for a given customer lookup\_id and a subscription lookup\_id.

**HTTPS PATCH**

`/customer/{customer_lookup_id}/subscription/subscriptionLookupId`

| **Request Arguments** |                                                                                                                 |
| --------------------- | --------------------------------------------------------------------------------------------------------------- |
| **status**            | ACTIVE, CANCELED, PAUSED                                                                                        |
| card\_lookup\_id      | Credit card Lookup ID from Customer Vault.                                                                      |
| **amount**            | Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.                                           |
| **email**             | The email address associated with the customer that will receive the receipt, if that attribute is set to true. |
| bcc\_emails           | Additional email the receipt should be sent to for expense tracking or accounting needs.                        |
| **description**       | An open field to record any information about the payment you want to appear in the customer’s receipt.         |

| **Response Attributes**          |                                                                                                                                    |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| <p>id</p><p>number</p>           | Internal ID representation.                                                                                                        |
| <p>lookup\_id</p><p>string</p>   | A hashed identifier used to identify and access saved customers, cards, plans and subscriptions.                                   |
| <p>email</p><p>string</p>        | The email address associated with the customer that will receive the receipt, if that attribute is set to true.                    |
| <p>first\_name</p><p>string</p>  | The first name of the customer.                                                                                                    |
| <p>last\_name</p><p>string</p>   | The customers last name.                                                                                                           |
| <p>company</p><p>string</p>      | Business name associated with customer.                                                                                            |
| <p>bcc\_emails</p><p>string</p>  | Additional email the receipt should be sent to for expense tracking or accounting needs.                                           |
| <p>telephone</p><p>string</p>    | Customer’s telephone number.                                                                                                       |
| <p>address1</p><p>string</p>     | First line of the customer address.                                                                                                |
| <p>address2</p><p>string</p>     | Second line of the customer address.                                                                                               |
| <p>city</p><p>string</p>         | The city where the customer is.                                                                                                    |
| <p>province</p><p>string</p>     | The province where Canadian customer reside. For US Customers, this would be the State of residence.                               |
| <p>country</p><p>string</p>      | The country where the customer is. All country codes should be in ISO 3166 Alpha 2. For Canada, use CA. For United States, use US. |
| <p>postal\_code</p><p>string</p> | The 6 digit address code for Canadian customer. US customers will use a 5-9 digit Zip Code.                                        |
| <p>custom\_id</p><p>string</p>   | A description field to record any general customer identifying information.                                                        |
| <p>cards</p><p>array</p>         | All the non-PCI card details stored with a customer profile.                                                                       |
| <p>subscriptions</p><p>array</p> | All the subscription info for the subscriptions stored with a customer profile.                                                    |

Example Request:

```
curl --include \
     --request PATCH \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \
     --data-binary "{
  \"card_lookup_id\": \"34cvb54564dfc\",
  \"amount\": 10.99,
  \"email\": \"brandon@stark.com\",
  \"bcc_emails\": \"nedd@stark.com, robb@stark.com\",
  \"description\": \"My test plan\"
}" \
"https://apigateway.payfirma.com/customer-service/customer/NV0B6eZB06/subscription/34cvb54564dfc"
```

Example Request Body:

```
{
  'card_lookup_id': '34cvb54564dfc',
  'amount': 10.99,
  'status': 'PAUSED',
  'email': 'brandon@stark.com',
  'bcc_emails': 'nedd@stark.com, robb@stark.com',
  'description': 'My test plan',
}
```

Example Response Body:

```
{
  'id': 2992429,
  'lookup_id': 'NV0B6eZB06',
  'email': 'brandon@stark.com',
  'first_name': 'Brandon',
  'last_name': 'Stark',
  'company': 'Payfirma',
  'bcc_emails': 'john.snow@stark.com',
  'telephone': '1234567891',
  'address1': 'No. 1 Road',
  'address2': 'Street 2',
  'city': 'Vancouver',
  'province': 'BC',
  'country': 'Canada',
  'postal_code': 'V6E 1B2',
  'custom_id': 'Internal456',
  'cards':[{"id":123456,"lookup_id":"34cvb54564dfc","card_expiry":"01/20","card_prefix":"4111","card_suffix":"1111","is_default":true,"card_description":"test card"}],
  'subscriptions':[{"id":123456,"lookup_id":"34cvb54564dfc","plan_id":987654,"plan_lookup_id":"98Avb98765dfc","name":"Sample Daily Plan","status":"ACTIVE","amount":10.99,"currency":"CAD","frequency":"DAILY","last_success":1467760023000,"last_run":1467760023000,"next_run":1467760023000,"total_cycles":10,"completed_cycles":3,"remaining_cycles":7,"failed_attempts":1,"delinquent_cycles":0,"delinquent_since":1467760023000}],
}
```

### Cancel a subscription <a href="#api-customer-cancelasubscription" id="api-customer-cancelasubscription"></a>

Cancel a subscription: Cancel all future payments scheduled on a subscription plan by changing the status of the subscription

**HTTPS PATCH**

`/customer/{customer_lookup_id}/subscription/subscriptionLookupId`

| **Request Arguments** |           |
| --------------------- | --------- |
| **status**            | CANCELLED |

| **Response Attributes**          |                                                                                                                                    |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| <p>id</p><p>number</p>           | Internal ID representation.                                                                                                        |
| <p>lookup\_id</p><p>string</p>   | A hashed identifier used to identify and access saved customers, cards, plans and subscriptions.                                   |
| <p>email</p><p>string</p>        | The email address associated with the customer that will receive the receipt, if that attribute is set to true.                    |
| <p>first\_name</p><p>string</p>  | The first name of the customer.                                                                                                    |
| <p>last\_name</p><p>string</p>   | The customers last name.                                                                                                           |
| <p>company</p><p>string</p>      | Business name associated with customer.                                                                                            |
| <p>bcc\_emails</p><p>string</p>  | Additional email the receipt should be sent to for expense tracking or accounting needs.                                           |
| <p>telephone</p><p>string</p>    | Customer’s telephone number.                                                                                                       |
| <p>address1</p><p>string</p>     | First line of the customer address.                                                                                                |
| <p>address2</p><p>string</p>     | Second line of the customer address.                                                                                               |
| <p>city</p><p>string</p>         | The city where the customer is.                                                                                                    |
| <p>province</p><p>string</p>     | The province where Canadian customer reside. For US Customers, this would be the State of residence.                               |
| <p>country</p><p>string</p>      | The country where the customer is. All country codes should be in ISO 3166 Alpha 2. For Canada, use CA. For United States, use US. |
| <p>postal\_code</p><p>string</p> | The 6 digit address code for Canadian customer. US customers will use a 5-9 digit Zip Code.                                        |
| <p>custom\_id</p><p>string</p>   | A description field to record any general customer identifying information.                                                        |
| <p>cards</p><p>array</p>         | All the non-PCI card details stored with a customer profile.                                                                       |
| <p>subscriptions</p><p>array</p> | All the subscription info for the subscriptions stored with a customer profile.                                                    |

Example Request:

```
curl --include \
     --request PATCH \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \
     --data-binary "{
  \"card_lookup_id\": \"34cvb54564dfc\",
  \"amount\": 10.99,
  \"email\": \"brandon@stark.com\",
  \"bcc_emails\": \"nedd@stark.com, robb@stark.com\",
  \"description\": \"My test plan\"
}" \
"https://apigateway.payfirma.com/customer-service/customer/NV0B6eZB06/subscription/34cvb54564dfc"
```

Example Request Body:

```
{
  'status': 'CANCELLED',
}
```

Example Response Body:

```
{
  'id': 2992429,
  'lookup_id': 'NV0B6eZB06',
  'email': 'brandon@stark.com',
  'first_name': 'Brandon',
  'last_name': 'Stark',
  'company': 'Payfirma',
  'bcc_emails': 'john.snow@stark.com',
  'telephone': '1234567891',
  'address1': 'No. 1 Road',
  'address2': 'Street 2',
  'city': 'Vancouver',
  'province': 'BC',
  'country': 'Canada',
  'postal_code': 'V6E 1B2',
  'custom_id': 'Internal456',
  'cards':[{"id":123456,"lookup_id":"34cvb54564dfc","card_expiry":"01/20","card_prefix":"4111","card_suffix":"1111","is_default":true,"card_description":"test card"}],
  'subscriptions':[{"id":123456,"lookup_id":"34cvb54564dfc","plan_id":987654,"plan_lookup_id":"98Avb98765dfc","name":"Sample Daily Plan","status":"ACTIVE","amount":10.99,"currency":"CAD","frequency":"DAILY","last_success":1467760023000,"last_run":1467760023000,"next_run":1467760023000,"total_cycles":10,"completed_cycles":3,"remaining_cycles":7,"failed_attempts":1,"delinquent_cycles":0,"delinquent_since":1467760023000}],
}
```