WooCommerce Code Reference

WC_Coupon extends WC_Legacy_Coupon
in package

Coupon class.

Table of Contents

E_WC_COUPON_ALREADY_APPLIED  = 103
E_WC_COUPON_ALREADY_APPLIED_INDIV_USE_ONLY  = 104
E_WC_COUPON_EXCLUDED_CATEGORIES  = 114
E_WC_COUPON_EXCLUDED_PRODUCTS  = 113
E_WC_COUPON_EXPIRED  = 107
E_WC_COUPON_INVALID_FILTERED  = 100
E_WC_COUPON_INVALID_REMOVED  = 101
E_WC_COUPON_MAX_SPEND_LIMIT_MET  = 112
E_WC_COUPON_MIN_SPEND_LIMIT_NOT_MET  = 108
E_WC_COUPON_NOT_APPLICABLE  = 109
E_WC_COUPON_NOT_EXIST  = 105
E_WC_COUPON_NOT_VALID_SALE_ITEMS  = 110
E_WC_COUPON_NOT_YOURS_REMOVED  = 102
E_WC_COUPON_PLEASE_ENTER  = 111
E_WC_COUPON_USAGE_LIMIT_COUPON_STUCK  = 115
E_WC_COUPON_USAGE_LIMIT_COUPON_STUCK_GUEST  = 116
E_WC_COUPON_USAGE_LIMIT_REACHED  = 106
WC_COUPON_REMOVED  = 201
WC_COUPON_SUCCESS  = 200
$error_message  : string
Error message.
$sort  : int
Sorting.
$cache_group  : string
Cache group.
$changes  : array<string|int, mixed>
Core data changes for this object.
$data  : array<string|int, mixed>
Data array, with defaults.
$data_store  : object
Contains a reference to the data store for this class.
$default_data  : array<string|int, mixed>
Set to _data on construct so we can track and reset data if needed.
$extra_data  : array<string|int, mixed>
Extra data for this object. Name value pairs (name + default value).
$id  : int
ID for this object.
$legacy_datastore_props  : array<string|int, mixed>
List of properties that were earlier managed by data store. However, since DataStore is a not a stored entity in itself, they used to store data in metadata of the data object.
$meta_data  : array<string|int, mixed>
Stores additional meta data.
$object_read  : bool
This is false until the object is read from the DB.
$object_type  : string
This is the name of this object type.
__clone()  : mixed
When the object is cloned, make sure meta is duplicated correctly.
__construct()  : mixed
Coupon constructor. Loads coupon data.
__get()  : mixed
Magic __get method for backwards compatibility. Maps legacy vars to new getters.
__isset()  : bool
Magic __isset method for backwards compatibility. Legacy properties which could be accessed directly in the past.
__sleep()  : array<string|int, mixed>
Only store the object ID to avoid serializing the data object instance.
__toString()  : string
Change data to JSON format.
__wakeup()  : mixed
Re-run the constructor with the object ID.
add_coupon_message()  : mixed
Converts one of the WC_Coupon message/error codes to a message string and.
add_meta_data()  : mixed
Add meta data.
apply_before_tax()  : bool
Check if coupon needs applying before tax.
apply_changes()  : mixed
Merge changes with data and clear.
dcr_usage_count()  : mixed
Decrease usage count for current coupon.
decrease_usage_count()  : mixed
Decrease usage count for current coupon.
delete()  : bool
Delete an object, set the ID to 0, and return result.
delete_meta_data()  : mixed
Delete meta data.
delete_meta_data_by_mid()  : mixed
Delete meta data.
delete_meta_data_value()  : mixed
Delete meta data with a matching value.
enable_free_shipping()  : bool
Check if a coupon enables free shipping.
exclude_sale_items()  : bool
Check if a coupon excludes sale items.
format_array()  : array<string|int, mixed>
Format loaded data as array.
generate_meta_cache_key()  : string
Generate cache key from id and group.
get_amount()  : string
Get coupon amount.
get_changes()  : array<string|int, mixed>
Return data changes only.
get_code()  : string
Get coupon code.
get_context_based_coupon_errors()  : array<string|int, mixed>
Returns alternate error messages based on context (eg. Cart and Checkout).
get_coupon_error()  : string
Map one of the WC_Coupon error codes to a message string.
get_coupon_message()  : string
Map one of the WC_Coupon message codes to a message string.
get_data()  : array<string|int, mixed>
Returns all data for this object.
get_data_keys()  : array<string|int, mixed>
Returns array of expected data keys for this object.
get_data_store()  : object
Get the data store.
get_date_created()  : WC_DateTime|null
Get date_created
get_date_expires()  : WC_DateTime|null
Get coupon expiration date.
get_date_modified()  : WC_DateTime|null
Get date_modified
get_description()  : string
Get coupon description.
get_discount_amount()  : float
Get discount amount for a cart item.
get_discount_type()  : string
Get discount type.
get_email_restrictions()  : array<string|int, mixed>
Get emails to check customer usage restrictions.
get_error_message()  : string
Returns the error_message string.
get_exclude_sale_items()  : bool
If this coupon should exclude items on sale.
get_excluded_product_categories()  : array<string|int, mixed>
Get product categories this coupon cannot not apply to.
get_excluded_product_ids()  : array<string|int, mixed>
Get product IDs that this coupon should not apply to.
get_extra_data_keys()  : array<string|int, mixed>
Returns all "extra" data keys for an object (for sub objects like product types).
get_free_shipping()  : bool
If this coupon grants free shipping or not.
get_generic_coupon_error()  : string
Map one of the WC_Coupon error codes to an error string.
get_id()  : int
Returns the unique ID for this object.
get_individual_use()  : bool
Get the "individual use" checkbox status.
get_limit_usage_to_x_items()  : int|null
Usage limited to certain amount of items
get_maximum_amount()  : float
Get maximum spend amount.
get_meta()  : mixed
Get Meta Data by Key.
get_meta_cache_key()  : string
Helper method to compute meta cache key. Different from WP Meta cache key in that meta data cached using this key also contains meta_id column.
get_meta_data()  : array<string|int, mixed>
Get All Meta Data.
get_minimum_amount()  : float
Get minimum spend amount.
get_object_read()  : bool
Get object read property.
get_product_categories()  : array<string|int, mixed>
Get product categories this coupon can apply to.
get_product_ids()  : array<string|int, mixed>
Get product IDs this coupon can apply to.
get_short_info()  : string
Get the coupon information that is needed to reapply the coupon to an existing order.
get_status()  : string
Get coupon status.
get_usage_count()  : int
Get coupon usage count.
get_usage_limit()  : int
Get coupon usage limit.
get_usage_limit_per_user()  : int
Get coupon usage limit per customer (for a single customer)
get_used_by()  : array<string|int, mixed>
Get records of all users who have used the current coupon.
get_virtual()  : bool
If the filter is added through the woocommerce_get_shop_coupon_data filter, it's virtual and not in the DB.
inc_usage_count()  : mixed
Increase usage count for current coupon.
increase_usage_count()  : mixed
Increase usage count for current coupon.
init_meta_data()  : mixed
Helper function to initialize metadata entries from filtered raw meta data.
is_type()  : bool
Checks the coupon type.
is_valid()  : bool
Check if a coupon is valid for the cart.
is_valid_for_cart()  : bool
Check if a coupon is valid.
is_valid_for_product()  : bool
Check if a coupon is valid for a product.
meta_exists()  : bool
See if meta data exists, since get_meta always returns a '' or array().
prime_raw_meta_data_cache()  : mixed
Prime caches for raw meta data. This includes meta_id column as well, which is not included by default in WP meta data.
read_manual_coupon()  : mixed
Developers can programmatically return coupons. This function will read those values into our WC_Coupon class.
read_meta_data()  : mixed
Read Meta Data from the database. Ignore any internal properties.
save()  : int
Save should create or update based on object existence.
save_meta_data()  : mixed
Update Meta Data in the database.
set_amount()  : mixed
Set amount.
set_code()  : mixed
Set coupon code.
set_date_created()  : mixed
Set date_created
set_date_expires()  : mixed
Set expiration date.
set_date_modified()  : mixed
Set date_modified
set_defaults()  : mixed
Set all props to default values.
set_description()  : mixed
Set coupon description.
set_discount_type()  : mixed
Set discount type.
set_email_restrictions()  : mixed
Set email restrictions.
set_error_message()  : void
Sets the error_message string.
set_exclude_sale_items()  : mixed
Set if this coupon should excluded sale items or not.
set_excluded_product_categories()  : mixed
Set the product category IDs this coupon cannot be used with.
set_excluded_product_ids()  : mixed
Set the product IDs this coupon cannot be used with.
set_free_shipping()  : mixed
Set if this coupon enables free shipping or not.
set_id()  : mixed
Set ID.
set_individual_use()  : mixed
Set if this coupon can only be used once.
set_limit_usage_to_x_items()  : mixed
Set usage limit to x number of items.
set_maximum_amount()  : mixed
Set the maximum spend amount.
set_meta_data()  : mixed
Set all meta data from array.
set_minimum_amount()  : mixed
Set the minimum spend amount.
set_object_read()  : mixed
Set object read property.
set_product_categories()  : mixed
Set the product category IDs this coupon can be used with.
set_product_ids()  : mixed
Set the product IDs this coupon can be used with.
set_props()  : bool|WP_Error
Set a collection of props in one go, collect any errors, and return the result.
set_short_info()  : mixed
Sets the coupon parameters from a reapply information set generated with 'get_short_info'.
set_status()  : mixed
Set coupon status.
set_usage_count()  : mixed
Set how many times this coupon has been used.
set_usage_limit()  : mixed
Set the amount of times this coupon can be used.
set_usage_limit_per_user()  : mixed
Set the amount of times this coupon can be used per user.
set_used_by()  : mixed
Set which users have used this coupon.
set_virtual()  : mixed
Set coupon virtual state.
update_meta_data()  : mixed
Update meta data by key or ID, if provided.
error()  : mixed
When invalid data is found, throw an exception unless reading from the DB.
filter_null_meta()  : bool
Filter null meta values from array.
get_hook_prefix()  : string
Prefix for action and filter hooks on data.
get_prop()  : mixed
Gets a prop for a getter method.
is_internal_meta_key()  : bool
Check if the key is an internal one.
maybe_read_meta_data()  : mixed
Read meta data if null.
read_object_from_database()  : mixed
If the object has an ID, read using the data store.
set_date_prop()  : mixed
Sets a date prop whilst handling formatting and datetime objects.
set_prop()  : mixed
Sets a prop for a setter method.

