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.

Prepare your store

Use a store with published products, purchasable variants, and shipping methods configured for your channel. The interactive examples use IDs returned by your store, so they do not need to match the sample IDs.

For an empty local development store, you can add sample data.

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:8000/graphql/ All queries will be via public access unless app token headers are specified.

Run the public examples directly below after configuring your API URL. The embedded Playground sends anonymous requests and does not accept tokens. Before configuration, the examples show editable placeholder values without executing requests.

Within this walkthrough, successful results fill in the next step’s variables. Run each prerequisite first; the connection check is optional. Rerunning or editing an earlier step clears dependent progress. Refreshing, leaving the page, or changing the API URL resets the walkthrough.

The later order operations require an app token and must be run in a separate GraphQL client.

Check your connection

Read your shop name

A small public query to check your connection. No token is needed.

Fetch products

Retrieve up to 10 products with a minimal price between 10 and 100. The editable channel starts as default-channel; replace it with a slug from your store in Variables, then execute the query to see a paginated list of product names and categories from your store.

The response also includes the cost of the query.

Fetch products

Filter products by price in your channel. Replace default-channel in Variables with a channel slug from your store.

Get specific product

The first product ID and channel from the previous successful query are filled in automatically. You can edit them in Variables before fetching product details.

You can edit the query to explore other public product fields. For schema exploration and autocomplete, use your store’s standalone GraphQL playground.

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

Get specific product

Use the first product returned by Fetch products. You can edit its ID and channel in Variables.

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.

Create a checkout

Use the first variant returned by Get specific product. This creates a checkout without placing an order or charging a payment.

Update checkout

Let’s add shipping and billing addresses and an email to the anonymous checkout. Review the sample address and email in Variables before running this mutation.

Notice that we can add three 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.

Update checkout

Add shipping and billing addresses and an email to the created checkout. Edit the sample address and email in Variables for your store.

mutation UpdateCheckout($checkoutId: ID!, $address: AddressInput!, $email: String!) { checkoutShippingAddressUpdate(checkoutId: $checkoutId, shippingAddress: $address) { errors { field code message } } checkoutBillingAddressUpdate(checkoutId: $checkoutId, billingAddress: $address) { errors { field code message } } checkoutEmailUpdate(checkoutId: $checkoutId, email: $email) { checkout { shippingMethods { id name } } errors { field code message } } }

Select shipping method

The first available shipping method from the previous step is filled in automatically. You can replace its ID in Variables with another returned method. If none are available, review the address and your store’s shipping configuration before rerunning Update checkout.

Select shipping method

Use the first shipping method returned by Update checkout. You can choose a different returned ID in Variables.

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 Extentions → Add Extention → Provide details manually
App name My App
Enable permissions HANDLE_CHECKOUTS and MANAGE_ORDERS
Copy the 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 the 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
        }
      }
    }
  }
}

Create an order

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

This operation requires an app token with HANDLE_CHECKOUTS. Use a separate GraphQL client, such as your store’s /graphql/ playground, and add the app token copied in the previous step to its headers. The embedded Playground does not accept tokens. Replace the sample checkout ID below with the ID returned when you created your checkout. 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.

Note: orderCreateFromCheckout mutation requires the App Token. To transform the checkout on behalf of the customer, use checkoutComplete mutation.

{
  "authorization": "Bearer YOUR_TOKEN"
}

mutation {
  orderCreateFromCheckout(
    id: "Q2hlY2tvdXQ6NmUzMzRlMjMtOWJiNS00MWUwLTk1NzYtZDc0NmJmMzQ4NDc1"
  ) {
    order {
      id
      status
      lines {
        variantName
        quantity
      }
    }
    errors {
      field
      message
    }
  }
}

{
  "data": {
    "orderCreateFromCheckout": {
      "order": {
        "id": "T3JkZXI6MzYwNWE2MWYtNDc4OC00ZjZlLWJiYzktZjEwMjJhOGFlOGYw",
        "status": "UNCONFIRMED",
        "lines": [
          {
            "variantName": "S",
            "quantity": 1
          }
        ]
      },
      "errors": []
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 1,
      "maximumAvailable": 50000
    }
  }
}

Marking order as paid

This operation requires MANAGE_ORDERS. Run it in the same authenticated client and replace the sample order ID with the ID returned by the previous operation.

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
      }
    }
  }
}

{
  "data": {
    "order": {
      "id": "T3JkZXI6MzYwNWE2MWYtNDc4OC00ZjZlLWJiYzktZjEwMjJhOGFlOGYw",
      "totalBalance": {
        "amount": 0
      }
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 1,
      "maximumAvailable": 50000
    }
  }
}

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.

Explore GraphQL tools
Learn more about Saleor’s GraphQL API usage.

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.

API Walkthrough

Prepare your store

Open GraphQL playground

Check your connection

Saleor Playground

Fetch products

Saleor Playground

Get specific product

Saleor Playground

Create a checkout

Saleor Playground

Update checkout

Saleor Playground

Select shipping method

Saleor Playground

Add webhook

Create an order

Marking order as paid

Next steps

Useful resources

Postman