Basic Concepts

* All End Points below are to be prefixed with, the '/client' part means it's for Client operations. All third party integrations are to operate under this name space. For example, the Client End Point is , the Client User End Point is  Please be aware that these end points are case-sensitive, incorrect case may result incorrect response from server. 


End Point




One 'Client' is an account in the system, from the perspective of Integration, all operations (Product, Consignment, Statements, etc.) are based on the current account.

Client User


There may be multiple 'Client Users' under one 'Client' account, each has their own Username, Password and API Key to login or communicate programmatically. Client and setup privilege of Client User by utilising Client Group



(Not accessible by Client)

Company acts like 'Site'. There are multiple companies in BirdSystem, such as UK Site, US Site, Germany Site, etc.

Each Client can be associated with one or more companies, as set by Customer Service Manage.

Each Company is settled in different currencies.

All API interactions need a valid company_id as HTTP Header for declaration purpose.

A full list of companies is accessible via /public/company-list end point.



(Not accessible by Client)

There is one or more Warehouses under one Company. All actual stocks exist in each warehouse.

It is not needed by Client to operate on Warehouse end point, however, warehouse_id is needed by some operations.



All Products (SKU) are shared among companies, their Stock (live_stock) are counted by Company though.



On the web page interface there are five different Consignment types: Local Consignment, Direct Consignment, Return Consignment, Agent Consignment and Batch Consignment.

All five consignment types are accessible via the same end point: /Consignment.

A 'type' field is used to distinguish different types, they are LOCAL, DIRECT, RETURN, AGENT and BATCH accordingly. ('LOCAL' by default)

Local Consignment is designed to be the most basic consignment type which needs actual stock in the local warehouse in order to send a parcel.

Direct Consignment is for client to sent consignments directly from their own premise, without actual stock in the warehouse. BirdSystem is responsible for producing address label. Product details such as weight and dimensions are needed in order to calculate correct fee for each consignment.

Return Consignment can produce a return label so buyers can return products back to our warehouse.

Agent Consignment is for client to use BirdSystem as a gateway to place order and keep record of the consignment fee.

Batch Consignment is similar to Agent Consignment however it records the consignment fee by batch.

Temp Consignment Info


Traditionally Consignment can only be added one by one, to allow importing order details in bulk, client can upload sales orders from eBay and Amazon to Temp Consignment Info and trigger /Temp-Consignment-Info/Convert-Into-Consignment End Point to convert them into proper consignments.

Delivery Service


(Read Only to Client)

Each Company has different Delivery Services, Client needs to specify delivery_service_id for each Consignment when placing order.

This End Point it Ready Only to Client.

Warehouse Dispatch Freight


(Read Only to Client)

When dispatching products into warehouse, Client need to specify which batch (Warehouse Dispatch Freight) to go with.

Client Dispatch


A Client Dispatch means a batch of products Client to send to Warehouse.