home > support > API > Marketplace API > Show promo code

Show promo code

Check a promo or gift code is valid and whether any membership number is required to verify


Notes

Checks a promo / gift code is valid for use on a given channel, not necessarily that it applies any discount to a particular tour or booking (that is indicated when a booking is created via Start New Booking).

REST info

Endpoint/c/promo/show
FormatsXML
Examples/c/promo/show.xml?promo_code=AAAMEMBER
VerbGET

Code samples

PHP examples use the PHP Client Library with SimpleXML

Description

object show_promo ( string $promo, int $channel )


Parameters

$promo
The code to check
$channel
ID for the Channel (supplier)

Example

// The code
$promo = "AAAMEMBER";

// Set the channel
$channel = 3930;

// Query the TourCMS API
$result = $tourcms->show_promo($promo, $channel);


// If the promo code is valid
if($result->error == "OK") {

  print "Promo / gift code is valid";

} else {

  print "Promo / gift code is not valid";

}
Promo / gift code is valid

C# examples use the .Net Client Library

Overload list

XmlDocument ShowPromo (String promo, int channelId)


Parameters

promo
The promo code to check
channelId
Id number for the Channel (supplier)

VB examples use the .Net Client Library

Overload list

XmlDocument ShowPromo (String promo, Integer channelId)


Parameters

promo
The promo code to check
channelId
Id number for the Channel (supplier)

NodeJS examples use the NodeJS Wrapper


Example

// Check if promo 'TENPERCENT' is valid for Channel 3930
// If so, <error> will be "OK"
TourCMS.showPromo({
  channelId: 3930,
  promo: 'TENPERCENT',
  callback: function(response) {
    console.log(response.error);
  }
});
OK

Looking for sample code in a different language? TourCMS and community provided API libraries

Querystring parameters

Querystring parameters
ParameterNotes
promoThe promo/gift code to check


The Channel ID is also passed via the request header, this is required as Tour IDs are unique within a particular channel (supplier) rather than being unique system wide.

Response fields

Response fields
XML NodeNotes
request Confirmation of the request that you sent
error Any error message returned. If the promo/gift code is valid on the given channel this will be OK, otherwise it will be PROMO CODE NOT VALID or similar
promo

If the promo/gift code is valid for the channel a promo node will be returned, containing:

NodeNotes
channel_id Channel ID
account_id Account ID
promo_code The promo code
value The value for the promo code, e.g. "10"
value_type The type specified in value, "PERCENT" for percentage based promo codes, "FIXED_VALUE" for gift codes.
value_currency Returned for "FIXED_VALUE" gift codes only, currently matches channel sale currency.
requires_membership Whether the customer should provide a membership number that can be used to validate their use of the promo code. Perhaps a club or association membership number.
 
1 - A membership number is required
0 - A membership number is NOT required
membership_mask Indicates the format for a membership number, e.g. "16" for 16 characters, "3-3-9-1" for 16 characters that are formatted on a membership card as two groups of 3 digits then 9 digits then 1 digit.
If endpoint called using Operator credentials (not available to Agents)
max_uses The maximum number of times this promo code can be used
current_uses The number of committed bookings already using this code
rules

A rules node containing the rules for this code

XML NodeNotes
rule

A rule node for each rule

XML NodeNotes
rule_type The type of rule being set, see the rules table below
rule_values

Where a rule has possible permissible values, a rule_values node is returned

XML NodeNotes
rule_value A permissible or blocked value for this rule, see the rules table below


Rules

Rules describe the logic configured within TourCMS that control how and when a promo code applies. For example promo codes can currently be restricted to certain dates, or certain products.

New rules may be added in future without warning, thus this information is intended for information purposes only and it is not advisable to implement checks based on these rules during the checkout process. Instead we would advise passing the promo code to "Start new booking" at which point TourCMS will check if the code applies to any products on the booking, and will calculate the booking total value. In the general these rules do not need to be read or understood by API implementers.

Rules are only returned if Operator credentials are used, this information is not returned to Agents.

Rules
Dates & Days
Rule restrict_booking_made_date_start
Notes If returned the code only applies to bookings made on or after the date value.
Values A value node for the first date the promo code can be used.
Example The promo code cannot be used by shoppers until 1st January 2022 at the earliest, if a customer tries to shop any earlier the the promo will not be applied
<rule>
   <rule_type>restrict_booking_made_date_start</rule_type>
   <rule_values>
      <rule_value>2022-01-01</rule_value>
   </rule_values>
</rule>
Rule restrict_booking_made_date_end
Notes If returned the code only applies to bookings made on or before the date value.
Values A value node for the last date the promo code can be used
Example The promo code cannot be used by shoppers after 31st December 2022, if a customer tries to shop at a later date the promo will no longer be applied
<rule>
   <rule_type>restrict_booking_made_date_end</rule_type>
   <rule_values>
      <rule_value>2022-12-31</rule_value>
   </rule_values>
</rule>
Rule restrict_booking_travel_date_start
Notes If returned the code only applies to bookings where the first tour is starts on or after the date value.
Values A value node for the earliest a booking can start.
Example The promo code can only be used by shoppers on bookings starting 1st January 2022 at the earliest, if a customer tries to use the promo on a booking starting any earlier the the promo will not be applied
<rule>
  <rule_type>restrict_booking_travel_date_start</rule_type>
  <rule_values>
    <rule_value>2022-01-01</rule_value>
  </rule_values>
