Business - Coupons

The Admin interface handles web service calls from the Admin web gui. The base url for this is at:

/api/business-admin

A JSON file with OpenAPI data about all business-related admin APIs can be downloaded here.

Get Coupon

Gets details about a specific coupon:

GET /v1/coupons/{id}

Gets details about a specific coupon

Parameters

  • id (integer) – The coupon to retrieve data for

Status Codes
DELETE /v1/coupons/{id}

Marks a coupon as deleted

Parameters

  • id (integer) – The coupon to delete

Status Codes
id: Coupon ID (int)

Returns a Json positive response and the data of the specified coupon:

{
  ID: 8                                                    // Int
  Name: "TCP Active Future User",                          // String
  CreatedDate: "2001-01-01T01:01:01Z",                     // DateTime
  LastUpdated: "2001-01-01T01:01:01Z",                     // DateTime
  Guid: "53155c4a-b2a0-412f-ab41-552d9ccdf784",            // Guid
  AvailabilityStart: "2001-01-01T01:01:01Z",               // DateTime
  EffectStart: "2001-01-01T01:01:01Z",                     // DateTime
  EffectEnd: "2001-01-01T01:01:01Z",                       // DateTime
  AvailabilityEnd: "2001-01-01T01:01:01Z",                 // DateTime
  IsCumulative: false,                                     // Boolean
  IsValidForAllUsers: false,                               // Boolean
  Amount: 10,                                              // Int
  MaxDiscount: 10,                                         // Decimal (nullable)
  MinDiscount: 10,                                         // Decimal (nullable)
  Code: "TCPAFU",                                          // String
  CommunityID: 1,                                          // Int (nullable)
  CommunityGuid: "53155c4a-b2a0-412f-ab41-552d9ccdf784",   // Guid (nullable)
  CommunityName: "Userbase"                                // String (nullable)
}

or a plain Json negative response on error.

Get coupon list

Gets a list of coupons:

GET /v1/coupons/list

Gets a list of coupons

Status Codes

Returns a list of all coupons:

[
  {
    ID: 8                                                    // Int
    Name: "TCP Active Future User",                          // String
    CreatedDate: "2001-01-01T01:01:01Z",                     // DateTime
    LastUpdated: "2001-01-01T01:01:01Z",                     // DateTime
    Guid: "53155c4a-b2a0-412f-ab41-552d9ccdf784",            // Guid
    AvailabilityStart: "2001-01-01T01:01:01Z",               // DateTime
    EffectStart: "2001-01-01T01:01:01Z",                     // DateTime
    EffectEnd: "2001-01-01T01:01:01Z",                       // DateTime
    AvailabilityEnd: "2001-01-01T01:01:01Z",                 // DateTime
    IsCumulative: false,                                     // Boolean
    IsValidForAllUsers: false,                               // Boolean
    Amount: 10,                                              // Int
    MaxDiscount: 10,                                         // Decimal (nullable)
    MinDiscount: 10,                                         // Decimal (nullable)
    Code: "TCPAFU",                                          // String
    CommunityID: 1,                                          // Int (nullable)
    CommunityGuid: "53155c4a-b2a0-412f-ab41-552d9ccdf784",   // Guid (nullable)
    CommunityName: "Userbase"                                // String (nullable)
  },
  ...
]

or a plain Json negative response on error.

Add new or edit existing coupon

Persists edits about a new or existing coupon:

POST /v1/coupons

Persists edits about a new or existing coupon

Status Codes

The request body is:

{
  ID: 123,
  Name: "TCP Active Future User",            // String
  Code: "TCPAFU",                            // String
  AvailabilityStart: "2001-01-01T01:01:01Z", // DateTime
  AvailabilityEnd: "2001-01-01T01:01:01Z",   // DateTime
  EffectStart: "2001-01-01T01:01:01Z",       // DateTime
  EffectEnd: "2001-01-01T01:01:01Z",         // DateTime
  IsCumulative: false,                       // Boolean (nullable)
  IsValidForAllUsers: false,                 // Boolean (nullable)
  Amount: 10,                                // Int
  MaxDiscount: 1.23,                         // Decimal (nullable)
  MinDiscount: 1.23,                         // Decimal (nullable)
  CommunityID: 1                             // Int (nullable)
}

If ID (coupon ID) is not provided or set to 0, then the request will create a new record. If no value is provided for the boolean data, the default value is false.

The property Amount has to be set as an integer number between 1 and 100.

A plain Json positive response will be returned if the record was sucessfully added or updated.

Possible errors are:

err_InvalidOrMissingDate

