Developers

Promotions and Vouchers

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: 

public static IDataApiCall<PromotionResponse> getPromotions(@Nullable List<PromotionStatus> statuses,
                                                                @Nullable List<PromotionType> types, int page)
public static IDataApiCall<PromotionResponse> getPromotions(@Nullable List<PromotionStatus> statuses,
                                                                @Nullable List<PromotionType> types, int limit, int page)
public static IDataApiCall<PromotionResponse> getPromotions(@Nullable List<PromotionStatus> statuses,
                                                                @Nullable List<PromotionType> types, int page, boolean includeMeta)
public static IDataApiCall<PromotionResponse> getPromotions(PromotionsApiQuery promotionsApiQuery)

fun getPromotions(@Nullable statuses:List<PromotionStatus>,
                  @Nullable types:List<PromotionType>, page:Int):IDataApiCall<PromotionResponse>
fun getPromotions(@Nullable statuses:List<PromotionStatus>,
                  @Nullable types:List<PromotionType>, limit:Int, page:Int):IDataApiCall<PromotionResponse>
fun getPromotions(@Nullable statuses:List<PromotionStatus>,
                  @Nullable types:List<PromotionType>, page:Int, includeMeta:Boolean):IDataApiCall<PromotionResponse>
fun getPromotions(promotionsApiQuery:PromotionsApiQuery):IDataApiCall<PromotionResponse>

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 yes --- Class responsible for storing all queryParameters.

Return Value:
IDataApiCall<PromotionResponse> object to execute the request.

Example: 

if (apiCall != null) 
    apiCall.cancel();
PromotionsApiQuery query = new PromotionsApiQuery();
query.limit = limit;
query.statuses = statuses;
query.page = 5;
query.includeMeta = true;
LinkedHashMap<PromotionSortingKey, ApiQuerySortingOrder> 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);

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: 

public static IDataApiCall<SinglePromotionResponse> getPromotionByUuid(@NonNull String uuid)

fun getPromotionByUuid(@NonNull uuid:String):IDataApiCall<SinglePromotionResponse>

Parameters:

Parameter Type Mandatory Default Description
uuid String yes - UUID of the promotion that you want to get.

Return Value:
IDataApiCall<SinglePromotionResponse> object to execute the request.

Example: 

IDataApiCall<SinglePromotionResponse> apiCall = Promotions.getPromotionByUuid(uuid);
        apiCall.execute(response -> {
            if (response != null) {
                Promotion promotion = response.getPromotion();
            }
        }, this::showAlertError);

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: 

public static IDataApiCall<SinglePromotionResponse> getPromotionByCode(@NonNull String code)

fun getPromotionByCode(@NonNull code:String):IDataApiCall<SinglePromotionResponse>

Parameters:

Parameter Type Mandatory Default Description
code String yes - Code of the promotion that you want to get.

Return Value:
IDataApiCall<SinglePromotionResponse> object to execute the request.

Example: 

IDataApiCall<SinglePromotionResponse> apiCall = Promotions.getPromotionByCode(code);
        apiCall.execute(response -> {
            if (response != null) {
                Promotion promotion = response.getPromotion();
            }
        }, this::showAlertError);

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: 

public static IApiCall activatePromotionByUuid(@NonNull String uuid)

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: 

IApiCall apiCall = Promotions.activatePromotionByUuid(uuid);
            apiCall.execute(this::onSuccess, this::onFailure);

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: 

public static IApiCall activatePromotionByCode(@NonNull String code)

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: 

IApiCall apiCall = Promotions.activatePromotionByCode(code);

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: 

public static IApiCall activatePromotionsBatch(List<PromotionIdentifier> promotionsToActivate)

fun activatePromotionsBatch(promotionsToActivate:List<PromotionIdentifier>):IApiCall

Parameters:

Parameter Type Mandatory Default Description
promotionsToActivate List<PromotionIdentifier> yes - List of promotions to be activated

Return Value:
IApiCall object to execute the request.

Example: 

IApiCall call = Promotions.activatePromotionsBatch(promotionsToActivate);
            call.execute(this::onSuccess, this::onFailure);

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: 

public static IApiCall deactivatePromotionByUuid(@NonNull String uuid)

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: 

IApiCall apiCall = Promotions.deactivatePromotionByUuid(uuid);
            apiCall.execute(this::onSuccess, this::onFailure);

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: 

public static IApiCall deactivatePromotionByCode(@NonNull String code)

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: 

IApiCall apiCall = Promotions.deactivatePromotionByCode(code);
            apiCall.execute(this::onSuccess, this::onFailure);

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: 

public static IApiCall deactivatePromotionsBatch(List<PromotionIdentifier> promotionsToDeactivate)

fun deactivatePromotionsBatch(promotionsToDeactivate:List<PromotionIdentifier>):IApiCall

Parameters:

Parameter Type Mandatory Default Description
promotionsToDeactivate List<PromotionIdentifier> yes - List of promotions to be activated

Return Value:
IApiCall object to execute the request.

Example: 

IApiCall call = Promotions.deactivatePromotionsBatch(promotionsToDeactivate);
            call.execute(this::onSuccess, this::onFailure);

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 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

Class:
Promotions

Declaration: 

static func getOrAssignVoucher(poolUUID: String, success: ((AssignVoucherResponse) -> Void), failure: ((ApiError) -> Void)) -> Void

+ (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) -> Void) yes - Closure/Block to be executed when the operation is completed successfully
failure ((ApiError) -> Void) yes - Closure/Block to be executed when the operation is completed with an error

Return Value:
No value is returned.

Example:

let poolUUID: String = "POOL_UUID"
Promotions.getOrAssignVoucher(poolUUID: poolUUID, success: { (assignVoucherResponse) in
  // success
failure: { (error) in
  // failure
})

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 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

Class:
Promotions

Declaration: 

static func assignVoucherCode(poolUUID: String, success: ((AssignVoucherResponse) -> Void), failure: ((ApiError) -> Void)) -> Void

+ (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) -> Void) yes - Closure/Block to be executed when the operation is completed successfully
failure ((ApiError) -> Void) yes - Closure/Block to be executed when the operation is completed with an error

Return Value:
No value is returned.

Example:

let poolUUID: String = "POOL_UUID"
Promotions.assignVoucherCode(poolUUID: poolUUID, success: { (assignVoucherResponse) in
  // success
}, failure: { (error) in
  // failure
})

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

Class:
Promotions

Declaration: 

static func getAssignedVoucherCodes(success: ((VoucherCodesResponse) -> Void), failure: ((ApiError) -> Void)) -> Void

+ (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) -> Void) yes - Closure/Block to be executed when the operation is completed with an error

Return Value:
No value is returned.

Example:

Promotions.getAssignedVoucherCodes(success: { (voucherCodesResponse) in
  // success
}, failure: { (error) in
  // failure
})

[SNRPromotions getAssignedVoucherCodesWithSuccess:^(SNRVoucherCodesResponse *voucherCodesResponse) {
  // success
} failure:^(NSError * _Nonnull error) {
  // failure
}];

Canonical URL: https://hub.synerise.com/developers/mobile-sdk/method-reference/android/promotions