Create Order
Only create an order if the preceding availability check returned a locker. This is a Locker Capacity Surplus order — the consumer did not select a locker in checkout and is not aware of the Instabee brand. The locker assignment is handled automatically based on surplus capacity.
It does also levels up the integration and enables you to send information in the post purchase call that is not possible to send in the post packing call. As Instabee will easily merge the information on our end without introducing any extra complexity.
When to Use
Call this endpoint immediately after:
- Customer completes their purchase in your checkout system
Integration Levels
You can integrate at different levels on what's possible:
- Nothing: This call can of course be skipped completely but that just makes it harder for Instabee to achieve a great delivery experience.
- Bare Minimum: Just an availability token/short toke/order reference/cart ID and the selected delivery options. This is the absolute minimum and will enable us to reserve the capacity.
- Regular (or Instabee prefered option): Basic recipient and delivery information.
- Maximum: Complete order details including products, dimensions, and special services. You can create a full order directly and just confirm the packing is done at a later stage.
Create Order API
API Endpoint
| Endpoint | Method | Content-Type |
|---|---|---|
api.integration.instabee.com/orders (production) · sandbox-api.integration.instabee.com/orders (sandbox) | PUT | application/json |
The Create Order API (also known as Create Parcel API) is used to register a parcel for delivery immediately after a customer completes their purchase. This is the prebooking step that reserves capacity for delivery before the parcel is physically packed.
Integration Levels
You can provide information at different levels:
- Bare Minimum: Nothing
- Minimum: Basic order identification and delivery option
- Regular: Basic recipient and delivery information
- Maximum: Complete order details including products, dimensions, and special services
Request Body
| Parameter | Type | Required | Description | Constraints | Comment |
|---|---|---|---|---|---|
| brand | string | required | Define brand of the delivery options | instabox or budbee | |
| product | string | required | Define the product of the delivery options | LOCKER_CAPACITY_SURPLUS | |
| parcelPackingConfirmed | boolean | conditional* | Confirm parcel is packed and ready for pickup | send as false | If not sent we will default to false for one call per availabilityToken, shortToken or checkoutID |
| availabilityToken | string | required | Availability token from availability response | Can be discussed with your Implementation Manager to be excluded. Used as a link in Instabee system | |
| parcelId | string | optional | Unique identifier/barcode for parcel | Auto-generated if omitted | |
| merchantBrandId | string | optional | Merchant brand identifier | Must be configured by your Implementation Manager | |
| communicationName | string | optional | Communication name override | Note! This will only change the name in Instabee communication such as notifications, SMS or email. Will not change partner name in our partner portal nor change any specs on invoices | |
| recipient | object | required | Recipient information object | ||
| deliveryOption | object | required* | The selected locker from checkout. Do not transform or validate this! | ||
| dispatch | object | optional | Dispatch readiness and warehouse information | ||
| additionalServices | object | optional | Additional services such as identification methods | ||
| cart | object | optional | Parcel and/or product details |
recipient
| Parameter | Type | Required | Description | Constraints | Comment |
|---|---|---|---|---|---|
| name | string | required | Recipient name | ||
| string | required | Recipient email address | Valid email format e.g email@domain.com | Used for delivery notifications | |
| phone | string | required | Recipient phone number | Min: 6 digits, Max 15 digits | Can be made optional with setting, talk to your Implementation Manager |
| ssn | string | optional | Social security number | For age verification services | |
| street | string | required | Recipient street address | ||
| street2 | string | optional | Additional address information | Floor, apartment, C/O etc. | |
| postalCode | string | required | Recipient postal code | ||
| city | string | required | Recipient city | ||
| countryCode | string | required | Recipient country code | ISO 3166 alpha 2 | e.g., "SE", "DK", "NO", "FI", "NL", "BE" |
deliveryOption
| Parameter | Type | Required | Description | Comment |
|---|---|---|---|---|
| sortCode | string | required | Sort code for the locker | Identifies specific locker or specific home delivery option |
dispatch
| Parameter | Type | Required | Description | Constraints | Comment |
|---|---|---|---|---|---|
| readyToShip | string | optional | When parcel is ready for pickup | ISO-8601 datetime | Only one of readyToShip/readyToPack/outOfStock |
| readyToPack | string | optional | When packing process will start | ISO-8601 datetime | Instabee adds packing time to this |
| outOfStock | boolean | optional | Product is out of stock | true/false | Removes ETA from delivery options |
| collectionPointId | string | optional | Specific warehouse/pickup point | Configured by Instabee | |
| returnPointId | string | optional | Currently not implemented! Return address point ID | For failed deliveries |
additionalServices
| Parameter | Type | Required | Description |
|---|---|---|---|
| identification | object | optional | Identity verification requirements |
additionalServices.identification
| Parameter | Type | Required | Description | Constraints | Comment |
|---|---|---|---|---|---|
| type | string | optional | Type of verification | "age_limit", "age_limit_at_handover", "specific_person", "specific_person_at_handover" "any_person" | Age veritification and specific person is currently only live in Sweden. Any person verification is live in Sweden, Denmark, Norway |
| ageLimit | number | optional | Minimum age required | Used with age_limit types | |
| ssn | string | optional | Required SSN for verification | ||
| name | string | optional | Required name for verification |
type explanations
| Type | Description |
|---|---|
| age_limit | Verify the consumer age. This verification will be triggered when the parcel is created. Only live with Swedish BankID |
| age_limit_at_handover | Verify the consumer age when they pickup the parcel (at handover). Only live with Swedish BankID |
| specific_person | Verify the consumer identify by matching SSN sent on the order with the SSN from the verification. Only live with Swedish BankID |
| specific_person_at_handover | Verify the consumer identify by matching SSN sent on the order with the SSN from the verification when they pickup the parcel (at handover). Only live with Swedish BankID |
| any_person | Verify the consumer identify by matching doing a BankID or NemID verification. Currently live in Sweden, Denmark and Norway |
cart
| Parameter | Type | Required | Description | Comment |
|---|---|---|---|---|
| checkoutId | string | optional | Checkout session ID | Used as a link in Instabee system |
| orderNumber | string | required* | Your order number | Used as a link in Instabee system |
| totalValueInCents | number | optional | Total order value in cents | This helps us with claims process |
| totalWeightGram | number | optional | Total weight in grams | This helps us with claims process |
| parcel | object | optional | Parcel dimensions and contents | Detailed parcel information |
cart.parcel
| Parameter | Type | Required | Description | Constraints | Comment |
|---|---|---|---|---|---|
| heightMm | number | optional | Parcel height in mm | If you do not have this data, do not send anything | |
| widthMm | number | optional | Parcel width in mm | If you do not have this data, do not send anything | |
| lengthMm | number | optional | Parcel length in mm | If you do not have this data, do not send anything | |
| volumeDm3 | number | optional | Parcel volume in dm³ | If you do not have this data, do not send anything | |
| estimatedSize | string | optional | Estimated size category | "small", "large" | |
| weightGram | number | optional | Parcel weight in grams | ||
| type | string | optional | Parcel type | "box", "envelope", "bag" | |
| products | array | optional | Array of products in parcel | Detailed product information |
cart.parcel.products[]
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | optional | Product name |
| quantity | number | optional | Quantity of this product |
| productId | string | optional | Your product identifier |
| details | object | optional | Detailed product information |
cart.parcel.products[].details
| Parameter | Type | Required | Description | Constraints |
|---|---|---|---|---|
| productType | string | optional | Type of product | e.g., "Prescription" |
| imgUrl | string | optional | Product image URL | |
| category | string | optional | Product category | |
| brand | string | optional | Product brand | |
| description | string | optional | Product description | |
| price | object | optional | Price information | |
| temperature | object | optional | Temperature requirements |
cart.parcel.products[].details.price
| Parameter | Type | Required | Description | Constraints | Comment |
|---|---|---|---|---|---|
| priceInCents | number | optional | Price in cents | ||
| taxRateInCents | number | optional | Tax amount in cents | ||
| discountRateInCents | number | optional | Discount amount in cents | ||
| currency | string | optional | Currency code | ISO 4217 | e.g., "SEK" |
cart.parcel.products[].details.temperature
| Parameter | Type | Required | Description |
|---|---|---|---|
| min | number | optional | Minimum 8. Temperature in Celsius |
| max | number | optional | Maximum 15. Temperature in Celsius |
cart.parcel.products[]
| Parameter | Type | Required | Description |
|---|---|---|---|
| packages | array | optional | Physical package information |
cart.parcel.products[].packages[]
| Parameter | Type | Required | Description | Comment |
|---|---|---|---|---|
| widthMm | number | optional | Package width in mm | If you do not have this data, do not send anything |
| heightMm | number | optional | Package height in mm | If you do not have this data, do not send anything |
| lengthMm | number | optional | Package length in mm | If you do not have this data, do not send anything |
| weightMm | number | optional | Package weight | If you do not have this data, do not send anything |
| volumeDm3 | number | optional | Package volume in mm³ | If you do not have this data, do not send anything |
| barcodes | array | optional | Barcode information | If you do not have this data, do not send anything |
cart.parcel.products[].packages[].barcodes[]
| Parameter | Type | Required | Description | Constraints |
|---|---|---|---|---|
| code | string | optional | Barcode value | |
| type | string | optional | Barcode type | "ean13", etc. |
Key Benefits
- Capacity Reservation: Ensures delivery slots are reserved for your customers
- Flexible Integration: Send as much or as little information as you have available
- Early Tracking: Customers get tracking information immediately after purchase
- Optimized Logistics: Helps Instabee plan pickup and delivery routes
Next Steps
- Complete Parameter Reference: See the Create Order API page for all available parameters
- After Packing: Use the Post Packing API to confirm when parcels are ready for pickup
- Integration Guide: Check the Authentication section for API setup
Quick Links
- Availability API - Check delivery options before creating parcels
- Post Packing API - Confirm parcels after physical packing