Record or cancel a POS sale

POST /v1/transaction lets an external POS or ERP record protection-plan sales with SureBright, and cancel them, without anyone typing them into the POS portal.

POST /v1/transaction is the ingest endpoint behind the SureBright POS. If your stores already run their own point-of-sale or ERP system, call it when a sale that includes a SureBright plan is completed, and again when that sale is cancelled or refunded. SureBright creates one contract per unit sold, emails the customer their coverage, and shows the sale in the POS portal's Sales History and your billing.

POST {POS_API_BASE}/v1/transaction
Content-Type: application/json

{POS_API_BASE} is the base URL SureBright shares with you when the integration is set up.

Authentication#

This endpoint takes no API key or bearer token. It is enabled per merchant: SureBright registers your merchantId for ingest, and a request whose merchantId is not registered is refused with 403. Treat your merchantId as confidential and send requests only from your server, never from a browser or a till's front end.

Request body#

stringrequired

Where the sale was made. Use OFFLINE for an external POS or ERP. Other values are reserved for SureBright's own platform integrations and are rejected with 400 unless SureBright has set them up for you.

stringrequired

Your SureBright store ID. Must be registered for ingest.

stringrequired

Your identifier for the order. Together with merchantId and the customer's email it is how SureBright finds the contracts again when you cancel.

stringrequired

"1" records a sale. "3" cancels contracts on an earlier sale. Any other value is accepted and does nothing (200 with an empty object).

string

Date of the sale as MM/dd/yyyy. Coverage dates are derived from it, so send it on every create. If it is missing or unreadable, the date the request is processed is used.

string

Date of the cancellation as MM/dd/yyyy. Stamped on each cancelled contract.

string

The order number printed on the customer's receipt, when it differs from orderId.

string

Your invoice number for the sale.

string

Identifier of the staff member who made the sale, for your own reporting.

objectrequired

The customer. Fields below.

arrayrequired

One entry per product line that carries a plan. Fields below.

customerDetails#

stringrequired

The customer's email. The coverage email goes here, and it is part of the key used to find the sale on cancellation. A create without it fails with 400.

string
First name.
string
Last name.
string
Phone number.
string

Street address. When it is missing the contract is held for address capture and the customer is asked for it; see Why a contract is on hold.

string
Second address line.
string
City.
string
State or province name.
string
Two-letter state or province code.
string
ZIP or postal code.
string
Country. Plans are sold in the US and Canada.
object

Optional structured shipping address: firstName, lastName, address1, address2, city, province, provinceCode, zip, country, countryCode, phone.

object

Optional structured billing address: firstName, lastName, address1, address2, city, provinceCode, zip, country, phone.

orderItems[]#

stringrequired

Must be "A" (active) on a create. Anything else fails the whole request with 400.

stringrequired

Plan term in months, as a numeric string, for example "36". On a cancel it must match the contract being cancelled.

stringrequired

Position of the line on the order, as a numeric string ("1", "2", ...).

integerrequired

Units sold. One contract is created per unit. 0 creates nothing.

stringrequired

Your product identifier. Used as the key in the response.

string

The SureBright plan category code for the product, as given to you by SureBright. Required to price the plan unless quoteId and quoteItemId are sent.

string

Country of sale, US or CA. Required to price the plan unless quoteId and quoteItemId are sent; an unknown value fails with 400.

string

What the customer paid for the product. Used to price the plan.

string

What the customer paid for the plan.

string

When the plan was quoted through the SureBright quote API, the quote's ID. With quoteItemId, the term and category are taken from the quote.

string
The quote line's ID.
string
Product name as shown to the customer.
string
Model number.
string
Manufacturer.
integer

Manufacturer warranty in months. Affects when SureBright coverage starts for extended-warranty plans.

string

Serial number. On a cancel it must match the contract being cancelled, so send it on the create too when you have it.

string
NEW, USED, REFURBISHED or CERTIFIED_REFURBISHED.
string
Your variant identifier.
string
List price before discounts.
string
Tax charged on the product.
string
Tax charged on the plan.
string
Currency of the amounts, for example USD or CAD.
string
Till ticket number.
string
Your store location identifier, stored on the contract.
string
Your identifier for the salesperson, stored on the contract.
string
Product image URL, shown in the POS.
string
Your reason code for a cancellation. Stamped on the contract when transactionReason is "3".

Unknown fields are ignored.

Example: record a sale#

