---
title: "Record or cancel a POS sale"
description: "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](/pos/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

<ParamField body="sourcePlatform" type="string" required>
  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.
</ParamField>
<ParamField body="merchantId" type="string" required>
  Your SureBright store ID. Must be registered for ingest.
</ParamField>
<ParamField body="orderId" type="string" required>
  Your identifier for the order. Together with `merchantId` and the customer's email it is how SureBright finds the contracts again when you cancel.
</ParamField>
<ParamField body="transactionReason" type="string" required>
  `"1"` records a sale. `"3"` cancels contracts on an earlier sale. Any other value is accepted and does nothing (`200` with an empty object).
</ParamField>
<ParamField body="purchaseDate" type="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.
</ParamField>
<ParamField body="cancellationDate" type="string">
  Date of the cancellation as `MM/dd/yyyy`. Stamped on each cancelled contract.
</ParamField>
<ParamField body="orderNumber" type="string">
  The order number printed on the customer's receipt, when it differs from `orderId`.
</ParamField>
<ParamField body="invoiceNumber" type="string">
  Your invoice number for the sale.
</ParamField>
<ParamField body="salesMemberUserId" type="string">
  Identifier of the staff member who made the sale, for your own reporting.
</ParamField>
<ParamField body="customerDetails" type="object" required>
  The customer. Fields below.
</ParamField>
<ParamField body="orderItems" type="array" required>
  One entry per product line that carries a plan. Fields below.
</ParamField>

### customerDetails

