Updating Adverts (Products)

What you’ll learn

• What an Advert is and its primary components
• How you can reference an advert (or variant) to update it
• How to use advertUpsert and variantUpdate to update different parts of product and/or variant
• How you can use the externalIds query to look up adverts and variants for subsequent update

What is an Advert?

This subject is covered in full in the Product Creation Guide, so rather than duplicate that content here, we’ll just summarize the main points. For a detailed overview - please refer to the aforementioned guide.

An Advert (or Product) has the following characteristics:

• Adverts are created, and placed for sale on the Marketplace by a Seller.
  • Operators can also create products on behalf of sellers
• Product updates are the most commonly executed use-case
• An Advert has a large number of attributes (full list here) we’ll cover the key attributes in this article
• Adverts must have at least 1 Variant, as it’s at the variant level that concepts such as Inventory, SKUs and Barcodes reside.
  • When orders are placed, it is the variantId that is used to identify the purchased item.
• Adverts can be created & updated via a number of different methods, in this article we will focus on how you can update Adverts using the GraphQL advertUpsert and variantUpdate mutations
• Adverts can be either:
  • “Online” - essentially available for purchase or
  • “Offline” - cannot be purchased. This may be because the Seller doesn’t wish to sell that product any longer, or there may be a problem with the way the advert has been created, making it invalid - e.g. it has not been assigned to a category (or Taxon as we call them at Marketplacer).
• The Advert is tightly coupled to the categorization that it’s placed into. We call this categorization hierarchy the “Taxonomy” in Marketplacer, so we’ll be referring to the Taxon that the Advert “belongs to” in this article.

Referencing an advert for updates

In order to update an existing advert, you would first need to be able to reference it. In this section we talk about the different “IDs” that an advert can have, and:

• Which IDs can be used directly with advertUpsert and variantUpdate to perform updates
• Which IDs can be used indirectly to retrieve adverts in order to perform updates
• Which IDs cannot be used to perform updates

Advert IDs

An advert can have the following IDs:

We can graphically represent these IDs as follows:

Example Updates

In this section we’ll update a single field (title) on an existing advert using each of the different IDs.

Note: it is assumed that you have an existing advert created. For more information on how to do this via the Seller API, please refer to this guide.

Example 1 - Use the id

mutation updateAdvertTitleById {
  advertUpsert(
    input: {
      advertId: "QWR2ZXJ0LTEwMDAwMDAxNg=="
      attributes: { title: "Electronic Radiant Coat" }
    }
  ) {
    advert {
      id
      externalId
      title
    }
    errors {
      messages
      field
    }
  }
}

Example 2 - Use the externalId

It is assumed that this advert has an externalId value assigned to it.

mutation updateAdvertTitleById {
  advertUpsert(
    input: {
      attributes: { 
        externalId: "ABC1234", 
        title: "Analog Dusty Jacket" }
    }
  ) {
    advert {
      id
      externalId
      title
    }
    errors {
      messages
      field
    }
  }
}

Example 3 - Both the id and the externalId supplied

In this case the id takes precedence over the externalId and will be used to look up the advert. Furthermore, if the externalId supplied with advertUpsert is different to the existing value of the externalId, then the new value will be applied.

mutation {
  advertUpsert(
    input: {
      advertId: "QWR2ZXJ0LTEwMDAwMDAzNg=="
      attributes: { 
        externalId: "xyz123", 
        title: "Magnificent Plasma Brain" }
    }
  ) {
    advert {
      id
      externalId
      title
    }
  }
}

Example 4 - Indirectly use externalIds

As already mentioned, you cannot use externalIds directly with either advertUpsert or variantUpdate, but you can use the externalIds query to retrieve an advert (and obtain an ID that you can use).

The example below shows how to use the externalIds query to look up an advert based on one of its attached externalIds. In this query we retrieve the id of the advert so that it could be used further to update the advert using advertUpsert.

query getAdvertByexternalId {
  externalIds(
      ownerType: "Advert", 
      key: "sys_1", 
      value: "abc1234") {
    id
    key
    value
    owner {
      id
      __typename
      ... on Advert {
        id
      }
    }
  }
}

This would result in something similar to the following:

