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

NameTypeSampleExplanation
document_id
post
int123Existing BUSINESS document id from Documents.List or Documents.Get (not an uploaded file id). The server checks account and customer access.

Optional Parameters

NameTypeSampleWhat it gives
expected_updated_date
post
string2026-11-16 08:00:00Recommended: 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.Cancel

Sample 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"
}