get-orders
Retrieve Shopify orders with filtering, sorting, and pagination capabilities to manage store data efficiently.
Instructions
Get shopify orders with advanced filtering and sorting
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| first | No | Limit of orders to return | |
| after | No | Next page cursor | |
| query | No | Filter orders using query syntax | |
| sortKey | No | Field to sort by | |
| reverse | No | Reverse sort order |
Implementation Reference
- src/index.ts:276-317 (registration)Registration of the MCP 'get-orders' tool, including input schema and the handler function that delegates to ShopifyClient.loadOrders and formats the output.
server.tool( "get-orders", "Get shopify orders with advanced filtering and sorting", { first: z.number().optional().describe("Limit of orders to return"), after: z.string().optional().describe("Next page cursor"), query: z.string().optional().describe("Filter orders using query syntax"), sortKey: z .enum([ "PROCESSED_AT", "TOTAL_PRICE", "ID", "CREATED_AT", "UPDATED_AT", "ORDER_NUMBER", ]) .optional() .describe("Field to sort by"), reverse: z.boolean().optional().describe("Reverse sort order"), }, async ({ first, after, query, sortKey, reverse }) => { const client = new ShopifyClient(); try { const response = await client.loadOrders( SHOPIFY_ACCESS_TOKEN, MYSHOPIFY_DOMAIN, { first, after, query, sortKey, reverse, } ); const formattedOrders = response.orders.map(formatOrder); return { content: [{ type: "text", text: formattedOrders.join("\n---\n") }], }; } catch (error) { return handleError("Failed to retrieve orders data", error); } } - src/index.ts:51-102 (handler)Helper function formatOrder used by the get-orders handler to format order data into readable text.
function formatOrder(order: ShopifyOrderGraphql): string { return ` Order: ${order.name} (${order.id}) Created At: ${order.createdAt} Status: ${order.displayFinancialStatus || "N/A"} Email: ${order.email || "N/A"} Phone: ${order.phone || "N/A"} Total Price: ${order.totalPriceSet.shopMoney.amount} ${ order.totalPriceSet.shopMoney.currencyCode } Customer: ${ order.customer ? ` ID: ${order.customer.id} Email: ${order.customer.email}` : "No customer information" } Shipping Address: ${ order.shippingAddress ? ` Province: ${order.shippingAddress.provinceCode || "N/A"} Country: ${order.shippingAddress.countryCode}` : "No shipping address" } Line Items: ${ order.lineItems.nodes.length > 0 ? order.lineItems.nodes .map( (item) => ` Title: ${item.title} Quantity: ${item.quantity} Price: ${item.originalTotalSet.shopMoney.amount} ${ item.originalTotalSet.shopMoney.currencyCode } Variant: ${ item.variant ? ` Title: ${item.variant.title} SKU: ${item.variant.sku || "N/A"} Price: ${item.variant.price}` : "No variant information" }` ) .join("\n") : "No items" } `; } - Core handler implementation in ShopifyClient.loadOrders that performs the GraphQL query to fetch orders from Shopify API with filtering, sorting, and pagination.
async loadOrders( accessToken: string, shop: string, queryParams: ShopifyOrdersGraphqlQueryParams ): Promise<ShopifyOrdersGraphqlResponse> { const myshopifyDomain = await this.getMyShopifyDomain(accessToken, shop); const graphqlQuery = gql` query getOrdersDetailed( $first: Int $after: String $query: String $sortKey: OrderSortKeys $reverse: Boolean ) { orders( first: $first after: $after query: $query sortKey: $sortKey reverse: $reverse ) { nodes { id name createdAt displayFinancialStatus email phone totalPriceSet { shopMoney { amount currencyCode } presentmentMoney { amount currencyCode } } customer { id email } shippingAddress { provinceCode countryCode } lineItems(first: 50) { nodes { id title quantity originalTotalSet { shopMoney { amount currencyCode } } variant { id title sku price } } } } pageInfo { hasNextPage endCursor } } } `; const variables = { first: queryParams.first || 50, after: queryParams.after, query: queryParams.query, sortKey: queryParams.sortKey, reverse: queryParams.reverse, }; const res = await this.shopifyGraphqlRequest<{ data: { orders: { nodes: ShopifyOrderGraphql[]; pageInfo: { hasNextPage: boolean; endCursor: string | null; }; }; }; }>({ url: `https://${myshopifyDomain}/admin/api/${this.SHOPIFY_API_VERSION}/graphql.json`, accessToken, query: graphqlQuery, variables, }); return { orders: res.data.data.orders.nodes, pageInfo: res.data.data.orders.pageInfo, }; } - TypeScript type definitions for input parameters (ShopifyOrdersGraphqlQueryParams) and response (ShopifyOrdersGraphqlResponse) used by the loadOrders method and thus the get-orders tool.
export type ShopifyOrdersGraphqlQueryParams = { first?: number; after?: string; query?: string; sortKey?: | "PROCESSED_AT" | "TOTAL_PRICE" | "ID" | "CREATED_AT" | "UPDATED_AT" | "ORDER_NUMBER"; reverse?: boolean; }; export type ShopifyOrdersGraphqlResponse = { orders: ShopifyOrderGraphql[]; pageInfo: { hasNextPage: boolean; endCursor: string | null; }; }; - Type definition for ShopifyOrderGraphql, the data structure for individual orders returned by the GraphQL query in loadOrders.
export type ShopifyOrderGraphql = { id: string; name: string; createdAt: string; displayFinancialStatus: string; email: string; phone: string | null; totalPriceSet: { shopMoney: { amount: string; currencyCode: string }; presentmentMoney: { amount: string; currencyCode: string }; }; customer: { id: string; email: string; } | null; shippingAddress: { provinceCode: string | null; countryCode: string; } | null; lineItems: { nodes: Array<{ id: string; title: string; quantity: number; originalTotalSet: { shopMoney: { amount: string; currencyCode: string }; }; variant: { id: string; title: string; sku: string | null; price: string; } | null; }>; }; };