How to query orders

What you’ll learn

• The simplified Marketplacer order / invoice model
• The API calls you can use to return your orders form Marketplacer

The Marketplacer Order Model

The diagram below illustrates the relationship between Order, Invoices and Line Items:

Put simply:

• A Seller is an individual entity (usually a business) that the marketplace operator has invited to sell on their marketplace. Multiple sellers can “participate” in a single order.
• An Order is the “marketplace-level” object that acts as the container for a customer’s entire purchase. An order object in Marketplacer will always have at least 1 Invoice attached to it.
• An invoice is the individual seller’s “view” of the order. Given that we are dealing with a marketplace, it is conceivable that customers will purchase items from 1 or more Sellers. It is therefore necessary to “split” the order into seller-level components, in this case the invoice object. Even if there is only 1 seller participating in the transaction, there will still be an invoice created on the order
• A Line Item is the individual item that a customer will purchase. Line items start their journey as Variants placed for sale on the marketplace by the seller. When a variant object is purchased a lineItem object is created.

The takeaway

The primary takeaway from this conversation is that as a Seller on Marketplacer, you will primarily be interested in querying Invoice objects. You may still hear the terms “orders” and “invoices” used interchangeably though.

Querying Invoices

The Seller API invoices query is a flexible way to retrieve your invoices from Marketplacer, providing a wide range filters that satisfy multiple use-cases. We therefore won’t cover every conceivable permutation here, but provide a number of examples to get you started.

The Seller API Collection contains examples of the Invoices query, and the full specification can be found in our reference documentation.

Before launching in to the queries it is assumed you’ve set up your environment as per these instructions.

Example 1

Starting with the simplest of queries, in this example we call the invoice query with no parameters, requesting only a set of fields on the invoice object:

query {
	invoices {
		totalCount
		nodes {
			id
			legacyId
			createdAt
			updatedAt
			totalCents
			statusFlags
		}
	}
}

This will return a JSON payload with the first 100 invoices for the Seller.

You can of course specify a different page size from the default 100, as well as employ paging. This is covered in detail in a separate article on pagination.

An example of the response for this query is shown below (for brevity we have only shown the first 2 invoice objects):

{
  "data": {
    "invoices": {
      "totalCount": 652,
      "nodes": [
        {
          "id": "SW52b2ljZS0xMDExMg==",
          "legacyId": 10112,
          "createdAt": "2020-11-11T14:49:13+11:00",
          "updatedAt": "2021-10-08T12:59:25+11:00",
          "totalCents": 10000,
          "statusFlags": [
            "PAID",
            "SENT",
            "REMITTED"
          ]
        },
        {
          "id": "SW52b2ljZS0xMDExNA==",
          "legacyId": 10114,
          "createdAt": "2020-11-13T11:28:29+11:00",
          "updatedAt": "2021-10-08T12:59:25+11:00",
          "totalCents": 10000,
          "statusFlags": [
            "PAID",
            "SENT",
            "REMITTED"
          ]
        }
      ]
    }
  }
}

Example 2

To build out a slightly more complex query this next example we:

• Change the default page size to 50
• Filter by the last updated date
• Include Line Items for the Invoice

query {
	invoices (
		first: 50
		filters: {updatedSince: "2022-04-01"}
	) {
		totalCount
		nodes {
			id
			legacyId
			createdAt
			updatedAt
			totalCents
			statusFlags
			lineItems
			{
				id
				variantName
			}
		}
	}
}

An example response to this query is shown below (again limited to 2 invoice objects)

{
  "data": {
    "invoices": {
      "totalCount": 605,
      "nodes": [
        {
          "id": "SW52b2ljZS0xMDExNg==",
          "legacyId": 10116,
          "createdAt": "2020-11-13T11:56:39+11:00",
          "updatedAt": "2022-05-12T14:01:49+10:00",
          "totalCents": 2000,
          "statusFlags": [
            "PAID",
            "SENT",
            "REMITTED"
          ],
          "lineItems": [
            {
              "id": "TGluZUl0ZW0tMTMz",
              "variantName": "Brown / 47"
            }
          ]
        },
        {
          "id": "SW52b2ljZS0xMDEyMg==",
          "legacyId": 10122,
          "createdAt": "2020-11-13T13:00:45+11:00",
          "updatedAt": "2022-05-12T14:01:49+10:00",
          "totalCents": 2000,
          "statusFlags": [
            "PAID",
            "SENT",
            "REMITTED"
          ],
          "lineItems": [
            {
              "id": "TGluZUl0ZW0tMTM5",
              "variantName": "Purple / 37"
            }
          ]
        }
      ]
    }
  }
}

Example 3

In this example we:

• Change the filter to all invoices that haven’t been dispatched
• Sorted the results by the paidAt in Ascending order
• Introduced the paidAt date in our payload response

query {
	invoices (
		first: 50
		filters: {notDispatched: true}
		sort: {fields: PAID_AT ordering: ASCENDING}
	) {
		totalCount
		nodes {
			id
			legacyId
			paidAt
			statusFlags
		}
	}
}

An example response for this query can be shown below (again limited to 2 invoice objects):

{
  "data": {
    "invoices": {
      "totalCount": 456,
      "nodes": [
        {
          "id": "SW52b2ljZS0xMDExNQ==",
          "legacyId": 10115,
          "paidAt": "2020-11-13T11:52:25+11:00",
          "statusFlags": [
            "PAID",
            "PARTIALLY_SENT"
          ]
        },
        {
          "id": "SW52b2ljZS0xMDExOA==",
          "legacyId": 10118,
          "paidAt": "2020-11-13T12:29:51+11:00",
          "statusFlags": [
            "PAID",
            "PARTIALLY_SENT"
          ]
        }
      ]
    }
  }
}