Green Invoice

Green Invoice (Morning)

Instructions

Step 1: Authentication and Plan Requirements

Green Invoice uses JWT Bearer token authentication. Obtain API credentials from the Green Invoice dashboard: Personal Area (אזור אישי) > Developer Tools (כלים למפתחים) > API Keys (מפתחות API).

Plan gating (verified May 2026):

• API access (any endpoint): requires the Best plan or higher (זמין למנויי Best ומעלה).
• Webhooks (Step 11): require the Extra plan or higher (זמין למנויים במסלול Extra).

Lower-tier accounts will not see the "API Keys" or "Webhooks" menu items at all. If a user reports a missing menu item, check their plan first.

Rebrand note. The product was rebranded from "חשבונית ירוקה" to "Morning של חשבונית ירוקה". The API host (api.greeninvoice.co.il) and dashboard host (app.greeninvoice.co.il) are unchanged, and there is still no api.morning.co.il. But do NOT extend that to "no Morning host exists": the current documentation puts the OAuth token endpoint on api.morning.co, which is a different hostname from the one that does not resolve.

Two authentication flows are live right now (both verified 2026-07-27). Use OAuth 2.0 for new work.

The published documentation at developers.morning.co (versioned "morning API Documentation (2.0.0)") now states: "Our APIs use the OAuth 2.0 protocol for authentication and authorization." The older API-key flow still answers, so existing integrations are not broken, but it is no longer the documented path and should be treated as legacy.

Both return a bearer token used the same way against the same API base URL, so the only thing that changes is how you obtain it. If you are writing new code, use the OAuth endpoint; if you are maintaining an integration on /account/token, it still works today but plan the migration.

Note the error mapping on the OAuth endpoint, because two of its codes are business-state rather than credential problems: invalid_grant means the API key is expired, revoked or pending, and unauthorized_client means there is no active subscription or the subscription does not include API access. Neither is fixed by re-issuing keys.

Base URLs:

Get a token (OAuth 2.0, the documented path):

curl -X POST https://api.morning.co/idp/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'grant_type=client_credentials' \
  -d 'client_id=YOUR_API_KEY_ID' \
  -d 'client_secret=YOUR_API_KEY_SECRET'

The response carries accessToken, a signed JWT valid for 1 hour.

Get a token (legacy API-key flow, still functional):

curl -X POST https://api.greeninvoice.co.il/api/v1/account/token \
  -H "Content-Type: application/json" \
  -d '{"id": "YOUR_API_KEY_ID", "secret": "YOUR_API_KEY_SECRET"}'

Either way you end up with a JWT. Use it in all subsequent requests:

Authorization: Bearer <token>
Content-Type: application/json

Always start by verifying credentials work:

curl -s https://api.greeninvoice.co.il/api/v1/documents/info \
  -H "Authorization: Bearer <token>" | python3 -m json.tool

Step 2: Tax Authority Authorization (Required for B2B Invoices Over the Threshold)

This step is mandatory for any user issuing B2B חשבונית מס (Tax Invoice, type 305) or חשבונית מס/קבלה (Tax Invoice-Receipt, type 320) over the SHAAM allocation-number threshold. Skipping it silently breaks VAT deduction for the buyer.

The threshold schedule (amounts are NET, before VAT):

Documents dated before May 2024 predate the regime and never needed a number. The threshold is date-dependent: when validating or migrating historical documents, test each against the threshold in force on ITS OWN date, not today's.

Two rules apply and conflating them is the classic error. The SELLER'S duty to obtain a number (s.47(a2)(1)) arises only when the buyer demands it, and does not apply to a zero-rated invoice. The BUYER'S loss of the deduction (s.38(a1)) has NO buyer-request condition: input VAT is disallowed on any qualifying invoice lacking a number, asked for or not.

