📄Orders

This API is available for version v.2.62.11 and later after 2024-10-04.

Best Practices

When performing system integration, associating order data with the customer (Contact) is crucial. The following are the recommended integration workflow steps:

1. Find or create customer data

   • Search for 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.

   • Obtain 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.

   • Make sure each order is correctly associated with the corresponding customer; this helps improve management efficiency and maintain data consistency.

Following the steps above 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 based on the specified criteria.

Curl Example

curl -X GET \
     -H "Content-Type: application/json" \
     '{
       "order_number": "ORD202309260001"
     }' \
     https://{API_HOST}/api/v1/contact-order

URL Parameters

Parameter Name	Required	Default Value	Type	Description
contact_id	No	NULL	Number	Customer system number, for example 5263
order_number	No	NULL	String	Order number, for example O412554
order_created_at__start	No	NULL	String	Order creation start time, which may be entered manually by staff or written in by a third-party e-commerce/external system through a synchronization mechanism, for example 2025-11-01
order_created_at__end	No	NULL	String	Order creation end time, which may be entered manually by staff or written in by a third-party e-commerce/external system through a synchronization mechanism, for example 2025-11-01

Response Structure

{
    "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": {
        // Pagination-related links
    },
    "meta": {
        // Pagination-related metadata
    }
}

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 based on the order ID.

Curl Example

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

{
    "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 record
data.id	Number	Order ID
data.order_source	String	Order source
data.order_number	String	Order number
data.contact_id	Number	Associated customer's unique identifier
...	...	Other order-related fields

---

Add Order

Request Method: POST Endpoint: /api/v1/contact-order Description: Create a new order record.

Curl Example

curl -X POST \
     -H "Content-Type: application/json" \
     '{
       "order_number": "FL_968521",
       "order_name": "Official Website Order #968521"
     }' \
     https://{API_HOST}/api/v1/contact-order

Form Data

Field Name	Required	Default Value	Type	Description
order_source	Yes	NULL	EnumValue	Order source
order_number	Yes	NULL	String	Number that uniquely identifies the order
contact_id	Yes	NULL	Number	Associated customer's unique identifier
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	The 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

{
    "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

curl -X PUT \
     -H "Content-Type: application/json" \
     '{
       "order_number": "FL_968521",
       "order_name": "Official Website Order #968521"
     }' \
     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

Form Data

Field Name	Required	Default Value	Type	Description
order_source	No	NULL	EnumValue	Order source
order_number	No	NULL	String	Number that uniquely identifies the order
contact_id	No	NULL	Number	Associated customer's unique identifier
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	The 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

{
    "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, format: YYYY-MM-DD HH:MM:SS
order_updated_at	String	Order last updated time, 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	The 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	Associated customer's unique identifier
items	Array	List of items in the order
created_at	String	Data creation time, format: YYYY-MM-DD HH:MM:SS
updated_at	String	Data update time, format: YYYY-MM-DD HH:MM:SS

Order status enums

• financial_status(Payment status):

  • pending: Awaiting payment

  • paid: Payment received

  • cod: Cash on delivery

  • remitted: Remitted but not yet received

  • failed: Payment failed

  • pending_refund: Refund pending

  • pending_partial_refund: Partial refund pending

  • 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 center

  • problem: Shipping exception