# Mutations / Customers

# Customers

**Mutation**
## allocateCustomerPayment — Returns [CustomerPayment](/documentation/Objects/Customers#CustomerPayment)

**Scopes required:** make_customer_payments

Allocate an existing customer payment to outstanding invoices

| Arguments | Type | Description |
| --- | --- | --- |
| id | [ID!](/documentation/Types/UUID#UUID) | The ID of the customer payment to allocate |
| invoices | [[CustomerPaymentInput]](/documentation/Inputs/Customer-Payment-Input#CustomerPaymentInput) | The invoices and amounts to allocate the customer payment to |

**Example Mutation**

```graphql
mutation AllocateCustomerPayment($id: ID!) {
    allocateCustomerPayment(id: $id) {
        id,
        reference,
        status,
        startBalance,
        amount
    }
}

# Example variables
{
    "id": "<ID>"
}
```

**Mutation**
## bulkDeleteCustomers — Returns *boolean*

**Scopes required:** delete_products

Bulk delete customers, this will not delete any sales and the customers can be recovered from the trash

| Arguments | Type | Description |
| --- | --- | --- |
| ids | [[ID!]!](/documentation/Types/UUID#UUID) | The list of customer IDs to delete |

**Example Mutation**

```graphql
mutation BulkDeleteCustomers($ids: [ID!]!) {
    bulkDeleteCustomers(ids: $ids)
}

# Example variables
{
    "ids": [
        "<IDS>"
    ]
}
```

**Mutation**
## createCustomer — Returns [Customer](/documentation/Objects/Customers#Customer)

**Scopes required:** create_customers

Create a new customer

| Arguments | Type | Description |
| --- | --- | --- |
| clientId | *String* | Your ID of the customer, you can use this field to store your own reference, this is not displayed anywhere |
| billing | [ContactInput](/documentation/Inputs/Contact-Input#ContactInput) | The billing details of the customer |
| delivery | [ContactInput](/documentation/Inputs/Contact-Input#ContactInput) | The delivery details of the customer |
| firstName | *String* | The customer's first name |
| lastName | *String* | The customer's last name |
| code | *String* | A code that can be used to lookup the customer in the register |
| company | *String* | The company this customer works for |
| businessNumber | *String* | This customer's company's business number |
| birthday | [Date](/documentation/Types/Date#Date) | The customer's birthday |
| gender | *String* | The customer's gender, currently limited to six characters |
| emails | [[Email]](/documentation/Types/Email#Email) | The customer's email addresses |
| fax | *String* | The facsimile machine number for the customer |
| phone | *String* | The customer's main phone number |
| mobile | *String* | The customer's mobile number |
| allowMarketingEmails | *Boolean* | Whether this customer has opted to receive marketing emails |
| website | *String* | The website for the customer |
| twitter | *String* | The customer's twitter handle |
| facebook | *String* | The customer's facebook page |
| invoiceMessage | *String* | A message to appear on all invoices (this could be printed on receipts) |
| comments | *String* | Any comments about the customer (this is internal) |
| customerGroup | [ID](/documentation/Types/UUID#UUID) | The group this customer belongs to |
| overrideCustomerGroup | *Boolean* | Whether to override the settings the customer's group has set |
| loyaltyEnabled | *Boolean* | Whether loyalty is enabled for this customer (if overrideCustomerGroup is on) |
| loyaltyPoints | *Float* | The starting loyalty points for the customer, we highly recommend that you let Shopfront handle this |
| disablePromotions | *Boolean* | Whether this customer should not be able to receive promotions (if overrideCustomerGroup is on) |
| priceList | [ID](/documentation/Types/UUID#UUID) | The custom price list this customer can use (if overrideCustomerGroup is on) |
| requireOrderReference | *Boolean* | Whether the customer requires a reference number to complete a sale |
| accountLimit | *Float* | The account limit for the customer (if overrideCustomerGroup is on) |
| currentOwing | *Float* | The initial amount the customer owes, we highly recommend that you let Shopfront handle this |

**Example Mutation**

```graphql
mutation CreateCustomer($clientId: String) {
    createCustomer(clientId: $clientId) {
        id,
        name,
        parent,
        deleted,
        clientId
    }
}

# Example variables
{
    "clientId": "<CLIENT_ID>"
}
```

**Mutation**
## createCustomerPayment — Returns [CustomerPayment](/documentation/Objects/Customers#CustomerPayment)

**Scopes required:** make_customer_payments

Create a customer payment

| Arguments | Type | Description |
| --- | --- | --- |
| customer | [ID!](/documentation/Types/UUID#UUID) | The ID of the customer that is making the payment |
| paymentMethod | [ID!](/documentation/Types/UUID#UUID) | The ID of the payment method they are using |
| paymentMethodSubtype | *String* | The "subtype" of the payment method (e.g. VISA / MASTERCARD for EFTPOS) |
| user | [ID!](/documentation/Types/UUID#UUID) | The user who has received the payment (defaults to the current user) |
| register | [ID!](/documentation/Types/UUID#UUID) | The register the payment was completed on |
| reference | *String* | The payment's reference number |
| amount | *Float!* | The amount that the customer paid |
| timestamp | [DateTime!](/documentation/Types/Date-Time#DateTime) | The time the customer made the payment |
| relatesTo | [ID](/documentation/Types/UUID#UUID) | Another customer payment that this relates to, typically used to show when a payment is refunded |
| invoices | [[CustomerPaymentInput]](/documentation/Inputs/Customer-Payment-Input#CustomerPaymentInput) | The invoices the customer paid off |

**Example Mutation**

```graphql
mutation CreateCustomerPayment($customer: ID!, $paymentMethod: ID!, $user: ID!, $register: ID!, $amount: Float!, $timestamp: DateTime!) {
    createCustomerPayment(customer: $customer, paymentMethod: $paymentMethod, user: $user, register: $register, amount: $amount, timestamp: $timestamp) {
        id,
        reference,
        status,
        startBalance,
        amount
    }
}

# Example variables
{
    "customer": "<CUSTOMER>",
    "paymentMethod": "<PAYMENT_METHOD>",
    "user": "<USER>",
    "register": "<REGISTER>",
    "amount": "<AMOUNT>",
    "timestamp": "<TIMESTAMP>"
}
```

**Mutation**
## deleteCustomer — Returns [Customer](/documentation/Objects/Customers#Customer)

**Scopes required:** delete_customers

Delete a customer, this will not delete any sales and the customer can be recovered from the trash

| Arguments | Type | Description |
| --- | --- | --- |
| id | *String!* | The ID of the customer to delete |

**Example Mutation**

```graphql
mutation DeleteCustomer($id: String!) {
    deleteCustomer(id: $id) {
        id,
        name,
        parent,
        deleted,
        clientId
    }
}

# Example variables
{
    "id": "<ID>"
}
```

**Mutation**
## mergeCustomers — Returns [Customer](/documentation/Objects/Customers#Customer)

**Scopes required:** create_customers, delete_customers

Merge customers into a new customer

| Arguments | Type | Description |
| --- | --- | --- |
| clientId | *String* | Your ID of the customer, you can use this field to store your own reference, this is not displayed anywhere |
| billing | [ContactInput](/documentation/Inputs/Contact-Input#ContactInput) | The billing details of the customer |
| delivery | [ContactInput](/documentation/Inputs/Contact-Input#ContactInput) | The delivery details of the customer |
| firstName | *String* | The customer's first name |
| lastName | *String* | The customer's last name |
| code | *String* | A code that can be used to lookup the customer in the register |
| company | *String* | The company this customer works for |
| businessNumber | *String* | This customer's company's business number |
| birthday | [Date](/documentation/Types/Date#Date) | The customer's birthday |
| gender | *String* | The customer's gender, currently limited to six characters |
| emails | [[Email]](/documentation/Types/Email#Email) | The customer's email addresses |
| fax | *String* | The facsimile machine number for the customer |
| phone | *String* | The customer's main phone number |
| mobile | *String* | The customer's mobile number |
| allowMarketingEmails | *Boolean* | Whether this customer has opted to receive marketing emails |
| website | *String* | The website for the customer |
| twitter | *String* | The customer's twitter handle |
| facebook | *String* | The customer's facebook page |
| invoiceMessage | *String* | A message to appear on all invoices (this could be printed on receipts) |
| comments | *String* | Any comments about the customer (this is internal) |
| customerGroup | [ID](/documentation/Types/UUID#UUID) | The group this customer belongs to |
| overrideCustomerGroup | *Boolean* | Whether to override the settings the customer's group has set |
| loyaltyEnabled | *Boolean* | Whether loyalty is enabled for this customer (if overrideCustomerGroup is on) |
| loyaltyRate | *Float* | The custom rate multiplier for the customer (if overrideCustomerGroup is on) - this is currently not in use |
| disablePromotions | *Boolean* | Whether this customer should not be able to receive promotions (if overrideCustomerGroup is on) |
| priceList | [ID](/documentation/Types/UUID#UUID) | The custom price list this customer can use (if overrideCustomerGroup is on) |
| accountLimit | *Float* | The account limit for the customer (if overrideCustomerGroup is on) |
| merge | [[ID]](/documentation/Types/UUID#UUID) | The list of customer IDs to merge into the new customer |

**Example Mutation**

```graphql
mutation MergeCustomers($clientId: String) {
    mergeCustomers(clientId: $clientId) {
        id,
        name,
        parent,
        deleted,
        clientId
    }
}

# Example variables
{
    "clientId": "<CLIENT_ID>"
}
```

**Mutation**
## updateCustomer — Returns [Customer](/documentation/Objects/Customers#Customer)

**Scopes required:** edit_customers

| Arguments | Type | Description |
| --- | --- | --- |
| id | *String!* | The ID of the customer, this can either be the customer's ID or their client ID |
| billing | [ContactInput](/documentation/Inputs/Contact-Input#ContactInput) | The billing details of the customer |
| delivery | [ContactInput](/documentation/Inputs/Contact-Input#ContactInput) | The delivery details of the customer |
| firstName | *String* | The customer's first name |
| lastName | *String* | The customer's last name |
| code | *String* | A code that can be used to lookup the customer in the register |
| company | *String* | The company this customer works for |
| businessNumber | *String* | This customer's company's business number |
| birthday | [Date](/documentation/Types/Date#Date) | The customer's birthday |
| gender | *String* | The customer's gender, currently limited to six characters |
| emails | [[Email]](/documentation/Types/Email#Email) | The customer's email addresses |
| fax | *String* | The facsimile machine number for the customer |
| phone | *String* | The customer's main phone number |
| mobile | *String* | The customer's mobile number |
| allowMarketingEmails | *Boolean* | Whether this customer has opted to receive marketing emails |
| website | *String* | The website for the customer |
| twitter | *String* | The customer's twitter handle |
| facebook | *String* | The customer's facebook page |
| invoiceMessage | *String* | A message to appear on all invoices (this could be printed on receipts) |
| comments | *String* | Any comments about the customer (this is internal) |
| customerGroup | [ID](/documentation/Types/UUID#UUID) | The group this customer belongs to |
| overrideCustomerGroup | *Boolean* | Whether to override the settings the customer's group has set |
| loyaltyEnabled | *Boolean* | Whether loyalty is enabled for this customer (if overrideCustomerGroup is on) |
| loyaltyPoints | *Float* | The starting loyalty points for the customer, we highly recommend that you let Shopfront handle this |
| disablePromotions | *Boolean* | Whether this customer should not be able to receive promotions (if overrideCustomerGroup is on) |
| priceList | [ID](/documentation/Types/UUID#UUID) | The custom price list this customer can use (if overrideCustomerGroup is on) |
| requireOrderReference | *Boolean* | Whether the customer requires a reference number to complete a sale |
| accountLimit | *Float* | The account limit for the customer (if overrideCustomerGroup is on) |
| currentOwing | *Float* | The initial amount the customer owes, we highly recommend that you let Shopfront handle this |

**Example Mutation**

```graphql
mutation UpdateCustomer($id: String!) {
    updateCustomer(id: $id) {
        id,
        name,
        parent,
        deleted,
        clientId
    }
}

# Example variables
{
    "id": "<ID>"
}
```

**Mutation**
## voidCustomerPayment — Returns [CustomerPayment](/documentation/Objects/Customers#CustomerPayment)

**Scopes required:** make_customer_payments

This will void the customer payment, marking it as cancelled and reversing the payments it applied to invoices

| Arguments | Type | Description |
| --- | --- | --- |
| id | [ID!](/documentation/Types/UUID#UUID) | The ID for the customer payment |

**Example Mutation**

```graphql
mutation VoidCustomerPayment($id: ID!) {
    voidCustomerPayment(id: $id) {
        id,
        reference,
        status,
        startBalance,
        amount
    }
}

# Example variables
{
    "id": "<ID>"
}
```