POST
Documents.Cancel
ביטול מסמך עסקי כשהפעולה מותרת, באמצעות canceled_status=1 ושמירת המסמך במערכת. Keeps the document id, number, rows and PDF record. Does not delete the document, refund money or cancel related documents.
Permissions
- On a company subdomain (e.g. https://{user_domain}.bull36.com) the user must match that Host — Login and protected APIs reject another company with success=0, error user_not_in_company. On a main brand host (bull36.com, biz1.co.il, mastrocrm.com, …) the company domain gate is skipped.
- A valid staff bearer token from this account is required. Customer portal tokens are rejected.
- The document must belong to the account and its customer must be accessible to the current user. Proposal visibility restrictions also apply.
- The permission to create/edit the saved document type is required; blocked document states cannot be bypassed by owners or administrators.
Action
- Sets canceled_status=1 on the eligible document, retaining its id, number, rows and PDF reference.
- Releases tracked order inventory reservations once when applicable. Does not move physical stock, refund payments, delete the record, reopen the document or cancel another document.
Push Service
- These routes do not promise a dedicated realtime event. Refresh the document through Documents.Get after changes.
Automation
- This route emits no new dedicated automation event. Cancellation changes state and tracked reservations only.
Special Instructions
- On a company subdomain (e.g. https://{user_domain}.bull36.com) the user must match that Host — Login and protected APIs reject another company with success=0, error user_not_in_company. On a main brand host (bull36.com, biz1.co.il, mastrocrm.com, …) the company domain gate is skipped.
- Supported types: purchase_orders (הזמנה), detail_orders (הזמנה מפורטת), order_proposals (הצעת מחיר). Issued invoices, receipts and other accounting document types are rejected.
- Use a staff bearer token. Customer portal tokens cannot call these routes. Account ownership, customer assignment/sharing and proposal visibility are checked on the server.
- Documents.Edit and Documents.Delete remain uploaded-file operations. Use Documents.Update, Documents.Remove and Documents.Cancel for BUSINESS documents; the numeric id alone never switches resource type.
- Call Documents.Get first to inspect data and actions. Capabilities are advisory; the server checks them again when writing. Blocked actions return HTTP 409 document_action_blocked with a reason.
- Approved, paid or closed documents are blocked. Canceled documents cannot be updated or canceled again. Closed, paid or linked line items block update and cancel.
- Update and cancel require the permission to create/edit that document type. Remove requires Delete Order permission. Financial edits by team members also require discount-edit permissions and must respect the order price lock.
- No implicit cancellation cascade is exposed: any related document blocks cancellation. Handle relations through the dashboard before retrying. Removal also checks reverse links and children.
- Errors: 400 invalid id/unsupported parameter/empty update; 401 missing or invalid bearer token; 403 access/field permission denied; 404 document not found; 409 changed/busy/blocked; 422 unsupported type or invalid values. Do not blindly retry a mutation after a network timeout; inspect Documents.Get first.
- Repeated cancellation returns a blocked-state error; it does not adjust inventory twice. For eligible purchase orders with reserved inventory, the reservation is released once. The physical inventory is not moved.
- Cancellation requires no request field for canceled_status; the server always sets 1. Reopening is not supported. A related document must be handled explicitly through the dashboard.
Required Parameters
| Name | Type | Sample | Explanation |
|---|---|---|---|
document_idpost | int | 123 | Existing BUSINESS document id from Documents.List or Documents.Get (not an uploaded file id). The server checks account and customer access. |
Optional Parameters
| Name | Type | Sample | What it gives |
|---|---|---|---|
expected_updated_datepost | string | 2026-11-16 08:00:00 | Recommended: copy data.updated_date from Documents.Get. A mismatch returns HTTP 409 document_changed; reload before retrying. Omit only if intentional last-write-wins behavior is acceptable. |
Authentication
Send the bearer token returned by Login in the request header. The user must be from the same company domain as this Host — a token from another company is rejected (user_not_in_company).
Authorization: Bearer YOUR TOKEN
Sample Request
{
"url": "\/app\/Documents.Cancel",
"method": "POST",
"headers": {
"Authorization": "Bearer YOUR TOKEN"
},
"body": {
"document_id": "123"
},
"url_user": "https:\/\/{user}.bull36.com\/app\/Documents.Cancel",
"url_domain": "https:\/\/{domain}\/app\/Documents.Cancel"
}Endpoint
POST /app/Documents.Cancel
POST https://{user}.bull36.com/app/Documents.Cancel
POST https://{domain}/app/Documents.CancelSample Output
{
"success": 1,
"document_id": 123,
"message": "OK",
"canceled_status": 1
}JavaScript Example
const token = 'YOUR TOKEN';
const body = new URLSearchParams({
"document_id": "123"
});
const response = await fetch('/app/Documents.Cancel', {
method: 'POST',
headers: { Authorization: 'Bearer ' + token },
body
});
const result = await response.json();
if (!response.ok || !result.success) throw new Error(result.message || 'Request failed');
console.log(result);Error Example
{
"success": 0,
"error": "document_action_blocked",
"message": "Document is approved"
}