get-orders
Retrieve Shopify orders with advanced filtering, sorting, and pagination to manage and analyze store transactions.
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:304-346 (registration)Registration of the 'get-orders' tool, including input schema and inline handler function that delegates to ShopifyClient.loadOrders and formats 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:307-323 (schema)Zod input schema defining parameters for the get-orders tool: first, after, query, sortKey, reverse.
{ 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"), }, - src/index.ts:324-346 (handler)Inline handler function for get-orders tool: creates ShopifyClient, calls loadOrders, formats results with formatOrder, returns formatted text content.
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:52-102 (helper)Helper function to format a ShopifyOrderGraphql object into a human-readable string.
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 helper method in ShopifyClient class that executes GraphQL query to Shopify Admin API to fetch orders with pagination, filtering, sorting.
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, }; }