br-woo-routes

better-route: WooCommerce routes

Register Woo routes during rest_api_init and retain the returned Router when contracts are needed.

use BetterRoute\BetterRoute;

add_action('rest_api_init', static function (): void {
    $woo = BetterRoute::wooRouteRegistrar()->register('myapp/v1', [
        'basePath' => 'woo',
        'requireHpos' => true,
        'deleteMode' => 'trash',
        'actions' => [
            'customers' => ['list', 'get'],
            'coupons' => [],
        ],
        'permissions' => [
            'orders.list' => 'manage_woocommerce',
            'orders.create' => 'manage_woocommerce',
        ],
    ]);
});

Routes cover orders, products, customers, and coupons under /wp-json/myapp/v1/woo by default.

Actions and permissions

Each resource supports list, get, create, update, and delete; update registers both PUT and PATCH.

• Omit actions.<resource> for full CRUD.
• Pass [] to disable that resource.
• Invalid action names or a non-array value throw.

Permission keys use <resource>.<action>. A value may be bool, capability string, any-of capability list, or callable receiving the request and optionally the registrar. Unrecognized/empty rules deny. Defaults are manage_woocommerce.

Customer writes also enforce native user capabilities inside the service:

• create: create_users;
• update: edit_user for the target;
• delete: delete_user for the target.

Customer list/get expose users with the customer role only; a general WordPress user directory is intentionally not provided.

Lists

GET /wp-json/myapp/v1/woo/orders?status=processing&sort=-date_created&page=1&per_page=50&fields=id,total,status

Lists return pagination in the JSON envelope:

{"data": [], "meta": {"page": 1, "perPage": 50, "total": 0}}

Do not expect X-WP-Total or X-WP-TotalPages; Better Route Woo pagination is in meta.

per_page > maxPerPage returns 400 validation_failed; it is not clamped. sort=-field means DESC. Services add an ID tie-breaker so equal primary sort values paginate deterministically.