GraphQL Shop API Guide

This is an overview of the GraphQL Shop API, which is used when implementing a storefront application with Vendure.

Universal Parameters

There are a couple of query parameters that are valid for all GraphQL operations:

• languageCode: This sets the current language for the request. Any translatable types (e.g. Products, Facets, Collections) will be returned in that language, if a translation is defined for that language. If not, they will fall back to the default language. The value should be one of the ISO 639-1 codes defined by the LanguageCode enum.

  POST http://localhost:3000/shop-api?languageCode=de
  

• vendure-token: If your Vendure instance features more than a single Channel, the token of the active Channel can be specified by token as either a query parameter or as a header. The name of the key can be configured by the channelTokenKey config option.

Browsing the catalogue

Listing collections

This query lists available Collections. Useful for creating navigation menus. The query will return Collections as a flat list, rather than a tree structure. Using the parent and children fields, you can convert this list into an arrayToTree function.

Listing products

The search query is intended to be used for keyword searching, facet-based filtering, and for listing product results by collection. In practice this query can power all kinds of storefront product lists, and is preferable to the products query, since it is backed by a dedicated search index and as such, queries are significantly more efficient.

Filtering by facet

A common requirement is to make product listing pages filterable based on facets. Using the search query, you can select a summary of all Facets and FacetValues which apply to the current results:

query SearchProducts {
  search(input: {
    collectionSlug: "shoes"
  }) {
    totalItems
    items {
      productId
      productName
    }
    facetValues {
      facetValue {
        id
        name
      }
      count
    }
  }
}

The FacetValue data can be then used to create a facet filter UI, allowing the customer to select which facets to filter for. The result set can then be filtered using the facetValueFilters input field:

query SearchProducts {
  search(input: {
    collectionSlug: "shoes"
    facetValueFilters: [
      { or: [34, 25] },
      { and: 12 }
    ]
  }) {
    totalItems
    # etc.
  }
}

The above example translates to return all products in the “shoes” collection, which have FacetValue 12 AND (34 OR 25)

Product detail

Use the product query for the Product detail view.

Order flow

See the Order Workflow guide for a detailed explanation with examples of how Orders are handled in Vendure.

• query activeOrder returns the currently-active Order for the session.
• mutation addItemToOrder adds an item to the order. The first time it is called will also create a new Order for the session.
• mutation adjustOrderLine is used to adjust the quantity of an OrderLine.
• mutation removeOrderLine removes an OrderLine from the Order.
• mutation removeAllOrderLines removes all OrderLine from the Order.
• mutation setCustomerForOrder specifies the Customer details (required if the customer is not logged in as an authenticated user).
• mutation setOrderShippingAddress sets the shipping address for the Order.
• query eligibleShippingMethods returns all available shipping methods based on the customer’s shipping address and the contents of the Order.
• mutation setOrderShippingMethod sets the shipping method to use.
• query eligiblePaymentMethods returns all available payment methods based on the contents of the Order.
• query nextOrderStates returns the possible next states that the active Order can transition to
• mutation transitionOrderToState transitions the active Order to the given state according to the Order state machine.
• mutation addPaymentToOrder adds a payment to the Order. If the payment amount equals the order total, then the Order will be transitioned to either the PaymentAuthorized or PaymentSettled state (depending on how the payment provider is configured) and the order process is complete from the customer’s side.
• query orderByCode allows even guest Customers to fetch the order they just placed for up to 2 hours after placing it. This is intended to be used to display an order confirmation page immediately after the order is completed.

Customer account management

• mutation registerCustomerAccount : Creates a new Customer account.
• mutation login : Log in with registered Customer credentials.
• mutation logout : Log out from Customer account.
• query activeCustomer : Returns the current logged-in Customer, or null if not logged in. This is useful for displaying the logged-in status in the storefront. The returned Customer type can also be used to query the Customer’s Order history, list of Addresses and other personal details.
• mutation requestPasswordReset : Use this to implement a “forgotten password” flow. This will trigger a password reset email to be sent.
• mutation resetPassword : Use the token provided in the password reset email to set a new password.