draftOrderUpdate - admin-graphql - MUTATION

Version: 2024-04

Description:

Updates a draft order. If a checkout has been started for a draft order, any update to the draft will unlink the checkout. Checkouts are created but not immediately completed when opening the merchant credit card modal in the admin, and when a buyer opens the invoice URL. This is usually fine, but there is an edge case where a checkout is in progress and the draft is updated before the checkout completes. This will not interfere with the checkout and order creation, but if the link from draft to checkout is broken the draft will remain open even after the order is created.

Access Scopes

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

Arguments

• id: ID! - Specifies the draft order to update.
• input: DraftOrderInput! - The draft order properties to update.

Returns

• draftOrder: DraftOrder The updated draft order.
• userErrors: UserError! The list of errors that occurred from executing the mutation.

Examples

• Create a new metafield and update another on an existing draft order

          Curl example: "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/2024-04/graphql.json \\\n-H 'Content-Type: application/json' \\\n-H 'X-Shopify-Access-Token: {access_token}' \\\n-d '{\n\"query\": \"mutation updateDraftOrderMetafields($input: DraftOrderInput!, $ownerId: ID!) { draftOrderUpdate(input: $input, id: $ownerId) { draftOrder { id metafields(first: 3) { edges { node { id namespace key value } } } } userErrors { message field } } }\",\n \"variables\": {\n    \"input\": {\n      \"metafields\": [\n        {\n          \"namespace\": \"my_field\",\n          \"key\": \"delivery_instructions\",\n          \"type\": \"single_line_text_field\",\n          \"value\": \"leave on back porch\"\n        },\n        {\n          \"id\": \"gid://shopify/Metafield/1069229059\",\n          \"value\": \"123\"\n        }\n      ]\n    },\n    \"ownerId\": \"gid://shopify/DraftOrder/276395349\"\n  }\n}'\n"
          Node example: "const client = new shopify.clients.Graphql({session});\nconst data = await client.query({\n  data: {\n    \"query\": `mutation updateDraftOrderMetafields($input: DraftOrderInput!, $ownerId: ID!) {\n      draftOrderUpdate(input: $input, id: $ownerId) {\n        draftOrder {\n          id\n          metafields(first: 3) {\n            edges {\n              node {\n                id\n                namespace\n                key\n                value\n              }\n            }\n          }\n        }\n        userErrors {\n          message\n          field\n        }\n      }\n    }`,\n    \"variables\": {\n      \"input\": {\n        \"metafields\": [\n          {\n            \"namespace\": \"my_field\",\n            \"key\": \"delivery_instructions\",\n            \"type\": \"single_line_text_field\",\n            \"value\": \"leave on back porch\"\n          },\n          {\n            \"id\": \"gid://shopify/Metafield/1069229059\",\n            \"value\": \"123\"\n          }\n        ]\n      },\n      \"ownerId\": \"gid://shopify/DraftOrder/276395349\"\n    },\n  },\n});\n"
          Ruby example: "session = ShopifyAPI::Auth::Session.new(\n  shop: \"your-development-store.myshopify.com\",\n  access_token: access_token\n)\nclient = ShopifyAPI::Clients::Graphql::Admin.new(\n  session: session\n)\n\nquery = <<~QUERY\n  mutation updateDraftOrderMetafields($input: DraftOrderInput!, $ownerId: ID!) {\n    draftOrderUpdate(input: $input, id: $ownerId) {\n      draftOrder {\n        id\n        metafields(first: 3) {\n          edges {\n            node {\n              id\n              namespace\n              key\n              value\n            }\n          }\n        }\n      }\n      userErrors {\n        message\n        field\n      }\n    }\n  }\nQUERY\n\nvariables = {\n  \"input\": {\n    \"metafields\": [{\"namespace\"=>\"my_field\", \"key\"=>\"delivery_instructions\", \"type\"=>\"single_line_text_field\", \"value\"=>\"leave on back porch\"}, {\"id\"=>\"gid://shopify/Metafield/1069229059\", \"value\"=>\"123\"}]\n  },\n  \"ownerId\": \"gid://shopify/DraftOrder/276395349\"\n}\n\nresponse = client.query(query: query, variables: variables)\n"
          PHP example: "use Shopify\\Clients\\Graphql;\n\n$client = new Graphql(\"your-development-store.myshopify.com\", $accessToken);\n$query = <<<QUERY\n  mutation updateDraftOrderMetafields($input: DraftOrderInput!, $ownerId: ID!) {\n    draftOrderUpdate(input: $input, id: $ownerId) {\n      draftOrder {\n        id\n        metafields(first: 3) {\n          edges {\n            node {\n              id\n              namespace\n              key\n              value\n            }\n          }\n        }\n      }\n      userErrors {\n        message\n        field\n      }\n    }\n  }\nQUERY;\n\n$variables = [\n  \"input\" => [\n    \"metafields\" => [{\"namespace\"=>\"my_field\", \"key\"=>\"delivery_instructions\", \"type\"=>\"single_line_text_field\", \"value\"=>\"leave on back porch\"}, {\"id\"=>\"gid://shopify/Metafield/1069229059\", \"value\"=>\"123\"}],\n  ],\n  \"ownerId\" => \"gid://shopify/DraftOrder/276395349\",\n];\n\n$response = $client->query([\"query\" => $query, \"variables\" => $variables]);\n"
          Remix example: "const { admin } = await authenticate.admin(request);\n\nconst response = await admin.graphql(\n  `#graphql\n  mutation updateDraftOrderMetafields($input: DraftOrderInput!, $ownerId: ID!) {\n    draftOrderUpdate(input: $input, id: $ownerId) {\n      draftOrder {\n        id\n        metafields(first: 3) {\n          edges {\n            node {\n              id\n              namespace\n              key\n              value\n            }\n          }\n        }\n      }\n      userErrors {\n        message\n        field\n      }\n    }\n  }`,\n  {\n    variables: {\n      \"input\": {\n        \"metafields\": [\n          {\n            \"namespace\": \"my_field\",\n            \"key\": \"delivery_instructions\",\n            \"type\": \"single_line_text_field\",\n            \"value\": \"leave on back porch\"\n          },\n          {\n            \"id\": \"gid://shopify/Metafield/1069229059\",\n            \"value\": \"123\"\n          }\n        ]\n      },\n      \"ownerId\": \"gid://shopify/DraftOrder/276395349\"\n    },\n  },\n);\n\nconst data = await response.json();\n"
          Graphql query: "mutation updateDraftOrderMetafields($input: DraftOrderInput!, $ownerId: ID!) {\n  draftOrderUpdate(input: $input, id: $ownerId) {\n    draftOrder {\n      id\n      metafields(first: 3) {\n        edges {\n          node {\n            id\n            namespace\n            key\n            value\n          }\n        }\n      }\n    }\n    userErrors {\n      message\n      field\n    }\n  }\n}"
        

  input: {
    "input": {
      "metafields": [
        {
          "namespace": "my_field",
          "key": "delivery_instructions",
          "type": "single_line_text_field",
          "value": "leave on back porch"
        },
        {
          "id": "gid://shopify/Metafield/1069229059",
          "value": "123"
        }
      ]
    },
    "ownerId": "gid://shopify/DraftOrder/276395349"
  }

  response: {
    "data": {
      "draftOrderUpdate": {
        "draftOrder": {
          "id": "gid://shopify/DraftOrder/276395349",
          "metafields": {
            "edges": [
              {
                "node": {
                  "id": "gid://shopify/Metafield/1069229059",
                  "namespace": "my_fields",
                  "key": "purchase_order",
                  "value": "123"
                }
              },
              {
                "node": {
                  "id": "gid://shopify/Metafield/1069229060",
                  "namespace": "my_field",
                  "key": "delivery_instructions",
                  "value": "leave on back porch"
                }
              }
            ]
          }
        },
        "userErrors": []
      }
    }
  }

  Update the draft order shipping address

          Curl example: "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/2024-04/graphql.json \\\n-H 'Content-Type: application/json' \\\n-H 'X-Shopify-Access-Token: {access_token}' \\\n-d '{\n\"query\": \"mutation draftOrderUpdate($id: ID!, $input: DraftOrderInput!) { draftOrderUpdate(id: $id, input: $input) { draftOrder { shippingAddress { id } } } }\",\n \"variables\": {\n    \"id\": \"gid://shopify/DraftOrder/276395349\",\n    \"input\": {\n      \"shippingAddress\": {\n        \"address1\": \"123 shipping ave\",\n        \"city\": \"Ottawa\",\n        \"provinceCode\": \"ON\",\n        \"zip\": \"K1L 2J3\",\n        \"country\": \"Canada\"\n      }\n    }\n  }\n}'\n"
          Node example: "const client = new shopify.clients.Graphql({session});\nconst data = await client.query({\n  data: {\n    \"query\": `mutation draftOrderUpdate($id: ID!, $input: DraftOrderInput!) {\n      draftOrderUpdate(id: $id, input: $input) {\n        draftOrder {\n          shippingAddress {\n            id\n          }\n        }\n      }\n    }`,\n    \"variables\": {\n      \"id\": \"gid://shopify/DraftOrder/276395349\",\n      \"input\": {\n        \"shippingAddress\": {\n          \"address1\": \"123 shipping ave\",\n          \"city\": \"Ottawa\",\n          \"provinceCode\": \"ON\",\n          \"zip\": \"K1L 2J3\",\n          \"country\": \"Canada\"\n        }\n      }\n    },\n  },\n});\n"
          Ruby example: "session = ShopifyAPI::Auth::Session.new(\n  shop: \"your-development-store.myshopify.com\",\n  access_token: access_token\n)\nclient = ShopifyAPI::Clients::Graphql::Admin.new(\n  session: session\n)\n\nquery = <<~QUERY\n  mutation draftOrderUpdate($id: ID!, $input: DraftOrderInput!) {\n    draftOrderUpdate(id: $id, input: $input) {\n      draftOrder {\n        shippingAddress {\n          id\n        }\n      }\n    }\n  }\nQUERY\n\nvariables = {\n  \"id\": \"gid://shopify/DraftOrder/276395349\",\n  \"input\": {\n    \"shippingAddress\": {\n      \"address1\": \"123 shipping ave\",\n      \"city\": \"Ottawa\",\n      \"provinceCode\": \"ON\",\n      \"zip\": \"K1L 2J3\",\n      \"country\": \"Canada\"\n    }\n  }\n}\n\nresponse = client.query(query: query, variables: variables)\n"
          PHP example: "use Shopify\\Clients\\Graphql;\n\n$client = new Graphql(\"your-development-store.myshopify.com\", $accessToken);\n$query = <<<QUERY\n  mutation draftOrderUpdate($id: ID!, $input: DraftOrderInput!) {\n    draftOrderUpdate(id: $id, input: $input) {\n      draftOrder {\n        shippingAddress {\n          id\n        }\n      }\n    }\n  }\nQUERY;\n\n$variables = [\n  \"id\" => \"gid://shopify/DraftOrder/276395349\",\n  \"input\" => [\n    \"shippingAddress\" => [\n      \"address1\" => \"123 shipping ave\",\n      \"city\" => \"Ottawa\",\n      \"provinceCode\" => \"ON\",\n      \"zip\" => \"K1L 2J3\",\n      \"country\" => \"Canada\",\n    ],\n  ],\n];\n\n$response = $client->query([\"query\" => $query, \"variables\" => $variables]);\n"
          Remix example: "const { admin } = await authenticate.admin(request);\n\nconst response = await admin.graphql(\n  `#graphql\n  mutation draftOrderUpdate($id: ID!, $input: DraftOrderInput!) {\n    draftOrderUpdate(id: $id, input: $input) {\n      draftOrder {\n        shippingAddress {\n          id\n        }\n      }\n    }\n  }`,\n  {\n    variables: {\n      \"id\": \"gid://shopify/DraftOrder/276395349\",\n      \"input\": {\n        \"shippingAddress\": {\n          \"address1\": \"123 shipping ave\",\n          \"city\": \"Ottawa\",\n          \"provinceCode\": \"ON\",\n          \"zip\": \"K1L 2J3\",\n          \"country\": \"Canada\"\n        }\n      }\n    },\n  },\n);\n\nconst data = await response.json();\n"
          Graphql query: "mutation draftOrderUpdate($id: ID!, $input: DraftOrderInput!) {\n  draftOrderUpdate(id: $id, input: $input) {\n    draftOrder {\n      shippingAddress {\n        id\n      }\n    }\n  }\n}"
        

  input: {
    "id": "gid://shopify/DraftOrder/276395349",
    "input": {
      "shippingAddress": {
        "address1": "123 shipping ave",
        "city": "Ottawa",
        "provinceCode": "ON",
        "zip": "K1L 2J3",
        "country": "Canada"
      }
    }
  }

  response: {
    "data": {
      "draftOrderUpdate": {
        "draftOrder": {
          "shippingAddress": {
            "id": "gid://shopify/MailingAddress/639215345?model_name=Address"
          }
        }
      }
    }
  }

  Updating a draft order that doesn't exist returns an error

          Curl example: "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/2024-04/graphql.json \\\n-H 'Content-Type: application/json' \\\n-H 'X-Shopify-Access-Token: {access_token}' \\\n-d '{\n\"query\": \"mutation draftOrderUpdate($id: ID!, $input: DraftOrderInput!) { draftOrderUpdate(id: $id, input: $input) { draftOrder { id } userErrors { message field } } }\",\n \"variables\": {\n    \"id\": \"gid://shopify/DraftOrder/1\",\n    \"input\": {\n      \"note\": \"This is a really awesome draft order\"\n    }\n  }\n}'\n"
          Node example: "const client = new shopify.clients.Graphql({session});\nconst data = await client.query({\n  data: {\n    \"query\": `mutation draftOrderUpdate($id: ID!, $input: DraftOrderInput!) {\n      draftOrderUpdate(id: $id, input: $input) {\n        draftOrder {\n          id\n        }\n        userErrors {\n          message\n          field\n        }\n      }\n    }`,\n    \"variables\": {\n      \"id\": \"gid://shopify/DraftOrder/1\",\n      \"input\": {\n        \"note\": \"This is a really awesome draft order\"\n      }\n    },\n  },\n});\n"
          Ruby example: "session = ShopifyAPI::Auth::Session.new(\n  shop: \"your-development-store.myshopify.com\",\n  access_token: access_token\n)\nclient = ShopifyAPI::Clients::Graphql::Admin.new(\n  session: session\n)\n\nquery = <<~QUERY\n  mutation draftOrderUpdate($id: ID!, $input: DraftOrderInput!) {\n    draftOrderUpdate(id: $id, input: $input) {\n      draftOrder {\n        id\n      }\n      userErrors {\n        message\n        field\n      }\n    }\n  }\nQUERY\n\nvariables = {\n  \"id\": \"gid://shopify/DraftOrder/1\",\n  \"input\": {\n    \"note\": \"This is a really awesome draft order\"\n  }\n}\n\nresponse = client.query(query: query, variables: variables)\n"
          PHP example: "use Shopify\\Clients\\Graphql;\n\n$client = new Graphql(\"your-development-store.myshopify.com\", $accessToken);\n$query = <<<QUERY\n  mutation draftOrderUpdate($id: ID!, $input: DraftOrderInput!) {\n    draftOrderUpdate(id: $id, input: $input) {\n      draftOrder {\n        id\n      }\n      userErrors {\n        message\n        field\n      }\n    }\n  }\nQUERY;\n\n$variables = [\n  \"id\" => \"gid://shopify/DraftOrder/1\",\n  \"input\" => [\n    \"note\" => \"This is a really awesome draft order\",\n  ],\n];\n\n$response = $client->query([\"query\" => $query, \"variables\" => $variables]);\n"
          Remix example: "const { admin } = await authenticate.admin(request);\n\nconst response = await admin.graphql(\n  `#graphql\n  mutation draftOrderUpdate($id: ID!, $input: DraftOrderInput!) {\n    draftOrderUpdate(id: $id, input: $input) {\n      draftOrder {\n        id\n      }\n      userErrors {\n        message\n        field\n      }\n    }\n  }`,\n  {\n    variables: {\n      \"id\": \"gid://shopify/DraftOrder/1\",\n      \"input\": {\n        \"note\": \"This is a really awesome draft order\"\n      }\n    },\n  },\n);\n\nconst data = await response.json();\n"
          Graphql query: "mutation draftOrderUpdate($id: ID!, $input: DraftOrderInput!) {\n  draftOrderUpdate(id: $id, input: $input) {\n    draftOrder {\n      id\n    }\n    userErrors {\n      message\n      field\n    }\n  }\n}"
        

  input: {
    "id": "gid://shopify/DraftOrder/1",
    "input": {
      "note": "This is a really awesome draft order"
    }
  }

  response: {
    "data": {
      "draftOrderUpdate": {
        "draftOrder": null,
        "userErrors": [
          {
            "message": "Draft order not found",
            "field": null
          }
        ]
      }
    }
  }

  Updating a draft order with a company, location and company contact

          Curl example: "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/2024-04/graphql.json \\\n-H 'Content-Type: application/json' \\\n-H 'X-Shopify-Access-Token: {access_token}' \\\n-d '{\n\"query\": \"mutation draftOrderUpdate($id: ID!, $input: DraftOrderInput!) { draftOrderUpdate(id: $id, input: $input) { draftOrder { purchasingEntity { ... on PurchasingCompany { company { id } } } } } }\",\n \"variables\": {\n    \"id\": \"gid://shopify/DraftOrder/276395349\",\n    \"input\": {\n      \"purchasingEntity\": {\n        \"purchasingCompany\": {\n          \"companyId\": \"gid://shopify/Company/426793626\",\n          \"companyLocationId\": \"gid://shopify/CompanyLocation/441870438\",\n          \"companyContactId\": \"gid://shopify/CompanyContact/207808057\"\n        }\n      }\n    }\n  }\n}'\n"
          Node example: "const client = new shopify.clients.Graphql({session});\nconst data = await client.query({\n  data: {\n    \"query\": `mutation draftOrderUpdate($id: ID!, $input: DraftOrderInput!) {\n      draftOrderUpdate(id: $id, input: $input) {\n        draftOrder {\n          purchasingEntity {\n            ... on PurchasingCompany {\n              company {\n                id\n              }\n            }\n          }\n        }\n      }\n    }`,\n    \"variables\": {\n      \"id\": \"gid://shopify/DraftOrder/276395349\",\n      \"input\": {\n        \"purchasingEntity\": {\n          \"purchasingCompany\": {\n            \"companyId\": \"gid://shopify/Company/426793626\",\n            \"companyLocationId\": \"gid://shopify/CompanyLocation/441870438\",\n            \"companyContactId\": \"gid://shopify/CompanyContact/207808057\"\n          }\n        }\n      }\n    },\n  },\n});\n"
          Ruby example: "session = ShopifyAPI::Auth::Session.new(\n  shop: \"your-development-store.myshopify.com\",\n  access_token: access_token\n)\nclient = ShopifyAPI::Clients::Graphql::Admin.new(\n  session: session\n)\n\nquery = <<~QUERY\n  mutation draftOrderUpdate($id: ID!, $input: DraftOrderInput!) {\n    draftOrderUpdate(id: $id, input: $input) {\n      draftOrder {\n        purchasingEntity {\n          ... on PurchasingCompany {\n            company {\n              id\n            }\n          }\n        }\n      }\n    }\n  }\nQUERY\n\nvariables = {\n  \"id\": \"gid://shopify/DraftOrder/276395349\",\n  \"input\": {\n    \"purchasingEntity\": {\n      \"purchasingCompany\": {\n        \"companyId\": \"gid://shopify/Company/426793626\",\n        \"companyLocationId\": \"gid://shopify/CompanyLocation/441870438\",\n        \"companyContactId\": \"gid://shopify/CompanyContact/207808057\"\n      }\n    }\n  }\n}\n\nresponse = client.query(query: query, variables: variables)\n"
          PHP example: "use Shopify\\Clients\\Graphql;\n\n$client = new Graphql(\"your-development-store.myshopify.com\", $accessToken);\n$query = <<<QUERY\n  mutation draftOrderUpdate($id: ID!, $input: DraftOrderInput!) {\n    draftOrderUpdate(id: $id, input: $input) {\n      draftOrder {\n        purchasingEntity {\n          ... on PurchasingCompany {\n            company {\n              id\n            }\n          }\n        }\n      }\n    }\n  }\nQUERY;\n\n$variables = [\n  \"id\" => \"gid://shopify/DraftOrder/276395349\",\n  \"input\" => [\n    \"purchasingEntity\" => [\n      \"purchasingCompany\" => [\n        \"companyId\" => \"gid://shopify/Company/426793626\",\n        \"companyLocationId\" => \"gid://shopify/CompanyLocation/441870438\",\n        \"companyContactId\" => \"gid://shopify/CompanyContact/207808057\",\n      ],\n    ],\n  ],\n];\n\n$response = $client->query([\"query\" => $query, \"variables\" => $variables]);\n"
          Remix example: "const { admin } = await authenticate.admin(request);\n\nconst response = await admin.graphql(\n  `#graphql\n  mutation draftOrderUpdate($id: ID!, $input: DraftOrderInput!) {\n    draftOrderUpdate(id: $id, input: $input) {\n      draftOrder {\n        purchasingEntity {\n          ... on PurchasingCompany {\n            company {\n              id\n            }\n          }\n        }\n      }\n    }\n  }`,\n  {\n    variables: {\n      \"id\": \"gid://shopify/DraftOrder/276395349\",\n      \"input\": {\n        \"purchasingEntity\": {\n          \"purchasingCompany\": {\n            \"companyId\": \"gid://shopify/Company/426793626\",\n            \"companyLocationId\": \"gid://shopify/CompanyLocation/441870438\",\n            \"companyContactId\": \"gid://shopify/CompanyContact/207808057\"\n          }\n        }\n      }\n    },\n  },\n);\n\nconst data = await response.json();\n"
          Graphql query: "mutation draftOrderUpdate($id: ID!, $input: DraftOrderInput!) {\n  draftOrderUpdate(id: $id, input: $input) {\n    draftOrder {\n      purchasingEntity {\n        ... on PurchasingCompany {\n          company {\n            id\n          }\n        }\n      }\n    }\n  }\n}"
        

  input: {
    "id": "gid://shopify/DraftOrder/276395349",
    "input": {
      "purchasingEntity": {
        "purchasingCompany": {
          "companyId": "gid://shopify/Company/426793626",
          "companyLocationId": "gid://shopify/CompanyLocation/441870438",
          "companyContactId": "gid://shopify/CompanyContact/207808057"
        }
      }
    }
  }

  response: {
    "data": {
      "draftOrderUpdate": {
        "draftOrder": {
          "purchasingEntity": {
            "company": {
              "id": "gid://shopify/Company/426793626"
            }
          }
        }
      }
    }
  }