Query

Every GraphQL schema has a root type for both queries and mutations. The query-type defines GraphQL operations that retrieve data from the server. Here are some examples of queries to get you started.

Example query: Customer

A basic GraphQL request will pass arguments to the query, and define a set of fields in the body of the query that should be returned. Unlike a RESTful API, the response from the server will include only those fields that the request explicitly asks for.

query {
  contact(id: 12345) {
  id
  fullName
  email
  }
}

The customer query above is simple and performant, allowing an API user to specify exactly what they need and retrieve it, without waste.

Example query: Orders

GraphQL queries can be tailored to be more specific, allowing the trade-off of additional up-front writing complexity in exchange for greatly increased granularity. An excellent example of this in the Printavo environment is the Orders type. Many Printavo users will have a large collection of Quotes and Invoices in their system, across a broad timeline. Filtering across those and other fields allows us to make a more complex, but vastly more powerful query. Here is an example of one such query.

query {
  orders(
  inProductionAfter: "2023-04-01T00:00:00Z"
  inProductionBefore: "2023-05-01T00:00:00Z"
  statusIds: ["4", "5"]
  first: 10
  sortOn: VISUAL_ID
  ) {
  nodes {
    ... on Quote {
      id
      visualId
      contact {
        id
        email
      }
    }
    ... on Invoice {
      id
      visualId
      owner {
        id
        email
      }
    }
  }
  }
}

Unions and Fragments

First, you'll note the query is named orders. This is because Quotes and Invoices are both joined together into the OrderUnion type. This union type allows API users to query for a combined set of both Quotes and Invoices. Each node in the response can behave differently based on whether its a Quote or an Invoice, which is where the fragments come into play. The fields defined in the fragment blocks ... on Quote { ... } and ... on Invoice { ... } instruct the server about what fields to return for each respective node, depending on which type it actually belongs to, without the API user needing to specify for each one. If a returned node is a Quote, then the ID and email of the Quote's contact will be returned. Otherwise, if a returned node is an Invoice, then the ID and email of the Invoice's owner will be returned.

Searching

The arguments included in this query are inProductionAfter, inProductionBefore, statusIds, and sortOn, though the query supports additional arguments as defined below. In the example above, our query explicitly asks for quotes and invoices that were produced between April 1st and May 1st of 2023. Further, our query is only interested in quotes and invoices that are in the Completed - Ready for Package and Order Ready for Pickup statuses, corresponding to statusIDs 4 and 5 respectively.

Enums and Slicing

GraphQL supports slicing, which allows an API user to define specifically which results of a sorted dataset the server's response should include. In the example above, the sortOn field acts as an Enum, and informs the server that it should sort the quotes and invoices in the dataset by their visualID, and return only the first ten results.

Connections

contacts (ContactConnection!)

List of Contacts

Argument	Type	Description
`after`	`String`	Returns the elements in the list that come after the specified cursor.
`before`	`String`	Returns the elements in the list that come before the specified cursor.
`first`	`Int`	Returns the first n elements from the list.
`last`	`Int`	Returns the last n elements from the list.
`primaryOnly`	`Boolean`	Only search primary contacts? The default value is `false`.
`query`	`String`	Query string
`sortDescending`	`Boolean`	Should the sort be descending? The default value is `false`.
`sortOn`	`ContactSortField`	Sort on this field

customers (CustomerConnection!)

Get all customers

Argument	Type	Description
`after`	`String`	Returns the elements in the list that come after the specified cursor.
`before`	`String`	Returns the elements in the list that come before the specified cursor.
`first`	`Int`	Returns the first n elements from the list.
`last`	`Int`	Returns the last n elements from the list.

inquiries (InquiryConnection!)

Get all Inquiries

Argument	Type	Description
`after`	`String`	Returns the elements in the list that come after the specified cursor.
`before`	`String`	Returns the elements in the list that come before the specified cursor.
`first`	`Int`	Returns the first n elements from the list.
`last`	`Int`	Returns the last n elements from the list.

invoices (InvoiceConnection)

