> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

# BulkUpsertAttributeValues

# Package: attributes

# Namespace: AttributeValuesService

# Method link: https://dev.wix.com/docs/api-reference/business-solutions/bookings/resources/attributes/attribute-value/bulk-upsert-attribute-values.md

## Permission Scopes:
Manage_Wix_Attributes_Forms_submissions: SCOPE.ATTRIBUTES.MANAGE

## Introduction

Upserts attribute values for an entity.

Each entry in `values` is upserted by its `attributeDefinitionId`: a matching value is updated, otherwise a new one is created. Existing attribute values for this entity that aren't in the list are left unchanged. The order of returned values isn't guaranteed; sort client-side if you need a stable order.

To retrieve the resulting values paired with their definitions, call List Entity Attributes.

---

## REST API

### Schema

```
 Method: bulkUpsertAttributeValues
 Description: Upserts attribute values for an entity.  Each entry in `values` is upserted by its `attributeDefinitionId`: a matching value is updated, otherwise a new one is created. Existing attribute values for this entity that aren't in the list are left unchanged. The order of returned values isn't guaranteed; sort client-side if you need a stable order.  To retrieve the resulting values paired with their definitions, call List Entity Attributes.
 URL: https://www.wixapis.com/_api/attributes/v1/attribute-values/{entityId}/bulk-upsert
 Method: POST
 # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present.
 Required parameters:  values.attributeDefinitionId
 Method parameters: 
   param name: returnEntity | type: returnEntity | description: Whether to return the upserted attribute values in the response.  
   param name: values | type: array<values> | description: Attribute values to upsert for this entity. Each entry is matched by `attribute_definition_id`. Values not listed aren't modified.  | validation: minItems 1, maxItems 50
              - ONE-OF: 
                 - name: stringData | type: string | description: Value for STRING-type attribute. Must be in StringConfig.allowed_values.  | validation: maxLength 40
                 - name: numberData | type: integer | description: Value for NUMBER-type attribute. Must be within NumberConfig [min, max].  
                 - name: boolData | type: boolean | description: Value for BOOL-type attribute.  
              - name: attributeDefinitionId | type: string | description: GUID of the attribute definition this value applies to. | required: true | validation: format GUID
 Return type: BulkUpsertAttributeValuesResponse
  - name: results | type: array<BulkUpsertAttributeValueResult> | description: Upsert results, one per requested value, in request order.  | validation: minItems 1, maxItems 50
     - name: action | type: BulkActionType | description: Whether the value was inserted or updated.  
         - enum: INSERT, UPDATE, DELETE
     - name: itemMetadata | type: ItemMetadata | description: Per-item metadata (id, original index, success).  
        - name: id | type: string | description: Item GUID. Provided only whenever possible. For example, `itemId` can't be provided when item creation has failed.  | validation: format GUID
        - name: originalIndex | type: integer | description: Index of the item within the request array. Allows for correlation between request and response items.  | validation: minimum 0
        - name: success | type: boolean | description: Whether the requested action for this item was successful. When `false`, the `error` field is returned.  
        - name: error | type: ApplicationError | description: Details about the error in case of failure.  
           - name: code | type: string | description: Error code.  
           - name: description | type: string | description: Description of the error.  
           - name: data | type: object | description: Data related to the error.  
     - name: item | type: AttributeValue | description: The upserted value. Only returned when `return_entity` is `true` in the request.  
        - ONE-OF: 
           - name: stringData | type: string | description: Value for STRING-type attribute. Must be in StringConfig.allowed_values.  | validation: maxLength 40
           - name: numberData | type: integer | description: Value for NUMBER-type attribute. Must be within NumberConfig [min, max].  
           - name: boolData | type: boolean | description: Value for BOOL-type attribute.  
        - name: id | type: string | description: Attribute value GUID.  | validation: format GUID
        - name: revision | type: string | description: Revision number, which increments by 1 each time the attribute value is updated.  | validation: format int64
        - name: createdDate | type: string | description: Date and time the attribute value was created.  | validation: format date-time
        - name: updatedDate | type: string | description: Date and time the attribute value was last updated.  | validation: format date-time
        - name: attributeDefinitionId | type: string | description: GUID of the attribute definition this value belongs to.  | validation: format GUID
        - name: entityId | type: string | description: GUID of the entity this value belongs to. An entity is any resource your application owns (in the current Rentals integration, a Bookings resource); this API does not validate it. Use the same GUID passed to `BulkUpsertAttributeValues` and `ListEntityAttributes`.  | validation: format GUID
        - name: valueType | type: ValueType | description: Value type of this attribute. Matches the related attribute definition's value_type. Set on create and never changes.  
             - enum:
             -     STRING: String attribute: single-select from a predefined list of allowed string values.
             -     NUMBER: Integer number attribute with a required min/max range.
             -     BOOL: Boolean attribute (true/false).
        - name: extendedFields | type: ExtendedFields | description: Custom field data for the attribute value. [Extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md) must be configured in the app dashboard before they can be accessed with API calls.  
           - name: namespaces | type: object | description: Extended field data. Each key corresponds to the namespace of the app that created the extended fields. The value of each key is structured according to the schema defined when the extended fields were configured.  You can only access fields for which you have the appropriate permissions.  Learn more about [extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md).  | validation: format map
  - name: bulkActionMetadata | type: BulkActionMetadata | description: Bulk action metadata (success and failure counts).  
     - name: totalSuccesses | type: integer | description: Number of items that were successfully processed.  | validation: minimum 0
     - name: totalFailures | type: integer | description: Number of items that couldn't be processed.  | validation: minimum 0
     - name: undetailedFailures | type: integer | description: Number of failures without details because detailed failure threshold was exceeded.  | validation: minimum 0

 Possible Errors:
   HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: VALUE_OUT_OF_RANGE | Description: A number value is outside the definition's configured `min`/`max` range.
   HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: VALUE_NOT_IN_ALLOWED_VALUES | Description: A string value is not one of the definition's configured `allowedValues`.
   HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: VALUE_TYPE_MISMATCH | Description: An entry's value variant does not match the referenced attribute definition's `valueType`.
   HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: VALUE_REQUIRED | Description: An entry has no value set.
   HTTP Code: 404 | Status Code: NOT_FOUND | Application Code: ATTRIBUTE_DEFINITION_NOT_FOUND | Description: Couldn't find the attribute definition referenced by an entry.


```

