# LinkShipToCustomersToBillCustomer

Link two customer records together

`POST /api/v2/companies/{companyId}/customers/billto/{code}/shipto/link`

**API:** AvaTax API
**Tag:** Customers
**API Version:** v2
**Base URL:** https://sandbox-rest.avatax.com/
**Content-Type:** `application/json`
**Accepts:** `application/json`
**Authentication:** API Key (`Authorization` in header) or OAuth 2.0 or Basic (username + license key)

Source: https://developer.avalara.com/products/crossborder/api/methods/Customers/LinkShipToCustomersToBillCustomer/

## Description

Links a Ship-To customer record with a Bill-To customer record.
            
Customer records represent businesses or individuals who can provide exemption certificates.  Some customers
may have certificates that are linked to their shipping address or their billing address.  To group these
customer records together, you may link multiple bill-to and ship-to addresses together to represent a single
entity that has multiple different addresses of different kinds.
            
In general, a customer will have only one primary billing address and multiple ship-to addresses, representing
all of the different locations where they receive goods.  To facilitate this type of customer, you can send in
one bill-to customer code and multiple ship-to customer codes in a single API call.
            
Note that you can only link a ship-to customer record to a bill-to customer record.  You may not link two customers
of the same kind together.

### Security Policies

* This API requires one of the following user roles: AccountAdmin, AccountOperator, AccountUser, AvaTaxOnlyAccountAdmin, AvaTaxOnlyAccountUser, AvaTaxOnlyCompanyAdmin, AvaTaxOnlyCompanyUser, BatchServiceAdmin, CompanyAdmin, CompanyUser, CSPTester, SSTAdmin, TechnicalSupportAdmin, TechnicalSupportUser.
* This API depends on the following active services:*Required* (all):  AvaTaxPro, ECMEssentials, ECMPro, ECMPremium, VEMPro, VEMPremium, ECMProComms, ECMPremiumComms.

## Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `companyId` | integer | path | Yes | The unique ID number of the company defining customers. |
| `code` | string | path | Yes | The code of the bill-to customer to link. |
| `X-Avalara-Client` | string | header | No | Identifies the software you are using to call this API.  For more information on the client header, see [Client Headers](https://developer.avalara.com/avatax/client-headers/) . |

## Request Body

**Schema:** `LinkCustomersModel`

Represents a customer to whom you sell products and/or services.

| Property | Type | Required | Description |
|---|---|---|---|
| `customers` | string[] | No | An array of customerCodes that are exempted by this certificate |

## Responses

| Status | Description | Schema |
|---|---|---|
| 200 | Success | `CustomerModel` |
| 400 | Bad Request | `ProblemDetails` |
| 401 | Unauthorized | `ProblemDetails` |
| 404 | Not Found | `ProblemDetails` |

### 200 Response: `CustomerModel`

Represents a customer to whom you sell products and/or services.

| Property | Type | Required | Description |
|---|---|---|---|
| `id` | integer | No | The unique ID number of this customer. |
| `companyId` | integer | **Yes** | The unique ID number of the AvaTax company that recorded this customer. Example: `0`. |
| `customerCode` | string | **Yes** | The unique code identifying this customer.  Must be unique within your company.
            
This code should be used in the `customerCode` field of any call that creates or adjusts a transaction
in order to ensure that all exemptions that apply to this customer are correctly considered.
            
Note: This field is case sensitive. Example: `d2425ec5-0e8c-4d1c-bed1-4614e039e282`. |
| `alternateId` | string | No | A customer-configurable alternate ID number for this customer.  You may set this value to match any
other system that would like to reference this customer record. Example: `987654321`. |
| `name` | string | **Yes** | A friendly name identifying this customer. Example: `Dr. Bob Example`. |
| `attnName` | string | No | Indicates the "Attn:" component of the address for this customer, if this customer requires mailings to be shipped
to the attention of a specific person or department name. Example: `Attn: Receiving`. |
| `line1` | string | **Yes** | First line of the street address of this customer. Example: `645 Main Street`. |
| `line2` | string | No | Second line of the street address of this customer. |
| `city` | string | **Yes** | City component of the street address of this customer. Example: `Irvine`. |
| `postalCode` | string | **Yes** | Postal Code / Zip Code component of the address of this customer. Example: `92614`. |
| `phoneNumber` | string | No | The main phone number for this customer. Example: `(949) 555-1212`. |
| `faxNumber` | string | No | The fax phone number for this customer, if any. Example: `949.555.1213`. |
| `emailAddress` | string | No | The main email address for this customer. Example: `dr.bob.example@example.org`. |
| `contactName` | string | No | The name of the main contact person for this customer. Example: `Alice Smith`. |
| `lastTransaction` | string | No | Date when this customer last executed a transaction. Example: `2008-10-08T00:00:00Z`. |
| `createdDate` | string | No | The date when this record was created. |
| `modifiedDate` | string | No | The date/time when this record was last modified. |
| `country` | string | **Yes** | Name or ISO 3166 code identifying the country.
            
This field supports many different country identifiers:
 * Two character ISO 3166 codes
 * Three character ISO 3166 codes
 * Fully spelled out names of the country in ISO supported languages
 * Common alternative spellings for many countries
            
For a full list of all supported codes and names, please see the Definitions API `ListCountries`. Example: `US`. |
| `region` | string | No | ISO 3166 code identifying the region within the country.
Two and three character ISO 3166 region codes.
This is a required field if the country is US or CA. For other countries, this is an optional field.
For a full list of all supported codes, please see the Definitions API `ListRegions`. Example: `CA`. |
| `isBill` | boolean | No | True if this customer record is specifically used for bill-to purposes. |
| `isShip` | boolean | No | True if this customer record is specifically used for ship-to purposes. |
| `taxpayerIdNumber` | string | No | For customers in the United States, this field is the federal taxpayer ID number.  For businesses, this is
a Federal Employer Identification Number.  For individuals, this will be a Social Security Number. |
| `certificates` | CertificateModel[] | No | A list of exemption certficates that apply to this customer.  You can fetch this data by specifying
`$include=certificates` when calling a customer fetch API. |
| `customFields` | CustomFieldModel[] | No | A list of custom fields defined on this customer.
            
For more information about custom fields, see the [Avalara Help Center article about custom fields](https://help.avalara.com/0021_Avalara_CertCapture/All_About_CertCapture/Edit_or_Remove_Details_about_Customers). |
| `exposureZones` | ExposureZoneModel[] | No | A list of exposure zones where you do business with this customer.
            
To keep track of certificates that are needed for each customer, set this value to a list of all exposure zones where you
sell products to this customer.  You can find a list of exposure zones by calling `ListExposureZones`.
            
This field is often called "Ship-To States" or "Ship-To Zones", since it generally refers to locations where you ship products
when this customer makes a purchase.
            
This field is useful for audit purposes since it helps you ensure you have the necessary certificates for each customer. |
| `billTos` | CustomerModel[] | No | A list of bill-to customer records that are connected to this ship-to customer.
            
Customer records represent businesses or individuals who can provide exemption certificates.  Some customers
may have certificates that are linked to their shipping address or their billing address.  To group these
customer records together, you may link multiple bill-to and ship-to addresses together to represent a single
entity that has multiple different addresses of different kinds. |
| `shipTos` | CustomerModel[] | No | A list of ship-to customer records that are connected to this bill-to customer.
            
Customer records represent businesses or individuals who can provide exemption certificates.  Some customers
may have certificates that are linked to their shipping address or their billing address.  To group these
customer records together, you may link multiple bill-to and ship-to addresses together to represent a single
entity that has multiple different addresses of different kinds. |
| `attributes` | CustomerAttributeModel[] | No | A list of attributes that apply to this customer.
            
You can fetch this data by specifying `$include=attributes` when calling a customer fetch API. |
| `activeCertificates` | ActiveCertificateModel[] | No | A list of active certificates with exemption reasons. |
| `histories` | HistoryModel[] | No | A list of field update histories for this customer. |
| `logs` | CertificateLogModel[] | No | A list of logs for this customer. |
| `shipToStates` | StateModel[] | No | A list of states where this customer ships to. |

## Example Request

```bash
curl -X POST "https://sandbox-rest.avatax.com/api/v2/companies/{companyId}/customers/billto/{code}/shipto/link" \
  -H "Authorization: Basic <credentials>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
  "customers": [
    "123456789"
  ]
}'
```