Incentives Last updated: 2020-06-24

The Incentive resource stores information about a shop's promotional discounts, including Coupons, Sitewide Promotions, Gift with Purchase (GWP) and Single Use Coupons.

What you can do with Incentives:
Incentive Properties
Property Description
OID "OID":  12321
The marketAgility ID for the incentive
SiteID "SiteID":  1
The marketAgility Site Id for the incentive
Name "Name":  "FREESHIP"
The name of the incentive
Created "Created":  "2019-04-21T12:43:12"
The date the incentive was created
Modified "Modified":  "2020-05-12T08:03:00"
The date the incentive was last modified
Status "Status":   "Active"
Defines whether a product is active or inactive
OnlineStatus "OnlineStatus":   "Migrating"
The live status of a product (Staging, Migrating, Production)
OnlineDate "OnlineDate":   "2020-05-05T18:03:00"
The date and time this incentive was published to the production environment
Description "Description":  "$5.00 off your purchase of $25 or more"
A description of the incentive
IncentiveType "IncentiveType":  "Coupon"
The type of incentive (Coupon, Incentive, GiftWithPurchase, GiftWithPurchaseCoupon)
TargetType "TargetType":  "Product"
Indicates the entity receiving the discount (Cart, Product, Shipping)
Sponsor "Sponsor":  "Shoe Co, Ltd"
(Optional) Related company sponsoring the promotion
Quantity "Quantity":  500
The total number of redemptions that can be transacted (0 = unlimited)
DiscountType "DiscountType":  "Absolute"
The Type of Discount (Absolute, Percentage, SetPrice)
DiscountAmount "DiscountAmount":  5.00
The dollar amount or percentage amount of the discount.
BuyCost "BuyCost":  75.00
How much money must the customer spend on the target items to qualify for this discount
BuyQuantity "BuyQuantity":  1
How many of the target items must the customer purchase to qualify for this discount
Usage "Usage":  0
The number of products the incentive applies to. For example, with a Buy 1 Get 2 promtion, this value would be 2. Note: does not affect shipping and order discounts.
Exclusive "Exclusive":  "None"
Is this promotion excluded from use with other same-type incentives? (None, Partial, Exclusive)
RedeemedCount "RedeemedCount":  422"
The number of times this promtion has been redeemed.
RedemptionStartDate "RedemptionStartDate":  "2019-03-06T00:00:00"
The first date this promotion can be used.
RedemptionEndDate "RedemptionEndDate":  "2019-03-06T00:00:00"
The last date this promotion can be used.
GroupName "GroupName":  "FREESHIP"
The Group name of the coupon family.
SortOrder "SortOrder":  321
The order within all same type incentives that this should be evaluated.
Reusable "Reusable":  1
Can the Coupon be reused? 1= Yes, 0 = No
MaximumMultiples "MaximumMultiples":  1
The number of times this coupon can be applied to the same order. For example on a Buy 1, Get 1 promotion, a MaximumMultiple of 3 means they could Buy 3 and Get 3, but not Buy 4 and Get 4. A value of Zero means "unlimited"

Get Incentive

Gets a single incentive by Id

GET /api/v3/incentives/12321 

HTTP/1.1 200 OK

{
            "OID": 12321,
            "SiteID": 1,
            "Name": "FreeCookieSocks",
            "Created": "2018-02-07T16:40:03.43Z",
            "Modified": "2018-02-07T16:40:03.43Z",
            "Status": 0,
            "OnlineStatus": "Migrating",
            "OnlineDate": "2018-02-07T16:40:03.43Z",
            "Description": "Spend $100, get free pair of cookie socks.",
            "IncentiveType": "GiftWithPurchase",
            "TargetType": "Product",
            "Sponsor": "",
            "Quantity": 0,
            "DiscountType": "SetPrice",
            "DiscountAmount": 0.00,
            "BuyQuantity": 0,
            "Usage": 1,
            "Exclusive": "None",
            "DistributedCount": 0,
            "RedeemedCount": 0,
            "RedemptionStartDate": "2018-02-07T00:00:00",
            "RedemptionEndDate": "2018-12-02T00:00:00",
            "GroupName": "FreeCookieSocks",
            "SortOrder": 0,
            "Reusable": 1,
            "MaximumMultiples": 1,
            "Terms": <Terms> [],
            "Targets": <Targets> [],
            "Exclusions": <Exclusions> []
}

List Incentives

