
Short answer: Bosta API integration means your store or operations system can create shipments, request pickups, print air waybills and receive delivery status from Bosta through Bosta's official APIs, API keys and webhooks, instead of staff typing every order into the dashboard. An official Shopify, WooCommerce or Easy Orders plugin can be enough when that plugin already covers your flow. A custom integration is worth scoping when you run a custom store, ERP or warehouse system, when you need retries and one status record in your own database, or when official plugin settings do not match how you actually deliver, collect cash, exchange or return orders.
By Mohamed Samy, senior backend developer specializing in Laravel/PHP, with seven years of experience. Published: 17 November 2026. Updated: 17 November 2026.
This is not legal or financial advice, and it is not a substitute for Bosta's official documentation, pricing or commercial terms. Shipping rates, cash collection and optional features such as FlexShip or prepaid amounts are set by Bosta; confirm them on Bosta's current official pages before you rely on a figure or a fee.
Most owners who contact me already ship with Bosta in Egypt and are tired of copying orders from a store dashboard into a courier screen. Whether to stay on a hosted platform or build a custom ecommerce store is a different article, as is the earlier choice between a company website, an online store and a hosted platform. This one assumes Bosta is your courier and you need a reliable official integration with the system that already holds the order. Golden Code builds that custom layer from scratch; we do not resell a Bosta plugin, and we do not publish a fixed package price.
What Bosta API integration actually has to do
Bosta publishes a developer documentation portal and an API reference. The current business endpoints live under https://app.bosta.co/api/v2, as shown on Bosta's official how-to pages. For an API key, official documentation tells you to send the key in the Authorization header as the key itself, together with Content-Type: application/json. That is not a shared dashboard password, and it is not a Bearer prefix unless a specific official token flow says so.
A useful integration usually has to do the following, even if you start with a plugin:
| Area | What usually breaks today | What the integration should do |
|---|---|---|
| New orders | Staff retype the customer and the address into Bosta | A confirmed order creates the right official order type once |
| Addresses | A free-text city name misses the hub | The address follows Bosta's official city, district and line format |
| Status | The store still says "processing" after the courier has moved | A webhook updates your record when the official state changes |
| Cash on delivery | Collected amounts live only in the courier dashboard | Your system stores the official collected amount against the order |
| Returns and exchanges | A return is opened as a normal delivery by mistake | The official CRP or Exchange type is used, with the required address side |
| Waybills | Someone prints the wrong label, or prints one that Bosta will not issue | Air waybills are requested only for printable official states |
Bosta's official create-delivery guide lists four primary order types, and you send the numeric code in the API request:
| Type | Code | Official use |
|---|---|---|
| Deliver | 10 | Standard order: you send the product to the customer |
| Cash Collection | 15 | You need Bosta to collect cash from the customer |
| CRP (Customer Return Pickup) | 25 | The customer asked to return an order |
| Exchange | 30 | Bosta delivers a new order and brings the exchanged package back |
The same official page states that dropOffAddress is required for Deliver and Exchange, and that pickupAddress is required for Cash Collection and CRP, because those two types start at the customer's location. A business location id can be sent; if you omit it, Bosta uses your default location. Official error code 1073 says you should have a business location before you create an order, so a default pickup location is not an optional nice-to-have.
Official Bosta geography, and what the API currently covers
Bosta's About page describes a logistics-tech company founded in Egypt in 2017. The public website brands itself as a courier service in Egypt and Saudi Arabia, and Bosta's international express page offers delivery from Egypt to Saudi Arabia. The fulfillment page also describes Bosta as a logistics and technology company in Egypt, Saudi Arabia and the UAE.
The official API is narrower than the marketing homepage, and that difference matters for a technical scope. Bosta's address format guide currently states that Bosta is supporting one country, Egypt, with country code EG, and it publishes an Egypt zoning sheet. Cities, districts and zones should be read from the official public list endpoints, not from a city list you remember from last year. Each district carries pickupAvailability and dropOffAvailability, so a district that looks familiar on a map is not always a district Bosta will pick up from or deliver to.
This article is therefore for Egyptian stores that need a Bosta API integration against that official Egypt address format. If you also use Bosta's Egypt-to-Saudi international express, confirm the current service and the fields Bosta expects with Bosta's official pages or support; do not assume the same district format covers every Gulf address. A Salla API integration for a Saudi or Gulf storefront is a separate job, with Salla's own official APIs.
Official plugins versus a custom layer
Bosta documents official plugins for Shopify and WooCommerce. In both cases you generate an API key from the Bosta business dashboard and paste it into the plugin settings. The WooCommerce guide covers manual sync, bulk "Send to Bosta", and an Auto Sync option that can create the Bosta shipment when a store order is placed, from your location. It also explains how to attach a Bosta fulfillment SKU if you use Bosta fulfillment centers. The Shopify guide covers AWB note options, a customer confirmation email that includes the Bosta tracking number, and a setting for businesses that pay shipping fees with Bosta credits. The Shopify guide lists automatic "Fulfilled" and "Paid" flags. The checkbox wording says those flags update after a successful delivery; a following sentence on the same official page says they update upon successfully sending the order to Bosta. Confirm the live official behaviour in the plugin before you rely on either timing.
Bosta's official FAQ also documents how to connect an Easy Orders account: the merchant sets Egypt as the shipping country, chooses Bosta from the shipping companies list, and pastes the same official API key.
Start with the official plugin when your store is actually Shopify, WooCommerce or Easy Orders, and when the documented settings match the flow you run every day. Move to a custom layer when the order lives in a custom system, when inventory or accounting must stay in your own database, when you need webhook intake, retries and an audit trail, or when a plugin flag is not the same thing as a business rule. A WooCommerce shop that has already outgrown the rest of WordPress can also be a reason to plan a WordPress-to-Laravel migration and to build the courier connection as part of that system, rather than stacking another plugin on a store you already intend to leave.
API keys, scopes and official hosts
Bosta's Get Your API Key guide is the official starting point. From the settings page you open the API Integration tab, request an OTP, enter the code sent to your phone, then create a named key and choose its permission. Official documentation says you must copy the key before you click done, because you will not be able to view it again. You can later enable, disable or delete keys.
Bosta publishes three official scopes:
- Read only (Viewer): GET endpoints only, for dashboards and reports.
- Read/Write (Editor): GET, POST, PUT and PATCH, but not DELETE. Official documentation calls this the most common choice for integrations that create or update deliveries and pickup requests.
- Full Access: all methods, including destructive ones. Official examples include terminating a delivery, deleting a pickup location, deleting a pickup by id, and deactivating a business admin. Bosta warns you to use this scope carefully, and it recommends the principle of least privilege: pick the lowest access that meets the job.
For a custom build I usually start with a Read/Write key in a non-production test, and I only discuss Full Access if a documented administrative action is actually in scope. The key belongs on the server, in a secret store, not in a theme file or a browser call. That is the same habit as the rest of a website security checklist: limit who can see the secret, and rotate it if it leaks.
Bosta also publishes a separate official guide for a login authorization token. For store and operations integrations, follow the API key guide and the current official SDK. Do not build a production integration that logs in with the business email and password if an official API key can do the work.
The official Bosta PHP SDK is published by the bostaapp GitHub organization. Its README installs the package as composer require bosta/bosta-sdk and names two base URLs: production https://app.bosta.co and staging https://stg-app.bosta.co. Confirm those hosts in the official repository before you hard-code them, and keep staging keys and live keys apart. Bosta's dashboard also has an official two-factor authentication flow under Settings, Security, using an authenticator app. Turn that on for the people who can create keys.
Addresses, pickups, waybills and money you should not invent
A delivery that fails because the city string was "Cairo" instead of the official city name is not a mysterious API bug. The official address guide requires a city from the official list, a district id or a district name with a city id, and a firstLine of more than five characters. Building number, floor, apartment and a nearby landmark are optional. Read cities from GET /api/v2/cities?countryId={countryId}, and districts or zones from the official city endpoints, including GET /api/v2/cities/getAllDistricts?countryId={countryId}. Create or confirm your default pickup location with a district id from that list, then use the official pickup request flow when you need Bosta to collect from that location.
Package specs also have official values. The create-delivery guide says package type should be one of SMALL, MEDIUM, LARGE, Light Bulky or Heavy Bulky, and that package details include a description and an item count. The same page says goodsInfo must be added correctly, because if it is omitted the insurance will not be calculated. Optional official features such as FlexShip, prepaid amounts and "allow to open the package" have extra rules on that page, including required product images when opening the package is enabled. Confirm the current wording and any fee on the official guide; I will not invent a tariff in this article. Confirm commercial rates on Bosta's official pricing page, not from a screenshot in a chat group.
If you are in scope for Egypt's e-receipt rules, cash collected by the courier is not a substitute for the tax receipt your system may still have to issue. That work belongs in your POS or ERP, as we described in the Egypt e-receipt integration guide, not in a shipping webhook alone.
Air waybills have official limits too. Bosta's print AWB guide says CRP, cash collection and finished orders are not printable, that A4 is the original waybill and A6 is the Zebra format, that you can print up to 1,000 waybills at a time, and that 50 or fewer return as a base64 PDF while more than 50 are emailed as a zip file to the registered email, with 100 waybills per file. Language can be ar or en. Build your print button around those official rules, not around a guess.

