Query Order Information

This guide describes how to obtain orders from the Nautical Commerce GraphQL API.

You can either retrieve a single order or a list of orders. You may require a list of orders in many situations, for example, when you need to simply display the catalog in your storefront, or to provide a third party service with a list of orders available in your store.

Retrieving a list of orders

To fetch a order list, you need to run the orders query. The orders field is a paginated collection, see Pagination for more information.

Let's take a look at an example query to fetch a list of orders:

{
  orders(first: 2) {
    edges {
      node {
        id
        name
      }
    }
  }
}

In this example, for each order, we want to return the following fields:

• id: the unique order ID, most operations will require one.
• name: the name of the order.

Filtering

The orders query gives the ability to filter the results. Use the optional filter argument. Some of the filters that are available here are:

• search: String: search by name or part of the description.
• price: ...: filter by base price:
  • price: {lte: Float}: price lower than or equal to given value.
  • price: {gte: Float}: price greater than or equal to given value.
• minimalPrice: ...: filter by minimal variant price:
  • minimalPrice: {lte: Float}: price lower than or equal to given value.
  • minimalPrice: {gte: Float}: price greater than or equal to given value.
• stockAvailability: ...: filter by available stock:
  • stockAvailability: IN_STOCK: only available orders.
  • stockAvailability: OUT_OF_STOCK: only out-of-stock orders.

Here is an example query that looks for the first 3 orders containing the term "juice" in the title or description:

{
  orders(first: 3, filter: { search: "juice" }) {
    edges {
      node {
        name
      }
    }
  }
}

Sorting

In orders you can also sort the results using two sortBy arguments:

• field: the field to use for sorting the results from several predefined choices:
  • DATE: sort orders by last update.
  • MINIMAL_PRICE: sort orders by minimal variant price.
  • NAME: sort orders by name.
  • PRICE: sort orders by base price.
  • PUBLICATION_DATE: sort orders by publication date.
  • PUBLISHED: sort orders by publication status.
  • TYPE: sort orders by order type.
• direction: The direction for sorting items:
  • ASC: sort ascending.
  • DESC: sort descending.

This example shows how to sort the orders list by the minimal variant price, lowest to highest:

{
  orders(
    first: 2
    sortBy: { field: MINIMAL_PRICE, direction: ASC }
  ) {
    edges {
      node {
        name
        minimalVariantPrice {
          amount
          currency
        }
      }
    }
  }
}

Retrieving a single order

To get a single order, use the order query, which requires only one input field:

• id: the unique order ID.

Here is the example query that fetches a single order:

query {
  order(id: "UHJvZHVjdDoxMTU=") {
    id
    name
  }
}

Retrieving order variants

To obtain order variants, query the variants field on the order type:

{
  orders(first: 1) {
    edges {
      node {
        id
        name
        variants {
          id
          name
        }
      }
    }
  }
}

Like orders, here we're asking for two fields from each variant:

• id: the unique variant ID.
• name: the name of the variant.

Pricing

Use the pricing field of orders and variants to obtain pricing information.

Here are the available fields for order pricing:

type orderPricingInfo {
  priceRange: TaxedMoneyRange
  priceRangeUndiscounted: TaxedMoneyRange
  discount: TaxedMoney
  onSale: Boolean
}

And similar fields for order variants:

type VariantPricingInfo {
  price: TaxedMoney
  priceUndiscounted: TaxedMoney
  discount: TaxedMoney
  onSale: Boolean
}

The main difference is that orders don't have a price point, instead they offer a price range that includes all of their variant prices.

Here are the money types returned by the above:

type TaxedMoneyRange {
  # lowest price
  start: TaxedMoney
  # highest price
  stop: TaxedMoney
}

type TaxedMoney {
  # before tax
  net: Money!
  # after tax
  gross: Money!

  # gross - net
  tax: Money!
  # repeated for convenience
  currency: String!
}

type Money {
  amount: Float!
  currency: String!
}

Show more ↓

Images

The order type contains two fields that refer to its images:

• thumbnail: the order's main image. An optional size parameter specifies the desired size in pixels if given. The following fields are available:
  • url: the image's URL.
  • alt: the alternative text to include when displaying the image.
• images: gives you access to the entire list of associated order images with the following fields available:
  • url: the image's URL. An optional size parameter specifies the desired size in pixels if given.
  • alt: the alternative text to include when displaying the image.

Here's a query that asks for both the thumbnail and all images of the first order, optimized for display at 100×100px:

{
  orders(first: 1) {
    edges {
      node {
        id
        name
        thumbnail(size: 100) {
          url
          alt
        }
        images {
          url(size: 100)
          alt
        }
      }
    }
  }
}

Examples

Here's a more complex GraphQL query that combines all of the above information:

{
  orders(first: 2, sortBy: {field: NAME}) {
    edges {
      node {
        id
        name
        pricing {
          priceRange {
            start {
              gross {
                amount
                currency
              }
            }
          }
          discount {
            gross {
              amount
              currency
            }
          }
          priceRangeUndiscounted {
            start {
              gross {
                amount
                currency
              }
            }
          }
        }
        thumbnail {
          url
        }
      }
    }
  }
}

Show more ↓