</rule>
Rule restrict_booking_travel_date_end
Notes If returned the code only applies to bookings where the last tour finishes on or before the date value.
Values A value node for the latest date a booking can finish.
Example The promo code can be used by shoppers on bookings ending 31st December 2022 at the latest, if a customer tries to use the promo on a booking ending any later the the promo will not be applied
<rule>
   <rule_type>restrict_booking_travel_date_end</rule_type>
   <rule_values>
      <rule_value>2022-12-31</rule_value>
   </rule_values>
</rule>
Rule restrict_max_days_before_start_date
Notes If returned the code only applies to bookings made at a maximum number of days prior to the booking start date. A late booking discount.
Values A value node for the maximum number of days prior to the booking start date that the code applies.
Example The promo code can be used by shoppers on bookings up to 3 days away, if a customer tries to use the promo on a booking starting any later the the promo will not be applied
 
Assuming the current date is 30th September 2020, then the last booking start date that the promo would apply to is 2nd October 2020
<rule>
   <rule_type>restrict_max_days_before_start_date</rule_type>
   <rule_values>
      <rule_value>3</rule_value>
   </rule_values>
</rule>
Rule restrict_min_days_before_start_date
Notes If returned the code only applies to bookings made at least a certain number of days prior to the booking start date. An early booking discount.
Values A value node for the minimum number of days prior to the booking start date that the code applies.
Example The promo code can be used by shoppers on bookings at least 3 days away, if a customer tries to use the promo on a booking starting any earlier the the promo will not be applied
 
Assuming the current date is 30th September 2020, then the last booking start date that the promo would apply to is 2nd October 2020
<rule>
   <rule_type>restrict_min_days_before_start_date</rule_type>
   <rule_values>
      <rule_value>3</rule_value>
   </rule_values>
</rule>
Rule restrict_component_start_day
Notes If returned the code only applies to bookings made at least a certain number of days prior to the booking start date. An early booking discount.
Values A value node for the minimum number of days prior to the booking start date that the code applies.
Example The promo code can be used by shoppers on tours that start on a Monday, Tuesday, Wednesday, Thursday or Friday. The promo will not be applied to any tour component starting on a Friday, Saturday or Sunday.
<rule>
   <rule_type>restrict_component_start_day</rule_type>
   <rule_values>
      <rule_value>Monday</rule_value>
      <rule_value>Tuesday</rule_value>
      <rule_value>Wednesday</rule_value>
      <rule_value>Thursday</rule_value>
   </rule_values>
</rule>
Applicable Tours & Options
Rule restrict_tour_ids
Notes If returned the code only applies to specific tours. Each applicable Tour ID is returned as a value.
Values A value node for each Tour ID the code applies to
Example Promo only applies to Tour ID 1 or 3, the promo will is not applicable to any other Tour
<rule>
   <rule_type>restrict_tour_ids</rule_type>
   <rule_values>
      <rule_value>1</rule_value>
      <rule_value>3</rule_value>
   </rule_values>
</rule>
Rule restricted_tour_rate_code
Notes If returned the code only applies to specific tour private rate codes
Values A value node for each private rate code that the promo code applies to, any other private rate codes will be sold at full price
Example Promo only applies to private rate codes "AD" and "CH", any other rate sold at full price
<rule>
   <rule_type>restricted_tour_rate_code</rule_type>
   <rule_values>
      <rule_value>AD</rule_value>
      <rule_value>CH</rule_value>
   </rule_values>
</rule>
Rule restrict_no_options
Notes If returned the code does not apply to Opptions, they will be sold at full price.
Values N/A
Example Code does not apply to options, they will be sold at full price.
<rule>
  <rule_type>restrict_no_options</rule_type>
</rule>
Rule restrict_no_overnight
Notes If returned the code does not apply to overnight departures (departures where the tour starts and ends on different dates), they will be sold at full price.
Values N/A
Example Code does not apply to overnight departures, they will be sold at full price.
<rule>
  <rule_type>restrict_no_overnight</rule_type>
</rule>
Membership
Rule requires_membership_number
Notes If returned the customer will need to provide a membership number for some organisation (such as a AAA number).
Values N/A
Example The customer should provide their membership number
<rule>
  <rule_type>requires_membership_number</rule_type>
</rule>
Rule restrict_membership_number_mask
Notes If returned the customers membership number is expected to be a specific length or in a specific format. Not currently validted by TourCMS, intended for aiding input
Values A single value documenting the membership number format expected
Examples Example 1: Membership number is 16 digits long, no particular format suggested
<rule>
   <rule_type>restrict_membership_number_mask</rule_type>
   <rule_values>
      <rule_value>16</rule_value>
   </rule_values>
</rule>
Example 2: Membership number is 16 digits long, pre-defined format suggested
<rule>
   <rule_type>restrict_membership_number_mask</rule_type>
   <rule_values>
      <rule_value>3-3-9-1</rule_value>
   </rule_values>
</rule>


More information