Constants

E_WC_COUPON_ALREADY_APPLIED_INDIV_USE_ONLY

public mixed E_WC_COUPON_ALREADY_APPLIED_INDIV_USE_ONLY = 104

E_WC_COUPON_USAGE_LIMIT_COUPON_STUCK_GUEST

public mixed E_WC_COUPON_USAGE_LIMIT_COUPON_STUCK_GUEST = 116

Properties

$error_message

Error message.

public string $error_message

This property should not be considered public API, and should not be accessed directly. It is being added to supress PHP > 8.0 warnings against dynamic property creation, and all access should be through the getter and setter methods, namely get_error_message() and set_error_message(). In the future, the access modifier may be changed back to protected.

$data

Data array, with defaults.

protected array<string|int, mixed> $data = array('code' => '', 'amount' => 0, 'status' => ull, 'date_created' => ull, 'date_modified' => ull, 'date_expires' => ull, 'discount_type' => 'fixed_cart', 'description' => '', 'usage_count' => 0, 'individual_use' => alse, 'product_ids' => array(), 'excluded_product_ids' => array(), 'usage_limit' => 0, 'usage_limit_per_user' => 0, 'limit_usage_to_x_items' => ull, 'free_shipping' => alse, 'product_categories' => array(), 'excluded_product_categories' => array(), 'exclude_sale_items' => alse, 'minimum_amount' => '', 'maximum_amount' => '', 'email_restrictions' => array(), 'used_by' => array(), 'virtual' => alse)
Tags
since
3.0.0

