Delivery Status

Billease Transaction API →

As an order progresses, tell us where it is so we can keep the customer updated in the app. This uses the standard transaction-update endpoint with one extra field, delivery_status.

POST https://trx.billease.ph/be-transactions-api/trx/{id}/update
Authorization: Bearer <your-token>
Content-Type: application/json

{
  "order_id": "order-123",
  "delivery_status": "DISPATCHED"
}

{id} is the Billease transaction UUID; order_id is the reference we sent you on POST /trx/transaction. Both must point at the same order, or the update is rejected.

Call it every time the status changes. Re-sending the status the order is already in is safe and returns 200.

The status codes

Status	Required?	Meaning
ORDER_RECEIVED	No	Already implied by your successful POST /trx/transaction response; you do not need to send it.
IN_PROCESS	Optional	Being prepared / packed
DISPATCHED	Required	Handed to the courier / out for delivery
DELIVERY_SUCCESSFUL	Required	Delivered to the customer
DELIVERY_FAILED	Required	Delivery attempt failed or could not be completed

At minimum, send DISPATCHED and then one of DELIVERY_SUCCESSFUL or DELIVERY_FAILED.

ORDER_RECEIVED ──▶ IN_PROCESS ──▶ DISPATCHED ──┬──▶ DELIVERY_SUCCESSFUL
      │            (optional)                  │
      └───────────────────────────────────────▶└──▶ DELIVERY_FAILED

status and delivery_status

They are two different things, and the endpoint accepts either or both.

Field	Governs	Who uses it
status	The transaction: OK to confirm, CAN to cancel	Standard checkout
delivery_status	The physical goods	Deals partners

status and delivery_status are independent. For a Deals order the status field is inert: the transaction is already approved on our side, so any status value (including CAN) is rejected and cannot change or reverse it. Reverse it through the refund process instead; only delivery_status has any effect.

Refunds

There is deliberately no REFUNDED delivery status. Refunds are a first-class flow of their own:

POST /trx/{id}/refund

It settles the money, marks the individual items refunded, folds into your net-proceeds accounting and returns a refund_id you can poll with GET /trx/refund/{refund_id}. A delivery status could do none of that.

Checking our view of a transaction

To confirm what Billease believes about a transaction after a timeout, or when your record and ours disagree, read it back:

Endpoint	Returns
GET /trx/{id}/status	Current status, order_id, timestamps
GET /trx/{id}	The full transaction
GET /trx/{id}/history	Every status transition, timestamped

These are the same endpoints every Billease merchant has. GET /trx/{id}/history is the quickest way to see whether a transaction was cancelled and when.

Errors

Status	Meaning
400	Malformed request, or an unrecognized delivery_status
401	Missing or invalid JWT
500	Error on our side. Safe to retry.