# Party

## Overview

Party Groups represent organizations or individuals that your company does business with. They capture customer, supplier, carrier, and tax authority information in a flexible structure that allows a single entity to play multiple roles. This eliminates data duplication when the same company is both a customer and a supplier.

Customers are parties who buy from you. Their records include contact information, shipping and billing addresses, pricing level assignments, payment terms, and credit limits. When sales orders and invoices are created, they reference the customer party, linking all sales activity back to the customer record. This provides a complete view of the customer relationship including order history, payment status, and total revenue.

Suppliers are parties who sell to you. Their records capture similar contact details plus supplier-specific information like default lead times and ordering preferences. Purchase orders and bills reference the supplier party, letting you track your purchasing relationship including open orders, payment obligations, and purchase history. This supports supplier management and accounts payable operations.

Carriers are parties who transport shipments. When you ship products, you specify which carrier is handling the shipment. Carrier records can include license information, hazmat contact details, and service preferences. This supports shipping operations and carrier performance analysis.

The multi-role capability is powerful. A company might be a customer for your finished products and also a supplier of raw materials. Rather than maintaining separate records and losing sight of the full relationship, one party record can have both customer and supplier roles. This provides a complete view of your interaction with that business partner.

Contact information is richly structured. A party can have multiple email addresses (billing, work, payment), multiple phone numbers (direct, mobile, fax), and multiple addresses (billing, shipping, payment). This supports complex organizational structures and ensures communications reach the right people. Addresses are stored as separate but related records, allowing historical tracking and multiple active addresses.

The primary party group is special - it represents your own company. This appears on invoices as the seller, on bills as the buyer, and in reports as the entity name. There's exactly one primary party group, and its information is used throughout the system to represent your business in transactions and documents.

### GraphQL API

The `party` collection provides access to party data via the GraphQL API. All queries use the Relay connection specification with cursor-based pagination.

**Query Name:**`partyViewConnection`

**Available Features:**

- Cursor-based pagination (first/last/after/before)
- 9 filter options
- 5 sortable fields
- 4 relations to other collections

## Query Examples

### Basic Query

The `party` collection is accessed via the `partyViewConnection` query, which returns a Relay-style connection with pagination support.

