How WhatsApp invoice messages work and how to use them

WhatsApp Invoice Message sends the invoice to the customer as a PDF attachment on WhatsApp when the invoice is generated. Sending requires a working WhatsApp Business ID, the customer's saved phone number, and the customer's WhatsApp Invoice consent.

Configure WhatsApp invoice message settings

Enabling WhatsApp invoice messaging starts with configuring two settings. Open Integrations at /configuration/integrations and configure WhatsApp Business messaging secret WHATSAPP_TOKEN . Then, in the Configuration view at /configuration , verify that WHATSAPP_PHONE_NUMBER_ID contains WhatsApp Business phone number identifier.

Both values must be non-empty. WHATSAPP_TOKEN is a secret, so an already stored value will be displayed in a masked state. Do not include the token in a customer message, screenshot, or support request. The phone number identifier is not the same as the phone number visible to the customer.

Verify customer number and consent

The recipient of the WhatsApp invoice is the phone number stored in the customer's account. Before ordering, make sure that the number belongs to the right customer and is in a format accepted by WhatsApp Business . A blank phone number will prevent the sending without interrupting the normal invoice generation.

The customer's WhatsApp invoice consent is stored in the whatsAppInvoice field, and the permanent customer information is grant_whatsapp .

• Consent can be saved at checkout or through the customer's information in the user interface where the option is enabled.
• When the customer logs in later, the saved consent is returned to the session and used in the next invoice sending decision.
• Do not enable consent on behalf of a customer without the customer's explicit choice.

When is the WhatsApp invoice message sent?

A WhatsApp invoice message is attempted to be sent when an invoice is generated and all sending conditions are met. The system also checks that the session's whatsAppInvoice consent is enabled, the customer account has a phone number, and WHATSAPP_TOKEN and WHATSAPP_PHONE_NUMBER_ID are set.

If any of the conditions are missing, the WhatsApp invoice message will not be sent. The recipient is not determined from the billing address or a separate WhatsApp setting, but the message is addressed to the phone number stored in the customer's account. An error in the WhatsApp transmission will be logged in the server log, but the error will not prevent further processing of the invoice email.

What does the customer get on WhatsApp?

The customer receives a document message on WhatsApp with the attached content of the invoice in PDF format. The name of the PDF file is formed from the invoice title: the title is trimmed to match the file name and .pdf is added to the end. If the title does not contain a valid name, the format order-<orderId>.pdf is used.

The caption for the document message is retrieved from the invoice translation key THANKS_FOR_ORDER_WHATSAPP_MESSAGE . The Finnish value of the key is Kiitos tiläustättänne . If the translation value is empty, the system uses the default text Thank you for your order! . Edit the visible caption in the invoice translations and check it in each language used by the store.

Test WhatsApp invoice message

It is a good idea to test the WhatsApp invoice message functionality with a separate test customer whose phone number you have permission to send messages to. Save the number and WhatsApp invoice consent for the test customer, create an invoice, and check that the correct order PDF with the correct file name and caption arrives on WhatsApp.

At the same time, check that the normal invoice email is generated as expected. Do not use the creation of the invoice as proof of success: WhatsApp first downloads the PDF document and then sends a separate document message, so both steps must be successful.

If the WhatsApp invoice message does not arrive

If the WhatsApp invoice message does not arrive, check the following in this order:

1. The customer's account has a valid phone number.
2. The customer's WhatsApp invoice consent is saved and enabled in the session.
3. WHATSAPP_TOKEN is configured in the Integrations view.
4. WHATSAPP_PHONE_NUMBER_ID is configured in the Configuration view.
5. The invoice was generated during the order processing in question.
6. There is no WhatsApp document download or upload error in the server log.

If the settings and customer information are correct but the message is missing, please collect the order ID, invoice generation time, the remainder of the recipient's phone number, and the exact log error for support. Do not send the WhatsApp token or the full phone number in the support request.