WP-CLI - Referral Commands

Referral management is available via the command-line with the introduction of the wp affwp referral WP-CLI command.

Usage: wp affwp referral <sub-command>

There are five referral sub-commands to choose from:

  • create – Creates a referral.
  • delete – Deletes a referral.
  • get – Retrieves a referral object or field(s) by ID.
  • list – Displays a list of referrals.
  • update – Updates an existing referral.

Clicking any of the sub-commands listed above will take you to more comprehensive documentation about the arguments they require and options available.

Be careful!

Sub-commands like delete or update have the very real possibility of wreaking havoc on your AffiliateWP data when not used with caution. Make sure you know what you're changing or removing, and heed confirmation messages when executing sub-commands.


create

The affwp referral create sub-command is used to create new referrals.

Usage: wp affwp referral create <username|ID> [--amount=<number>] [--description=<description>] [--reference=<reference>] [--context=<context>] [--status=<status>]

Note: create assumes you already added a user account and have a user ID or username to pass as the first argument, which is required.

Options

All options are optional unless noted otherwise.

  • username|user_id (required)
    Username or ID for an existing affiliate with whom to associate the created referral.
  • --amount
    Referral amount.
  • --description
    Referral description. 
  • --reference
    Referral reference. Typically this will be a link or other data which points to the originating transaction, such as an order ID.
  • --status
    Referral status. Accepts 'pending', 'rejected', 'paid', or 'unpaid'. If not specified, the AffiliateWP default of 'pending' will be used.
  • --context
    The context of the referral.

Examples

# Creates a referral with a $1.00 referral amount.
wp affwp referral create edduser1 --amount=1.00


# Creates a referral for user ID 5, with an amount of 3.00, a description of 'Big Sale', and a reference of '123'
wp affwp referral create 5 --amount=3 --description='Big Sale' --reference=123


# Creates a referral for user ID 142 with a status of 'rejected'.
wp affwp referral create 142 --status=rejected

delete

The affwp referral delete sub-command is used to delete referrals.

Usage: wp affwp referral delete <username|affiliate_id> [--delete_data] [--delete_user] [--network]

Options

  • <referral_id> (required)
    Referral ID.

Examples

# Deletes the referral with an ID of 123
wp affwp referral delete 123

get

The affwp referral get sub-command is used to retrieve a single referral object.

Usage: wp affwp affiliate get <affiliate_id> [--field=<field>] [--fields=<fields>] [--format=<format>]

Options

All options are optional unless noted otherwise.

  • <id> The referral ID to retrieve.
  • --field=<field> Instead of returning the whole referral object, returns the value of a single field.
  • --fields=<fields> Limit the output to specific fields. Defaults to all fields.
  • --format=<format> Accepted values: table, json, csv, yaml. Default: table.

Examples

Usage: # save the referral field value to a file
wp post get 12 --field=earnings > earnings.txt

list

The affwp referral list sub-command is used to list out referrals based on given criteria.

Usage: wp affwp referral list [--<field>=<value>] [--field=<field>] [--fields=<fields>] [--format=<format>]

Options

All options are optional unless noted otherwise.

--
One or more args to pass to get_affiliates(). 'user_login' and 'name' are not affiliate fields and will be ignored.

  • --field
    Prints the value of a single field for each affiliate.
  • --fields
    Limit the output to specific affiliate fields.
  • --format
    Accepted values: table, csv, json, count, ids, yaml. Default: table
Available Fields

These fields will be displayed by default for each referral:

  • ID (alias for affiliate_id)
  • amount
  • affiliate_name
  • affiliate_id
  • visit_id
  • reference
  • description
  • status
  • date
  These fields are also optionally available:
  • currency
  • custom
  • campaign

Examples

# Lists referrals by the affiliate name
affwp referral list --field=affiliate_name

# List referrals with a percentage rate type, with the affiliate ID, rate, and earnings columns
affwp referral list --rate_type=percentage --fields=affiliate_id,rate,earnings

# List referrals by earnings in json format
affwp referral list --field=earnings --format=json

update

The affwp referral update sub-command is used to update a single referral based on given criteria.

Usage: wp affwp referral update <referral_id> [--affiliate=<username|affiliate_id>] [--amount=<number>] [--description=<description>] [--reference=<reference>] [--context=<context>] [--status=<status>]

Options

All options are optional unless noted otherwise.

<referral_id>
Referral ID.
--affiliate=<username|affiliate_id>
Affiliate ID or userna me.
--amount=<number>
Referral amount.
--description=<description>
Referral description.
--reference=<reference>
Referral reference (usually product information).
--context=<context>
Referral context (usually related to the integration, e.g. woocommerce)
--status=<status>
Referral status. Accepts 'unpaid', 'paid', 'pending', or 'rejected'.

Examples

# Updates referral ID 120 with an amount of $1
wp affwp referral update 120 --amount=1

# Updates referral ID 33 with a status of 'paid'
wp affwp referral update 33 --status=paid

# Updates referral ID 50 to belong to affiliate username woouser1
wp affwp referral update 50 --affiliate=woouser1