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
Formats	XML
Examples	/c/promo/show.xml?promo_code=AAAMEMBER
Verb	GET

Code samples

PHP
C#
VB
NodeJS
Other

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
Parameter	Notes
promo	The 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

XML Node

Notes

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:

Node

Notes

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)

current_uses

The number of committed bookings already using this code

max_uses

The maximum number of times this promo code can be used

rules

A rules node containing the rules for this code

XML Node

Notes

rule

A rule node for each rule

XML Node

Notes

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 Node	Notes
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>`
Markups
Rule	valid_markup_types
Notes	If returned the code only applies to specific markups. Each applicable Markup ID is returned as a value.
Values	A value node for each Markup ID the code applies to
Example	Promo only applies to Markup ID 1 or 3, the promo will is not applicable to any other Markup `<rule> <rule_type>valid_markup_types</rule_type> <rule_values> <rule_value>1</rule_value> <rule_value>3</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>`

Contact Info

Learn More

Follow Us

Show promo code

Notes

REST info

Code samples

Description

Parameters

Example

Overload list

Parameters

Overload list

Parameters

Example

Querystring parameters

Response fields

Rules

More information