Batch mutations

Last updated October 27th at 2:11pm

Many Integration API mutations support batching - sending multiple items in one mutation. For massive updates, batch mutations are faster and work atomically (either all items are saved or none) whenever it makes sense. Always consider using batch mutations for large updates.

Because every API call is sent, authorized, processed and responded to individually, a big profit from using batch mutations is how much network round trip time and server processing time it can save you. For example, sending 10 calls to create ID conversions will require you to wait 10 times for the requests and responses to be processed and carried over the Internet. If you instead send those mutations in a single API call, not only the total execution on the server will be faster, but you will also save a lot on network time to receive the single response.

Risks#

With greater performance, you need to know about the risks:

In some cases, large batches can cause an instant high load. To choose a batch size that works best for you, you can test different sizes and compare response times.
Processing some items can fail due to errors. Most mutations roll back all changes if any item fails, including successful ones. You will see this as a non-empty userErrors in the response. Other mutations throw userWarnings and save valid items. Pay attention to the errors you receive to determine if partial changes have been applied or not. See more on handling errors in the Integration API.
Using these mutations for updating a single object at a time is ineffective. Try to collect updates on your side to send a single mutation with many objects.

Example#

When you need to update multiple prices of a single pricelist, you can use setPrices. Pay attention to individual variant prices: there can be many of them in one mutation as well.

mutation setPricesForOnePricelist {
  setPrices(
    input: {
      pricelist: { id: 10 }
      productPrices: [
        { 
          product: { id: 1 }
          price: { value: 99.99, currencyIsoCode: "USD" }
        }
        { 
          product: { id: 2 }
          price: { value: 199.99, currencyIsoCode: "USD" } 
          individualVariantPrices: [
            {
              productVariant: { id: 1002 }
              price: { value: 202, currencyIsoCode: "USD" } 
            }
            {
              productVariant: { id: 1003 }
              price: { value: 203, currencyIsoCode: "USD" } 
            }
          ]
        }
        # and more
      ]
    }
  ) {
    userErrors { message path }
    userWarnings { message path }
    pricelist { id }
  }
}

When you need to update multiple prices of multiple pricelists, setPricesBatch will do it in one go, while setPrices would have to be called for as many pricelists as you have.

mutation setPricesForMultiplePricelists {
  setPricesBatch(
    input: [
      {
        pricelist: { id: 10 }
        productPrices: [
          {
            product: { id: 1 }
            price: { value: 99.99, currencyIsoCode: "USD" }
          }
          {
            product: { id: 2 }
            price: { value: 199.99, currencyIsoCode: "USD" }
            individualVariantPrices: [
              {
                productVariant: { id: 1002 }
                price: { value: 202, currencyIsoCode: "USD" } 
              }
              {
                productVariant: { id: 1003 }
                price: { value: 203, currencyIsoCode: "USD" } 
              }
            ]
          }
        ]
      }
      {
        pricelist: { id: 11 }
        productPrices: [
          {
            product: { id: 1 }
            price: { value: 79.99, currencyIsoCode: "EUR" }
          }
          {
            product: { id: 2 }
            price: { value: 189.99, currencyIsoCode: "EUR" }
            individualVariantPrices: [
              {
                productVariant: { id: 1002 }
                price: { value: 182, currencyIsoCode: "EUR" } 
              }
              {
                productVariant: { id: 1003 }
                price: { value: 183, currencyIsoCode: "EUR" } 
              }
            ]
          }
        ]
      }
    ]
  ) {
    userErrors { message path }
    userWarnings { message path }
    pricelists { id }
  }
}

Batch mutations in Integration API#

assignAttributes/unassignAttributes - to assign attributes to a single object / to unassign attributes from a single object. Batch size limit: no limit.
assignAttributesBatch/unassignAttributesBatch - to assign attributes to multiple objects / to unassign attributes from multiple objects. Batch size limit: 100 objects.
createMediaBatch - to upload multiple product images. Batch size limit: 100 images.
setCampaignVariants/unsetCampaignVariants - to enable selected variants in one campaign/to remove variants from a campaign. Batch size limit: no limit.
setCategoryDisplays/unsetCategoryDisplays - to add displays to a single category, or remove displays from a single category. Batch size limit: 100 displays.
setMarketDisplays/unsetMarketDisplays - to add displays to a single market, or remove displays from a single market. Batch size limit: 100 displays.
setIdConversions/unsetIdConversions - to set/unset multiple ID conversions. Batch size limit: 100 objects.
setPrices/setAlteredPrices - to set prices for a single pricelist. Batch size limit: 100 prices.
setPricesBatch/setAlteredPricesBatch - to set prices for multiple pricelists. Batch size limits: 100 prices per one pricelist, 1000 prices in total.
setStock - to set absolute stock values to multiple product variants or product sizes.
changeStock - to execute a stock transfer between warehouses.
setTranslations - to set translations to a single object.
and others.

Many mutations from this list can only set multiple values to a single object. We’re working on adding more mutations similar to setPricesBatch to modify multiple values of multiple objects.