$default_data

Set to _data on construct so we can track and reset data if needed.

protected array<string|int, mixed> $default_data = array()
Tags
since
3.0.0

$extra_data

Extra data for this object. Name value pairs (name + default value).

protected array<string|int, mixed> $extra_data = array()

Used as a standard way for sub classes (like product types) to add additional information to an inherited class.

Tags
since
3.0.0

$legacy_datastore_props

List of properties that were earlier managed by data store. However, since DataStore is a not a stored entity in itself, they used to store data in metadata of the data object.

protected array<string|int, mixed> $legacy_datastore_props = array()

With custom tables, some of these are moved from metadata to their own columns, but existing code will still try to add them to metadata. This array is used to keep track of such properties.

Only reason to add a property here is that you are moving properties from DataStore instance to data object. If you are adding a new property, consider adding it to to $data array instead.

Methods

__construct()

Coupon constructor. Loads coupon data.

public __construct([mixed $data = '' ]) : mixed
Parameters
$data : mixed = ''

Coupon data, object, ID or code.

Return values
mixed —

__get()

Magic __get method for backwards compatibility. Maps legacy vars to new getters.

public __get(string $key) : mixed
Parameters
$key : string
Return values
mixed —

__isset()

Magic __isset method for backwards compatibility. Legacy properties which could be accessed directly in the past.

public __isset(string $key) : bool
Parameters
$key : string
Return values
bool —

__sleep()

Only store the object ID to avoid serializing the data object instance.

public __sleep() : array<string|int, mixed>
Return values
array<string|int, mixed> —

__wakeup()

Re-run the constructor with the object ID.

public __wakeup() : mixed