### Examples

### Upsert attribute values for an entity.
```curl
curl -X POST \
'https://www.wixapis.com/attributes/v1/attribute-values/5a9b3e88-1f6c-4f3b-9c7e-08e2f3b5a1b2/bulk-upsert' \
-H 'Authorization: <AUTH>' \
-H 'Content-Type: application/json' \
-d '{
  "values": [
    {
      "attributeDefinitionId": "d7a341c4-196b-46e7-813c-2b0fc1847ec6",
      "numberData": 4
    }
  ],
  "returnEntity": true
}'
```

---

## JavaScript SDK

### Schema

```
 Method: wixClientAdmin.bookings.attributeValue.bulkUpsertAttributeValues(entityId, options)
 Description: Upserts attribute values for an entity.  Each entry in `values` is upserted by its `attributeDefinitionId`: a matching value is updated, otherwise a new one is created. Existing attribute values for this entity that aren't in the list are left unchanged. The order of returned values isn't guaranteed; sort client-side if you need a stable order.  To retrieve the resulting values paired with their definitions, call List Entity Attributes.
 # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present.
 Required parameters:  entityId, optionss.attributeDefinitionId
 Method parameters: 
   param name: entityId | type: string | description: GUID of the entity whose attribute values to update. | required: true | validation: format GUID
   param name: options | type: BulkUpsertAttributeValuesOptions  none  
        - name: values | type: array<BulkUpsertAttributeValue> | description: Attribute values to upsert for this entity. Each entry is matched by `attribute_definition_id`. Values not listed aren't modified.  | validation: minItems 1, maxItems 50
           - ONE-OF: 
              - name: stringData | type: string | description: Value for STRING-type attribute. Must be in StringConfig.allowed_values.  | validation: maxLength 40
              - name: numberData | type: integer | description: Value for NUMBER-type attribute. Must be within NumberConfig [min, max].  
              - name: boolData | type: boolean | description: Value for BOOL-type attribute.  
           - name: attributeDefinitionId | type: string | description: GUID of the attribute definition this value applies to.  | validation: format GUID
        - name: returnEntity | type: boolean | description: Whether to return the upserted attribute values in the response.  
 Return type: PROMISE<BulkUpsertAttributeValuesResponse>
  - name: results | type: array<BulkUpsertAttributeValueResult> | description: Upsert results, one per requested value, in request order.  | validation: minItems 1, maxItems 50
     - name: action | type: BulkActionType | description: Whether the value was inserted or updated.  
         - enum: INSERT, UPDATE, DELETE
     - name: itemMetadata | type: ItemMetadata | description: Per-item metadata (id, original index, success).  
        - name: _id | type: string | description: Item GUID. Provided only whenever possible. For example, `itemId` can't be provided when item creation has failed.  | validation: format GUID
        - name: originalIndex | type: integer | description: Index of the item within the request array. Allows for correlation between request and response items.  | validation: minimum 0
        - name: success | type: boolean | description: Whether the requested action for this item was successful. When `false`, the `error` field is returned.  
        - name: error | type: ApplicationError | description: Details about the error in case of failure.  
           - name: code | type: string | description: Error code.  
           - name: description | type: string | description: Description of the error.  
           - name: data | type: object | description: Data related to the error.  
     - name: item | type: AttributeValue | description: The upserted value. Only returned when `return_entity` is `true` in the request.  
        - ONE-OF: 
           - name: stringData | type: string | description: Value for STRING-type attribute. Must be in StringConfig.allowed_values.  | validation: maxLength 40
           - name: numberData | type: integer | description: Value for NUMBER-type attribute. Must be within NumberConfig [min, max].  
           - name: boolData | type: boolean | description: Value for BOOL-type attribute.  
        - name: _id | type: string | description: Attribute value GUID.  | validation: format GUID
        - name: revision | type: string | description: Revision number, which increments by 1 each time the attribute value is updated.  | validation: format int64
        - name: _createdDate | type: Date | description: Date and time the attribute value was created.  
        - name: _updatedDate | type: Date | description: Date and time the attribute value was last updated.  
        - name: attributeDefinitionId | type: string | description: GUID of the attribute definition this value belongs to.  | validation: format GUID
        - name: entityId | type: string | description: GUID of the entity this value belongs to. An entity is any resource your application owns (in the current Rentals integration, a Bookings resource); this API does not validate it. Use the same GUID passed to `BulkUpsertAttributeValues` and `ListEntityAttributes`.  | validation: format GUID
        - name: valueType | type: ValueType | description: Value type of this attribute. Matches the related attribute definition's value_type. Set on create and never changes.  
             - enum:
             -     STRING: String attribute: single-select from a predefined list of allowed string values.
             -     NUMBER: Integer number attribute with a required min/max range.
             -     BOOL: Boolean attribute (true/false).
        - name: extendedFields | type: ExtendedFields | description: Custom field data for the attribute value. [Extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md) must be configured in the app dashboard before they can be accessed with API calls.  
           - name: namespaces | type: object | description: Extended field data. Each key corresponds to the namespace of the app that created the extended fields. The value of each key is structured according to the schema defined when the extended fields were configured.  You can only access fields for which you have the appropriate permissions.  Learn more about [extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md).  | validation: format map
  - name: bulkActionMetadata | type: BulkActionMetadata | description: Bulk action metadata (success and failure counts).  
     - name: totalSuccesses | type: integer | description: Number of items that were successfully processed.  | validation: minimum 0
     - name: totalFailures | type: integer | description: Number of items that couldn't be processed.  | validation: minimum 0
     - name: undetailedFailures | type: integer | description: Number of failures without details because detailed failure threshold was exceeded.  | validation: minimum 0

 Possible Errors:
   HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: VALUE_OUT_OF_RANGE | Description: A number value is outside the definition's configured `min`/`max` range.
   HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: VALUE_NOT_IN_ALLOWED_VALUES | Description: A string value is not one of the definition's configured `allowedValues`.
   HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: VALUE_TYPE_MISMATCH | Description: An entry's value variant does not match the referenced attribute definition's `valueType`.
   HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: VALUE_REQUIRED | Description: An entry has no value set.
   HTTP Code: 404 | Status Code: NOT_FOUND | Application Code: ATTRIBUTE_DEFINITION_NOT_FOUND | Description: Couldn't find the attribute definition referenced by an entry.


```