Get all invoices

Argument	Type	Description
`after`	`String`	Returns the elements in the list that come after the specified cursor.
`before`	`String`	Returns the elements in the list that come before the specified cursor.
`excludeStatusIds`	`[ID!]`	Exclude ones with these status IDs
`first`	`Int`	Returns the first n elements from the list.
`inProductionAfter`	`ISO8601DateTime`	Find any with a due_date after this date
`inProductionBefore`	`ISO8601DateTime`	Find any with a start_date before this date
`last`	`Int`	Returns the last n elements from the list.
`paymentStatus`	`OrderPaymentStatus`	Find any with this payment status
`query`	`String`	Query string
`sortDescending`	`Boolean`	Should the sort be descending?
`sortOn`	`OrderSortField`	Sort on this field
`statusIds`	`[ID!]`	Only include ones with these status IDs
`tags`	`[String!]`	Find any with one of these tags. Ignored if using a query

merchStores (MerchStoreConnection!)

List all merch stores

Argument	Type	Description
`after`	`String`	Returns the elements in the list that come after the specified cursor.
`before`	`String`	Returns the elements in the list that come before the specified cursor.
`first`	`Int`	Returns the first n elements from the list.
`last`	`Int`	Returns the last n elements from the list.

orders (OrderUnionConnection)

Get all quotes and invoices

Argument	Type	Description
`after`	`String`	Returns the elements in the list that come after the specified cursor.
`before`	`String`	Returns the elements in the list that come before the specified cursor.
`excludeStatusIds`	`[ID!]`	Exclude ones with these status IDs
`first`	`Int`	Returns the first n elements from the list.
`inProductionAfter`	`ISO8601DateTime`	Find any with a due_date after this date
`inProductionBefore`	`ISO8601DateTime`	Find any with a start_date before this date
`last`	`Int`	Returns the last n elements from the list.
`paymentStatus`	`OrderPaymentStatus`	Find any with this payment status
`query`	`String`	Query string
`sortDescending`	`Boolean`	Should the sort be descending?
`sortOn`	`OrderSortField`	Sort on this field
`statusIds`	`[ID!]`	Only include ones with these status IDs
`tags`	`[String!]`	Find any with one of these tags. Ignored if using a query

paymentRequests (PaymentRequestConnection!)

Get all open payment requests

Argument	Type	Description
`after`	`String`	Returns the elements in the list that come after the specified cursor.
`before`	`String`	Returns the elements in the list that come before the specified cursor.
`first`	`Int`	Returns the first n elements from the list.
`last`	`Int`	Returns the last n elements from the list.

products (ProductConnection!)

List of products

Argument	Type	Description
`after`	`String`	Returns the elements in the list that come after the specified cursor.
`before`	`String`	Returns the elements in the list that come before the specified cursor.
`first`	`Int`	Returns the first n elements from the list.
`last`	`Int`	Returns the last n elements from the list.
`query`	`String!`	Product search term

quotes (QuoteConnection)

Get all quotes

Argument	Type	Description
`after`	`String`	Returns the elements in the list that come after the specified cursor.
`before`	`String`	Returns the elements in the list that come before the specified cursor.
`excludeStatusIds`	`[ID!]`	Exclude ones with these status IDs
`first`	`Int`	Returns the first n elements from the list.
`inProductionAfter`	`ISO8601DateTime`	Find any with a due_date after this date
`inProductionBefore`	`ISO8601DateTime`	Find any with a start_date before this date
`last`	`Int`	Returns the last n elements from the list.
`paymentStatus`	`OrderPaymentStatus`	Find any with this payment status
`query`	`String`	Query string
`sortDescending`	`Boolean`	Should the sort be descending?
`sortOn`	`OrderSortField`	Sort on this field
`statusIds`	`[ID!]`	Only include ones with these status IDs
`tags`	`[String!]`	Find any with one of these tags. Ignored if using a query

statuses (StatusConnection!)

List statuses

