=== JagoOngkir ===
Contributors: tatakode
Tags: woocommerce, shipping, indonesia, ongkir
Requires at least: 6.3
Tested up to: 7.1
Requires PHP: 7.4
Requires Plugins: woocommerce
Stable tag: 1.0.0
License: GPL-2.0-or-later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Indonesian shipping rates for classic WooCommerce Cart and Checkout using api.co.id, RajaOngkir / Komerce, or Biteship.

== Description ==

JagoOngkir displays courier services and shipping rates for Indonesian destinations on WooCommerce Cart and Checkout pages. Rates come from your selected API provider and depend on the shipping origin, destination, and package details required by that provider.

= Choose your shipping API provider =

The plugin supports [api.co.id](https://api.co.id/), [RajaOngkir / Komerce](https://rajaongkir.com/), and [Biteship](https://biteship.com/). Create an account with your preferred provider, obtain an API key, and connect it in the plugin settings. Only one provider needs to be active to calculate storefront rates.

Each provider keeps its own API connection, origin, request limits, usage counters, and account-specific cache. You can switch the active provider without deleting other provider profiles. Courier, service, and route availability depend on the provider and your account access.

= Configure shipping and monitor API usage =

Set your shipping origin, choose the courier services to offer, and enter product weights. A configurable default weight is used per item when its product weight is empty. Customers select a destination through dropdowns or location search, depending on your settings and provider support.

Rate caching reduces repeated API requests during the lifetime you configure. The dashboard shows request usage and estimated costs. Request limits and optional warning emails help monitor usage. Cost estimates are informational; the provider's billing records determine actual charges.

The Checkout tab controls destination selection, cheapest and fastest badges, and rate sorting by name, price, or delivery time.

= Rates and service terms =

JagoOngkir is an independent integration with third-party services. Shipping rates are supplied by the selected API provider. They may differ between providers or from direct courier quotes because of differences in data, calculation methods, rounding, coverage, and rate updates. Final shipping charges are determined by the courier when the parcel is processed.

Registration, API fees, quotas, service terms, and privacy policies are managed by each provider. API usage charges are separate from parcel delivery charges. See External services and Privacy below for request and data details.

= Compatibility and scope =

The plugin supports stores using Indonesian rupiah (IDR), classic WooCommerce Cart and Checkout, and High-Performance Order Storage (HPOS). Use the [woocommerce_cart] and [woocommerce_checkout] shortcodes.

JagoOngkir calculates shipping rates only. It does not book deliveries, arrange pickups, or track parcels. Biteship services requiring coordinates, including instant delivery, are not supported. The plugin works without installing a permanent local location database.

= Features =

* Display provider rates for the courier services you select.
* Select provider-verified destinations through dropdowns or location search where supported.
* Keep API keys, origins, request limits, usage counters, and caches separate for each provider account.
* Set a default weight for products without a weight and configure the rate cache lifetime in seconds.
* Show optional cheapest and fastest badges and sort shipping rates.
* Monitor daily and monthly rate requests, estimated costs, and optional usage warning emails.
* Check rates, clear shipping caches, and import or export settings from Tools. API keys are excluded from exports.
* Retain shared courier and service selections when switching providers. Only supported selections can return rates.

= Requirements =

* WordPress 6.3 or later.
* PHP 7.4 or later.
* WooCommerce 8.2 or later.
* A provider account with access to shipping rate and location APIs.

== Installation ==

1. Install and activate WooCommerce. Upload the jagoongkir folder to /wp-content/plugins/ and activate JagoOngkir from Plugins.
2. Go to WooCommerce > Ongkos Kirim > API Connection and enter your provider API key. For RajaOngkir, use a current RajaOngkir Shipping Cost API key.
3. Select the active provider in General. Set the Origin Location under Shipping Origin.
4. Choose courier services, configure the default product weight and rate cache duration, and enable shipping.
5. Configure destination selection, badges, and rate sorting in Checkout. Use [woocommerce_cart] and [woocommerce_checkout] on the corresponding pages. Enable WooCommerce's cart shipping calculator if you want destination selection on the cart page.
6. Enter product weights and check your configuration. Checking rates in Tools sends a fresh provider request and may incur an API fee.

== Frequently Asked Questions ==

= Is JagoOngkir affiliated with the API providers or couriers? =

No. JagoOngkir is an independent plugin connecting WooCommerce to third-party shipping APIs. It is not officially affiliated with those providers or courier companies.

= Do I need an API account? =

Yes. Register with [api.co.id](https://api.co.id/), [RajaOngkir / Komerce](https://rajaongkir.com/), or [Biteship](https://biteship.com/) and obtain an API key. You only need an account with the provider you choose.

= Are there API usage fees? =

Fees, quotas, and API access depend on your provider account and plan. API fees are separate from parcel delivery charges. Check your provider's current pricing and account terms.

= Where do shipping rates come from? =

Shipping rates and service availability come from your selected API provider. JagoOngkir displays the results it receives.

= Why can rates differ between providers or from direct courier quotes? =

Providers may use different data sources or calculation methods. Weight rounding, package dimensions, coverage, and rate updates can also affect results. Final delivery charges follow the courier's calculation when the parcel is processed.

= Which terms and privacy policies apply? =

API use is subject to the selected provider's terms and privacy policy:

* api.co.id: [Terms](https://dashboard.api.co.id/terms) and [Privacy policy](https://api.co.id/privacy-policy/).
* RajaOngkir: [Terms](https://rajaongkir.com/terms-condition) and [Privacy policy](https://rajaongkir.com/privacy-policy).
* Biteship: [Terms](https://biteship.com/en/terms-of-use) and [Privacy policy](https://biteship.com/en/privacy-policy).

= Why are shipping rates missing? =

Check your API key, provider balance or quota, origin, destination, product weights, and service selections. Rates may be unavailable during a provider outage or when a courier does not serve the route. After switching providers, select the destination again so it can be verified by the active provider.

= Is customer information sent to the API provider? =

The plugin sends origin and destination location data and the package information needed for a quote. Customer names, email addresses, phone numbers, and street addresses are not sent. See External services and Privacy below.

= Can JagoOngkir book or track shipments? =

No. The plugin calculates shipping rates only. It does not book deliveries, arrange pickups, or track parcels.

= Does the plugin support Cart and Checkout Blocks? =

No. Use the classic [woocommerce_cart] and [woocommerce_checkout] shortcodes.

= Can I change providers without losing my settings? =

Yes. Provider profiles and account-specific caches are retained. Shared courier and service selections are preserved, including selections unavailable for the active provider. Only matching, unexpired quotes are reused.

== External services ==

An account and API key are required for your selected provider. Requests are sent from the WordPress server. API keys are not sent to browser JavaScript or displayed unmasked. After the merchant configures a key, API requests occur when testing a connection, searching locations, validating destinations, preparing location caches, or calculating shipping rates. Storefront requests use the active provider. Administrators can test connections for each configured provider; the rate-checking tool uses the active provider.

The provider receives location names, search terms, and rate parameters needed for its requests, along with the server IP address and standard HTTP request metadata. Customer names, email addresses, phone numbers, and street addresses are not sent. Provider account terms and fees apply.

Activating the plugin alone does not start provider requests: a merchant must configure a provider API key first. Connection tests and the admin rate tool make provider requests when used. Configured providers may also receive background requests to prepare location caches and storefront requests when customers select destinations or calculate shipping. Usage warning emails use the site's configured WordPress mail service.

All plugin JavaScript and CSS is served locally. jQuery comes from WordPress, and SelectWoo and its stylesheet come from the installed WooCommerce plugin. No CDN, remote executable code, analytics, or third-party update checker is loaded. Public AJAX URLs, nonces, and translated labels are passed as non-executable JSON in script data attributes; provider API keys remain on the server. Links to the author website, documentation, and provider policies are ordinary links and are not contacted automatically.

= api.co.id =

* Website: https://api.co.id/
* Documentation: https://docs.api.co.id/products/indonesia-courier-rates/
* Terms: https://dashboard.api.co.id/terms
* Privacy policy: https://api.co.id/privacy-policy/
* Requests use https://use.api.co.id/ with the x-api-co-id header. GET courier/v1/couriers tests the connection. GET courier/v1/locations/provinces, courier/v1/locations/cities, and courier/v1/locations/districts provide shipping location hierarchies.
* Location search uses expiring caches progressively prepared from those courier endpoints after connection verification. Matching regions and the origin city are prioritized. Preparation runs in the background; an initial empty search may also advance up to three hierarchy-loading tasks without waiting for hosting cron. Loading feedback is shown while requests are running. The separate Regional API is not used.
* A browser search makes at most three automatic attempts within 20 seconds, stopping earlier if preparation does not advance. Results are reused on the same page for 60 seconds, or 10 seconds while preparation is pending. Closing the dropdown or changing the search cancels the previous browser search. Districts not yet cached may need more preparation; include a city or province name to prioritize them.
* Search supports province, city/regency, and district names. These courier location endpoints do not provide village results.
* GET courier/v2/rates sends origin and destination district codes, weight in kilograms, insurance=false, and item value when available. The plugin estimates Rp5 for each request returning usable shipping rates; failed and empty responses are excluded. Actual billing follows the provider's current terms.

= RajaOngkir =

* Website and documentation: https://www.rajaongkir.com/docs/shipping-cost/getting_started/about
* Terms: https://rajaongkir.com/terms-condition
* Privacy policy: https://rajaongkir.com/privacy-policy
* Requests use https://rajaongkir.komerce.id/api/v1/ with the key header. GET destination/province, destination/city/{province_id}, and destination/district/{city_id} provide verified location hierarchies. GET destination/domestic-destination searches location names; search-result IDs are not used directly as district IDs.
* If direct search does not match some city names, the plugin uses the same provider's province/city directory, cached per account for 24 hours, to return verified districts. This directory is prepared progressively in the background, prioritizing the origin province. Village names are still searched directly through the provider. No permanent local location database is installed.
* POST calculate/district/domestic-cost sends verified origin and destination district IDs, weight in grams, supported courier codes, and price=lowest. The integration does not use the legacy RajaOngkir API or the Komerce Delivery Order API.

= Biteship =

* Website: https://biteship.com/
* Documentation: https://biteship.com/en/docs/api/maps/search_area and https://biteship.com/en/docs/api/rates/overview
* Terms: https://biteship.com/en/terms-of-use
* Privacy policy: https://biteship.com/en/privacy-policy
* Requests use https://api.biteship.com/v1/ with the Authorization header. GET couriers verifies the key and returns supported services. GET maps/areas searches Indonesian locations with countries=ID, input, and type=single.
* POST rates/couriers sends verified origin and destination area IDs, supported courier codes, a generic item label, weight in grams, quantity, item value, and dimensions in centimeters when available. The admin rate tool uses one item with the entered weight and zero item value, so services requiring an item value may be unavailable. Coordinates and shipment booking data are not sent.

== Privacy ==

Settings and credentials are stored in non-autoloaded WordPress options. Provider response and location caches are separated by account and stored in expiring WordPress transients rather than a permanent local location database. Verified customer addresses and rate metadata are stored through WooCommerce sessions and customer/order CRUD operations.

Location responses are normally cached for 24 hours and search results for five minutes. The shipping rate cache duration is configurable in seconds. Daily usage details are retained for 90 days and monthly summaries for the last 13 recorded months per account. The dashboard shows all providers and filters for today, yesterday, this week, this month, and last month, using the site's timezone and start-of-week setting. Older daily details may be incomplete because earlier versions retained only three days; available monthly summaries are preserved.

Optional usage warning emails are sent to the configured recipient through the WordPress mail service. The local location request limiter stores a keyed hash of the visitor's IP address in WordPress options. This limiter does not send the visitor's raw IP address to providers. Counters use one-minute intervals; the stored hash remains until a later request updates the counter state. Describe your store's use of the selected providers in its privacy policy.

== Changelog ==

= 1.0.0 =
* Initial release.
