Add fulfillments REST API and hooks documentation #60152
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Testing GuidelinesHi @ismaeldcom , Apart from reviewing the code changes, please make sure to review the testing instructions (Guide) and verify that relevant tests (E2E, Unit, Integration, etc.) have been added or updated as needed. Reminder: PR reviewers are required to document testing performed. This includes:
|
…mmerce, woocommerce/client/admin
|
Warning Rate limit exceeded@tpaksu has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 3 minutes and 20 seconds before requesting another review. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughThis change introduces comprehensive public documentation for WooCommerce's order fulfillment system. It adds two new documentation files: one detailing all available REST API endpoints for order fulfillments, and another providing an in-depth reference for fulfillment-related action and filter hooks. Additionally, a changelog entry records the addition of this documentation. Changes
Sequence Diagram(s)WooCommerce Order Fulfillment REST API FlowsequenceDiagram
participant Client
participant REST API
participant WooCommerce Core
participant Database
Client->>REST API: Authenticate & send request (e.g., Create Fulfillment)
REST API->>WooCommerce Core: Validate request & permissions
WooCommerce Core->>Database: Create/Update/Delete fulfillment record
Database-->>WooCommerce Core: Fulfillment data
WooCommerce Core->>REST API: Return response (success/error)
REST API-->>Client: API response
alt notify_customer flag set
WooCommerce Core->>Client: Trigger notification via hooks
end
Estimated code review effort🎯 2 (Simple) | ⏱️ ~8 minutes ✨ Finishing Touches🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
Documentation and Community
|
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (4)
plugins/woocommerce/changelog/60152-add-fulfillments-documentation (1)
1-5: Minor formatting / field-name issues in changelog entry
- WooCommerce changelog files usually use the key
Description:rather thanComment:– verify with another recent entry to keep the schema consistent.- Line 5 appears to contain a stray
5(or an empty line incorrectly numbered). Remove to avoid noise in the generated release notes.Comment: Add public documentation of order fulfillment entity REST API and hooks. - -5plugins/woocommerce/client/admin/docs/features/fulfillments-hooks.md (2)
17-21: Parameter name mismatch ($datavs$fulfillment)The bullet list names the parameter
$data, while the code sample that follows uses$fulfillment. Use a single name throughout the doc to avoid confusion.- - `$data` (Fulfillment) - The created fulfillment object + - `$fulfillment` (Fulfillment) - The created fulfillment object
37-41: Same mismatch repeatedThe “after_fulfill” hook table has the same
$datavs$fulfillmentinconsistency – apply the same fix here and to any other occurrences for consistency.plugins/woocommerce/client/admin/docs/features/fulfillments-rest-api.md (1)
540-550: DELETE metadata example deviates from the path specThe endpoint path does not include a
{meta_key}segment, yet the example sends the key in the request body. Either:a) Change the path to
/metadata/{meta_key}and make it a route param, or
b) Document that the key must be supplied in the JSON body for aDELETErequest (unusual for REST).Clarify and align the example & table accordingly.
📜 Review details
Configuration used: .coderabbit.yml
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
plugins/woocommerce/client/admin/docs/features/images/fulfillment-status-text.pngis excluded by!**/*.png
📒 Files selected for processing (3)
plugins/woocommerce/changelog/60152-add-fulfillments-documentation(1 hunks)plugins/woocommerce/client/admin/docs/features/fulfillments-hooks.md(1 hunks)plugins/woocommerce/client/admin/docs/features/fulfillments-rest-api.md(1 hunks)
🧰 Additional context used
🧠 Learnings (3)
📓 Common learnings
Learnt from: jorgeatorres
PR: woocommerce/woocommerce#59675
File: .github/workflows/release-bump-as-requirement.yml:48-65
Timestamp: 2025-07-15T15:39:21.856Z
Learning: In WooCommerce core repository, changelog entries for all PRs live in `plugins/woocommerce/changelog/` directory and are processed during releases, not at the repository root level.
Learnt from: CR
PR: woocommerce/woocommerce#0
File: .cursor/rules/generate-pr-description.mdc:0-0
Timestamp: 2025-07-21T05:22:46.426Z
Learning: Provide clear, step-by-step instructions for how to test the changes in the PR description.
Learnt from: tpaksu
PR: woocommerce/woocommerce#59172
File: plugins/woocommerce/src/Internal/Fulfillments/Providers/MPLShippingProvider.php:14-21
Timestamp: 2025-06-26T10:47:27.212Z
Learning: In the WooCommerce fulfillments system, only the UPS shipping provider is currently fully implemented. All other shipping provider classes in plugins/woocommerce/src/Internal/Fulfillments/Providers/ are placeholders for future implementations, so empty shipping country arrays and stub methods in these classes are intentional and should not be flagged as issues.
📚 Learning: in woocommerce core repository, changelog entries for all prs live in `plugins/woocommerce/changelog...
Learnt from: jorgeatorres
PR: woocommerce/woocommerce#59675
File: .github/workflows/release-bump-as-requirement.yml:48-65
Timestamp: 2025-07-15T15:39:21.856Z
Learning: In WooCommerce core repository, changelog entries for all PRs live in `plugins/woocommerce/changelog/` directory and are processed during releases, not at the repository root level.
Applied to files:
plugins/woocommerce/changelog/60152-add-fulfillments-documentationplugins/woocommerce/client/admin/docs/features/fulfillments-hooks.mdplugins/woocommerce/client/admin/docs/features/fulfillments-rest-api.md
📚 Learning: in the woocommerce fulfillments system, only the ups shipping provider is currently fully implemente...
Learnt from: tpaksu
PR: woocommerce/woocommerce#59172
File: plugins/woocommerce/src/Internal/Fulfillments/Providers/MPLShippingProvider.php:14-21
Timestamp: 2025-06-26T10:47:27.212Z
Learning: In the WooCommerce fulfillments system, only the UPS shipping provider is currently fully implemented. All other shipping provider classes in plugins/woocommerce/src/Internal/Fulfillments/Providers/ are placeholders for future implementations, so empty shipping country arrays and stub methods in these classes are intentional and should not be flagged as issues.
Applied to files:
plugins/woocommerce/changelog/60152-add-fulfillments-documentationplugins/woocommerce/client/admin/docs/features/fulfillments-hooks.mdplugins/woocommerce/client/admin/docs/features/fulfillments-rest-api.md
🪛 LanguageTool
plugins/woocommerce/client/admin/docs/features/fulfillments-rest-api.md
[style] ~654-~654: ‘new records’ might be wordy. Consider a shorter alternative.
Context: ...ique identifier for the metadata (0 for new records) | | key | string | The metadata k...
(EN_WORDINESS_PREMIUM_NEW_RECORDS)
plugins/woocommerce/client/admin/docs/features/fulfillments-hooks.md
Outdated
Show resolved
Hide resolved
plugins/woocommerce/client/admin/docs/features/fulfillments-rest-api.md
Outdated
Show resolved
Hide resolved
plugins/woocommerce/client/admin/docs/features/fulfillments-rest-api.md
Outdated
Show resolved
Hide resolved
…oks.md Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (3)
plugins/woocommerce/client/admin/docs/features/fulfillments-hooks.md (3)
355-366: Fix unreachablethrowin example snippet
return $fulfillment;exits the callback, so the subsequentthrowwill never run.
Show the “early-return” and the “abort via exception” alternatives as two separate snippets to avoid copy-pasting bugs.function validate_fulfillment_data( $fulfillment ) { // … - return $fulfillment; - - // Or, prevent the update action if some checks of yours fail - throw new FulfillmentException( __( 'The fulfillment is missing the required item. Please add it to the fulfillment and try again.', 'woocommerce' ) ); + return $fulfillment; } + +// --- Alternative: abort creation ------------------------------------------- + +add_filter( 'woocommerce_fulfillment_before_create', 'abort_if_no_items' ); +function abort_if_no_items( $fulfillment ) { + if ( empty( $fulfillment->get_meta( '_items', true ) ) ) { + throw new FulfillmentException( + __( 'The fulfillment is missing the required item. Please add it and try again.', 'woocommerce' ) + ); + } + return $fulfillment; +}
625-633: Undeclared$category_idin auto-fulfill example
$category_idis undefined, so the snippet won’t work if readers paste it.
Either pass an explicit ID or fetch the term by slug.- $products = wc_get_products([ - 'category' => get_term($category_id, 'gift-cards')->slug - ]); + $gift_cards = get_term_by( 'slug', 'gift-cards', 'product_cat' ); + $products = wc_get_products( + array( + 'category' => $gift_cards ? $gift_cards->slug : '', + ) + );
443-445: Typo: back-tick used instead of apostrophe in “can’t”-throw new FulfillmentException( __( 'The fulfillment can`t be deleted because it is being processed by a 3rd party plugin.', 'woocommerce' ) ); +throw new FulfillmentException( __( 'The fulfillment can\'t be deleted because it is being processed by a 3rd party plugin.', 'woocommerce' ) );
📜 Review details
Configuration used: .coderabbit.yml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
plugins/woocommerce/client/admin/docs/features/fulfillments-hooks.md(1 hunks)
🧰 Additional context used
🧠 Learnings (4)
📓 Common learnings
Learnt from: jorgeatorres
PR: woocommerce/woocommerce#59675
File: .github/workflows/release-bump-as-requirement.yml:48-65
Timestamp: 2025-07-15T15:39:21.856Z
Learning: In WooCommerce core repository, changelog entries for all PRs live in `plugins/woocommerce/changelog/` directory and are processed during releases, not at the repository root level.
Learnt from: CR
PR: woocommerce/woocommerce#0
File: .cursor/rules/generate-pr-description.mdc:0-0
Timestamp: 2025-07-21T05:22:46.426Z
Learning: Provide clear, step-by-step instructions for how to test the changes in the PR description.
Learnt from: tpaksu
PR: woocommerce/woocommerce#59172
File: plugins/woocommerce/src/Internal/Fulfillments/Providers/MPLShippingProvider.php:14-21
Timestamp: 2025-06-26T10:47:27.212Z
Learning: In the WooCommerce fulfillments system, only the UPS shipping provider is currently fully implemented. All other shipping provider classes in plugins/woocommerce/src/Internal/Fulfillments/Providers/ are placeholders for future implementations, so empty shipping country arrays and stub methods in these classes are intentional and should not be flagged as issues.
📚 Learning: in the woocommerce fulfillments system, only the ups shipping provider is currently fully implemente...
Learnt from: tpaksu
PR: woocommerce/woocommerce#59172
File: plugins/woocommerce/src/Internal/Fulfillments/Providers/MPLShippingProvider.php:14-21
Timestamp: 2025-06-26T10:47:27.212Z
Learning: In the WooCommerce fulfillments system, only the UPS shipping provider is currently fully implemented. All other shipping provider classes in plugins/woocommerce/src/Internal/Fulfillments/Providers/ are placeholders for future implementations, so empty shipping country arrays and stub methods in these classes are intentional and should not be flagged as issues.
Applied to files:
plugins/woocommerce/client/admin/docs/features/fulfillments-hooks.md
📚 Learning: in woocommerce core repository, changelog entries for all prs live in `plugins/woocommerce/changelog...
Learnt from: jorgeatorres
PR: woocommerce/woocommerce#59675
File: .github/workflows/release-bump-as-requirement.yml:48-65
Timestamp: 2025-07-15T15:39:21.856Z
Learning: In WooCommerce core repository, changelog entries for all PRs live in `plugins/woocommerce/changelog/` directory and are processed during releases, not at the repository root level.
Applied to files:
plugins/woocommerce/client/admin/docs/features/fulfillments-hooks.md
📚 Learning: in plugins/woocommerce/src/internal/admin/settings/payments.php, the process_payment_provider_states...
Learnt from: vladolaru
PR: woocommerce/woocommerce#58784
File: plugins/woocommerce/src/Internal/Admin/Settings/Payments.php:431-439
Timestamp: 2025-06-17T14:19:30.933Z
Learning: In plugins/woocommerce/src/Internal/Admin/Settings/Payments.php, the process_payment_provider_states() method intentionally filters out payment providers that don't have a _suggestion_id. This is by design to only track state changes for gateways from partner extensions, not core WooCommerce gateways or other installed gateways.
Applied to files:
plugins/woocommerce/client/admin/docs/features/fulfillments-hooks.md
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (9)
- GitHub Check: Core e2e tests 6/6 - @woocommerce/plugin-woocommerce [e2e]
- GitHub Check: Core e2e tests 3/6 - @woocommerce/plugin-woocommerce [e2e]
- GitHub Check: Metrics - @woocommerce/plugin-woocommerce [performance]
- GitHub Check: Core e2e tests 1/6 - @woocommerce/plugin-woocommerce [e2e]
- GitHub Check: Core e2e tests 5/6 - @woocommerce/plugin-woocommerce [e2e]
- GitHub Check: Core e2e tests 2/6 - @woocommerce/plugin-woocommerce [e2e]
- GitHub Check: Core e2e tests 4/6 - @woocommerce/plugin-woocommerce [e2e]
- GitHub Check: Validate markdown
- GitHub Check: build
🔇 Additional comments (1)
plugins/woocommerce/client/admin/docs/features/fulfillments-hooks.md (1)
483-486: Verify image path
assumes animages/folder adjacent to this markdown file, but no image is included in this PR. Broken images render as alt text only.Confirm the asset is committed at
plugins/woocommerce/client/admin/docs/features/images/fulfillment-status-text.png
or adjust the path accordingly.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
plugins/woocommerce/client/admin/docs/features/fulfillments-rest-api.md (2)
652-657:valuecolumn type should allow non-string dataExamples above store arrays and objects, yet the table constrains
valuetostring.-| `value` | string | The metadata value +| `value` | mixed | The metadata value (string, number, array, or object)
654-654: Minor wording – “new records” → “new entries”-| `id` | integer | Unique identifier for the metadata (0 for new records) +| `id` | integer | Unique identifier for the metadata (0 for new entries)
📜 Review details
Configuration used: .coderabbit.yml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
plugins/woocommerce/client/admin/docs/features/fulfillments-rest-api.md(1 hunks)
🧰 Additional context used
🧠 Learnings (12)
📓 Common learnings
Learnt from: jorgeatorres
PR: woocommerce/woocommerce#59675
File: .github/workflows/release-bump-as-requirement.yml:48-65
Timestamp: 2025-07-15T15:39:21.856Z
Learning: In WooCommerce core repository, changelog entries for all PRs live in `plugins/woocommerce/changelog/` directory and are processed during releases, not at the repository root level.
Learnt from: CR
PR: woocommerce/woocommerce#0
File: .cursor/rules/generate-pr-description.mdc:0-0
Timestamp: 2025-07-21T05:22:46.426Z
Learning: Provide clear, step-by-step instructions for how to test the changes in the PR description.
Learnt from: tpaksu
PR: woocommerce/woocommerce#59172
File: plugins/woocommerce/src/Internal/Fulfillments/Providers/MPLShippingProvider.php:14-21
Timestamp: 2025-06-26T10:47:27.212Z
Learning: In the WooCommerce fulfillments system, only the UPS shipping provider is currently fully implemented. All other shipping provider classes in plugins/woocommerce/src/Internal/Fulfillments/Providers/ are placeholders for future implementations, so empty shipping country arrays and stub methods in these classes are intentional and should not be flagged as issues.
📚 Learning: in the woocommerce fulfillments system, only the ups shipping provider is currently fully implemente...
Learnt from: tpaksu
PR: woocommerce/woocommerce#59172
File: plugins/woocommerce/src/Internal/Fulfillments/Providers/MPLShippingProvider.php:14-21
Timestamp: 2025-06-26T10:47:27.212Z
Learning: In the WooCommerce fulfillments system, only the UPS shipping provider is currently fully implemented. All other shipping provider classes in plugins/woocommerce/src/Internal/Fulfillments/Providers/ are placeholders for future implementations, so empty shipping country arrays and stub methods in these classes are intentional and should not be flagged as issues.
Applied to files:
plugins/woocommerce/client/admin/docs/features/fulfillments-rest-api.md
📚 Learning: in woocommerce core repository, changelog entries for all prs live in `plugins/woocommerce/changelog...
Learnt from: jorgeatorres
PR: woocommerce/woocommerce#59675
File: .github/workflows/release-bump-as-requirement.yml:48-65
Timestamp: 2025-07-15T15:39:21.856Z
Learning: In WooCommerce core repository, changelog entries for all PRs live in `plugins/woocommerce/changelog/` directory and are processed during releases, not at the repository root level.
Applied to files:
plugins/woocommerce/client/admin/docs/features/fulfillments-rest-api.md
📚 Learning: in plugins/woocommerce/src/internal/admin/settings/payments.php, the process_payment_provider_states...
Learnt from: vladolaru
PR: woocommerce/woocommerce#58784
File: plugins/woocommerce/src/Internal/Admin/Settings/Payments.php:431-439
Timestamp: 2025-06-17T14:19:30.933Z
Learning: In plugins/woocommerce/src/Internal/Admin/Settings/Payments.php, the process_payment_provider_states() method intentionally filters out payment providers that don't have a _suggestion_id. This is by design to only track state changes for gateways from partner extensions, not core WooCommerce gateways or other installed gateways.
Applied to files:
plugins/woocommerce/client/admin/docs/features/fulfillments-rest-api.md
📚 Learning: in woocommerce blocks, when porting existing code patterns that have known issues (like parseint tru...
Learnt from: samueljseay
PR: woocommerce/woocommerce#58716
File: plugins/woocommerce/client/blocks/assets/js/blocks/mini-cart/iapi-frontend.ts:83-101
Timestamp: 2025-06-17T07:07:53.443Z
Learning: In WooCommerce blocks, when porting existing code patterns that have known issues (like parseInt truncating decimal money values), maintain consistency with existing implementation rather than making isolated fixes. The preference is for systematic refactoring approaches (like broader Dinero adoption) over piecemeal changes.
Applied to files:
plugins/woocommerce/client/admin/docs/features/fulfillments-rest-api.md
📚 Learning: in woocommerce email editor store initialization (packages/js/email-editor/src/store/initial-state.t...
Learnt from: triple0t
PR: woocommerce/woocommerce#59186
File: packages/js/email-editor/src/store/initial-state.ts:9-10
Timestamp: 2025-06-26T12:13:32.062Z
Learning: In WooCommerce email editor store initialization (packages/js/email-editor/src/store/initial-state.ts), the current_post_id and current_post_type from window.WooCommerceEmailEditor are required parameters that should cause explicit errors if missing, rather than using fallback values or optional chaining. The design preference is to fail fast when critical initialization data is unavailable.
Applied to files:
plugins/woocommerce/client/admin/docs/features/fulfillments-rest-api.md
📚 Learning: in plugins/woocommerce/client/blocks/assets/js/blocks/checkout/inner-blocks/checkout-shipping-addres...
Learnt from: ralucaStan
PR: woocommerce/woocommerce#58782
File: plugins/woocommerce/client/blocks/assets/js/blocks/checkout/inner-blocks/checkout-shipping-address-block/customer-address.tsx:76-90
Timestamp: 2025-06-13T13:37:35.793Z
Learning: In plugins/woocommerce/client/blocks/assets/js/blocks/checkout/inner-blocks/checkout-shipping-address-block/customer-address.tsx, the `shouldAnimate` flag is expected to be `false` only on initial render and may remain `true` after the first edit; it does not need to be reset.
Applied to files:
plugins/woocommerce/client/admin/docs/features/fulfillments-rest-api.md
📚 Learning: in woocommerce projects, formatting suggestions should respect the project's prettier configuration ...
Learnt from: lysyjan
PR: woocommerce/woocommerce#59632
File: packages/js/email-editor/src/layouts/flex-email.tsx:116-122
Timestamp: 2025-07-14T10:41:46.200Z
Learning: In WooCommerce projects, formatting suggestions should respect the project's Prettier configuration and linting rules. Changes that would break the lint job should be avoided, even if they appear to improve readability.
Applied to files:
plugins/woocommerce/client/admin/docs/features/fulfillments-rest-api.md
📚 Learning: in plugins/woocommerce/client/admin/client/settings-payments/components/other-payment-gateways/other...
Learnt from: vladolaru
PR: woocommerce/woocommerce#58784
File: plugins/woocommerce/client/admin/client/settings-payments/components/other-payment-gateways/other-payment-gateways.tsx:43-50
Timestamp: 2025-06-18T07:56:06.961Z
Learning: In plugins/woocommerce/client/admin/client/settings-payments/components/other-payment-gateways/other-payment-gateways.tsx, the user vladolaru prefers to keep the current setUpPlugin function signature with optional positional context parameter rather than refactoring to an options object or making context required.
Applied to files:
plugins/woocommerce/client/admin/docs/features/fulfillments-rest-api.md
📚 Learning: in woocommerce codebase, when table names are hardcoded (like `$wpdb->prefix . 'wc_order_coupon_look...
Learnt from: NeosinneR
PR: woocommerce/woocommerce#60129
File: plugins/woocommerce/includes/wc-coupon-functions.php:145-154
Timestamp: 2025-07-31T11:18:02.478Z
Learning: In WooCommerce codebase, when table names are hardcoded (like `$wpdb->prefix . 'wc_order_coupon_lookup'`), the preference is to maintain consistency with existing patterns throughout the codebase rather than making isolated security improvements when the risk is minimal (since $wpdb->prefix is controlled by WordPress and table names are hardcoded constants).
Applied to files:
plugins/woocommerce/client/admin/docs/features/fulfillments-rest-api.md
📚 Learning: in woocommerce payments onboarding components (like plugins/woocommerce/client/admin/client/settings...
Learnt from: vladolaru
PR: woocommerce/woocommerce#59160
File: plugins/woocommerce/client/admin/client/settings-payments/onboarding/providers/woopayments/steps/payment-methods-selection/index.tsx:0-0
Timestamp: 2025-06-26T14:56:54.917Z
Learning: In WooCommerce payments onboarding components (like plugins/woocommerce/client/admin/client/settings-payments/onboarding/providers/woopayments/steps/payment-methods-selection/index.tsx), when updating local React state based on API calls, the local state should only be updated after the API call succeeds to prevent inconsistent state if the save operation fails. The pattern is to move setPaymentMethodsState calls inside the .then() callback of the API promise.
Applied to files:
plugins/woocommerce/client/admin/docs/features/fulfillments-rest-api.md
📚 Learning: in the woocommerce payments settings provider state tracking system (plugins/woocommerce/src/interna...
Learnt from: vladolaru
PR: woocommerce/woocommerce#58784
File: plugins/woocommerce/src/Internal/Admin/Settings/Payments.php:484-488
Timestamp: 2025-06-17T11:30:23.806Z
Learning: In the WooCommerce Payments settings provider state tracking system (plugins/woocommerce/src/Internal/Admin/Settings/Payments.php), when an extension is deactivated and its snapshot key disappears, only the 'extension_active' flag should be set to false while keeping other state flags like 'account_connected', 'needs_setup', 'test_mode', etc. unchanged. This is intentional behavior to preserve historical state information.
Applied to files:
plugins/woocommerce/client/admin/docs/features/fulfillments-rest-api.md
🪛 LanguageTool
plugins/woocommerce/client/admin/docs/features/fulfillments-rest-api.md
[style] ~654-~654: ‘new records’ might be wordy. Consider a shorter alternative.
Context: ...ique identifier for the metadata (0 for new records) | | key | string | The metadata k...
(EN_WORDINESS_PREMIUM_NEW_RECORDS)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (9)
- GitHub Check: Metrics - @woocommerce/plugin-woocommerce [performance]
- GitHub Check: Core e2e tests 5/6 - @woocommerce/plugin-woocommerce [e2e]
- GitHub Check: Core e2e tests 6/6 - @woocommerce/plugin-woocommerce [e2e]
- GitHub Check: Core e2e tests 4/6 - @woocommerce/plugin-woocommerce [e2e]
- GitHub Check: Core e2e tests 1/6 - @woocommerce/plugin-woocommerce [e2e]
- GitHub Check: Core e2e tests 2/6 - @woocommerce/plugin-woocommerce [e2e]
- GitHub Check: Core e2e tests 3/6 - @woocommerce/plugin-woocommerce [e2e]
- GitHub Check: Validate markdown
- GitHub Check: build
🔇 Additional comments (1)
plugins/woocommerce/client/admin/docs/features/fulfillments-rest-api.md (1)
41-80: Double-check whether the list endpoint really wraps the array in afulfillmentskeyCore WooCommerce collection endpoints (e.g. order notes, refunds) return a bare JSON array rather than an object wrapper. If the implementation follows the same pattern, the current example response is misleading.
Please confirm the actual runtime payload and update the docs (or the endpoint) accordingly.
plugins/woocommerce/client/admin/docs/features/fulfillments-rest-api.md
Outdated
Show resolved
Hide resolved
Test using WordPress PlaygroundThe changes in this pull request can be previewed and tested using a WordPress Playground instance. Test this pull request with WordPress Playground. Note that this URL is valid for 30 days from when this comment was last updated. You can update it by closing/reopening the PR or pushing a new commit. |
ismaeldcom
approved these changes
Aug 4, 2025
plugins/woocommerce/client/admin/docs/features/fulfillments-hooks.md
Outdated
Show resolved
Hide resolved
plugins/woocommerce/client/admin/docs/features/fulfillments-hooks.md
Outdated
Show resolved
Hide resolved
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (4)
plugins/woocommerce/client/admin/docs/features/fulfillments-hooks.md (4)
417-419: Grammar nit – “these information” → “this information”“Please add these information and try again” should read “this information”.
- throw new FulfillmentException( __( 'The fulfillment is missing the tracking number and shipping provider information. Please add these information and try again.', 'woocommerce' ) ); + throw new FulfillmentException( __( 'The fulfillment is missing the tracking number and shipping provider information. Please add this information and try again.', 'woocommerce' ) );
219-220: Use “metadata” (one word) consistentlyIn WooCommerce docs the term is normally “metadata”, not “meta data”.
-**Purpose:** Allows customization of fulfillment meta data display in emails. +**Purpose:** Allows customization of fulfillment metadata display in emails.
500-505: Prefer<strong>over<b>in translatable stringsWordPress coding standards recommend semantic tags. Replace
<b>with<strong>so screen readers interpret emphasis correctly.- return __( 'All items have been <b>Delivered</b>.', 'woocommerce' ); + return __( 'All items have been <strong>Delivered</strong>.', 'woocommerce' );
696-700: Usewp_json_encode()instead ofjson_encode()in examples
wp_json_encode()handles WP-specific encoding quirks (e.g., unescaped slashes & multibyte support). Using it in code samples reinforces best practices.- 'body' => json_encode( array( + 'body' => wp_json_encode( array(
📜 Review details
Configuration used: .coderabbit.yml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
plugins/woocommerce/client/admin/docs/features/fulfillments-hooks.md(1 hunks)plugins/woocommerce/client/admin/docs/features/fulfillments-rest-api.md(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- plugins/woocommerce/client/admin/docs/features/fulfillments-rest-api.md
🧰 Additional context used
🧠 Learnings (6)
📓 Common learnings
Learnt from: jorgeatorres
PR: woocommerce/woocommerce#59675
File: .github/workflows/release-bump-as-requirement.yml:48-65
Timestamp: 2025-07-15T15:39:21.856Z
Learning: In WooCommerce core repository, changelog entries for all PRs live in `plugins/woocommerce/changelog/` directory and are processed during releases, not at the repository root level.
Learnt from: CR
PR: woocommerce/woocommerce#0
File: .cursor/rules/generate-pr-description.mdc:0-0
Timestamp: 2025-07-21T05:22:46.426Z
Learning: Provide clear, step-by-step instructions for how to test the changes in the PR description.
Learnt from: tpaksu
PR: woocommerce/woocommerce#59172
File: plugins/woocommerce/src/Internal/Fulfillments/Providers/MPLShippingProvider.php:14-21
Timestamp: 2025-06-26T10:47:27.212Z
Learning: In the WooCommerce fulfillments system, only the UPS shipping provider is currently fully implemented. All other shipping provider classes in plugins/woocommerce/src/Internal/Fulfillments/Providers/ are placeholders for future implementations, so empty shipping country arrays and stub methods in these classes are intentional and should not be flagged as issues.
📚 Learning: in the woocommerce fulfillments system, only the ups shipping provider is currently fully implemente...
Learnt from: tpaksu
PR: woocommerce/woocommerce#59172
File: plugins/woocommerce/src/Internal/Fulfillments/Providers/MPLShippingProvider.php:14-21
Timestamp: 2025-06-26T10:47:27.212Z
Learning: In the WooCommerce fulfillments system, only the UPS shipping provider is currently fully implemented. All other shipping provider classes in plugins/woocommerce/src/Internal/Fulfillments/Providers/ are placeholders for future implementations, so empty shipping country arrays and stub methods in these classes are intentional and should not be flagged as issues.
Applied to files:
plugins/woocommerce/client/admin/docs/features/fulfillments-hooks.md
📚 Learning: in woocommerce core repository, changelog entries for all prs live in `plugins/woocommerce/changelog...
Learnt from: jorgeatorres
PR: woocommerce/woocommerce#59675
File: .github/workflows/release-bump-as-requirement.yml:48-65
Timestamp: 2025-07-15T15:39:21.856Z
Learning: In WooCommerce core repository, changelog entries for all PRs live in `plugins/woocommerce/changelog/` directory and are processed during releases, not at the repository root level.
Applied to files:
plugins/woocommerce/client/admin/docs/features/fulfillments-hooks.md
📚 Learning: in plugins/woocommerce/src/internal/admin/settings/payments.php, the process_payment_provider_states...
Learnt from: vladolaru
PR: woocommerce/woocommerce#58784
File: plugins/woocommerce/src/Internal/Admin/Settings/Payments.php:431-439
Timestamp: 2025-06-17T14:19:30.933Z
Learning: In plugins/woocommerce/src/Internal/Admin/Settings/Payments.php, the process_payment_provider_states() method intentionally filters out payment providers that don't have a _suggestion_id. This is by design to only track state changes for gateways from partner extensions, not core WooCommerce gateways or other installed gateways.
Applied to files:
plugins/woocommerce/client/admin/docs/features/fulfillments-hooks.md
📚 Learning: in woocommerce blocks, when porting existing code patterns that have known issues (like parseint tru...
Learnt from: samueljseay
PR: woocommerce/woocommerce#58716
File: plugins/woocommerce/client/blocks/assets/js/blocks/mini-cart/iapi-frontend.ts:83-101
Timestamp: 2025-06-17T07:07:53.443Z
Learning: In WooCommerce blocks, when porting existing code patterns that have known issues (like parseInt truncating decimal money values), maintain consistency with existing implementation rather than making isolated fixes. The preference is for systematic refactoring approaches (like broader Dinero adoption) over piecemeal changes.
Applied to files:
plugins/woocommerce/client/admin/docs/features/fulfillments-hooks.md
📚 Learning: in woocommerce codebase, prefer using `wc_string_to_bool()` over `filter_var($value, filter_validate...
Learnt from: vladolaru
PR: woocommerce/woocommerce#58784
File: plugins/woocommerce/src/Internal/Admin/Settings/PaymentsProviders/Paytrail.php:29-35
Timestamp: 2025-06-18T09:58:10.616Z
Learning: In WooCommerce codebase, prefer using `wc_string_to_bool()` over `filter_var($value, FILTER_VALIDATE_BOOLEAN)` when converting option values (especially 'yes'/'no' style flags) to boolean. The WooCommerce helper function is more idiomatic and handles the conversion consistently with core WooCommerce patterns.
Applied to files:
plugins/woocommerce/client/admin/docs/features/fulfillments-hooks.md
🔇 Additional comments (1)
plugins/woocommerce/client/admin/docs/features/fulfillments-hooks.md (1)
485-486: Verify the image path existsThe documentation references
images/fulfillment-status-text.png. Ensure this asset was added in the same PR; otherwise the rendered docs will show a broken image.
plugins/woocommerce/client/admin/docs/features/fulfillments-hooks.md
Outdated
Show resolved
Hide resolved
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
plugins/woocommerce/client/admin/docs/features/fulfillments-hooks.md (2)
389-393: Use a single helper name for consistencyThe examples alternate between
custom_error_logger()(Line 391) andcustom_error_log()(Line 448). Pick one function name to avoid copy-paste bugs and cognitive friction.- $logged = custom_error_logger( 'Updating fulfillment: ' . $fulfillment->get_id() ); + $logged = custom_error_log( 'Updating fulfillment: ' . $fulfillment->get_id() ); … - $logged = custom_error_log( 'Deleting fulfillment: ' . $fulfillment->get_id() ); + $logged = custom_error_log( 'Deleting fulfillment: ' . $fulfillment->get_id() );Also applies to: 448-451
403-403: Grammar – replace “cancel the fulfilling”“Cancel the fulfilling” is awkward; “cancel the fulfillment” is clearer. Also remove the stray space before the comma.
-Allows modification of fulfillment data before it's marked as fulfilled. If you want to cancel the fulfilling, you can throw a `FulfillmentException` exception, which will cancel the process , and show the error message on the user’s form. +Allows modification of fulfillment data before it's marked as fulfilled. If you need to cancel the fulfillment, throw a `FulfillmentException`; this stops the process and shows the error message on the user’s form.
📜 Review details
Configuration used: .coderabbit.yml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
plugins/woocommerce/client/admin/docs/features/fulfillments-hooks.md(1 hunks)
🧰 Additional context used
🧠 Learnings (9)
📓 Common learnings
Learnt from: jorgeatorres
PR: woocommerce/woocommerce#59675
File: .github/workflows/release-bump-as-requirement.yml:48-65
Timestamp: 2025-07-15T15:39:21.856Z
Learning: In WooCommerce core repository, changelog entries for all PRs live in `plugins/woocommerce/changelog/` directory and are processed during releases, not at the repository root level.
Learnt from: CR
PR: woocommerce/woocommerce#0
File: .cursor/rules/generate-pr-description.mdc:0-0
Timestamp: 2025-07-21T05:22:46.426Z
Learning: Provide clear, step-by-step instructions for how to test the changes in the PR description.
Learnt from: tpaksu
PR: woocommerce/woocommerce#59172
File: plugins/woocommerce/src/Internal/Fulfillments/Providers/MPLShippingProvider.php:14-21
Timestamp: 2025-06-26T10:47:27.212Z
Learning: In the WooCommerce fulfillments system, only the UPS shipping provider is currently fully implemented. All other shipping provider classes in plugins/woocommerce/src/Internal/Fulfillments/Providers/ are placeholders for future implementations, so empty shipping country arrays and stub methods in these classes are intentional and should not be flagged as issues.
📚 Learning: in the woocommerce fulfillments system, only the ups shipping provider is currently fully implemente...
Learnt from: tpaksu
PR: woocommerce/woocommerce#59172
File: plugins/woocommerce/src/Internal/Fulfillments/Providers/MPLShippingProvider.php:14-21
Timestamp: 2025-06-26T10:47:27.212Z
Learning: In the WooCommerce fulfillments system, only the UPS shipping provider is currently fully implemented. All other shipping provider classes in plugins/woocommerce/src/Internal/Fulfillments/Providers/ are placeholders for future implementations, so empty shipping country arrays and stub methods in these classes are intentional and should not be flagged as issues.
Applied to files:
plugins/woocommerce/client/admin/docs/features/fulfillments-hooks.md
📚 Learning: in woocommerce core repository, changelog entries for all prs live in `plugins/woocommerce/changelog...
Learnt from: jorgeatorres
PR: woocommerce/woocommerce#59675
File: .github/workflows/release-bump-as-requirement.yml:48-65
Timestamp: 2025-07-15T15:39:21.856Z
Learning: In WooCommerce core repository, changelog entries for all PRs live in `plugins/woocommerce/changelog/` directory and are processed during releases, not at the repository root level.
Applied to files:
plugins/woocommerce/client/admin/docs/features/fulfillments-hooks.md
📚 Learning: in plugins/woocommerce/src/internal/admin/settings/payments.php, the process_payment_provider_states...
Learnt from: vladolaru
PR: woocommerce/woocommerce#58784
File: plugins/woocommerce/src/Internal/Admin/Settings/Payments.php:431-439
Timestamp: 2025-06-17T14:19:30.933Z
Learning: In plugins/woocommerce/src/Internal/Admin/Settings/Payments.php, the process_payment_provider_states() method intentionally filters out payment providers that don't have a _suggestion_id. This is by design to only track state changes for gateways from partner extensions, not core WooCommerce gateways or other installed gateways.
Applied to files:
plugins/woocommerce/client/admin/docs/features/fulfillments-hooks.md
📚 Learning: in woocommerce blocks, when porting existing code patterns that have known issues (like parseint tru...
Learnt from: samueljseay
PR: woocommerce/woocommerce#58716
File: plugins/woocommerce/client/blocks/assets/js/blocks/mini-cart/iapi-frontend.ts:83-101
Timestamp: 2025-06-17T07:07:53.443Z
Learning: In WooCommerce blocks, when porting existing code patterns that have known issues (like parseInt truncating decimal money values), maintain consistency with existing implementation rather than making isolated fixes. The preference is for systematic refactoring approaches (like broader Dinero adoption) over piecemeal changes.
Applied to files:
plugins/woocommerce/client/admin/docs/features/fulfillments-hooks.md
📚 Learning: in woocommerce codebase, prefer using `wc_string_to_bool()` over `filter_var($value, filter_validate...
Learnt from: vladolaru
PR: woocommerce/woocommerce#58784
File: plugins/woocommerce/src/Internal/Admin/Settings/PaymentsProviders/Paytrail.php:29-35
Timestamp: 2025-06-18T09:58:10.616Z
Learning: In WooCommerce codebase, prefer using `wc_string_to_bool()` over `filter_var($value, FILTER_VALIDATE_BOOLEAN)` when converting option values (especially 'yes'/'no' style flags) to boolean. The WooCommerce helper function is more idiomatic and handles the conversion consistently with core WooCommerce patterns.
Applied to files:
plugins/woocommerce/client/admin/docs/features/fulfillments-hooks.md
📚 Learning: in the woocommerce woopayments rest controller, it's acceptable to let apiexception bubble up from o...
Learnt from: vladolaru
PR: woocommerce/woocommerce#58784
File: plugins/woocommerce/src/Internal/Admin/Settings/PaymentsProviders/WooPayments/WooPaymentsRestController.php:619-625
Timestamp: 2025-06-17T10:33:54.736Z
Learning: In the WooCommerce WooPayments REST controller, it's acceptable to let ApiException bubble up from onboarding-related method calls like get_onboarding_step_status() and mark_onboarding_step_completed() rather than wrapping them in local try/catch blocks.
Applied to files:
plugins/woocommerce/client/admin/docs/features/fulfillments-hooks.md
📚 Learning: woocommerce legacy javascript files in plugins/woocommerce/client/legacy/js/ must use older javascri...
Learnt from: opr
PR: woocommerce/woocommerce#0
File: :0-0
Timestamp: 2025-06-20T17:38:16.565Z
Learning: WooCommerce legacy JavaScript files in plugins/woocommerce/client/legacy/js/ must use older JavaScript syntax and cannot use modern features like optional chaining (?.) due to browser compatibility requirements. Explicit null checking with && operators should be used instead.
Applied to files:
plugins/woocommerce/client/admin/docs/features/fulfillments-hooks.md
📚 Learning: in woocommerce payments onboarding components (like plugins/woocommerce/client/admin/client/settings...
Learnt from: vladolaru
PR: woocommerce/woocommerce#59160
File: plugins/woocommerce/client/admin/client/settings-payments/onboarding/providers/woopayments/steps/payment-methods-selection/index.tsx:0-0
Timestamp: 2025-06-26T14:56:54.917Z
Learning: In WooCommerce payments onboarding components (like plugins/woocommerce/client/admin/client/settings-payments/onboarding/providers/woopayments/steps/payment-methods-selection/index.tsx), when updating local React state based on API calls, the local state should only be updated after the API call succeeds to prevent inconsistent state if the save operation fails. The pattern is to move setPaymentMethodsState calls inside the .then() callback of the API promise.
Applied to files:
plugins/woocommerce/client/admin/docs/features/fulfillments-hooks.md
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (9)
- GitHub Check: Metrics - @woocommerce/plugin-woocommerce [performance]
- GitHub Check: Core e2e tests 6/6 - @woocommerce/plugin-woocommerce [e2e]
- GitHub Check: Core e2e tests 5/6 - @woocommerce/plugin-woocommerce [e2e]
- GitHub Check: Core e2e tests 4/6 - @woocommerce/plugin-woocommerce [e2e]
- GitHub Check: Core e2e tests 3/6 - @woocommerce/plugin-woocommerce [e2e]
- GitHub Check: Core e2e tests 1/6 - @woocommerce/plugin-woocommerce [e2e]
- GitHub Check: Core e2e tests 2/6 - @woocommerce/plugin-woocommerce [e2e]
- GitHub Check: Validate markdown
- GitHub Check: build
plugins/woocommerce/client/admin/docs/features/fulfillments-hooks.md
Outdated
Show resolved
Hide resolved
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Submission Review Guidelines:
Changes proposed in this Pull Request:
This PR adds the REST API endpoints and hooks introduced in the Order fulfillment entity project to the repository documentation.
Closes #60153 WOOPLUG-5240
How to test the changes in this Pull Request:
Using the WooCommerce Testing Instructions Guide, include your detailed testing instructions:
Open each of the new markdown files on this PR using the three dots menu on the right of each file's title, and see if it renders correctly.
Changelog entry
Changelog Entry Details
Significance
Type
Message
Changelog Entry Comment
Comment
Add public documentation of order fulfillment entity REST API and hooks.