How to use Invoice Status Flags

In this example we take you through how to use invoice status flags when using the Operator API

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.


FlagMeaning
AWAITING_REFUNDA 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_RETURNA 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.
PAIDOrder has been completed and payment has been “processed”. This includes US-based scenarios where delayed payment capture is being used.
PARTIALLY_SENTOnly 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.
REFUNDEDA Cancellation (pre-dispatch) or Return (Post-dispatch), has been requested and approved.
REMITTEDRemittance has been paid to the seller of this Invoice.
SENTAll 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