create-promo-order

name	create-promo-order
description	Create a promotional or sample order for a customer
user-invocable	true

You are helping the sales team create a promotional or sample order.

IMPORTANT: Before doing anything else, use the ToolSearch tool with query +promo-order to load the promo-order MCP tools. All tools below are prefixed with mcp__promo-order__ (e.g., mcp__promo-order__search_accounts).

Follow these steps:

Step 1: Identify the Customer

Ask the user for the customer name or email. Use mcp__promo-order__search_accounts to find the customer record.

If multiple matches are returned, present them and ask the user to confirm which customer.

If no match is found, ask the user to verify the name/email or provide an alternative.

Step 2: Choose Order Type

Ask the user:

• Promo order — 100% discounted draft order for promotional purposes
• Sample order — 100% discounted draft order for product sampling

Step 3: Select Products

Use mcp__promo-order__check_products to show available products with current inventory levels.

Let the user select products and quantities. Validate that:

• Requested quantities are available in inventory
• Products are eligible for promo/sample orders

Step 4: Collect Required Tracking Fields

Call mcp__promo-order__list_metafield_options to get valid values for:

• internal_requestor — who is requesting this order (e.g., "Gordon Divine", "Brian Littlefield")
• promo_order_type — the purpose (e.g., "Wholesale/DSD Account Sampling", "Trade Shows and Events")

Present the options and ask the user to select one of each. These are required on every order.

Step 5: Confirm and Create

Display a summary:

• Customer name and shipping address
• Order type (promo/sample)
• Line items with quantities
• Total retail value (pre-discount)
• Internal requestor and order type

After user confirmation, use mcp__promo-order__create_promo_order with:

• customer_id: from Step 1
• variant_ids: comma-separated variant IDs from Step 3
• quantities: comma-separated quantities matching variants
• note: any notes from the user
• internal_requestor: from Step 4
• promo_order_type: from Step 4

Step 6: Report Result

Show the created draft order ID and link. Remind the user that draft orders require approval before fulfillment (via /jf-sales-command:approve-orders).

Error Handling

• If MCP tools are unavailable, inform the user that the promo-order server may need reconnection
• If inventory is insufficient, suggest alternative products or reduced quantities
• If customer creation is needed, direct the user to the Shopify admin