Backend API
Request options are $ parameters that change how Swell handles a request. They aren't stored on the record. Pass them with the request data, alongside the record's fields, or in the query of a read.
The options on this page work with any collection. Options that apply to one endpoint, such as $restock on Update an order, are listed with that endpoint's arguments and under Endpoint options below. To change values in a record, see Update operators.
Controls the notifications a create or update sends. See Email notifications.
- false sends no notifications for the request.
- A notification name, such as receipt, sends that notification even when its conditions don't match or it was already sent for the record.
- An object with id and data sends the notification named by id and adds data to the template data.
Notifications aren't sent for $migrate requests or for writes in a transaction.
// Complete an order without emailing the customer
await swell.put('/orders/{id}', {
id: '5c15505200c7d14d851e510f',
status: 'complete',
$notify: false,
});
// Send the order receipt again
await swell.put('/orders/{id}', {
id: '5c15505200c7d14d851e510f',
$notify: 'receipt',
});
// Send it with extra template data
await swell.put('/orders/{id}', {
id: '5c15505200c7d14d851e510f',
$notify: {
id: 'receipt',
data: { note: 'Your shipping address was updated.' },
},
});Controls the events a request creates. Webhooks and app functions subscribed to an event run only when it's created. See Events and Webhooks.
- false creates no events, so subscribed webhooks and app functions don't run. Writes in a transaction still create events.
- An object with type, an event type such as order.updated or an array of types, creates only those events. Add data to add values to each event's data. With data, update events are created even when nothing changed.
- true creates events for a $migrate request, which otherwise creates none.
// Update a product without triggering webhooks
await swell.put('/products/{id}', {
id: '5e31e67be53f9a59d89600f1',
price: 25,
$events: false,
});
// Create only the order.updated event, with extra data
await swell.put('/orders/{id}', {
id: '5c15505200c7d14d851e510f',
metadata: { erp_id: 'SO-10452' },
$events: {
type: 'order.updated',
data: { source: 'erp-sync' },
},
});Sets the locale of the field values returned by a read, or by the record a write returns. See Retrieve localized content.
- A locale code, such as fr, returns values in that locale, with the store's fallback locales applied.
- An array or comma-separated list of codes, or true for all locales, returns the stored $locale values on each object instead.
To store localized values, pass a $locale object on the record. See Set locale values.
// Retrieve a product in French
await swell.get('/products/{id}', {
id: '5e31e67be53f9a59d89600f1',
$locale: 'fr',
});
// Retrieve the stored French and German values
await swell.get('/products/{id}', {
id: '5e31e67be53f9a59d89600f1',
$locale: ['fr', 'de'],
});Sets the currency of the price fields returned by a read, or by the record a write returns. Defaults to the record's currency, or the store's base currency. See Multi-currency.
- A currency code, such as EUR, returns prices in that currency.
- An array or comma-separated list of codes, or true for all currencies, returns the stored $currency values on each object instead.
To store prices in a currency, pass a $currency object on the record.
// Retrieve a product with prices in euros
await swell.get('/products/{id}', {
id: '5e31e67be53f9a59d89600f1',
$currency: 'EUR',
});
// Retrieve products with the stored prices for every currency
await swell.get('/products', {
limit: 25,
$currency: true,
});Sets which apps' $app fields are returned on reads. Defaults to the fields of all installed apps. See Models in the Apps docs.
- An app ID or slug, or an array of them, returns only those apps' fields.
- false returns no app fields.
// Return only one app's fields
await swell.get('/products/{id}', {
id: '5e31e67be53f9a59d89600f1',
$app: 'reviews',
});
// Return no app fields
await swell.get('/products', {
limit: 25,
$app: false,
});Set to true to fill in values missing from the result with the defaults of the content models that extend the collection. String defaults are rendered as templates with the record's values. Applies to reads and to the record returned by writes, and doesn't change stored values. Defaults to false. See Content in the Apps docs.
await swell.get('/products/{id}', {
id: '5e31e67be53f9a59d89600f1',
$content: true,
});Set to true to write the record as given, without validation, the model's built-in logic, formula fields, linked record writes or notifications. Defaults to false. See Migrate to Swell.
- App before: and after: hooks still run.
- Events are created only when the request also sets $events.
- New records get migrated: true.
// Import a past order as it was
await swell.post('/orders', {
number: '10452',
account_id: '5c15505200c7d14d851e5112',
items: [
{ product_id: '5e31e67be53f9a59d89600f1', quantity: 1, price: 25 },
],
date_created: '2024-03-08T15:20:00.000Z',
$migrate: true,
});
// Import it and create its events
await swell.post('/orders', {
number: '10453',
// ...
$migrate: true,
$events: true,
});On update, replaces the whole record with the given object instead of merging it. Fields not in the object are removed, and other fields in the request are ignored. The record keeps its id. Returns a 400 error if the value isn't an object.
// The product keeps only these fields and its id
await swell.put('/products/{id}', {
id: '5e31e67be53f9a59d89600f1',
$replace: {
name: 'T-shirt',
price: 25,
active: true,
},
});These options apply to specific endpoints and are listed with their arguments.
- $restock on Update an order
- $validate_stock on Create an order and Update an order
- $combine_items on Create an order, Update an order, Create a cart and Update a cart
- $validate_items on Create a shipment and Update a shipment
- $force_delete on Delete an account
- $bulk_count on Create a gift card
- $generate_variants on Create a product and Update a product
- $pricing on Retrieve a product and List all products
- $recommendations on Retrieve a product
- $filters on List all products