Invalid or missing values for the Availability and Effect dates

err_AmountBadNumberFormat

The value of Amount is not in a valid format.

err_AmountOutOfRange

The value of Amount is less than 1 or greater than 100

err_DiscountBadNumberFormat

The values of MaxDiscount and MinDiscount is not in a valid format (a decimal format).

err_InvalidElement

The field Name or Code are empty or null, or no coupon to edit has been found for the privided ID.

err_DuplicateElement

A coupon with the same Code already exists

Delete coupon

Marks a coupon as deleted:

GET /v1/coupons/{id}

Gets details about a specific coupon

Parameters

  • id (integer) – The coupon to retrieve data for

Status Codes
DELETE /v1/coupons/{id}

Marks a coupon as deleted

Parameters

  • id (integer) – The coupon to delete

Status Codes
id: Coupon ID (int)

Returns a plain Json positive response if the coupon was successfully marked as deleted.

Possible errors are:

err_ElementDoesNotExist

There is no coupon corresponding to the ID specified in the requested

err_ElementAlreadyDeleted

The specified coupon has already been marked as deleted

Revoke coupon

Revokes the activation of a coupon for a specific user:

POST /v1/coupons/revoke/{guid}/{cid}

Revoke a CouponActivation

Parameters

  • guid (string) – User Guid

  • cid (integer) – Coupon ID

Status Codes
guid: User Guid (Guid)
cid: Coupon ID (int)

Returns a plain Json positive response if the coupon was successfully revoked, or a plain Json negative response if not.

Possible errors are:

err_NoActivationFound

There is no active or revoked coupon corresponding to the provided coupon ID on the user

err_AlreadyRevoke

The specified coupon has already been revoked

Reactivate coupon

Reactivates a revoked coupon for a specific user:

POST /v1/coupons/reactivate/{guid}/{cid}

Reactivate a CouponActivation

Parameters

  • guid (string) – User Guid

  • cid (integer) – Coupon ID

Status Codes
guid: User Guid (Guid)
cid: Coupon ID (int)

Returns a plain Json positive response if the coupon was successfully reactivated, or a plain Json negative response if not.

Possible errors are:

err_NoActivationFound

There is no active or revoked coupon corresponding to the provided coupon ID on the user

err_AlreadyActive

The specified coupon is already active

Get user coupons

Get all coupons activated by the user (both still active and revoked) (it’s a Paged List APIs, as explained in the introduction):

GET /v1/coupons/list-active/{guid}

Get all the active CouponActivation for a single user

Parameters

  • guid (string) – User Guid

Status Codes
guid: User Guid (Guid)

Returns all the active CouponActivation for the selectad user:

[
  {
    ID: 1234,                                      // Int
    Guid: "53155c4a-b2a0-412f-ab41-552d9ccdf784",  // Guid
    EffectStart: "2001-01-01T01:01:01Z",           // DateTime
    EffectEnd: "2001-01-01T01:01:01Z",             // DateTime
    Code: "TCPAFU",                                // String
    CouponName: "TCP Active Future User",          // String
    UserName: "John Doe",                          // String
    IsDisabled: false,                             // Boolean
    Email: "user@email.com",                       // String
    Activation: "2001-01-01T01:01:01Z",            // DateTime
    Revoked: "2001-01-01T01:01:01Z",               // DateTime (nullable)
    Amount: 10,                                    // Int
    IsCumulative: false                            // Boolean
  },
  ...
]

Get coupon users

Get all the users connecteded to the specified coupon (it’s a Paged List APIs, as explained in the introduction):

GET /v1/coupons/list-user/{cid}

Get all the users connecteded to the specified coupon

Parameters

  • cid (integer) – Coupon ID

Status Codes
cid: Coupon ID (int)

Returns the list of all users that the specific coupon is applied to:

[
  {
    ID: 1234,                                      // Int
    Guid: "53155c4a-b2a0-412f-ab41-552d9ccdf784",  // Guid
    EffectStart: "2001-01-01T01:01:01Z",           // DateTime
    EffectEnd: "2001-01-01T01:01:01Z",             // DateTime
    Code: "TCPAFU",                                // String
    CouponName: "TCP Active Future User",          // String
    UserName: "John Doe",                          // String
    IsDisabled: false,                             // Boolean
    Email: "user@email.com",                       // String
    Activation: "2001-01-01T01:01:01Z",            // DateTime
    Revoked: "2001-01-01T01:01:01Z",               // DateTime (nullable)
    Amount: 10,                                    // Int
    IsCumulative: false                            // Boolean
  },
  ...
]