An invoice is a document that provides details about a transaction, including information about the merchant, customer, and the monetary exchange. The customer-facing version of an invoice is often referred to as a bill. This page provides an in-depth understanding of invoice functionality within the Stax API, including their lifecycle, structure, and common use cases.

Statuses

Invoice statuses in the Stax platform are automatically managed by system operations and cannot be manually modified through API requests. Actions such as creating, sending, viewing, and making payments impact the current status of an invoice. However, certain functionalities, such as reverting statuses after refunds, require careful implementation to ensure accurate status tracking.

Status Transitions Overview

DRAFT → SENT: After sending the invoice via email.

DRAFT → VIEWED: If a customer views an invoice sent via a different email method.

DRAFT → PAID / PARTIALLY PAID / ATTEMPTED: When payments are processed directly.

Any status → DELETED: When the invoice is deleted.

Note: Status transitions such as refunds or voids are automatically managed. Ensure your integration accounts for these updates when handling payments or deletions.

---

Invoice Structure

Understanding the structure of an invoice is critical for developers to handle API responses effectively. Below are the key fields in an invoice:

---

Common Use Cases

Creating an Invoice

When you create an invoice using the POST /invoice endpoint, the invoice is initially assigned a status of DRAFT. This means the invoice has not yet been sent or viewed.

Sending an Invoice via Email

If the invoice belongs to a customer with an email, you can send it using the PUT /invoice/{id}/send/email endpoint. This action will:

• Update the invoice status to SENT.
• Record the current timestamp in the sent_at field.

Invoice Viewed by Customer

The VIEWED status is assigned when a customer opens the invoice email or views the invoice through the link provided. This status will have a viewed_at timestamp to indicate when the invoice was viewed.

Note: The SENT and VIEWED statuses are only applicable if the merchant uses the Stax email solution or UI to send invoices. If an API integrator manages the email process themselves, the invoice may go directly from DRAFT to VIEWED or even directly to PAID.

Handling Refunds and Voids

• Refunds: If a payment linked to an invoice is refunded (fully or partially), the invoice's status will revert to reflect the updated payment total.
• Voids: Voiding a payment linked to an invoice will revert the status and make the invoice eligible for a new payment attempt.

Deleted Status

The DELETED status can branch from any other status. This indicates the invoice has been soft-deleted, meaning it is inaccessible but still exists in the database for reference or restoration.

---

Best Practices

Unique Identifiers: Use a UUID or unique identifier for each invoice to avoid conflicts during creation and updates.

Tracking Payments: Link transactions to invoices via the invoice_id field for complete payment tracking.

Error Handling: Implement robust error handling for scenarios like invalid customer details, failed payments, or incorrect invoice IDs.

Customization: Leverage hosted invoice pages to allow tipping, partial payments, or displaying memos to customers.

---

Troubleshooting