Quotes from an invoice

Upload a purchase invoice, get every line item read, categorised and quoted, then correct a line and check eligibility rules.

Use these endpoints when a customer brings a receipt instead of a product in your catalog: a direct-to-consumer registration, a service counter, or an in-store sale of a plan for something bought elsewhere. SureBright reads the invoice, categorises each line, prices plans for each line, and keeps the result as a lead you can edit line by line. A separate endpoint applies the eligibility rules on their own.

No authentication header is needed for these endpoints.

The two invoice endpoints share a limit of 50 requests per minute across all callers. Over the limit they return 429 with a Retry-After header (seconds).

Upload an invoice#

POST https://{HOST_NAME}/quote/api/lead/invoice/upload

Send the invoice as multipart/form-data.

filerequired

The invoice. PDF, PNG, JPEG, WebP or TIFF, up to 20 MB.

stringrequired

Your store identifier.

stringrequired

US or CA.

string

Invoice currency.

string

Your account identifier. Resolved from the store when omitted.

string

State or province, when prices vary by region.

string

Default CUSTOM.

string

An existing lead to replace with this invoice instead of creating a new one.

bash
curl -X POST 'https://{HOST_NAME}/quote/api/lead/invoice/upload' \
  -F 'file=@receipt.pdf;type=application/pdf' \
  -F 'storeId=example-pos-store' \
  -F 'country=US'

Response#

leadIdstring

The lead holding this invoice. Use it to edit lines.

invoiceAssetIdstring

Reference to the processed file.

customerobject

What was read from the invoice: firstName, lastName, email, mobilePhone, and address (addressLine1, addressLine2, city, state, country, zip). Empty strings when not found.

lineItemsListobject[]

One entry per line read from the invoice.

Errors#

CodeBodyMeaning
400{"isError": true, "message": "File is required (field name: 'file')"}No file part
400{"isError": true, "message": "storeId and country are required"}Missing form fields
400{"isError": true, "message": "Unsupported file type: ..."}MIME type not in the supported list
429{"isError": true, "message": "Rate limit exceeded: 50/min. Retry in Ns."}Shared limit reached; see Retry-After
500{"isError": true, "message": "..."}The invoice could not be read (including files over 20 MB), or the lead could not be saved

Correct a line item#

PUT https://{HOST_NAME}/quote/api/lead/{leadId}/invoiceLineItem/{lineItemId}

Send any subset of the editable fields. A changed productTitle or description re-classifies the line unless you also send sbCategoryId, which wins. The line is always re-priced.

stringrequired
From the upload response.
stringrequired
From lineItemsList.
string
New product name.
string
New description.
number
Corrected unit price.
string
Corrected purchase date.
number
Corrected quantity.
string
Force the SureBright category instead of re-classifying.
bash
curl -X PUT 'https://{HOST_NAME}/quote/api/lead/7f3a9c2e-4b1d-4e8f-9a6c-2d5b8e1f0a3c/invoiceLineItem/0c9e8d7b-6a5f-4e3d-2c1b-0a9f8e7d6c5b' \
  -H 'Content-Type: application/json' \
  -d '{ "productPrice": 1299.00, "productTitle": "Aero 2 Electric Scooter" }'

Response: {"isError": false, "leadId": "...", "lineItem": {...}} where lineItem has the same fields as an entry of lineItemsList.

CodeBodyMeaning
400{"isError": true, "message": "No updatable fields provided"}Body had none of the editable fields
404{"isError": true, "message": "Lead not found"} or "Line item not found"Unknown ids
429as aboveShared limit reached
500{"isError": true, "message": "Failed to persist line item update"}Save failed

Check eligibility rules#

POST https://{HOST_NAME}/quote/api/eligibility/evaluate

Runs the eligibility rules for an invoice and its lines without quoting. The rules that apply depend on the calling application, identified by the site-id header; SureBright gives you the identifier for yours. The same rules run inside By Category when that call carries a site-id header: an invoice-level block returns 422, and blocked lines are listed in blacklistedItems.

HeaderDescriptionRequired
site-idYour application identifierYes
Content-Typeapplication/jsonYes
object

purchaseDate (MM/DD/YYYY or YYYY-MM-DD), and optionally retailerName and totalAmount.

object[]required

Each with productTitle and manufacturerName; other fields are passed through unchanged.

bash
curl -X POST 'https://{HOST_NAME}/quote/api/eligibility/evaluate' \
  -H 'site-id: YOUR_APP_ID' -H 'Content-Type: application/json' \
  -d '{ "invoice": { "purchaseDate": "2026-10-20" },
        "lineItemList": [ { "productTitle": "Aero 2 Electric Scooter", "manufacturerName": "Aero" } ] }'

Rules#

RuleError codeSeverityFires when
INVOICE_AGE_LIMITWARRANTY_WINDOW_EXCEEDEDBLOCK_INVOICEinvoice.purchaseDate is more than 90 days ago
PRODUCT_BLACKLISTPRODUCT_NOT_SUPPORTEDBLOCK_LINE_ITEMThe product is one SureBright does not cover
MANUFACTURER_BLOCKMANUFACTURER_NOT_SUPPORTEDBLOCK_LINE_ITEMThe manufacturer is one SureBright does not cover

A rule is skipped, not failed, when the field it needs is missing (purchaseDate for the age rule, productTitle for the product rule, manufacturerName for the manufacturer rule). Not every application runs the age rule.

Response#

Returned with 200 for eligible and ineligible results alike.

invoiceobject

isEligible, error (the invoice-level hit or null), notices.

lineItemListobject[]

Your lines, each with isEligible, error (the blocking hit or null) and notices. Empty when the invoice itself is blocked.

summaryobject

blockedInvoice, blockedLineItemCount, and userMessage, a sentence you can show the customer.

A hit is {ruleId, errorCode, severity, message, match}.

CodeBodyMeaning
400errorCode: MISSING_SITE_IDHeader missing
400errorCode: INVALID_REQUESTlineItemList is not an array
400errorCode: UNKNOWN_APPsite-id is not registered
500errorCode: INTERNAL_ERRORUnexpected failure