<ParamField body="customerDetails.customerEmail" type="string" required>
  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`.
</ParamField>
<ParamField body="customerDetails.customerFirstName" type="string">First name.</ParamField>
<ParamField body="customerDetails.customerLastName" type="string">Last name.</ParamField>
<ParamField body="customerDetails.customerPhone" type="string">Phone number.</ParamField>
<ParamField body="customerDetails.customerAddress1" type="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](/contracts/holds).
</ParamField>
<ParamField body="customerDetails.customerAddress2" type="string">Second address line.</ParamField>
<ParamField body="customerDetails.customerCity" type="string">City.</ParamField>
<ParamField body="customerDetails.customerState" type="string">State or province name.</ParamField>
<ParamField body="customerDetails.customerProvinceCode" type="string">Two-letter state or province code.</ParamField>
<ParamField body="customerDetails.customerZipCode" type="string">ZIP or postal code.</ParamField>
<ParamField body="customerDetails.customerCountry" type="string">Country. Plans are sold in the US and Canada.</ParamField>
<ParamField body="customerDetails.shippingAddress" type="object">
  Optional structured shipping address: `firstName`, `lastName`, `address1`, `address2`, `city`, `province`, `provinceCode`, `zip`, `country`, `countryCode`, `phone`.
</ParamField>
<ParamField body="customerDetails.billingAddress" type="object">
  Optional structured billing address: `firstName`, `lastName`, `address1`, `address2`, `city`, `provinceCode`, `zip`, `country`, `phone`.
</ParamField>

### orderItems[]

<ParamField body="orderItems[].contractStatus" type="string" required>
  Must be `"A"` (active) on a create. Anything else fails the whole request with `400`.
</ParamField>
<ParamField body="orderItems[].termMonths" type="string" required>
  Plan term in months, as a numeric string, for example `"36"`. On a cancel it must match the contract being cancelled.
</ParamField>
<ParamField body="orderItems[].productSequenceNumber" type="string" required>
  Position of the line on the order, as a numeric string (`"1"`, `"2"`, ...).
</ParamField>
<ParamField body="orderItems[].quantity" type="integer" required>
  Units sold. One contract is created per unit. `0` creates nothing.
</ParamField>
<ParamField body="orderItems[].productId" type="string" required>
  Your product identifier. Used as the key in the response.
</ParamField>
<ParamField body="orderItems[].subCategory" type="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.
</ParamField>
<ParamField body="orderItems[].insurerCountry" type="string">
  Country of sale, `US` or `CA`. Required to price the plan unless `quoteId` and `quoteItemId` are sent; an unknown value fails with `400`.
</ParamField>
<ParamField body="orderItems[].productPurchasePrice" type="string">
  What the customer paid for the product. Used to price the plan.
</ParamField>
<ParamField body="orderItems[].totalContractCost" type="string">
  What the customer paid for the plan.
</ParamField>
<ParamField body="orderItems[].quoteId" type="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.
</ParamField>
<ParamField body="orderItems[].quoteItemId" type="string">The quote line's ID.</ParamField>
<ParamField body="orderItems[].modelName" type="string">Product name as shown to the customer.</ParamField>
<ParamField body="orderItems[].modelNumber" type="string">Model number.</ParamField>
<ParamField body="orderItems[].manufacturerName" type="string">Manufacturer.</ParamField>
<ParamField body="orderItems[].manufacturerWarrantyDuration" type="integer">
  Manufacturer warranty in months. Affects when SureBright coverage starts for extended-warranty plans.
</ParamField>
<ParamField body="orderItems[].serialNumber" type="string">
  Serial number. On a cancel it must match the contract being cancelled, so send it on the create too when you have it.
</ParamField>
<ParamField body="orderItems[].productCondition" type="string">`NEW`, `USED`, `REFURBISHED` or `CERTIFIED_REFURBISHED`.</ParamField>
<ParamField body="orderItems[].variantId" type="string">Your variant identifier.</ParamField>
<ParamField body="orderItems[].productListPrice" type="string">List price before discounts.</ParamField>
<ParamField body="orderItems[].productTax" type="string">Tax charged on the product.</ParamField>
<ParamField body="orderItems[].policyTax" type="string">Tax charged on the plan.</ParamField>
<ParamField body="orderItems[].contractCurrency" type="string">Currency of the amounts, for example `USD` or `CAD`.</ParamField>
<ParamField body="orderItems[].salesTicketNumber" type="string">Till ticket number.</ParamField>
<ParamField body="orderItems[].locationId" type="string">Your store location identifier, stored on the contract.</ParamField>
<ParamField body="orderItems[].salesPersonId" type="string">Your identifier for the salesperson, stored on the contract.</ParamField>
<ParamField body="orderItems[].imageUrl" type="string">Product image URL, shown in the POS.</ParamField>
<ParamField body="orderItems[].cancelReasonCode" type="string">Your reason code for a cancellation. Stamped on the contract when `transactionReason` is `"3"`.</ParamField>

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.

<ResponseField name="{productId}" type="array">
  Contracts for that order line. Each contract has the fields below.
</ResponseField>
<ResponseField name="contractId" type="string">SureBright's contract identifier. Quote it to support.</ResponseField>
<ResponseField name="status" type="string">Processing status of the contract.</ResponseField>
<ResponseField name="stage" type="string">
  Processing stage. `ADDRESS_CAPTURE` when the customer's street address was missing, otherwise `PAYMENT_CAPTURE`.
</ResponseField>
<ResponseField name="storeType" type="string">Echo of `sourcePlatform`.</ResponseField>
<ResponseField name="salesPersonId" type="string">Echo of `orderItems[].salesPersonId`.</ResponseField>
<ResponseField name="locationId" type="string">Echo of `orderItems[].locationId`.</ResponseField>
<ResponseField name="quoteId" type="string">Echo of `orderItems[].quoteId`.</ResponseField>
<ResponseField name="quoteItemId" type="string">Echo of `orderItems[].quoteItemId`.</ResponseField>
<ResponseField name="contractDetails" type="object">
  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.
</ResponseField>

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

## Errors

| Status | Body | Cause |
|---|---|---|
| `400` | `{"data":{"orderId":["Please provide Order_Id"]},"statusCode":1,"statusMessage":"Validation Error"}` | `sourcePlatform` or `orderId` is blank. The `data` map names each failing field. |
| `403` | `ERROR: Forbidden for this merchant id` | `merchantId` is missing or not registered for ingest. |
| `400` | `ERROR: Invalid or missing arguments in Order_Items` | An item's `contractStatus` is not `"A"`, or `termMonths` or `productSequenceNumber` is not numeric. |
| `400` | `Invalid sourcePlatform {VALUE} provided during transaction` | `sourcePlatform` is not one SureBright accepts for you. |
| `400` | `ERROR: Invalid country` | `insurerCountry` is not a country SureBright sells in. |
| `400` | `ERROR: Invalid or missing arguments` | Anything 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.

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