## Promotions --- ### Get all promotions of a customer --- This method retrieves all available promotions that are defined for a customer.
The API key must have the `PROMOTIONS_DETAILS_FOR_CLIENT_READ` permission from the **Client** group.
**Method name:** Promotions.getPromotions(statuses, types, page) Promotions.getPromotions(statuses, types, limit, page) Promotions.getPromotions(statuses, types, page, includeMeta) Promotions.getPromotions(promotionsApiQuery)
Methods using arguments are now deprecated. Only Promotions.getPromotions(promotionsApiQuery) is valid.
**Declaration:**
```java public static IDataApiCall getPromotions(@Nullable List statuses, @Nullable List types, int page) public static IDataApiCall getPromotions(@Nullable List statuses, @Nullable List types, int limit, int page) public static IDataApiCall getPromotions(@Nullable List statuses, @Nullable List types, int page, boolean includeMeta) public static IDataApiCall getPromotions(PromotionsApiQuery promotionsApiQuery) ```
```kotlin fun getPromotions(@Nullable statuses:List, @Nullable types:List, page:Int):IDataApiCall fun getPromotions(@Nullable statuses:List, @Nullable types:List, limit:Int, page:Int):IDataApiCall fun getPromotions(@Nullable statuses:List, @Nullable types:List, page:Int, includeMeta:Boolean):IDataApiCall fun getPromotions(promotionsApiQuery:PromotionsApiQuery):IDataApiCall ```
**Parameters:** | Parameter | Type | Mandatory | Default | Description | | --- | --- | --- | --- | --- | | **statuses** | List | yes | - | Specify a status filter, can be any combination or an empty list. | | **types** | List | yes | - | Specify type filter, can be any combination or an empty list. | | **page** | int | yes | - | Query for a specific page, minimum 1. | | **limit** | int | yes | 100 | Query for promotions limit. | | **includeMeta** | boolean | yes | false | Decide whether to include metadata in the final response. | | **promotionsApiQuery** | [PromotionsApiQuery](/developers/mobile-sdk/class-reference/android/promotions-and-vouchers#promotionsapiquery) | yes | --- | Class responsible for storing all queryParameters. | **Return Value:** IDataApiCall<[PromotionResponse](/developers/mobile-sdk/class-reference/android/promotions-and-vouchers#promotionresponse)> object to execute the request. **Example:**
```java if (apiCall != null) apiCall.cancel(); PromotionsApiQuery query = new PromotionsApiQuery(); query.limit = limit; query.statuses = statuses; query.page = 5; query.includeMeta = true; LinkedHashMap sortParams = new LinkedHashMap<>(); sortParams.put(PromotionSortingKey.TYPE, ApiQuerySortingOrder.ASCENDING); sortParams.put(PromotionSortingKey.CREATED_AT, ApiQuerySortingOrder.ASCENDING); sortParams.put(PromotionSortingKey.EXPIRE_AT, ApiQuerySortingOrder.DESCENDING); query.setSortParameters(sortParams); apiCall = Promotions.getPromotions(query); apiCall.execute(this::onSuccess, this::onFailure); ```
```kotlin if (apiCall != null) apiCall.cancel() val query = PromotionsApiQuery() query.limit = limit query.statuses = statuses query.page = 5 query.includeMeta = true val sortParams = LinkedHashMap() sortParams.put(PromotionSortingKey.TYPE, ApiQuerySortingOrder.ASCENDING) sortParams.put(PromotionSortingKey.CREATED_AT, ApiQuerySortingOrder.ASCENDING) sortParams.put(PromotionSortingKey.EXPIRE_AT, ApiQuerySortingOrder.DESCENDING) query.setSortParameters(sortParams) apiCall = Promotions.getPromotions(query) apiCall.execute(({ this.onSuccess() }), ({ this.onFailure() })) ```
### Get promotion by UUID --- This method retrieves the promotion with the specified UUID.
The API key must have the `PROMOTIONS_DETAILS_FOR_CLIENT_READ` permission from the **Client** group.
**Method name:** Promotions.getPromotionByUuid(uuid) **Declaration:**
```java public static IDataApiCall getPromotionByUuid(@NonNull String uuid) ```
```kotlin fun getPromotionByUuid(@NonNull uuid:String):IDataApiCall ```
**Parameters:** | Parameter | Type | Mandatory | Default | Description | | --- | --- | --- | --- | --- | | **uuid** | String | yes | - | UUID of the promotion that you want to get. | **Return Value:** IDataApiCall<[SinglePromotionResponse](/developers/mobile-sdk/class-reference/android/promotions-and-vouchers#singlepromotionresponse)> object to execute the request. **Example:**
```java IDataApiCall apiCall = Promotions.getPromotionByUuid(uuid); apiCall.execute(response -> { if (response != null) { Promotion promotion = response.getPromotion(); } }, this::showAlertError); ```
```kotlin val apiCall = Promotions.getPromotionByUuid(uuid) apiCall.execute({ response-> if (response != null) { val promotion = response.getPromotion() } }, ({ this.showAlertError() })) ```
### Get promotion by code --- This method retrieves the promotion with the specified code.
The API key must have the `PROMOTIONS_DETAILS_FOR_CLIENT_READ` permission from the **Client** group.
**Method name:** Promotions.getPromotionByCode(code) **Declaration:**
```java public static IDataApiCall getPromotionByCode(@NonNull String code) ```
```kotlin fun getPromotionByCode(@NonNull code:String):IDataApiCall ```
**Parameters:** | Parameter | Type | Mandatory | Default | Description | | --- | --- | --- | --- | --- | | **code** | String | yes | - | Code of the promotion that you want to get. | **Return Value:** IDataApiCall<[SinglePromotionResponse](/developers/mobile-sdk/class-reference/android/promotions-and-vouchers#singlepromotionresponse)> object to execute the request. **Example:**
```java IDataApiCall apiCall = Promotions.getPromotionByCode(code); apiCall.execute(response -> { if (response != null) { Promotion promotion = response.getPromotion(); } }, this::showAlertError); ```
```kotlin val apiCall = Promotions.getPromotionByCode(code) apiCall.execute({ response-> if (response != null) { val promotion = response.getPromotion() } }, ({ this.showAlertError() })) ```
### Activate promotion by UUID --- This method activates the promotion with the specified UUID.
The API key must have the `PROMOTIONS_ACTIVATE_PROMOTIONS_UPDATE` permission from the **Promotions** group.
**Method name:** Promotions.activatePromotionByUuid(uuid) **Declaration:**
```java public static IApiCall activatePromotionByUuid(@NonNull String uuid) ```
```kotlin fun activatePromotionByUuid(@NonNull uuid:String):IApiCall ```
**Parameters:** | Parameter | Type | Mandatory | Default | Description | | --- | --- | --- | --- | --- | | **uuid** | String | yes | - | UUID of the promotion that will be activated. | **Return Value:** IApiCall object to execute the request. **Example:**
```java IApiCall apiCall = Promotions.activatePromotionByUuid(uuid); apiCall.execute(this::onSuccess, this::onFailure); ```
```kotlin val apiCall = Promotions.activatePromotionByUuid(uuid) apiCall.execute(({ this.onSuccess() }), ({ this.onFailure() })) ```
### Activate promotion by code --- This method activates the promotion with the specified code.
The API key must have the `PROMOTIONS_ACTIVATE_PROMOTIONS_UPDATE` permission from the **Promotions** group.
**Method name:** Promotions.activatePromotionByCode(code) **Declaration:**
```Java public static IApiCall activatePromotionByCode(@NonNull String code) ```
```Kotlin fun activatePromotionByCode(@NonNull code:String):IApiCall ```
**Parameters:** | Parameter | Type | Mandatory | Default | Description | | --- | --- | --- | --- | --- | | **code** | String | yes | - | Code of the promotion that will be activated. | **Return Value:** IApiCall object to execute the request. **Example:**
```Java IApiCall apiCall = Promotions.activatePromotionByCode(code); ```
```Kotlin var apiCall = Promotions.activatePromotionByCode(code) ```
### Activate promotions in a batch --- This method activates promotions with a code or with UUID in a batch.
The API key must have the `PROMOTIONS_ACTIVATE_PROMOTIONS_UPDATE` permission from the **Promotions** group.
**Method name:** Promotions.activatePromotionsBatch(promotionsToActivate) **Declaration:**
```java public static IApiCall activatePromotionsBatch(List promotionsToActivate) ```
```kotlin fun activatePromotionsBatch(promotionsToActivate:List):IApiCall ```
**Parameters:** | Parameter | Type | Mandatory | Default | Description | | --- | --- | --- | --- | --- | | **promotionsToActivate** | List<[PromotionIdentifier](/developers/mobile-sdk/class-reference/android/promotions-and-vouchers#promotionidentifier)> | yes | - | List of promotions to be activated | **Return Value:** IApiCall object to execute the request. **Example:**
```java IApiCall call = Promotions.activatePromotionsBatch(promotionsToActivate); call.execute(this::onSuccess, this::onFailure); ```
```kotlin val call = Promotions.activatePromotionsBatch(promotionsToActivate) call.execute(({ this.onSuccess() }), ({ this.onFailure() })) ```
### Deactivate promotion by UUID --- This method deactivates the promotion with the specified UUID.
The API key must have the `PROMOTIONS_DEACTIVATE_PROMOTIONS_UPDATE` permission from the **Promotions** group.
**Method name:** Promotions.deactivatePromotionByUuid(uuid) **Declaration:**
```java public static IApiCall deactivatePromotionByUuid(@NonNull String uuid) ```
```kotlin fun deactivatePromotionByUuid(@NonNull uuid:String):IApiCall ```
**Parameters:** | Parameter | Type | Mandatory | Default | Description | | --- | --- | --- | --- | --- | | **uuid** | String | yes | - | UUID of the promotion that will be deactivated. | **Return Value:** IApiCall object to execute the request. **Example:**
```java IApiCall apiCall = Promotions.deactivatePromotionByUuid(uuid); apiCall.execute(this::onSuccess, this::onFailure); ```
```kotlin val apiCall = Promotions.deactivatePromotionByUuid(uuid) apiCall.execute(({ this.onSuccess() }), ({ this.onFailure() })) ```
### Deactivate promotion by code --- This method deactivates the promotion with the specified code.
The API key must have the `PROMOTIONS_DEACTIVATE_PROMOTIONS_UPDATE` permission from the **Promotions** group.
**Method name:** Promotions.deactivatePromotionByCode(code) **Declaration:**
```java public static IApiCall deactivatePromotionByCode(@NonNull String code) ```
```kotlin fun deactivatePromotionByCode(@NonNull code:String):IApiCall ```
**Parameters:** | Parameter | Type | Mandatory | Default | Description | | --- | --- | --- | --- | --- | | **code** | String | yes | - | Code of the promotion that will be deactivated. | **Return Value:** IApiCall object to execute the request. **Example:**
```java IApiCall apiCall = Promotions.deactivatePromotionByCode(code); apiCall.execute(this::onSuccess, this::onFailure); ```
```kotlin val apiCall = Promotions.deactivatePromotionByCode(code) apiCall.execute(({ this.onSuccess() }), ({ this.onFailure() })) ```
### Deactivate promotions in a batch --- This method deactivates promotions with a code or with UUID in a batch.
The API key must have the `PROMOTIONS_DEACTIVATE_PROMOTIONS_UPDATE` permission from the **Promotions** group.
**Method name:** Promotions.deactivatePromotionsBatch(promotionsToDeactivate) **Declaration:**
```java public static IApiCall deactivatePromotionsBatch(List promotionsToDeactivate) ```
```kotlin fun deactivatePromotionsBatch(promotionsToDeactivate:List):IApiCall ```
**Parameters:** | Parameter | Type | Mandatory | Default | Description | | --- | --- | --- | --- | --- | | **promotionsToDeactivate** | List<[PromotionIdentifier](/developers/mobile-sdk/class-reference/android/promotions-and-vouchers#promotionidentifier)> | yes | - | List of promotions to be activated | **Return Value:** IApiCall object to execute the request. **Example:**
```java IApiCall call = Promotions.deactivatePromotionsBatch(promotionsToDeactivate); call.execute(this::onSuccess, this::onFailure); ```
```kotlin val call = Promotions.deactivatePromotionsBatch(promotionsToDeactivate) call.execute(({ this.onSuccess() }), ({ this.onFailure() })) ```
## Vouchers --- ### Get or assign voucher from pool --- This method retrieves an assigned voucher code or assigns a voucher from a pool identified by UUID to the customer. Once a voucher is assigned using this method, **the same** voucher is returned for the profile every time the method is called. When the voucher is assigned for the first time, a [voucherCode.assigned](/docs/assets/events/event-reference/loyalty#vouchercodeassigned) event is produced.
The API key must have the `VOUCHERS_ITEM_ASSIGN_CREATE` and `VOUCHERS_ITEM_ASSIGN_READ` permission from the **Assign** group.
**Declared In:** Headers/SNRPromotions.h **Related To:** [AssignVoucherResponse](/developers/mobile-sdk/class-reference/ios/promotions-and-vouchers#assignvoucherresponse) **Class:** [Promotions](/developers/mobile-sdk/class-reference/ios/modules#promotions) **Declaration:**
```Swift static func getOrAssignVoucher(poolUUID: String, success: ((AssignVoucherResponse) -> Void), failure: ((ApiError) -> Void)) -> Void ```
```Objective-C + (void)getOrAssignVoucherWithPoolUUID:(nonnull NSString *)poolUUID success:(nonnull void (^)(SNRAssignVoucherResponse *assignVoucherResponse))success failure:(nonnull void (^)(NSError *error))failure ```
**Parameters:** | Parameter | Type | Mandatory | Default | Description | | --- | --- | --- | --- | --- | | **poolUUID** | String | no | - | Unique identifier of a code pool | | **success** | (([AssignVoucherResponse](/developers/mobile-sdk/class-reference/ios/promotions-and-vouchers#assignvoucherresponse)) -> Void) | yes | - | Closure/Block to be executed when the operation is completed successfully | | **failure** | (([ApiError](/developers/mobile-sdk/class-reference/ios/miscellaneous#snrapierror)) -> Void) | yes | - | Closure/Block to be executed when the operation is completed with an error | **Return Value:** No value is returned. **Example:**
```Swift let poolUUID: String = "POOL_UUID" Promotions.getOrAssignVoucher(poolUUID: poolUUID, success: { (assignVoucherResponse) in // success failure: { (error) in // failure }) ```
```Objective-C NSString *poolUUID = @"POOL_UUID"; [SNRPromotions getOrAssignVoucherWithPoolUUID:poolUUID success:^(SNRAssignVoucherResponse *assignVoucherResponse) { // success } failure:^(NSError * _Nonnull error) { // failure }]; ```
### Assign voucher code from pool --- This method assigns a voucher from a pool identified by UUID to the profile. Every request returns a **different code** until the pool is empty. A [voucherCode.assigned](/docs/assets/events/event-reference/loyalty#vouchercodeassigned) event is produced.
Returns the HTTP 416 status code when the pool is empty.
The API key must have the `VOUCHERS_ITEM_ASSIGN_CREATE` and `VOUCHERS_ITEM_ASSIGN_READ` permission from the **Assign** group.
**Declared In:** Headers/SNRPromotions.h **Related To:** [AssignVoucherResponse](/developers/mobile-sdk/class-reference/ios/promotions-and-vouchers#assignvoucherresponse) **Class:** [Promotions](/developers/mobile-sdk/class-reference/ios/modules#promotions) **Declaration:**
```Swift static func assignVoucherCode(poolUUID: String, success: ((AssignVoucherResponse) -> Void), failure: ((ApiError) -> Void)) -> Void ```
```Objective-C + (void)assignVoucherCodeWithPoolUUID:(nonnull NSString *)poolUUID success:(nonnull void (^)(SNRAssignVoucherResponse *assignVoucherResponse))success failure:(nonnull void (^)(NSError *error))failure ```
**Parameters:** | Parameter | Type | Mandatory | Default | Description | | --- | --- | --- | --- | --- | | **poolUUID** | String | yes | - | Unique identifier of a code pool | | **success** | (([AssignVoucherResponse](/developers/mobile-sdk/class-reference/ios/promotions-and-vouchers#assignvoucherresponse)) -> Void) | yes | - | Closure/Block to be executed when the operation is completed successfully | | **failure** | (([ApiError](/developers/mobile-sdk/class-reference/ios/miscellaneous#snrapierror)) -> Void) | yes | - | Closure/Block to be executed when the operation is completed with an error | **Return Value:** No value is returned. **Example:**
```Swift let poolUUID: String = "POOL_UUID" Promotions.assignVoucherCode(poolUUID: poolUUID, success: { (assignVoucherResponse) in // success }, failure: { (error) in // failure }) ```
```Objective-C NSString *poolUUID = @"POOL_UUID"; [SNRPromotions assignVoucherCodeWithPoolUUID:poolUUID success:^(SNRAssignVoucherResponse *assignVoucherResponse) { // success } failure:^(SNRApiError *error) { // failure }]; ```
### Get voucher codes assigned to customer --- This method retrieves voucher codes for a customer.
The API key must have the `VOUCHERS_ITEM_ASSIGN_READ` permission from the **Assign** group.
**Declared In:** Headers/SNRPromotions.h **Related To:** [VoucherCodesResponse](/developers/mobile-sdk/class-reference/ios/promotions-and-vouchers#vouchercodesresponse) **Class:** [Promotions](/developers/mobile-sdk/class-reference/ios/modules#promotions) **Declaration:**
```Swift static func getAssignedVoucherCodes(success: ((VoucherCodesResponse) -> Void), failure: ((ApiError) -> Void)) -> Void ```
```Objective-C + (void)getAssignedVoucherCodesWithSuccess:(nonnull void (^)(SNRVoucherCodesResponse *voucherCodesResponse))success failure:(nonnull void (^)(NSError *error))failure ```
**Parameters:** | Parameter | Type | Mandatory | Default | Description | | --- | --- | --- | --- | --- | | **success** | ((VoucherCodesResponse) -> Void) | yes | - | Closure/Block to be executed when the operation is completed successfully | | **failure** | (([ApiError](/developers/mobile-sdk/class-reference/ios/miscellaneous#snrapierror)) -> Void) | yes | - | Closure/Block to be executed when the operation is completed with an error | **Return Value:** No value is returned. **Example:**
```Swift Promotions.getAssignedVoucherCodes(success: { (voucherCodesResponse) in // success }, failure: { (error) in // failure }) ```
```Objective-C [SNRPromotions getAssignedVoucherCodesWithSuccess:^(SNRVoucherCodesResponse *voucherCodesResponse) { // success } failure:^(NSError * _Nonnull error) { // failure }]; ```