```graphql
query {
  partyViewConnection(first: 10) {
    edges {
      node {
        contactName
        defaultSource
        defaultTerms
        emailAddressBilling
        emailAddresses
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

### Pagination

Use cursor-based pagination to retrieve large datasets:

```graphql
# First page
query {
  partyViewConnection(first: 50) {
    edges {
      node { partyId }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

# Subsequent pages
query {
  partyViewConnection(first: 50, after: "cursor-from-previous-page") {
    edges {
      node { partyId }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

### Filtering

Apply filters to narrow results:

```graphql
query {
  partyViewConnection(
    first: 10
    connectionRelationErrorDates: { begin: "2024-01-01", end: "2024-12-31" }
  ) {
    edges {
      node { partyId }
    }
  }
}
```

### Sorting

Sort results by one or more fields:

```graphql
query {
  partyViewConnection(
    first: 10
    sort: [{ field: "contactName", mode: "desc" }]
  ) {
    edges {
      node {
        partyId
        contactName
      }
    }
  }
}
```

### Relations

Query related data:

```graphql
query {
  partyViewConnection(first: 10) {
    edges {
      node {
        partyId
        addressBilling {
          name
          formatted
        }
      }
    }
  }
}
```

## Summary and Aggregation

This collection supports metrics aggregation through the `summary` field. You can calculate totals, averages, counts, and other aggregate values across filtered data.

### Query Structure

```graphql
partyViewConnection(filters...) {
  summary {
    errorCode
    errorMessage
    metrics {
      # Calculated metrics
    }
  }
}
```

### Available Metrics

This collection provides 1 metric that can be aggregated:

| Metric | Parameters | Description |
| --- | --- | --- |
| `count` | None | Count of items in the result set |

**Common Parameters:**

- `operator` - Aggregation function: `sum`, `mean`, `min`, `max`
- `transform` - Mathematical transformation: `abs`
- `dateRange` - Filter to specific date range
- `facilityUrlList` - Filter to specific facilities

### Examples

#### Example 1: Total party Metrics

Calculate aggregate metrics across all party records:

```graphql
query {
  partyViewConnection(first: 1) {
    summary {
      errorCode
      errorMessage
      metrics {
        totalCount: count
      }
    }
  }
}
```

Expected result structure:

```json
{
  "data": {
    "partyViewConnection": {
      "summary": {
        "errorCode": null,
        "errorMessage": null,
        "metrics": {
          "totalCount": [1523]
        }
      }
    }
  }
}
```

## Fields

This collection has 37 fields:

- 34 simple fields
- 2 enum fields (with predefined values)
- 1 parameterized fields (accept query options)

### Simple Fields

These fields return values directly without additional options.

#### `contactName`

The primary contact name for the party. This is used for display purposes in party listings and represents the main point of contact or organization name.

**Label:** Contact name

**Sortable:** Yes

#### `defaultSource`

The default source party reference for purchasing relationships. This identifies the preferred supplier or source when this party is used in procurement transactions.

**Label:** Default source

**Sortable:** No

#### `defaultTerms`

The default payment terms applied to transactions with this party. This defines the standard billing and payment conditions, such as net 30 or due on receipt, used when creating orders or invoices.

**Label:** Default terms

**Sortable:** No

#### `emailAddressBilling`

The email address designated for billing-related communications. This is where invoices, payment reminders, and other accounting correspondence should be sent for this party.

**Label:** Email address billing

**Sortable:** No

#### `emailAddresses`

A list of all email addresses associated with the party. This aggregates multiple contact methods from the party's contact mechanisms, providing a comprehensive view of available email channels for communication.

**Label:** Email addresses

**Sortable:** No

#### `hazmatContactPhoneNumber`

**Label:** Hazmat contact phone number

**Sortable:** No

#### `leadTime`

**Label:** Default lead days

**Sortable:** Yes

#### `partyId`

**Label:** Party ID

**Sortable:** No

### Enum Fields

#### `role`

**Label:** Role

**Sortable:** No

**Possible Values:**

- `CUSTOMER` - Customer
- `SUPPLIER` - Supplier
- `CARRIER` - Carrier
- `TAX_AUTHORITY` - Tax authority

#### `status`

**Label:** Status

**Sortable:** No

**Possible Values:**

- `PARTY_ENABLED` - Active
- `PARTY_DISABLED` - Inactive

### Parameterized Fields

These fields accept parameters to customize the returned data. Parameters allow filtering by location, date ranges, aggregation methods, and more.

#### `portalScreenView`

**Label:** Portal screen view

**Sortable:** No
**Parameters:**
- **screenViewPurpose** (`String`)

### Relations

#### addressBilling

- **Related Collection:** [address](https://developer.finaleinventory.com/reference/graphql-address)
- **Label:** Billing address

#### addressPayment

- **Related Collection:** [address](https://developer.finaleinventory.com/reference/graphql-address)
- **Label:** Payment address

#### addressShipping

- **Related Collection:** [address](https://developer.finaleinventory.com/reference/graphql-address)
- **Label:** Shipping address

## Filters

### connectionRelationErrorDates

- **Label:** Latest error date
- **Type:** dateRangeInput
- **Enabled:** Yes
- **Filter Type:** Date range

**Input Structure:**

```typescript
{
  begin: string  // ISO date format: "2024-01-01"
  end: string    // ISO date format: "2024-12-31"
}
```

### recordCreated

- **Label:** Created date
- **Type:** dateRangeInput
- **Enabled:** Yes
- **Filter Type:** Date range

**Input Structure:**

```typescript
{
  begin: string  // ISO date format: "2024-01-01"
  end: string    // ISO date format: "2024-12-31"
}
```

### status

- **Label:** Status
- **Type:** List|String
- **Enabled:** Yes
- **Options:**
  - Active (PARTY_ENABLED)
  - Inactive (PARTY_DISABLED)