📄Orders

This API is available for versions v.2.62.11 and later as of 2024-10-04.

Best Practices

When performing system integration, linking order data to customer (Contact) records is crucial. The following are recommended integration workflow steps:

1. Find or create customer record

   • Search for an existing customer record based on purchaser criteria (such as email, phone number, etc.).

   • If no matching customer record exists, create a new customer record.

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

   • Ensure 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 linking between orders and customer data.

---

Search Orders

Request Method: GET Endpoint: /api/v1/contact-order Description: Search for orders that match the specified conditions.

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 identifier, 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 by a third-party e-commerce/external system via 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 by a third-party e-commerce/external system via 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	Array of sales order data
meta	Object	Pagination-related metadata
links	Object	Pagination-related links

---

Get single order

Request Method: GET Endpoint: /api/v1/contact-order/{contact-order} Description: Retrieve the details of a single order by 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	The 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 data
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

---

Create 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 Site 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	Unique identifier for the order number
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 of the order's last update
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	Sum of all item prices, excluding any discounts, taxes, shipping, or other additional 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 specified order's data.

Curl Example

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

URL Parameters

Parameter Name	Required	Default Value	Type	Description
id	Yes	NULL	Number	The 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 identifier for the order number
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 of the order's last update
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	Sum of all item prices, excluding any discounts, taxes, shipping, or other additional 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 is YYYY-MM-DD HH:MM:SS
order_updated_at	String	Order last update time, format is 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	Sum of all item prices, excluding any discounts, taxes, shipping, or other additional 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	Record creation time, format is YYYY-MM-DD HH:MM:SS
updated_at	String	Record update time, format is YYYY-MM-DD HH:MM:SS

Order Status Enumerations

• financial_status(Payment Status):

  • pending: Awaiting payment

  • paid: Payment received

  • cod: Cash on delivery

  • remitted: Remitted but not 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: Overdue for pickup

  • problem: Shipping exception

• return_status(Return Status):

  • no_need: No return needed

  • request_return: Return requested

  • returning: Returning

  • checking: Return under review

  • refused: Return refused

  • returned: Returned

  • partial_return: Partial return

  • in_origin_cvs: Original drop-off store

  • in_hub: Transit hub

  • problem: Shipping exception