Pro module13 abilities

Paid Memberships Pro ability reference

Reference for the GoBuildWP Pro 1.12.4 source. Installed schemas and policy remain authoritative.

This Paid Memberships Pro ability reference covers how an agent manages membership levels and discount codes, reads orders and a member's current levels, and grants or cancels a level for a member, with each call spelling out what the change means at the payment gateway before it runs.

By GoBuildWPContent updated 13 October 2026How we check claims

Read-only, write and destructive groups describe the source annotations. They do not establish a minimum safety profile, human approval or undo support. Those controls are separate: check the installed ability, the connected user and the active site policy before calling it. A read can still return sensitive data. These pages are not evidence that every operation passed an end-to-end runtime test.

What Paid Memberships Pro needs before these load

Paid Memberships Pro 3.2.0 or newer must be active; the gate needs PMPRO_VERSION, pmpro_getAllLevels() and pmpro_getMembershipLevelsForUser(). Writing levels and discount codes and reading orders check PMPro's per-screen capabilities (pmpro_membershiplevels, pmpro_discountcodes, pmpro_orders), and manage_options also passes. Listing levels, reading a member's levels, and granting or cancelling one use GoBuildWP's standard manage_options check. Deleting a level relies on a PMPro 3.8 function; on older installs that call returns pmpro_unsupported rather than attempting the delete.

Minimum (base): 3.2.0 WPPILOT_PRO_PMPRO_MIN_VERSION
Paid Memberships Pro editions: free, pro
Agent skills shipped: paid-memberships-pro-integration

What granting or cancelling a level does to billing

Granting goes through pmpro_changeMembershipLevel(). It opens no checkout, charges nothing and verifies no payment. If the level belongs to a group that allows one level per member, PMPro ends whatever level the member held in that group and asks the gateway to cancel that level's subscription. Cancelling goes through pmpro_cancelMembershipLevel(): access ends immediately, and PMPro asks the payment gateway to cancel the member's subscription for that level unless a site filter on pmpro_cancel_previous_subscriptions turns that off. The result verifies that access ended, not the gateway outcome: if the gateway call fails, PMPro marks the subscription cancelled locally and emails the site admin, and billing can continue until someone cancels it at the gateway. Nothing is refunded. Both calls are destructive, so they need confirm: true. A member already in the requested state gets changed: false, and every response lists the active level ids before and after.

Changes that stop and ask

Some writes refuse with wppilot_confirmation_required until the call carries confirm=true, which the agent should send only after the user agrees. Creating a level with no price while signups are open would let anyone join free, so it needs confirm. A discount code that sells any level below its normal price needs confirm too, and goes live for checkout as soon as its start date arrives. Updating a level's price warns that active members keep their current terms.

Deleting a level is the most guarded call. dry_run reports active_members and the member ids. With members present it is refused (pmpro_level_has_members) until the user picks member_policy cancel or reassign; more than 100 members are refused as pmpro_too_many_members; and if any member cannot be processed the level stays in place with the result members_partially_processed.

Why rollback-change cannot help here

Levels, codes and orders live in PMPro's own tables, which none of wppilot/rollback-change's strategies restore. Each write is still logged, marked reversible: false, and returns the previous values so a person can put them back. Orders are read through MemberOrder::get_orders() with an allowlist of fields, so card type, last four digits, expiry, billing address, transaction ids and notes never appear. The order query has no offset: narrow it with UTC dates, a user, a level or a gateway, up to 100 rows.

Representative call sequence

This sequence describes the documented calls and checks to perform. It is not a recorded result from an installed WordPress site. Inspect returned errors and partial results, then verify the saved values and affected output before proceeding.

Retire the Legacy Monthly level and move its members to Standard.

01 wppilot/paid-memberships-pro-list-levels Returns both levels' ids and billing terms so the user can see what members are moving to.
02 wppilot/paid-memberships-pro-delete-level With dry_run=true, reports how many active members Legacy Monthly has and whether the delete would be refused.
03 wppilot/paid-memberships-pro-delete-level With member_policy=reassign, reassign_to_level_id and confirm: true, moves each member without charging them and then deletes the level and its links.

Paid Memberships Pro in practice

Describing a PMPro level's price in the fields GoBuildWP takes

A level's price is spread over several fields, and the zero values carry meaning. initial_payment is charged at checkout. billing_amount is the recurring charge, and setting it to 0 means no recurring billing, which also clears the cycle and trial fields. cycle_number and cycle_period set how often the recurring charge runs, with the period one of Hour, Day, Week, Month or Year. billing_limit caps the number of recurring payments, where 0 means bill until cancelled. trial_amount and trial_limit describe a reduced price for the first few payments, and expiration_number with expiration_period ends access after a fixed time, where 0 means the level never expires.

So a yearly plan at 120 with no setup fee is initial_payment 120, billing_amount 120, cycle_number 1 and cycle_period Year. A level is placed in a level group, which defaults to the first group; an unknown group returns pmpro_group_not_found and an unknown restricted category returns pmpro_category_not_found. Discount codes use the same price fields per level, so the same reading applies to a code's pricing.

Discount code naming, limits and collisions

A code can be up to 32 characters of letters, digits and hyphens, and one is generated when none is given. max_uses of 0 means unlimited. Creating a code that already exists returns pmpro_discount_code_exists with the existing id, so the agent updates it instead of creating a second one. Because the code text cannot be renamed later, settle the spelling before creating it; a typo means deleting the code and creating another.

wppilot/paid-memberships-pro-list-discount-codes searches with up to 100 characters and returns 20 codes per page by default, up to 100. Each code's per-level pricing is listed with the use count, which is the quickest way to see whether a promotion is still being used.

Narrowing a PMPro order query when there is no paging

