An Invoice states the amount a customer owes. Invoices can be generated periodically from Subscriptions or as a one-off Invoice. A Stripe Invoice is created from the Blackthorn Invoice (bt_stripe__Sales_Document__c) object.
Types of Invoices
There are two types of Invoices created by the Blackthorn Invoice object: Invoice and Stripe Invoice.
Invoices
The checkout process generates Invoices. Not all fields from a Blackthorn Invoice are mapped to a Stripe Invoice, and Invoices can work independently from Stripe Invoices.
Stripe Invoices
A Stripe Invoice is included with all records coming from Stripe Billing. All fields on a Stripe Invoice are mapped to an Invoice.
The following list includes the Stripe Invoice fields that are mapped to an Invoice:
Name
Customer (Mandatory)
Subscription
Stripe Coupon
Stripe Invoice Id
Stripe Hosted Invoice Link
Currency
Bill To Street
Bill To Street 2
Bill To City
Bill To State
Bill To Country
Bill To Postal Code
Ship To Street
Ship To Street 2
Ship To City
Ship To State
Ship To Country
Ship To Postal Code
Automatically Generated Invoices
When a customer’s transaction is complete and the charge is successful, Stripe generates a Stripe Invoice, which is synced to Salesforce through a webhook.
NOTE: Invoices are only generated automatically from Stripe Billing. Payment Schedules cannot create Invoices.
One-Off Invoices
You can create an individual Stripe Invoice for a customer.
Add Line Items
Before you push the Invoice to Stripe, you must add at least one Line Item (bt_stripe__Line_Item__c) to the Invoice. The Line Item(s) record will inherit one of the following record types.
Record Type = "Line Item" This is used for all non-Stripe Line Items on an Invoice.
Record Type = "Stripe Line Item" This is used for Stripe Invoices.
The Line Item record(s) must include either a Unit Price and Quantity, OR a Price and Product, before the Invoice can be pushed to Stripe.
Create a One-Off Invoice
Go to the Invoice you want to sync to Stripe.
Confirm that the following fields contain a value.
Customer
Currency
Confirm that the Invoice has at least one Line Item with the Description and the Unit Price and Quantity fields populated.
Check the Push To Stripe checkbox.
Click Save.
Update Line Items
You can update existing Line Items when the Invoice Status = "Draft." This will trigger updates to the Stripe Invoice.
Log a Partial Payment as Non-Gateway
If you receive a partial payment, such as a check, you can log it as non-gateway against an Invoice in Stripe by using the customer’s Payment Gateway Customer Account Balance field in Salesforce.
Before the Invoice is due, Stripe will automatically apply the amount from the customer's Account Balance field. Webhooks will update the remaining balance on the customer record. A Salesforce Transaction record will be created once the Invoice is paid in full.
If the Invoice remains partially paid, the Invoice’s Balance Due field will reflect the remaining amount due, and the Invoice’s Payment Status will be set to "Unpaid."
Steps
Go to Setup.
In the Quick Find box, enter and click "Payment Gateway Customer."
Click the Page Layouts tab.
Select the "Stripe Customer Layout."
Drag and drop the Account Balance field onto the page layout.
Click Save.
Open the Payment Gateway Customer record and refresh the page.
Click the Pencil icon next to the Account Balance field.
Enter the value of the paid Invoice amount.
Click Save.
You will see the Account Balance reflected in your Stripe dashboard.
Open the Stripe Invoice to see the applied amount.
Once the Invoice is paid, a Transaction will be created and logged against the Invoice in Salesforce.
Mapping a Stripe Invoice Status to an Invoice Status
The following table shows the mapping relationship between the Stripe Invoice statuses and the Invoice statuses:
Stripe Invoice Status | Invoice Status |
|---|---|
draft | Draft |
open | Sent |
paid | Completed* |
uncollectible | Rejected |
void | Voided |
*Invoices with Status = "Completed" cannot be edited.
Troubleshooting & FAQs
Troubleshooting
Review the following scenarios that may cause an error before syncing an Invoice with Stripe.
Scenario | Error Message |
|---|---|
The Invoice Customer field is blank. | To push an Invoice to Stripe, you must enter a value in the Customer field. |
Modify the discount Code on an Invoice after the Invoice is pushed to Stripe | The discount Code cannot be modified using the API. |
The Payment Gateway field on the Payment Gateway Customer record is not defined. | Add a Payment Gateway to the Payment Gateway field. |
Invoice Status = "Draft" and Due Date = "before today" | The Invoice's Due Date must be in the future. |
Invoice Status = "Draft", Billing Method = "Send Invoice," and Days Until Due and Due Date are blank | If the Billing Method is set to "Send Invoice," the Days Until Due field must contain a value. |
The Invoice's Billing Method is set to "Send Invoice," but Payment Gateway Customer's Email field is blank. | To create an Invoice to send to a Payment Gateway Customer, the Email field must have a valid email. |
The Invoice's Billing Method is set to "Charge Automatically," but the Invoice's Payment Method field is blank, not valid, or not verified. | To create an Invoice that will be charged automatically, the Payment Method field must have a payment method. Add a Payment Method or change the Billing Method to "Send Invoice." |
Try to change the Invoice Status when it is set to "Completed" or "Voided." | The Invoice Status field cannot be changed if it is set to "Completed" or "Voided." |
Try to update an Invoice when the Status is set to anything BUT "Draft." | An Invoice can only be updated when the Status is set to "Draft." |
Add a Line Item to an Invoice when the Status is set to anything but "Draft." | Line Items can only be added to an Invoice when the Status is set to "Draft." |
FAQs
Q: Can I create a custom record type?
A: No, custom record types are currently not supported.
Q: How will my coupon (discount Code) be applied?
A: Coupons (Code Discount Percentage or Discount Amount) applied to prorated Subscriptions in Stripe will be applied only at the Invoice level, not at the prorated Line Item level.
Q: What permissions does my Site Guest User need?
A: A guest user must be assigned the Blackthorn | Payments (Site Guest User) permission set and custom permissions to have Read access to several standard objects, which are required to process the webhooks. The custom permission set must include the following object permissions:
Account - Read
Opportunity - Read
Product2 – Read
Q: How do I update the Metadata field on a Line Item?
A: Add the Metadata field to the Line Item’s page layout. If a value is populated from this parameter, you will see the update in Salesforce once the webhook process is complete.