> For the complete documentation index, see [llms.txt](https://en.help.firstline.cc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://en.help.firstline.cc/developer/api/contact-order.md). # Orders {% hint style="success" %} This API is available for versions v.2.62.11 and later after 2024-10-04. {% endhint %} ## Best Practices When performing system integration, it is crucial to associate order (Order) data with the customer (Contact). The following are the recommended integration steps: 1. **Find or create customer data** * Find existing customer data based on the buyer's criteria (such as email, phone number, etc.). * If no matching customer data is found, create new customer data. * Get the customer's unique identifier (`contact_id`). 2. **Create or update order data** * Use the order number (`order_number`) and customer ID (`contact_id`) to create a new order or update an existing order. * Ensure each order is correctly matched to the corresponding customer; this helps improve management efficiency and maintain data consistency. By following the above steps, you can effectively optimize the API integration process and ensure accurate association between order and customer data. *** ## Search Orders **Request Method**: `GET`\ **Endpoint**: `/api/v1/contact-order`\ **Description**: Search for a list of matching orders according to the specified criteria. **Curl Example** ```bash curl -G "https://{API_HOST}/api/v1/contact-order" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Accept: application/json" \ --data-urlencode "order_number=ORD202309260001" ``` **URL Parameters**
Parameter NameRequiredDefault ValueTypeDescription
contact_idNoNULLNumberCustomer system ID, for example 5263
order_numberNoNULLStringOrder number, for example O412554
order_created_at__startNoNULLStringOrder creation start time, which may be entered manually by a staff member or written in by a third-party e-commerce/external system through synchronization, for example 2025-11-01
order_created_at__endNoNULLStringOrder creation end time, which may be entered manually by a staff member or written in by a third-party e-commerce/external system through synchronization, for example 2025-11-01
**Response Structure** ```json { "data": [ { "id": 1, "order_source": "cyberbiz", "order_created_at": "2024-09-06 00:00:00", "order_updated_at": null, "order_number": "ORD202309260001", "order_name": "Order #1001", "receiver_name": null, "receiver_address": null, "receiver_phone": null, "subtotal_price": "4000.00", "total_discount": "400.00", "shipping_fee": "330.00", "total_tax": "230.00", "total_price": "5245.00", "financial_status": "paid", "fulfillment_status": "preparing", "return_status": "returning", "note": null, "extra_info": null, "contact_id": 2195878, "items": [], "created_at": "2024-09-27 10:02:25", "updated_at": "2024-09-27 14:20:27" } ], "links": {}, "meta": {} } ``` **Response Field Descriptions** | **Field Name** | **Type** | **Description** | | -------------- | ---------------- | --------------------------- | | `data` | Array of objects | Sales order data array | | `meta` | Object | Pagination-related metadata | | `links` | Object | Pagination-related links | *** ## Get a Single Order Record **Request Method**: `GET`\ **Endpoint**: `/api/v1/contact-order/{contact-order}`\ **Description**: Get detailed information for a single order by order ID. **Curl Example** ```bash curl -X GET \ -H "Content-Type: application/json" \ https://{API_HOST}/api/v1/contact-order/1 ``` **URL Parameters** | **Parameter Name** | **Required** | **Default Value** | **Type** | **Description** | | ------------------ | ------------ | ----------------- | -------- | ------------------------------ | | `id` | Yes | NULL | Number | Unique identifier of the order | **Response Structure** ```json { "data": { "id": 1, "order_source": "cyberbiz", "order_created_at": "2024-09-06 00:00:00", "order_updated_at": null, "order_number": "ORD202309260001", "order_name": "Order #1001", "receiver_name": null, "receiver_address": null, "receiver_phone": null, "subtotal_price": "4000.00", "total_discount": "400.00", "shipping_fee": "330.00", "total_tax": "230.00", "total_price": "5245.00", "financial_status": "paid", "fulfillment_status": "preparing", "return_status": "returning", "note": null, "extra_info": null, "contact_id": 2195878, "items": [], "created_at": "2024-09-27 10:02:25", "updated_at": "2024-09-27 14:20:27" } } ``` **Response Field Descriptions** | **Field Name** | **Type** | **Description** | | ------------------- | -------- | -------------------------------------------- | | `data` | Object | Single order data | | `data.id` | Number | Order ID | | `data.order_source` | String | Order source | | `data.order_number` | String | Order number | | `data.contact_id` | Number | Unique identifier of the associated customer | | ... | ... | Other order-related fields | *** ## Create Order **Request Method**: `POST`\ **Endpoint**: `/api/v1/contact-order`\ **Description**: Create a new order record. **Curl Example** ```bash curl -X POST "https://{API_HOST}/api/v1/contact-order" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "order_source": "cyberbiz", "contact_id": 123, "order_number": "FL_968521", "order_name": "Official website order #968521" }' ``` **JSON Request Body** | **Field Name** | **Required** | **Default Value** | **Type** | **Description** | | -------------------- | ------------ | ----------------- | --------- | ------------------------------------------------------------------------------------------------------ | | `order_source` | Yes | NULL | EnumValue | Order source | | `order_number` | Yes | NULL | String | Unique order identifier | | `contact_id` | Yes | NULL | Number | Unique identifier of the associated customer | | `order_created_at` | No | NULL | DateTime | Timestamp when the order was created | | `order_updated_at` | No | NULL | DateTime | Timestamp when the order was last updated | | `order_name` | No | NULL | String | Display name of the order | | `receiver_name` | No | NULL | String | Recipient's name | | `receiver_address` | No | NULL | String | Recipient's address | | `receiver_phone` | No | NULL | String | Recipient's phone number | | `subtotal_price` | No | NULL | Decimal | Total price of all items, excluding any additional charges such as discounts, taxes, and shipping fees | | `total_discount` | No | NULL | Decimal | Total amount of all discounts in the order | | `shipping_fee` | No | NULL | Decimal | Total shipping fee for the order | | `total_tax` | No | NULL | Decimal | Total tax amount for the order | | `total_price` | No | NULL | Decimal | Final total amount of the order | | `financial_status` | No | NULL | EnumValue | Payment status | | `fulfillment_status` | No | NULL | EnumValue | Fulfillment status | | `return_status` | No | NULL | EnumValue | Return status | | `note` | No | NULL | String | Additional notes for the order | | `extra_info` | No | NULL | String | Supplementary information for the order | **Response Structure** ```json { "data": { "id": 1, "order_source": "cyberbiz", "order_created_at": "2024-09-06 00:00:00", "order_updated_at": null, "order_number": "ORD202309260001", "order_name": "Order #1001", "receiver_name": null, "receiver_address": null, "receiver_phone": null, "subtotal_price": "4000.00", "total_discount": "400.00", "shipping_fee": "330.00", "total_tax": "230.00", "total_price": "5245.00", "financial_status": "paid", "fulfillment_status": "preparing", "return_status": "returning", "note": null, "extra_info": null, "contact_id": 2195878, "items": [], "created_at": "2024-09-27 10:02:25", "updated_at": "2024-09-27 14:20:27" } } ``` *** ## Update Order Data **Request Method**: `PUT`\ **Endpoint**: `/api/v1/contact-order/{contact-order}`\ **Description**: Update the data of the specified order. **Curl Example** ```bash curl -X PUT "https://{API_HOST}/api/v1/contact-order/1" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "order_source": "cyberbiz", "contact_id": 123, "order_number": "FL_968521", "order_name": "Official website order #968521" }' ``` **URL Parameters** | **Parameter Name** | **Required** | **Default Value** | **Type** | **Description** | | ------------------ | ------------ | ----------------- | -------- | ------------------------------ | | `id` | Yes | NULL | Number | Unique identifier of the order | **Form Data** | **Field Name** | **Required** | **Default Value** | **Type** | **Description** | | -------------------- | ------------ | ----------------- | --------- | ------------------------------------------------------------------------------------------------------ | | `order_source` | No | NULL | EnumValue | Order source | | `order_number` | No | NULL | String | Unique order identifier | | `contact_id` | No | NULL | Number | Unique identifier of the associated customer | | `order_created_at` | No | NULL | DateTime | Timestamp when the order was created | | `order_updated_at` | No | NULL | DateTime | Timestamp when the order was last updated | | `order_name` | No | NULL | String | Display name of the order | | `receiver_name` | No | NULL | String | Recipient's name | | `receiver_address` | No | NULL | String | Recipient's address | | `receiver_phone` | No | NULL | String | Recipient's phone number | | `subtotal_price` | No | NULL | Decimal | Total price of all items, excluding any additional charges such as discounts, taxes, and shipping fees | | `total_discount` | No | NULL | Decimal | Total amount of all discounts in the order | | `shipping_fee` | No | NULL | Decimal | Total shipping fee for the order | | `total_tax` | No | NULL | Decimal | Total tax amount for the order | | `total_price` | No | NULL | Decimal | Final total amount of the order | | `financial_status` | No | NULL | EnumValue | Payment status | | `fulfillment_status` | No | NULL | EnumValue | Fulfillment status | | `return_status` | No | NULL | EnumValue | Return status | | `note` | No | NULL | String | Additional notes for the order | | `extra_info` | No | NULL | String | Supplementary information for the order | **Response Structure** ```json { "data": { "id": 1, "order_source": "cyberbiz", "order_created_at": "2024-09-06 00:00:00", "order_updated_at": null, "order_number": "ORD202309260001", "order_name": "Order #1001", "receiver_name": null, "receiver_address": null, "receiver_phone": null, "subtotal_price": "4000.00", "total_discount": "400.00", "shipping_fee": "330.00", "total_tax": "230.00", "total_price": "5245.00", "financial_status": "paid", "fulfillment_status": "preparing", "return_status": "returning", "note": null, "extra_info": null, "contact_id": 2195878, "items": [], "created_at": "2024-09-27 10:02:25", "updated_at": "2024-09-27 14:20:27" } } ``` *** ## Order data model | **Field Name** | **Type** | **Description** | | -------------------- | -------- | ------------------------------------------------------------------------------------------------------ | | `id` | Number | Product ID | | `order_source` | String | Order source | | `order_created_at` | String | Order creation time, in the format `YYYY-MM-DD HH:MM:SS` | | `order_updated_at` | String | Order last updated time, in the format `YYYY-MM-DD HH:MM:SS` | | `order_number` | String | Order number | | `order_name` | String | Display name of the order | | `receiver_name` | String | Recipient's name | | `receiver_address` | String | Recipient's address | | `receiver_phone` | String | Recipient's phone number | | `subtotal_price` | Decimal | Total price of all items, excluding any additional charges such as discounts, taxes, and shipping fees | | `total_discount` | Decimal | Total amount of all discounts in the order | | `shipping_fee` | Decimal | Total shipping fee for the order | | `total_tax` | Decimal | Total tax amount for the order | | `total_price` | Decimal | Final total amount of the order | | `financial_status` | String | Payment status (Enum) | | `fulfillment_status` | String | Fulfillment status (Enum) | | `return_status` | String | Return status (Enum) | | `note` | String | Additional notes for the order | | `extra_info` | String | Supplementary information for the order | | `contact_id` | Number | Unique identifier of the associated customer | | `items` | Array | List of items in the order | | `created_at` | String | Data creation time, in the format `YYYY-MM-DD HH:MM:SS` | | `updated_at` | String | Data update time, in the format `YYYY-MM-DD HH:MM:SS` | ## Order status enumeration * **`financial_status`**(Payment status): * `pending`: Waiting for payment * `paid`: Payment received * `cod`: Cash on delivery * `remitted`: Remitted, not yet received * `failed`: Payment failed * `pending_refund`: Pending refund * `pending_partial_refund`: Pending partial refund * `partial_refunded`: Partially refunded * `refunded`: Refunded * **`fulfillment_status`**(Fulfillment status): * `unshipped`: Not shipped * `preparing`: Preparing for shipment * `partial`: Partially shipped * `fulfilled`: Shipped * `arrived`: Arrived at store * `received`: Received * `returned`: Returned * `expired`: Unclaimed past due * `problem`: Shipping exception * **`return_status`**(Return status): * `no_need`: No return needed * `request_return`: Return request * `returning`: Returning * `checking`: Return review * `refused`: Return refused * `returned`: Returned * `partial_return`: Partial return * `in_origin_cvs`: Original shipping store * `in_hub`: Transfer hub * `problem`: Shipping exception