wppilot/paid-memberships-pro-list-orders returns the most recent orders, 20 by default and at most 100, and cannot skip ahead. To look further back, narrow instead: filter by status (success, pending, refunded, review, token, error, or a status a gateway add-on uses), by user_id, level_id or gateway, and by start_date and end_date, both inclusive Y-m-d dates in UTC. A date in any other shape returns pmpro_invalid_date. A month of orders on a busy site can still exceed the cap, and even a week can. Split the range into smaller ranges until every read returns fewer than 100 rows, because a read that comes back with exactly 100 may have left orders out, and say in the answer that the totals came from several reads.

Paid Memberships Pro errors to recognise

wppilot/paid-memberships-pro-check-setup reports the active gateway key and whether members may hold several levels at once. Read both before granting a level, because on a site with one level per group, granting can end a level the member already has and ask the gateway to cancel that level's subscription.

pmpro_invalid_reassign: the level chosen for reassigned members is the one being deleted, or does not exist.
pmpro_cancellation_verification_failed: PMPro accepted the cancellation, but the member still holds the level when read back. Check the member's profile in wp-admin before cancelling again.
pmpro_unsupported: this PMPro install lacks an API the write needs, for example an older version. GoBuildWP refuses rather than writing around it.
pmpro_level_not_found, pmpro_user_not_found and pmpro_discount_code_not_found: the id does not match anything on this site.

Questions about Paid Memberships Pro

Does assigning a level charge the member?

No. It grants access administratively with no checkout or payment, which is why the agent must say so and get confirmation before calling it.

Can the agent refund or cancel an order?

No. Orders are read-only through GoBuildWP; refunds belong in PMPro's order screen or at the gateway.

Can I undo a level or discount-code edit?

Not with wppilot/rollback-change, because PMPro stores them in its own tables. The response returns the previous values so they can be written back.

Paid Memberships Pro reads

Ability	What it does
`wppilot/paid-memberships-pro-check-setup`Check Paid Memberships Pro Setup	Reports the PMPro version, membership-level count, gateway name without credentials, multiple-membership mode, and administration capabilities.
`wppilot/paid-memberships-pro-get-user-memberships`Get User Memberships	Reads a WordPress user’s PMPro memberships without returning email, billing address, payment tokens, order codes, or gateway data.
`wppilot/paid-memberships-pro-list-discount-codes`List Discount Codes	Lists PMPro discount codes with dates, use limits, times used and the price each level costs with the code.
`wppilot/paid-memberships-pro-list-levels`List Membership Levels	Lists PMPro membership levels with signup visibility, initial payment, recurring billing, trial, and expiration configuration. No gateway credentials are exposed.
`wppilot/paid-memberships-pro-list-orders`List Membership Orders	Lists the most recent PMPro orders with status, gateway, environment, subtotal, tax, total, level and date, read through MemberOrder::get_orders(). Never returns card details, billing addresses, transaction ids or order notes.

Paid Memberships Pro writes

Ability	What it does
`wppilot/paid-memberships-pro-create-discount-code`Create Discount Code	Creates a PMPro discount code through PMPro_Discount_Code::save() with dates, a use limit and per-level pricing. Price fields left out of a level take that level's normal values. A code that sells any level below its normal price needs confirm=true, and is live for checkout as soon as it starts. Not undoable through the change ledger; delete the code instead.
`wppilot/paid-memberships-pro-create-level`Create Membership Level	Creates a PMPro membership level with pricing, recurring billing, trial, expiration, signup visibility, confirmation text and restricted categories. Saved through PMPro_Membership_Level::save(). Omitted prices are 0 and signups default to open, so a level given no initial_payment or billing_amount needs allow_signups=false or confirm=true. Not undoable through the change ledger; delete the level instead.
`wppilot/paid-memberships-pro-update-discount-code`Update Discount Code	Changes a PMPro discount code's dates, use limit or level pricing (levels replaces the whole list; a field left out of a level keeps the code's current value for it). New level pricing below a level's normal price needs confirm=true. The code text itself cannot be renamed. Returns the previous code; not undoable through the change ledger.
`wppilot/paid-memberships-pro-update-level`Update Membership Level	Changes the given fields of a PMPro level and keeps the rest. New prices apply to future checkouts only; existing gateway subscriptions keep billing their old amount. Returns the previous level; not undoable through the change ledger.

Destructive Paid Memberships Pro calls

Ability	What it does
`wppilot/paid-memberships-pro-assign-user-level`Assign User Membership Level	Administratively grants a PMPro level to an existing user through pmpro_changeMembershipLevel(). It does not create a checkout, charge a gateway, or verify payment, so explicit confirmation is mandatory.
`wppilot/paid-memberships-pro-cancel-user-level`Cancel User Membership Level	Cancels one PMPro membership level for a user through pmpro_cancelMembershipLevel(). This changes access and may trigger PMPro hooks; explicit confirmation is mandatory.
`wppilot/paid-memberships-pro-delete-discount-code`Delete Discount Code	Deletes a PMPro discount code and its level pricing, as PMPro's discount-code screen does. Past uses stay in the order history. Not undoable; the deleted code is returned.
`wppilot/paid-memberships-pro-delete-level`Delete Membership Level	Deletes a PMPro level and its category, page, discount-code and group links. Refused while the level has active members unless member_policy says what happens to them: "cancel" ends each membership through pmpro_cancelMembershipLevel() (PMPro requests cancellation of the linked gateway subscription; filters or gateway failure can leave billing active, so verify at the gateway), "reassign" moves each member to reassign_to_level_id without charging. Needs PMPro 3.8+.

For the task-level view of Paid Memberships Pro, with worked requests and what to check afterwards, see Paid Memberships Pro integration page.