Party

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:

Query Examples

Basic Query

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

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

Pagination

Use cursor-based pagination to retrieve large datasets:

# 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:

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

Sorting

Sort results by one or more fields:

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

Relations

Query related data:

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

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:

Examples

Example 1: Total party Metrics

Calculate aggregate metrics across all party records:

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

Expected result structure:

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

Fields

This collection has 37 fields:

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:

status

Label: Status

Sortable: No

Possible Values:

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:

Relations

addressBilling

addressPayment

addressShipping

Filters

connectionRelationErrorDates

Input Structure:

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

recordCreated

Input Structure:

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

status