Stripe Invoice record type (RT) will now be automatically set for all Invoices flowing in from Stripe. Every field on this RT syncs to/from the Stripe Invoices. To activate, go to Blackthorn Payments | Admin tab,
- Metadata Updates > Click Deploy Record Types
- Stripe Billing > Click Update to Stripe Invoice Record Type
An Invoice is a statement of the amount owed by a customer. Invoices can be generated periodically from Subscriptions or can be created as a one-off Invoice. A Stripe Invoice is represented as an Invoice object.
There are two record types on the Invoice object:
- Invoice: Generated by checkouts. Not every field of an Invoice is mapped to Stripe Invoices and Invoices can work independently from Stripe Invoices.
- Stripe Invoice: Set on all records flowing in from Stripe Billing. Every field on this record type is mapped to a Stripe Invoice.
No, custom record types are currently not supported.
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
Coupons (Amount Off and Percentage Off) applied to prorated Subscriptions in Stripe will be applied only at the Invoice level and not at the prorated Line Item level.
Automatically Generated Invoices
When a customer is charged successfully, an Stripe Invoice is generated in Stripe, and the Stripe Invoice is synced to Salesforce through a webhook.
Create a One-off Invoice
You can create an individual Stripe Invoice for a customer. To do this, check the Push To Stripe checkbox on the Stripe Invoice record.
The following fields are required:
- Customer
- Currency
- At least one Line Item with the Description and the Unit Price and Quantity fields populated.
A guest user must be assigned a custom permission set in addition to the Blackthorn | Payments (Site Guest User) permission set to have Read access to several standard objects to process the webhooks. The custom permission set must include the following object permissions:
- Account - Read
- Opportunity - Read
- Product2 - Read
Line Items
You need to add a Line Item before pushing the Invoice to Stripe. Depending on the record type of the Invoice, the Line Items inherit one of the below two record types -
- Line Item (Used for all non-Stripe Line Items for Invoice)
- Stripe Line Item (Used with the Stripe Invoice)
The Line Item needs to be populated with either a Unit Price and Quantity OR a Price and Product before the Invoice is pushed to Stripe.
Update Line Items
You can update existing Line Items when the Invoice Status = "Draft". This will trigger updates to the Stripe Invoice.
Add the field labeled Metadata to your page layout for the Line Item object. If there is a value populated from this parameter you will see the update in Salesforce once the webhooks process.
Log Partial Payment for Invoices as Non-Gateway Before the Due Date
For logging a partial payment as Non-Gateway (example - received via check) against an Invoice in Stripe, you can utilize the customer's Account Balance field in Salesforce. Before the Invoice is due, Stripe will automatically apply the balance amount from the customer's account balance. Webhooks will update the remaining balance on the customer record and a Transaction will be logged in Salesforce once the Invoice is paid completely.
Process Flow
-
Navigate to the Payment Gateway Customer object in Setup and drag the Account Balance field on to the page layout.
-
Set the field value with the paid Invoice amount.
-
You will see the balance amount reflected in your Stripe dashboard.
-
Check 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.
When the Invoice is partially paid, the Balance Due field on the Invoice will reflect the remaining amount to pay and Status will remain "Unpaid".
Mapping of Stripe Invoice Status to Invoice Status
There is a mapping 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.
Invoice Validations Before Syncing with Stripe
| Validation When | Error Message |
|---|---|
| Customer not set on SD | In order to push an Invoice to Stripe, you need to set the Customer. |
| Trying to modify the discount coupons on Invoice after pushed to Stripe | The discount coupon cannot be modified using the API. |
| Payment gateway not defined on the Customer record | Please set the Payment Gateway. |
| SD status = Draft and due date < TODAY | The Due Date for the invoice needs to be in future. |
| SD Status = Draft, billing Method = Send Invoice and Days Until Due & Due Date both not populated | If the Billing Method is Send Invoice, the Days Until Due field should be set. |
| Billing Method = Send Invoice, but customer email is blank | In order to create invoices that are sent to the customer, the Customer must have a valid email. |
| Billing Method = Charge automatically, but customer have no Payment method added, or is not valid or verified | In order to create invoices that are charged automatically, the Customer must have a Payment Method. Add a Payment Method or select Send Invoice. |
| Status of the SD invoice is Completed / Voided - we trying to change the status | Status cannot be updated. |
| Trying to update a sales document when Status is not Draft | Only draft SD can be updated. |
| When trying to add Line Item to SD whose status is not Draft | Line Items can be added only to Draft Invoices. |