Skip to main content

Draft orders

Draft orders allow merchants to create orders on behalf of customers for scenarios like phone orders, wholesale quotes, custom orders, and manual invoicing. Draft order pages display information about individual draft orders and draft order lists. Extensions on these pages help merchants enhance these workflows with custom functionality.

Anchor to Use casesUse cases

  • External order management: Sync draft orders with external order management systems, ERPs, or wholesale platforms to maintain consistent order data across systems and support B2B workflows.
  • Custom pricing and quotes: Display custom pricing, apply special discounts, calculate complex wholesale pricing, or generate professional quotes with pricing from external systems before converting draft orders.
  • Order validation and verification: Validate draft order data against external systems, verify customer credit limits, check inventory availability across warehouses, or flag potential issues before order completion.
  • Payment processing workflows: Integrate custom payment workflows, generate payment links for draft orders, process deposits or partial payments, or send payment requests to customers through external payment gateways.
  • Bulk draft order operations: Process multiple draft orders at once for operations like bulk conversion, batch invoice generation, mass updates, or exporting draft order data to accounting systems.
Shopify admin draft order pages showing all available extension target locations.

Anchor to Draft order details targetsDraft order details targets

Use action and block targets to extend the draft order details page. Add workflows and contextual information that help merchants manage individual draft orders and improve order creation processes.

Action targets open as modal overlays from the More actions menu, while block targets display as inline cards. The examples demonstrate fetching data from Shopify's direct API or your app's backend.

Anchor to Draft order details action ,[object Object]Draft order details action target

admin.draft-order-details.action.render

Renders an admin action extension on the draft order details page. Merchants can access this extension from the More actions menu. Use this target to provide workflows that operate on individual draft orders, such as syncing with external systems, generating quotes, processing payments, or applying custom pricing.

Extensions at this target can access information about the draft order through the data property in the Action Extension API. The action renders in a modal overlay, providing space for multi-step workflows, forms, and confirmations.

Support
Components (45)
APIs (1)

Supported components

Available APIs

Examples

jsx

import {render} from 'preact';
import {useState, useEffect} from 'preact/hooks';

export default async () => {
render(<Extension />, document.body);
};

const Extension = () => {
const [loading, setLoading] = useState(false);
const [fetching, setFetching] = useState(true);
const [draftOrder, setDraftOrder] = useState(null);
const [sendEmail, setSendEmail] = useState(true);
const [success, setSuccess] = useState(false);
const [error, setError] = useState(false);
const [paymentLink, setPaymentLink] = useState('');

useEffect(() => {
const fetchDraftOrder = async () => {
const draftOrderId = shopify.data.selected[0].id;

try {
// Fetch draft order details from GraphQL Admin API
const response = await fetch('shopify:admin/api/graphql.json', {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
query: `
query GetDraftOrder($id: ID!) {
draftOrder(id: $id) {
id
name
customer {
email
firstName
lastName
}
totalPriceSet {
presentmentMoney {
amount
currencyCode
}
}
}
}
`,
variables: {id: draftOrderId},
}),
});

const {data} = await response.json();
setDraftOrder(data.draftOrder);
} catch (err) {
console.error('Error fetching draft order:', err);
} finally {
setFetching(false);
}
};

fetchDraftOrder();
}, []);

const handleGenerate = async () => {
setLoading(true);
setSuccess(false);
setError(false);
const draftOrderId = shopify.data.selected[0].id;

try {
// Generate payment link through your app's backend
const response = await fetch('https://your-app.com/api/generate-payment-link', {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
draftOrderId,
sendEmail,
}),
});

if (response.ok) {
const {paymentUrl} = await response.json();
setPaymentLink(paymentUrl);
setSuccess(true);
} else {
setError(true);
}
} catch (err) {
setError(true);
} finally {
setLoading(false);
}
};

if (fetching) {
return (
<s-admin-action heading="Generate Payment Link">
<s-spinner size="base" /> Loading draft order details...
</s-admin-action>
);
}

