Choose a version:

draftOrderCreate

mutation

Requires write_draft_orders access scope. Also: The user must have access to manage draft orders.

Creates a draft order with attributes such as customer information, line items, shipping and billing addresses, and payment terms. Draft orders are useful for merchants that need to:

Create new orders for sales made by phone, in person, by chat, or elsewhere. When a merchant accepts payment for a draft order, an order is created.
Send invoices to customers with a secure checkout link.
Use custom items to represent additional costs or products not in inventory.
Re-create orders manually from active sales channels.
Sell products at discount or wholesale rates.
Take pre-orders.

After creating a draft order, you can:

Send an invoice to the customer using the draftOrderInvoiceSend mutation.
Complete the draft order using the draftOrderComplete mutation.
Update the draft order using the draftOrderUpdate mutation.
Duplicate a draft order using the draftOrderDuplicate mutation.
Delete the draft order using the draftOrderDelete mutation.

Note

When you create a draft order, you can't reserve or hold inventory for the items in the order by default. However, you can reserve inventory using the reserveInventoryUntil input.

Arguments

Anchor to inputinput •DraftOrderInput!required: The fields used to create the draft order.

Was this section helpful?

Anchor to DraftOrderCreatePayload returnsDraftOrderCreatePayload returns

Anchor to draftOrderdraftOrder •DraftOrder: The created draft order.
Anchor to userErrorsuserErrors •[UserError!]!non-null: The list of errors that occurred from executing the mutation.

Was this section helpful?

Create a draft order
Create a draft order with markets context
Create a new metafield on a new draft order
Creating a draft order with a company, location and company contact
Creating a draft order with invalid input returns an error
draftOrderCreate reference

Examples

