Create Order
Only create an order if the preceding availability check returned a locker. This is a Locker Allocation order — the consumer did not select a locker in checkout and is not aware of the Instabee brand. The locker assignment uses Instabee's broader network allocation logic.
First make an availability call with the recipient's full address to verify that Instabee can receive the order. If the availability response includes a locker, create the order straight away with parcelPackingConfirmed: true using the sortCode from the availability response.
When to Use
Call this endpoint immediately after the availability check returns a locker.
Integration Levels
You can integrate at different levels on what's possible:
- Minimum: Availability token, selected brand/product, and the delivery option (locker sortCode from availability).
- Regular (or Instabee preferred option): Basic recipient and delivery information.
- Maximum: Complete order details including recipient, products, dimensions, and special services.
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. Create the order straight away — parcelPackingConfirmed must be set to true.
Integration Levels
You can provide information at different levels:
- Minimum: Basic order identification and delivery option
- Regular: Basic recipient and delivery information
- Maximum: Complete order details including recipient, 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_ALLOCATION | |
| parcelPackingConfirmed | boolean | required | Confirm parcel is packed and ready for pickup | must be true | Order is created and confirmed in a single call |
| 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 for locker deliveries. 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 | ||
| deliveryInstructions | object | optional | Delivery instruction details | ||
| 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 | Box: Min 6 digits, Home delivery: Min 10 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
- Simple Integration: Single API call creates a confirmed order — no multi-step flow required
- Flexible Integration: Send as much or as little information as you have available
- Immediate Tracking: Customers get tracking information straight away
- Optimized Logistics: Helps Instabee plan pickup and delivery routes
Next Steps
- Integration Guide: Check the Authentication section for API setup
Quick Links
- Availability API - Check delivery options and get locker sortCode before creating orders