So when validating, do NOT treat "the buyer never asked" as a pass. Flag every tax invoice above that date's threshold that carries VAT and has no allocation number. The statute says עולה על (exceeds), so an invoice at exactly the threshold is outside it. The number is 9 digits, and a missing one blocks the recipient's deduction without voiding the invoice. Statute text in references/api-reference.md.

Above the threshold, a B2B tax invoice must carry a מספר הקצאה (allocation number) issued by שע"מ. Without it your customer cannot deduct the input VAT they paid you.

Morning attaches the allocation number automatically, BUT ONLY AFTER a one-time authorization grant in the user's Morning account. This is NOT automatic on signup. The user must:

1. In the Morning dashboard, navigate to: אזור אישי > רשות המיסים > הוספת הרשאה (Personal Area > Tax Authority > Add Authorization)
2. The dashboard redirects to the Tax Authority gov.il portal for identity verification
3. After authorization, the browser returns automatically to Morning, and the connection becomes active

Once active, Morning attaches the allocation number to the tax invoice through its own system, with no second platform to log into ("מספר ההקצאה מתנהל אוטומטית").

Critical: the authorization expires every 3 months and must be renewed manually. Morning's help centre states the connection is valid for 3 months with an in-system alert 10 days before expiry. Do not rely on an email; check the connection from your own runbook. If it lapses, qualifying invoices still succeed at HTTP level but ship WITHOUT an allocation number.

What to do in code:

1. Surface this requirement to the human user before they create their first large B2B invoice - the API does not currently expose a tax_authority_connection_active flag in public docs.
2. After creating a qualifying B2B invoice, fetch the resulting document with GET /v1/documents/{id} and check the PDF / response for an allocation number. If missing, the user's authorization is lapsed or was never set up.
3. The field is allocationNumber, documented in the Morning OpenAPI on Document, UpdatedDocument, Expense and ExpenseRequest. It is omitted when no number was assigned, so a qualifying invoice returning without it means the authorization lapsed. See references/api-reference.md.

For end-to-end SHAAM compliance use the israeli-e-invoice skill alongside this one.

Step 3: Understand Document Types

Green Invoice supports 15 document types. Each has a numeric code used in API calls.

Key rule: For Israeli clients who pay immediately, use type 320 (Tax Invoice-Receipt). For invoices where payment comes later, use type 300 (Transaction Invoice). For an export sale to a foreign client (osek murshe), issue a tax invoice (type 305 or 320) with each income row zero-rated via vatRate: 0. Export of services is zero-rated (0%) under VAT Law Section 30, NOT exempt, so keep the rows taxable (vatType: 0) and set the rate to zero rather than marking them vatType: 1 (Exempt). Use type 400 (Receipt) only to record a payment against an already-issued invoice, never as the sole document for a sale.

Step 4: Create Documents

POST /v1/documents

Required fields: type, client (with name and emails), income (line items array).

{
  "type": 320,
  "date": "2026-03-05",
  "lang": "he",
  "currency": "ILS",
  "vatType": 0,
  "rounding": true,
  "signed": true,
  "attachment": true,
  "client": {
    "name": "Moshe Cohen",
    "emails": ["moshe@example.com"],
    "taxId": "123456789",
    "add": true
  },
  "income": [
    {
      "description": "Web Development Services",
      "quantity": 1,
      "price": 5000,
      "currency": "ILS",
      "vatType": 0
    }
  ],
  "payment": [
    {
      "type": 4,
      "date": "2026-03-05",
      "price": 5000,
      "currency": "ILS"
    }
  ]
}

VAT types (document level):

VAT types (income row level): the income-row vatType is a DIFFERENT enum from the document-level one. A document uses DocumentVatType (0 default, 1 exempt, 2 mixed); an income row uses ItemVatType (0 default, 1 VAT included in price, 2 exempt). The two collide on the value 1, so copying a document-level vatType: 1 onto a row does not make the row exempt, it makes it VAT-inclusive and changes the amount charged. To set a specific rate on a line (e.g. 0% for a zero-rated export line), use the separate vatRate field, a decimal fraction (0 for 0%, 0.18 for 18%).

