beeShip WMS API Documentation

Version 1.0.0 | Last Updated: October 12, 2026

Complete API reference for integrating with beeShip Warehouse Management System

Quick Navigation
Legal Notice Getting Started Authentication Rate Limits Error Handling Products API Orders API Picklists API Active Picklists API Suppliers API Vendor Orders API Returns API Code Examples

Global Warehouse Network

Connect, automate and ship from anywhere. The beeShip WMS API powers fulfillment for sellers across the world — multi-tenant, multi-warehouse, and integrated with every major shop platform.

Available API Endpoints

Products
Full CRUD
Orders
Full CRUD
Picklists
Full CRUD
Suppliers
Full CRUD
Vendor Orders
Full CRUD
Returns
Full CRUD + Workflow
Active Picklists
Progress + Edit

Try the API in Postman

Download the ready-to-use Postman collection and environment below. Import both into Postman, fill in your API key, email and password in the environment once, and every request is pre-configured to hit app.beeship.io.

In Postman: File → Import both JSON files, then select the beeShip API environment from the top-right dropdown and fill in your credentials.

Getting Started

Base URL
https://app.beeship.io/api

All API requests should be made to this base URL with the appropriate endpoint path.

Quick Start Guide

  1. Get your API credentials from your tenant administrator
  2. Make your first request using the examples below
  3. Handle responses according to our standard format
Request Format

All API requests must include:

  • Headers: X-API-Key, X-Email, X-Password
  • Content-Type: application/json (for POST/PUT requests)
  • Method: GET, POST, PUT, PATCH, or DELETE
Response Format

Success Response:

