---
title: "Quotes from an invoice"
description: "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.

<Warning>
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).
</Warning>

## Upload an invoice

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

Send the invoice as `multipart/form-data`.

<ParamField body="file" type="file" required>
  The invoice. PDF, PNG, JPEG, WebP or TIFF, up to 20 MB.
</ParamField>
<ParamField body="storeId" type="string" required>
  Your store identifier.
</ParamField>
<ParamField body="country" type="string" required>
  `US` or `CA`.
</ParamField>
<ParamField body="currency" type="string">
  Invoice currency.
</ParamField>
<ParamField body="storeParentId" type="string">
  Your account identifier. Resolved from the store when omitted.
</ParamField>
<ParamField body="province" type="string">
  State or province, when prices vary by region.
</ParamField>
<ParamField body="platform" type="string">
  Default `CUSTOM`.
</ParamField>
<ParamField body="leadId" type="string">
  An existing lead to replace with this invoice instead of creating a new one.
</ParamField>

```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

<ResponseField name="leadId" type="string">
  The lead holding this invoice. Use it to edit lines.
</ResponseField>
<ResponseField name="invoiceAssetId" type="string">
  Reference to the processed file.
</ResponseField>
<ResponseField name="customer" type="object">
  What was read from the invoice: `firstName`, `lastName`, `email`, `mobilePhone`, and `address` (`addressLine1`, `addressLine2`, `city`, `state`, `country`, `zip`). Empty strings when not found.
</ResponseField>
<ResponseField name="lineItemsList" type="object[]">
  One entry per line read from the invoice.
  <Expandable title="fields">
    <ResponseField name="lineItemId" type="string">
      Identifier for edits.
    </ResponseField>
    <ResponseField name="productTitle" type="string">
      Product name as read.
    </ResponseField>
    <ResponseField name="description" type="string">
      Description as read.
    </ResponseField>
    <ResponseField name="quantity" type="number">
      Quantity, default 1.
    </ResponseField>
    <ResponseField name="productPrice" type="number">
      Unit price (the line total when no unit price was printed).
    </ResponseField>
    <ResponseField name="purchaseDate" type="string">
      The invoice date, applied to every line.
    </ResponseField>
    <ResponseField name="sbCategoryId" type="string">
      SureBright category the line was classified into; empty when classification failed.
    </ResponseField>
    <ResponseField name="categoryName" type="string">
      Name of that category.
    </ResponseField>
    <ResponseField name="confidence" type="number">
      Classification confidence, when the classifier reports one.
    </ResponseField>
    <ResponseField name="quotes" type="object[]">
      One entry per plan term: `tenure`, `price`, `monthlyPrice`. Empty when the line could not be quoted.
    </ResponseField>
    <ResponseField name="quoteError" type="string">
      Why `quotes` is empty: `MISSING_SB_CATEGORY`, `INVALID_PRICE`, `POLICY_BAND_NOT_FOUND`, `INVALID_COUNTRY_<code>`, `QUOTE_FAILED` or `QUOTE_EXCEPTION`. `null` when quotes were produced.
    </ResponseField>
    <ResponseField name="lastQuotedAt" type="string">
      When the line was last priced.
    </ResponseField>
  </Expandable>
</ResponseField>

### Errors

| Code | Body | Meaning |
|------|------|---------|
| `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.

<ParamField path="leadId" type="string" required>From the upload response.</ParamField>
<ParamField path="lineItemId" type="string" required>From `lineItemsList`.</ParamField>
<ParamField body="productTitle" type="string">New product name.</ParamField>
<ParamField body="description" type="string">New description.</ParamField>
<ParamField body="productPrice" type="number">Corrected unit price.</ParamField>
<ParamField body="purchaseDate" type="string">Corrected purchase date.</ParamField>
<ParamField body="quantity" type="number">Corrected quantity.</ParamField>
<ParamField body="sbCategoryId" type="string">Force the SureBright category instead of re-classifying.</ParamField>

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

| Code | Body | Meaning |
|------|------|---------|
| `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 |
| `429` | as above | Shared 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`.

| Header | Description | Required |
|--------|-------------|----------|
| site-id | Your application identifier | Yes |
| Content-Type | application/json | Yes |

<ParamField body="invoice" type="object">
  `purchaseDate` (`MM/DD/YYYY` or `YYYY-MM-DD`), and optionally `retailerName` and `totalAmount`.
</ParamField>
<ParamField body="lineItemList" type="object[]" required>
  Each with `productTitle` and `manufacturerName`; other fields are passed through unchanged.
</ParamField>

```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

| Rule | Error code | Severity | Fires when |
|------|-----------|----------|------------|
| `INVOICE_AGE_LIMIT` | `WARRANTY_WINDOW_EXCEEDED` | `BLOCK_INVOICE` | `invoice.purchaseDate` is more than 90 days ago |
| `PRODUCT_BLACKLIST` | `PRODUCT_NOT_SUPPORTED` | `BLOCK_LINE_ITEM` | The product is one SureBright does not cover |
| `MANUFACTURER_BLOCK` | `MANUFACTURER_NOT_SUPPORTED` | `BLOCK_LINE_ITEM` | The 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.

<ResponseField name="invoice" type="object">
  `isEligible`, `error` (the invoice-level hit or `null`), `notices`.
</ResponseField>
<ResponseField name="lineItemList" type="object[]">
  Your lines, each with `isEligible`, `error` (the blocking hit or `null`) and `notices`. Empty when the invoice itself is blocked.
</ResponseField>
<ResponseField name="summary" type="object">
  `blockedInvoice`, `blockedLineItemCount`, and `userMessage`, a sentence you can show the customer.
</ResponseField>

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

| Code | Body | Meaning |
|------|------|---------|
| `400` | `errorCode: MISSING_SITE_ID` | Header missing |
| `400` | `errorCode: INVALID_REQUEST` | `lineItemList` is not an array |
| `400` | `errorCode: UNKNOWN_APP` | `site-id` is not registered |
| `500` | `errorCode: INTERNAL_ERROR` | Unexpected failure |