Step 5: Payment Types

When adding payment records to a document, use these type codes:

Credit card types (CreditCardType, when payment type is 3): 0 Unknown, 1 Isracard, 2 Visa, 3 Mastercard, 4 American Express, 5 Diners. Deal types (CreditCardDealType): 1 Standard, 2 Payments, 3 Credit, 4 Deferred, 5 Other, 6 Recurring.

Step 6: Manage Clients

Create client: POST /v1/clients

{
  "name": "Startup Ltd.",
  "emails": ["billing@startup.co.il"],
  "taxId": "515123456",
  "country": "IL",
  "city": "Tel Aviv",
  "address": "Rothschild 45",
  "paymentTerms": 30,
  "labels": ["3777a6ef-0000-0000-0000-000000000000"]
}

Payment terms: PaymentTerm is -1 (מיידי) and 0/10/15/30/45/60/75/90/120 for שוטף +N. Full table in references/api-reference.md. These are שוטף+N, not end-of-month+N.

Other client endpoints:

Search clients:

{
  "name": "Startup",
  "active": true,
  "page": 1,
  "pageSize": 25
}

Step 7: Search and Query Documents

POST /v1/documents/search

{
  "page": 1,
  "pageSize": 25,
  "type": [320, 305],
  "status": [0, 1],
  "fromDate": "2026-01-01",
  "toDate": "2026-03-31",
  "sort": "documentDate"
}

Document statuses:

Get document: GET /v1/documents/{id}

Close document: POST /v1/documents/{id}/close

Download document PDF: GET /v1/documents/{id}/download/links returns URLs in Hebrew, English, and original language.

Step 8: Link Documents

Documents can be linked to create workflows. Use linkedDocumentIds when creating a new document.

Common linking patterns:

When a receipt is linked to an invoice with full payment, the invoice automatically closes.

Step 9: Item Catalog

Manage reusable product/service items:

Use itemId in income line items to reference catalog items instead of manually specifying description and price each time.

Step 10: Business Types and VAT Rules

Green Invoice handles VAT automatically based on business type:

Non-profits: donation receipts carry a 2026 reporting obligation. Since 1 January 2026 an amuta holding Section 46 authorization must report credit-granting donations to the Tax Authority's digital donations system, and the reporting is meant to happen automatically from receipt-issuing software that is connected to it (organisations on unconnected software or paper receipts file through a dedicated Tax Authority application instead). This is the same shape of trap as the SHAAM allocation number in Step 2: issuing a type 405 receipt through the API can return HTTP 200 while the donation is not reported, and the donor's Section 46 credit is what is at stake. If you are integrating for an amuta, confirm with Morning whether donation reporting is connected for that account before assuming the API call is the whole of compliance. Do not tell a non-profit they are compliant just because the receipt was created.

Do not confuse עוסק זעיר with any of the codes above. Since Amendment 265 to the Income Tax Ordinance a business can elect "micro-dealer" status, and users increasingly describe themselves that way. It is an INCOME TAX classification governing how income is computed, and it is independent of the VAT classification in this table. It is not a Green Invoice business type, it does not appear in this enum, and it changes nothing about which document type you issue or how VAT is applied. A business can be an osek patur for VAT and a micro-dealer for income tax at the same time, or either one alone. If a user says they are an עוסק זעיר, ask separately whether they are an osek patur or an osek murshe, because that is the answer that determines the document type.

Set vatType: 0 on documents and the system applies the correct VAT based on your business type. Override with vatType: 1 for exempt transactions or vatType: 2 for mixed documents.

Step 10.5: Suppliers and Expenses (the purchase side)

Everything above is the sales side. An Israeli business also has to record what it BUYS, because input VAT is only reclaimable against recorded supplier documents, and an exporter or any osek murshe lives on that deduction. The API covers this and the endpoints are easy to miss because they sit outside the document flow.