### Examples

### Upsert attribute values for an entity
```javascript
import { attributeValue } from "@wix/bookings";

const entityId = "5a9b3e88-1f6c-4f3b-9c7e-08e2f3b5a1b2";
const options = {
  values: [
    { attributeDefinitionId: "d7a341c4-196b-46e7-813c-2b0fc1847ec6", numberData: 4 },
  ],
  returnEntity: true,
};

async function bulkUpsertAttributeValues() {
  const response = await attributeValue.bulkUpsertAttributeValues(entityId, options);
}

/* Promise resolves to:
 * {
 *   "results": [
 *     {
 *       "action": "INSERT",
 *       "itemMetadata": { "id": "b1e6f0a2-3c4d-4e5f-9a8b-1c2d3e4f5a6b", "originalIndex": 0, "success": true },
 *       "item": {
 *         "_id": "b1e6f0a2-3c4d-4e5f-9a8b-1c2d3e4f5a6b",
 *         "attributeDefinitionId": "d7a341c4-196b-46e7-813c-2b0fc1847ec6",
 *         "entityId": "5a9b3e88-1f6c-4f3b-9c7e-08e2f3b5a1b2",
 *         "valueType": "NUMBER",
 *         "numberData": 4
 *       }
 *     }
 *   ],
 *   "bulkActionMetadata": { "totalSuccesses": 1, "totalFailures": 0 }
 * }
 */

```

### bulkUpsertAttributeValues (self-hosted)
Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md).

```javascript
import { createClient } from '@wix/sdk';
import { attributeValue } from '@wix/bookings';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { attributeValue },
  // Include the auth strategy and host as relevant
});


async function bulkUpsertAttributeValues(entityId,options) {
  const response = await myWixClient.attributeValue.bulkUpsertAttributeValues(entityId,options);
};
```

---