Skip to main content

Introduction

In this section, we'll guide you through the essential steps to start using the Endless Commerce GraphQL API. You'll learn how to connect to the server, authenticate your requests, and understand the necessary headers. We'll also cover how to handle responses, including both successful payloads and error messages.

Connecting to the GraphQL Server

The Endless Commerce GraphQL API is accessible via a single endpoint:

https://api-dev.endlesscommerce.com/graphql

Authentication

To interact securely with the Endless Commerce GraphQL API, authentication is a crucial step. Follow these steps to authenticate and obtain a token for subsequent API requests.

Step 1: Sign In to Obtain Token​

Use the signIn mutation to authenticate and acquire an access token. Include your credentials (such as username and password) in the mutation.

mutation {
    signIn(input: {
        loginIdentifier: "your@email",
        password: "your-password"
    }) {
        token
        tokenExpiration
    }
}

Replace your@email and your-password with your actual credentials. The response will include the access token.

{
  "data": {
    "signIn": {
      "token": "your_access_token",
      "tokenExpiration": "2023-08-15T12:00:00Z"
    }
  }
}

Step 2: Use Token in Subsequent Requests​

Include the obtained access token in the Authorization header with the Bearer scheme for all subsequent API requests.

Example using cURL:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_access_token" \
  --data '{ "query": "{ yourGraphQLQuery }" }' \
  https://api-dev.endlesscommerce.com/graphql

Replace your_access_token with the token obtained from the signIn mutation.

Now, you are authenticated and can make secure requests to the Endless Commerce GraphQL API.

Note: Please replace placeholder values with your actual credentials and tokens when using the examples.

Required Headers

When making requests to the Endless Commerce GraphQL API, include the following headers:

Content-Type: application/json
Authorization: Bearer your_access_token
X-Company-Id: your_company_id (optional)
X-Brand-Id: your_brand_id (optional)

Replace your_access_token with the token obtained from the signIn mutation.

Example using cURL:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_access_token" \
  -H "X-Company-Id: Bearer your_access_token" \
  -H "X-Brand-Id: Bearer your_access_token" \
  --data '{ "query": "{ yourGraphQLQuery }" }' \
  https://api-dev.endlesscommerce.com/graphql

Response Handling​

Successful Response​

A successful response will have a status code of 200 and contain a JSON object with a data field. The structure of the data field will depend on the query or mutation you've executed.

Example of a successful response:

{
  "data": {
    "yourQuery": {
      "field1": "value1",
      "field2": "value2"
    }
  }
}

Error Responses​

When an error occurs, the API will return an appropriate HTTP status code along with a JSON response body containing more details about the error.

Example of an error response:

{
  "data": null,
  "errors": [
    {
      "message": "A descriptive error message",
      "locations": [
        {
          "line": 3,
          "column": 3
        }
      ],
      "path": [
        "createOrder"
      ],
      "extensions": {
        "code": "E0004",
        "name": "ValidationError",
        "status": 404
      }
    }
  ]
}

Always check for the presence of an errors field in the response to handle potential issues in your API requests.

Now you're ready to start using the Endless Commerce GraphQL API. If you have any questions or need further assistance, please don't hesitate to reach out to our support team.

Note: Always replace placeholder values with your actual credentials and tokens when using the examples in your implementation.