• 03 Apr 2024
  • 4 Minutes to read
  • Dark


  • Dark

Article summary

New record type from 4.143+

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.
Can I create a custom record type?

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
Where will my Coupon be applied?

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.
Does your Site Guest User have the correct permissions?

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.

Looking to Update Metadata on the Line Item?

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

  1. Navigate to the Payment Gateway Customer object in Setup and drag the Account Balance field on to the page layout.

  2. Set the field value with the paid Invoice amount.
    M_03_02 process flow 1

  3. You will see the balance amount reflected in your Stripe dashboard.
    M_03_02 process flow 2

  4. Check the Stripe Invoice to see the applied amount.
    M_03_02 process flow 3

  5. Once the Invoice is paid, a Transaction will be created and logged against the Invoice in Salesforce.
    M_03_02 process flow 4

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 StatusInvoice Status

Invoices with Status = "Completed" cannot be edited.

Invoice Validations Before Syncing with Stripe

Validation WhenError Message
Customer not set on SDIn order to push an Invoice to Stripe, you need to set the Customer.
Trying to modify the discount coupons on Invoice after pushed to StripeThe discount coupon cannot be modified using the API.
Payment gateway not defined on the Customer recordPlease set the Payment Gateway.
SD status = Draft and due date < TODAYThe 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 populatedIf the Billing Method is Send Invoice, the Days Until Due field should be set.
Billing Method = Send Invoice, but customer email is blankIn 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 verifiedIn 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 statusStatus cannot be updated.
Trying to update a sales document when Status is not DraftOnly draft SD can be updated.
When trying to add Line Item to SD whose status is not DraftLine Items can be added only to Draft Invoices.

What's Next