Skip to main content

API Walkthrough

Getting familiar with basic APIs and Webhooks. This guide assumes basic knowledge of GraphQL.

Communicating with Saleor is done via public and private GraphQL APIs and webhooks:

  • Public APIs: Used for storefront clients, mobile apps, and other public-facing applications that do not store secret tokens.
  • Admin APIs: Can be accessed by backend services, admin dashboards, apps or backends for front-ends.
  • Webhooks: Used to notify external systems about events in Saleor, such as order creation, order payment, or order fulfillment.
  • Sync Webhooks: Allow to modify saleor responses, for when user adds item to cart, webhook would call your backend to for custom price calculation.

GraphQL provides many benefits and one of them is tooling that eliminates the needs for dedicated SDKs. To keep this guide universal to any technology stack, we will use GraphQL playground, but you can paste the queries to your preferred language or tool.

1

Use sample dataset​

To make this guide easier to follow, we recommend using a sample dataset to ensure that the IDs used in example queries and mutations are identical.

For Saleor Cloud: Go to instance settings and choose "Replace database with a sample".

For local development follow this step.

2

Open GraphQL playground​

Saleor comes with GraphQL pre-installed, which can be accessed in two ways:

Saleor Dashboard: The dashboard is available at use cmd+' to open the playground. All queries will be on behalf of the authenticated user, therefore the queries will be limited to the user's permissions.

Public playground: Each instance has /graphql/ endpoint available for public access. For example https://{your_store}.saleor.cloud/graphql/ or http://localhost:9000/graphql/ All queries will be via public access unless app token headers are specified.

For this tutorial, we will use the public playground to execute queries. But you can use the dashboard playground as well, as it will not require additional credentials (assuming you are the admin).

3

Fetch products​

Retrieve a list of 10 products with a minimal price between 10 and 100.

In the result tab, we get a paginated list of products with their names and categories.

Each query also returns the cost of the query.

{
  products(
    first: 10
    channel: "default-channel"
    where: { minimalPrice: { range: { gte: 10, lte: 100 } } }
  ) {
    edges {
      node {
        id
        name
        category {
          id
          name
        }
      }
    }
  }
}
4

Get specific product​

Retrieve the first product ID from the previous query and fetch the product details.

It is possible to fetch many fields associated with products. To conveniently explore the fields that can be added to the query, use the auto-complete by using cmd+space or ctrl+space on Windows. Or use the folder icon in the left side panel to explore the fields and interactively add them to the query.

Note that some fields are private and require specific permissions, which we will cover in the later steps.

{
  product(id: "UHJvZHVjdDoxMzQ=", channel: "default-channel") {
    id
    seoTitle
    seoDescription
    availableForPurchaseAt
    created
    externalReference
    isAvailable(address: { country: US })
    media(sortBy: { direction: ASC, field: ID }) {
      id
      alt
    }
    name
    variants {
      created
      id
      media {
        alt
      }
    }
  }
}
Expand ▼
5

Create a checkout​

Let's create a checkout with a product variant we fetched in the previous step.

Checkout only accepts the variant ID, not the product, as variants have inventory and pricing information.

mutation {
  checkoutCreate(
    input: {
      channel: "default-channel"
      lines: { quantity: 1, variantId: "UHJvZHVjdFZhcmlhbnQ6MzQ4" }
    }
  ) {
    checkout {
      id
      lines {
        id
        variant {
          name
        }
      }
    }
    errors {
      field
      message
    }
  }
}
Expand ▼
6

Update checkout​

Let's add the user and billing addresses to the checkout and assign them to an anonymous user.

Notice that we can add two mutations in a single request. In the last mutation, we updated the email address of the checkout and requested the shipping methods available for the checkout.

