For developers

What developers can build on: hooks, shortcodes, blocks, REST routes and WP-CLI commands, taken from each plugin’s own readme and from what this site has registered.

DoctorX Made-to-Measure Checkout

Shortcodes: [drx_mtm_account], [drx_mtm_picker], [drx_mtm_checkout], [drx_mtm_order], [drx_mtm_price_table]
Blocks: doctorx-commerce/picker
REST routes: /doctorx-commerce/v1, /doctorx-commerce/v1/cart, /doctorx-commerce/v1/cart/add, /doctorx-commerce/v1/cart/line, /doctorx-commerce/v1/cart/clear, /doctorx-commerce/v1/cart/code, /doctorx-commerce/v1/quote, /doctorx-commerce/v1/order, /doctorx-commerce/v1/paypal/create, /doctorx-commerce/v1/paypal/capture, /doctorx-commerce/v1/paypal/webhook

Every function below is defined only when no other plugin defines it: check function_exists() first, because this plugin may be switched off. DOCTORX_COMMERCE_VERSION holds the version. Money is in cents (integers) unless stated; sizes are in base units (eighths of an inch for inch products, millimetres for centimetre products); dates are UTC.

Orders

doctorx_commerce_get_order( $id_or_reference ) returns an order or null: id, reference, status, status_label, created_at, paid_at (ISO 8601, UTC), customer (user_id, name, email, phone, address_1, address_2, city, province, postal, country), fulfilment (ship or pickup), tax_province, currency, subtotal_cents (before the discount), shipping_cents, fee_cents, discount_code, discount_cents, tax_cents, taxes (label, type, rate in thousandths of a percent, cents), total_cents, paid_cents, refunded_cents, payment_method, items (product_id, title, sku, size_text, area_text, width, height, unit, material_id, material_name, options, label, qty, each_cents, line_cents, discount_cents (the line's share of the discount)), meta, view_url (the customer's private link), admin_url.
doctorx_commerce_get_orders( array $args ): status (a status or a list), email, user_id, search, since, until (UTC "Y-m-d H:i:s"), limit (default 50, at most 500), offset. Newest first.
doctorx_commerce_get_customer_orders( $user_id_or_email, array $args ).
doctorx_commerce_order_statuses(): pending (Awaiting payment), review (Payment needs review), paid, in_production, shipped, ready (Ready for pickup), delivered, cancelled, refunded.
doctorx_commerce_set_order_status( $order_id, $status, $note ): moves an order the way the order screen would; paid and refunded come only from a payment or a refund.
doctorx_commerce_get_order_meta( $order_id, $key ) and doctorx_commerce_update_order_meta( $order_id, $key, $value ) (null removes it): small values of your own on an order.
doctorx_commerce_order_url( $order_id ): the customer's private link.

Products, prices and the cart

doctorx_commerce_get_products( array( 'status' => 'publish' ) ) returns one array per product that has a price. Always: id, price (float, dollars: the "From" price the product page and its structured data show, for one item at the example size with the cheapest material and required options, before tax; send this to shopping feeds so the feed matches the page), price_from (the lowest price at the smallest size), currency, in_stock (true while the store is open and the product is published; filter doctorx_commerce_product_in_stock). Also price_cents, sku, title, description, url, image_url, gallery (image URLs), categories (names), brand (the business name), mpn (the SKU) and material (names joined with "/"). Arguments: status (a status or a list), ids, limit. doctorx_commerce_get_product( $id ) returns one.
doctorx_commerce_get_product_config( $product_id ), without prices: mode (area or fixed), unit (in or cm), min_w, max_w, min_h, max_h, example_w, example_h (base units), max_qty, label_field, materials (swatch id => name), groups (each id, label, required, show_if (array( group, choice ) or null), choices (id => label)).
doctorx_commerce_quote( $product_id, array $config ): the server's price for width, height, material, options (group => choice), qty; returns each_cents, line_cents and the description, or a WP_Error with a message per field.
doctorx_commerce_cart_add( array $item ) (product, width, height, material, options, qty, label) returns true or a WP_Error; doctorx_commerce_cart_clear(); doctorx_commerce_cart_url() (the checkout page); doctorx_commerce_account_url().
doctorx_commerce_money( $cents ): a price in the store's currency, as the shop prints it.
doctorx_commerce_cart_totals( array( 'province' => 'ON', 'fulfilment' => 'ship' ) ): the current visitor's cart priced as the checkout shows it (the REST GET cart figures: subtotal_cents, discount_cents, shipping_cents, tax_cents, total_cents, lines).
doctorx_commerce_store_is_public(): true when the store is open to the public. While it is open to staff only (or off), this plugin's Checkout, Order status and My account pages are private; a plugin that makes its own shop pages can keep them private too and publish them on doctorx_commerce_store_opened.
doctorx_commerce_payment_methods( $ready_only = true ): id => label of the ways to pay the current visitor is offered (etransfer, bank, cheque, delivery, paypal, and account when a plugin offers it), or every method the store knows with false. Every method except paypal is offline: the shop marks the order paid by hand.

Payment on account

The account method ("On account (invoice)") is never offered to ordinary shoppers. Offer it to a customer by adding it in the doctorx_commerce_payment_methods filter, for example for approved trade customers:

add_filter( 'doctorx_commerce_payment_methods', function ( $methods, $ready_only ) {
    if ( $ready_only && my_customer_may_pay_on_account( get_current_user_id() ) ) {
        $methods['account'] = true; // or array( 'label' => ..., 'note' => ... )
    }
    return $methods;
}, 10, 2 );

Such an order is placed as "Awaiting payment" with its order number as the invoice reference, and the shop marks it paid on the order screen, like an e-Transfer.

Actions

doctorx_commerce_order_placed ( $order_id, $order ): an order was placed (not yet paid).
doctorx_commerce_order_paid ( $order_id, $order ): paid in full (a verified PayPal capture, or an offline payment marked received). Fires once per order.
doctorx_commerce_order_status_changed ( $order_id, $status, $old_status, $order, $note ).
doctorx_commerce_order_delivered ( $order_id, $order ): delivered or collected (for example, to ask for a review).
doctorx_commerce_order_cancelled ( $order_id, $order ).
doctorx_commerce_order_refunded ( $order_id, $cents, $order ).
doctorx_commerce_payment_mismatch ( $order_id, $detail, $facts ): a payment did not match its order; it was left unpaid and marked for review.
doctorx_commerce_product_changed ( $product_id ): a product's details, prices, materials or availability changed; 0 means every product (a store-wide setting such as the currency or the store switch changed).
doctorx_commerce_before_picker ( $product_id ): print above the picker and its prices.
doctorx_commerce_product_after_summary ( $product_id ): print after the picker on a product's own page (reviews, ratings).
doctorx_commerce_account_top ( $user ): print at the top of a signed-in customer's account page.
doctorx_commerce_store_opened: the store has just been opened to the public (fires once per opening).

Filters

doctorx_commerce_pricing_rules ( $rules, $product_id ): change a product's rules (for example trade prices). The picker preview, the cart, the checkout and the order all read the filtered rules, so they always agree. Money in cents: lines (base, rate), price (fixed products), groups[].choices[] (add, add_rate).
doctorx_commerce_payment_methods ( $methods, $ready_only ): the ways to pay (id => array( label, note )); see "Payment on account".
doctorx_commerce_fulfilment_options ( $options ): ship => label and/or pickup => label for the current visitor.
doctorx_commerce_order_row ( $row, $input, $totals ): the order just before it is saved. Only meta may be changed (an array of your own values); amounts can't be.
doctorx_commerce_account_order_actions ( $actions, $order_id, $user_id ): buttons on the customer's account and order pages, each array( 'url' => …, 'label' => … ). $user_id is 0 for a guest who opened the order from its link.
doctorx_commerce_product_schema ( $data, $post ): the Product JSON-LD on a product page (add ratings here).
doctorx_commerce_products ( $products, $args ): the list from doctorx_commerce_get_products().
doctorx_commerce_tax_rates ( $rates, $province ): the taxes charged in a province.
doctorx_commerce_discount_valid ( true, $code, $context ): return a WP_Error (its message is shown to the customer) to refuse a discount code. $code: code, kind (percent or fixed), amount (hundredths of a percent, or cents), min_cents, starts_on, ends_on, max_uses, per_customer, used, products. $context: subtotal, lines (index, product_id, line_cents), email (when known), stage (cart, order or payment), order (at payment).
doctorx_commerce_discount_amount ( $cents, $code, $context ): change what a code takes off; it is always kept between 0 and the eligible goods.
doctorx_commerce_method_starts_unpaid ( $starts, $method ): methods whose orders may be made and delivered before payment (default delivery and account); payment is recorded later with "Mark paid".
doctorx_commerce_currencies ( $list ): the currencies offered on the Store settings (code => label).
doctorx_commerce_email ( $mail ): an order email (to, subject, html, text, headers, context); return false to stop it.
doctorx_commerce_status_emails ( $texts, $order ): which status changes email the customer.
doctorx_commerce_payment_instructions ( $lines, $order ): the paragraphs telling the customer how to pay, for every method (add a due date for orders on account, for example).
doctorx_commerce_paypal_order_payload ( $payload, $order ): the PayPal order request (the amount, invoice number and order id are always put back).
doctorx_commerce_crm_lead ( $lead, $order ): what is sent to DoctorX Customers; return an empty value to send nothing.
doctorx_commerce_social_roles ( $roles ): the roles social sign-in may sign in (default customer and subscriber). An account with any other role, or any capability listed in doctorx_commerce_social_blocked_caps, is always refused.
doctorx_commerce_social_blocked_caps ( $caps ): capabilities that make an account staff for social sign-in.
doctorx_commerce_capability ( $cap ): who may manage orders and settings (default manage_options); doctorx_commerce_pricing_capability ( $cap ): who may change prices.
doctorx_commerce_may_shop ( $ok, $state ): whether the current visitor may add to the cart and order.
doctorx_commerce_client_ip ( $ip ): the address used for rate limits (behind a proxy).
doctorx_commerce_block_editor_for_products ( false ): edit products in the block editor instead of the classic one.
doctorx_command_center_modules: this plugin adds itself to DoctorX Command Center.

Sales Tax Report contract

DoctorX Sales Tax Report calls drx_commerce_orders_for_accounting( $from, $to, $which ) with site-time dates ("Y-m-d") and $which paid (orders with money received, net of refunds) or awaiting (placed, not paid, not cancelled: including orders paid on delivery that were already delivered). Each row, amounts in dollars: id, number, edit, date (the day it was placed, site time), province (where it was taxed), status, customer, sales (goods after the discount), shipping, fees, tax, tax_names (joined with " + "), taxes (GST, HST, PST, QST, other), discount (taken off the goods, before tax), total, refunded, refunded_tax, payment, items (name, qty, total: before tax, after the line's share of the discount). For paid rows sales + shipping + fees + tax = total; refunds take the tax and the discount back in the same proportion they were paid.

REST routes (namespace doctorx-commerce/v1)

GET cart, POST cart/add, POST cart/line, POST cart/clear, POST cart/code (the code only; the server works out what it is worth), POST quote, POST order, POST paypal/create, POST paypal/capture, POST paypal/webhook. The cart and order routes follow the store switch and are rate limited; an existing order is reached only with its reference and private key.

DoctorX Trade Accounts

Shortcodes: [doctorx_trade_notice], [doctorx_trade_apply], [doctorx_trade_portal], [doctorx_trade_dealers], [doctorx_trade_spec_link], [doctorx_trade_projects]

Shortcodes

[doctorx_trade_apply] the application form. kind="..." chooses one of your kinds of business in advance (so does ?kind= in the address).
[doctorx_trade_portal] the trade portal.
[doctorx_trade_dealers] the dealer directory.
[doctorx_trade_projects] the projects page with its enquiry form.
[doctorx_trade_notice] the "trade account" line, shown only to approved dealers.
[doctorx_trade_spec_link text="..."] a link to the spec sheet, shown only to people who may open it.

Hooks for developers

Filters: doctorx_trade_capability, doctorx_trade_email (change or stop any email), doctorx_trade_is_spam, doctorx_trade_client_ip, doctorx_trade_crm_lead, doctorx_trade_crm_task, doctorx_trade_crm_enquiry_lead, doctorx_trade_upload_types, doctorx_trade_private_dir, doctorx_trade_block_admin, doctorx_trade_money.
Actions: doctorx_trade_applied, doctorx_trade_status_changed, doctorx_trade_dealer_message, doctorx_trade_project_enquiry, doctorx_trade_enquiry_status, doctorx_trade_tender_filed.

DoctorX Reviews

Shortcodes: [doctorx_reviews], [doctorx_reviews_summary], [drx_reviews], [drx_reviews_summary]

Functions (check function_exists() first): doctorx_reviews_get_rating( $product_id ), doctorx_reviews_get_reviews( $args ), doctorx_reviews_product_block( $product_id ), doctorx_reviews_schedule_request( $source, $order_id ).

Shortcodes: [doctorx_reviews] (every published review; product="123" for one product), [doctorx_reviews_summary] (stars and count), [doctorx_review_form] (the form page).

Filters: doctorx_reviews_product_schema (pass your own Product markup through it to get the rating added), doctorx_reviews_add_schema, doctorx_reviews_should_ask, doctorx_reviews_request_email, doctorx_reviews_display_name, doctorx_reviews_moderator_caps, doctorx_reviews_sources and doctorx_reviews_get_order (add another shop). Actions: doctorx_reviews_submitted, doctorx_reviews_changed, doctorx_reviews_request_sent.

DoctorX Made-to-Measure Checkout is read through doctorx_commerce_get_order(), doctorx_commerce_get_orders(), the doctorx_commerce_order_delivered and doctorx_commerce_order_cancelled actions and the doctorx_commerce_product_schema filter. Its product pages show reviews where it fires do_action( 'doctorx_commerce_product_after_summary', $product_id ); ratings are added to its product markup only once it does (override with doctorx_reviews_commerce_shows_reviews). Its account page can offer a "Review" button through the doctorx_commerce_account_order_actions filter. Statuses that count as delivered: doctorx_reviews_woocommerce_delivered_statuses and doctorx_reviews_commerce_delivered_statuses.