Extending Models Using Metadata

Nautical gives you the possibility to customize your shop without modifying the core. You can extend most of the common models using metadata fields. Metadata can be public or private.

Metadata allows you to store additional information about each object, for example external identifiers for items synchronized with a third party platform. You can also use metadata to customize the way your storefront looks and behaves.

Supported object types

The following object models can be extended with metadata:

• AddressType
• Agreement
• AgreementCommission
• AgreementSellers
• App
• Attribute
• Category
• Checkout
• Collection
• DigitalContent
• Directory

• Fulfillment
• Invoice
• Listing
• Microsite
• NauticalFulfillment
• NauticalOrder
• NauticalSubOrder
• Order
• Page
• Payment
• Payout

• PriceBook
• Product
• ProductType
• ProductVariant
• Refund
• Seller
• SellerType
• User
• UserType
• VendorPayout
• Warehouse

Private and public metadata

All objects support two sets of metadata:

• metadata is public and visible to unauthenticated users.
• privateMetadata is protected and visible only to staff users and apps with permissions to the underlying object.

Modifying both requires the permission to manage the item that metadata is attached to.

Querying metadata

All of the objects types listed above implement the same interface, ObjectWithMetadata:

Interface

interface ObjectWithMetadata {
  privateMetadata: [MetadataItem!]!
  metadata: [MetadataItem!]!
}

Each MetadataItem is a key-value pair:

Object

type MetadataItem {
  key: String!
  value: String!
}

You can query metadata by querying the underlying object and requesting the metadata and privateMetadata fields. Here's an example query that fetches the metadata of the first five products:

Query

{
  products(first: 5) {
    edges {
      node {
        id
        name
        metadata {
          key
          value
        }
        privateMetadata {
          key
          value
        }
      }
    }
  }
}

Updating metadata

The following GraphQL mutations allow you to update and remove metadata:

• metadataUpdate: Adds metadata to an object based on a given `id`.
• metadataDelete: Deletes an object's metadata based on a given `id` and `keys` to delete.
• privateMetadataUpdate: Adds private metadata to an object based on a given `id`.
• privateMetadataDelete: Deletes an object's private metadata based on a given `id` and `keys` to delete.

Example usage

Here's an example of how a product's metadata could be updated:

Mutation

mutation {
  metadataUpdate(
    id: "UHJvZHVjdDoxMTM="
    input: [{ key: "special_product", value: "true" }]
  ) {
    metadataErrors {
      field
      code
    }
    item {
      metadata {
        key
        value
      }
    }
  }
}

Then, upon querying the product we can see the metadata has been added:

Query

{
  product(id: "UHJvZHVjdDoxMTM=") {
    metadata {
      key
      value
    }
  }
}

Response

{
  "data": {
    "product": {
      "metadata": [
        {
          "key": "special_product",
          "value": "true"
        }
      ]
    }
  }
}

Then, to remove the same metadata field we just added:

Mutation

mutation {
  metadataDelete(id: "UHJvZHVjdDoxMTM=", keys: ["special_product"]) {
    metadataErrors {
      field
      code
    }
    item {
      metadata {
        key
        value
      }
    }
  }
}