GraphQL API
Search…
Products

Introduction

This guide describes how to obtain products from the Outshifter GraphQL API.
You can either retrieve a single product or a list of products.
  • List of Products: You may require a list of products 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 products available in your store.
  • Single Product: You may require a single product when you need more information of a particular product, for example when you need to show full listing data before to trigger purchase decision.
Besides from these two main options, there are additional features to look into, such as filtering of products, sorting, how we manage pricing and how we deal with stocks.

Product Catalog

Working with Outshifter gives you the possibility to get products from multiple suppliers.
When fetching product data, you can choose from the following parameters from the ProductCatalog.
  • id: the unique product identifier
  • title: the title of the product
  • description: it provides commercial information about the product.
  • price: the price of the product. You can choose the currency it comes in.
  • currency: it can be USD, EUR or NOK
  • images
  • quantity: the available stock. This field is updated each time you receive product information. It is an important field to validate at the moment of the purchase to check for possibles out of stock.
  • supplier: it contains an object with key user information
If the product has variants, check both the ProductOption and the ProductVariant objects.
Each option contains:
Each variant contains:
  • id: The unique id identifier of the variant.
  • title: A combination of the variant options. For example: "Small-Blue".
  • price: The price of the variant. It usually is the same, but it may vary.
  • quantity: the available stock of the variant.

Retrieving a list of products

By retrieving saved products from a seller, you as a partner can get products from a wide range of suppliers.
This endpoint is designed with displaying a list of products on the frontend of your solution in mind. You will get general information about the product. If you want additional and more detailed data, see the other endpoint (Ref. single product).
To fetch a product list, you need to run the products query. Let's take a look at an example to fetch a list of products:
1
query ExampleQuery {
2
AllCatalog {
3
id
4
title
5
referalFee
6
description
7
supplier {
8
id
9
name
10
}
11
quantity
12
price
13
images {
14
url
15
width
16
order
17
height
18
}
19
}
20
}
Copied!
Response:
1
{
2
"data": {
3
"AllCatalog": [
4
{
5
"id": "920",
6
"title": "Silk Summer Top",
7
"referalFee": 10,
8
"description": "<p>Silk womens top with short sleeves and number pattern.</p>",
9
"supplier": {
10
"id": "239",
11
"name": " LM Corporation"
12
},
13
"quantity": 0,
14
"price": 70,
15
"images": [
16
{
17
"url": "https://cdn.shopify.com/s/files/1/0532/0717/1247/products/young-hip-woman-at-carnival_925x_5922501b-0a6b-48f3-84ce-db1f3ae3cb99.jpg?v=1611671752",
18
"width": 925,
19
"order": 0,
20
"height": 617
21
}
22
]
23
},
24
...
25
]
26
}
27
}
Copied!
You can work with the data provided, just continue to the next sections to learn how to:
  • paginate: The products field is a paginated collection, see Pagination for more information.
  • filter: By default the response will provide all saved products. You may include in the body pre defined filters and get a more refined response.
  • sort: Define the order you want to receive the products in the array. Only some fields are available here.

Retrieving a single product

Get single product information by id. You will receive detailed information of a product from the Outshifter database.
Use the product query, which requires only one input field as an argument:
  • catalogId: the unique product ID.
1
{
2
"catalogId": 920
3
}
Copied!
Here is the example query that fetches a single product:
1
query ExampleQuery($catalogId: Int!) {
2
Catalog(id: $catalogId) {
3
id
4
title
5
quantity
6
price
7
images {
8
order
9
url
10
}
11
}
12
}
Copied!
Response:
1
{
2
"data": {
3
"Catagog": {
4
"id": "920",
5
"title": "Silk Summer Top",
6
"quantity": 0,
7
"price": 70,
8
"images": [
9
{
10
"url": "https://cdn.shopify.com/s/files/1/0532/0717/1247/products/young-hip-woman-at-carnival_925x_5922501b-0a6b-48f3-84ce-db1f3ae3cb99.jpg?v=1611671752",
11
"order": 0,
12
}
13
]
14
}
15
}
16
}
Copied!