{ "success": true, "data": { // Response data here }, "timestamp": "2025-11-02T14:30:00+01:00" }

Error Response:

{ "success": false, "error": { "code": 400, "message": "Error message" }, "timestamp": "2025-11-02T14:30:00+01:00" }

Authentication

The beeShip WMS API uses Triple Authentication for enhanced security.

Required Headers
Header Description Example
X-API-Key Your tenant's unique API key c1fe8d64dd95e504...
X-Email Your user email address user@company.com
X-Password Your account password YourPassword123
Example Authentication
curl -X GET "https://app.beeship.io/api/index.php?endpoint=products" \ -H "X-API-Key: your_api_key_here" \ -H "X-Email: user@company.com" \ -H "X-Password: YourPassword123" \ -H "Content-Type: application/json"
Security Best Practices
  • Never share your API key publicly
  • Never commit API keys to version control
  • Rotate your password regularly
  • Use environment variables for credentials
  • Always use HTTPS (never HTTP)

Rate Limits

beeShip GmbH enforces rate limits to ensure fair usage and system stability.

Current Limits
Endpoint Type Requests per Minute Burst Limit
General (GET) 250 300
Orders 100 120
Batch Operations 1 2
Rate Limit Headers

Response headers include rate limit information:

X-RateLimit-Limit: 250 X-RateLimit-Remaining: 247 X-RateLimit-Reset: 1699012345

Note: beeShip GmbH reserves the right to adjust rate limits without notice.

Error Handling

HTTP Status Codes
Code Meaning Description
200 OK Request successful
201 Created Resource created successfully
400 Bad Request Invalid request data or parameters
401 Unauthorized Authentication failed
403 Forbidden Insufficient permissions
404 Not Found Resource not found
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server error occurred

Products API

Manage products including inventory, images, variations, and stock levels.

GET /api/index.php?endpoint=products
Query Parameters:
Parameter Type Required Description
page integer Optional Page number (default: 1)
limit integer Optional Items per page (default: 20, max: 250)
search string Optional Search in name, SKU, EAN
Example Request:
curl -X GET "https://app.beeship.io/api/index.php?endpoint=products&limit=10" \ -H "X-API-Key: your_api_key" \ -H "X-Email: user@company.com" \ -H "X-Password: password"
Example Response:
{ "success": true, "data": { "products": [ { "product_id": 123, "name": "Luxury Hand Soap", "sku": "SOAP-001", "price": 12.99, "stock": 150 } ], "pagination": { "total_count": 1245 } } }

POST /api/index.php?endpoint=products

Create a new product in the warehouse management system.

Request Body Fields:
Field Type Required Description
name string Required Product name (max 255 characters)
sku string Required Unique SKU code (stock keeping unit)
ean string Optional EAN/UPC barcode number
description text Optional Detailed product description
price decimal Optional Selling price (2 decimal places)
cost_price decimal Optional Cost/purchase price
weight integer Optional Weight in grams
length decimal Optional Length in centimeters
width decimal Optional Width in centimeters
height decimal Optional Height in centimeters
min_stock integer Optional Minimum stock alert level
max_stock integer Optional Maximum stock capacity
manufacturer string Optional Manufacturer/brand name
country_of_origin string Optional 2-letter country code (e.g., DE, US, CN)
customs_tariff_number string Optional HS tariff code for customs
category string Optional Product category
location string Optional Warehouse location code (e.g., A-01-02)
Example Request:
curl -X POST "https://app.beeship.io/api/index.php?endpoint=products" \ -H "X-API-Key: your_api_key" \ -H "X-Email: user@company.com" \ -H "X-Password: password" \ -H "Content-Type: application/json" \ -d '{ "name": "Organic Face Cream", "sku": "CREAM-100", "ean": "4260987654321", "description": "Natural face cream with vitamin E and aloe vera", "price": 29.99, "cost_price": 15.00, "weight": 50, "length": 5, "width": 5, "height": 7, "min_stock": 5, "max_stock": 100, "manufacturer": "NatureCare GmbH", "country_of_origin": "DE", "customs_tariff_number": "330499", "category": "Cosmetics", "location": "A-03-12" }'
Example Response (Success):
{ "success": true, "data": { "product_id": 1246, "sku": "CREAM-100", "message": "Product created successfully" }, "timestamp": "2025-11-02T15:35:00+01:00" }
Validation Rules:
  • SKU must be unique across all products in your tenant
  • EAN must be unique if provided
  • Numeric fields must be positive numbers
  • Dimensions are used for shipping calculations

GET /api/index.php?endpoint=products/{id}

Replace {id} with the product ID you want to retrieve.

PUT /api/index.php?endpoint=products/{id}

Update an existing product. Send only the fields you want to update. All fields are optional - only include the fields you wish to modify.

Request Body Fields:
Field Type Required Description
external_item_id string Optional External item identifier from source platform
sku string Optional Unique SKU code (stock keeping unit). Must be unique within tenant.
ean string Optional EAN/UPC barcode number
name string Optional Product name (max 255 characters)
description text Optional Detailed product description
weight decimal Optional Weight in grams (default: 0)
length decimal Optional Length in centimeters (default: 0)
width decimal Optional Width in centimeters (default: 0)
height decimal Optional Height in centimeters (default: 0)
min_stock integer Optional Minimum stock alert level (default: 0)
max_stock integer Optional Maximum stock capacity (default: 0)
manufacturer string Optional Manufacturer name
brand string Optional Brand name
country_of_origin string Optional Country of origin code
customs_tariff_number string Optional Customs tariff/harmonized system number
net_weight decimal Optional Net weight in grams (default: 0)
gross_weight decimal Optional Gross weight in grams (defaults to weight if not provided)
product_type integer Optional Product type identifier (default: 0)
exclude_from_picklist boolean Optional Whether to exclude product from picklists (default: 0/false)
einkaufs_preis decimal Optional Purchase price/cost price
external_ids array Optional Array of external ID objects. Each object must have platform (string, required) and external_id (string, required). Replaces all existing external IDs.
images array Optional Array of image objects. Each object must have image_url (string, required). Optional fields: external_id, thumbnail_url, is_primary (boolean), sort_order (integer). Replaces all existing images.
variations array Optional Array of variation objects. Each object must have attribute_name (string, required) and attribute_value (string, required). Optional: parent_product_id (integer). Replaces all existing variations.
components array Optional Array of component objects for bundle/set products. Each object must have component_product_id (integer, required). Optional: quantity (integer, default: 1). Replaces all existing components.
Example Request:
curl -X PUT "https://app.beeship.io/api/index.php?endpoint=products/123" \ -H "X-API-Key: your_api_key" \ -H "X-Email: user@company.com" \ -H "X-Password: password" \ -H "Content-Type: application/json" \ -d '{ "name": "Updated Product Name", "weight": 500, "min_stock": 10, "max_stock": 100, "einkaufs_preis": 25.99 }'
Example Response:
{ "success": true, "data": { "product_id": 123, "message": "Product updated successfully" }, "timestamp": "2025-11-03T14:00:00+01:00" }
Note: When updating arrays (external_ids, images, variations, components), the entire array is replaced. To add items, include all existing items plus the new ones.

GET /api/index.php?endpoint=products/{id}/stock

Returns the stock of a product per storage location, including batch number (Charge) and expiry date (MHD). total_stock is all available stock, sellable_stock is the stock your sales channels see (everything except Sperr-Lager locations).

Example Request:
curl -X GET "https://app.beeship.io/api/index.php?endpoint=products/1246/stock" \ -H "X-API-Key: your_api_key" \ -H "X-Email: user@company.com" \ -H "X-Password: password"
Example Response:
{ "success": true, "data": { "product_id": 1246, "sku": "CREAM-100", "total_stock": 85, "sellable_stock": 80, "locations": [ { "location_code": "A-03-12", "location_type": "picking", "quantity": 60, "batch_number": "L2510", "expiry_date": "2026-12-31", "status": "available" }, { "location_code": "B-01-04", "location_type": "nachschub", "quantity": 20, "batch_number": "L2511", "expiry_date": "2027-03-31", "status": "available" }, { "location_code": "SPERR-01", "location_type": "sperr", "quantity": 5, "batch_number": null, "expiry_date": null, "status": "available" } ] }, "timestamp": "2025-11-02T15:40:00+01:00" }

POST /api/index.php?endpoint=products/{id}/stock

Books stock for a product at a storage location: book in, book out, correct a quantity, clear a location or move stock to another location. Batch number (Charge) and expiry date (MHD) are supported for every booking. Each booking is written to the stock movement log (Bestandsprotokoll) and the new sellable stock is sent to the product's sales channel, exactly like a booking in the beeShip app.

Actions:
Action Description
add Books stock in at location. The location is created automatically if it does not exist yet.
subtract Books stock out at location. Without batch / expiry date, stock with the earliest expiry date is used first.
set Sets the quantity of one stock row (location + batch + expiry date) to quantity, e.g. after a stock count. 0 clears the row.
remove Books out all stock at location (only the given batch / expiry date, if provided).
transfer Moves quantity from location to to_location. Batch and expiry date move along.
Request Body Fields:
Field Type Required Description
action string Required add, subtract, set, remove or transfer
location string Required Storage location code (for transfer: the source location)
quantity integer Required Number of units, at least 1. For set the new quantity (0 allowed). Not used for remove.
to_location string Optional Target location code. Required for transfer; created automatically if it does not exist.
batch_number string Optional Batch number / Charge (max 50 characters)
expiry_date date Optional Expiry date / MHD in the format YYYY-MM-DD
location_type string Optional Type of location: picking, nachschub or sperr
to_location_type string Optional Type of to_location: picking, nachschub or sperr
reason string Optional Reason shown in the stock movement log (default API)
Example Request (book in with batch and expiry date):
curl -X POST "https://app.beeship.io/api/index.php?endpoint=products/1246/stock" \ -H "X-API-Key: your_api_key" \ -H "X-Email: user@company.com" \ -H "X-Password: password" \ -H "Content-Type: application/json" \ -d '{ "action": "add", "location": "A-03-12", "quantity": 50, "batch_number": "L2511", "expiry_date": "2027-03-31", "reason": "Wareneingang Lieferant 4711" }'
Example Response (Success):
{ "success": true, "data": { "action": "add", "location": "A-03-12", "batch_number": "L2511", "expiry_date": "2027-03-31", "changes": [ { "product_id": 1246, "sku": "CREAM-100", "qty_before": 0, "qty_after": 50 } ], "platform_updates": [ { "product_id": 1246, "sku": "CREAM-100", "platform": "billbee", "new_stock": 130, "result": { "success": true } } ] }, "timestamp": "2025-11-02T15:42:00+01:00" }
Example Request (move stock to another location):
curl -X POST "https://app.beeship.io/api/index.php?endpoint=products/1246/stock" \ -H "X-API-Key: your_api_key" \ -H "X-Email: user@company.com" \ -H "X-Password: password" \ -H "Content-Type: application/json" \ -d '{ "action": "transfer", "location": "B-01-04", "to_location": "A-03-12", "quantity": 20, "batch_number": "L2511", "expiry_date": "2027-03-31" }'
Important Notes:
  • Batch and expiry date identify a stock row together with the location. set and transfer use exactly the given combination (no batch = stock without batch).
  • Not enough stock: subtract and transfer are rejected with 409 if the location holds less than the requested quantity. Nothing is booked in that case.
  • Linked products: if the product shares its stock with other products (product mapping), add, subtract, set and remove are booked for all of them.
  • Sperr-Lager: bookings on a sperr location do not change the stock your sales channels see.
  • One booking per request. Every booking appears in the stock movement log with the user of the API key.

DELETE /api/index.php?endpoint=products/{id}

Permanently delete a product from the system.

Orders API

Manage customer orders, including creation, updates, and status tracking.

GET /api/index.php?endpoint=orders
Query Parameters:
Parameter Type Description
status string Filter by status: pending, processing, shipped, completed, cancelled
limit integer Items per page (default: 20, max: 100)

POST /api/index.php?endpoint=orders

Create a new customer order with full shipping details and line items.

Request Body Fields:
Field Type Required Description
order_number string Optional Your order number (auto-generated if not provided)
external_order_id string Optional Order ID from external system (Shopify, WooCommerce, etc.)
source_platform string Optional Source platform (shopify, woocommerce, manual, api, etc.)
customer object Required Customer information object
customer.name string Required Customer full name
customer.email string Required Customer email address
customer.phone string Optional Customer phone number
shipping_address object Required Shipping address object
shipping_address.name string Optional Recipient name (defaults to customer name)
shipping_address.street string Required Street name
shipping_address.house_number string Required House/building number
shipping_address.postal_code string Required Postal/ZIP code
shipping_address.city string Required City name
shipping_address.country string Required Country name
shipping_address.country_code string Required 2-letter country code (DE, US, GB, etc.)
billing_address object Optional Billing address (defaults to shipping address if not provided)
items array Required Array of order line items
items[].product_id integer Required Product ID from your products table
items[].quantity integer Required Quantity ordered
items[].price decimal Optional Override price (uses product price if not provided)
shipping_cost decimal Optional Shipping cost
tax_amount decimal Optional Tax amount
discount decimal Optional Discount amount
currency string Optional Currency code (default: EUR)
notes string Optional Internal notes
customer_comment string Optional Customer's comment/note
tags array Optional Array of tag strings (e.g., ["express", "gift", "vip"])
Example Request:
curl -X POST "https://app.beeship.io/api/index.php?endpoint=orders" \ -H "X-API-Key: your_api_key" \ -H "X-Email: user@company.com" \ -H "X-Password: password" \ -H "Content-Type: application/json" \ -d '{ "external_order_id": "SHOP-99999", "source_platform": "shopify", "customer": { "name": "Max Mustermann", "email": "max@example.com", "phone": "+49 40 98765432" }, "shipping_address": { "street": "Teststraße", "house_number": "42", "postal_code": "20095", "city": "Hamburg", "country": "Germany", "country_code": "DE" }, "items": [ { "product_id": 123, "quantity": 3, "price": 12.99 }, { "product_id": 456, "quantity": 1, "price": 24.99 } ], "shipping_cost": 5.99, "tax_amount": 8.59, "notes": "Urgent delivery", "tags": ["express", "vip"] }'
Example Response (Success):
{ "success": true, "data": { "order_id": 5156, "order_number": "ORD-2025-11-0156", "status": "pending", "total": 67.54, "message": "Order created successfully" }, "timestamp": "2025-11-02T16:00:00+01:00" }
Important Notes:
  • Product Validation: All product_ids must exist in your system
  • Stock Check: Products must have sufficient stock
  • Address Validation: Country code must be valid ISO 3166-1 alpha-2
  • Automatic Calculations: Total is calculated automatically if not provided
  • Order Status: New orders start with "pending" status

GET /api/index.php?endpoint=orders/{id}

PUT /api/index.php?endpoint=orders/{id}

Update an existing order. Send only the fields you want to update. All fields are optional - only include the fields you wish to modify. Note: source_platform is automatically set to 'api' for all API updates.

Request Body Fields:
Field Type Required Description
external_order_id string Optional External order identifier from source platform
source_platform string Optional Source platform identifier (automatically set to 'api' for API updates, regardless of input value)
shop_id integer Optional Shop/store identifier (defaults to tenant_id if not provided)
order_number string Optional Order number (must be unique within tenant)
order_date datetime Optional Order date and time (format: YYYY-MM-DD HH:MM:SS)
status string Optional Order status. Valid values: 'bestellt (ordered)', 'bestaetigt (confirmed)', 'bezahlt (paid)', 'versendet (shipped)', 'reklamation (complaint)', 'geloescht (deleted)', 'abgeschlossen (completed)', 'storniert (canceled)', 'archiviert (archived)', 'bewertet (reviewed)', 'gepackt (packed)', '1_mahnung (1st reminder)', '2_mahnung (2nd reminder)', 'angeboten (offered)', 'zahlungserinnerung (payment reminder)', 'im_fulfillment (in fulfillment)'. Triggers post-processing (shipping rules, tag rules, picking strategy) when changed.
total_amount decimal Optional Total order amount (default: 0)
currency string Optional Currency code (default: EUR)
shipping_provider_id integer Optional Shipping provider identifier
shipping_provider_product_id integer Optional Shipping provider product/service identifier
seller_comment text Optional Internal seller/merchant comments
customer_comments text Optional Customer comments/notes
shipping_cost decimal Optional Shipping cost amount
payment_terms string Optional Payment terms description
items array Optional Array of order item objects. Each item should have product_sku (string) or product_id (integer). Required fields: quantity (integer, default: 1). Optional fields: external_item_id, transaction_id, product_title, ean, unit_price, total_price, tax_amount, tax_index, is_component (boolean), parent_set_info, product_type. Replaces all existing items. Maximum 250 items per request.
addresses array Optional Array of address objects. Each address must have address_type (string, required). Optional fields: external_address_id, company, first_name, last_name, street, house_number, additional_info, postal_code, city, state, country, country_code, phone, email. Replaces all existing addresses.
tags array Optional Array of tag strings. Replaces all existing tags. Triggers tag rules and picking strategy when changed.
Example Request:
curl -X PUT "https://app.beeship.io/api/index.php?endpoint=orders/456" \ -H "X-API-Key: your_api_key" \ -H "X-Email: user@company.com" \ -H "X-Password: password" \ -H "Content-Type: application/json" \ -d '{ "status": "bezahlt (paid)", "total_amount": 99.99, "currency": "EUR", "tags": ["priority", "express"] }'
Example Response:
{ "success": true, "data": { "order_id": 456, "message": "Order updated successfully" }, "timestamp": "2025-11-03T14:00:00+01:00" }
Note: When updating arrays (items, addresses, tags), the entire array is replaced. To add items, include all existing items plus the new ones. Updating status or tags triggers automatic post-processing (shipping rules, tag rules, picking strategy).

DELETE /api/index.php?endpoint=orders/{id}

Picklists API

Manage picklist templates for warehouse picking operations. The picklists these templates create are in the Active Picklists API.

GET /api/index.php?endpoint=picklists

POST /api/index.php?endpoint=picklists

Create a new picklist template for warehouse picking operations. Picklist templates define how orders are grouped and processed for picking.

Request Body Fields:
Field Type Required Description
name string Required Picklist template name
tag string Required Unique tag identifier for this picklist template. Must be unique within tenant. Used to match orders to this picklist.
picking_type string Required Type of picking method. Valid values: 'rollende kommissionierung' (rolling picking), 'sammelkommissionierung' (batch picking), 'ausdruckbare pickliste' (printable picklist)
max_orders_per_list integer Required Maximum number of orders that can be assigned to a single picklist
description string Optional Description of the picklist template
warehouse_id integer Optional Warehouse identifier (default: 1)
sorting_method string Optional Method for sorting orders in the picklist. Valid values: 'order_date', 'priority', 'shipping_method', 'custom' (default: 'order_date')
batch_size integer Optional Batch size for processing (default: 0)
auto_assign boolean Optional Whether to automatically assign orders to this picklist (default: 0/false)
require_confirmation boolean Optional Whether confirmation is required before processing (default: 0/false)
print_labels boolean Optional Whether to print labels for items (default: 1/true)
consolidate_items boolean Optional Whether to consolidate items from multiple orders (default: 0/false)
priority integer Optional Priority level for picklist assignment (lower numbers = higher priority). Must be unique within picking type. Ignored for 'ausdruckbare pickliste' type (automatically set to 0). Valid only for 'rollende kommissionierung' and 'sammelkommissionierung' types.
show_artikel_barcodes boolean Optional Whether to show product/article barcodes (default: 1/true)
show_auftrag_barcodes boolean Optional Whether to show order barcodes (default: 1/true)
is_active boolean Optional Whether the picklist template is active (default: 1/true)
visible_users array Optional Array of user IDs (integers) who can see this picklist template. If not provided, template is visible to all users.
Example Request:
curl -X POST "https://app.beeship.io/api/index.php?endpoint=picklists" \ -H "X-API-Key: your_api_key" \ -H "X-Email: user@company.com" \ -H "X-Password: password" \ -H "Content-Type: application/json" \ -d '{ "name": "Express Picking", "tag": "express", "picking_type": "rollende kommissionierung", "max_orders_per_list": 10, "priority": 1, "sorting_method": "priority", "auto_assign": true, "print_labels": true }'
Example Response:
{ "success": true, "data": { "template_id": 5, "message": "Picklist template created successfully" }, "timestamp": "2025-11-03T14:00:00+01:00" }
Important: The tag field must be unique within your tenant. This tag is used to match orders to picklist templates. The priority field must be unique within the same picking type (for 'rollende kommissionierung' and 'sammelkommissionierung' only). For 'ausdruckbare pickliste' type, priority is automatically set to 0.

Active Picklists API

The real picklists in your warehouse – the lists the templates above produce. See status, orders, items, trolleys and the pick progress (what is picked and what is still open), and change or delete lists. This is the data behind the picklist dashboard and the printable picklists in beeShip.

Stock: Picking does not book stock. Quantities picked here are only recorded; the stock is booked at the packing station (Packtisch) as usual.
Safety: Deleting a picklist or removing an order from it is refused with 409 when goods are already picked or the list is running/completed – add &force=1 to do it anyway (picked goods must then be put back by hand). Access tokens with the scope write:single can use PATCH but no DELETE.

GET /api/index.php?endpoint=active-picklists

Returns picklists with their progress. Without status only active picklists (draft and in progress) are returned, sorted like the dashboard: running first, then drafts, then completed; newest first.

Query Parameters:
Parameter Type Required Description
status string Optional active (default), all, or a comma list of draft, in_progress, completed
picking_type string Optional ausdruckbare pickliste, rollende kommissionierung, sammelkommissionierung or zweistufige kommissionierung
template_id integer Optional Only picklists of this template
warehouse_id integer Optional Only picklists of this warehouse
assigned_user_id integer Optional Only picklists assigned to this user
is_printed boolean Optional Printed or not printed picklists
tag string Optional Picklists containing an order with this tag
cart_id string Optional Picklists on this trolley, or none for picklists without a trolley
has_shipped_orders boolean Optional Picklists with (or without) shipped orders
order_id integer Optional Picklists containing this order
external_order_id string Optional Picklists containing this order (ID from the sales channel)
created_from date Optional Created on or after (YYYY-MM-DD or date-time)
created_to date Optional Created on or before (YYYY-MM-DD = whole day)
page integer Optional Page number (default: 1)
limit integer Optional Items per page (default: 20, max: 250)
Example Request:
curl -X GET "https://app.beeship.io/api/index.php?endpoint=active-picklists&status=active&limit=20" \ -H "X-API-Key: your_api_key" \ -H "X-Email: user@company.com" \ -H "X-Password: password"
Example Response:
{ "success": true, "data": { "picklists": [ { "picklist_id": 18452, "status": "in_progress", "template": { "template_id": 12, "name": "Express", "picking_type": "sammelkommissionierung", "template_type": "normal" }, "warehouse": { "warehouse_id": 1, "name": "Hauptlager" }, "assigned_user": { "user_id": 7, "username": "Lena" }, "is_printed": false, "order_count": 3, "shipped_order_count": 0, "open_order_count": 3, "item_lines": 5, "lines_picked": 2, "lines_open": 3, "quantity_required": 10, "quantity_picked": 4, "quantity_open": 6, "pick_progress_pct": 40, "tags": ["express"], "carts": [ { "cart_id": 31, "cart_number": "W-07", "cart_type": "sammelkommissionierung", "status": "active", "assigned_at": "2025-11-03 08:41:12" } ], "created_at": "2025-11-03 08:30:05", "started_at": "2025-11-03 08:41:12", "completed_at": null, "updated_at": "2025-11-03 08:41:12", "first_label_at": null, "last_label_at": null } ], "pagination": { "page": 1, "limit": 20, "total_count": 1, "total_pages": 1 } }, "timestamp": "2025-11-03T09:15:00+01:00" }

GET /api/index.php?endpoint=active-picklists/stats

Counts your picklists per status and per picking type.

Example Request:
curl -X GET "https://app.beeship.io/api/index.php?endpoint=active-picklists/stats" \ -H "X-API-Key: your_api_key" \ -H "X-Email: user@company.com" \ -H "X-Password: password"
Example Response:
{ "success": true, "data": { "active": 4, "by_status": { "draft": 0, "in_progress": 4, "completed": 11, "cancelled": 0 }, "by_picking_type": { "sammelkommissionierung": { "in_progress": 4, "completed": 11 } } }, "timestamp": "2025-11-03T09:15:00+01:00" }

GET /api/index.php?endpoint=active-picklists/{id}

Returns one picklist including its progress, all orders and all items (lines). orders and items are shortened in this example – each entry looks like the ones under "Get Orders" and "Get Items".

Example Request:
curl -X GET "https://app.beeship.io/api/index.php?endpoint=active-picklists/18452" \ -H "X-API-Key: your_api_key" \ -H "X-Email: user@company.com" \ -H "X-Password: password"
Example Response:
{ "success": true, "data": { "picklist_id": 18452, "status": "in_progress", "template": { "template_id": 12, "name": "Express", "picking_type": "sammelkommissionierung", "template_type": "normal" }, "warehouse": { "warehouse_id": 1, "name": "Hauptlager" }, "assigned_user": { "user_id": 7, "username": "Lena" }, "is_printed": false, "order_count": 3, "shipped_order_count": 0, "open_order_count": 3, "item_lines": 5, "lines_picked": 2, "lines_open": 3, "quantity_required": 10, "quantity_picked": 4, "quantity_open": 6, "pick_progress_pct": 40, "tags": ["express"], "carts": [ { "cart_id": 31, "cart_number": "W-07", "cart_type": "sammelkommissionierung", "status": "active", "assigned_at": "2025-11-03 08:41:12" } ], "created_at": "2025-11-03 08:30:05", "started_at": "2025-11-03 08:41:12", "completed_at": null, "updated_at": "2025-11-03 08:41:12", "first_label_at": null, "last_label_at": null, "progress": { "lines": { "total": 5, "picked": 2, "partially_picked": 1, "open": 2 }, "quantities": { "required": 10, "picked": 4, "open": 6 }, "orders": { "total": 3, "fully_picked": 1, "partially_picked": 1, "not_started": 1, "shipped": 0 }, "pick_progress_pct": 40, "is_fully_picked": false, "open_items": [ { "picklist_item_id": 902117, "order_id": 551203, "sku": "CREAM-100", "name": "Handcreme 100 ml", "quantity_open": 1 }, { "picklist_item_id": 902119, "order_id": 551204, "sku": "SOAP-250", "name": "Seife 250 g", "quantity_open": 3 } ] }, "orders": [ { "order_id": 551202, "external_order_id": "4156", "order_number": "4156", "order_date": "2025-11-03 07:12:44", "status": "bezahlt (paid)", "priority": 0, "source_platform": "shopify", "shipping_method": null, "sort_order": 0, "tags": ["express"], "quantity_required": 2, "quantity_picked": 2, "quantity_open": 0, "pick_state": "picked", "is_shipped": false, "tracking_number": null, "label_created_at": null } ], "items": [ { "picklist_item_id": 902116, "order_id": 551202, "external_order_id": "4156", "product_id": 1246, "sku": "CREAM-100", "ean": "4260123456789", "name": "Handcreme 100 ml", "quantity_required": 2, "quantity_picked": 2, "quantity_open": 0, "is_picked": true, "location_picked": { "location_id": 3405, "location_code": "A-03-12" }, "picked_by": "Lena", "picked_at": "2025-11-03 08:44:51" } ] }, "timestamp": "2025-11-03T09:15:00+01:00" }

GET /api/index.php?endpoint=active-picklists/{id}/progress

Where is the picklist? Lines, quantities and orders split into picked, partially picked and open, plus every line that still has to be picked.

Example Request:
curl -X GET "https://app.beeship.io/api/index.php?endpoint=active-picklists/18452/progress" \ -H "X-API-Key: your_api_key" \ -H "X-Email: user@company.com" \ -H "X-Password: password"
Example Response:
{ "success": true, "data": { "picklist_id": 18452, "status": "in_progress", "lines": { "total": 5, "picked": 2, "partially_picked": 1, "open": 2 }, "quantities": { "required": 10, "picked": 4, "open": 6 }, "orders": { "total": 3, "fully_picked": 1, "partially_picked": 1, "not_started": 1, "shipped": 0 }, "pick_progress_pct": 40, "is_fully_picked": false, "open_items": [ { "picklist_item_id": 902117, "order_id": 551203, "sku": "CREAM-100", "name": "Handcreme 100 ml", "quantity_open": 1 }, { "picklist_item_id": 902119, "order_id": 551204, "sku": "SOAP-250", "name": "Seife 250 g", "quantity_open": 3 } ] }, "timestamp": "2025-11-03T09:15:00+01:00" }

GET /api/index.php?endpoint=active-picklists/{id}/orders

The orders on the picklist in picking order, with their pick state (open, partially_picked, picked), tags and shipping label.

Example Request:
curl -X GET "https://app.beeship.io/api/index.php?endpoint=active-picklists/18452/orders" \ -H "X-API-Key: your_api_key" \ -H "X-Email: user@company.com" \ -H "X-Password: password"
Example Response:
{ "success": true, "data": { "picklist_id": 18452, "orders": [ { "order_id": 551202, "external_order_id": "4156", "order_number": "4156", "order_date": "2025-11-03 07:12:44", "status": "bezahlt (paid)", "priority": 0, "source_platform": "shopify", "shipping_method": null, "sort_order": 0, "tags": ["express"], "quantity_required": 2, "quantity_picked": 2, "quantity_open": 0, "pick_state": "picked", "is_shipped": false, "tracking_number": null, "label_created_at": null } ] }, "timestamp": "2025-11-03T09:15:00+01:00" }

GET /api/index.php?endpoint=active-picklists/{id}/items

Every line of the picklist: product, required, picked and open quantity, the storage location it was picked from and who picked it. Use picklist_item_id to change the picked quantity.

Example Request:
curl -X GET "https://app.beeship.io/api/index.php?endpoint=active-picklists/18452/items" \ -H "X-API-Key: your_api_key" \ -H "X-Email: user@company.com" \ -H "X-Password: password"
Example Response:
{ "success": true, "data": { "picklist_id": 18452, "items": [ { "picklist_item_id": 902116, "order_id": 551202, "external_order_id": "4156", "product_id": 1246, "sku": "CREAM-100", "ean": "4260123456789", "name": "Handcreme 100 ml", "quantity_required": 2, "quantity_picked": 2, "quantity_open": 0, "is_picked": true, "location_picked": { "location_id": 3405, "location_code": "A-03-12" }, "picked_by": "Lena", "picked_at": "2025-11-03 08:44:51" } ] }, "timestamp": "2025-11-03T09:15:00+01:00" }

PATCH /api/index.php?endpoint=active-picklists/{id}

Changes the status, the assigned picker or the printed flag. Setting the status to completed runs the same steps as finishing the list in beeShip (history, orders to "im Fulfillment", trolleys released). The response is the updated picklist, like "Get Picklist".

Request Body:
Parameter Type Required Description
status string Optional draft, in_progress or completed
assigned_user_id integer|null Optional beeShip user who picks the list; null removes the assignment
is_printed boolean Optional Mark the list as printed or not printed
Rules: A completed picklist cannot be re-opened. A picklist with picked goods cannot go back to draft. The status cancelled is not used – delete the picklist instead.
Example Request:
curl -X PATCH "https://app.beeship.io/api/index.php?endpoint=active-picklists/18452" \ -H "X-API-Key: your_api_key" \ -H "X-Email: user@company.com" \ -H "X-Password: password" \ -H "Content-Type: application/json" \ -d '{"status": "completed"}'

DELETE /api/index.php?endpoint=active-picklists/{id}

Deletes the picklist with the same cleanup as the picklist dashboard. Its orders become free and can be assigned to a new picklist. Draft picklists without picked goods are deleted directly; everything else needs &force=1.

Query Parameters:
Parameter Type Required Description
force boolean Optional 1 = also delete running/completed lists or lists with picked goods
Example Request:
curl -X DELETE "https://app.beeship.io/api/index.php?endpoint=active-picklists/18452&force=1" \ -H "X-API-Key: your_api_key" \ -H "X-Email: user@company.com" \ -H "X-Password: password"
Example Response:
{ "success": true, "data": { "picklist_id": 18452, "deleted": true, "orders_released": 3, "items_deleted": 5 }, "timestamp": "2025-11-03T09:15:00+01:00" }
Example Response without force (409):
{ "success": false, "error": { "code": 409, "message": "Picklist is 'in_progress' with 4 picked unit(s) – send ?force=1 to delete it anyway (picked goods must be put back by hand)." }, "timestamp": "2025-11-03T09:15:00+01:00" }

PATCH /api/index.php?endpoint=active-picklists/{id}/orders/{order_id}

Moves an order up or down on the picklist (lower sort_order comes first). Returns the orders in their new order.

Request Body:
Parameter Type Required Description
sort_order integer Required New position of the order
Example Request:
curl -X PATCH "https://app.beeship.io/api/index.php?endpoint=active-picklists/18452/orders/551204" \ -H "X-API-Key: your_api_key" \ -H "X-Email: user@company.com" \ -H "X-Password: password" \ -H "Content-Type: application/json" \ -d '{"sort_order": -1}'

DELETE /api/index.php?endpoint=active-picklists/{id}/orders/{order_id}

Takes one order off the picklist; the order becomes free again. If it was the last order, the picklist is deleted automatically (picklist_deleted: true). An order with picked goods or a completed list needs &force=1.

Query Parameters:
Parameter Type Required Description
force boolean Optional 1 = remove even with picked goods or on a completed list
Example Request:
curl -X DELETE "https://app.beeship.io/api/index.php?endpoint=active-picklists/18452/orders/551204" \ -H "X-API-Key: your_api_key" \ -H "X-Email: user@company.com" \ -H "X-Password: password"
Example Response:
{ "success": true, "data": { "picklist_id": 18452, "order_id": 551204, "removed": true, "items_removed": 2, "picklist_deleted": false }, "timestamp": "2025-11-03T09:15:00+01:00" }

PATCH /api/index.php?endpoint=active-picklists/{id}/items/{picklist_item_id}

Sets the picked quantity of one line (0 up to the required quantity). No stock is booked. Lowering the quantity also lowers the recorded pick locations, so the packing station never books more than was picked. Not possible on a completed picklist.

Request Body:
Parameter Type Required Description
quantity_picked integer Required New picked quantity, 0 … quantity_required
Example Request:
curl -X PATCH "https://app.beeship.io/api/index.php?endpoint=active-picklists/18452/items/902117" \ -H "X-API-Key: your_api_key" \ -H "X-Email: user@company.com" \ -H "X-Password: password" \ -H "Content-Type: application/json" \ -d '{"quantity_picked": 1}'
Example Response:
{ "success": true, "data": { "picklist_id": 18452, "item": { "picklist_item_id": 902117, "order_id": 551202, "external_order_id": "4156", "product_id": 1246, "sku": "CREAM-100", "ean": "4260123456789", "name": "Handcreme 100 ml", "quantity_required": 2, "quantity_picked": 1, "quantity_open": 1, "is_picked": false, "location_picked": { "location_id": 3405, "location_code": "A-03-12" }, "picked_by": "Lena", "picked_at": "2025-11-03 08:44:51" }, "progress": { "lines": { "total": 5, "picked": 2, "partially_picked": 1, "open": 2 }, "quantities": { "required": 10, "picked": 4, "open": 6 }, "orders": { "total": 3, "fully_picked": 1, "partially_picked": 1, "not_started": 1, "shipped": 0 }, "pick_progress_pct": 40, "is_fully_picked": false } }, "timestamp": "2025-11-03T09:15:00+01:00" }

Suppliers API

Manage suppliers (vendors/manufacturers) with full contact and address information.

GET /api/index.php?endpoint=suppliers

POST /api/index.php?endpoint=suppliers

Create a new supplier (vendor) in the system.

Request Body Fields:
Field Type Required Description
name string Required Supplier company name
contact_person string Optional Primary contact person name
email string Optional Supplier email address
phone string Optional Supplier phone number
website string Optional Supplier website URL
street string Optional Street name
house_number string Optional House/building number
postal_code string Optional Postal/ZIP code
city string Optional City name
country string Optional Country name
country_code string Optional 2-letter country code (DE, US, etc.)
tax_id string Optional Tax ID / VAT number
notes text Optional Internal notes about the supplier
Example Request:
curl -X POST "https://app.beeship.io/api/index.php?endpoint=suppliers" \ -H "X-API-Key: your_api_key" \ -H "X-Email: user@company.com" \ -H "X-Password: password" \ -H "Content-Type: application/json" \ -d '{ "name": "Global Wholesale GmbH", "contact_person": "Hans Schmidt", "email": "info@globalwholesale.de", "phone": "+49 30 12345678", "website": "https://globalwholesale.de", "street": "Industriestraße", "house_number": "123", "postal_code": "10115", "city": "Berlin", "country": "Germany", "country_code": "DE", "tax_id": "DE123456789", "notes": "Preferred supplier for electronics" }'
Example Response (Success):
{ "success": true, "data": { "supplier_id": 42, "message": "Supplier created successfully" }, "timestamp": "2025-11-02T16:30:00+01:00" }
Note:
  • Only the name field is required to create a supplier
  • All other fields are optional but recommended for complete supplier records
  • Suppliers with existing orders cannot be deleted, only deactivated

Vendor Orders API

Manage purchase orders (vendor orders) from suppliers for inventory replenishment.

GET /api/index.php?endpoint=vendor-orders
Query Parameters:
Parameter Type Required Description
page integer Optional Page number (default: 1)
limit integer Optional Items per page (default: 20, max: 250)
status string Optional Filter by status (pending, ordered, received, cancelled)
supplier_id integer Optional Filter by supplier ID
Example Request:
curl -X GET "https://app.beeship.io/api/index.php?endpoint=vendor-orders&limit=10" \ -H "X-API-Key: your_api_key" \ -H "X-Email: user@company.com" \ -H "X-Password: password"
Example Response:
{ "success": true, "data": { "vendor_orders": [ { "vendor_order_id": 101, "order_number": "PO-2025-001", "supplier_id": 5, "supplier_name": "Global Wholesale GmbH", "status": "pending", "order_date": "2025-11-01", "expected_delivery": "2025-11-15", "total_amount": 1250.00, "currency": "EUR" } ], "pagination": { "total_count": 45 } } }

GET /api/index.php?endpoint=vendor-orders/{id}

Retrieve detailed information about a specific vendor order including all line items.

Example Request:
curl -X GET "https://app.beeship.io/api/index.php?endpoint=vendor-orders/101" \ -H "X-API-Key: your_api_key" \ -H "X-Email: user@company.com" \ -H "X-Password: password"
Example Response:
{ "success": true, "data": { "vendor_order_id": 101, "order_number": "PO-2025-001", "supplier": { "supplier_id": 5, "name": "Global Wholesale GmbH", "email": "orders@globalwholesale.de" }, "status": "pending", "order_date": "2025-11-01", "expected_delivery": "2025-11-15", "items": [ { "product_id": 123, "sku": "SOAP-001", "product_name": "Luxury Hand Soap", "quantity_ordered": 100, "quantity_received": 0, "unit_price": 6.50 } ], "total_amount": 1250.00, "currency": "EUR", "notes": "Urgent restocking order" } }

POST /api/index.php?endpoint=vendor-orders

Create a new purchase order to order inventory from a supplier.

Request Body Fields:
Field Type Required Description
supplier_id integer Required ID of the supplier
order_number string Optional Custom order number (auto-generated if not provided)
order_date date Optional Order date (YYYY-MM-DD, defaults to today)
expected_delivery date Optional Expected delivery date (YYYY-MM-DD)
items array Required Array of order line items
items[].product_id integer Required Product ID to order
items[].quantity integer Required Quantity to order
items[].unit_price decimal Optional Purchase price per unit
currency string Optional Currency code (default: EUR)
notes text Optional Internal notes for the order
Example Request:
curl -X POST "https://app.beeship.io/api/index.php?endpoint=vendor-orders" \ -H "X-API-Key: your_api_key" \ -H "X-Email: user@company.com" \ -H "X-Password: password" \ -H "Content-Type: application/json" \ -d '{ "supplier_id": 5, "expected_delivery": "2025-11-20", "items": [ { "product_id": 123, "quantity": 200, "unit_price": 6.50 }, { "product_id": 456, "quantity": 150, "unit_price": 12.00 } ], "notes": "Urgent restocking for winter season" }'
Example Response (Success):
{ "success": true, "data": { "vendor_order_id": 102, "order_number": "PO-2025-002", "message": "Vendor order created successfully" }, "timestamp": "2025-11-03T12:00:00+01:00" }
Important Notes:
  • Supplier Validation: The supplier_id must exist in your system
  • Product Validation: All product_ids must exist in your inventory
  • Automatic Numbering: Order numbers are auto-generated if not provided
  • Status Flow: New orders start with "pending" status

PUT /api/index.php?endpoint=vendor-orders/{id}

Update an existing vendor order. Send only the fields you want to update. All fields are optional - only include the fields you wish to modify.

Request Body Fields:
Field Type Required Description
status string Optional Vendor order status. Common values: 'pending', 'ordered', 'confirmed', 'in_transit', 'received', 'cancelled', 'completed'
expected_delivery date Optional Expected delivery date (format: YYYY-MM-DD)
notes text Optional Internal notes or comments about the vendor order
supplier_id integer Optional Supplier/vendor identifier (must exist in system)
order_number string Optional Purchase order number (must be unique within tenant)
order_date date Optional Order date (format: YYYY-MM-DD)
items array Optional Array of order item objects. Each item should have product_id (integer, required), quantity (integer, required), and unit_price (decimal, optional). Replaces all existing items.
Example Request:
curl -X PUT "https://app.beeship.io/api/index.php?endpoint=vendor-orders/102" \ -H "X-API-Key: your_api_key" \ -H "X-Email: user@company.com" \ -H "X-Password: password" \ -H "Content-Type: application/json" \ -d '{ "status": "ordered", "expected_delivery": "2025-11-18", "notes": "Confirmed with supplier - earlier delivery" }'
Example Response:
{ "success": true, "data": { "vendor_order_id": 102, "message": "Vendor order updated successfully" }, "timestamp": "2025-11-03T14:00:00+01:00" }
Note: When updating the items array, the entire array is replaced. To add items, include all existing items plus the new ones.
Status Values:
  • pending: Order created but not yet sent to supplier
  • ordered: Order has been placed with supplier
  • received: Order has been received and processed
  • cancelled: Order was cancelled

DELETE /api/index.php?endpoint=vendor-orders/{id}

Delete a vendor order from the system. Only orders with "pending" status can be deleted.

Example Request:
curl -X DELETE "https://app.beeship.io/api/index.php?endpoint=vendor-orders/102" \ -H "X-API-Key: your_api_key" \ -H "X-Email: user@company.com" \ -H "X-Password: password"
Example Response:
{ "success": true, "data": { "message": "Vendor order deleted successfully" }, "timestamp": "2025-11-03T15:00:00+01:00" }

Note: Orders that have been placed (status: ordered or received) cannot be deleted. Use the status update endpoint to cancel them instead.

Returns API

Manage customer returns (Retouren) — covers everything done by the desktop returns.php and mobile mobile_returns.php pages: create returns from a known order or unknown package, scan/inspect items, transition status, upload photos, restock to warehouse locations, record refunds, and read the full audit history.

URL & sub-resources

All routes are tenant-scoped (via auth headers) and live under the returns endpoint. Sub-resources use PATH_INFO, exactly like the Orders API:

  • GET /api/index.php/{return_id}?endpoint=returns
  • GET /api/index.php/{return_id}/items?endpoint=returns
  • PATCH /api/index.php/{return_id}/status?endpoint=returns
  • POST /api/index.php/{return_id}/restock?endpoint=returns
  • POST /api/index.php/{return_id}/refund?endpoint=returns
  • GET /api/index.php/search?endpoint=returns&q=...
  • GET /api/index.php/reasons?endpoint=returns
  • GET /api/index.php/conditions?endpoint=returns

Status enum: pending, received, inspecting, approved, rejected, processing, completed, cancelled
Return type: customer_initiated, manual, system
Refund method: original_payment, store_credit, exchange, none
File category: photo, document, inspection, damage, other

GET /api/index.php?endpoint=returns

Returns a paginated list of returns for the authenticated tenant, with an embedded reason name and aggregate item counts per return.

Query Parameters
ParamTypeDescription
pageintPage number (default 1)
limitintItems per page, max 250 (default 25)
statusstringSingle status or comma-separated list (e.g. received,inspecting)
return_typestringOne of customer_initiated, manual, system
order_idintFilter by original order ID
external_order_idstringFilter by external (platform) order ID
tracking_numberstringExact match on tracking number
return_numberstringPartial match on return number
assigned_tointFilter by assigned user_id
warehouse_idintFilter by warehouse
date_from / date_todatetimeFilter on created_at (ISO format)
qstringFree-text search across number, tracking, email, name, external order ID
sortstringcreated_at | updated_at | status | return_number | received_at
dirstringasc | desc (default desc)
curl -X GET "https://app.beeship.io/api/index.php?endpoint=returns&status=received,inspecting&limit=20" \ -H "X-API-Key: YOUR_API_KEY" \ -H "X-Email: your@email.com" \ -H "X-Password: YOUR_PASSWORD"

GET /api/index.php/{return_id}?endpoint=returns

Returns the full return record, joined with its reason, plus arrays of items, files, and the most recent 50 history entries.

curl "https://app.beeship.io/api/index.php/123?endpoint=returns" \ -H "X-API-Key: ..." -H "X-Email: ..." -H "X-Password: ..."

POST /api/index.php?endpoint=returns

Creates a return. Pass order_id for a known-order return, or set unknown: true for a package that arrived without prior context (status defaults to received). For known returns the API validates each item against the order's quantities and any prior non-cancelled returns to prevent over-returning.

Request Body
FieldTypeRequiredDescription
order_idintRequired (known)ID of the original order in this tenant
unknownboolOptionalIf true, no order_id needed; status auto-set to received
return_typestringOptionalDefault manual
statusstringOptionalDefault pending (or received for unknown)
return_numberstringOptionalAuto-generated (RET-YYYY-NNNNNN) if omitted
tracking_numberstringOptionalTracking number of incoming package
return_reason_idintOptionalMust belong to this tenant
custom_reasontextOptionalFree-text reason if not using predefined
customer_name / customer_emailstringOptionalCustomer info for notifications
shipping_address_id / billing_address_idintOptionalReferences to order_addresses
notes / customer_notestextOptionalInternal / customer-provided notes
assigned_to / warehouse_idintOptionalAssignee and warehouse
items[]arrayRequired (known)See item fields below
Item Fields
FieldTypeDescription
order_item_idintFK to order_items.item_id
product_id / product_sku / product_name / eanmixedSnapshot of product info
quantity_returnedintRequired, > 0; cannot exceed remaining quantity on the order
quantity_received / quantity_approvedintOptional initial inspection counts
condition_idintFK to return_conditions
unit_price / refund_amountdecimalOptional pricing
restock_location_idintOptional pre-assigned storage location
curl -X POST "https://app.beeship.io/api/index.php?endpoint=returns" \ -H "X-API-Key: ..." -H "X-Email: ..." -H "X-Password: ..." \ -H "Content-Type: application/json" \ -d '{ "order_id": 456, "return_reason_id": 3, "tracking_number": "DHL-9912345", "customer_email": "buyer@example.com", "items": [ { "order_item_id": 9001, "product_sku": "SKU-A", "quantity_returned": 2 }, { "order_item_id": 9002, "product_sku": "SKU-B", "quantity_returned": 1, "condition_id": 4 } ] }'

Response 201: { return_id, return_number, status, message }

PATCH /api/index.php/{return_id}?endpoint=returns

Updates mutable fields on the return. Cannot change status here — use the dedicated status endpoint so transitions are timestamped and logged.

Updatable: return_number, tracking_number, return_reason_id, custom_reason, customer_email, customer_name, shipping_address_id, billing_address_id, notes, customer_notes, assigned_to, warehouse_id, refund_amount, refund_method.

DELETE /api/index.php/{return_id}?endpoint=returns

Soft-cancels the return (sets status to cancelled). Returns already in completed status are rejected with HTTP 409. Optional JSON body: { "notes": "..." }.

PATCH /api/index.php/{return_id}/status?endpoint=returns

Transitions the return status, automatically stamps the matching timestamp column (received_at, inspected_at, approved_at, rejected_at, completed_at) and writes a row to return_history.

curl -X PATCH "https://app.beeship.io/api/index.php/123/status?endpoint=returns" \ -H "X-API-Key: ..." -H "X-Email: ..." -H "X-Password: ..." \ -H "Content-Type: application/json" \ -d '{ "status": "approved", "notes": "Inspection passed" }'

GET /api/index.php/{return_id}/items?endpoint=returns

Returns items with their condition info joined in (condition_name, condition_code, can_restock).

POST /api/index.php/{return_id}/items?endpoint=returns

Appends items to an existing return — primarily used to assign products to an unknown package once it has been inspected. If the return is linked to an order, the same over-return validation is applied (taking already-added items on this same return into account).

{ "items": [ { "order_item_id": 9003, "quantity_returned": 1, "condition_id": 2 } ] }

PATCH /api/index.php/{return_id}/items/{item_id}?endpoint=returns

Updates inspection-related fields on a single item.

Updatable: quantity_received, quantity_approved, quantity_rejected, condition_id, condition_notes, inspection_notes, unit_price, refund_amount, restock_location_id.

DELETE /api/index.php/{return_id}/items/{item_id}?endpoint=returns

Removes a return item. Blocked (HTTP 409) when the return status is processing or completed.

POST /api/index.php/{return_id}/restock?endpoint=returns

Marks an inspected item as restocked at a warehouse location. Verifies the location belongs to the tenant and that quantity does not exceed quantity_returned.

{ "return_item_id": 8801, "location_id": 42, "quantity": 1 }

POST /api/index.php/{return_id}/refund?endpoint=returns

Marks the return as refunded (sets refund_processed = 1, stamps refund_processed_at) and logs a refunded history entry.

{ "refund_amount": 24.90, "refund_method": "original_payment" }

GET /api/index.php/{return_id}/files?endpoint=returns

Lists all active files/photos/documents attached to the return.

POST /api/index.php/{return_id}/files?endpoint=returns

Accepts two modes:

  1. Multipart upload — send a file part plus optional file_category, return_item_id, ftp_server_id, description form fields. The server stores the file under uploads/returns/{tenant_id}/.
  2. Pre-uploaded FTP file — JSON body with file_path, file_name, file_size, file_type, mime_type, ftp_server_id. Use this when the mobile app already pushed the file to an FTP server.
curl -X POST "https://app.beeship.io/api/index.php/123/files?endpoint=returns" \ -H "X-API-Key: ..." -H "X-Email: ..." -H "X-Password: ..." \ -F "file=@damage.jpg" \ -F "file_category=damage" \ -F "return_item_id=8801"

DELETE /api/index.php/{return_id}/files/{file_id}?endpoint=returns

Soft-deletes the file (sets is_active = 0).

GET /api/index.php/{return_id}/history?endpoint=returns

Returns up to limit (default 100, max 500) history rows, newest first, with the username of the actor. metadata is decoded JSON.

GET /api/index.php/reasons?endpoint=returns
POST /api/index.php/reasons?endpoint=returns

List or create configurable return reasons for this tenant. POST requires reason_code and reason_name; optional flags: requires_approval, auto_approve, requires_inspection, allow_partial_return, refund_percentage, sort_order, description.

GET /api/index.php/conditions?endpoint=returns

List configured item conditions (e.g. Wie Neu, Beschädigt) used in item inspections.

Notes
  • Every state-changing call writes a row to return_history (action + previous/new status + user_id + optional JSON metadata).
  • All foreign IDs (return_reason_id, condition_id, location_id, order_id) are verified against the authenticated tenant.
  • Over-return prevention sums quantity_returned across all prior non-cancelled returns for the same order before allowing new items.
  • Status transitions automatically stamp the matching timestamp column on returns (received_at, inspected_at, …).

Code Examples

<?php class BeeShipAPIClient { private $apiKey; private $email; private $password; private $baseUrl = 'https://app.beeship.io/api/index.php'; public function __construct($apiKey, $email, $password) { $this->apiKey = $apiKey; $this->email = $email; $this->password = $password; } public function request($method, $endpoint, $data = null) { $url = $this->baseUrl . '?endpoint=' . $endpoint; $ch = curl_init($url); $headers = [ 'Content-Type: application/json', 'X-API-Key: ' . $this->apiKey, 'X-Email: ' . $this->email, 'X-Password: ' . $this->password ]; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); if ($method === 'POST') { curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data)); } $response = curl_exec($ch); curl_close($ch); return json_decode($response, true); } public function getProducts($limit = 20) { return $this->request('GET', 'products&limit=' . $limit); } } // Usage $client = new BeeShipAPIClient('your_api_key', 'user@company.com', 'password'); $products = $client->getProducts(10); ?>
import requests class BeeShipAPI: def __init__(self, api_key, email, password): self.api_key = api_key self.email = email self.password = password self.base_url = 'https://app.beeship.io/api/index.php' def _headers(self): return { 'Content-Type': 'application/json', 'X-API-Key': self.api_key, 'X-Email': self.email, 'X-Password': self.password } def request(self, method, endpoint, data=None): url = f"{self.base_url}?endpoint={endpoint}" response = requests.request( method=method, url=url, headers=self._headers(), json=data ) return response.json() def get_products(self, limit=20): return self.request('GET', f'products&limit={limit}') # Usage client = BeeShipAPI('your_api_key', 'user@company.com', 'password') products = client.get_products(10)
class BeeShipAPI { constructor(apiKey, email, password) { this.apiKey = apiKey; this.email = email; this.password = password; this.baseUrl = 'https://app.beeship.io/api/index.php'; } async request(method, endpoint, data = null) { const url = `${this.baseUrl}?endpoint=${endpoint}`; const config = { method: method, headers: { 'Content-Type': 'application/json', 'X-API-Key': this.apiKey, 'X-Email': this.email, 'X-Password': this.password } }; if (data) { config.body = JSON.stringify(data); } const response = await fetch(url, config); return await response.json(); } async getProducts(limit = 20) { return await this.request('GET', `products&limit=${limit}`); } } // Usage const client = new BeeShipAPI('your_api_key', 'user@company.com', 'password'); const products = await client.getProducts(10);

beeShip WMS API • Professional Warehouse Management System

support@de.beeship.io Login to WMS