Promotion

  • 15.5
This article is may not be up to date with the latest stable release of M4.

Description

The Promotion endpoint provides the API consumer with access to methods pertaining to promotions. The endpoint allows consumers to create and update promotions, retreive promotion information, and link promotions to various other data objects.

Methods

URL base/Workforce/Promotion/Specification
Action GET
Description Returns a data dictionary that details the available web service methods related to the Promotion controller.
Parameters None
 Returns  A JSON object with method descriptions
Sample Return Object 
[
{
"HttpAction": "Post",
"MethodName": "AddPromotion",
"Description": "Returns Promotion object representing a newly created Promotion.",
"Format": {
"PromotionType": "Company",
"PromotionName": "3 mo HBO free",
"StartDate": "2018-05-01T00:00:00",
"EndDate": "2018-06-01T00:00:00",
"PromotionDisplay": "Click here"
}
]
URL base/Workforce/Promotion/AddPromotion
Action POST
Description Returns the Promotion object just added to the M4 database.
Parameters
Name Required? Type Description
PromotionType Yes String Customer or Company.
PromotionName Yes String Name of promotion. Must be unique.
StartDate No DateTime When promotion begins. NULL means beginning of time.
EndDate No DateTime When promotion ends. NULL means end of time.
PromotionDisplay Yes String HTML displayed in Mobile Tech for promotion
Sample JSON Package 
{
"PromotionType": "Customer",
"PromotionName": "HBO 12 mo",
"StartDate": "05-01-2018",
"EndDate": "05-31-2018",
"PromotionDisplay": "
HBO 12 months for $4.99/mo
"
}
Returns A JSON Promotion data object
Sample Return Object 
{
"ID": 167,
"PromotionType": "Customer",
"PromotionName": "HBO 12 mo",
"StartDate": "2018-05-01T00:00:00",
"EndDate": "2018-05-31T00:00:00",
"PromotionDisplay": "
HBO 12 months for $4.99/mo
"
}
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.
  • PromotionName: Must be unique
  • PromotionType: Must be Company or Customer
  • StartDate: Must not be after EndDate
  • PromotionDisplay: Required
URL base/Workforce/Promotion/UpdatePromotion
Action POST
Description Returns the Promotion object just updated in the M4 database.
Parameters
Name Required? Type Description
ID Yes Integer ID of the Promotion.
PromotionType Yes String Customer or Company.
PromotionName Yes String Name of promotion. Must be unique.
StartDate No DateTime When promotion begins. NULL means beginning of time.
EndDate No DateTime When promotion ends. NULL means end of time.
PromotionDisplay Yes String HTML displayed in Mobile Tech for promotion
Sample JSON Package 
{
"ID": 167
"PromotionType": "Customer",
"PromotionName": "HBO 12 mo",
"StartDate": "05-01-2018",
"EndDate": "05-31-2018",
"PromotionDisplay": "
HBO 12 months for $4.99/mo
"
}
Returns A JSON Promotion data object
Sample Return Object 
{
"ID": 167,
"PromotionType": "Customer",
"PromotionName": "HBO 12 mo",
"StartDate": "2018-05-01T00:00:00",
"EndDate": "2018-05-31T00:00:00",
"PromotionDisplay": "
HBO 12 months for $4.99/mo
"
}
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.
  • ID: Must exist in Promotions
  • PromotionName: Must be unique
  • PromotionType: Must be Company or Customer
  • StartDate: Must not be after EndDate
  • PromotionDisplay: Required
URL base/Workforce/Promotion/DeletePromotion/ID
Action POST
Description Returns a message indicating status of delete request.
Parameters
Name Required? Type Description
ID Yes Integer ID of the Promotion.
Returns A JSON message
Sample Return Object 
{
    "Message": "The promotion with ID [167] was deleted successfully."
}
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.
  • ID: Must exist in Promotions
URL base/Workforce/Promotions/GetPromotion/ID
Action GET
Description Returns a Promotion object when given an ID of a valid promotion in the M4 database.
Parameters
Name Required? Type Description
ID Yes Integer An integer value representing the ID of a promotion in the M4 database.
Returns A JSON Promotion data object
Sample Return Object 
{
    "ID": 1,
    "PromotionType": "Customer",
    "PromotionName": "HBO 6 mo",
    "StartDate": "2018-01-01T00:00:00",
    "EndDate": "2018-04-30T00:00:00",
    "PromotionDisplay": "
HBO 12 months for $4.99/mo
"
}
URL base/Workforce/Promotions/GetPromotionsByCustomerID/ID
Action GET
Description Returns a collection of Promotion objects when given a customer ID of a valid customer in the M4 database.
Parameters
Name Required? Type Description
ID Yes Integer An integer value representing the ID of a customer in the M4 database.
Returns A JSON collection of Promotion data object(s)
Sample Return Object 
[
    {
        "ID": 1,
        "PromotionType": "Customer",
        "PromotionName": "HBO 6 mo",
        "StartDate": "2018-01-01T00:00:00",
        "EndDate": "2018-04-30T00:00:00",
        "PromotionDisplay": "
HBO 12 months for $4.99/mo
"
    }
]
URL base/Workforce/Promotions/GetAllPromotions
Action GET
Description Returns a collection of all Promotion objects in the M4 database.
Parameters
Name Required? Type Description
Returns A JSON collection of Promotion data object(s)
Sample Return Object 
[
    {
        "ID": 1,
        "PromotionType": "Customer",
        "PromotionName": "HBO 6 mo",
        "StartDate": "2018-01-01T00:00:00",
        "EndDate": "2018-04-30T00:00:00",
        "PromotionDisplay": "
HBO 12 months for $4.99/mo
"
    }
]
URL base/Workforce/Promotions/GetAllActivePromotions
Action GET
Description Returns a collection of all active Promotion objects in the M4 database.
Parameters
Name Required? Type Description
Returns A JSON collection of Promotion data object(s)
Sample Return Object 
[
    {
        "ID": 1,
        "PromotionType": "Customer",
        "PromotionName": "HBO 6 mo",
        "StartDate": "2018-01-01T00:00:00",
        "EndDate": "2018-04-30T00:00:00",
        "PromotionDisplay": "
HBO 12 months for $4.99/mo
"
    }
]
URL base/Workforce/Promotions/GetActivePromotionsByCustomerID/ID
Action GET
Description Returns a collection of active Promotion objects when given a customer ID of a valid customer in the M4 database.
Parameters
Name Required? Type Description
ID Yes Integer An integer value representing the ID of a customer in the M4 database.
Returns A JSON collection of Promotion data object(s)
Sample Return Object 
[
    {
        "ID": 1,
        "PromotionType": "Customer",
        "PromotionName": "HBO 6 mo",
        "StartDate": "2018-01-01T00:00:00",
        "EndDate": "2018-06-30T00:00:00",
        "PromotionDisplay": "
HBO 12 months for $4.99/mo
"
    }
]
URL base/Workforce/Promotion/LinkCustomerToPromotion
Action POST
Description Returns a message indicating status of link request.
Parameters
Name Required? Type Description
CustomerID Yes Integer ID of the Customer.
PromotionID Yes Integer ID of the Promotion.
Sample JSON Package 
{
      "CustomerID": 1,
      "PromotionID": 32
}
Returns A JSON message
Sample Return Object 
{
    "Message": "The promotion with ID [32] was linked to customer [1] successfully."
}
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.
  • CustomerID: Must exist in Customers
  • PromotionID: Must exist in Promotions
  • Unlinked: Must not already be linked
URL base/Workforce/Promotion/UnlinkCustomerFromPromotion
Action POST
Description Returns a message indicating status of link request.
Parameters
Name Required? Type Description
CustomerID Yes Integer ID of the Customer.
PromotionID Yes Integer ID of the Promotion.
Sample JSON Package 
{
      "CustomerID": 1,
      "PromotionID": 32
}
Returns A JSON message
Sample Return Object 
{
    "Message": "The promotion with ID [32] was unlinked from customer [1] successfully."
}
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.
  • CustomerID: Must exist in Customers
  • PromotionID: Must exist in Promotions
  • Linked: Must already be linked

Was this article helpful?

Yes No

Related Articles