Filtering

The products 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 a given value.
· price: {gte: Float}: price greater than or equal to a given value.
· minimalPrice: ...: filter by minimal variant price:
· minimalPrice: {lte: Float}: price lower than or equal to a given value.
· minimalPrice: {gte: Float}: price greater than or equal to a given value.
· stockAvailability: ...: filter by available stock:
· stockAvailability: IN_STOCK: only available products.
· stockAvailability: OUT_OF_STOCK: only out-of-stock products.
Here is an example query that looks for the first 3 products containing the term "juice" in the title or description:

Sorting

In products 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 products by last update.
· MINIMAL_PRICE: sort products by minimal variant price.
· NAME: sort products by name.
· PRICE: sort products by base price.
· PUBLICATION_DATE: sort products by publication date.
· PUBLISHED: sort products by publication status.
· RATING: sort products by rating.
· TYPE: sort products by product type.
  • direction: The direction for sorting items:
· ASC: sort ascending.
· DESC: sort descending.
This example shows how to sort the products list by the minimal variant price, lowest to highest:
Response:

Retrieving product variants

To obtain product variants, query the variants field on the Product type:
Response:
Like products, 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 products and variants to obtain pricing information.
Here are the available fields for product pricing:
And similar fields for product variants:
The main difference is that products 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:
See Prices for more information about money types.

Fetching prices with tax rates specific to a country

When using Outshifter with tax, you can fetch prices including taxes specific to a country. To do that, pass the address parameter in the pricing field including a country code, for which the tax should be calculated. The address parameter is available in Product.pricing and ProductVariant.pricing fields.
In the example below we fetch a price of a product variant for Norway, where the standard VAT rate is 25%:
Result:
The tax equals 100 which is 25% of the net price. Gross price is the sum of net price and the tax.

Stock availability for customers

Stock availability of products is defined for each variant and warehouse (see Warehouses and Checking inventory sections to see how to configure it in the Dashboard). There are two fields that allows you to fetch the stock information in the public API.
To fetch the stock availability, use the Product.isAvailable field:
Result:
The address parameter is used to check the quantity in a warehouse that is connected with a shipping zone that includes the given address. If not provided, Outshifter will use a warehouse with the highest available quantity.
The isAvailable field is True when:
· There is at least one variant for which the stock quantity minus the allocated quantity is above zero (in a warehouse matched for the given address).
· The product is published in the given channel and available for purchase (see Make your product available section in the Dashboard docs).
To fetch the available quantity, use the ProductVariant.quantityAvailable field:
Response:
A warehouse is chosen based on the argument address. If the argument is omitted, API will return the highest available quantity.

Stock quantities

For creating integrations with an external stock management system, you will need to use stock values not restricted by MAX_CHECKOUT_LINE_QUANTITY.
To clarify the difference between quantityAvailable and stocks, we will query both for the product variant:
Request:
Response:
· "quantityAvailable": 50: customers only see maximum of 50 pcs available to buy
· stocks contain full list of stock quantities in every of the warehouses

Media

Product media are images that can be associated with products and used to render product galleries. Outshifter saves the product images is a defined sorting order:
  • order: 0 is related to the main product image
  • order: 1 is related to the cover product image
  • order >= 2 is related to the remaining gallery images
The Product type contains the following fields that refer to its media:
· images: Image: the product's images come in an array. An optional width and height parameters specifies the desired size in pixels.
Available fields:
· url: String!: the image's URL.
· alt: String: the alternative text to include when displaying the image.
· order: Int: the order of the .
· width: Int: the width of the image to display.
· height: Int: the height of the image to display.
Here's a query that asks for both the thumbnail and all media of the first product, optimized for display at 100×100px: