Shop API Guide

GraphQL Shop API Guide

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

This guide only lists some of the more common operations you’ll need for your storefront. Please consult the Shop API reference for a complete guide.

Universal Parameters

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

  • languageCode: This sets the current langauge 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

  • query collections : List available Collections. Useful for creating navigation menus.
  • query search : Useful both for keyword searching, and for listing product results by collectionId and/or facetValueId. In practice this query can power all kinds of storefront product lists as it is backed by a search index optimized for performance.
  • query product : Use this for the Product detail view.

Order flow

See the Order Workflow guide for a detailed explanation 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.
  • mutation 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 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.