mutation {
  checkoutShippingAddressUpdate(
    checkoutId: "Q2hlY2tvdXQ6NmUzMzRlMjMtOWJiNS00MWUwLTk1NzYtZDc0NmJmMzQ4NDc1"
    shippingAddress: {
      firstName: "First"
      lastName: "Last"
      streetAddress1: "8066 Madison St."
      city: "Brooklyn"
      postalCode: "11237"
      country: US
      countryArea: "NY"
    }
  ) {
    errors {
      field
      message
    }
  }
  checkoutBillingAddressUpdate(
    checkoutId: "Q2hlY2tvdXQ6NmUzMzRlMjMtOWJiNS00MWUwLTk1NzYtZDc0NmJmMzQ4NDc1"
    billingAddress: {
      firstName: "First"
      lastName: "Last"
      streetAddress1: "8066 Madison St."
      city: "Brooklyn"
      postalCode: "11237"
      country: US
      countryArea: "NY"
    }
  ) {
    errors {
      field
      message
    }
  }
  checkoutEmailUpdate(
    checkoutId: "Q2hlY2tvdXQ6NmUzMzRlMjMtOWJiNS00MWUwLTk1NzYtZDc0NmJmMzQ4NDc1"
    email: "test@test.com"
  ) {
    checkout {
      shippingMethods {
        id
        name
      }
    }
    errors {
      field
      message
    }
  }
}
Expand ▼
7

Select shipping method​

Let's select the default shipping method for the checkout retrieved in the previous step.

mutation {
  checkoutDeliveryMethodUpdate(
    id: "Q2hlY2tvdXQ6NmUzMzRlMjMtOWJiNS00MWUwLTk1NzYtZDc0NmJmMzQ4NDc1"
    deliveryMethodId: "U2hpcHBpbmdNZXRob2Q6MQ=="
  ) {
    errors {
      field
      message
    }
  }
}
8

Add webhook​

Before placing an order, we would like to add a webhook to notify our system about the order so we can dispatch email, create an export to the ERP system, or any other custom action.

For simplicity of the steps, let's do it via the dashboard:

  • Open Saleor dashboard
  • Go to Settings -> Create App
  • App name My App
  • Enable Permissions HANDLE_CHECKOUT and MANAGE_ORDERS
  • Copy generated token somewhere safe
  • Create a webhook with the following details:
    • Name: Order webhook
    • Target URL: For simplicity of the test go to https://webhook.site/ and copy Your unique URL value
    • App: My App
    • Select Event: Asynchronous -> ORDER -> CREATED
subscription {
  event {
    ... on OrderCreated {
      __typename
      order {
        id
        shippingAddress {
          streetAddress1
          city
          cityArea
          companyName
          countryArea
          firstName
          country {
            country
            code
          }
          id
          lastName
          postalCode
          phone
        }
      }
    }
  }
}
Expand ▼
9

Create an order​

For simplicity of the steps, we will skip the payment step and create an order directly.

Creating an order without payment requires admin or app permission. Add the app token copied in the previous step to the headers in the playground. If you forgot or lost a token from the previous step, you can create another one in the app settings.

After executing the mutation, you should be able to see the order in the dashboard and a payload in the https://webhook.site/ with the order details provided in the subscription query.

{
  "authorization": "Bearer YOUR_TOKEN"
}
10

Marking order as paid​

We can mark the order as paid manually in the dashboard, but let's proceed via API, as the main feature of headless API is that we can automate anything via API.

mutation {
  orderMarkAsPaid(
    id: "T3JkZXI6MzYwNWE2MWYtNDc4OC00ZjZlLWJiYzktZjEwMjJhOGFlOGYw"
  ) {
    order {
      id
      totalBalance {
        amount
      }
    }
  }
}

Next steps​

To learn more about Saleor APIs interactively, you can inspect GraphQL operations using the browser's native network inspector or GraphQL inspector while using the dashboard.

Useful resources​

Postman​

Official postman profile of Saleor's QA team. You can fork collections and flows which are useful for testing and exploring Saleor APIs.