API - Planyo Web Services - list_coupons

Vous êtes ici: Planyo » Aide » 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. When using a metasite api key, you can specify a site to list the coupons from that site only. You can also use a special value all which will list coupons on the site level for all the sites belonging to the meta site.
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.
type int optional
If passed, only coupons matching the specified type will be returned. If not specified, the function will return coupons of all types. The allowed values are: 1 - Prepaid amount, 2 - Number of hours, 3 - Number of entries, 4 - Valid for given number of days, 5 - Discount valid for given number of days.
page int optional
Zero-based page number. The default is 0. Each page lists max 5000 coupons. Note: you can change the page size (max 5000) with the page_size parameter
method string required
must be set to list_coupons
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, 5 - Discount 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.
latest_reservation_start_time datetime
The date and time of the reservation when the coupon was used for the last time, e.g. 2017-02-17 20:45:00.
latest_coupon_type_id int
ID of the existing coupon type that was used to create (load) the coupon. You can find coupon types valid for your site on the Create coupons page.
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.
discount_amount int
For the Discount valid for given number of days type, this is the discount value in percent.

API playground:

Click here to test this function in the API playground.