django_program.registration.services.qbo_invoicing

QuickBooks Online invoicing integration for purchase orders.

Provides functions to create and sync QBO invoices from purchase orders, using the QBO REST API v3 directly via httpx. Handles OAuth2 token refresh transparently so callers only need a Conference with valid QBO credentials.

The QBO OAuth flow for obtaining initial tokens is out of scope – tokens are assumed to be stored on the Conference model and refreshed here when expired.

Functions

create_qbo_invoice(purchase_order)	Create a QBO Invoice from a purchase order's line items.
handle_qbo_webhook(payload)	Process a QBO webhook notification for invoice payment events.
send_qbo_invoice_email(purchase_order)	Send the QBO invoice to the customer via QBO's email delivery.
sync_qbo_invoice_status(purchase_order)	Fetch the current QBO invoice status and record payment if paid.

Exceptions

QBOAPIError	Raised when the QBO API returns an error response.
QBONotConfiguredError	Raised when a conference does not have QBO credentials configured.

exception django_program.registration.services.qbo_invoicing.QBONotConfiguredError

Bases: ValueError

Raised when a conference does not have QBO credentials configured.

exception django_program.registration.services.qbo_invoicing.QBOAPIError

Bases: Exception

Raised when the QBO API returns an error response.

Parameters:

• status_code (int) – The HTTP status code from the QBO API.

• detail (str) – A description of the error.

__init__(status_code, detail)

Initialize with the HTTP status code and error detail.

Parameters:

• status_code (int)

• detail (str)

django_program.registration.services.qbo_invoicing.create_qbo_invoice(purchase_order)

Create a QBO Invoice from a purchase order’s line items.

Finds or creates the QBO Customer by organization name, then builds and submits an invoice with the PO’s line items. Stores the resulting QBO invoice ID and public URL on the PurchaseOrder.

Parameters:

purchase_order (PurchaseOrder) – The purchase order to invoice.

Return type:

str

Returns:

The QBO invoice ID string.

Raises:

• QBONotConfiguredError – If the conference lacks QBO credentials.

• QBOAPIError – If any QBO API call fails.

• ValueError – If the PO already has a QBO invoice.

django_program.registration.services.qbo_invoicing.sync_qbo_invoice_status(purchase_order)

Fetch the current QBO invoice status and record payment if paid.

Queries the QBO invoice by ID, checks its Balance field, and if the invoice is fully paid (balance == 0), records a payment on the PO using the existing record_payment() service function.

Parameters:

purchase_order (PurchaseOrder) – The PO whose QBO invoice to sync.

Raises:

• ValueError – If the PO has no QBO invoice ID.

• QBONotConfiguredError – If the conference lacks QBO credentials.

• QBOAPIError – If the QBO API call fails.

Return type:

None

django_program.registration.services.qbo_invoicing.send_qbo_invoice_email(purchase_order)

Send the QBO invoice to the customer via QBO’s email delivery.

Uses the QBO invoice/{id}/send endpoint to trigger email delivery to the billing email address stored on the invoice.

Parameters:

purchase_order (PurchaseOrder) – The PO whose QBO invoice to send.

Raises:

• ValueError – If the PO has no QBO invoice ID.

• QBONotConfiguredError – If the conference lacks QBO credentials.

• QBOAPIError – If the QBO API call fails.

Return type:

None

django_program.registration.services.qbo_invoicing.handle_qbo_webhook(payload)

Process a QBO webhook notification for invoice payment events.

QBO sends webhook events when invoices are paid. This handler looks for Payment events, finds the associated invoice(s), and syncs payment status for any matching purchase orders.

Parameters:

payload (dict[str, object]) – The parsed JSON webhook payload from QBO.

Return type:

None