Goods receipts

Use goods receipt operations when a merchant integration needs to receive products into a warehouse and connect the receipt to supplier orders.

Available operations

• List goods receipts with goodsReceipts, or load one by global ID with goodsReceipt.
• List goods receipt line items with goodsReceiptLineItems, or load one by global ID with goodsReceiptLineItem.
• Create a goods receipt with createGoodsReceipt.
• Approve a goods receipt in state created with approveGoodsReceipt.
• Stock a goods receipt into its warehouse and complete it with completeGoodsReceipt.
• Delete a goods receipt in state draft, created or approved with deleteGoodsReceipt.
• Add a line item to a free goods receipt with addGoodsReceiptLineItem, and remove one with removeGoodsReceiptLineItem.
• Split a line item into two with splitGoodsReceiptLineItem.
• Change the warehouse the goods are booked into with updateGoodsReceiptWarehouse.

Lifecycle and stock

A goods receipt moves through the states draft, created, approved, in_progress and completed, and its state field carries that technical name. When stock is booked depends on the state:

• createGoodsReceipt creates the receipt in state created. No stock is booked yet.
• approveGoodsReceipt moves a created receipt to approved and books the received quantities onto the goods receipt itself: the stock exists from now on, but it is not in the warehouse yet. Approving a receipt of type Supplier also moves the supplier orders its lines are received against to partially_delivered or delivered.
• completeGoodsReceipt stocks the goods from the receipt into its warehouse and moves the receipt to completed. It accepts a receipt in created, approved or in_progress and approves a created one first, so one call takes a fresh receipt all the way to completed.

A receipt in draft is still being captured in Pickware; no mutation moves it on.

Example: receive a supplier delivery

mutation ReceiveDelivery($input: CreateGoodsReceiptInput!) {
  createGoodsReceipt(input: $input) {
    id
    number
    type
    state
    warehouse {
      code
    }
  }
}

{
  "input": {
    "warehouseId": "V2FyZWhvdXNlOjAx...",
    "supplierId": "U3VwcGxpZXI6MDE4...",
    "lineItems": [
      {
        "productId": "UHJvZHVjdDow...",
        "quantity": 24,
        "supplierOrderId": "U3VwcGxpZXJPcmRlcjow..."
      }
    ]
  }
}

The receipt is of type Supplier only when supplierId is passed — pass the supplier of the orders you receive against. Without it the receipt is a free goods receipt (type Free), even when its lines name supplier orders, and it never moves those supplier orders to partially_delivered or delivered. A quantity counts toward a supplier order's delivery only on a line that names the order in supplierOrderId; supplierOrderIds links further supplier orders to the receipt without receiving anything against them.

The result is in state created. Stock the goods and complete the receipt in one call:

mutation CompleteGoodsReceipt($id: ID!) {
  completeGoodsReceipt(id: $id) {
    id
    state
  }
}

Example: correct a goods receipt

A receipt does not have to be deleted and recreated when the delivery turns out to differ from what was booked. Line items can be added to and removed from a free goods receipt while it is in state draft or created, a line of any goods receipt can be split for as long as the receipt is not completed yet, and the warehouse can be changed until the receipt is part of a stock valuation report.

mutation AddLine($input: AddGoodsReceiptLineItemInput!) {
  addGoodsReceiptLineItem(input: $input) {
    id
    lineItems(first: 50) {
      edges {
        node {
          id
          productId
          quantity
          unitPrice
        }
      }
    }
  }
}

Every one of these mutations returns the updated goods receipt, so no follow-up query is needed. Select lineItems on the result to get the refreshed list back in the same call; updateGoodsReceiptWarehouse leaves the lines untouched.

Splitting takes the quantity for the newly created line item; the original line keeps the remainder, so the received total stays the same:

mutation SplitLine($id: ID!, $newLineItemQuantity: Int!) {
  splitGoodsReceiptLineItem(id: $id, newLineItemQuantity: $newLineItemQuantity) {
    id
    lineItems(first: 50) {
      edges {
        node {
          id
          quantity
        }
      }
    }
  }
}

Adding and removing line items only applies to free goods receipts: on a receipt of type Supplier or Customer the API rejects the mutation.