metadataUpsert

metadataUpsert allows you to add custom string attributes to your objects, this is useful when the standard Marketplacer data model does not contain the attributes you require

Key Information

Use-Case

There are often times when you want to have “non-standard” fields attached to the various objects in Marketplacer, e.g.:

  • fraudReviewStatus attached to an order
  • detailedDeliveryInstructions on a shipment.

When the standard Markjetplacer data model does not contain such fields you can add metadata to the objects that support the attachment of metadata.

Further Points of Note

  • Metadata is generally only surfaced at the API layer (and not via the Marketplacer UI)
    • 1 exception to this is that you can expose metadata attached to order line items via the Seller Portal UI by following this guide
  • You cannot query objects based on any metadata that may be attached to them
  • The metadata value will be updated when the owner / key combination already exists, otherwise a new metadata item will be added

Availability

  • Operator API: Yes
  • Seller API: No

Example 1 - Attached single metadata item

mutation attachMetaData {
  metadataUpsert(
    input: { 
      owner: "U2VsbGVyLTc4", 
      key: "CreditRating", 
      value: "Good" }
  ) {
    status
    metadata {
      key
      value
    }
    errors{
      field
      messages
    }
  }
}

Example 2 - Attach multiple metadata items to different object types

mutation{
  a: metadataUpsert(input:
    {
      owner: "U2hpcG1lbnQtNzM0"
      key: "detailedDeliveryInstructions"
      value: "Leave behind the large plant pot at front entrance"
    })
  {
    metadata{
      key
      value
    }
    errors{
      field
      messages
    }
  }
  b: metadataUpsert(input:
    {
      owner: "SW52b2ljZS0xMzIxNw=="
      key: "fraudReviewStatus"
      value: "PENDING REVIEW"
    })
  {
    metadata{
      key
      value
    }
    errors{
      field
      messages
    }
  }
}

Arguments

NameType
inputMetadataUpsertMutationInput

Response

Returns MetadataUpsertMutationPayload


Error Responses

HTTP ErrorError MessageMeaning
401UnauthorizedYou don’t have access to the endpoint, likely Basic Authentication credentials are missing
401API Token has expiredYou don’t have access to the endpoint, likely that you are either not supplying an API Key, or the key you are supplying is invalid
200Argument ‘value’ on InputObject ‘MetadataUpsertMutationInput’ is required. Expected type String!You have not supplied a value
200Argument ‘key’ on InputObject ‘MetadataUpsertMutationInput’ is required. Expected type String!You have not supplied a key
200Argument ‘owner’ on InputObject ‘MetadataUpsertMutationInput’ is required. Expected type ID!You have not supplied a owner (id)

Further Reading