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

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