Introduction to Finale GraphQL API

Overview

The Finale GraphQL API provides a flexible, powerful way to query and interact with your inventory data. Unlike traditional REST APIs that require multiple requests to fetch related data, GraphQL allows you to request exactly the data you need in a single query.

Key Features

Consistent API Structure

All collections follow the same patterns:

ViewConnection naming: Every collection uses the {name}ViewConnection pattern
Relay pagination: Standard cursor-based pagination across all queries
Filtering and sorting: Consistent argument patterns for data manipulation
Relations: Nested queries for related data in a single request

What You Can Do

Query inventory data: Products, orders, locations, and more
Navigate relationships: Fetch related data in a single request
Filter results: Apply collection-specific filters to narrow results
Sort data: Order results by one or more fields
Paginate efficiently: Use cursor-based pagination for large datasets
Aggregate data: Get summary metrics and grouped statistics
Format output: Control how field values are formatted (HTML, raw, abbreviated, etc.)

GraphQL vs REST

GraphQL Advantages:

Fetch exactly what you need (no over-fetching or under-fetching)
Get related data in one request (no N+1 queries)
Strongly typed schema with built-in documentation
Evolution without versioning

When to Use GraphQL:

Building custom integrations or applications
Need to fetch related data efficiently
Want flexible queries without backend changes
Working with large datasets requiring pagination

When to Use REST:

Simple CRUD operations
Existing integrations already using REST
File uploads/downloads
Webhook handlers

Core Concepts

ViewConnections

Every collection is accessed via a ViewConnection:

query {
  productViewConnection(first: 10) {
    edges {
      node {
        productId
        sku
      }
    }
  }
}

See ViewConnections for details.

Pagination

All queries use cursor-based pagination:

query {
  orderViewConnection(first: 50) {
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

See Pagination for details.

Filtering

Apply filters to narrow results:

query {
  orderViewConnection(
    first: 10
    type: ["SALES_ORDER"]
    status: ["OPEN"]
  ) {
    edges {
      node {
        orderId
      }
    }
  }
}

See Filtering for details.

Sorting

Sort results by one or more fields:

query {
  orderViewConnection(
    first: 10
    sort: [{ field: "orderDate", mode: "desc" }]
  ) {
    edges {
      node {
        orderId
        orderDate
      }
    }
  }
}

See Sorting for details.

Formatting

Control how field values are returned:

query {
  productViewConnection(first: 10) {
    edges {
      node {
        productId(formatter: "html")  # HTML with links
        sku(formatter: "none")        # Raw value
      }
    }
  }
}

See Formatting for details.

Next Steps

Set up authentication to access the API
Run your first query to fetch data
Explore available collections in the sidebar navigation
Learn about core concepts in detail