📄Orders

This API is available for versions 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 recommended integration workflow steps:

1. Find or create customer data

   • Search for existing customer records based on buyer criteria (such as email, phone number, etc.).

   • If no matching customer record is found, 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 correctly corresponds to the appropriate customer; this helps improve management efficiency and maintain data consistency.

Following the above steps can effectively optimize the API integration process and ensure accurate association between orders and customer data.

---

Search orders

Request method: GET Endpoint: /api/v1/contact-order Instructions: Search for a list of matching orders according to 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 values	Type	Instructions
contact_id	No	NULL	Number	Customer system ID, for example 5263
order_number	No	NULL	String	Order number, for example O412554

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	Instructions
data	Array of objects	Array of sales order data
meta	Object	Pagination-related metadata
links	Object	Pagination-related links

---

Get single order data

Request method: GET Endpoint: /api/v1/contact-order/{contact-order} Instructions: 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 values	Type	Instructions
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	Instructions
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 Instructions: 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 values	Type	Instructions
order_source	Yes	NULL	EnumValue	Order source
order_number	Yes	NULL	String	The 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
subtotal_price	No	NULL	Decimal	Sum of prices for all items, excluding any discounts, taxes, shipping fees, or other additional charges
total_discount	No	NULL	Decimal	Total amount of all discounts in the order
shipping_fee	No	NULL	Decimal	Total shipping fee amount 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} Instructions: Update the specified order's data.

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 values	Type	Instructions
id	Yes	NULL	Number	Unique identifier of the order

Form Data

Field Name	Required	Default values	Type	Instructions
order_source	No	NULL	EnumValue	Order source
order_number	No	NULL	String	The 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
subtotal_price	No	NULL	Decimal	Sum of prices for all items, excluding any discounts, taxes, shipping fees, or other additional charges
total_discount	No	NULL	Decimal	Total amount of all discounts in the order
shipping_fee	No	NULL	Decimal	Total shipping fee amount 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	Instructions
id	Number	Product ID
order_source	String	Order source
order_created_at	String	Order creation time, formatted as YYYY-MM-DD HH:MM:SS
order_updated_at	String	Order last update time, formatted as 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
subtotal_price	Decimal	Sum of prices for all items, excluding any discounts, taxes, shipping fees, or other additional charges
total_discount	Decimal	Total amount of all discounts in the order
shipping_fee	Decimal	Total shipping fee amount 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, formatted as YYYY-MM-DD HH:MM:SS
updated_at	String	Record update time, formatted as 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: Expired / Not picked up in time

  • 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