=== CartBridge Checkout Links for WooCommerce ===
Contributors:      gik000, unmoscerinonelweb
Donate link:       https://unmoscerinonelweb.com
Tags:              woocommerce, facebook, instagram, cart, checkout, social shop
Requires at least: 6.0
Tested up to:      7.0
Requires PHP:      7.4
Stable tag:        1.0.1
License:           GPL-2.0-or-later
License URI:       https://www.gnu.org/licenses/gpl-2.0.html

Fills the WooCommerce cart automatically when customers arrive from a Meta (Facebook or Instagram) shop checkout URL.

== Description ==

Since mid-2025 Meta no longer supports native on-platform checkout for Facebook and Instagram shops. Merchants must instead configure a **Checkout URL** on their own website — Meta documents this approach in the [Commerce Platform Checkout URL setup guide](https://developers.facebook.com/docs/commerce-platform/setup-checkout-url). That URL should pre-fill the store cart and send customers straight to checkout.

**CartBridge Checkout Links for WooCommerce** handles this seamlessly. You configure your store URL as the checkout URL in Meta Commerce Manager and the plugin takes care of the rest: it reads the product list from the URL, fills the WooCommerce cart, and redirects the customer to the checkout page.

= How it works =

Meta appends a `products` query parameter to your checkout URL every time a customer taps "Buy" on your Facebook or Instagram shop listing:

`https://yourstore.com/checkout?products=wc_post_id_123:2,wc_post_id_456:1`

The plugin intercepts this request, adds the right products (and quantities) to the cart, and bounces the customer to `/checkout` in one smooth redirect.

= Supported product ID formats =

* `wc_post_id_123:2` — simple product with WooCommerce post ID 123, quantity 2
* `wc_post_id_123_variation_456:2` — variable product 123, variation 456, quantity 2
* `123:2` — plain WooCommerce post ID (fallback format)

= Optional parameters =

* `coupon=CODE` — applies a coupon code automatically
* `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term` — forwarded to the checkout URL for analytics
* `fbclid`, `cart_origin` — forwarded for Meta attribution

= Setup =

1. Install and activate the plugin.
2. Follow [Meta's official Checkout URL setup guide](https://developers.facebook.com/docs/commerce-platform/setup-checkout-url).
3. In **Meta Commerce Manager → Settings → Checkout**, choose *Checkout on another website*.
4. Set the Checkout URL to your store's checkout page, e.g. `https://yourstore.com/checkout`.
5. Meta will automatically append the `?products=…` parameter when a customer buys.

= Security =

* All query-string values are sanitised before use.
* Product IDs are validated against the WooCommerce catalogue; non-existent or non-purchasable products are silently skipped.
* Quantities are capped at 99 per item; item count is capped at 50 per request.
* The final redirect uses `wp_safe_redirect()`.

= Requirements =

* WordPress 6.0 or later
* WooCommerce 7.0 or later
* PHP 7.4 or later

== Installation ==

1. Upload the `cartbridge-checkout-for-woocommerce` folder to `/wp-content/plugins/`.
2. Activate the plugin through the **Plugins** screen in WordPress.
3. Configure your Checkout URL in Meta Commerce Manager (see the Description tab).

No other configuration is needed.

== Frequently Asked Questions ==

= Does this work with variable products? =

Yes. Meta passes variation IDs in the format `wc_post_id_123_variation_456:qty`. The plugin maps those to the correct WooCommerce variation automatically.

= What happens if a product is out of stock? =

Out-of-stock and non-purchasable products are silently skipped. If *no* valid product can be added to the cart, the redirect is suppressed and the customer stays on the landing page.

= Can I use any page as the checkout URL? =

Yes. The plugin listens on *every* front-end request and activates only when the `products` parameter is present, so you can point Meta to any page of your site.

= Does the plugin conflict with page caching? =

URLs containing the `products` parameter should be excluded from your caching layer. Most caching plugins (LiteSpeed Cache, W3 Total Cache, WP Rocket, etc.) allow you to add query-string exclusion rules for this parameter.

= Is the plugin GDPR-compliant? =

The plugin does not collect, store, or transmit any personal data. It only reads URL parameters provided by Meta and uses them to populate a server-side WooCommerce cart session.

== Screenshots ==

1. Meta Commerce Manager — Checkout URL setting.
2. WooCommerce checkout page after the cart has been pre-filled via the Meta link.

== Changelog ==

= 1.0.1 =
* Renamed plugin to CartBridge Checkout Links for WooCommerce for WordPress.org directory compliance.
* Replaced generic wc prefix with cartbridge prefix throughout the codebase.
* Removed redundant load_plugin_textdomain() call.
* Added plugin directory banners and icons.
* Added link to Meta's official Checkout URL documentation in the plugin description.
* Added complete translations for 14 languages.

= 1.0.0 =
* Initial release.

== Upgrade Notice ==

= 1.0.1 =
Renamed for WordPress.org compliance. No configuration changes required.

= 1.0.0 =
Initial release. No upgrade steps required.