Retrieves a list of incentives for a marketAgility site.

GET /api/v3/incentives/ 

HTTP/1.1 200 OK
[
    {
            "OID": 12321,
            "SiteID": 1,
            "Name": "FreeCookieSocks",
            "Created": "2018-02-07T16:40:03.43Z",
            "Modified": "2018-02-07T16:40:03.43Z",
            "Status": 0,
            "OnlineStatus": "Migrating",
            "OnlineDate": "2018-02-07T16:40:03.43Z",
            "Description": "Spend $100, get free pair of cookie socks.",
            "IncentiveType": "GiftWithPurchase",
            "TargetType": "Product",
            "Sponsor": "",
            "Quantity": 0,
            "DiscountType": "SetPrice",
            "DiscountAmount": 0.00,
            "BuyQuantity": 0,
            "Usage": 1,
            "Exclusive": "None",
            "DistributedCount": 0,
            "RedeemedCount": 0,
            "RedemptionStartDate": "2018-02-07T00:00:00Z",
            "RedemptionEndDate": "2018-12-02T00:00:00Z",
            "GroupName": "FreeCookieSocks",
            "SortOrder": 0,
            "Reusable": 1,
            "MaximumMultiples": 1,
    }
]

Promocodes

A promotion code is a single use code bound to an existing marketAgility coupon. They are most useful when distributing a coupon to a limited number of customers, either as a reward for completing an action, or tied to an email or catalog campaign to better identify and track subscriber behavior.

Once a promotion code is bound to a coupon, the coupon can no longer be used by itself. This prevents a customer from giving out the underlying coupon to their freinds and family, or posting on a public forum. If that is the desired behavior, a traditional coupon based incentive is better suited for an all-access promotion.

What you can do with Promocodes:
Promotion Code Properties
Property Description
OID "OID":  2
The marketAgility ID for the promotion code
SiteID "SiteID":  1
The marketAgility Site Id for the promotion code
Promocode "Promocode":  "12321"
The name of the promotion code
Coupon "Coupon":  "welcome"
The marketAgility incentive that defines the discount that this promotion code will offer.
Created "Created":  "2019-04-21T12:43:12"
The date the promotion code was created
Modified "Modified":  "2020-05-12T08:03:00"
The date the promotion code was last modified
Status "Status":   "Active"
Defines whether a promotion code is active or inactive
ExpireDate "ExpireDate":   "2020-05-05T18:03:00"
The date and time this promotion code will expire
OrderNumber "OrderNumber":  "TEST-12323"
When used, this will indicate the customer order the used the discount
IncentiveType "IncentiveType":  "Coupon"
The type of incentive (Coupon, Incentive, GiftWithPurchase, GiftWithPurchaseCoupon)

Get Promocode

Retrieves a single-use promotion code by code

GET /api/v3/promocodes/12321 

HTTP/1.1 200 OK
{
            "OID": 3,
            "SiteID": 1,
            "Promocode": "12321",
            "Created": "2018-02-07T16:40:03.43Z",
            "Modified": "2018-02-07T16:40:03.43Z",
            "Status": 1,
            "Coupon": "welcome",
            "ExpireDate": "2018-02-07T00:00:00Z",
            "OrderNumber": "TEST-1234",
}

Create a new promotion code

Creates a new promotion code bound to an existing coupon.

POST /api/v3/promocodes/ 
{
    "Promocode": "A6NS342",
    "Coupon": "welcome",
    "Status": "Active",
    "ExpireDate": "11/21/2022"
}
                                

HTTP/1.1 201 Created
{
            "OID": 3,
            "SiteID": 1,
            "Promocode": "A6NS342",
            "Created": "2018-02-07T16:40:03.43Z",
            "Modified": "2018-02-07T16:40:03.43Z",
            "Status": Active,
            "Coupon": "welcome",
            "ExpireDate": "2018-02-07T00:00:00Z",
            "OrderNumber": "",
}

Updates an existing promotion code

Creating a .

POST /api/v3/promocodes/A6NS342 
{
    "Status": "Inactive",
    "OrderNumber": "TEST-1234"
}
                                

HTTP/1.1 204 No Content

Issue Promocode

Issues the next available promotion code from the queue for a given coupon. If the issuance is successful, the promotion code is immediately available for use and marked as issued in the queue. It will not be issued again in subsequent calls to this endpoint.

GET /api/v3/coupons/test/promocodes 

HTTP/1.1 200 OK

"promo5"