Two behaviours matter here. An expense created WITH an attached file becomes a draft, not an expense. Uploading a receipt or supplier invoice produces an expense draft that has to be reviewed and approved before it counts; until approval it is not an actual expense and will not appear in your totals. An expense created without a file is live immediately. If you are bulk-importing scanned supplier invoices and your reported expenses look far too low, unapproved drafts are the first thing to check.

Pair this with the allocation-number rule from Step 2 in the other direction. When YOU are the buyer, a supplier's tax invoice above the NIS 5,000 threshold needs its allocation number for you to deduct the input VAT. Record it when the document arrives rather than at period close.

Step 11: Webhooks

Tier requirement: webhook configuration requires the Extra plan or higher. Lower-tier accounts will not see the menu item.

Configure webhooks in the dashboard at: Personal Area (אזור אישי) > Developer Tools (כלים למפתחים) > Webhooks. The earlier "Settings > Developer Tools" path is no longer correct after the 2025 dashboard restructure.

Webhooks fire on document creation. The payload includes the full document object:

{
  "id": "document-uuid",
  "type": 320,
  "number": 12345,
  "currency": "ILS",
  "date": "2026-03-05",
  "total": 5850,
  "recipient": {
    "name": "Client Name",
    "emails": ["client@example.com"]
  },
  "items": [
    {
      "description": "Service",
      "quantity": 1,
      "price": 5000
    }
  ],
  "files": {
    "signed": true,
    "downloadLinks": {
      "he": "https://www.greeninvoice.co.il/api/v1/documents/download?d=...",
      "en": "https://www.greeninvoice.co.il/api/v1/documents/download?d=..."
    }
  }
}

Common webhook automations:

• Save PDF to Google Drive or Dropbox on invoice creation
• Update CRM when a receipt is issued
• Send Slack notification for new documents
• Sync invoices to external accounting systems

Consult references/api-reference.md for the complete webhook payload schema.

Step 12: Currencies and Exchange Rates

Green Invoice supports 27 document currencies. If currencyRate is not specified, the system uses Bank of Israel (BOI) exchange rates for the document date.

Common currencies: ILS, USD, EUR, GBP, JPY, CHF, CAD, AUD.

For multi-currency invoices, each income line item can specify its own currency and currencyRate. The totals are always calculated in the document's base currency.

Step 13: Sandbox Testing

Always test in the sandbox environment before going to production:

1. Register for a sandbox account at the Green Invoice sandbox
2. Use base URL: https://sandbox.d.greeninvoice.co.il/api/v1
3. Generate sandbox API credentials
4. Test all document creation, client management, and webhook flows
5. Verify VAT calculations and document linking work correctly
6. Switch to production URL when ready

Examples

Example 1: Create Tax Invoice-Receipt for Israeli Client

User says: "Create a hashbonit mas kabala for a client paying by bank transfer"

Actions:

1. Authenticate with Green Invoice API
2. Create client if new (POST /v1/clients with name, email, taxId)
3. Create document type 320 (Tax Invoice-Receipt) with payment type 4 (bank transfer)
4. Set signed: true for digital signature, attachment: true to email PDF

Result: Tax invoice-receipt created, digitally signed, and emailed to client as PDF.

Example 2: Monthly Recurring Invoices

User says: "I need to send monthly invoices to 3 retainer clients"

Actions:

1. Search existing clients: POST /v1/clients/search with client names
2. For each client, create document type 300 (Transaction Invoice) with description "Monthly Retainer - March 2026"
3. Set dueDate to payment terms date, lang based on client preference
4. Documents are emailed automatically when attachment: true

Result: Three invoices created and sent, each with correct payment terms and language.

Example 3: Issue Credit Note for Partial Refund

User says: "Refund half the amount on invoice #12345"

Actions:

1. Get original document: GET /v1/documents/{id}
2. Calculate refund amount (half of original total)
3. Create document type 330 (Credit Note) with linkedDocumentIds: ["original-id"] and linkType: "cancel"
4. Set income amount to negative refund value

