How to Annotate an Invoice

In this example we take you through how to annotate an invoice while using the Operator API

4 minute read

What you’ll learn

In this article you’ll learn:

What Invoice Annotations are
How to create Invoice Annotation Types
How to add an Invoice Annotation to an Invoice

What are invoice annotations

Invoice Annotations are a way of communicating information about an order from a seller, back to your connected eCommerce system. For example a seller may use Invoice Annotations to communicate that they have received the order and are processing it, or that a line item on the order is on back-order and will therefore be delayed.

Note

Invoice Annotations are only available on Connected Marketplacer instances, and cannot be leveraged using Full Stack or Headless configurations.

In order to use Invoice Annotations:

The Operator will have to create a list of Invoice Annotation Types
The Seller will select one of those types and add it to an invoice

You can execute these steps using the Marketplacer Operator and Seller Portals, or via the GraphQL API. In this article we cover how you can use Invoice Annotations using the GraphQL API.

Note

For more information on how to use Invoice Annotations within the Marketplacer UI, please refer to the Marketplacer Knowledge base and search for: “Invoice Annotations”

GraphQL Queries and Mutations

While we won’t necessarily be using all of the following queries and mutations in this article, we have listed those queries and mutations that can be used to work directly with Invoice Annotations:

Mutation or Query	Type	Description	Operator	Seller
InvoiceAnnotationCreate	Mutation	Create an annotation of a given type on a single invoice	Yes	Yes
InvoiceAnnotationUpdate	Mutation	Update an existing annotation	Yes	Yes
InvoiceAnnotationResolve	Mutation	Set the status of the annotation to resolved	Yes	Yes
InvoiceAnnotationTypeCreate	Mutation	Create an Invoice Annotation Type	Yes	No
InvoiceAnnotationTypeUpdate	Mutation	Update an Invoice Annotation Type	Yes	No
InvoiceAnnotationTypeDiscard	Mutation	Destroy an Invoice Annotation Type	Yes	No
Any query that can reference the `Invoice` type	Query	Querying an `invoice` will give you access to the annotations on it	Yes	Yes

Note

Examples of these queries and mutations can be found in our Postman and Insomnia collections for both Operators and Sellers

Create an Invoice Annotation Type

This can only be performed by the Operator, an example mutation call is provided below:

    mutation {
      invoiceAnnotationTypeCreate(
        input: {
          attributes: {
            name: "Order Received"
            description: "The order has been received"
            creatableByCustomer: true
            creatableBySeller: true
            creatableByOperator: true
            editableBySeller: true
            editableByCustomer: true
            editableByOperator: true
            resolvableBySeller: true
            resolvableByCustomer: true
            resolvableByOperator: true
            viewableBySeller: true
            viewableByCustomer: true
            viewableByOperator: true
          }
        }
      ) {
        errors {
          field
          messages
        }
        invoiceAnnotationType {
          id
        }
      }
    }

Note

If you attempt to add an Invoice Annotation Type with a name that has already been taken you will receive a validation error.

An example response is given below:

    {
      "data": {
        "invoiceAnnotationTypeCreate": {
          "errors": null,
          "invoiceAnnotationType": {
            "id": "SW52b2ljZUFubm90YXRpb25UeXBlLTg="
          }
        }
      }
    }

We will use the invoiceAnnotationType id in the next step.

Adding an Annotation to an Invoice

This step can be performed by either the Seller or the Operator, an example mutation call is provided below:

    mutation{
      invoiceAnnotationCreate(input:
        {
          invoiceId: "SW52b2ljZS0xMDM3Nw=="
          invoiceAnnotationTypeId: "SW52b2ljZUFubm90YXRpb25UeXBlLTg="
          attributes:{
            content: "Picking order"
            resolved: false
          }
        })
      {
        errors{
          field
          messages
        }
        invoiceAnnotation{
          id
        }
      }
    }

In this case we have added an annotation to the Invoice using the `invoiceAnnotationType` `id` from the previous section. You’ll note that at this point we specified that the annotation is not resolved.

Querying for Invoice Annotations

You can access the Invoice Annotations on your invoices using any query that permits you to resolve the invoice type. This can be performed by either the Seller or Operator, for Sellers it should be noted that they only have access to their invoices.

An example of querying an Invoice directly using a node query is shown below:

    query{
      nodes(ids: [
        "SW52b2ljZS0xMDM3Nw=="
      ])
      {
        ... on Invoice {
          legacyId
          id
          statusFlags
          seller{
            businessName
          }
          annotations{
            content
            createdAt
            updatedAt
            invoiceAnnotationType{
              name
            }
            resolved
          }
        }
      }
    }

With an example payload as shown below

    {
      "data": {
        "nodes": [
          {
            "legacyId": 10377,
            "id": "SW52b2ljZS0xMDM3Nw==",
            "statusFlags": [
              "PAID"
            ],
            "seller": {
              "businessName": "ACME Corp."
            },
            "annotations": [
              {
                "content": "Picking Order",
                "createdAt": "2022-11-17T10:52:13+11:00",
                "updatedAt": "2022-11-17T10:52:13+11:00",
                "invoiceAnnotationType": {
                "name": "Order Received"
              },
              "resolved": false
              }
            ]
          }
        ]
      }
    }

Marking an annotation as resolved

When we created the annotation initially, we set its resolved status to false, we can now update to true to reflect the “completion” of this annotation type.

This can be performed by either the Operator or Seller, and example mutation is given below.

    mutation{
      invoiceAnnotationResolve(input:
        {
          invoiceAnnotationId: "SW52b2ljZUFubm90YXRpb24tNDI="
        })
      {
        errors{
          field
          messages
        }
        invoiceAnnotation{
          id
        }
      }
    }