WooCommerce Georgian Post International Shipping Method

Documentation for the Plug and Pay WooCommerce Georgian Post International Shipping Method plugin. This plugin is focused on Georgian Post international shipping workflows, including box packing, customs declaration items, parcel registration, labels, and tracking.

• PHP: 7.4, 8.1, 8.2, or 8.3
• ionCube Loader: Required. For version requirements and installation details, see IonCube Loader.
• WooCommerce: 3.6 or higher

• Currency: The plugin fetches rates from Georgian Post in GEL (Georgian Lari). It includes a currency converter (NBG or BOG) to automatically convert these rates into your store's base currency if you are not using GEL.
• Weights & Dimensions: All products must have weight and dimensions (length, width, height) defined to calculate box packing.
• Package Boxes: At least one package box must be defined in settings for the shipping calculator to work.
• Product Settings: Each product must have a Declaration Item assigned in the product shipping settings for customs purposes.

Go to WooCommerce > Settings > Shipping > Georgian Post to configure the global API settings:

1. API username: Provided by Georgian Post.
2. API password: Your Georgian Post API password.
3. Currency converter: Choose between National Bank of Georgia, Bank of Georgia, or Disabled. Georgian Post returns shipping rates in GEL. If your store uses a different currency, this setting will automatically convert those GEL rates into your store's currency.
4. Debug Log: Enable this to log API events for troubleshooting.

Since this is an international shipping method, it requires pre-defined package boxes to calculate rates accurately.

1. Go to WooCommerce > Settings > Shipping > Package boxes.
2. Add your available shipping boxes with the following details:
   • Ref. name: A descriptive name for the box.
   • Outer Dimensions: Width, Length, and Height (cm).
   • Inner Dimensions: Width, Length, and Height (cm).
   • Empty weight: The weight of the box itself (kg).
   • Max weight: The maximum weight the box can carry (kg).

For international shipping, customs declarations are mandatory.

1. Edit a product (or variation).
2. Go to the Shipping tab.
3. Select the appropriate Declaration item from the dropdown. These items are fetched directly from the Georgian Post API.
4. Ensure Weight and Dimensions are correctly set.

After configuring the global settings and package boxes, add the Georgian Post method to your desired shipping zones under WooCommerce > Settings > Shipping > Shipping zones.

The International plugin and Georgian Post Courier can be active together. No compatibility setting is required, but each shipping destination must be assigned to only one of the two methods through WooCommerce shipping zones.

“Standalone” means that only one of the two Georgian Post plugins is active and API-key activated. It does not remove WooCommerce's shipping-zone requirement.

• International only: Add Georgian Post to every zone where it should provide rates. This can include a Georgia zone if you intend to use the International service domestically.
• Courier only: Add Georgian Post Courier to a Georgia-only zone. Courier cannot provide international rates and requires the store currency to be GEL.

If an activated plugin is not added to the shipping zone that matches the customer's destination, WooCommerce will not show its rate. The plugin may still change the checkout city field, but that alone does not make the shipping method available.

Configure the zones under WooCommerce > Settings > Shipping > Shipping zones as follows:

Do not add both Georgian Post methods to the same zone. The Courier and International APIs provide separate city lists, and their city IDs are provider-specific. Even when two cities have the same name, their IDs must not be assumed to match. If both methods are available for the same destination, checkout can collect an ID for one provider and later submit it to the other provider.

With the recommended setup:

• Georgia (GE) uses the Courier city search and Courier rates.
• All other configured countries use the International city list and International rates.
• Billing and shipping countries are handled independently. For example, a Georgian billing address and an international shipping address use the appropriate city source for each field.
• Changing a country clears the previous provider's city ID. The customer must select a city valid for the newly selected country.

Courier requires the store currency to be GEL. For a non-GEL store, do not enable Courier in a shipping zone; use the International plugin for the required destinations instead.

If either plugin or its API-key activation is disabled, the remaining plugin returns to its standalone checkout behavior.

The plugin uses a box-packing algorithm to determine which of your defined package boxes can fit the items in the cart. It then fetches real-time rates from the Georgian Post API based on the destination country, city, and packed box dimensions/weight.

To ensure accurate shipping rates, the plugin dynamically fetches the official list of destination cities from the Georgian Post API based on the selected country during checkout. This ensures that customers select valid delivery locations and that the API returns correct pricing.

Store administrators can manually register shipments directly from the WooCommerce order details page. Once a shipping item is associated with the Georgian Post method, a Register button appears in the shipping items section of the order edit page.

After successful registration, a Print Label button becomes available to generate the shipping labels required for international post.

Customers can view the real-time status of their shipment directly on the "View Order" page. The plugin fetches the latest routing information and status updates from Georgian Post.

When configuring or troubleshooting rates, enable WooCommerce shipping debug mode so cached rates do not hide settings changes:

1. Go to WooCommerce > Settings > Shipping > Shipping options.
2. Enable Debug mode.
3. Save the changes.

Disable WooCommerce shipping debug mode again after testing because it can affect checkout performance.

Enable Debug Log in the Georgian Post global or shipping-zone instance settings, then review entries under WooCommerce > Status > Logs using the gpost_shipping_method source.

The WooCommerce method ID is gpost_shipping_method.

Use the standard woocommerce_package_rates filter to change, remove, or rename Georgian Post rates. See General Shipping Hooks for examples based on cart total, destination city, or products.