If the object no longer exists, remove the ID.

Return values
mixed —

add_coupon_message()

Converts one of the WC_Coupon message/error codes to a message string and.

public add_coupon_message(int $msg_code[, string $notice_type = 'success' ]) : mixed

displays the message/error.

Parameters
$msg_code : int

Message/error code.

$notice_type : string = 'success'

Notice type.

Return values
mixed —

add_meta_data()

Add meta data.

public add_meta_data(string $key, string|array<string|int, mixed> $value[, bool $unique = false ]) : mixed
Parameters
$key : string

Meta key.

$value : string|array<string|int, mixed>

Meta value.

$unique : bool = false

Should this be a unique key?.

Tags
since
2.6.0
Return values
mixed —

dcr_usage_count()

Decrease usage count for current coupon.

public dcr_usage_count([string $used_by = '' ]) : mixed
Parameters
$used_by : string = ''

Either user ID or billing email

Return values
mixed —

decrease_usage_count()

Decrease usage count for current coupon.

public decrease_usage_count([string $used_by = '' ]) : mixed
Parameters
$used_by : string = ''

Either user ID or billing email.

Return values
mixed —

delete()

Delete an object, set the ID to 0, and return result.

public delete([bool $force_delete = false ]) : bool
Parameters
$force_delete : bool = false

Should the date be deleted permanently.

Tags
since
2.6.0
Return values
bool — result

delete_meta_data()

Delete meta data.

public delete_meta_data(string $key) : mixed
Parameters
$key : string

Meta key.

Tags
since
2.6.0
Return values
mixed —

delete_meta_data_by_mid()

Delete meta data.

public delete_meta_data_by_mid(int $mid) : mixed
Parameters
$mid : int

Meta ID.

Tags
since
2.6.0
Return values
mixed —

delete_meta_data_value()

Delete meta data with a matching value.

public delete_meta_data_value(string $key, mixed $value) : mixed
Parameters
$key : string

Meta key.

$value : mixed

Meta value. Entries will only be removed that match the value.

Tags
since
7.7.0
Return values
mixed —

format_array()

Format loaded data as array.

public format_array(string|array<string|int, mixed> $array) : array<string|int, mixed>
Parameters
$array : string|array<string|int, mixed>
Return values
array<string|int, mixed> —

generate_meta_cache_key()

Generate cache key from id and group.

public static generate_meta_cache_key(int|string $id, string $cache_group) : string
Parameters
$id : int|string

Object ID.

$cache_group : string

Group name use to store cache. Whole group cache can be invalidated in one go.

Tags
since
4.7.0
Return values
string — Meta cache key.

get_amount()

Get coupon amount.

public get_amount([string $context = 'view' ]) : string
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Tags
since
3.0.0
Return values
string —

get_changes()

Return data changes only.

public get_changes() : array<string|int, mixed>
Tags
since
3.0.0
Return values
array<string|int, mixed> —

get_code()

Get coupon code.

public get_code([string $context = 'view' ]) : string
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Tags
since
3.0.0
Return values
string —

get_context_based_coupon_errors()

Returns alternate error messages based on context (eg. Cart and Checkout).

public get_context_based_coupon_errors([int $err_code = null ]) : array<string|int, mixed>
Parameters
$err_code : int = null

Message/error code.

Return values
array<string|int, mixed> — Context based alternate error messages.

get_coupon_error()

Map one of the WC_Coupon error codes to a message string.

public get_coupon_error(int $err_code) : string
Parameters
$err_code : int

Message/error code.

Return values
string — Message/error string

get_coupon_message()

Map one of the WC_Coupon message codes to a message string.

public get_coupon_message(int $msg_code) : string
Parameters
$msg_code : int

Message code.

Return values
string — Message/error string.

get_data()

Returns all data for this object.

public get_data() : array<string|int, mixed>
Tags
since
2.6.0
Return values
array<string|int, mixed> —

get_data_keys()

Returns array of expected data keys for this object.

public get_data_keys() : array<string|int, mixed>
Tags
since
3.0.0
Return values
array<string|int, mixed> —

get_date_created()

Get date_created

public get_date_created([string $context = 'view' ]) : WC_DateTime|null
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Tags
since
3.0.0
Return values
WC_DateTime|null — object if the date is set or null if there is no date.

get_date_expires()

Get coupon expiration date.

public get_date_expires([string $context = 'view' ]) : WC_DateTime|null
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Tags
since
3.0.0
Return values
WC_DateTime|null — object if the date is set or null if there is no date.

get_date_modified()

Get date_modified

public get_date_modified([string $context = 'view' ]) : WC_DateTime|null
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Tags
since
3.0.0
Return values
WC_DateTime|null — object if the date is set or null if there is no date.