return (
<s-admin-action heading="Generate Payment Link">
{success && (
<s-banner tone="success" dismissible={false}>
Payment link generated successfully!
{sendEmail && ' Email sent to customer.'}
</s-banner>
)}
{error && (
<s-banner tone="critical" dismissible={false}>
Failed to generate payment link. Please try again.
</s-banner>
)}

<s-section heading="Draft order information">
<s-stack gap="base">
<s-stack gap="small-300">
<s-text type="strong">Draft order:</s-text>
<s-text> {draftOrder.name}</s-text>
</s-stack>

{draftOrder.customer && (
<s-stack gap="small-300">
<s-text type="strong">Customer:</s-text>
<s-text> {draftOrder.customer.firstName} {draftOrder.customer.lastName}</s-text>
<s-text color="subdued"> ({draftOrder.customer.email})</s-text>
</s-stack>
)}

<s-stack gap="small-300">
<s-text type="strong">Total:</s-text>
<s-text> {draftOrder.totalPriceSet.presentmentMoney.currencyCode} {draftOrder.totalPriceSet.presentmentMoney.amount}</s-text>
</s-stack>
</s-stack>
</s-section>

<s-section heading="Payment link options">
<s-stack gap="base">
<s-checkbox
label="Send payment link to customer via email"
checked={sendEmail}
onChange={(event) => setSendEmail(event.currentTarget.checked)}
disabled={!draftOrder.customer?.email}
/>
{!draftOrder.customer?.email && (
<s-text color="subdued">No customer email available</s-text>
)}
</s-stack>
</s-section>

{paymentLink && (
<s-section heading="Payment link">
<s-stack gap="base">
<s-text-field
label="Payment URL"
value={paymentLink}
readOnly
/>
<s-button
onClick={() => navigator.clipboard.writeText(paymentLink)}
variant="secondary"
>
Copy to clipboard
</s-button>
</s-stack>
</s-section>
)}

<s-button
slot="primary-action"
onClick={handleGenerate}
disabled={loading || success}
>
{loading ? 'Generating...' : 'Generate Link'}
</s-button>
<s-button slot="secondary-actions" onClick={() => shopify.close()}>
{success ? 'Close' : 'Cancel'}
</s-button>
</s-admin-action>
);
};

Anchor to Draft order details action (should render) ,[object Object]Draft order details action (should render) target

admin.draft-order-details.action.should-render

Controls the render state of an admin action extension on the draft order details page. Use this target to conditionally show or hide your action extension based on the draft order's properties, such as status, customer type, or total amount.

This target returns a boolean value that determines whether the corresponding action extension appears in the More actions menu. The extension is evaluated each time the page loads.

Support
Components (0)
APIs (1)

Supported components

-

Available APIs

Examples

jsx

export default async () => {
const draftOrderId = shopify.data.selected[0].id;

try {
// Fetch draft order customer information
const response = await fetch(
'shopify:admin/api/graphql.json',
{
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
query: `
query GetDraftOrder($id: ID!) {
draftOrder(id: $id) {
customer {
id
}
}
}
`,
variables: {id: draftOrderId},
}),
}
);

const {data} = await response.json();

// Only show action if draft order has a customer
return {display: !!data.draftOrder.customer};
} catch (err) {
console.error('Error fetching draft order:', err);
return {display: false};
}
};

Anchor to Draft order details block ,[object Object]Draft order details block target

admin.draft-order-details.block.render

Renders an admin block extension inline on the draft order details page. Use this target to display contextual information, validation status, external system data, or payment status related to the draft order without requiring merchants to open a modal.

Extensions at this target appear as cards on the page and can show real-time data, insights, or quick actions. Blocks provide persistent visibility and are ideal for displaying information merchants need to see at a glance.

Support
Components (46)
APIs (1)

Supported components

Available APIs

Examples

jsx

import {render} from 'preact';
import {useState, useEffect} from 'preact/hooks';

export default async () => {
render(<Extension />, document.body);
};

