API - Planyo Web Services - list_coupons

You are here: Planyo » Help » API » list_coupons

list_coupons

Description:

Lists the purchased coupons. You can specify a number of parameters to filter the results.

Input:

resource_id int optional
If you specify resource ID only coupons which can be used for this resource will be listed.
site_id int optional
Setting site_id and not specifying any resource_id will list coupons compatible with multiple resources. If your api key is valid for a single site, you can leave this empty.
coupon_code string optional
You can enter a coupon code if you want to list only coupons with this code.
email string optional
You can enter an email address if you want to list only coupons purchased for this email address.
check_if_valid bool optional
If true, only coupons which can still be used are returned. This basically checks if the amount is greater than 0 and for the 'valid for given number of days' coupon type, the valid-until date is checked against the rental_time parameter (only if passed)
include_reservations bool optional
If true, all reservations for which given coupon was used will be returned in the results
include_usage_data bool optional
If true, the amount of the coupon that was already used (amount_used) and the last time the coupon was used (latest_usage_time) will be returned in the results
rental_time DateTime optional
If passed AND if check_if_valid is true, only coupons which can still be used at the time passed in this parameter will be returned. Please note that Planyo checks if the rental's end time lies within the coupon's validity date.
language string optional
by specifying a 2-letter (ISO 639-1) language code (all capital letters e.g. EN, DE, FR, ES, IT) you can change the language of the text values returned
api_key string required
your API key - Click here to get your key. If your API key uses a hash key, you must also include the parameters hash_key and hash_timestamp.

Output:

results array
Array whose items are named arrays with the following keys:
type int
The type of the coupon: 1 - Prepaid amount, 2 - Number of hours, 3 - Number of entries, 4 - Valid for given number of days
id int
ID of the coupon.
resource_id string
The comma-separated resource IDs for which the coupon can be used. If empty, the coupon can be used will all resources of the site.
email string
The email address for which the coupon was purchased. Please see personal_usage whether
personal_usage int
When true, the coupon can be use only with email address (see also coupon_code).
coupon_code string
When specified, the coupon can be used with the code. When personal_usage is true, both email address and coupon code need to specified.
is_personal bool
When true, the coupon can be used only by a single person identified by an email address. When false, the coupon can be used with different email addresses.
amount_left float
The remaining coupon's amount that still can be used. Depending on the coupon type, this can be: prepaid amount, number of hours, number of entries or number of days.
amount_used float
The coupon's amount that was already used.
purchase_date datetime
The date and time when the coupon was purchased or loaded for the last time, e.g. 2017-03-11 12:35:00.
latest_usage_time datetime
The date and time when the coupon was used for the last time, e.g. 2017-02-17 20:45:00.
entry_per_person bool
The Number of entries coupon only. When true, one entry is counted per person. Otherwise, one entry is counted per reservation.
reservations array
If include_reservations is set to true, this key will contain a list of reservation IDs where the coupon was used.
validity_start_date date
The first date of coupon's validity. Note that in most cases this will be the same as purchase_date but sometimes this can be a different date chosen by the customer.
validity_end_date date
The last date of coupon's validity. Note that this value can be null when coupon's validity is not limited.

API playground:

Click here to test this function in the API playground.