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#
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.
Your SureBright store ID. Must be registered for ingest.
Your identifier for the order. Together with merchantId and the customer's email it is how SureBright finds the contracts again when you cancel.
"1" records a sale. "3" cancels contracts on an earlier sale. Any other value is accepted and does nothing (200 with an empty object).
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.
Date of the cancellation as MM/dd/yyyy. Stamped on each cancelled contract.
The order number printed on the customer's receipt, when it differs from orderId.
Your invoice number for the sale.
Identifier of the staff member who made the sale, for your own reporting.
The customer. Fields below.
One entry per product line that carries a plan. Fields below.
customerDetails#
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.
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.
Optional structured shipping address: firstName, lastName, address1, address2, city, province, provinceCode, zip, country, countryCode, phone.
Optional structured billing address: firstName, lastName, address1, address2, city, provinceCode, zip, country, phone.
orderItems[]#
Must be "A" (active) on a create. Anything else fails the whole request with 400.
Plan term in months, as a numeric string, for example "36". On a cancel it must match the contract being cancelled.
Position of the line on the order, as a numeric string ("1", "2", ...).
Units sold. One contract is created per unit. 0 creates nothing.
Your product identifier. Used as the key in the response.
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.
Country of sale, US or CA. Required to price the plan unless quoteId and quoteItemId are sent; an unknown value fails with 400.
What the customer paid for the product. Used to price the plan.
What the customer paid for the plan.
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.
Manufacturer warranty in months. Affects when SureBright coverage starts for extended-warranty plans.
Serial number. On a cancel it must match the contract being cancelled, so send it on the create too when you have it.
NEW, USED, REFURBISHED or CERTIFIED_REFURBISHED.USD or CAD.transactionReason is "3".Unknown fields are ignored.
Example: record a sale#
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.
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}arrayContracts for that order line. Each contract has the fields below.
contractIdstringstatusstringstagestringProcessing stage. ADDRESS_CAPTURE when the customer's street address was missing, otherwise PAYMENT_CAPTURE.
storeTypestringsourcePlatform.salesPersonIdstringorderItems[].salesPersonId.locationIdstringorderItems[].locationId.quoteIdstringorderItems[].quoteId.quoteItemIdstringorderItems[].quoteItemId.contractDetailsobjectThe 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#
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.