const Extension = () => {
const [orderStatus, setOrderStatus] = useState(null);
const [loading, setLoading] = useState(true);

useEffect(() => {
const fetchOrderStatus = async () => {
const draftOrderId = shopify.data.selected[0].id;

try {
// Fetch order status from your app's backend
const response = await fetch(
`https://your-app.com/api/draft-order-status?draftOrderId=${draftOrderId}`
);
const data = await response.json();
setOrderStatus(data);
} catch (err) {
console.error('Error fetching order status:', err);
} finally {
setLoading(false);
}
};

fetchOrderStatus();
}, []);

if (loading) {
return (
<s-admin-block heading="External Order Status">
<s-spinner size="base" /> Loading order status...
</s-admin-block>
);
}

if (!orderStatus) {
return (
<s-admin-block heading="External Order Status">
<s-text color="subdued">Not synced with external system</s-text>
</s-admin-block>
);
}

return (
<s-admin-block heading="External Order Status">
<s-stack gap="base">
<s-stack gap="small-300">
<s-heading>Sync Status</s-heading>
<s-badge tone={orderStatus.synced ? 'success' : 'warning'}>
{orderStatus.synced ? 'Synced' : 'Pending'}
</s-badge>
</s-stack>

<s-divider />

<s-stack gap="small-300">
<s-heading>External Order ID</s-heading>
<s-text>{orderStatus.externalOrderId || 'Not assigned'}</s-text>
</s-stack>

<s-divider />

<s-stack gap="small-300">
<s-heading>Processing Status</s-heading>
<s-text>{orderStatus.processingStatus}</s-text>
</s-stack>

{orderStatus.warehouse && (
<>
<s-divider />
<s-stack gap="small-300">
<s-heading>Assigned Warehouse</s-heading>
<s-text>{orderStatus.warehouse}</s-text>
</s-stack>
</>
)}

{orderStatus.lastSyncedAt && (
<>
<s-divider />
<s-stack gap="small-300">
<s-heading>Last Synced</s-heading>
<s-text color="subdued">{orderStatus.lastSyncedAt}</s-text>
</s-stack>
</>
)}

{orderStatus.externalUrl && (
<s-button
onClick={() => window.open(orderStatus.externalUrl, '_blank')}
variant="secondary"
>
View in external system
</s-button>
)}
</s-stack>
</s-admin-block>
);
};

Anchor to Draft order index targetsDraft order index targets

Use action targets to extend the draft order index page with bulk operations and workflows that help merchants manage multiple draft orders efficiently.

Anchor to Draft order index action ,[object Object]Draft order index action target

admin.draft-order-index.action.render

Renders an admin action extension on the draft order index page. Merchants can access this extension from the More actions menu. Use this target to provide workflows that operate on the draft order list, such as batch processing, bulk exports, or generating reports.

Extensions at this target can access the page context through the Action Extension API. The action renders in a modal overlay, providing space for configuration and execution of list-wide operations.

Support
Components (45)
APIs (1)

Supported components

Available APIs

Examples

jsx

import {render} from 'preact';
import {useState} from 'preact/hooks';

export default async () => {
render(<Extension />, document.body);
};

const Extension = () => {
const [loading, setLoading] = useState(false);
const [exportType, setExportType] = useState('all');
const [dateRange, setDateRange] = useState('7days');
const [success, setSuccess] = useState(false);
const [error, setError] = useState(false);

const handleExport = async () => {
setLoading(true);
setSuccess(false);
setError(false);

try {
// Export draft orders through your app's backend
const response = await fetch('https://your-app.com/api/export-draft-orders', {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
exportType,
dateRange,
}),
});

if (response.ok) {
setSuccess(true);
shopify.close();
} else {
setError(true);
}
} catch (err) {
setError(true);
} finally {
setLoading(false);
}
};