get_description()

Get coupon description.

public get_description([string $context = 'view' ]) : string
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Tags
since
3.0.0
Return values
string —

get_discount_amount()

Get discount amount for a cart item.

public get_discount_amount(float $discounting_amount[, array<string|int, mixed>|null $cart_item = null ][, bool $single = false ]) : float
Parameters
$discounting_amount : float

Amount the coupon is being applied to.

$cart_item : array<string|int, mixed>|null = null

Cart item being discounted if applicable.

$single : bool = false

True if discounting a single qty item, false if its the line.

Return values
float — Amount this coupon has discounted.

get_discount_type()

Get discount type.

public get_discount_type([string $context = 'view' ]) : string
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Tags
since
3.0.0
Return values
string —

get_email_restrictions()

Get emails to check customer usage restrictions.

public get_email_restrictions([string $context = 'view' ]) : array<string|int, mixed>
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Tags
since
3.0.0
Return values
array<string|int, mixed> —

get_error_message()

Returns the error_message string.

public get_error_message() : string
Return values
string —

get_exclude_sale_items()

If this coupon should exclude items on sale.

public get_exclude_sale_items([string $context = 'view' ]) : bool
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Tags
since
3.0.0
Return values
bool —

get_excluded_product_categories()

Get product categories this coupon cannot not apply to.

public get_excluded_product_categories([string $context = 'view' ]) : array<string|int, mixed>
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Tags
since
3.0.0
Return values
array<string|int, mixed> —

get_excluded_product_ids()

Get product IDs that this coupon should not apply to.

public get_excluded_product_ids([string $context = 'view' ]) : array<string|int, mixed>
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Tags
since
3.0.0
Return values
array<string|int, mixed> —

get_extra_data_keys()

Returns all "extra" data keys for an object (for sub objects like product types).

public get_extra_data_keys() : array<string|int, mixed>
Tags
since
3.0.0
Return values
array<string|int, mixed> —

get_free_shipping()

If this coupon grants free shipping or not.

public get_free_shipping([string $context = 'view' ]) : bool
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Tags
since
3.0.0
Return values
bool —

get_generic_coupon_error()

Map one of the WC_Coupon error codes to an error string.

public static get_generic_coupon_error(int $err_code) : string

No coupon instance will be available where a coupon does not exist, so this static method exists.

Parameters
$err_code : int

Error code.

Return values
string — Error string.

get_individual_use()

Get the "individual use" checkbox status.

public get_individual_use([string $context = 'view' ]) : bool
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Tags
since
3.0.0
Return values
bool —

get_limit_usage_to_x_items()

Usage limited to certain amount of items

public get_limit_usage_to_x_items([string $context = 'view' ]) : int|null
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Tags
since
3.0.0
Return values
int|null —

get_maximum_amount()

Get maximum spend amount.

public get_maximum_amount([string $context = 'view' ]) : float
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Tags
since
3.0.0
Return values
float —

get_meta()

Get Meta Data by Key.

public get_meta([string $key = '' ][, bool $single = true ][, string $context = 'view' ]) : mixed
Parameters
$key : string = ''

Meta Key.

$single : bool = true

return first found meta with key, or all with $key.

$context : string = 'view'

What the value is for. Valid values are view and edit.

Tags
since
2.6.0
Return values
mixed —

get_meta_cache_key()

Helper method to compute meta cache key. Different from WP Meta cache key in that meta data cached using this key also contains meta_id column.

public get_meta_cache_key() : string
Tags
since
4.7.0
Return values
string —

get_meta_data()

Get All Meta Data.

public get_meta_data() : array<string|int, mixed>
Tags
since
2.6.0
Return values
array<string|int, mixed> — of objects.

get_minimum_amount()

Get minimum spend amount.

public get_minimum_amount([string $context = 'view' ]) : float
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Tags
since
3.0.0
Return values
float —

get_product_categories()

Get product categories this coupon can apply to.

public get_product_categories([string $context = 'view' ]) : array<string|int, mixed>
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Tags
since
3.0.0
Return values
array<string|int, mixed> —

get_product_ids()

Get product IDs this coupon can apply to.

public get_product_ids([string $context = 'view' ]) : array<string|int, mixed>
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Tags
since
3.0.0
Return values
array<string|int, mixed> —

get_short_info()

Get the coupon information that is needed to reapply the coupon to an existing order.

public get_short_info() : string

This information is intended to be stored as a meta value in the order line item corresponding to the coupon and should NOT be modified or extended (additional/custom data should go in a separate metadata entry).

The information returned is a JSON-encoded string of an array with the following coupon information:

