Purchase Receipt Builder - Nioron07/Easy-Acumatica GitHub Wiki

This guide covers the PurchaseReceiptBuilder, which is your primary tool for creating the JSON payload needed to create PurchaseReceipt records with the PurchaseReceiptsService.

1. Importing the PurchaseReceiptBuilder

To get started, import the PurchaseReceiptBuilder from the models directory.

from easy_acumatica.models.purchase_receipt_builder import PurchaseReceiptBuilder

2. Understanding the Builder's Purpose

When you send data to Acumatica's contract-based API, each field must be wrapped in a specific JSON structure, such as {"value": ...}. The PurchaseReceiptBuilder handles this formatting for you automatically, allowing you to construct a valid payload for a new purchase receipt using a fluent, chainable interface. It supports various receipt types, including standard receipts, returns, and transfers.

3. PurchaseReceiptBuilder Methods

The following table summarizes the primary methods available in the PurchaseReceiptBuilder.

Method	Description	Parameters
.set()	Sets any top-level field on the purchase receipt.	field (str), value (Any)
.type()	(Required) Sets the Type ('Receipt', 'Return', etc.).	type (str)
.vendor_id()	Sets the VendorID.	id (str)
.hold()	Sets the Hold status.	hold (bool)
.create_bill()	Sets the CreateBill flag.	create_bill (bool)
.add_detail_from_po()	Adds a detail line linked to a Purchase Order.	po_order_nbr, po_order_type, **kwargs
.add_return_detail()	Adds a detail line for a purchase return.	inventory_id, receipt_qty, **kwargs
.add_detail_with_allocations()	Adds a detail line with lot/serial allocations.	inventory_id, receipt_qty, allocations, **kwargs
.to_body()	Constructs the final JSON payload for the request.	(None)

4. Building a Purchase Receipt Payload

You can set top-level fields using the generic .set() method or one of the convenient shortcut methods. The most important part is adding detail lines, which can be done in several ways depending on the transaction type.

Receiving from a Purchase Order

The .add_detail_from_po() method is used to receive items against an existing PO.

Example: Receiving against a PO

# 1. Create a builder instance
receipt_payload = (
    PurchaseReceiptBuilder()
    .type("Receipt")
    .vendor_id("VEND001")
    .create_bill(True)
    .add_detail_from_po(po_order_nbr="PO000456")
)

Processing a Purchase Return

The .add_return_detail() method is used for processing returns.

Example: Returning a specific item

# 1. Create a builder instance for a return
return_payload = (
    PurchaseReceiptBuilder()
    .type("Return")
    .vendor_id("VEND001")
    .add_return_detail(inventory_id="PRODUCT-A", receipt_qty=5)
)

5. Generating the Final JSON Body

Once you have set all the required fields, call the .to_body() method to generate the final dictionary.

# 1. Build the purchase receipt
receipt_payload = (
    PurchaseReceiptBuilder()
    .type("Receipt")
    .vendor_id("VEND001")
    .add_detail_from_po(po_order_nbr="PO000456")
)

# 2. Get the final dictionary
json_body = receipt_payload.to_body()

# The json_body will look like this:
# {
#     "Type": {"value": "Receipt"},
#     "VendorID": {"value": "VEND001"},
#     "Details": [
#         {
#             "POOrderNbr": {"value": "PO000456"},
#             "POOrderType": {"value": "Normal"}
#         }
#     ]
# }

6. Complete Example with PurchaseReceiptsService

Here is a complete example of how to use the PurchaseReceiptBuilder to create a new purchase receipt.

from easy_acumatica.models.purchase_receipt_builder import PurchaseReceiptBuilder

# 1. Build the purchase receipt payload
receipt_to_create = (
    PurchaseReceiptBuilder()
    .type("Receipt")
    .vendor_id("VEND002")
    .create_bill(True)
    .set("Description", "Receipt for order PO000500")
    .add_detail_from_po(
        po_order_nbr="PO000500",
        receipt_qty=10 # Override the quantity
    )
)

# 2. Use the payload with the PurchaseReceiptsService to create the record
try:
    new_receipt = client.purchase_receipts.create(
        "24.200.001",
        builder=receipt_to_create
    )
    print(f"Successfully created purchase receipt: {new_receipt['ReceiptNbr']['value']}")
except Exception as e:
    print(f"Failed to create purchase receipt: {e}")