# Customers

Manage customer information, payment agreements, and customer data in FarPay. This section covers all customer-related operations including creating, updating, and managing customer payment instruments.

## Overview

A **Customer** is a person or business that receives invoices from your company and can pay using FarPay's payment technology. Customers can have **Payment Instruments** (agreements) that enable recurring payments.

A **Customer** is a person or business that receives invoices from your company and can pay using FarPay's payment technology. Customers can have **Payment Instruments** (agreements) that enable recurring payments.

## Customer Object

### Required Properties

| Property         | Type   | Description                | Constraints        |
| ---------------- | ------ | -------------------------- | ------------------ |
| `CustomerNumber` | string | Unique customer identifier | Max 15 digits      |
| `Name`           | string | Customer's full name       | Max 255 characters |
| `Email`          | string | Customer's email address   | Max 255 characters |

### Optional Properties

| Property           | Type    | Description                     | Constraints                                 |
| ------------------ | ------- | ------------------------------- | ------------------------------------------- |
| `PoBox`            | string  | Post office box                 | Max 20 characters                           |
| `Street`           | string  | Street address                  | Max 255 characters                          |
| `AdditionalStreet` | string  | Additional address line         | Max 255 characters                          |
| `HouseNumber`      | string  | House/building number           | Max 10 characters                           |
| `PostCode`         | string  | Postal code                     | Max 20 characters                           |
| `City`             | string  | City name                       | Max 255 characters                          |
| `Country`          | string  | Country name                    | Max 255 characters                          |
| `AttachPdfInvoice` | boolean | Include PDF with invoice emails | Default: false                              |
| `Language`         | string  | Communication language          | "Danish", "English", "Faroese", "Norwegian" |

## API Endpoints

### Get All Customers

Retrieve all customers in your account.

```http
GET https://api.farpay.io/v2/customers
```

**Response Example:**

```json
[
  {
    "CustomerNumber": "12345",
    "Name": "John Smith",
    "Email": "john@example.com",
    "Street": "Main Street 123",
    "City": "Copenhagen",
    "PostCode": "1000",
    "Country": "Denmark",
    "AttachPdfInvoice": false,
    "Language": "English"
  }
]
```

### Get Single Customer

Retrieve detailed information for a specific customer.

```http
GET https://api.farpay.io/v2/customers/{customerNumber}
```

**Parameters:**

* `customerNumber` (path) - The customer's unique identifier

**Response Example:**

```json
{
  "CustomerNumber": "12345",
  "Name": "John Smith",
  "Email": "john@example.com",
  "Street": "Main Street 123",
  "City": "Copenhagen",
  "PostCode": "1000",
  "Country": "Denmark",
  "AttachPdfInvoice": false,
  "Language": "English",
  "Agreements": [
    {
      "Id": 1,
      "Type": "Card",
      "Status": "Active",
      "Details": "Visa|4444xxxxxxxx1234|12/25"
    }
  ]
}
```

### Create Customer

Create a new customer in your account.

```http
POST https://api.farpay.io/v2/customers
```

**Request Body:**

```json
{
  "CustomerNumber": "12345",
  "Name": "John Smith",
  "Email": "john@example.com",
  "Street": "Main Street 123",
  "City": "Copenhagen",
  "PostCode": "1000",
  "Country": "Denmark",
  "AttachPdfInvoice": false,
  "Language": "English"
}
```

**Response:** Returns the created customer object with HTTP 201 status.

### Update Customer

Update an existing customer's information.

```http
PUT https://api.farpay.io/v2/customers/{customerNumber}
```

**Updatable Properties:**

* `Name`
* `Email`
* All address properties (`Street`, `City`, `PostCode`, etc.)
* `AttachPdfInvoice`
* `Language`

**Request Body:**

```json
{
  "CustomerNumber": "12345",
  "Name": "John Smith Updated",
  "Email": "john.updated@example.com",
  "Street": "New Street 456",
  "City": "Aarhus",
  "PostCode": "8000",
  "Country": "Denmark",
  "AttachPdfInvoice": true,
  "Language": "Danish"
}
```

### Delete Customer (Beta)

Delete a customer and all associated data.

```http
DELETE https://api.farpay.io/v2/customers/{customerNumber}
```

**Response Codes:**

* `200` - Customer successfully deleted
* `400` - CustomerNumber missing from URI
* `404` - Customer not found

## Payment Agreement Requests

### Send Agreement Invitation Email

Send an email to a customer inviting them to create a payment agreement.

```http
GET https://api.farpay.io/v2/customers/{customerNumber}/agreementRequest
```

**Query Parameters:**

* `type` (required) - Payment type to offer
* `email` (required) - Email address to send invitation to

**Payment Types:**

| Type   | Description                                           |
| ------ | ----------------------------------------------------- |
| `mp`   | MobilePay Subscriptions                               |
| `card` | Visa, MasterCard, or Dankort                          |
| `bs`   | Betalingsservice (direct debit for private customers) |
| `ls`   | Leverandørservice (direct debit for businesses)       |
| `all`  | All available payment types                           |

**Example Request:**

```http
GET https://api.farpay.io/v2/customers/12345/agreementRequest?type=card&email=customer@example.com
```

## Language Settings

The `Language` property controls communication language:

* **Default behavior**: If your company communicates in one language, customers reading the same language don't need this property set
* **Use cases**: Set for customers who prefer different languages than your default
* **Available options**: "Danish", "English", "Faroese", "Norwegian"

## PDF Invoice Attachments

The `AttachPdfInvoice` setting controls whether customers receive PDF invoices via email:

* **`true`**: Customer receives PDF attachments with invoice emails
* **`false`**: Customer receives invoice emails without PDF attachments

**Note:** When PDF attachments are enabled, monitoring customer behavior (email opens, downloads) may be less accurate.

## Best Practices

1. **Customer Numbers**: Use meaningful, unique identifiers that work with your existing systems
2. **Email Validation**: Ensure email addresses are valid and active
3. **Address Information**: Provide complete address details for better payment processing
4. **Language Preferences**: Set appropriate language for international customers
5. **PDF Attachments**: Consider customer preferences and monitoring needs when setting this option

## Error Handling

Common customer-related errors:

| Error                           | Description                 | Solution                     |
| ------------------------------- | --------------------------- | ---------------------------- |
| `CustomerNumber already exists` | Duplicate customer number   | Use a unique customer number |
| `Invalid email format`          | Email address is malformed  | Check email format           |
| `Customer not found`            | Customer doesn't exist      | Verify customer number       |
| `Required field missing`        | Missing required properties | Include all required fields  |

## Related Resources

* [Orders](orders#) - Create payment flows for customers
* [Agreements](agreements#) - Manage payment instruments
* [Invoices](invoices#) - Generate invoices for customers

<br />