Result: Credit note issued, linked to original invoice, with partial refund amount.

Example 4: Webhook Automation for Document Filing

User says: "Set up automatic filing when Green Invoice creates a document"

Actions:

1. Configure webhook URL in Green Invoice dashboard
2. Implement webhook endpoint that receives document payload
3. Extract type field to route document (invoice vs receipt vs credit note)
4. Use files.downloadLinks.he to download the Hebrew PDF
5. File to appropriate folder based on document type and date

Result: All new documents automatically downloaded and organized by type and month.

Bundled Resources

Scripts

• scripts/green-invoice-client.py -- Python helper for common Green Invoice API operations: authenticate, create documents, search clients, and list recent documents. Run: python3 scripts/green-invoice-client.py --help

References

• references/api-reference.md -- Complete Green Invoice API endpoint reference with request/response schemas, all enum codes, and payload examples. Consult when building API integrations or debugging request formats.
• references/document-workflows.md -- Common Israeli business document workflows: freelancer billing, retainer invoicing, refund flows, multi-currency billing, and e-commerce integration patterns. Consult when designing invoicing automation or choosing the correct document type sequence.

Recommended MCP Servers

Reference Links

Gotchas

• Green Invoice was rebranded to "Morning". The API base URL is still api.greeninvoice.co.il/api/v1, but a Morning host DOES now exist and is where the current OAuth token endpoint lives: api.morning.co/idp/v1/oauth/token. The hostname that does not resolve is api.morning.co.il. Do not tell a user that "the Morning API does not exist"; see Step 1 for both auth flows.
• The most common document type for Israeli clients paying immediately is type 320 (Tax Invoice-Receipt), not type 305 (Tax Invoice). Agents may default to 305 because it sounds like the standard invoice type.
• Osek Patur (exempt dealer) businesses cannot issue Tax Invoices (type 305). Agents may not check the business type before selecting a document type, causing API errors.
• VAT rate in Israel is 18% as of 2026, not 17%. The rate changed in January 2025 and agents trained on older data may use the outdated 17% figure in calculations.
• Payment type code 10 covers Israeli payment apps (Bit, PayBox), which are extremely common in Israel. Agents may not know these apps exist and default to bank transfer or credit card only. The app is named by appType (PaymentAppType): 1 Bit, 2 Pay, 3 PayBox, 5 Google Pay, 6 Apple Pay. There is no subAppType field, and code 2 is Pay, not Pepper Pay (Pepper Pay shut down on 10 Apr 2022 and is not in the enum at all).
• SHAAM allocation number requires a one-time gov.il authorization in the user's Morning account. This is the most common reason API integrations "look correct" but produce invoices the customer's accountant rejects. The integration is NOT automatic on signup. See Step 2 for the full setup, the 3-month expiry, and the renewal workflow. The threshold is NIS 5,000 net, in force since Jun 1, 2026 and the final step of the rollout. It was NIS 10,000 between Jan 1 and May 31, 2026, so treat any integration written earlier in 2026 as skipping allocation numbers on invoices between 5,000 and 10,000, which silently breaks the customer's input-VAT deduction. Pair with the israeli-e-invoice skill for end-to-end SHAAM compliance.
• Plan tiers gate features in the dashboard. API access requires the Best plan; webhooks require the Extra plan. A user on a lower tier will not see "API Keys" or "Webhooks" in the dashboard menu - this is not a bug, it is the gate. Check the plan before debugging missing menu items.
• Webhook signature verification. When the webhook has a secret, every delivery carries x-webhook-signature: the HMAC-SHA256 of the RAW body, keyed with your secret, hex-encoded. Capture the raw bytes before JSON parsing and compare in constant time, since re-serializing changes the digest. With no secret there is no signature, and the safety net is a server-to-server GET /v1/documents/{id} before trusting any payload field. Full header list in references/api-reference.md.
• The Apiary reference is gone; use developers.morning.co. https://greeninvoice.docs.apiary.io/ now returns HTTP 404 ("Apiary - Page not found"), verified in a browser on 2026-07-27. It was live at the previous review a month earlier, so older guidance, including earlier versions of this skill, still points there. The canonical reference is now https://developers.morning.co ("morning API Documentation (2.0.0)"), with https://app.greeninvoice.co.il/api as the signed-in explorer. When a field name is unclear, confirm it there rather than guessing.
• Rate limits. The ceiling is not published, so do not code against a specific requests-per-second number. Treat HTTP 429 as a soft, expected error: back off exponentially and retry rather than failing the job. For batch operations put the calls behind a queue with a concurrency limit you can tune down when you see 429s.

