Description
Crates Shipping for Bosta connects a WooCommerce store in Egypt to the Bosta courier service. It prices delivery at checkout from your Bosta account, sends orders to Bosta as shipments, prints airway bills, and keeps each order’s delivery status up to date.
This is an independent plugin by Crates Digital. It is not made, endorsed or supported by Bosta, and is not affiliated with Bosta in any way. Bosta, its name, logo and brands are trademarks and copyrights of Bosta Technology LLC. For Bosta account, pricing or delivery questions, contact Bosta directly.
You need a Bosta business account and an API key from your Bosta dashboard.
- Live Bosta prices at checkout, no shipping zones needed. Every Egyptian address is offered Bosta delivery at your Bosta account’s own price, VAT included, for the customer’s governorate and the largest Bosta shipping class in the cart.
- Send orders to Bosta with the “Send to Bosta” button in the orders list, from the Bosta box on an order, in bulk, or automatically when an order reaches Processing (off by default). Sent orders show “Sent to Bosta”, their tracking number and a Print AWB button.
- Shipment details on the order: AWB number, status, delivery area, size, cash to collect, insurance, Bosta’s fees and delivery attempts.
- Notes on the AWB. Staff can write notes on the order before or after sending; after sending they are updated on Bosta until the parcel is out for delivery.
- Cash on delivery is worked out for you. COD orders collect the order total minus refunds; orders paid online collect nothing.
- Print airway bills for one order or up to 50 at a time, in A4 or A6, Arabic or English.
- Live status. Bosta reports each change to the store: it appears in an order note and in the Bosta column of the orders list. Delivered orders can be completed automatically.
- Cancel shipments from the order screen. This needs a Full Access API key.
- Bosta shipping class on every product, included in WooCommerce product CSV export and import. A shipment takes the largest class in the order.
- Shipping insurance. Off, a checkbox customers can tick at checkout, or always built into the shipping rate. Bosta is only asked to insure orders that paid the fee.
- Bosta’s places in addresses. Egyptian addresses use Bosta’s governorate names and Area and Neighborhood dropdowns, so orders name an exact Bosta district.
- Customers see their tracking number on their order page and in order emails sent after the shipment exists.
Setup
- Activate the plugin and open WooCommerce > Settings > Bosta.
- Paste an API key from your Bosta dashboard (Settings > API Integration). Use a Read/Write key, or Full Access if you want to cancel from WooCommerce. You can define
CDBS_API_KEYin wp-config.php instead. - Choose your pickup location and defaults. The Status line confirms the connection.
No webhook setup is needed: each shipment tells Bosta where to send its updates.
Bosta shipping method
With “Offer Bosta delivery” on (WooCommerce > Settings > Bosta, the default), checkout offers Bosta delivery for every Egyptian address, with no shipping zone needed. Stores that prefer zones can instead add the “Bosta” method to a zone; where a zone has it, the zone’s settings are used and the customer never sees Bosta twice. Either way the price comes from Bosta’s shipping fee calculator for your account:
- Where: the customer’s governorate, as a Bosta city, delivered from your Bosta pickup location’s city.
- Size: the largest Bosta shipping class in the cart, since Bosta ships an order as one parcel (Small & Medium is Bosta’s Normal size, XX-Large is its White Bag).
- VAT: included, using Bosta’s price after VAT. Prices are rounded up to a whole pound unless you turn that off in the method.
Prices are cached for 12 hours. If Bosta can’t be reached, a price up to a week old is used; with none, the method is left off checkout and a warning is logged under WooCommerce > Status > Logs (crates-shipping-for-bosta). Bosta’s extra fee on large cash-on-delivery amounts is not added.
Bosta shipping classes
The field is under Product data > Shipping, and on each variation. Choosing a class also sets the matching WooCommerce Shipping class, which flat rates in your shipping zones use for their price. Products that don’t have a Bosta class saved yet use their WooCommerce Shipping class, so existing products need no changes.
Product exports include a “Bosta shipping class” column, and imports map it automatically. Use Small & Medium, Large, X-Large, XX-Large, Light Bulky or Heavy Bulky. A blank cell changes nothing, and a misspelled class fails that row with a message. If a row has both this column and WooCommerce’s “Shipping class”, this one wins.
Bosta’s API documents no size value for X-Large or XX-Large, so those are currently sent as LARGE. The cdbs_api_size filter changes this.
Shipping insurance
Choose a mode under WooCommerce > Settings > Bosta and enter your insurance rate. The fee is that percentage of the value of the physical products.
- Customer chooses at checkout: a checkbox adds the fee as its own line in the order totals.
- Always included in the shipping rate: the fee is added to every delivery rate, with no choice. Local pickup is never insured.
Either way COD orders collect it. Staff can change the choice on the order screen before creating a shipment, but that doesn’t change the fee the customer paid.
Customer addresses
With “Use Bosta’s places” on (the default), Egyptian addresses at checkout and in My Account use Bosta’s governorate names, and the town field becomes an Area dropdown, then a Neighborhood dropdown where the area has more than one. The town field stores “Neighborhood, Area”, which shipments read back as an exact district. WooCommerce’s state codes are kept, so shipping zones and saved addresses still work.
All 28 of Bosta’s governorates are listed, including North Coast, which Bosta treats as its own city. Bosta doesn’t currently deliver to North Sinai, so customers there can choose it but are offered no Bosta delivery, only any other method such as store pickup. A saved address whose town isn’t on Bosta’s list opens for editing at checkout, so the customer picks one. If the list can’t be loaded, the normal town field comes back.
How towns become Bosta districts
Checkout collects the town as free text, but Bosta needs one of its own districts. The plugin matches the text in English or Arabic.
- A clear match is used automatically.
- A town that only names a whole area, like “Nasr City” or “New Cairo”, needs staff to choose the district on the order screen.
- Anything else is offered there as a best guess for staff to confirm.
- Bulk and automatic creation never guess. Those orders wait, with the reason in the Bosta column and order notes.
Duplicate protection
Each order can only have one active shipment. Creation is locked per order, and each shipment carries a unique reference (GN-<order id>-<attempt>) so Bosta can reject a repeat if a request is retried after a timeout.
External services
This plugin connects to Bosta’s API (https://app.bosta.co/api/v2) to deliver your orders. It only does so for the features you use:
- Places: Bosta’s list of cities and districts is downloaded and cached for a week, to show governorates and neighborhoods in addresses. No personal data is sent.
- Delivery prices: when a customer’s cart needs a delivery price, the pickup city, destination city and parcel size are sent to Bosta’s price calculator. No personal data is sent. Answers are cached for 12 hours.
- Shipments: when an order is sent to Bosta (by staff, in bulk, or automatically if you turn that on), the customer’s name, phone number, email, delivery address, the order number, the cash to collect, a description and count of the items, the airway bill notes, and, if insured, the value of the goods are sent. If you allow customers to open the package, links to the product photos are sent too.
- Shipment management: the tracking number is sent to fetch a shipment’s status, update its notes, cancel it, or print its airway bill.
- Status updates: Bosta sends delivery updates to your store’s webhook address, which is given to Bosta with each shipment along with a secret token.
Every request uses your Bosta API key. Bosta’s privacy policy: https://bosta.co/en-eg/privacy-policy. Bosta API documentation: https://docs.bosta.co/
The order tracking links shown to staff and customers open Bosta’s tracking page (https://bosta.co/tracking-shipments).
Changelog
1.0.0
- First release.