return (
<s-admin-action heading="Export to ERP System">
{success && (
<s-banner tone="success" dismissible={false}>
Draft order export initiated! You'll receive an email when complete.
</s-banner>
)}
{error && (
<s-banner tone="critical" dismissible={false}>
Failed to initiate export. Please try again.
</s-banner>
)}

<s-section heading="Export settings">
<s-stack gap="base">
<s-select
label="Export type"
value={exportType}
onChange={(event) => setExportType(event.currentTarget.value)}
>
<option value="all">All draft orders</option>
<option value="open">Open draft orders only</option>
<option value="completed">Completed draft orders only</option>
<option value="invoiced">Invoiced draft orders only</option>
</s-select>

<s-select
label="Date range"
value={dateRange}
onChange={(event) => setDateRange(event.currentTarget.value)}
>
<option value="7days">Last 7 days</option>
<option value="30days">Last 30 days</option>
<option value="90days">Last 90 days</option>
<option value="1year">Last year</option>
<option value="all">All time</option>
</s-select>

<s-banner tone="info" dismissible={false}>
This will export all matching draft orders to your ERP system. Large exports may take several minutes to complete.
</s-banner>
</s-stack>
</s-section>

<s-button
slot="primary-action"
onClick={handleExport}
disabled={loading || success}
>
{loading ? 'Starting Export...' : 'Start Export'}
</s-button>
<s-button slot="secondary-actions" onClick={() => shopify.close()}>
Cancel
</s-button>
</s-admin-action>
);
};

Anchor to Draft order index action (should render) ,[object Object]Draft order index action (should render) target

admin.draft-order-index.action.should-render

Controls the render state of an admin action extension on the draft order index page. Use this target to conditionally show or hide your action extension based on business logic, user permissions, or app configuration.

This target returns a boolean value that determines whether the corresponding action extension appears in the More actions menu. The extension is evaluated each time the page loads.

Support
Components (0)
APIs (1)

Supported components

-

Available APIs

Examples

jsx

export default async () => {
try {
// Check if app is configured through your backend
const response = await fetch(
'https://your-app.com/api/check-configuration'
);
const {configured, erpConnected} = await response.json();

// Only show action if app is configured and ERP is connected
return {display: configured && erpConnected};
} catch (err) {
console.error('Error checking configuration:', err);
return {display: false};
}
};

Anchor to Draft order index selection action ,[object Object]Draft order index selection action target

admin.draft-order-index.selection-action.render

Renders a selection action extension on the draft order index page when multiple draft orders are selected. Merchants can access this extension from the More actions menu of the resource list. Use this target to provide bulk operations on selected draft orders, such as bulk conversion, batch invoice generation, or bulk status updates.

Extensions at this target can access the IDs of selected draft orders through the data property in the Action Extension API. The action renders in a modal overlay designed for batch processing.

Support
Components (45)
APIs (1)

Supported components

Available APIs

Examples

jsx

import {render} from 'preact';
import {useState, useEffect} from 'preact/hooks';

export default async () => {
render(<Extension />, document.body);
};

const Extension = () => {
const [loading, setLoading] = useState(false);
const [draftOrderCount, setDraftOrderCount] = useState(0);
const [sendMethod, setSendMethod] = useState('email');
const [emailTemplate, setEmailTemplate] = useState('default');
const [success, setSuccess] = useState(false);
const [error, setError] = useState(false);
const [eligibleCount, setEligibleCount] = useState(0);

useEffect(() => {
const checkEligibility = async () => {
const selectedDraftOrders = shopify.data.selected || [];
setDraftOrderCount(selectedDraftOrders.length);

// Check how many draft orders have customers with email addresses
try {
const draftOrderIds = selectedDraftOrders.map((draftOrder) => draftOrder.id);
const response = await fetch('https://your-app.com/api/check-payment-eligibility', {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({draftOrderIds}),
});
const {eligibleCount: count} = await response.json();
setEligibleCount(count);
} catch (err) {
console.error('Error checking eligibility:', err);
}
};

checkEligibility();
}, []);

const handleSend = async () => {
setLoading(true);
setSuccess(false);
setError(false);
const draftOrderIds = shopify.data.selected.map((draftOrder) => draftOrder.id);

try {
// Send payment requests through your app's backend
const response = await fetch('https://your-app.com/api/send-payment-requests', {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
draftOrderIds,
sendMethod,
emailTemplate,
}),
});

if (response.ok) {
setSuccess(true);
shopify.close();
} else {
setError(true);
}
} catch (err) {
setError(true);
} finally {
setLoading(false);
}
};

