API Requests

After authentication, you can make requests to the Qumra Admin API using GraphQL or REST.

GraphQL Requests

GraphQL is the primary way to interact with the Qumra Admin API. After authenticating, use the admin.graphql() method to execute queries and mutations.

Simple Query

export async function loader({ request }: { request: Request }) {
  const { admin } = await authenticate.admin(request);

  const shop = await admin.graphql(`
    query {
      shop {
        name
        email
        domain
      }
    }
  `);

  return Response.json(shop);
}

Query with Variables

Pass variables as the second argument to admin.graphql():

const products = await admin.graphql(
  `
  query GetProducts($first: Int!) {
    products(first: $first) {
      edges {
        node {
          id
          title
          price
        }
      }
    }
  }
`,
  { first: 10 }
);

admin.graphql() Signature

graphql<TResponse = unknown, TVariables = Record<string, unknown>>(
  query: string,
  variables?: TVariables
): Promise<TResponse>

Parameter	Type	Description
query	string	A GraphQL query or mutation string.
variables	TVariables	Optional variables to pass into the query.

REST Requests

For endpoints not available via GraphQL, you can use Qumra.fetch() to make standard HTTP requests.

GET Request

import Qumra from "~/qumra.server";

const stores = await Qumra.fetch({
  url: "https://api.qumra.cloud/v1/stores",
  method: "GET",
  headers: {
    Authorization: `Bearer ${session.accessToken}`,
  },
});

POST Request

const result = await Qumra.fetch({
  url: "https://api.qumra.cloud/v1/orders",
  method: "POST",
  body: {
    items: [{ product_id: "123", quantity: 1 }],
  },
  headers: {
    Authorization: `Bearer ${session.accessToken}`,
  },
});

FetchRequestOptions Interface

interface FetchRequestOptions<TVariables, TBody> {
  url?: string;
  method?: HttpMethod;  // "GET" | "POST" | "PUT" | "PATCH" | "DELETE"
  headers?: Record<string, string>;
  query?: string;
  variables?: TVariables;
  body?: TBody;
  timeout?: number;     // Default: 30000ms
}

Field	Type	Description
url	string	The full URL of the API endpoint.
method	HttpMethod	HTTP method: GET, POST, PUT, PATCH, DELETE.
headers	Record<string, string>	Request headers (e.g. Authorization).
query	string	Optional GraphQL query string.
variables	TVariables	Optional variables for the query.
body	TBody	Request body for POST, PUT, PATCH requests.
timeout	number	Request timeout in milliseconds. Default: 30000.

Prefer GraphQL

Prefer GraphQL over REST for most operations. The GraphQL API provides a strongly-typed schema with better querying capabilities.

Error Handling

Both admin.graphql() and Qumra.fetch() will throw errors on failure. See the Error Handling guide for details on catching and handling API failures.