Troubleshooting

Error: "401 Unauthorized" on API calls

Cause: JWT token expired or invalid credentials Solution: Tokens expire. An OAuth access token is valid for exactly 1 hour, so a long batch run WILL hit this mid-way and must re-authenticate rather than fail. Re-authenticate against whichever flow you use: POST https://api.morning.co/idp/v1/oauth/token with grant_type=client_credentials (the documented path), or the legacy POST /v1/account/token with your API key ID and secret. On the OAuth endpoint, note that invalid_grant means the key is expired/revoked/pending and unauthorized_client means the subscription does not include API access; neither is fixed by retrying. Verify credentials in the Green Invoice dashboard under Personal Area (אזור אישי) > Developer Tools (כלים למפתחים) > API Keys. If the menu item is missing, the account is on a lower-tier plan; API access requires Best or higher.

Error: "Document type not supported for your business type"

Cause: an osek patur cannot issue a tax invoice. s.47(a) of the VAT Law gives the right to issue one only to an osek murshe (עוסק מורשה רשאי להוציא לגבי עסקה חייבת במס חשבונית מס). Solution: this rules out BOTH 305 (חשבונית מס) and 320 (חשבונית מס/קבלה), since 320 is a tax invoice with a receipt attached. An osek patur issues 300 (חשבון עסקה), 400 (קבלה) or 20 (חשבון / אישור תשלום). Routing an osek patur to 320 makes them issue a document that purports to charge VAT they are not registered to collect, and the recipient's input VAT is disallowed. Osek murshe and Ltd. companies can use all document types.

Error: "VAT calculation mismatch"

Cause: Mixing vatType settings between document level and income row level Solution: Set vatType: 0 at document level to use defaults. Only override at the income row level when a line's VAT treatment differs from the document. To apply a specific rate to a line (e.g. 0% on a zero-rated export line), set the row's vatRate (decimal), not vatType.

Error: "Client email required"

Cause: Creating a document without providing client email Solution: The client.emails array must contain at least one valid email when attachment: true. For documents that should not be emailed, set attachment: false.

Issue: B2B invoice over the threshold missing allocation number / customer's accountant rejected it

Cause: The Tax Authority authorization in the Morning dashboard was never set up, or it expired (3-month TTL). The API call succeeded (HTTP 200) but the resulting invoice has no מספר הקצאה. The recipient business cannot deduct input VAT without it. Solution: Direct the user to: אזור אישי > רשות המיסים > הוספת הרשאה in the Morning dashboard, complete the gov.il redirect, then re-issue or re-send the invoice. If the connection had been active and just expired, an in-system alert would have appeared 10 days before expiry. Add this authorization-status check to your runbook before any qualifying B2B invoice creation. Threshold: NIS 5,000 net, in force since Jun 1, 2026. If the integration was built earlier in 2026 against the NIS 10,000 figure, invoices between 5,000 and 10,000 are now going out without allocation numbers; re-check that band specifically. See Step 2 for full setup.

Issue: "API Keys" or "Webhooks" menu items missing in dashboard

Cause: The user's plan does not include this feature. API access requires Best+; webhooks require Extra+. Solution: Check the plan in Personal Area > Account/Subscription. Upgrade is required to proceed - there is no workaround at the API level.