Skip to main content

createReturn

Requires permission sales:credit_note:create.

Records a return against a sales order (type SALES_RETURN, goods coming back from a customer) or a purchase order (type PURCHASE_RETURN, goods going back to a supplier). The return starts as PENDING and moves no stock until processReturn. A sales return needs an order whose goods have gone out: orders that are DRAFT, AWAITING_PAYMENT, CONFIRMED or CANCELLED are refused. Each line must name a variant and resolve to one line of the source order, and the quantity returned across all returns of that line cannot exceed what was ordered (sales) or received (purchase). The refund value comes from the original order line, not from a price you send. A purchase return needs the purchase returns feature on your plan and the debit note create permission as well.

Errors: a failed call returns a GraphQL errors entry, not a field on the result, and data may be null or partial. Read the entry's extensions.code and message; every shape and code is in the Error reference.

Example:

mutation CreateReturn($input: CreateReturnInput!) {
  createReturn(input: $input) {
    id
    returnNumber
    status
    type
    createdAt
    baseTotalAmount
    creditNotes {
      id
      creditNoteNumber
      status
      type
      amount
      issueDate
    }
  }
}

Variables:

{
  "input": {
    "items": [
      {
        "condition": "DAMAGED",
        "productId": "string",
        "quantity": 0,
        "unitPrice": 0,
        "variantId": "string"
      }
    ],
    "originalOrderId": "string",
    "reason": "DAMAGED",
    "type": "DEFECTIVE_RETURN",
    "warehouseId": "string"
  }
}

Response:

{
  "data": {
    "createReturn": {
      "id": "id",
      "returnNumber": "string",
      "status": "APPROVED",
      "type": "DEFECTIVE_RETURN",
      "createdAt": "2025-01-15T00:00:00Z",
      "baseTotalAmount": 0,
      "creditNotes": [
        {
          "id": "id",
          "creditNoteNumber": "string",
          "status": "string",
          "type": "string",
          "amount": 0,
          "issueDate": "2025-01-15T00:00:00Z"
        }
      ]
    }
  }
}
createReturn(
  input: CreateReturnInput!
): ProductReturn!

Arguments​

createReturn.input ● CreateReturnInput! non-null input​

The details of the return to create.

Type​

ProductReturn object​

A return of goods, sales or purchase side, with its lines and the notes raised from it.