Before your API key can be activated for the production environment, Biteship requires proof that your system is ready to handle various delivery statuses. One of the main requirements in the API activation form is to include test order IDs that have reached the Delivered status and test order IDs that have the Cancelled status.
Since test orders are not connected to real couriers, Biteship provides a status simulation feature directly from the Dashboard. You can manually change the status of test orders, step by step, until reaching the required status.
This article will help you understand:
- How to create test orders using a sandbox API key
- How to simulate a test order status to Delivered
- How to simulate a test order status to Cancelled
- How to use the simulated Order ID in the API activation form
1. What Are Test Orders and the Sandbox Environment?
Biteship provides two separate environments: production and sandbox (development). When you use a sandbox API key (which starts with biteship_test.), all orders created are test orders. Test orders do not deduct balance, do not involve real couriers, and their statuses can be changed manually via the Dashboard.
This status simulation feature is specifically designed to help developers test their webhook integrations before switching to production.
2. Make Sure You Have a Sandbox API Key
Before creating test orders, make sure you have an API key with the Development (Sandbox) environment.
- Log in to the Biteship Dashboard, then open the Settings > API menu.
- Make sure the API key you will use is labeled Development. The token starts with
biteship_test. - Copy this API key. You will use it to create test orders via the API.
3. Create Test Orders Using the Sandbox API Key
Test orders must be created through the Biteship API using your sandbox API key. Use the following endpoint:
Endpoint: POST https://api.biteship.com/v1/orders
Required headers:
Authorization: Bearer biteship_test.xxxxx(use your sandbox API key)Content-Type: application/json
Create at least two test orders: one to be simulated as Delivered and another as Cancelled. Note the Order ID of each order returned in the API response (field id).
{
"id": "YOUR_ORDER_ID",
"status": "confirmed",
...
}4. How to Simulate a Test Order as Delivered
After successfully creating the test order, follow these steps to change its status to Delivered:
- Log in to the Biteship Dashboard, then open the Shipments menu.
- Find the test order you created. Test orders are marked with a yellow WEBHOOK badge in the action column.
- Click the Update Status button on that test order. A dropdown menu will appear with the next status options.
- Click the next status options in order. The status sequence to reach Delivered is as follows:
- CONFIRM ORDER (from status confirmed)
- ALLOCATE (from status confirmed after confirmation)
- START PICKING UP
- Picked Up (Picked)
- Heading to Customer (Dropping Off)
- COMPLETED (Delivered)
- After the status changes to Delivered, the page will refresh automatically. Note this test order’s Order ID to use in the API activation form.
5. How to Simulate a Test Order as Cancelled
Use the second test order you created. The Cancelled status can be triggered from almost any stage before the order is completed.
- Open the Shipments menu in the Biteship Dashboard and find your second test order.
- Click the Update Status button on that test order.
- Select the CANCEL option from the dropdown menu. This option is available at almost every stage before the order reaches its final status.
- After confirmation, the test order status will change to Cancelled. Note this Order ID for the API activation form.
6. Enter the Order IDs into the API Activation Form
After both test orders have been successfully simulated, enter their Order IDs into the activation form:
- Open the Settings > API page, then click the Activate API button or access it directly via
dashboard.biteship.com/api-activation-form. - In the Delivered Order ID field, enter the Order ID of the test order that reached the Delivered status.
- In the Cancelled Order ID field, enter the Order ID of the test order that was cancelled.
- Complete the rest of the form (select courier, upload shipping label if needed, and fill in other optional fields), then click Submit.
7. Understanding the Test Order Status Sequence
Below is the full sequence of statuses that can be simulated through the Dashboard for test orders:
| Status (System) | Description |
|---|---|
| confirmed | Order confirmed, courier will be scheduled |
| allocated | Courier allocated and ready for pickup |
| picking_up | Courier is heading to pickup location |
| picked | Item picked up by courier |
| dropping_off | Courier is heading to destination |
| delivered | Order successfully received by recipient |
| cancelled | Order cancelled |
| on_hold | Order temporarily held due to delivery issues |
| return_in_transit | Package is being returned to sender |
| returned | Package successfully returned to sender |
| disposed | Package destroyed |
8. FAQ About Biteship Test Order Simulation
Why doesn’t the Update Status button appear on my order?
The Update Status button only appears on test orders created using the sandbox API key (biteship_test.). Orders created with a production API key do not have this simulation feature. Make sure you use the correct API key when creating orders.
Can I directly change the status to Delivered without going through previous stages?
No. Status must be changed sequentially according to the delivery flow. You need to click the Update Status button multiple times until the status reaches Delivered.
How many test orders do I need to create?
At least two test orders: one to simulate as Delivered and another as Cancelled. If your activation form also requires orders with price changes or waybill number changes, create additional test orders as needed.
Does simulating test orders deduct from my Biteship balance?
No. Test orders in the sandbox environment do not deduct balance and do not involve real financial transactions.
Is there a sandbox/testing mode for API integration?
Yes, Biteship provides a sandbox environment. Use API keys with the prefix biteship_test. available on the Settings > API page in the Biteship Dashboard.
Why does my API return a 401 error?
A 401 error indicates the API key is invalid or not included correctly. Make sure your request header uses the format Authorization: Bearer biteship_test.xxxxx with an active sandbox API key.
My test order status is Delivered, but the webhook is not received. What should I do?
Make sure the webhook URL is properly configured in Settings > API under the Webhook URL (Test) section. Each time a test order status updates, Biteship will send a notification to that URL.
Conclusion
Simulating test orders is a mandatory step in the Biteship production API key activation process. By following the guide above, you can create test orders, simulate Delivered and Cancelled statuses via the Dashboard, then use those Order IDs to complete the API activation form.
If you encounter any issues during this process, do not hesitate to contact the Biteship support team via email at support@biteship.com or through the live chat feature in the Dashboard.