How to add metadata

What you’ll learn

In this article you’ll learn about adding metadata to objects that support it, specifically:

• Adding metadata at object creation: e.g. with orders or adverts
• Using metadataUpsert to add metadata to an existing object
• Using metadata2Upsert to add multiple metadata to an existing object
• Retrieving metadata

What is metadata and why would you use it

The metadata object allows you to add key-value pairs to multiple objects within the Marketplacer GraphQL schema, including but not limited to:

• order
• invoice
• seller
• advert

Its intended purpose is to allow you to define and use attributes that may not exist for that object in the default schema.

Adding Metadata at object creation

Some mutations such as orderCreate & advertUpsert allow you to supply metadata at the point when objects are created. An example of how to do this using orderCreate is shown below:

Example: orderCreate

In this example we are adding 2 pieces of metadata with the following keys:

• createdBy
• mode

    mutation createOrderWithMetadata{
      orderCreate(input: {
        order: {   
          firstName: "John"
          surname: "Doe"
          phone: "0405123456"
          emailAddress: "john@email.com"
          billingFirstName: "John"
          billingSurname: "Doe"
          messageToSeller: "This is a test order on Wed 19th Feb"
          billingEmailAddress: "john@email.com"
          address: {
            address: "1 Bourke Street"
              city: "Melbourne"
              country: {
                code: "AU"
              }
              postcode: "3000"
              state: {
                name: "victoria"
              }
          }
          metadata: [{
            key: "createdBy"
            value: "ERP"
          },
          {
            key: "mode"
            value: "Real_Time"
          }
          ]
          termsAndConditionsAccepted: true
          }
        lineItems: [{             
          variantId: "VmFyaWFudC00ODE3"
          quantity: 1
          totalCents: 22500
          postageCents: 1000 
        }]
      })
      {
        order{
          id
        }
      }
    }

As you can see you are able to create any number of key / value pairs as required.

Please refer to the individual docs (e.g. advertUpsert) for more detail on how to add metadata at object creation.

Upserting on existing objects

In addition to adding metadata at the point of object creation, you can “upsert” metadata on existing objects.

Upserting is when you add/insert data when it doesn’t already exist, and update when it does. The owner and key values combined determine the uniqueness of the metadata. E.g. if an owner and key combination already exist, then supplying them again, will result in the update of the value.

Example: metadataUpsert

This mutation allows you to add 1 set of metadata to an existing object that supports metadata attachment, you need to supply:

• The owner (ID) of the object (E.g. order, invoice or advert), that you want to work with
• The key for the metadata
• The value for the key

Mutation

mutation addMetaDataToInvoice($input: MetadataUpsertMutationInput!) {
 metadataUpsert(input: $input) {
  errors {
   field
   messages
  }
  metadata {
   key
   value
   owner {
    ... on Invoice {
     id
    }
   }
  }
 }
}

Variables

{
  "input": {
    "owner": "SW52b2ljZS0xMzY4NA==",
    "key"  : "Shipping_Date"       ,
    "value": "2024-09-20"
  }
}

Example: metadata2Upsert

This mutation allows you to add 1 or more sets of metadata to an existing object that supports metadata attachment, you need to supply:

• The owner (ID) of the object (E.g. order, invoice or advert), that you want to work with
  • Note: You can only supply 1 owner
• The key(s) for the metadata
• The value(s) for the key(s)

Mutation

mutation ($input: Metadata2UpsertMutationInput!) {
 metadata2Upsert(input: $input) {
  errors {
   field
   messages
  }
  metadata {
   key
   value
  }
 }
}

Variables

{
  "input": {
    "ownerId": "SW52b2ljZS0xMzcxNg==",
    "metadata": [
      {"key": "Shipping_Date"  , "value": "2024-9-20"},
      {"key": "Priority_Member", "value": "Gold"     }
    ]
  }
}

Retrieving metadata

Returning this data via a GraphQL query is no more complex than any other, an example using the updatedOrders query is illustrated below, but the same syntax would be used for other queries that have metadata:

query getOrdersWithMetadata {
 updatedOrders(updatedSince: "2021-02-19", first: 10) {
  nodes {
   id
   metadata {
    key
    value
   }
  }
 }
}

Considerations

The use of metadata as described in this article is intended to be used only within the context of the GraphQL API, i.e.:

• The metadata is not accessible via the Marketplacer Web frontend
  • Some exceptions to this do exist where line item metadata can be exposed in the Seller Portal. This knowledge base article explains how this is achieved.
• The metadata is not available via the v2 (REST) API
• You cannot query objects using metadata
  • This functionality is available using externalIds, which may be suitable for some use-cases.