Add allocation number to an issued document
Add an allocation number (מספר הקצאה) to an already-issued document. This is for Israeli Tax Authority (SHAAM) compliance when a document was issued with a deferred allocation decision.
When to use this endpoint:
- Document was issued with deferred allocation (allocationStatus = 'pending_post_issuance')
- Document was issued without allocation (allocationStatus = 'issued_without')
- Business wants to add the allocation number within the 1-year deadline
Methods:
- manual: User provides the allocation number directly (e.g., received via Tax Authority portal)
- automatic: System requests allocation from Tax Authority SHAAM API
Validations:
- Document must be issued (isLocked = true) and not cancelled
- Document type must be allocation-eligible (tax_invoice, consolidated_invoice, tax_invoice_receipt, credit_note, reservation_invoice, agent_invoice)
- Must be within 1 year of the document issue date
- If > 6 months since issuance, response includes
extensionRequired: truewarning
Only updates: allocationNumber, allocationStatus, allocationReceivedAt Does NOT modify: any financial fields (amounts, items, client, etc.)
X-Api-Key<token>
Business API key, e.g. vuz_ab12cdef... Created via Settings → Integrations → API Keys. Unlike partner keys, a public API key's STRING does not encode its environment — isolation instead comes from a completely separate sandbox database: a key minted on the Sandbox server (above) only ever reads/writes sandbox data and can never see or affect production, regardless of what the key looks like.
In: header
Path Parameters
id*string
Document unique identifier (UUID)
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X PATCH "https://example.com/documents/880e8400-e29b-41d4-a716-446655440000/allocation" \ -H "Content-Type: application/json" \ -d '{ "method": "manual" }'{ "document": { "id": "880e8400-e29b-41d4-a716-446655440000", "createdAt": "2025-11-09T09:31:07.507Z", "updatedAt": "2025-11-09T09:31:07.523Z", "deletedAt": null, "docType": "quote", "docNumber": null, "status": "draft", "issueDate": "2025-11-09", "issueTime": "14:32:07", "documentDate": "2025-11-05", "dueDate": "2025-12-09", "documentDatePeriodClosed": true, "backdateAckAt": "2019-08-24T14:15:22Z", "backdateAckByUserId": "7009be0c-f167-48ba-92d0-be39eb8a403b", "paymentTermsId": "990e8400-e29b-41d4-a716-446655440000", "paymentTermsText": "שוטף + 30", "currency": "ILS", "fxRate": null, "vatMode": "exclusive", "vatRateDefault": 17, "subTotal": "150.00", "vatTotal": "25.50", "grandTotal": "175.50", "clientName": null, "clientTaxId": null, "clientAddress": null, "notes": null, "metadata": null, "originalDocumentId": null, "parentDocumentId": null, "cancelledByDocumentId": null, "pdfPath": null, "publicSlug": "j3AxtCjwHS", "isPublicEnabled": true, "clientPhoneSnapshot": "+972522456789", "branchId": "string", "branchName": "string", "parentClientName": "string", "signedAt": null, "signatureImagePath": null, "signatureName": null, "signatureNote": null, "outstandingAmount": null, "paidAt": null, "paymentStatus": "UNPAID", "documentBalance": 1000, "totalPaymentsReceived": 0, "totalCreditsApplied": 0, "roundingAdjustment": -0.01, "paymentStatusUpdatedAt": null, "paymentLinkUrl": "https://pay.vuz.co.il/abc123def456", "paymentLinkId": "990e8400-e29b-41d4-a716-446655440000", "paymentLinkStatus": "active", "paymentLinkExpiresAt": "2025-12-25T00:00:00.000Z", "isClosed": false, "closedAt": null, "closedBy": null, "isInteractive": false, "interactiveStatus": "negotiation", "publicToken": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6", "publicTokenExpiresAt": "2025-12-25T00:00:00.000Z", "negotiationVersion": 1, "business": { "id": "50596d36-8006-4aeb-a29e-ca78edddb2df", "businessName": "אקו דב", "ownerPhone": "972527253023", "vatRate": 18, "currency": "ILS", "vatNumber": "300160629", "logoPath": null, "address": null, "email": "naor@echo-dev.co.il", "businessMeta": { "logoUrl": "/uploads/logos/fd32d6f3-f790-4999-b30a-df360993123b.jpg" }, "userId": "45b9de13-426f-45f8-98f8-a8a8961acf34", "isActive": true, "isOnTrial": true, "trialEndDate": "2025-11-11" }, "businessId": "50596d36-8006-4aeb-a29e-ca78edddb2df", "client": { "id": "3c3e3b30-924b-4a9f-9fbc-516010d36427", "name": "אקסיומה", "type": "company_ltd", "email": "yosi@exioma.co.il", "phone": "0522456789", "address": "צנחנים 1 רעננה", "vatNumber": "111111111", "contactPerson": "יוסי בוכניק", "notes": "", "isActive": true, "userId": "45b9de13-426f-45f8-98f8-a8a8961acf34", "businessId": "50596d36-8006-4aeb-a29e-ca78edddb2df" }, "clientId": "3c3e3b30-924b-4a9f-9fbc-516010d36427", "createdBy": null, "updatedBy": null, "origin": "web", "originName": "vuz", "items": [ { "id": "990e8400-e29b-41d4-a716-446655440000", "lineNo": 1, "description": "ייעוץ עסקי - 10 שעות", "quantity": "10.000", "unit": "שעות", "unitPrice": "150.00", "discountPercent": "0.00", "vatApplicable": true, "vatRate": 17, "lineSubTotal": "150.00", "lineVatTotal": "25.50", "lineGrandTotal": "175.50", "createdAt": "2025-11-09T09:31:07.518Z", "updatedAt": "2025-11-09T09:31:07.518Z", "deletedAt": null, "documentId": "25cd5cfb-8e24-4dd6-b564-0b3c06cb9056" } ], "payments": [ { "id": "990e8400-e29b-41d4-a716-446655440000", "paymentMethod": "cash", "paymentProvider": "string", "amount": 500, "paymentDate": "2025-11-09", "notes": "Payment for invoice #123", "referenceNumber": "REF-12345", "bankNumber": "12", "branchNumber": "456", "accountNumber": "123456789", "checkNumber": "123456", "dueDate": "2025-02-15", "creditCompanyCode": 2, "cardName": "Visa", "cardLastDigits": "1234", "creditTransactionType": 1, "numberOfInstallments": 3, "tranzilaTransactionId": "6982", "tranzilaAuthCode": "0672865" } ], "aiSummaryData": {} }, "extensionRequired": false, "message": "Allocation number A12345678 added successfully."}