---
title: "Invoices"
slug: "stripe-billing-invoices"
updated: 2025-09-17T15:42:49Z
published: 2025-09-17T15:42:49Z
canonical: "docs.blackthorn.io/stripe-billing-invoices"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blackthorn.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Invoices

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

1. Go to the Invoice you want to sync to Stripe.
2. Confirm that the following fields contain a value.
  - **Customer**
  - **Currency**
3. Confirm that the Invoice has at least one Line Item with the **Description** and the **Unit Price** and **Quantity** fields populated.
4. Check the **Push To Stripe** checkbox.
5. 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

1. Go to Setup.
2. In the Quick Find box, enter and click "Payment Gateway Customer."
3. Click the Page Layouts tab.
4. Select the "Stripe Customer Layout."
5. Drag and drop the **Account Balance** field onto the page layout.
6. Click **Save**.
7. Open the Payment Gateway Customer record and refresh the page.
8. Click the **Pencil** icon next to the **Account Balance** field.
9. Enter the value of the paid Invoice amount. ![M_03_02 process flow 1](https://cdn.document360.io/f977eec0-500f-40a3-b663-724a51f78075/Images/Documentation/M_03_02%20process%20flow%201.png)
10. Click **Save**.

You will see the **Account Balance** reflected in your Stripe dashboard.

![M_03_02 process flow 2](https://cdn.document360.io/f977eec0-500f-40a3-b663-724a51f78075/Images/Documentation/M_03_02%20process%20flow%202.png)

Open the Stripe Invoice to see the applied amount.

![M_03_02 process flow 3](https://cdn.document360.io/f977eec0-500f-40a3-b663-724a51f78075/Images/Documentation/M_03_02%20process%20flow%203.png)

Once the Invoice is paid, a Transaction will be created and logged against the Invoice in Salesforce.

![M_03_02 process flow 4](https://cdn.document360.io/f977eec0-500f-40a3-b663-724a51f78075/Images/Documentation/M_03_02%20process%20flow%204.png)

## 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.