Open in GraphiQL

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(

`#graphql

mutation draftOrderCreate($input: DraftOrderInput!) {

draftOrderCreate(input: $input) {

draftOrder {

}

}`,

{

variables: {

"input": {

"customerId": "gid://shopify/Customer/544365967",

"note": "Test draft order",

"email": "test.user@shopify.com",

"taxExempt": true,

"tags": [

"foo",

"bar"

"shippingLine": {

"title": "Custom Shipping",

"price": 4.55

"shippingAddress": {

"address1": "123 Main St",

"city": "Waterloo",

"province": "Ontario",

"country": "Canada",

"zip": "A1A 1A1"

"billingAddress": {

"address1": "456 Main St",

"city": "Toronto",

"province": "Ontario",

"country": "Canada",

"zip": "Z9Z 9Z9"

"appliedDiscount": {

"description": "damaged",

"value": 5.0,

"amount": 5.0,

"valueType": "FIXED_AMOUNT",

"title": "Custom"

"lineItems": [

{

"title": "Custom product",

"originalUnitPrice": 14.99,

"quantity": 5,

"appliedDiscount": {

"description": "wholesale",

"value": 5.0,

"amount": 3.74,

"valueType": "PERCENTAGE",

"title": "Fancy"

"weight": {

"value": 1,

"unit": "KILOGRAMS"

"customAttributes": [

{

"key": "color",

"value": "Gold"

{

"key": "material",

"value": "Plastic"

}

]

{

"variantId": "gid://shopify/ProductVariant/43729076",

"quantity": 2

}

"customAttributes": [

{

"key": "name",

"value": "Achilles"

{

"key": "city",

"value": "Troy"

}

]

}

);

const data = await response.json();

mutation draftOrderCreate($input: DraftOrderInput!) {
  draftOrderCreate(input: $input) {
    draftOrder {
      id
    }
  }
}

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2024-07/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation draftOrderCreate($input: DraftOrderInput!) { draftOrderCreate(input: $input) { draftOrder { id } } }",
 "variables": {
    "input": {
      "customerId": "gid://shopify/Customer/544365967",
      "note": "Test draft order",
      "email": "test.user@shopify.com",
      "taxExempt": true,
      "tags": [
        "foo",
        "bar"
      ],
      "shippingLine": {
        "title": "Custom Shipping",
        "price": 4.55
      },
      "shippingAddress": {
        "address1": "123 Main St",
        "city": "Waterloo",
        "province": "Ontario",
        "country": "Canada",
        "zip": "A1A 1A1"
      },
      "billingAddress": {
        "address1": "456 Main St",
        "city": "Toronto",
        "province": "Ontario",
        "country": "Canada",
        "zip": "Z9Z 9Z9"
      },
      "appliedDiscount": {
        "description": "damaged",
        "value": 5.0,
        "amount": 5.0,
        "valueType": "FIXED_AMOUNT",
        "title": "Custom"
      },
      "lineItems": [
        {
          "title": "Custom product",
          "originalUnitPrice": 14.99,
          "quantity": 5,
          "appliedDiscount": {
            "description": "wholesale",
            "value": 5.0,
            "amount": 3.74,
            "valueType": "PERCENTAGE",
            "title": "Fancy"
          },
          "weight": {
            "value": 1,
            "unit": "KILOGRAMS"
          },
          "customAttributes": [
            {
              "key": "color",
              "value": "Gold"
            },
            {
              "key": "material",
              "value": "Plastic"
            }
          ]
        },
        {
          "variantId": "gid://shopify/ProductVariant/43729076",
          "quantity": 2
        }
      ],
      "customAttributes": [
        {
          "key": "name",
          "value": "Achilles"
        },
        {
          "key": "city",
          "value": "Troy"
        }
      ]
    }
  }
}'

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(
  `#graphql
  mutation draftOrderCreate($input: DraftOrderInput!) {
    draftOrderCreate(input: $input) {
      draftOrder {
        id
      }
    }
  }`,
  {
    variables: {
      "input": {
        "customerId": "gid://shopify/Customer/544365967",
        "note": "Test draft order",
        "email": "test.user@shopify.com",
        "taxExempt": true,
        "tags": [
          "foo",
          "bar"
        ],
        "shippingLine": {
          "title": "Custom Shipping",
          "price": 4.55
        },
        "shippingAddress": {
          "address1": "123 Main St",
          "city": "Waterloo",
          "province": "Ontario",
          "country": "Canada",
          "zip": "A1A 1A1"
        },
        "billingAddress": {
          "address1": "456 Main St",
          "city": "Toronto",
          "province": "Ontario",
          "country": "Canada",
          "zip": "Z9Z 9Z9"
        },
        "appliedDiscount": {
          "description": "damaged",
          "value": 5.0,
          "amount": 5.0,
          "valueType": "FIXED_AMOUNT",
          "title": "Custom"
        },
        "lineItems": [
          {
            "title": "Custom product",
            "originalUnitPrice": 14.99,
            "quantity": 5,
            "appliedDiscount": {
              "description": "wholesale",
              "value": 5.0,
              "amount": 3.74,
              "valueType": "PERCENTAGE",
              "title": "Fancy"
            },
            "weight": {
              "value": 1,
              "unit": "KILOGRAMS"
            },
            "customAttributes": [
              {
                "key": "color",
                "value": "Gold"
              },
              {
                "key": "material",
                "value": "Plastic"
              }
            ]
          },
          {
            "variantId": "gid://shopify/ProductVariant/43729076",
            "quantity": 2
          }
        ],
        "customAttributes": [
          {
            "key": "name",
            "value": "Achilles"
          },
          {
            "key": "city",
            "value": "Troy"
          }
        ]
      }
    },
  },
);

const data = await response.json();

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation draftOrderCreate($input: DraftOrderInput!) {
      draftOrderCreate(input: $input) {
        draftOrder {
          id
        }
      }
    }`,
    "variables": {
      "input": {
        "customerId": "gid://shopify/Customer/544365967",
        "note": "Test draft order",
        "email": "test.user@shopify.com",
        "taxExempt": true,
        "tags": [
          "foo",
          "bar"
        ],
        "shippingLine": {
          "title": "Custom Shipping",
          "price": 4.55
        },
        "shippingAddress": {
          "address1": "123 Main St",
          "city": "Waterloo",
          "province": "Ontario",
          "country": "Canada",
          "zip": "A1A 1A1"
        },
        "billingAddress": {
          "address1": "456 Main St",
          "city": "Toronto",
          "province": "Ontario",
          "country": "Canada",
          "zip": "Z9Z 9Z9"
        },
        "appliedDiscount": {
          "description": "damaged",
          "value": 5.0,
          "amount": 5.0,
          "valueType": "FIXED_AMOUNT",
          "title": "Custom"
        },
        "lineItems": [
          {
            "title": "Custom product",
            "originalUnitPrice": 14.99,
            "quantity": 5,
            "appliedDiscount": {
              "description": "wholesale",
              "value": 5.0,
              "amount": 3.74,
              "valueType": "PERCENTAGE",
              "title": "Fancy"
            },
            "weight": {
              "value": 1,
              "unit": "KILOGRAMS"
            },
            "customAttributes": [
              {
                "key": "color",
                "value": "Gold"
              },
              {
                "key": "material",
                "value": "Plastic"
              }
            ]
          },
          {
            "variantId": "gid://shopify/ProductVariant/43729076",
            "quantity": 2
          }
        ],
        "customAttributes": [
          {
            "key": "name",
            "value": "Achilles"
          },
          {
            "key": "city",
            "value": "Troy"
          }
        ]
      }
    },
  },
});

session = ShopifyAPI::Auth::Session.new(
  shop: "your-development-store.myshopify.com",
  access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session
)

query = <<~QUERY
  mutation draftOrderCreate($input: DraftOrderInput!) {
    draftOrderCreate(input: $input) {
      draftOrder {
        id
      }
    }
  }
QUERY

variables = {
  "input": {
    "customerId": "gid://shopify/Customer/544365967",
    "note": "Test draft order",
    "email": "test.user@shopify.com",
    "taxExempt": true,
    "tags": ["foo", "bar"],
    "shippingLine": {
      "title": "Custom Shipping",
      "price": 4.55
    },
    "shippingAddress": {
      "address1": "123 Main St",
      "city": "Waterloo",
      "province": "Ontario",
      "country": "Canada",
      "zip": "A1A 1A1"
    },
    "billingAddress": {
      "address1": "456 Main St",
      "city": "Toronto",
      "province": "Ontario",
      "country": "Canada",
      "zip": "Z9Z 9Z9"
    },
    "appliedDiscount": {
      "description": "damaged",
      "value": 5.0,
      "amount": 5.0,
      "valueType": "FIXED_AMOUNT",
      "title": "Custom"
    },
    "lineItems": [{"title"=>"Custom product", "originalUnitPrice"=>14.99, "quantity"=>5, "appliedDiscount"=>{"description"=>"wholesale", "value"=>5.0, "amount"=>3.74, "valueType"=>"PERCENTAGE", "title"=>"Fancy"}, "weight"=>{"value"=>1, "unit"=>"KILOGRAMS"}, "customAttributes"=>[{"key"=>"color", "value"=>"Gold"}, {"key"=>"material", "value"=>"Plastic"}]}, {"variantId"=>"gid://shopify/ProductVariant/43729076", "quantity"=>2}],
    "customAttributes": [{"key"=>"name", "value"=>"Achilles"}, {"key"=>"city", "value"=>"Troy"}]
  }
}

response = client.query(query: query, variables: variables)

Input variables

JSON

{

"input": {

"customerId": "gid://shopify/Customer/544365967",

"note": "Test draft order",

"email": "test.user@shopify.com",

"taxExempt": true,

"tags": [

"foo",

"bar"

"shippingLine": {

"title": "Custom Shipping",

"price": 4.55

"shippingAddress": {

"address1": "123 Main St",

"city": "Waterloo",

"province": "Ontario",

"country": "Canada",

"zip": "A1A 1A1"

"billingAddress": {

"address1": "456 Main St",

"city": "Toronto",

"province": "Ontario",

"country": "Canada",

"zip": "Z9Z 9Z9"

"appliedDiscount": {

"description": "damaged",

"value": 5,

"amount": 5,

"valueType": "FIXED_AMOUNT",

"title": "Custom"

"lineItems": [

{

"title": "Custom product",

"originalUnitPrice": 14.99,

"quantity": 5,

"appliedDiscount": {

"description": "wholesale",

"value": 5,

"amount": 3.74,

"valueType": "PERCENTAGE",

"title": "Fancy"

"weight": {

"value": 1,

"unit": "KILOGRAMS"

"customAttributes": [

{

"key": "color",

"value": "Gold"

{

"key": "material",

"value": "Plastic"

}

]

{

"variantId": "gid://shopify/ProductVariant/43729076",

"quantity": 2

}

"customAttributes": [

{

"key": "name",

"value": "Achilles"

{

"key": "city",

"value": "Troy"

}

]

}

Response

JSON

{

"draftOrderCreate": {

"draftOrder": {

"id": "gid://shopify/DraftOrder/1069920527"

}