# Request options

Source: https://developers.swell.is/backend-api/request-options

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](https://developers.swell.is/backend-api/orders/update-an-order), are listed with that endpoint's arguments and under Endpoint options below. To change values in a record, see [Update operators](https://developers.swell.is/backend-api/updating/update-operators).

## $notify

Controls the notifications a create or update sends. See [Email notifications](https://developers.swell.is/guides/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.

**Skip or resend notifications**

**Node**

```javascript
// 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.' },
  },
});
```

## $events

Controls the events a request creates. Webhooks and app functions subscribed to an event run only when it's created. See [Events](https://developers.swell.is/backend-api/events) and [Webhooks](https://developers.swell.is/backend-api/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.

**Skip or limit events**

**Node**

```javascript
// 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' },
  },
});
```

## $locale

Sets the locale of the field values returned by a read, or by the record a write returns. See [Retrieve localized content](https://developers.swell.is/backend-api/localization/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](https://developers.swell.is/backend-api/localization/set-locale-values).

**Retrieve localized values**

**Node**

```javascript
// 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'],
});
```

## $currency

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](https://developers.swell.is/backend-api/localization/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 prices in a currency**

**Node**

```javascript
// 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,
});
```

## $app

Sets which apps' `$app` fields are returned on reads. Defaults to the fields of all installed apps. See [Models](https://developers.swell.is/apps/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.

**Filter app fields**

**Node**

```javascript
// 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,
});
```

## $content

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](https://developers.swell.is/apps/content) in the Apps docs.

**Apply content defaults**

**Node**

```javascript
await swell.get('/products/{id}', {
  id: '5e31e67be53f9a59d89600f1',
  $content: true,
});
```

## $migrate

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](https://developers.swell.is/guides/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 record**

**Node**

```javascript
// 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,
});
```

## $replace

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.

**Replace a record**

**Node**

```javascript
// The product keeps only these fields and its id
await swell.put('/products/{id}', {
  id: '5e31e67be53f9a59d89600f1',
  $replace: {
    name: 'T-shirt',
    price: 25,
    active: true,
  },
});
```

## Endpoint options

These options apply to specific endpoints and are listed with their arguments.

- `$restock` on [Update an order](https://developers.swell.is/backend-api/orders/update-an-order)
- `$validate_stock` on [Create an order](https://developers.swell.is/backend-api/orders/create-an-order) and [Update an order](https://developers.swell.is/backend-api/orders/update-an-order)
- `$combine_items` on [Create an order](https://developers.swell.is/backend-api/orders/create-an-order), [Update an order](https://developers.swell.is/backend-api/orders/update-an-order), [Create a cart](https://developers.swell.is/backend-api/carts/create-a-cart) and [Update a cart](https://developers.swell.is/backend-api/carts/update-a-cart)
- `$validate_items` on [Create a shipment](https://developers.swell.is/backend-api/shipments/create-a-shipment) and [Update a shipment](https://developers.swell.is/backend-api/shipments/update-a-shipment)
- `$force_delete` on [Delete an account](https://developers.swell.is/backend-api/accounts/delete-an-account)
- `$bulk_count` on [Create a gift card](https://developers.swell.is/backend-api/gift-cards/create-a-gift-card)
- `$generate_variants` on [Create a product](https://developers.swell.is/backend-api/products/create-a-product) and [Update a product](https://developers.swell.is/backend-api/products/update-a-product)
- `$pricing` on [Retrieve a product](https://developers.swell.is/backend-api/products/retrieve-a-product) and [List all products](https://developers.swell.is/backend-api/products/list-all-products)
- `$recommendations` on [Retrieve a product](https://developers.swell.is/backend-api/products/retrieve-a-product)
- `$filters` on [List all products](https://developers.swell.is/backend-api/products/list-all-products)