bash
curl -X POST "{POS_API_BASE}/v1/transaction" \
  -H "Content-Type: application/json" \
  -d '{
    "sourcePlatform": "OFFLINE",
    "merchantId": "your-store-id",
    "orderId": "INV-10482",
    "orderNumber": "10482",
    "transactionReason": "1",
    "purchaseDate": "11/09/2026",
    "salesMemberUserId": "staff-17",
    "customerDetails": {
      "customerFirstName": "Dana",
      "customerLastName": "Lee",
      "customerEmail": "dana.lee@example.com",
      "customerPhone": "+1 415 555 0199",
      "customerAddress1": "456 Pine Avenue",
      "customerCity": "San Francisco",
      "customerState": "California",
      "customerProvinceCode": "CA",
      "customerZipCode": "94101",
      "customerCountry": "US"
    },
    "orderItems": [
      {
        "contractStatus": "A",
        "productSequenceNumber": "1",
        "productId": "SKU-2211",
        "modelName": "55-inch 4K TV",
        "manufacturerName": "Acme",
        "manufacturerWarrantyDuration": 12,
        "serialNumber": "SN-88211",
        "productCondition": "NEW",
        "quantity": 1,
        "productPurchasePrice": "899.00",
        "subCategory": "<plan category code from SureBright>",
        "insurerCountry": "US",
        "termMonths": "36",
        "totalContractCost": "129.00",
        "contractCurrency": "USD"
      }
    ]
  }'

Example: cancel a sale#

Send the same merchantId, orderId and customerDetails.customerEmail as the create, transactionReason "3", and one entry per line to cancel. Each entry is matched to active contracts on that order by serialNumber and termMonths; quantity says how many units to cancel.

bash
curl -X POST "{POS_API_BASE}/v1/transaction" \
  -H "Content-Type: application/json" \
  -d '{
    "sourcePlatform": "OFFLINE",
    "merchantId": "your-store-id",
    "orderId": "INV-10482",
    "transactionReason": "3",
    "cancellationDate": "11/20/2026",
    "customerDetails": { "customerEmail": "dana.lee@example.com" },
    "orderItems": [
      {
        "productId": "SKU-2211",
        "serialNumber": "SN-88211",
        "termMonths": "36",
        "quantity": 1,
        "cancelReasonCode": "CUSTOMER_RETURN"
      }
    ]
  }'

The customer is emailed about the cancellation. Lines that match no active contract return an empty array and are not an error.

Response#

200 OK with a JSON object keyed by each line's productId. The value is the list of contracts created (or cancelled) for that line, one per unit.

{productId}array

Contracts for that order line. Each contract has the fields below.

contractIdstring
SureBright's contract identifier. Quote it to support.
statusstring
Processing status of the contract.
stagestring

Processing stage. ADDRESS_CAPTURE when the customer's street address was missing, otherwise PAYMENT_CAPTURE.

storeTypestring
Echo of sourcePlatform.
salesPersonIdstring
Echo of orderItems[].salesPersonId.
locationIdstring
Echo of orderItems[].locationId.
quoteIdstring
Echo of orderItems[].quoteId.
quoteItemIdstring
Echo of orderItems[].quoteItemId.
contractDetailsobject

The contract as issued: contractNumber, contractStatus (A active, C cancelled), termMonths, effectiveDate and expirationDate (MM/dd/yyyy), salePurchaseDate, orderId, orderNumber, invoiceNumber, productId, variantId, modelName, modelNumber, manufacturerName, manufacturerWarrantyDuration, serialNumber, productCondition, productPurchasePrice, totalContractCost, contractCurrency, quantity, cancellationDate, cancelReasonCode, and customerDetails as sent.

Store contractId against your order line. It is the identifier the POS portal, the customer's documents and SureBright support all use.

Errors#

StatusBodyCause
400{"data":{"orderId":["Please provide Order_Id"]},"statusCode":1,"statusMessage":"Validation Error"}sourcePlatform or orderId is blank. The data map names each failing field.
403ERROR: Forbidden for this merchant idmerchantId is missing or not registered for ingest.
400ERROR: Invalid or missing arguments in Order_ItemsAn item's contractStatus is not "A", or termMonths or productSequenceNumber is not numeric.
400Invalid sourcePlatform {VALUE} provided during transactionsourcePlatform is not one SureBright accepts for you.
400ERROR: Invalid countryinsurerCountry is not a country SureBright sells in.
400ERROR: Invalid or missing argumentsAnything else: unknown store for merchantId, missing customerDetails.customerEmail, missing transactionReason, or a malformed body.

Error bodies other than the validation error are plain text. A request that fails after some contracts were created is not rolled back; check the response map before retrying.

OFFLINE sales are not de-duplicated. Sending the same orderId twice with transactionReason "1" creates a second set of contracts, and the customer is emailed twice. Make your retry logic idempotent on your side.