{
  "data": {
    "externalIds": [
      {
        "id": "RXh0ZXJuYWxJRC0xMA==",
        "key": "sys_1",
        "value": "abc1234",
        "owner": {
          "id": "QWR2ZXJ0LTEwMDAwMDI3Nw==", 👈 Now use this with advertUpsert
          "__typename": "Advert"
        }
      }
    ]
  }
}

To reiterate, the recommended approach to managing adverts is to use the native Marketplacer object id. The scenario in Example 4 should really only be used where there is no alternative, and you only know about the externalIds.

Further Scenarios

Along with single-value fields that an advert can have (title, price, description etc.), adverts can have more complex associations:

• Images
  • Covered in a separate how to guide
• Option Values
  • Covered in a separate how to guide
• Variants
• Metadata
• ExternalIds

As images and option values have been covered in separate guides, in this article we’ll focus on updating:

• Variants
• Metadata
• ExternalIds

Variants

Updating Variants can be done in 1 of 2 ways:

1. Using advertUpsert
   • When you want to update an advert and its variant(s) with 1 call
   • When you want to update multiple variants with 1 call
2. Using variantUpdate
   • When you want to update an individual variant only

Using advertUpsert

When using advertUpsert to update variants the following should be considered:

• You must supply either an advertId or externalId (to reference the advert to which the variant belongs)
• You should supply either a variantId or externalId for the variant(s) you want to update
  • If you do not supply either a variantId or externalId along with the variant definition, then a new variant will be created
  • If you supply only an externalId for the variant, and that externalId does not exist, then a new variant will be created
  • If you supply both a variantId and an externalId for the variant, the variantId will take precedence for the look up, and if the externalId is different, then that will be updated to the externalId supplied.

The example below shows how we can update both the:

• Advert: title
• Variant: barcode

mutation updateAdvertAndVariant {
  advertUpsert(
    input: {
      advertId: "QWR2ZXJ0LTEwMDAwMDAzNg=="
      attributes: {
        title: "Insolvent Muddy Shin"
        variants: [
          { 
            id: "VmFyaWFudC0zNQ==", 
            barcode: "2579325358052" 
          }
        ]
      }
    }
  ) {
    advert {
      id
      externalId
      title
      variants(displayableOnly: false) {
        nodes {
          id
          barcode
        }
      }
    }
    errors {
      messages
      field
    }
  }
}

Using variantUpdate

The variantUpdate mutation is useful when you only need to update a single variant, an example of this is shown below where we update the countOnHand (stock level) for the variant:

mutation updateVariantStockLevel {
  variantUpdate(
    input: { 
      variantId: "VmFyaWFudC0zNQ==", 
      attributes: 
        { 
          countOnHand: 888 
        }
      }
  ) {
    variant {
      id
      countOnHand
    }
    errors {
      messages
      field
    }
  }
}

Advert Metadata

Operators and Sellers can add and update metadata on an advert via the advertUpsert mutation, when doing so, the following points should be noted:

• If you supply a metadata value where the key value does not already exist - a new metadata item will be created
• If you supply a metadata value where the key value does exist then the value will be updated

mutation updateAdvertMetaData {
  advertUpsert(
    input: {
      advertId: "QWR2ZXJ0LTEwMDAwMDAzNg=="
      attributes: { metadata: [
        { 
          key: "Channel_Segement", 
          value: "P3" 
          }
      ]}
    }
  ) {
    advert {
      id
      metadata {
        key
        value
      }
    }
    errors {
      messages
      field
    }
  }
}

Advert External Ids

Sellers can add and update externalIds on an advert via the advertUpsert mutation, when doing so, the following points should be noted:

• If you supply an externalIds value where the key value does not already exist - a new externalIds item will be created
• If you supply an externalIds value where the key value does exist then the value will be updated

mutation updateAdvertMetaData {
  advertUpsert(
    input: {
      advertId: "QWR2ZXJ0LTEwMDAwMDAzNg=="
      attributes: { externalIds: [
        { 
          key: "CRM_1", 
          value: "ABC1234" 
          }
      ]}
    }
  ) {
    advert {
      id
      metadata {
        key
        value
      }
    }
    errors {
      messages
      field
    }
  }
}