Promotion Code

Promotions enable you to track the source of revenue and to offer discounts in the form of coupons. Each promotion has a promotion code that can be applied to transactions and campaigns.

This record is not a subrecord.

The REST API Browser includes information about the field names and field types of the promotion code record, and about the HTTP methods, request parameters, and operations available to this record. For details, see the REST API Browser’s promotionCode reference page.

For information about promotion, see Promotion.

For information about working with promotions in the UI, see The Promotion Record.

For information about using the REST API Browser, see The REST API Browser.

Record ID

The record ID for the promotion code REST record is promotioncode.

Prerequisites

You must enable the SuitePromotions feature before you can use this record through REST web services.
If you need to create shipping promotions, you need to enable Charge for Shipping.
If you need to use the auto-apply configuration, you need to enable the Auto-apply feature.
Other subtabs or sublists may require additional features to be enabled.

Elements with Different Functionality

The following sublist has different functionality through REST web services:

campaigns

The following fields related to CSV import files under the Coupon Codes subtab are not accessible through REST web services:

lastUploadDate
lastUploadStatus
lastUploadFile
couponCodeFile

The following field is not accessible through REST web services:

useMaterializedSavedSearch

Note:
The useMaterializedSavedSearch field can be found under the Saved search preferences subtab and it applies to promotions with items saved search.

Elements Related to Taxation Features

Note:

REST web services do not support legacy tax features. To work with taxation through REST web services, you must have the SuiteTax feature enabled. For more information about using SuiteTax, see SuiteTax.

The discount item for accounting field on the promotioncode REST record is related to taxation.

Additional Details

Considerations related to features:

For sales channels, you need both the locations and website features enabled even if you do not have the sites configured.

Considerations related to forms:

Only forms provided by NetSuite for SuitePromotions are supported.

Considerations related to fields:

Do not use fields and forms that do not apply to SuitePromotions or are not supported. For example, forms and fields specific to advanced promotions.
The lastUploadDate, lastUploadStatus, lastUploadFile, and couponCodeFile fields are related to the coupon code file uploads and are not available.
The campaigns field is not available through REST.
When you set a dynamic customer group as audience, you must explicitly set a value to the customerGroupPreference field.
Before updating sublists, refer the documentation for working with sublists. For example, working with items, discountItems, and so on.
You should use the supported SuitePromotion form IDs for customForm.
Do not use customForm to try to change the promotion type. Instead, delete the existing one and create a new one.

Note:
The promotion type we create is based on the value of customForm field. You can create an Item promotion by setting the customForm field value to -10501. Similarly, we can use -10502 to create an Order promotion, -10503 to create a Shipping promotion, -10504 to create a Fixed price promotion, and -10507 to create a Free gift promotion.

Considerations when testing your requests:

Open the promotion in the user interface and verify that all the values are the same as if you were to create the promotion manually.
Verify the promotion and its sublist and tab contents in the user interface when updating it.
Use orders that meet the conditions of the promotion and verify that the promotion is applied as expected.

Other considerations:

In case of both single-use and multi-use coupon code types, delete and create a new promotion if you want to change the coupon code type. Updating the coupon code type from single-use to multi-use or from multi-use to single-use is not supported.
You cannot remove a promotion that is being used in a transaction.

Code Sample

In the following example, we create an order promotion scheduled for year 2024 applying a 10% discount for orders with a minimum amount of 150.00 and 10 automatically generated coupon codes. Also, in the request we use 10 as the discount item ID for accounting.

The following code shows how to create a promotion:

            POST: https://demo123.suitetalk.api.netsuite.com/services/rest/record/v1/promotionCode
{ "customForm": { "id": "-10502" }, "name": "My order promotion", "startDate": "2024-01-01", "endDate": "2024-12-31", "combinationType": "ORDERTYPEEXCLUSIVE", "discount": { "id": "10" }, "whatTheCustomerNeedsToBuy": { "id": "MINIMUMORDERAMOUNTORSPECIFICITEMS" }, "minimumOrderAmountCheck": true, "minimumOrderAmount": 150.0, "discountType": { "id": "percent" }, "rate": 10.0, "useType": { "id": "SINGLEUSE" }, "codePattern": "ABC-[AN.3]-[N.3]", "numberToGenerate": 10
}

In the following example, 206 represents the promotion ID.

The following code shows how to retrieve a promotions record using a GET Request:

            GET: https://demo123.suitetalk.api.netsuite.com/services/rest/record/v1/promotioncode/206

The following code shows how you can add an optional parameter to the GET request so that the subrecords and sublists are expanded and not returned only as links:

          GET: https://demo123.suitetalk.api.netsuite.com/services/rest/record/v1/promotioncode/206?expandSubResources=true

The following code shows how to update a promotions record by removing the minimum order amount condition and setting the condition for specific items with IDs 150 and 200 and a quantity of 10:

          PATCH: https://demo123.suitetalk.api.netsuite.com/services/rest/record/v1/promotionCode/206
{ "minimumOrderAmountCheck": false, "minimumOrderAmount": null, "specificItemsCheck": true, "items": { "items": [ {"item": {"id": 150}}, {"item": {"id": 200}} ] }, "itemQuantifier": 10
}

The following code shows how to delete a promotions record:

          DELETE: https://demo123.suitetalk.api.netsuite.com/services/rest/record/v1/promotioncode/206

Note:

If the promotion is already being used in a transaction, you won't be able to remove the promotions record.

Record ID

Prerequisites

Elements with Different Functionality

Elements Related to Taxation Features

Additional Details

Code Sample

Related Topics