return (
<s-admin-action heading="Send Payment Requests">
{success && (
<s-banner tone="success" dismissible={false}>
Payment requests sent successfully to {eligibleCount} customers!
</s-banner>
)}
{error && (
<s-banner tone="critical" dismissible={false}>
Failed to send payment requests. Please try again.
</s-banner>
)}

<s-section heading="Payment request settings">
<s-stack gap="base">
<s-stack gap="small-300">
<s-text type="strong">Selected draft orders:</s-text>
<s-text> {draftOrderCount}</s-text>
</s-stack>

<s-stack gap="small-300">
<s-text type="strong">Eligible for payment requests:</s-text>
<s-text> {eligibleCount}</s-text>
<s-text color="subdued"> (with customer email)</s-text>
</s-stack>

<s-select
label="Delivery method"
value={sendMethod}
onChange={(event) => setSendMethod(event.currentTarget.value)}
>
<option value="email">Email</option>
<option value="sms">SMS (if available)</option>
</s-select>

<s-select
label="Email template"
value={emailTemplate}
onChange={(event) => setEmailTemplate(event.currentTarget.value)}
>
<option value="default">Default payment request</option>
<option value="friendly">Friendly reminder</option>
<option value="professional">Professional invoice</option>
<option value="urgent">Urgent payment request</option>
</s-select>

{eligibleCount < draftOrderCount && (
<s-banner tone="warning" dismissible={false}>
{draftOrderCount - eligibleCount} draft orders will be skipped (missing customer email).
</s-banner>
)}
</s-stack>
</s-section>

<s-button
slot="primary-action"
onClick={handleSend}
disabled={loading || success || eligibleCount === 0}
>
{loading ? 'Sending...' : `Send ${eligibleCount} Payment Requests`}
</s-button>
<s-button slot="secondary-actions" onClick={() => shopify.close()}>
Cancel
</s-button>
</s-admin-action>
);
};

Anchor to Draft order index selection action (should render) ,[object Object]Draft order index selection action (should render) target

admin.draft-order-index.selection-action.should-render

Controls the render state of a selection action extension on the draft order index page when multiple draft orders are selected. Use this target to conditionally show or hide your bulk action extension based on the number of selected draft orders, their properties, or app configuration.

This target returns a boolean value that determines whether the corresponding selection action extension appears in the More actions menu. The extension is evaluated each time the selection changes.

Support
Components (0)
APIs (1)

Supported components

-

Available APIs

Examples

jsx

export default async () => {
const selectedCount = shopify.data.selected?.length || 0;

// Only show action if between 1 and 50 draft orders are selected
return {display: selectedCount > 0 && selectedCount <= 50};
};

Anchor to Best practicesBest practices

  • Handle draft order states properly: Draft orders can be in different states (open, invoice sent, completed). Always check the draft order status before performing operations, and provide clear feedback when operations aren't applicable to certain states.
  • Validate customer information: Many draft order workflows require customer information. Always validate that required customer data (for example, email and address) exists before attempting operations like sending payment links or converting to orders.
  • Provide clear conversion workflows: When building workflows that convert draft orders to orders, provide clear confirmation steps and explain what will happen. Draft order conversion is a significant action that merchants need to understand.
  • Respect payment status: Be mindful of existing payment requests and payment status. Avoid sending duplicate payment requests or conflicting payment workflows that could confuse customers.

Anchor to LimitationsLimitations

  • Single target per module: Each [[extensions.targeting]] entry in your TOML configuration maps one target to one module file.
  • Data retention: Draft orders created on or after April 1, 2025 are automatically purged after one year of inactivity.
  • Block target visibility: Block extensions must be manually added and pinned by merchants before they appear.
  • Block collapse behavior: Returning null from a block extension collapses the block rather than removing it from the page. Blocks can't be fully hidden at runtime.
Was this page helpful?