Configure automatic invoice issuance for a subscription

Configure a subscription to automatically issue NFS-e (service invoices) for the payments generated during the recurrence.

Issuance will follow the timing, municipal service, and tax rules defined in the configuration.

Before you start

Before configuring:

• create the subscription and store its ID;
• confirm that the account is enabled to issue invoices;
• define the municipal service;
• validate the fiscal and tax information used in the issuance.

How it works

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Create the subscription"] --> B["Define the municipal service"]
    B --> C["Define when to issue"]
    C --> D["Configure automatic issuance"]
    D --> E["Asaas generates the payment"]
    E --> F["Issue the invoice"]
    F --> G["Track via Webhook"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px,font-size:17px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px,font-size:17px

    class A inicio
    class B,C,D,E,F validacao
    class G sucesso

    linkStyle default stroke:#94A3B8,stroke-width:2px

1. Define the municipal service

When the municipality provides the registered services, query:

GET /v3/fiscalInfo/services

Use the returned id in municipalServiceId.

See the endpoint List municipal services.

If the municipality does not provide the listing, get the service code from the city hall and provide municipalServiceCode.

2. Choose when to issue the invoice

The effectiveDatePeriod field defines when the invoice is issued:

When using BEFORE_PAYMENT_DUE_DATE, provide daysBeforeDueDate with one of the allowed values:

5, 10, 15, 30, or 60

For ON_NEXT_MONTH, receivedOnly can restrict issuance to paid payments. When not provided, its default value is false.

3. Create the configuration

Use the subscription ID:

POST /v3/subscriptions/{id}/invoiceSettings

In addition to the issuance period, provide the municipal service data and the taxes block corresponding to the account's tax situation.

Example of a rule to issue only after payment:

{
  "effectiveDatePeriod": "ON_PAYMENT_CONFIRMATION"
}

This snippet represents only the issuance rule. Complete the request with the tax data required for your operation.

See the endpoint Create configuration for issuing invoices.

Expected result

The configuration will be linked to the subscription.

New payments generated by the recurrence will start using these rules for automatic invoice issuance.

Existing payments will only be considered when they meet the configuration's conditions.

4. Track the invoices

The automatic creation of the invoice does not mean it has been authorized by the city hall.

Use the invoice Webhooks to track processing, especially:

• INVOICE_AUTHORIZED: invoice authorized;
• INVOICE_ERROR: issuance failure.

See the Events for invoices.

To list the invoices linked to the subscription's payments, use:

GET /v3/subscriptions/{id}/invoices

See the endpoint List invoices for subscription charges.

If you need to change the configuration

The issuance rules can be updated through:

PUT /v3/subscriptions/{id}/invoiceSettings

Invoices already issued are not modified. The new rules apply to upcoming payments or payments that do not yet have an invoice created.

See the endpoint Update configuration for issuing invoices.

Common errors

If the invoice is not issued, check:

• whether the subscription has an issuance configuration;
• whether the account is enabled to issue invoices;
• whether the provided municipal service is valid;
• whether effectiveDatePeriod and its dependent fields are correct;
• whether the required taxes data was provided according to the tax regime.

Next steps

• Track invoice events
• List the subscription's invoices
• Retrieve the issuance configuration
• Update the issuance configuration
• Remove the issuance configuration
• See the Subscriptions FAQ