Create invoice

📘
API Refs

Staging: Create invoice

This endpoint creates a new invoice for a policyholder.

Request body

Name	Type	Description	Required
policyholderId	number	ID of the policyholder	yes
carrierId	number	ID of the insurance carrier	yes
grossPremium	number	Gross premium amount	yes
effectiveDate	string	Effective date of the invoice (ISO 8601)	yes
expirationDate	string	Expiration date of the invoice (ISO 8601)	yes
mgaId	number	ID of the MGA	no
commission	number	Commission amount	no
taxes	number	Tax amount	no
serviceFee	number	Service fee amount	no
policyId	string	External policy ID (max 50 chars)	no
brokerCode	string	Broker code associated with this invoice (max 50 chars)	no
memo	string	Memo for the invoice (max 256 chars)	no
downPayment	number	Down payment amount	no
financeAmount	number	Finance amount	no
shouldBeSigned	boolean	Whether the invoice should be signed	no
paymentMethod	string	Desired payment method ("card", "us_bank_account", or "affirm")	no

Example request

{
  "policyholderId": 123,
  "carrierId": 456,
  "grossPremium": 1200.50,
  "effectiveDate": "2024-01-01T00:00:00Z",
  "expirationDate": "2025-01-01T00:00:00Z",
  "commission": 120.05,
  "taxes": 50.00,
  "policyId": "POL-98765",
  "brokerCode": "BRK-001",
  "paymentMethod": "us_bank_account"
}

Example with Affirm

{
  "policyholderId": 123,
  "carrierId": 456,
  "grossPremium": 2500.0,
  "effectiveDate": "2024-01-01T00:00:00Z",
  "expirationDate": "2025-01-01T00:00:00Z",
  "commission": 250.0,
  "taxes": 100.0,
  "policyId": "POL-98766",
  "brokerCode": "BRK-001",
  "paymentMethod": "affirm"
}

Response

A successful request returns a 201 Created status code with the created invoice ID and a payment URL:

Name	Type	Description
invoiceId	number	ID of the created invoice (also returned in the `location` header)
paymentUrl	string \| null	Link the policyholder can use to pay the invoice (see below)

paymentUrl depends on how the invoice was created:

No paymentMethod provided — the payment link that is emailed to the policyholder. The invoice is finalized and the same link is returned in the response.
paymentMethod provided — the checkout URL for that payment method.
Draft invoice (amounts/dates not yet set) — null. A payment link does not exist until the invoice is finalized.

{
  "invoiceId": 789,
  "paymentUrl": "https://agent.snaprefund.io/invoice-payment-method?token=..."
}

Payment Method Notes

Affirm Payment Method

When using "affirm" as the payment method, the following validation rules apply:

Amount Requirements: The total invoice amount (grossPremium + taxes + serviceFee) must be between $35 and $30,000
Account Configuration: Affirm must be enabled for your account by an administrator
Validation Errors:
- If the amount is outside the allowed range, you'll receive a 400 Bad Request error
- If Affirm is not enabled for your account, you'll receive a 403 Forbidden error

📘
Important
The Affirm validation occurs before invoice creation. Ensure your invoice total meets the minimum requirement of $35 to use Affirm financing.