0: Id 1: Code 2: Type, null is equivalent to 'fixed_cart' 3: Nominal amount (either a fixed amount or a percent, depending on the coupon type) 4: The coupon grants free shipping? (present only if true)

Return values
string — A JSON string with information that allows the coupon to be reapplied to an existing order.

get_status()

Get coupon status.

public get_status([string $context = 'view' ]) : string
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Tags
since
6.2.0
Return values
string —

get_usage_count()

Get coupon usage count.

public get_usage_count([string $context = 'view' ]) : int
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Tags
since
3.0.0
Return values
int —

get_usage_limit()

Get coupon usage limit.

public get_usage_limit([string $context = 'view' ]) : int
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Tags
since
3.0.0
Return values
int —

get_usage_limit_per_user()

Get coupon usage limit per customer (for a single customer)

public get_usage_limit_per_user([string $context = 'view' ]) : int
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Tags
since
3.0.0
Return values
int —

get_used_by()

Get records of all users who have used the current coupon.

public get_used_by([string $context = 'view' ]) : array<string|int, mixed>
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Tags
since
3.0.0
Return values
array<string|int, mixed> —

get_virtual()

If the filter is added through the woocommerce_get_shop_coupon_data filter, it's virtual and not in the DB.

public get_virtual([string $context = 'view' ]) : bool
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Tags
since
3.2.0
Return values
bool —

inc_usage_count()

Increase usage count for current coupon.

public inc_usage_count([string $used_by = '' ]) : mixed
Parameters
$used_by : string = ''

Either user ID or billing email

Return values
mixed —

increase_usage_count()

Increase usage count for current coupon.

public increase_usage_count([string $used_by = '' ][, WC_Order $order = null ]) : mixed
Parameters
$used_by : string = ''

Either user ID or billing email.

$order : WC_Order = null

If provided, will clear the coupons held by this order.

Return values
mixed —

init_meta_data()

Helper function to initialize metadata entries from filtered raw meta data.

public init_meta_data([array<string|int, mixed> $filtered_meta_data = array() ]) : mixed
Parameters
$filtered_meta_data : array<string|int, mixed> = array()

Filtered metadata fetched from DB.

Return values
mixed —

is_type()

Checks the coupon type.

public is_type(string|array<string|int, mixed> $type) : bool
Parameters
$type : string|array<string|int, mixed>

Array or string of types.

Return values
bool —

is_valid()

Check if a coupon is valid for the cart.

public is_valid() : bool
Tags
deprecated
3.2.0

In favor of WC_Discounts->is_coupon_valid.

Return values
bool —

is_valid_for_cart()

Check if a coupon is valid.

public is_valid_for_cart() : bool
Return values
bool —

is_valid_for_product()

Check if a coupon is valid for a product.

public is_valid_for_product(WC_Product $product[, array<string|int, mixed> $values = array() ]) : bool
Parameters
$product : WC_Product

Product instance.

$values : array<string|int, mixed> = array()

Values.

Return values
bool —

meta_exists()

See if meta data exists, since get_meta always returns a '' or array().

public meta_exists([string $key = '' ]) : bool
Parameters
$key : string = ''

Meta Key.

Tags
since
3.0.0
Return values
bool —

prime_raw_meta_data_cache()

Prime caches for raw meta data. This includes meta_id column as well, which is not included by default in WP meta data.

public static prime_raw_meta_data_cache(array<string|int, mixed> $raw_meta_data_collection, string $cache_group) : mixed
Parameters
$raw_meta_data_collection : array<string|int, mixed>

