Guides

We’ve compiled a few instructions and considerations for you when exploring this new API. Ultimately, this feature is still in progress, and we encourage you to provide feedback and suggestions for anything you may encounter throughout the beta.

💡

If you have not yet signed up for this beta, be sure to sign up here!

The endpoint will reference your Swell store domain, which can be found at the top of the API Keys section of the Developer menu in the dashboard.

Access URL
https://{store ID}.swell.store/graphql

For example, if Urbul gro-Orkulg wanted to use his Swell store ID (slash-n-smash), the endpoint would be https://slash-n-smash.swell.store/graphql.

Before you are able to query your endpoint, you will need to add an authorization header to your GraphQL client of choice, or to the HTTP Headers section if using the Playground. To do so, you will need a public key from your store, which can be acquired through your Swell store dashboard under Developer > API.

Depending on your preference, you can use an existing key or create and use a new public key by clicking the Add public key button and providing a description. Your new key will be displayed at the top of the Public keys table.

Example authorization key
{
  "Authorization": "pk_1234abcd5678efgh9101112ijklmnop"
}

Explore queries, current schema, and data structures with our GraphQL playground. To access the playground, enter the URL below in your browser:

Playground access URL
https://{store ID}.swell.store/playground

Within the Playground, you have access to:

  • An interactive way to explore fields and queries.
  • Instant feedback through a panel that shows you the responses to your queries.
  • A Docs tab to reference available types, queries, and mutations.
  • A Schema tab for an overview of your store schema and the option to download it.
💡

For our GraphQL playground, we are making use of the graphql-playground project. Check out these resources for more info →

Now that you’ve got the client and authorization configured, you’ll be able to explore and interact with your store data.

List products

So, if Urbul ever wanted to fetch a list of products for the Slash ‘N Smash, he could use the following:

POSTapi/graphql
query {
	products {
		results {
			name
		}
	}
}

Response

Urbul would receive the following response:

Example product query response
{
	"data" {
		"products": {
			"results": [
				{
					"name": "Rusty iron dagger"
				},
				{
					"name": "Steel shortsword"
				},
				{
					"name": "Iron bow"
				},
				{
					"name": "Elven longsword"
				},
				{
					"name": "Silver handaxe"
				},
				{
					"name": "Glass warhammer"
				},
				. . .]
			}
		}
	}

Some queries and mutations need an active session to be established (e.g., cart operations). For that, you’ll need to manage a session token and include it within your requests’ headers. This will allow you to continue interacting with the same session throughout your requests.

The session token can be acquired from the response headers of your queries, under the name X-Session. You’ll need to configure your application and GraphQL client to fetch it and store it for subsequent requests.

Example API Response
Response Headers
...
"X-Session": "f07c9fadde8fca959fe3152e1d949dc..."
...


Response Data
{
  "data": {
	  "addCartItem": {
		  "items": {
			  "product": {
				  "name": "Fine Iron Warhammer"
				 },
				 "quantity": 2
				}
			}
		}
	}
}

You can use this X-Session token by adding it to the list of headers of your GraphQL client or Playground session. For example, using the graphql-request client:

graphql-request example
const client = new GraphQLClient("my-store.swell.store/graphql", {
  headers: {
    "X-Session": "f07c9fadde8fca959fe3152e1d949dc..."
  }
});

Most GraphQL clients should support access to the headers and the ability to set the session header for subsequent requests.

⚠️

This session token can change after some operations—like adding to a cart or logging in—so we recommend that you keep it in sync by storing the latest X-Session response header after a request.

Say our good friend Urbul gro-Orkulg wanted to check the products in his cart and to add some to the list.

Fetching cart items

He could see if there’s already any items in his cart by using the following query:

query {
  cart {
    items {
      product {
        name
      }
    }
  }
}
Response
Returned cart
Response Headers
...
"X-Session": "f07c9fadde8fca959fe3152e1d949dc..."
...


Response Data
{
  "data": {
    "cart": {
      "items": null
    }
  }
}

Since no session token was provided, a new session is generated with a corresponding token and an empty cart.

👉

When making an initial query, a session is generated automatically with the first operation for use with subsequent queries.

⚠️

If attempting to fetch an existing cart, then the session token should be included within the request. Otherwise, it will be assumed that the intention is to create a new session.

Adding items to the cart

Urbul is surprised to see the cart empty. He’s completely unprepared for battle. He could use the following mutation to add some items to this session’s cart:

Add some items to the cart
Request Headers
...
"X-Session": "f07c9fadde8fca959fe3152e1d949dc..."
...

mutation {
	addCartItem(input: (productId: "5e5198ce72f5542e005fa4c8", quantity: 2)) {
		items {
			product {
				name
			}
			quantity
		}
	}
}

By specifying a session token within the HTTP Headers section prior to making additional queries, he can make sure that he never loses track of his cart’s items.

Query

Finally, he can try fetching the cart data from his current session again

with the following query:

Checking his cart
Request Headers
...
"X-Session": "f07c9fadde8fca959fe3152e1d949dc..."
...

query {
	cart {
		items {
			product {
				name
			}
			quantity
		}
	}
}
Response
{
  "data": {
	  "addCartItem": {
		  "items": {
			 {
			   "product": {
				   "name": "Fine Iron Warhammer"
				  },
				  "quantity": 2
			   }
			 }
		}
	}
}

Success! He would find that his wares were added to the cart successfully. Time to go find some Daedra!