Argument	Type	Description
`after`	`String`	Returns the elements in the list that come after the specified cursor.
`before`	`String`	Returns the elements in the list that come before the specified cursor.
`first`	`Int`	Returns the first n elements from the list.
`last`	`Int`	Returns the last n elements from the list.
`type`	`StatusType`	The type of status

tasks (TaskConnection!)

Get all tasks

Argument	Type	Description
`after`	`String`	Returns the elements in the list that come after the specified cursor.
`assigneeId`	`ID`	Find only tasks assigned to this User
`before`	`String`	Returns the elements in the list that come before the specified cursor.
`completed`	`Boolean`	Search only for completed tasks?
`dueAfter`	`ISO8601DateTime`	Find any tasks with a due date after this date
`dueBefore`	`ISO8601DateTime`	Find any tasks with a due date before this date
`excludedOrderStatusIds`	`[ID!]`	Only find tasks with associated Orders that do not have one of these statuses
`first`	`Int`	Returns the first n elements from the list.
`includedOrderStatusIds`	`[ID!]`	Only find tasks with associated Orders that have one of these statuses
`last`	`Int`	Returns the last n elements from the list.
`sortDescending`	`Boolean`	Should the sort be descending?
`sortOn`	`TaskSortField`	Which field to sort Tasks on

threads (ThreadSummaryConnection!)

Get latest message from all threads

Argument	Type	Description
`after`	`String`	Returns the elements in the list that come after the specified cursor.
`before`	`String`	Returns the elements in the list that come before the specified cursor.
`first`	`Int`	Returns the first n elements from the list.
`last`	`Int`	Returns the last n elements from the list.
`onlyWithUnread`	`Boolean`	Only return threads that have unread messages?

transactions (TransactionUnionConnection!)

Get all transactions

Argument	Type	Description
`after`	`String`	Returns the elements in the list that come after the specified cursor.
`before`	`String`	Returns the elements in the list that come before the specified cursor.
`first`	`Int`	Returns the first n elements from the list.
`last`	`Int`	Returns the last n elements from the list.

Fields

account (Account!)

Get account for the current user's session

contact (Contact)

Get contact by ID

Argument	Type	Description
`id`	`ID!`	The ID of the contact to find

customer (Customer)

Get customer by ID

Argument	Type	Description
`id`	`ID!`	The ID of the customer to find

inquiry (Inquiry)

Get an Inquiry by ID

Argument	Type	Description
`id`	`ID!`	Inquiry ID to get

invoice (Invoice)

Get invoice by ID

Argument	Type	Description
`id`	`ID!`	The ID of the invoice to find

lineItem (LineItem!)

Get a line item by ID

Argument	Type	Description
`id`	`ID!`	The ID of the line item to find

lineItemGroup (LineItemGroup!)

Get a line item group by ID

Argument	Type	Description
`id`	`ID!`	The ID of the line item group to find

lineItemGroupPricing ([LineItemPriceReceipt!]!)

Calculate line item prices in a line item group

Argument	Type	Description
`lineItemGroup`	`LineItemGroupPricingInput!`	The line item group to calculate prices

merchOrder (MerchOrder)

Get merch order by ID

Argument	Type	Description
`id`	`ID!`	The ID of the merch order to find

merchStore (MerchStore)

Get a merch store by ID

Argument	Type	Description
`id`	`ID!`	The ID of the merch store for find

order (OrderUnion)

Get quote or invoice by ID

Argument	Type	Description
`id`	`ID!`	The ID of the quote or invoice to find

quote (Quote)

Get quote by ID

Argument	Type	Description
`id`	`ID!`	The ID of the quote to find

status (Status)

Status

Argument	Type	Description
`id`	`ID!`	The status ID

task (Task)

Get a task

Argument	Type	Description
`id`	`ID!`	Task ID to get

thread (Thread!)

Get all the messages in a thread

Argument	Type	Description
`id`	`ID!`	Thread ID to get messages from

transaction (TransactionUnion!)

Get transaction by ID

Argument	Type	Description
`id`	`ID!`	The ID of the transaction to find

user (User!)

Get user for the current user's session