Skip to content

GraphQL

GraphQL is the main way to read data from Shypr. Each record of a workspace, with its relations, is a type in the schema.

POST https://api.shypr.app/graphql
Content-Type: application/json
X-API-KEY: sh_...

The endpoint accepts only a JSON POST. A GET or a form post finds no route.

{
"query": "query Invoices($page: Int) { invoices(page: $page) { collection { uid } } }",
"variables": { "page": 1 }
}

Download the full schema: schema.graphql. Load it in your editor or in a code generator such as GraphQL Code Generator to get types for your queries.

The schema changes as Shypr grows. Download it again when you update your integration.

A collection query returns a collection and a paginationInfo. Pages start at 1. A page has 25 items by default, at most 100.

query OpenInvoices {
invoices(page: 1, itemsPerPage: 50, _order: [{ dueDate: "ASC" }]) {
collection {
uid
displaySequenceId
dueDate { unix }
grandTotal { amount precision currency }
customer { name reference }
}
paginationInfo {
currentPage
lastPage
totalCount
hasNextPage
}
}
}

Read the next page while hasNextPage is true.

The arguments of a collection query are its filters. They differ for each type. The schema lists them.

Filter Example Meaning
Exact customer_id: "/customers/0193..." The relation is this record.
List customer_id_list: ["/customers/0193...", "/customers/0194..."] The relation is one of these records.
Text name: "acme" The text matches the value. The schema description of each filter tells how.
Date issueDate: [{ after: "1767225600" }] A unix time as a string. Also before, strictly_before and strictly_after.
Order _order: [{ issueDate: "DESC" }] Sort on one or more fields.
{
invoices(
issueDate: [{ after: "1767225600", strictly_before: "1769904000" }]
_order: [{ issueDate: "DESC" }]
) {
collection { uid displaySequenceId }
}
}

A single-record query takes the IRI of the record as id:

{
customer(id: "/customers/01936f6e-2b1c-7a4e-9c1d-3f5e8a2b7c90") {
name
vatNumber
invoices(itemsPerPage: 10) { collection { displaySequenceId } }
}
}

A mutation takes one input object and returns a payload with the record:

mutation AddNote($input: createNoteInput!) {
createNote(input: $input) {
note { uid }
}
}

Use variables for the input. Do not put values in the query text.

Many writes of billing, CRM, warehousing and shipping are REST endpoints. See REST.

A GraphQL error comes back with status 200 and an errors list. Always read errors before data. See Errors.