Use this endpoint to record a sale in Subiz, for example when an order is placed in your shop or CRM. See Order format for all fields.
Before you begin
- Get a Bearer access token and your account ID.
- Get the customer’s Subiz user ID. Every order needs a customer. Use Find or create by channel identity or Create a customer first if needed.
Request body
| Field | Type | Description |
|---|---|---|
user.id |
string | Required. ID of an existing customer. |
items |
array | Order lines. Each has a quantity and a product with name, sku, and price. |
source_id |
string | Recommended. Your own order ID. See Avoid duplicates. |
currency |
string | Currency of the amounts, such as VND. Empty means the account’s base currency. |
shipping |
object | Delivery address and nominal_fee. |
status |
string | Optional. open (default), unconfirmed, closed, or canceled. |
number |
string | Optional. Order number. Must not already be used by another order. |
note, private_note |
string | Optional notes. |
discount_type, discount_amount, discount_percentage |
Optional order-level discount. |
Line items keep the product data you send, including price. Send the price you charged; Subiz does not look it up again.
If a line has product.source_id but no product.id, Subiz links it to the catalog product with that source ID and uses the catalog data. If no such product exists, Subiz creates one named after the source ID, without a price.
Fields Subiz sets
Do not send these fields; Subiz sets or computes them:
id,created,created_by,updated.subtotal,total_tax,total, and linetotal, computed from the items, discounts, shipping fee, and adjustment.payment_madeandpayment_status, computed from payments recorded on the order. A new order isunpaid.user.attributes: if you omit the customer’sfullnameorphones, Subiz copies them from the customer record.pipeline_stage: if you send no pipeline, the order starts in the first stage of the default sales pipeline.
Avoid duplicates
Set source_id to the order’s ID in your system. If an order with the same source_id already exists, Subiz replaces that order with the fields you send instead of creating another one. This makes retries safe. Always send the complete order.
Without source_id, every request creates a new order. Do not retry blindly after a timeout; first check with List orders.
Response
A successful request returns HTTP 200 with the saved order, including its id and computed totals. Selected fields:
{
"id": "order_example",
"account_id": "account_example",
"source_id": "crm-1001",
"status": "open",
"payment_status": "unpaid",
"currency": "VND",
"user": {
"id": "user_example"
},
"subtotal": 240000,
"total": 270000,
"created": 1763107200000
}
Store the id to read or update the order later.
Errors
| Problem | Result |
|---|---|
user.id is missing |
Error naming the missing user. |
| Customer does not exist | Not-found error for the user. |
status is not one of the four values above |
Invalid-input error for status. |
number already used |
The request fails. Use a new number or omit it. |
See Errors for the error format.
HTTP request
Replace YOUR_ACCID, YOUR_USER_ID, YOUR_SOURCE_ORDER_ID, and YOUR_ACCESS_TOKEN with your values.
POST https://api.subiz.com.vn/4.0/accounts/YOUR_ACCID/orders
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
{
"source_id": "YOUR_SOURCE_ORDER_ID",
"user": {
"id": "YOUR_USER_ID"
},
"currency": "VND",
"items": [
{
"quantity": 2,
"product": {
"name": "Ceramic mug",
"sku": "MUG-01",
"price": 120000
}
}
],
"shipping": {
"address": {
"fullname": "Alex Example",
"phone": "+84900000000",
"address": "12 Example Street",
"region": "Ho Chi Minh City",
"country_code": "VN"
},
"nominal_fee": 30000
}
}