Array of objects of { object_id => array( meta_row_1, meta_row_2, ... }.

$cache_group : string

Name of cache group.

Tags
since
4.7.0
Return values
mixed —

read_manual_coupon()

Developers can programmatically return coupons. This function will read those values into our WC_Coupon class.

public read_manual_coupon(string $code, array<string|int, mixed> $coupon) : mixed
Parameters
$code : string

Coupon code.

$coupon : array<string|int, mixed>

Array of coupon properties.

Tags
since
3.0.0
Return values
mixed —

read_meta_data()

Read Meta Data from the database. Ignore any internal properties.

public read_meta_data([bool $force_read = false ]) : mixed

Uses it's own caches because get_metadata does not provide meta_ids.

Parameters
$force_read : bool = false

True to force a new DB read (and update cache).

Tags
since
2.6.0
Return values
mixed —

set_amount()

Set amount.

public set_amount(float $amount) : mixed
Parameters
$amount : float

Amount.

Tags
since
3.0.0
Return values
mixed —

set_code()

Set coupon code.

public set_code(string $code) : mixed
Parameters
$code : string

Coupon code.

Tags
since
3.0.0
Return values
mixed —

set_date_created()

Set date_created

public set_date_created(string|int|null $date) : mixed
Parameters
$date : string|int|null

UTC timestamp, or ISO 8601 DateTime. If the DateTime string has no timezone or offset, WordPress site timezone will be assumed. Null if there is no date.

Tags
since
3.0.0
Return values
mixed —

set_date_expires()

Set expiration date.

public set_date_expires(string|int|null $date) : mixed
Parameters
$date : string|int|null

UTC timestamp, or ISO 8601 DateTime. If the DateTime string has no timezone or offset, WordPress site timezone will be assumed. Null if there is no date.

Tags
since
3.0.0
Return values
mixed —

set_date_modified()

Set date_modified

public set_date_modified(string|int|null $date) : mixed
Parameters
$date : string|int|null

UTC timestamp, or ISO 8601 DateTime. If the DateTime string has no timezone or offset, WordPress site timezone will be assumed. Null if there is no date.

Tags
since
3.0.0
Return values
mixed —

set_description()

Set coupon description.

public set_description(string $description) : mixed
Parameters
$description : string

Description.

Tags
since
3.0.0
Return values
mixed —

set_discount_type()

Set discount type.

public set_discount_type(string $discount_type) : mixed
Parameters
$discount_type : string

Discount type.

Tags
since
3.0.0
Return values
mixed —

set_email_restrictions()

Set email restrictions.

public set_email_restrictions([array<string|int, mixed> $emails = array() ]) : mixed
Parameters
$emails : array<string|int, mixed> = array()

List of emails.

Tags
since
3.0.0
Return values
mixed —

set_error_message()

Sets the error_message string.

public set_error_message(string $message) : void
Parameters
$message : string

Message string.

Return values
void —

set_exclude_sale_items()

Set if this coupon should excluded sale items or not.

public set_exclude_sale_items(bool $exclude_sale_items) : mixed
Parameters
$exclude_sale_items : bool

If should exclude sale items.

Tags
since
3.0.0
Return values
mixed —

set_excluded_product_categories()

Set the product category IDs this coupon cannot be used with.

public set_excluded_product_categories(array<string|int, mixed> $excluded_product_categories) : mixed
Parameters
$excluded_product_categories : array<string|int, mixed>

List of excluded product categories.

Tags
since
3.0.0
Return values
mixed —

set_excluded_product_ids()

Set the product IDs this coupon cannot be used with.

public set_excluded_product_ids(array<string|int, mixed> $excluded_product_ids) : mixed
Parameters
$excluded_product_ids : array<string|int, mixed>

Exclude product IDs.

Tags
since
3.0.0
Return values
mixed —

set_free_shipping()

Set if this coupon enables free shipping or not.

public set_free_shipping(bool $free_shipping) : mixed
Parameters
$free_shipping : bool

If grant free shipping.

Tags
since
3.0.0
Return values
mixed —

set_individual_use()

Set if this coupon can only be used once.

public set_individual_use(bool $is_individual_use) : mixed
Parameters
$is_individual_use : bool

If is for individual use.

Tags
since
3.0.0
Return values
mixed —

set_limit_usage_to_x_items()

Set usage limit to x number of items.

public set_limit_usage_to_x_items(int|null $limit_usage_to_x_items) : mixed
Parameters
$limit_usage_to_x_items : int|null

Limit usage to X items.

Tags
since
3.0.0
Return values
mixed —

set_maximum_amount()

Set the maximum spend amount.

public set_maximum_amount(float $amount) : mixed
Parameters
$amount : float

Maximum amount.

Tags
since
3.0.0
Return values
mixed —

set_meta_data()

Set all meta data from array.

public set_meta_data(array<string|int, mixed> $data) : mixed
Parameters
$data : array<string|int, mixed>

Key/Value pairs.

Tags
since
2.6.0
Return values
mixed —

set_minimum_amount()

Set the minimum spend amount.

public set_minimum_amount(float $amount) : mixed
Parameters
$amount : float

Minimum amount.

Tags
since
3.0.0
Return values
mixed —

set_object_read()

Set object read property.

public set_object_read([bool $read = true ]) : mixed
Parameters
$read : bool = true

Should read?.

Tags
since
3.0.0
Return values
mixed —

set_product_categories()

Set the product category IDs this coupon can be used with.

public set_product_categories(array<string|int, mixed> $product_categories) : mixed
Parameters
$product_categories : array<string|int, mixed>

List of product categories.

Tags
since
3.0.0
Return values
mixed —

set_product_ids()

Set the product IDs this coupon can be used with.

public set_product_ids(array<string|int, mixed> $product_ids) : mixed
Parameters
$product_ids : array<string|int, mixed>

Products IDs.

Tags
since
3.0.0
Return values
mixed —

set_props()

Set a collection of props in one go, collect any errors, and return the result.

public set_props(array<string|int, mixed> $props[, string $context = 'set' ]) : bool|WP_Error

Only sets using public methods.

Parameters
$props : array<string|int, mixed>

Key value pairs to set. Key is the prop and should map to a setter function name.

$context : string = 'set'

In what context to run this.

Tags
since
3.0.0
Return values
bool|WP_Error —

set_short_info()

Sets the coupon parameters from a reapply information set generated with 'get_short_info'.

public set_short_info(string $info) : mixed
Parameters
$info : string

JSON string with reapply information as returned by 'get_short_info'.

Return values
mixed —

set_status()

Set coupon status.

public set_status(string $status) : mixed
Parameters
$status : string

Status.

Tags
since
3.0.0
Return values
mixed —

set_usage_count()

Set how many times this coupon has been used.

public set_usage_count(int $usage_count) : mixed
Parameters
$usage_count : int

Usage count.

Tags
since
3.0.0
Return values
mixed —

set_usage_limit()

Set the amount of times this coupon can be used.

public set_usage_limit(int $usage_limit) : mixed
Parameters
$usage_limit : int

Usage limit.

Tags
since
3.0.0
Return values
mixed —

set_usage_limit_per_user()

Set the amount of times this coupon can be used per user.

public set_usage_limit_per_user(int $usage_limit) : mixed
Parameters
$usage_limit : int

Usage limit.

Tags
since
3.0.0
Return values
mixed —

set_used_by()

Set which users have used this coupon.

public set_used_by(array<string|int, mixed> $used_by) : mixed
Parameters
$used_by : array<string|int, mixed>

List of user IDs.

Tags
since
3.0.0
Return values
mixed —

set_virtual()

Set coupon virtual state.

public set_virtual(bool $virtual) : mixed
Parameters
$virtual : bool

Whether it is virtual or not.

Tags
since
3.2.0
Return values
mixed —

update_meta_data()

Update meta data by key or ID, if provided.

public update_meta_data(string $key, string|array<string|int, mixed> $value, int $meta_id) : mixed
Parameters
$key : string

Meta key.

$value : string|array<string|int, mixed>

Meta value.

$meta_id : int

Meta ID.

Tags
since
2.6.0
Return values
mixed —

error()

When invalid data is found, throw an exception unless reading from the DB.

protected error(string $code, string $message[, int $http_status_code = 400 ][, array<string|int, mixed> $data = array() ]) : mixed
Parameters
$code : string

Error code.

$message : string

Error message.

$http_status_code : int = 400

HTTP status code.

$data : array<string|int, mixed> = array()

Extra error data.

Tags
throws
WC_Data_Exception

Data Exception.

since
3.0.0
Return values
mixed —

filter_null_meta()

Filter null meta values from array.

protected filter_null_meta(mixed $meta) : bool
Parameters
$meta : mixed

Meta value to check.

Tags
since
3.0.0
Return values
bool —

get_hook_prefix()

Prefix for action and filter hooks on data.

protected get_hook_prefix() : string
Tags
since
3.0.0
Return values
string —

get_prop()

Gets a prop for a getter method.

protected get_prop(string $prop[, string $context = 'view' ]) : mixed

Gets the value from either current pending changes, or the data itself. Context controls what happens to the value before it's returned.

Parameters
$prop : string

Name of prop to get.

$context : string = 'view'

What the value is for. Valid values are view and edit.

Tags
since
3.0.0
Return values
mixed —

is_internal_meta_key()

Check if the key is an internal one.

protected is_internal_meta_key(string $key) : bool
Parameters
$key : string

Key to check.

Tags
since
3.2.0
Return values
bool — true if it's an internal key, false otherwise

read_object_from_database()

If the object has an ID, read using the data store.

protected read_object_from_database() : mixed
Tags
since
3.4.1
Return values
mixed —

set_date_prop()

Sets a date prop whilst handling formatting and datetime objects.

protected set_date_prop(string $prop, string|int $value) : mixed
Parameters
$prop : string

Name of prop to set.

$value : string|int

Value of the prop.

Tags
since
3.0.0
Return values
mixed —

set_prop()

Sets a prop for a setter method.

protected set_prop(string $prop, mixed $value) : mixed

This stores changes in a special array so we can track what needs saving the DB later.

Parameters
$prop : string

Name of prop to set.

$value : mixed

Value of the prop.

Tags
since
3.0.0
Return values
mixed —