VibeFox Correos CityPaq for WooCommerce — Help

Requirements

WordPress: 5.8 or later.

WooCommerce: 7.0 or later, installed and active. The plugin refuses to activate without it.

PHP: 8.0 or later.

Correos API credentials (for the live locker list only): the Correos CityPaq list reads the active lockers from the Correos "terminals" API. On the Correos developer portal, open the "terminals" API and use Request access for your application. Correos approves requests from its business customers and sends a client ID and a client secret. They are also shown under My applications on the portal. If customers enter the locker themselves or choose from your own list, you do not need API credentials.

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

1. In WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the vfd_correos_citypaq folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Shipping > VibeFox Correos CityPaq, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

5. Fill in the price table and choose how the customer selects the locker (see Configuration).

6. Add VibeFox Correos CityPaq to your shipping zone for Spain in WooCommerce > Settings > Shipping > Shipping zones, or turn on Ignore shipping zones.

Configuration

All settings are on one page: WooCommerce > Settings > Shipping > VibeFox Correos CityPaq. They apply to every shipping zone. When you add the method to a zone, the zone window has only one field:

Title (zone): the name of this option at checkout for this zone. Leave it empty to use the global Name.

Warnings above the settings tell you when the price table has no usable row, when the chosen locker selection cannot work (no lockers in your list, no API credentials) and what the last Correos API error was. Prices and amounts accept a decimal comma or a decimal point.

General

CityPaq lockers exist only in Spain, so the method is never offered for other countries.

Enable/Disable: turns the method on or off in all zones at once.

Name: the shipping method name shown to the customer at checkout. Default: Correos CityPaq.

Tax status: Taxable adds WooCommerce tax on top of the prices from the table, None does not.

Prices (the section title shows your store currency)

Price table: a row for Spain (ES) and/or a default row *. Each row has a base Price and optional prices for the parcel sizes XS (up to 1 kg), S (up to 2 kg), M (up to 3 kg), L (up to 5 kg) and XL (above 5 kg). A size price of 0 or empty uses the base price. Click + Add row to add a row and the cross to remove one. Enter your Correos contract prices in the store currency. Without a matching row the method is hidden. Invalid prices and duplicated rows are reported when you save.

Calculation type: how the parcel size is found.

Per order (size by the total cart weight): one price for the whole cart, chosen by the total weight. This is the default.

Per item (size by each item weight, multiplied by quantity): each product gets the price of its own size, multiplied by its quantity, and the prices are added up.

Product weights are converted to kg from your store weight unit (kg, g, lbs or oz).

Conditions

Min weight (kg): hide the method when the cart is lighter. 0 means no limit.

Max weight (kg): hide the method when the cart is heavier. Default: 30, because CityPaq accepts parcels up to 30 kg. 0 means no limit.

Minimum order amount: show the method only when the cart subtotal (after discounts, before tax) reaches this amount. Leave empty to always show it.

Excluded shipping classes: hide the method when the cart contains a product of one of these WooCommerce shipping classes, for example bulky items that do not fit a locker. The plugin does not check parcel dimensions.

Free shipping

Free shipping: turn on free CityPaq delivery from the amount below.

Free shipping from: the cart subtotal (after discounts, before tax) from which this method costs 0. Used only when Free shipping is on.

CityPaq locker selection

Locker selection: how the customer chooses the locker before placing the order. Default: the customer enters the locker.

Customer chooses from the Correos CityPaq list (Correos API, credentials below): the customer sees the active CityPaq lockers of the postal code of the shipping address and can search another 5-digit postal code. When a postal code has no locker, the lockers of the same area, then of the same province are listed, nearest postal codes first. Each locker shows its name, address, postal code, town and opening hours. If the list cannot be loaded or finds nothing, the customer enters the locker instead.

Customer enters the locker (code or address from the Correos finder): a required field for the locker code (for example S0000213D) or address, with a link to the official Correos CityPaq finder.

Customer chooses from my list of lockers (below): a required drop-down of the lockers from My lockers. Lockers near the customer's postal code are listed first.

Do not ask for a locker: no locker question at checkout.

If you choose the Correos list without API credentials, or your own list while My lockers is empty, customers are asked to enter the locker instead.

