Backend API
Update operators are used to modify specific fields within records. They can change field names and values, remove entire fields, and add, replace, or remove items in arrays. You can access array items and fields of nested objects using dot notation.
Be careful! There is no way to roll back update operations. We recommend running your queries first on test records to confirm they do what you expect, especially if you’re updating multiple records at once.
Swell automatically generates an ObjectID when creating new records or nested objects. When using $set or in other situations where you wish to supply your own ID, it must use BSON ObjectID format for compatibility.
| Name | Description |
| $set | Updates the value of a field or adds the field if it doesn't exist. |
| $unset | Removes a field if it exists. On arrays, it replaces the matched element with null. |
| $inc | Increments the value of a field by a specified amount, or sets the value if the field doesn’t exist. Passing a negative number will decrement the value. |
| $addToSet | Adds an element to an array if it doesn't already exist, avoiding duplicates. |
| $push | Adds an element to an array. May result in duplicates. |
| $pull | Removes all elements from an array that match a specified condition. |
| $rename | Changes the name of a field. If a field with the new name already exists, it will be removed. |
| $each | Used in combination with $push or $addToSet to add multiple array elements at once. |
| $[] | Makes the update operator modify all elements in the specified array field. |
const swell = require('swell-node').init('store-id', 'secret-key');
// Set a product variant's stock status (custom attribute) as "Made to order"
await swell.put('/products:variants/{id}', {
id: '6298d900f97f61001253d91a',
$set: { 'attributes.stock_status': 'Made to order' }
});
// Remove a product variant's stock status (custom attribute)
await swell.put('/products:variants/{id}', {
id: '6298d900f97f61001253d91a',
$unset: { 'attributes.stock_status': '' }
});
// Increment a product's view count (custom attribute) by 1
await swell.put('/products/{id}', {
id: '6298d900f97f61001253d90f',
$inc: { 'attributes.view_count': 1 }
});
// Decrement a product's view count (custom attribute) by 1
await swell.put('/products/{id}', {
id: '6298d900f97f61001253d90f',
$inc: { 'attributes.view_count': -1 }
});
// Rename the "room_usage" attribute on a product to "rooms".
// Note: this would be after changing the name of the master attribute definition in /attributes.
await swell.put('/products/{id}', {
id: '6298d900f97f61001253d90f',
$rename: {
'attributes.room_usage': 'attributes.rooms'
}
});const swell = require('swell-node').init('store-id', 'secret-key');
// Add "Kitchen" to a product's room usage array (custom attribute), avoiding duplicates
await swell.put('/products/{id}', {
id: '6298d900f97f61001253d90f',
$addToSet: { 'attributes.room_usage': 'Kitchen' }
});
// Add "Kitchen" to a product's room usage array (custom attribute), allowing duplicates
await swell.put('/products/{id}', {
id: '6298d900f97f61001253d90f',
$push: { 'attributes.room_usage': 'Kitchen' }
});
// Remove any values containing "Nut" or "nut" from a product's allergens array (custom attribute).
await swell.put('/products/{id}', {
id: '6298d900f97f61001253d90f',
$pull: {
'attributes.allergens': {
$regex: 'nut', $options: 'i'
}
}
});
// Remove any values containing "Nut" or "nut" from a product's allergens array (custom attribute).
await swell.put('/products/{id}', {
id: '6298d900f97f61001253d90f',
$pull: {
'attributes.allergens': {
$regex: 'nut', $options: 'i'
}
}
});
// Remove any option values from a product which don't have an ID
await swell.put('/products/{id}', {
id: '6298d900f97f61001253d90f',
$pull: {
'options.$[].values': {
id: { $exists: false }
}
}
});
// Add 3 new "Material" option values to a product, avoiding duplicates
// Import library to generate ObjectIDs for the new option values
import ObjectID from 'bson-objectid';
// Get the index of the option named "Material"
const optionIndex = product.options.findIndex(({ name }) => name === 'Material'
// Add the new values
await swell.put('/products/{id}', {
id: '6298d900f97f61001253d90f',
$addToSet: {
`options.${optionIndex}.values`: {
$each: [
{ id: ObjectID(), name: "Bahia laminate", price: 66 },
{ id: ObjectID(), name: "Laurent black quartz", price: 122 },
{ id: ObjectID(), name: "Ducal marble", price: 148 }
]
}
}
});When updating a record that links to another collection, the values of records in that collection can be updated in the same request by passing their IDs, along with the fields and new values.
For example, the code below will update a customer's phone number for three of their addresses in a single request, as the addresses field is a link to the collection accounts:addresses and the IDs of each record are specified.
await swell.put('/accounts/{id}', {
id,
addresses: [
{ id: '5fc4a1a7a1c964001f451e1a', phone: '999-999-9999' },
{ id: '5fd927d9a1c964001f45215e', phone: '999-999-9999' },
{ id: '6020d206a1c964001f453950', phone: '999-999-9999' },
]
})This also works for single linked records. On orders, for example, the account field is a link to the accounts collection, and the billing field is a link to the accounts:cards collection. Say you wanted to change the default card on file for a customer while making other changes to an order, the following code would accomplish that in one request.
await swell.put('/orders/{id}', {
id,
account: {
billing: {
account_card_id: '5feb2c50a1c964001f452b4a'
},
}
... // Other order record changes
})