How to use Invoice Status Flags
5 minute read
What you’ll learn
In this article you’ll learn:
- What status flags are and their intended use
- The current list of status flags that we use
- How status flags are represented through some typical invoice scenarios
What are status flags?
Status flags are used to represent the “story” of an Invoice, this means that a given invoice can (and most usually does) have multiple status flags. For example, in a very simple scenario where an Invoice (order) has been created, and all the line items on that invoice have been dispatched to the customer, that invoice would have the following status flags:
- PAID
- SENT
There are obviously more complex scenarios, (some of which are covered in this article), where the invoice may have additional status flags.
Why can’t we have 1 status?
Invoices did originally just have a single status, so in the above example, the single status of the invoice would be;
- SENT
For simple, happy path scenarios, this used to suffice, as it logically follows that you would need to have paid for your items before they were sent to you.
However as the complexity of the scenarios increased, attempting to represent the status of an invoice with a singular status became increasingly difficult, and confusing. E.g. What single status would make sense for an invoice where some items had been dispatched and some had been cancelled prior to dispatch?
Indeed trying to map a single status to all possible permutations of an invoices state transition history (while theoretically possible) would be unwieldy and difficult to interpret, (you’d need lengthy status descriptions etc.)
We have therefore settled on using multiple status flags, that when taken as a whole, not only represent the current status of the invoice, but give the API consumer a view of the history of that invoice.
What are the individual status flags?
The individual status flags are defined in InvoiceStatusFlagEnum, which can be referenced in the docs here. However we have also provided the list below.
Note
The majority of Marketplacer instances are of the type: “Connected”. This means that payment for orders is taken off platform, and not within Marketplacer. There are some status flags that are relevant only to non-Connected instances (where payment is taken and processed by Marketplacer). We identify non-Connected status flags where relevant so that readers working with Connected instances can ignore them.| Flag | Meaning |
|---|---|
| AWAITING_REFUND | A Cancellation (pre-dispatch) or Return (Post-dispatch), has been requested and items have been marked as having been returned to the Seller. The refund request is awaiting the Operator to either approve or deny the refund request. |
| AWAITING_RETURN | A Cancellation (pre-dispatch) or Return (Post-dispatch), has been requested. The refund request is awaiting on the Seller to mark the items as having been returned in acceptable condition. |
| CANCELLED | [Non-Connected Only] Order / Invoice had been awaiting payment but the payment has subsequently been cancelled. |
| COLLECTED | [Non-Connected Only] Where a click and collect order / invoice had been placed, and the line items on that invoice had been collected. At the time of writing Click and Collect functionality is only available in Non-Connected instances. |
| PAID | Order has been completed and payment has been “processed”. This includes US-based scenarios where delayed payment capture is being used. |
| PARTIALLY_SENT | Only some items of an invoice have been dispatched. This includes scenarios where: 1) Multiple quantities of a single line item were ordered and only a subset have been dispatched, 2) Multiple line items had been ordered and only some of those line items have been dispatched |
| PAYMENT_UNDER_REVIEW | [Non-Connected Only] Where payments are being taken by Marketplacer the payment gateway has placed the payment in a review status. |
| READY | [Non-Connected Only] Where a click and collect order / invoice has been placed, and the items on that invoice are ready to be collected. At the time of writing click and collect functionality is only available in Non-Connected instances. |
| REFUNDED | A Cancellation (pre-dispatch) or Return (Post-dispatch), has been requested and approved. |
| REMITTED | Remittance has been paid to the seller of this Invoice. |
| SENT | All line items on the invoice have been sent. |
Invoice Scenario Examples
Below are some common examples of the workflow that a typical invoice can go through, it is not exhaustive though. Readers wanting to understand the status flag configuration for their specific scenarios should trial these themselves.
Scenario 1: Simplex Happy Path
Scenario Summary: Order (and Invoice) have been created on a connected Marketplacer instance (payment has been taken off platform), and the Seller has dispatched all line items on that Invoice.
Status Flags
- PAID
- SENT
Scenario 2: Partial Dispatch
Scenario Summary: Order (and Invoice) have been created on a connected Marketplacer instance (payment has been taken off platform), and the Seller has dispatched some of the line items on that Invoice.
Status Flags:
- PAID
- PARTIALLY_SENT
Scenario Addendum 1: The seller then eventually dispatches all remaining items
Status Flags:
- PAID
- SENT
Scenario 3: Refund Customer
Scenario Summary: Order (and Invoice) have been created on a connected Marketplacer instance (payment has been taken off platform). The Seller has dispatched all line items on the invoice, and the Customer has now initiated a refund request.
Status Flags:
- PAID
- SENT
- AWAITING_RETURN
Scenario Addendum 1: The seller receives the dispatched items from the customer and marks the items as having been returned
Status Flags:
- PAID
- SENT
- AWATING_REFUND
Scenario Addendum 2: The operator approves the refund
Status Flags:
- PAID
- SENT
- REFUNDED