My lockers: used when Locker selection is set to your list. One locker per line: CODE | Name | Address | Postal code | City. The code and the name are required. Invalid and duplicated lines are reported when you save.

Correos CityPaq list (API) (used only with the Correos CityPaq list)

The section has a link to the "terminals" API page on the Correos developer portal. Only the list of lockers is read. Prices always come from the price table.

API client ID: the client_id of your application on the Correos developer portal.

API client secret: the client_secret of your application on the Correos developer portal.

When you change the credentials or the locker selection, the cached locker lists are cleared.

Availability without shipping zones

Ignore shipping zones: offer CityPaq for every Spanish address, even if no shipping zone contains this method. Off (recommended) means the method is offered where you added it to a shipping zone.

Advanced

Debug log: writes debug lines to WooCommerce > Status > Logs, source vfd-correos-citypaq. Correos API errors are always logged, even when this is off. Credentials and personal data are never logged.

Remove data on uninstall: when on, deleting the plugin removes its settings and zone methods. Deactivating the plugin never deletes anything. Lockers saved in orders are kept.

How it works at checkout

When the customer enters a delivery address in Spain, WooCommerce asks the plugin for a rate. The plugin checks the cart weight, the minimum order amount and the excluded shipping classes, finds the price row for Spain (or the * row) and the parcel size, and shows the price. If free shipping applies, the price is 0.

When the customer selects CityPaq, the locker field appears under the method. The order cannot be placed without a valid locker. This is checked on the server too, also for orders placed through the Cart and Checkout blocks. With the Correos list, a locker code is accepted only if Correos offered it to this customer, and its name and address are taken from Correos. The number of postal code searches per customer session is limited. When the limit is reached, the customer enters the locker instead.

A Correos list is cached for 12 hours per postal code. A failed request is cached for 10 minutes, so the checkout does not wait for Correos on every refresh. The API timeout is 12 seconds. The customer never sees the technical error, only a short message and the manual field.

The method works on the classic checkout and on the Cart and Checkout blocks. It is compatible with WooCommerce High-Performance Order Storage (HPOS).

The plugin does not get live rates from Correos, show a map, pre-register shipments, print labels, request pickups or track parcels. Create the shipment in your Correos account using the locker saved in the order.

Pickup points

The chosen locker is saved in the order. It is shown in the order admin under the shipping address, on the order received page, in My account > Orders and in all order e-mails (HTML and plain text) as CityPaq locker.

In the order admin you can change the locker in the Change CityPaq locker field: choose another locker from your list, or type a new code or address. With the Correos list, a typed locker code is looked up at Correos. Leave the field empty to keep the current locker. Each change adds an order note.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Shipping > VibeFox Correos CityPaq. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, Correos CityPaq is not shown to customers at checkout. Logged-in store managers still see it, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

Troubleshooting

Correos CityPaq does not appear at checkout: check that the license is active, Enable/Disable is on, the address is in Spain and the method is added to the matching shipping zone (or Ignore shipping zones is on). Check that the price table has a row for Spain or a * row, and that the cart is within the weight limits, Minimum order amount and Excluded shipping classes.

Customers must type the locker although the Correos list is selected: check that API client ID and API client secret are filled in and look at the warning above the settings. It shows the last Correos API error. HTTP 401/403 means Correos refused the credentials: check them and that your application has access to the "terminals" API. After an error, the next attempt is made after 10 minutes.

No lockers for a postal code: Correos found no active locker for that postal code, its area or its province. The customer can search another postal code or enter the locker found on the Correos CityPaq finder.

The drop-down of my lockers does not appear: My lockers is empty or its lines are invalid. Each line needs at least CODE | Name.

Where customers find the locker code: on the Correos CityPaq finder linked under the locker field.

Developer notes: the locker is stored in the order meta _vfd_cpq_locker (text shown everywhere) and _vfd_cpq_locker_id (locker code, when chosen from the Correos list or your list). The plugin uses the production Correos "terminals" API. No sandbox is documented for this API.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed, as are the cached Correos locker lists and the last API error. Settings and zone methods are removed only if Remove data on uninstall was on. Otherwise they stay for a later re-install. Lockers saved in orders are never deleted, and existing orders keep their shipping lines.

Correos and CityPaq are trademarks of their respective owners. This plugin is not affiliated with or endorsed by Correos.