BillptCreateInvoiceFromShopify

Description

Receives a Shopify order payload (from a webhook or previous node) and automatically creates a fiscal document in Bill.pt. Handles the full flow:

1. Looks up the customer contact by email in Bill.pt — creates it from billing_address if not found
2. Resolves VAT tax IDs by matching Shopify tax_lines rates against a DataStore tax group
3. Calculates net prices (removing VAT when taxes_included: true)
4. Creates the document (FT, FR, ORC or NC) with the correct series

Configuration

Field	Type	Required	Description
credentials_id	credentials	Yes	Bill.pt credential
document_type	select	Yes	FT (Invoice), FR (Invoice-Receipt), ORC (Quote), NC (Credit Note)
tax_group	text	No	DataStore group name with Bill.pt tax map (see Tax Map section)
default_tax_id	text	No	Fallback Bill.pt tax ID if no DataStore group or no match found
series_group	text	No	DataStore group name with Bill.pt series (row_data = series object with id and nome)
series_name	text	No	Series name to look up in the DataStore group (e.g. FHPT)
series_id	text	No	Direct numeric series ID — takes priority over series_name
use_order_date	select	No	Use Shopify order date (yes) or today’s date (no). Default: yes. Use no if error 292 appears (AT-communicated series may reject backdated invoices)
finalized	select	No	yes = finalize document (default), no = save as draft
exchange_rate	text	No	Exchange rate vs EUR (default: 1). Only used for non-EUR orders
contact_id	text	No	Override: use this Bill.pt contact instead of searching by email
observations	textarea	No	Additional notes. Shopify order reference is always appended automatically

Credentials

Requires a billpt credential with:

• API Token: Bill.pt API access token
• Environment: production or sandbox

Tax Map (DataStore)

Create a DataStore group (e.g. billpt_taxes) populated with the output of the BillptGetTaxes node. Each row must have row_data with the full Bill.pt tax object (id, valor, nome).

The node matches each Shopify tax_line by converting the decimal rate to a percentage integer:

Shopify tax_line.rate	Converted	Matched valor	Resolved imposto_id
0.23	23	IVA 23	33891
0.13	13	IVA 13	33892
0.06	6	IVA 6	33893

Matching order: tax_line.title → percentage integer → decimal string → default_tax_id fallback.

Series Map (DataStore)

Create a DataStore group (e.g. billpt_series) populated with the output of BillptGetSeries. Set series_group: billpt_series and series_name: FHPT to automatically resolve the series ID.

If series_id is set directly, it takes priority.

Price Calculation

When the Shopify order has taxes_included: true, the node extracts the net unit price before creating the document:

net_price = shopify_price / (1 + tax_rate)

Discounts (total_discount) are folded directly into the unit price:

final_net_price = net_price - (total_discount / quantity / (1 + tax_rate))

Line items with price == 0 are skipped.

Input

Expected input: a Shopify Order object (from webhook or Shopify API). Key fields used:

{
  "id": 6684429451477,
  "order_number": 14522,
  "email": "customer@example.com",
  "taxes_included": true,
  "currency": "EUR",
  "created_at": "2025-03-24T10:00:00Z",
  "billing_address": {
    "name": "John Doe",
    "address1": "Rua Example 123",
    "city": "Lisboa",
    "zip": "1000-001",
    "country_code": "PT",
    "phone": "+351900000000"
  },
  "line_items": [
    {
      "title": "Product Name",
      "price": "25.95",
      "quantity": 1,
      "total_discount": "0.00",
      "tax_lines": [{ "title": "IVA 23", "rate": 0.23, "price": "4.86" }]
    }
  ]
}

Output

{
  "success": true,
  "document": { ... },
  "document_id": 789,
  "document_number": "FT FHPT/2025/1",
  "contact_id": 212478,
  "total": 25.95,
  "shopify_order_id": 6684429451477,
  "shopify_order_number": 14522,
  "message": "Documento FT FHPT/2025/1 creado para pedido Shopify 14522"
}

Error 292

Error {"error": ["292"]} from Bill.pt means the series rejects the document date. This happens with AT-communicated series in Portugal when the invoice date is too far in the past.

Solution: Set use_order_date: no to use today’s date instead of the Shopify order date.

Notes

• A new Bill.pt contact is created if the customer email is not found. Contact search may fail silently if the Bill.pt API does not support the pesquisa parameter — in that case a new contact is always created.
• The Shopify order reference (Shopify Order #XXXXX) is always appended to observations.
• For non-EUR currencies, set exchange_rate to the appropriate rate.
• Use finalized: no to create drafts for review before finalizing.

Related Nodes

• BillptGetTaxes - Get tax IDs to build the tax DataStore group
• BillptGetSeries - Get series IDs to build the series DataStore group
• BillptGetContacts - Look up existing contacts
• BillptCreateDocument - Create documents manually
• BillptSendDocumentEmail - Send the invoice by email
• BillptCreateReceipt - Create a receipt for the invoice