--- schema_version: "1" id: c766fef1edec1147c128ad9d70f9b22bfdee9b74e3ad4bfff2ee001947d72074 title: Store Associate Management API collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/store-associate-management-api.md canonical_url: https://developer.salesforce.com/docs/commerce/retail-cloud/references/store-associate-management-api source_site: developer.salesforce.com content_type: documentation content_hash: 13201a2a970d7f7fc4a75a497d264ee18144a57d7fa93203006219f0c42d7a50 products: - Point of Sale for Developers - Salesforce APIs --- Store Associate Management API # Store Associate Management API [Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/store-associate-management-api/store-associate-management-api-oas-public.yaml) POS Merchant API to create, search, update, and deactivate store associates from the POS system. **Version:** 2.3.4 ## Tags ### Store Associate Management API [Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/store-associate-management-api/store-associate-management-api-oas-public.yaml) POS Merchant API to create, search, update, and deactivate store associates from the POS system. ## Operations ### PUT Create or update store associates. `PUT /merchant/{version}/associates/bulk` Operation ID: `bulkUpsertStoreAssociate`. Tags: Store Associate Management API. Create or update a list of store associates in the POS system. The number of associates in the request must be between 1 and 100. All mandatory fields are required for each associate being created or updated. If any non-mandatory field is set to null, it overwrites the existing data with null. Update and create validation rules are applied to each associate in the request. If all associates are created or updated successfully, a successful response is returned; otherwise, the response contains error messages corresponding to the failures. ErrorMessage and code are populated for validation failures. General Validation includes: 1. Ensuring the associateList is not empty or null. 2. Performing mobile configuration ID validation. Update Validation includes: 3. Verifying that all associates to be updated exist in the system. 4. Checking for mismatches between the number of updating associates and existing associates. 5. Validating that all associate IDs in the update list exist in the system. Create Validation includes: 6. Verifying that all associates to be created do not exist in the system. #### Parameters * `version` (path, string, required) Supported: v1. Pattern: v1|v2. #### Request body Media type: `application/json`. Schema: `StoreAssociateBulkRequest`. #### Responses * **default** Default response. Media type: `application/json`. Schema: `PSResponse`. ### POST Create store associates. `POST /merchant/{version}/associates/bulk` Operation ID: `bulkCreateStoreAssociate`. Tags: Store Associate Management API. Create a list of store associates in the POS system. The number of associates in the request must be between 1 and 100. All mandatory fields are required for each associate being created. If any non-mandatory field is set to null, it overwrites the existing data with null. If all associates are created successfully, a successful response is returned. Otherwise, the response contains an errorMessage and errorCode corresponding to the failure. ErrorMessage and code are populated for validation failures. Validation includes: 1. Ensuring the associateList is not empty or null. 2. Verifying that all associates to be created do not exist in the system. 3. Performing mobile configuration ID validation. #### Parameters * `version` (path, string, required) Supported: v1. Pattern: v1|v2. #### Request body Media type: `application/json`. Schema: `StoreAssociateBulkRequest`. #### Responses * **default** Default response. Media type: `application/json`. Schema: `PSResponse`. ### PATCH Update store associates. `PATCH /merchant/{version}/associates/bulk` Operation ID: `bulkUpdateStoreAssociate`. Tags: Store Associate Management API. Update a list of store associates in the POS system. The number of associates in the request must be between 1 and 100. The update only requires the store associate ID field. Only the fields provided in the request are updated. If all associates are updated successfully, a successful response is returned. Otherwise, the response contains an errorMessage and errorCode corresponding to the failure. ErrorMessage and code are populated for validation failures. Validation includes: 1. Ensuring the associateList is not empty or null. 2. Verifying that all associates to be updated exist in the system. 3. Checking for mismatches between the number of updating associates and existing associates. 4. Validating that all associate IDs in the update list exist in the system. 5. Performing mobile configuration ID validation. #### Parameters * `version` (path, string, required) Supported: v1. Pattern: v1|v2. #### Request body Media type: `application/json`. Schema: `StoreAssociateBulkRequest`. #### Responses * **default** Default response. Media type: `application/json`. Schema: `PSResponse`. ### GET Retrieve store associates. `GET /merchant/{version}/associates` Operation ID: `getStoreAssociates`. Tags: Store Associate Management API. Retrieve active or inactive store associates based on query parameters storeId and associateId. Both query parameters are optional. #### Parameters * `PredictSpring-Secret` (header, string) * `version` (path, string, required) Supported: v1. Pattern: v1|v2. * `storeId` (query, string) * `associateId` (query, string) * `active` (query, string) #### Responses * **default** Default response. Media type: `application/json`. Schema: `StoreAssociateSearchResponse`. ### PUT Update store associate. `PUT /merchant/{version}/associates` Operation ID: `updateStoreAssociate`. Tags: Store Associate Management API. Update a store associate in the POS system. If the associate is updated successfully, the same associate details are returned. Otherwise, the response contains ErrorMessage and ErrorCode corresponding to the failure. #### Parameters * `PredictSpring-Secret` (header, string) * `version` (path, string, required) Supported: v1. Pattern: v1|v2. #### Request body Media type: `application/json`. Schema: `Associate`. #### Responses * **default** Default response. Media type: `application/json`. Schema: `StoreAssociateSearchResponse`. ### POST Create store associate. `POST /merchant/{version}/associates` Operation ID: `createStoreAssociate`. Tags: Store Associate Management API. Create a store associate in the POS system. If the associate is created successfully, the same associate details are returned. Otherwise, the response contains ErrorMessage and ErrorCode corresponding to the failure. #### Parameters * `PredictSpring-Secret` (header, string) * `version` (path, string, required) Supported: v1. Pattern: v1|v2. #### Request body Media type: `application/json`. Schema: `Associate`. #### Responses * **default** Default response. Media type: `application/json`. Schema: `StoreAssociateSearchResponse`. ### DELETE Deactivate store associate. `DELETE /merchant/{version}/associates` Operation ID: `deleteStoreAssociate`. Tags: Store Associate Management API. Deactivate a store associate from the POS system corresponding to the associateId query parameter. On successful deactivation, the active field on the associate is set to false, and the response contains the deactivated associate details. If unsuccessful, the response contains the ErrorMessage and ErrorCode corresponding to the failure. #### Parameters * `PredictSpring-Secret` (header, string) * `version` (path, string, required) Supported: v1. Pattern: v1|v2. * `associateId` (query, string) #### Responses * **default** Default response. Media type: `application/json`. Schema: `StoreAssociateSearchResponse`. ### GET Retrieve store associate. `GET /merchant/{version}/associates/{associateId}` Operation ID: `getStoreAssociate`. Tags: Store Associate Management API. Retrieve store associate details by associateId. #### Parameters * `PredictSpring-Secret` (header, string) * `version` (path, string, required) Supported: v1. Pattern: v1|v2. * `associateId` (path, string, required) #### Responses * **default** Default response. Media type: `application/json`. Schema: `Associate`. ## Schemas ### StoreAssociateBulkRequest * `associateList` (_array of Associate_, required) List of associates to create, update, or upsert in the POS System. This list must contain at least 1 associate and no more than 100 associates. Minimum items: 1. Maximum items: 100. ### PSResponse * `errorMessage` (_string_, nullable) Error message shown to the user. Example: `Invalid request. Please check the request and try again.`. * `errorCode` (_string_, nullable) Error code shown to the user. Example: `INTERNAL_ERROR`. * `error` (_boolean_) ### StoreAssociateSearchResponse * `errorMessage` (_string_, nullable) Error message shown to the user. Example: `Invalid request. Please check the request and try again.`. * `errorCode` (_string_, nullable) Error code shown to the user. Example: `INTERNAL_ERROR`. * `storeAssociates` (_array of Associate_) List of the store associates. It can have a single associate, the associates from a store, or all associates. * `error` (_boolean_) ### Associate Store associate. * `storeAssociateID` (_string_) ID of the store associate (POS login ID for the associate). * `storeID` (_string_, nullable) Store ID of the associate. * `merchantUserID` (_string_, nullable) Merchant's underlying system's user ID for the store associates. For example, LoginId for underlying OMS or Salseforce Commerce. * `paymentDeviceMerchantID` (_string_, nullable) Merchant ID of a payment device assigned to the associate. * `paymentDeviceID` (_string_, nullable) ID of a payment device, like terminal ID, assigned to the associate. * `storeAssociatePassword` (_string_) Store associate's password (POS Login Password for the associate). * `merchantPassword` (_string_, nullable) Merchant's underlying system's password for the associate. * `storeAssociatePasswordPin` (_string_, nullable) Password hint for the associate's POS login. * `firstName` (_string_, nullable) First name of the associate. * `lastName` (_string_, nullable) Last name of the associate. * `storeType` (_string_) Type of the store where the associate works. Possible values include: Regular, Popup, Outlet or eComm. * `role` (_string_) The associate's role in the store. Possible values include: STORE\_ASSOCIATE, STORE\_MANAGER or AREA\_MANAGER. * `passwordSetOn` (_integer (int64)_, nullable) Date when password was set last time. Represented as the number of milliseconds since epoch. * `storeAssociatePasswordFlag` (_boolean_) Flag indicating that the store associate password is updated during associate update operation. Used only during update operation. * `merchantPasswordFlag` (_boolean_) Flag indicating that the merchant password is updated during associate update operation. Used only during update operation. * `storeAssociateSecretFlag` (_boolean_, nullable) Flag indicating that the store associate secret is updated during associate update operation. Used only during update operation. * `imageUrl` (_string_, nullable) The associate's image URL. * `active` (_boolean_) Specifies whether the status of the associate is active (true) or removed/deactivated (false). * `emailId` (_string_, nullable) Email ID of the associate. * `mobilePhoneNumber` (_string_, nullable) Mobile phone number of the associate. * `additionalStoreIDs` (_array of string_, nullable) Additional store IDs where the associate can log in. * `gender` (_string_) Gender of the store associate. Allowed values: `Male`, `Female`, `Neutral`, `Unknown`. * `hireDate` (_integer (int64)_, nullable) Date when the associate is hired or can start work in the store. * `terminationDate` (_integer (int64)_, nullable) Termination date for the associate. * `firstLoginPasswordReset` (_boolean_) Flag indicating that the password is set on the first login. * `mobileConfigID` (_string_, nullable) Mobile configuration ID. Maximum length: 128. Example: `134ac374-0f49-4239-a161-ccfe4d3d7686`.