Webhooks, status changes and the cases that break a demo
The status of a shipment will change after you create it, and a demo that only calls "create delivery" will look finished until the first postponed or returned order. Bosta's official shipment status webhook guide tells you to open Settings, go to API Integration, request an OTP, then set a webhook URL. The URL is mandatory. You may also add an authorization key with a custom name; official documentation says the key name and its value must be entered together, and that neither field can be submitted on its own.
Two official notes save a lot of debugging time. The account webhook is triggered only when an order status changes, not when the order is created. Once the webhook is saved on the account, you do not need to send it again in the create-delivery request. If you have not added a webhook on the account, the same official page shows a webhookUrl field, with optional custom headers, on the create-delivery body.
Bosta will send a POST request to your endpoint after a state change, with fields such as the order id, tracking number, state code, type, timestamp, delivery promise date, number of attempts, and, where they apply, cash-on-delivery amount, exception reason and the businessReference you sent at creation. Official documentation also publishes a state table and exception codes; map your store statuses from that table, and do not invent codes. If your server sits behind a firewall, allow only the source addresses on Bosta's official whitelisting page, and re-check that list when you go live, because published IPs can change.
A serious intake does four things the plugin checkbox will not design for you: it rejects a request that fails the official authorization header, it records the raw payload before your code maps it, it updates an order only once for the same state change, and it has a way to replay a failed delivery when your endpoint was down. That is usually the gap between "we connected the plugin" and "the operations team can trust the status they see".
What we build, and what we will not promise
When a custom Bosta API integration is the right job, Golden Code builds a server-side layer, usually in Laravel and PHP, that talks to Bosta's official v2 APIs, stores the official identifiers against your orders, and listens for official webhooks. We will read the current official docs with you, agree which order types and plugins are in or out of scope, and test on the official staging host before a live key is used.
We will not invent a shipping rate, a delivery-time guarantee, or an unofficial workaround that the docs do not support. We will not resell Bosta, Shopify, WooCommerce or Easy Orders, and we will not quote a fixed package price for a job whose scope depends on your store, your warehouse and the official fields you actually need. Official software support is documented on Bosta's engineering contact page; use that channel for Bosta-side issues, and use a custom build only for the layer that sits in your system.
Six steps to scope a custom Bosta API integration
Step 1: Confirm the Bosta business account and the services you actually use
Open or complete the official Bosta business account first, and write down which official services you really run: standard delivery, cash collection, customer returns, exchanges, fulfillment, or Egypt-to-Saudi international express. Confirm commercial terms on Bosta's official pricing and service pages. Do not start a technical scope against a flow your contract or dashboard does not include.
Step 2: Choose an official plugin when it already covers the store
If the store is Shopify, WooCommerce or Easy Orders, read the official plugin or FAQ guide and test the documented settings, including Auto Sync, fulfillment SKUs and status flags. Stay on the official plugin when it matches the daily flow. Commission a custom layer only when orders, inventory or status need to live in your own system, or when a documented plugin setting cannot represent the rule you run.
Step 3: Create an API key with the lowest official scope and a separate staging host
From the official API Integration settings, request the OTP, create a named key, and choose Read only or Read/Write unless a documented administrative action truly needs Full Access. Copy the key once, store it on the server, and keep a staging key on the official staging base URL separate from the live key. Enable dashboard two-factor authentication for the people who can issue keys.
Step 4: Map your orders to official addresses, types and the default pickup location
Load official Egypt cities and districts from Bosta's public list endpoints, and format every pickup or drop-off address with the required official fields, including a first address line longer than five characters. Give the business a default pickup location before you create deliveries. Map each of your order cases to the official type code, and send the required address side for that type.
Step 5: Register the account webhook and allow only official Bosta traffic
In the official dashboard, set the webhook URL after the OTP step, and add the authorization header name and value together if you use one. Build your endpoint to accept status-change events, not an event at order creation, and to store the official tracking number, state, exceptions and business reference. Allow only the current source addresses published on Bosta's official whitelisting page.
Step 6: Test waybills, failures and returns, then agree monitoring and handover
Print air waybills only for official printable states, and respect the official A4 or A6 format and the official volume limits. Walk a postponed delivery, a cash-collection case and a customer return all the way through your own records. Agree who watches failed webhooks, who rotates keys, and who contacts Bosta support. If you want Golden Code to build the custom layer, ask for a custom technical quote after that scope is written down.
Soft next step
If your Egyptian store already runs on Bosta and the next risk is a missed status or a retyped address, write down the order types you actually use and the system that should own the record. You can then request a custom technical quote from Golden Code. We will answer against official Bosta documentation and against your scope, not with a ready-made package.
FAQ
Is Bosta API integration only for stores in Egypt?
The official address format guide currently states that Bosta is supporting one country, Egypt. Bosta's public site also markets courier and international express services involving Saudi Arabia, and the fulfillment page mentions Egypt, Saudi Arabia and the UAE. Confirm any service outside the official Egypt address format with Bosta's current official pages; this guide is written for Egyptian stores using that official API format.
Should we use the official WooCommerce or Shopify plugin instead of a custom integration?
Use the official plugin when your store is actually on that platform and the documented settings cover the daily flow, including sync, fulfillment SKUs and status flags. A custom integration is worth scoping when the order already lives in your own system, or when you need webhook intake, retries and a single audit trail the plugin does not give you.
How do we get a Bosta API key?
From the official Bosta business dashboard, open Settings, then the API Integration tab, request an OTP, enter the code sent to your phone, and create a named key with the lowest official scope that meets the job. Copy the key before you click done, because official documentation says you will not be able to view it again.
Does the Bosta webhook fire when we create an order?
No. Official documentation states that the account webhook is triggered only when an order status changes, not on order creation. Once the webhook is saved on the account, you do not need to send it again in the create-delivery request.
Which API key scope should a typical store integration use?
Official documentation describes Read only for GET access, Read/Write as the most common choice when you create or update deliveries, and Full Access for administrative actions that can include terminating a delivery or deactivating a business admin. Follow least privilege, and use Full Access only when a documented administrative action is actually in scope.
Do you sell a fixed Bosta API integration package?
No. Golden Code builds a custom integration against official Bosta APIs when a plugin is not enough. The work depends on your store, your order types and the official fields you need, so we provide a custom technical quote rather than a published package price.
Sources
- Bosta documentation portal
- Bosta API reference
- Get Your API Key
- Create Your First Delivery
- Format Bosta Address
- Get Shipment Status via Webhook
- Create Your Pickup Location
- Create Your First Pickup
- Print Air Waybill
- Whitelisting
- Login with Two-Factor Authentication
- Shopify Integration
- WooCommerce Integration
- Easy Orders FAQ
- Contact Bosta engineering
- Official Bosta PHP SDK
- Bosta About (Egypt)
- Bosta international express
- Bosta fulfillment
- Bosta pricing




