Ctrl K

Create Return

Published today

Open an approved return for fulfilled items of an order.

Script shopify Verified

Use in Windmill

The script

Submitted by hugo989 Typescript (fetch-only)

Verified 2 hours ago

All edits

Permalink

//native

/**
 * Create Return
 * Open a return on a fulfilled order, already approved (unlike a customer return request). return_line_items take the fulfillment line item ids from the order's fulfillments (Get Fulfillment), a quantity and a return reason definition id (default 1 Unknown; 2 Changed my mind, 3 Not as described, 4 Wrong item, 5 Other, 6 Damaged or defective, 7 Too small, 8 Too big; full library via the returnReasonDefinitions query). Returns the return with its line item ids, to pass to Process Return. Needs the write_returns scope.
 */
export async function main(
  auth: RT.Shopify,
  order_id: string,
  return_line_items: {
    fulfillment_line_item_id: string
    quantity: number
    return_reason_definition_id?: string
    return_reason_note?: string
  }[]
) {
  const response = await fetch(
    `https://${auth.store_name}.myshopify.com/admin/api/2026-10/graphql.json`,
    {
      method: "POST",
      headers: {
        "X-Shopify-Access-Token": auth.token,
        "Content-Type": "application/json",
        Accept: "application/json",
      },
      body: JSON.stringify({
        query: `mutation ($returnInput: ReturnInput!) { returnCreate(returnInput: $returnInput) { return { id name status createdAt totalQuantity order { id name } returnLineItems(first: 50) { nodes { id quantity returnReasonNote ... on ReturnLineItem { fulfillmentLineItem { id lineItem { id name } } } } } } userErrors { field message code } } }`,
        variables: {
          returnInput: {
            orderId: order_id.startsWith("gid://")
              ? order_id
              : `gid://shopify/Order/${order_id}`,
            returnLineItems: return_line_items.map((li) => ({
              fulfillmentLineItemId: li.fulfillment_line_item_id.startsWith(
                "gid://"
              )
                ? li.fulfillment_line_item_id
                : `gid://shopify/FulfillmentLineItem/${li.fulfillment_line_item_id}`,
              quantity: li.quantity,
              returnReasonDefinitionId: `gid://shopify/ReturnReasonDefinition/${(li.return_reason_definition_id || "1").replace("gid://shopify/ReturnReasonDefinition/", "")}`,
              returnReasonNote: li.return_reason_note || undefined,
            })),
          },
        },
      }),
    }
  )

  if (!response.ok) {
    throw new Error(`${response.status} ${await response.text()}`)
  }

  const { data, errors } = await response.json()
  if (errors) {
    throw new Error(JSON.stringify(errors))
  }

  if (data.returnCreate.userErrors.length) {
    throw new Error(JSON.stringify(data.returnCreate.userErrors))
  }

  return data.returnCreate
}


`1`	`//native`
`2`
`3`	`/**`
`4`	`* Create Return`
`5`	* Open a return on a fulfilled order, already approved (unlike a customer return request). return_line_items take the fulfillment line item ids from the order's fulfillments (Get Fulfillment), a quantity and a return reason definition id (default 1 Unknown; 2 Changed my mind, 3 Not as described, 4 Wrong item, 5 Other, 6 Damaged or defective, 7 Too small, 8 Too big; full library via the returnReasonDefinitions query). Returns the return with its line item ids, to pass to Process Return. Needs the write_returns scope.
`6`	`*/`
`7`	`export async function main(`
`8`	`auth: RT.Shopify,`
`9`	`order_id: string,`
`10`	`return_line_items: {`
`11`	`fulfillment_line_item_id: string`
`12`	`quantity: number`
`13`	`return_reason_definition_id?: string`
`14`	`return_reason_note?: string`
`15`	`}[]`
`16`	`) {`
`17`	`const response = await fetch(`
`18`	`https://${auth.store_name}.myshopify.com/admin/api/2026-10/graphql.json`,
`19`	`{`
`20`	`method: "POST",`
`21`	`headers: {`
`22`	`"X-Shopify-Access-Token": auth.token,`
`23`	`"Content-Type": "application/json",`
`24`	`Accept: "application/json",`
`25`	`},`
`26`	`body: JSON.stringify({`
`27`	query: `mutation ($returnInput: ReturnInput!) { returnCreate(returnInput: $returnInput) { return { id name status createdAt totalQuantity order { id name } returnLineItems(first: 50) { nodes { id quantity returnReasonNote ... on ReturnLineItem { fulfillmentLineItem { id lineItem { id name } } } } } } userErrors { field message code } } }`,
`28`	`variables: {`
`29`	`returnInput: {`
`30`	`orderId: order_id.startsWith("gid://")`
`31`	`? order_id`
`32`	: `gid://shopify/Order/${order_id}`,
`33`	`returnLineItems: return_line_items.map((li) => ({`
`34`	`fulfillmentLineItemId: li.fulfillment_line_item_id.startsWith(`
`35`	`"gid://"`
`36`	`)`
`37`	`? li.fulfillment_line_item_id`
`38`	: `gid://shopify/FulfillmentLineItem/${li.fulfillment_line_item_id}`,
`39`	`quantity: li.quantity,`
`40`	returnReasonDefinitionId: `gid://shopify/ReturnReasonDefinition/${(li.return_reason_definition_id \|\| "1").replace("gid://shopify/ReturnReasonDefinition/", "")}`,
`41`	`returnReasonNote: li.return_reason_note \|\| undefined,`
`42`	`})),`
`43`	`},`
`44`	`},`
`45`	`}),`
`46`	`}`
`47`	`)`
`48`
`49`	`if (!response.ok) {`
`50`	throw new Error(`${response.status} ${await response.text()}`)
`51`	`}`
`52`
`53`	`const { data, errors } = await response.json()`
`54`	`if (errors) {`
`55`	`throw new Error(JSON.stringify(errors))`
`56`	`}`
`57`
`58`	`if (data.returnCreate.userErrors.length) {`
`59`	`throw new Error(JSON.stringify(data.returnCreate.userErrors))`
`60`	`}`
`61`
`62`	`return data.returnCreate`
`63`	`}`
`64`