invoices

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

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

NameTypeDescription
filtersInvoiceFiltersExtensive collection of filter attributes
sortInvoiceSortALlows you to select which field to sort on (e.g. CREATED_AT, and how you want to sort, e.g. DESCENDING)
afterStringPagination cursor for moving through result set - more on pagination here
beforeStringNot in use - backwards pagination not supported
firstIntPagination page size - more on pagination here
lastIntNot in use - backwards pagination not supported

Response

Returns InvoicesConnection


Error Responses

HTTP ErrorError MessageMeaning
401UnauthorizedYou don’t have access to the endpoint, likely Basic Authentication credentials are missing
401API Token has expiredYou 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
200An object of type Order was hidden due to permissionsYou have attempted to query the Order object without the requisite permissions

Further Reading