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 a test order ID that has reached the Delivered status and a test order ID with 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 the sandbox API key
- How to simulate test order status to Delivered
- How to simulate 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 (starting 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 manually changed 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, ensure you have an API key with the Development (Sandbox) environment.
- Log in to the Biteship Dashboard, then open the Settings > API menu.
- Ensure the API key you will use is labeled Development. The token starts with
biteship_test. - Copy that API key. You will use it to create test orders via API.
3. Create Test Orders Using the Sandbox API Key
Test orders must be created through 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 simulate 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 Test Order to 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 the test order. A dropdown menu will appear with the next status options.
- Click the next status options sequentially. The status order to reach Delivered is as follows:
- CONFIRM ORDER (from the confirmed status)
- ALLOCATE (from confirmed after confirmation)
- START PICKING UP
- Pick Up Item (Picked)
- Heading to Customer (Dropping Off)
- COMPLETED (Delivered)
- Once 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 Test Order to 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 all stages before the order reaches the final status.
- After confirmation, the test order status will change to Cancelled. Note this Order ID for the API activation form.
6. Enter 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 directly via
dashboard.biteship.com/api-activation-form. - In the Delivered Order ID field, enter the Order ID of the test order that reached 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 (choose courier, upload shipping label if required, and fill 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 has been allocated and is ready to pick up |
| picking_up | Courier is heading to pickup location |
| picked | Item has been 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 in the process of 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 a 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 the previous stages?
No. Status must be changed sequentially according to the delivery flow. You need to press 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 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 an API key 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 correctly configured in Settings > API under the Webhook URL (Test) section. Each time the test order status is updated, 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 difficulties during this process, feel free to contact the Biteship support team via email at support@biteship.com or through the live chat feature in the Dashboard.