SubizDeveloper Docs
Orders

API 4.0

Create an order

Create an order for an existing customer.

POSThttps://api.subiz.com.vn/4.0/accounts/{accid}/orders

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

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 line total, computed from the items, discounts, shipping fee, and adjustment.
  • payment_made and payment_status, computed from payments recorded on the order. A new order is unpaid.
  • user.attributes: if you omit the customer’s fullname or phones, 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
  }
}