invoices

The invoices query provides a wide range of filter criteria to return a set of invoices.

3 minute read

Key Information

Use-Case

The invoices query can be used by both Operators and Sellers to return invoice objects using a wide range of filter criteria. Possibly the most common scenario for this mutation would be in a Seller Integration, where a Seller wants to retrieve (poll) for new invoices created within a given time period (e.g. every hour).

Further Points of Note

While Sellers can use this query to query for their Invoices, they should be aware that attempting to reference the Order object associated with the invoice will result in a query permissions error. This is because the Order object is considered a marketplace-level object, and as such is only available to Operators to query.

You can read more about the Anatomy of an Order here.

Availability

Operator API: Yes
Seller API: Yes (Scoped to Seller-owned invoices only)

Example 1 - Querying the Invoice only

query getNonDispatchedInvoices{
  invoices(
    first: 10
    after: null
    filters: { 
      createdSince: "2019-08-26T09:15:49Z", 
      notDispatched: true }
    sort: { fields: [PAID_AT], ordering: DESCENDING }
  ) {
    totalCount
    nodes {
      id
      legacyId
      seller {
        businessName
      }
      lineItems {
        id
        variantId
      }
    }
    pageInfo{
      hasNextPage
      endCursor
    }
  }
}

Example 2 - Querying the Invoice and associated Order

As discussed above, if a Seller attempts to run this query they will encounter a permissions error as they have requested the order as part of the query

query {
  invoices(
    first: 10
    after: ""
    filters: { 
      createdSince: "2019-08-26T09:15:49Z", 
      notDispatched: true }
    sort: { fields: [PAID_AT], ordering: DESCENDING }
  ) {
    totalCount
    nodes {
      id
      legacyId
      seller {
        businessName
      }
      lineItems {
        id
        variantId
      }
      order {
        id
        legacyId
        externalId
        totalCents
      }
    }
    pageInfo{
      hasNextPage
      endCursor
    }
  }
}

Arguments

Name	Type	Description
filters	InvoiceFilters	Extensive collection of filter attributes
sort	InvoiceSort	ALlows you to select which field to sort on (e.g. `CREATED_AT`, and how you want to sort, e.g. `DESCENDING`)
after	String	Pagination cursor for moving through result set - more on pagination here
before	String	Not in use - backwards pagination not supported
first	Int	Pagination page size - more on pagination here
last	Int	Not in use - backwards pagination not supported

Response

Returns InvoicesConnection

Error Responses

HTTP Error	Error Message	Meaning
401	Unauthorized	You don’t have access to the endpoint, likely Basic Authentication credentials are missing
401	API Token has expired	You don’t have access to the endpoint, likely that you are either not supplying an API Key, or the key you are supplying is invalid
200	An object of type Order was hidden due to permissions	You have attempted to query the `Order` object without the requisite permissions