{ "openapi": "3.0.0", "info": { "title": "SureBright API", "description": "API documentation for SureBright services", "version": "1.0.0" }, "servers": [ { "url": "https://{HOST_NAME}" } ], "paths": { "/quote/api/storeCategory/listStoreCategories": { "get": { "summary": "List Categories", "description": "Lists the warranty categories active on a store. Send either storeId or storeParentId. Use the returned sbCategoryId when listing quotes by category.", "operationId": "listCategories", "tags": [ "storeCategory" ], "parameters": [ { "name": "storeId", "in": "query", "required": false, "schema": { "type": "string", "example": "ecca4210-09a4-446c-ad87-5e65bd50df12" }, "description": "A unique identifier for a store, shared as part of the integration kit. Required when storeParentId is not sent." }, { "name": "storeParentId", "in": "query", "required": false, "schema": { "type": "string", "example": "13612f29-8ec5-49ad-bab1-5ab09b51367e" }, "description": "Unique identifier for the store parent. Required when storeId is not sent. Used instead of storeId when both are sent." } ], "responses": { "200": { "description": "Successful response. The store's active categories; an empty list when none are configured.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "storeCategoryId": { "type": "string", "description": "Unique identifier for the store category", "example": "07b1dcb3-fbe5-46c6-b42f-66d82e89f2a7" }, "storeParentId": { "type": "string", "description": "Unique identifier for the store parent", "example": "13612f29-8ec5-49ad-bab1-5ab09b51367e" }, "sbCategoryId": { "type": "string", "description": "Unique identifier for the SureBright category. Send it as storeCategoryList[].sbCategoryId when listing quotes.", "example": "4c3103e4-38dc-4171-96e5-b4b77ab0e96f" }, "sbCategoryName": { "type": "string", "description": "Name of the SureBright category", "example": "Small Home Appliance" }, "labelList": { "type": "array", "description": "List of category labels", "items": { "type": "string" }, "example": [ "Ovens", "Microwaves", "Refrigerators" ] } } }, "example": [ { "storeCategoryId": "07b1dcb3-fbe5-46c6-b42f-66d82e89f2a7", "storeParentId": "13612f29-8ec5-49ad-bab1-5ab09b51367e", "sbCategoryId": "4c3103e4-38dc-4171-96e5-b4b77ab0e96f", "sbCategoryName": "Small Home Appliance", "labelList": [ "Ovens", "Microwaves", "Refrigerators" ] } ] } } } }, "400": { "description": "Neither storeId nor storeParentId was sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Insufficient params" } } } } } } } } }, "/quote/api/quote/category/listQuotes": { "get": { "summary": "List Quotes by Category", "description": "Lists warranty quote options for one or more products, by category and product price. Each quoteItemList entry carries a quoteId and quoteItemId; send these in planDetails when recording the order.", "operationId": "listQuotes", "tags": [ "quotes" ], "parameters": [ { "name": "payload", "in": "query", "required": true, "schema": { "type": "string", "example": "eyJzdG9yZVBhcmVudElkIjoiMTM2MTJmMjktOGVjNS00OWFkLWJhYjEtNWFiMDliNTEzNjdlIiwiY291bnRyeSI6IlVTIiwidmlzaXRJZCI6IjNkOTlhNGFlLTVjZjAtNGQ4Ny04NDM2LTQ2YzBjZGMwMzY3NiIsInBsYXRmb3JtIjoiT0ZGTElORV9QT1JUQUwiLCJzdG9yZUNhdGVnb3J5TGlzdCI6W3sic2JDYXRlZ29yeUlkIjoiNGMzMTAzZTQtMzhkYy00MTcxLTk2ZTUtYjRiNzdhYjBlOTZmIiwicHJvZHVjdFByaWNlIjoxOTkuOTl9XX0=" }, "description": "Base64-encoded (UTF-8) JSON object. All quote inputs go inside this object, not as separate query parameters.\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n| country | string | Yes | Alpha-2 country code of the customer, e.g. `US` |\n| visitId | string | Yes | Any unique identifier for the shopper session |\n| platform | string | Yes | Calling platform, e.g. `OFFLINE_PORTAL` |\n| storeParentId | string | Yes, unless storeId is sent | Unique identifier for the store parent. Required when quoting by sbCategoryId |\n| storeId | string | Yes, unless storeParentId is sent | A unique identifier for a store |\n| province | string | No | State or province code of the customer |\n| storeCategoryList | array | Yes | One entry per product to quote. Must not be empty |\n| storeCategoryList[].sbCategoryId | string | sbCategoryId or storeCategoryId | SureBright category ID from List Categories |\n| storeCategoryList[].storeCategoryId | string | sbCategoryId or storeCategoryId | Store category ID from List Categories |\n| storeCategoryList[].productPrice | number | Yes | Price of the product being protected |\n| storeCategoryList[].sbProductId | string | No | SureBright product ID |\n| storeCategoryList[].manufacturerWarrantyDuration | integer | No | Manufacturer warranty, in months |\n\n**Example: JSON before Base64 encoding**\n```json\n{\n \"storeParentId\": \"13612f29-8ec5-49ad-bab1-5ab09b51367e\",\n \"country\": \"US\",\n \"visitId\": \"3d99a4ae-5cf0-4d87-8436-46c0cdc03676\",\n \"platform\": \"OFFLINE_PORTAL\",\n \"storeCategoryList\": [\n {\n \"sbCategoryId\": \"4c3103e4-38dc-4171-96e5-b4b77ab0e96f\",\n \"productPrice\": 199.99\n }\n ]\n}\n```" }, { "name": "quoteSyncMode", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "SYNC", "ASYNC" ], "default": "ASYNC", "example": "SYNC" }, "description": "Send `SYNC` to save the quote before the response returns, so its quoteId and quoteItemId can be used to record an order straight away." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "quoteList": { "type": "array", "description": "One quote per storeCategoryList entry", "items": { "type": "object", "properties": { "storeCategoryId": { "type": "string", "example": "ecca4210-09a4-446c-ad87-5e65bd50df12", "description": "A unique identifier for a store category" }, "sbCategoryId": { "type": "string", "example": "4c3103e4-38dc-4171-96e5-b4b77ab0e96f", "description": "Unique identifier for the surebright category" }, "country": { "type": "string", "example": "US", "description": "The country code of the identified customer location" }, "platform": { "type": "string", "example": "SHOPIFY", "description": "The platform of the merchant's store" }, "sbProductId": { "type": "string", "example": "643bc477-0eec-4da1-946a-38ff7d1292c9", "description": "Unique identifier for the product" }, "storeParentId": { "type": "string", "example": "ecca4210-09a4-446c-ad87-5e65bd50df12", "description": "Unique identifier for the store" }, "allowDynamicPolicyPricing": { "type": "boolean", "example": true, "description": "Indicates if dynamic policy pricing is allowed" }, "platformOrderDetails": { "type": "object", "example": null, "description": "The platform order details" }, "quoteId": { "type": "string", "example": "33f21a29-95ca-4150-b5df-afe36f5ef537", "description": "Unique identifier for the quote" }, "quoteItemList": { "type": "array", "description": "A list of quote item details", "items": { "type": "object", "properties": { "quoteId": { "type": "string", "example": "33f21a29-95ca-4150-b5df-afe36f5ef537", "description": "Unique identifier for the quote" }, "quoteItemId": { "type": "string", "example": "33f21a29-95ca-4150-b5df-afe36f5ef537", "description": "Unique identifier for the quote item" }, "lowerPrice": { "type": "number", "example": 749.99, "description": "The lower price of the quote item" }, "upperPrice": { "type": "number", "example": 999.99, "description": "The upper price of the quote item" }, "coverageYears": { "type": "string", "example": "1", "description": "The number of years of coverage in years" }, "policyPrice": { "type": "string", "example": "79", "description": "The price of the policy product" }, "storeProductVariantPrice": { "type": "string", "example": "899.99", "description": "The price of the product variant" }, "country": { "type": "string", "example": "US", "description": "The country code of the identified customer location" }, "isActive": { "type": "boolean", "example": true, "description": "Indicates if the quote item is active" } } } }, "coverageType": { "type": "string", "example": "AD", "description": "Represents the type of policy coverage associated with a product" }, "coverageList": { "type": "array", "description": "List of coverage options grouped under different sections", "items": { "type": "object", "properties": { "coverageItemType": { "type": "string", "enum": [ "COVERAGE_OPTION", "WHY_SUREBRIGHT" ], "example": "COVERAGE_OPTION" }, "coverageItemTitle": { "type": "string", "example": "Your warranty plan provides" }, "coverageItemList": { "type": "array", "items": { "type": "string" }, "example": [ "Protection against everyday spills (food, beverages, human or pet biological stains, cosmetics, etc)." ] } } } }, "policyId": { "type": "string", "example": "1234567890", "description": "Unique identifier for the policy" }, "createdAt": { "type": "string", "example": "2021-01-01T00:00:00Z", "description": "The date and time the quote was created" }, "updatedAt": { "type": "string", "example": "2021-01-01T00:00:00Z", "description": "The date and time the quote was updated" } } } } } } } } }, "400": { "description": "A required payload field is missing", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Insufficient params" } } } } } } } } }, "/quote/api/quote/listWarrantyQuotes?platform={platform}&storeId={storeId}&productId={productId}&variantId={variantId}&country={country}": { "get": { "summary": "List Warranty Quotes by Product", "description": "This endpoint retrieves a list of warranty quotes for a specific product and its price.", "operationId": "listWarrantyQuotesByProduct", "tags": [ "quotes" ], "parameters": [ { "name": "platform", "in": "query", "required": true, "schema": { "type": "string", "example": "SHOPIFY" }, "description": "The platform of the merchant's store." }, { "name": "storeId", "in": "query", "required": true, "schema": { "type": "string", "example": "strictlyapple.myshopify.com" }, "description": "The unique identifier for the merchant's store. This is typically the store's domain name (e.g., 'yourstore.myshopify.com' for Shopify stores)." }, { "name": "productId", "in": "query", "required": true, "schema": { "type": "string", "example": "8606368530686" }, "description": "The ID of the product that is shown to the customer" }, { "name": "variantId", "in": "query", "required": true, "schema": { "type": "string", "example": "45667967238398" }, "description": "The ID of the variant that is shown to the customer" }, { "name": "country", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]{2}$", "example": "US" }, "description": "The country code of the identified customer location" }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "example": "AL" }, "description": "The state code of the identified customer location" } ], "responses": { "200": { "description": "Quotes Found", "content": { "application/json": { "schema": { "type": "object", "required": [ "warrantyQuoteId", "warrantyQuoteItemList", "coverageWidgetHeading", "coveragePopupHeading", "coverageList" ], "properties": { "warrantyQuoteId": { "type": "string", "description": "A unique ID representing this specific return quote in this particular API call", "example": "929d14dd-2937-4290-9818-8fca2a00a9a3" }, "warrantyQuoteItemList": { "type": "array", "description": "A list of warranty offers generated for this particular request", "items": { "type": "object", "properties": { "warrantyProductId":{ "type": "integer", "description": "Product ID of the warranty item", "example": 7080029454439 }, "warrantyVariantId":{ "type": "integer", "description": "Variant ID of the warranty item", "example": 40937702359143 }, "warrantyTenure": { "type": "integer", "description": "Duration of the warranty in years", "example": 2 }, "warrantyPrice": { "type": "number", "format": "float", "description": "Price of the warranty", "example": 64.99 }, "warrantyQuoteItemId": { "type": "string", "description": "Unique identifier for the warranty quote item", "example": "8c78bc1a-0790-4cd3-a3f9-5ed97bbe59f5" } } } }, "tncLink": { "type": "string", "description": "Unique link for legal Terms & Conditions of the warranty for each product Category", "example": "https://customer.surebright.com/t-c/098e0e696f20839479dfe4a2804756233d32130f068441e24c6c0dbbc790677ff9718e04396a18dac753d0cf92bcaf63a26d2b666e5326475d0b2ed7475ad7fc" }, "sbCategoryId":{ "type": "string", "description": "SureBright Category ID of the warranty item", "example": "4c3103e4-38dc-4171-96e5-b4b77ab0e96f" }, "productImageUrl":{ "type": "string", "description": "Link of the product image that can be show as part of the warranty offer UI", "example": "https://cdn.shopify.com/s/files/1/0254/6227/6182/products/bedbathandimage.jpg?v=1664467971" }, "coverageWidgetHeading": { "type": "string", "description": "Heading for the various tenure options shown to a customer on the product page", "example": "Add premium product protection" }, "coveragePopupHeading": { "type": "string", "description": "Title that nudges the customers to buy a warranty for their product purchase", "example": "Don't want to spend extra on this product for the next few years? We've got you covered!" }, "coverageList": { "type": "array", "description": "List of coverage options grouped under different sections", "items": { "type": "object", "properties": { "coverageItemType": { "type": "string", "enum": [ "COVERAGE_OPTION", "WHY_SUREBRIGHT" ], "example": "COVERAGE_OPTION" }, "coverageItemTitle": { "type": "string", "example": "Your warranty plan provides," }, "coverageItemList": { "type": "array", "items": { "type": "string" }, "example": [ "Protection against everyday spills (food, beverages, human or pet biological stains, cosmetics, etc)." ] } } } } } } } } }, "511": { "description": "Insufficient Parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 511 }, "errorMessage": { "type": "string", "description": "error message", "example": "Insufficient Parameters" } } } } } }, "512": { "description": "Validation Failed for Input Parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 512 }, "errorMessage": { "type": "string", "description": "error message", "example": "Validation Failed for Input Parameters" } } } } } }, "513": { "description": "Product Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 513 }, "errorMessage": { "type": "string", "description": "error message", "example": "Product Not Found" } } } } } }, "514": { "description": "No Quote Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 514 }, "errorMessage": { "type": "string", "description": "error message", "example": "No Quote Found" } } } } } }, "515": { "description": "Store Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 515 }, "errorMessage": { "type": "string", "description": "error message", "example": "Store Not Found" } } } } } }, "516": { "description": "Not Eligible", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 516 }, "errorMessage": { "type": "string", "description": "error message", "example": "Not Eligible" } } } } } }, "517": { "description": "Category Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 517 }, "errorMessage": { "type": "string", "description": "error message", "example": "Category Not Found" } } } } } }, "500": { "description": "Something Unexpectedly Went Wrong", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 500 }, "errorMessage": { "type": "string", "description": "error message", "example": "Something Unexpectedly Went Wrong" } } } } } } } } } , "/api/v1/quote/listWarrantyQuotes?storeId={storeId}&country={country}&productUrl={PRODUCT_URL}": { "get": { "summary": "List Quotes by URL", "description": "This endpoint fetches all warranty quotes for the product category to which product in the sent URL belongs.", "operationId": "listWarrantyQuotesByUrl", "tags": [ "quotes" ], "parameters": [ { "name": "storeId", "in": "query", "required": true, "schema": { "type": "string", "example": "ecca4210-09a4-446c-ad87-5e65bd50df12" }, "description": "A unique identifier for a store will be shared as part of the integration kit." }, { "name": "country", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]{2}$", "example": "US" }, "description": "The country code of the identified customer location" }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "example": "AL" }, "description": "The state code of the identified customer location" }, { "name": "productUrl", "in": "query", "required": true, "schema": { "type": "string", "example": "aHR0cHM6Ly93d3cubWVkaWNhbGVzaG9wLmNvbS9xdWlja2llLXE1MC1yLWNhcmJvbi1mb2xkaW5nLXBvd2VyLXdoZWVsY2hhaXI=" }, "description": "Base64 encoded URL containing the product page that is shown to the customer" } ], "responses": { "200": { "description": "Quotes Found", "content": { "application/json": { "schema": { "type": "object", "required": [ "warrantyQuoteId", "warrantyQuoteItemList", "coverageWidgetHeading", "coveragePopupHeading", "coverageList" ], "properties": { "lowerPrice": { "type": "number", "format": "float", "example": 0 }, "upperPrice": { "type": "number", "format": "float", "example": 499.99 }, "warrantyQuoteId": { "type": "string", "description": "A unique ID representing this specific return quote in this particular API call", "example": "929d14dd-2937-4290-9818-8fca2a00a9a3" }, "warrantyQuoteItemList": { "type": "array", "description": "A list of warranty offers generated for this particular request", "items": { "type": "object", "properties": { "warrantyTenure": { "type": "integer", "description": "Duration of the warranty in years", "example": 2 }, "warrantyPrice": { "type": "number", "format": "float", "description": "Price of the warranty", "example": 64.99 }, "warrantyQuoteItemId": { "type": "string", "description": "Unique identifier for the warranty quote item", "example": "8c78bc1a-0790-4cd3-a3f9-5ed97bbe59f5" } } } }, "tncLink": { "type": "string", "description": "Unique link for legal Terms & Conditions of the warranty for each product Category", "example": "https://customer.surebright.com/t-c/098e0e696f20839479dfe4a2804756233d32130f068441e24c6c0dbbc790677ff9718e04396a18dac753d0cf92bcaf63a26d2b666e5326475d0b2ed7475ad7fc" }, "productImageURL":{ "type": "string", "description": "Link of the product image that can be show as part of the warranty offer UI", "example": "" }, "coverageWidgetHeading": { "type": "string", "description": "Heading for the various tenure options shown to a customer on the product page", "example": "Add premium product protection" }, "coveragePopupHeading": { "type": "string", "description": "Title that nudges the customers to buy a warranty for their product purchase", "example": "Don't want to spend extra on this product for the next few years? We've got you covered!" }, "coverageList": { "type": "array", "description": "List of coverage options grouped under different sections", "items": { "type": "object", "properties": { "coverageItemType": { "type": "string", "enum": [ "COVERAGE_OPTION", "WHY_SUREBRIGHT" ], "example": "COVERAGE_OPTION" }, "coverageItemTitle": { "type": "string", "example": "Your warranty plan provides," }, "coverageItemList": { "type": "array", "items": { "type": "string" }, "example": [ "Protection against everyday spills (food, beverages, human or pet biological stains, cosmetics, etc)." ] } } } } } } } } }, "511": { "description": "Insufficient Parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 511 }, "errorMessage": { "type": "string", "description": "error message", "example": "Insufficient Parameters" } } } } } }, "512": { "description": "Validation Failed for Input Parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 512 }, "errorMessage": { "type": "string", "description": "error message", "example": "Validation Failed for Input Parameters" } } } } } }, "513": { "description": "Product Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 513 }, "errorMessage": { "type": "string", "description": "error message", "example": "Product Not Found" } } } } } }, "514": { "description": "No Quote Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 514 }, "errorMessage": { "type": "string", "description": "error message", "example": "No Quote Found" } } } } } }, "515": { "description": "Store Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 515 }, "errorMessage": { "type": "string", "description": "error message", "example": "Store Not Found" } } } } } }, "516": { "description": "Not Eligible", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 516 }, "errorMessage": { "type": "string", "description": "error message", "example": "Not Eligible" } } } } } }, "517": { "description": "Category Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 517 }, "errorMessage": { "type": "string", "description": "error message", "example": "Category Not Found" } } } } } }, "500": { "description": "Something Unexpectedly Went Wrong", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 500 }, "errorMessage": { "type": "string", "description": "error message", "example": "Something Unexpectedly Went Wrong" } } } } } } } } } , "/partner/api/v1/order": { "post": { "summary": "Create/Update Warranty", "description": "This endpoint is used to create warranty contracts for a specific order.\n\n🛠️ **Contract Creation Logic**\nWarranty contracts are created in a 1:1 ratio with the quantity of the associated product purchased.\nThe warranty quantity is automatically inferred from the product quantity.\nContracts are only created for the exact number of products purchased—warranty coverage cannot exceed or fall short of the product quantity.\n\n🏷️ **Using policySKU**\nThe `policySKU` is a required field that determines the parameters of each warranty contract, including:\n- Coverage Type (e.g., accidental damage, mechanical breakdown)\n- Tenure (duration of coverage)\n- Country (to apply relevant terms and conditions)\n- Category (product type classification)\nMerchants must ensure that the appropriate `policySKU` is used for each product to ensure accurate coverage assignment.\n\n🔁 **Handling Updates**\nIf this endpoint is called for an order where contracts already exist:\n- Existing contracts will be updated if the quantity or details have changed.\n- Warranty price, tenure, and coverage type are handled automatically based on the provided `policySKU`.", "operationId": "createUpdateWarranty", "tags": [ "orders" ], "parameters": [ { "name": "X-SureBright-Access-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Access token for authentication" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "storeId", "orderId", "orderPurchaseDate", "orderLineItemList", "customerDetails" ], "properties": { "storeId": { "type": "string", "description": "A unique identifier for a store will be shared as part of the integration kit", "example": "f4c059b2-5b74-4e4c-a3c5-85bc80cf8a09" }, "orderId": { "type": "string", "description": "Unique identifier for the complete successful order placed by a customer on the merchant site. This represents the whole order that can have multiple line items of different quantities.", "maxLength": 48, "example": "83737121380" }, "manufacturerWarrantyDuration": { "type": "integer", "description": "The warranty period provided by the product’s manufacturer, specified in months.", "example": 24 }, "orderPurchaseDate": { "type": "string", "format": "date-time", "description": "Date time at which the order was purchased by customer.", "example": "2024-01-07T10:15:30Z" }, "orderLineItemList": { "type": "array", "description": "The lineItemList consists of individual line items representing purchased products and/or products with policies. Each line item is uniquely identified by a lineItemId (String: maximum length 48 characters). The planDetails serve to identify the specific quote option acquired by the customer. OptionId is the combination of product attributes separated by #.", "items": { "type": "object", "required": [ "lineItemId", "totalPrice", "salePrice", "quantity", "productTitle", "productId", "productSKU", "totalOrderValue", "isTestOrder", "tax" ], "properties": { "lineItemId": { "type": "string", "maxLength": 48, "example": "374dc3c3-94a3-4b85-a876-8651e461446d" }, "planDetails": { "type": "object", "description": "Identifies the warranty plan bought for this line item. Send policyPurchaseDate plus one of: quoteId and quoteItemId (from List Quotes by Category), policySKU and policyPrice, or categoryId and tenure. When quoteId and quoteItemId are sent, the other fields are ignored.", "required": [ "policyPurchaseDate" ], "properties": { "policyPurchaseDate": { "type": "string", "format": "date-time", "description": "Date time at which the policy was purchased by the customer. ISO 8601 with a timezone offset or Z.", "example": "2024-01-07T10:15:30Z" }, "quoteId": { "type": "string", "description": "quoteId of the selected quote item from List Quotes by Category. Send with quoteItemId.", "example": "33f21a29-95ca-4150-b5df-afe36f5ef537" }, "quoteItemId": { "type": "string", "description": "quoteItemId of the selected quote item from List Quotes by Category. Send with quoteId.", "example": "a7defcbd-aa07-4e01-9076-c1935af20a98" }, "policySKU": { "type": "string", "description": "Policy SKU shared with the store. Send with policyPrice. A quoteItemId is not accepted here.", "example": "SBW-1U-SHAB-2900" }, "policyPrice": { "type": "number", "description": "Price of the policy purchased by the customer. Required with policySKU. Must be less than salePrice.", "example": 29 }, "categoryId": { "type": "string", "description": "Category of the plan. Send with tenure.", "example": "4c3103e4-38dc-4171-96e5-b4b77ab0e96f" }, "tenure": { "type": "number", "description": "Plan tenure. Must be a positive number. Send with categoryId.", "example": 2 } } }, "totalPrice": { "type": "number", "example": 3300 }, "quantity": { "type": "integer", "example": 3 }, "productTitle": { "type": "string", "example": "GreatCircleUSA 3-in-1 Wood Chipper - 7HP Engine, 3 Max Branch Capacity" }, "productId": { "type": "string", "example": "6673746231399" }, "optionId": { "type": "string", "example": "8577825144935" }, "productSKU": { "type": "string", "example": "ALH05" }, "salePrice": { "type": "number", "example": 1100 }, "listPrice": { "type": "number", "example": 1299 }, "discountAmount": { "type": "number", "example": 199 }, "productURL": { "type": "string", "example": "https://example.com/products/wood-chipper-alh05" } } } }, "customerDetails": { "type": "object", "required": [ "firstName", "lastName", "addressLine1", "city", "state", "country", "zipCode", "customerEmail" ], "properties": { "firstName": { "type": "string", "example": "John" }, "lastName": { "type": "string", "example": "Doe" }, "addressLine1": { "type": "string", "example": "123 Hathway Street" }, "addressLine2": { "type": "string", "example": "Apt 4B" }, "city": { "type": "string", "example": "New York City" }, "state": { "type": "string", "description": "ISO 3166-2 code", "example": "NY" }, "country": { "type": "string", "description": "Country code for USA is US", "example": "US" }, "zipCode": { "type": "string", "example": "10005" }, "customerEmail": { "type": "string", "format": "email", "example": "johndoe@gmail.com" }, "mobileNumber": { "type": "string", "example": "7872323781" } } }, "discount": { "type": "object", "properties": { "discountAmount": { "type": "number", "example": 10 } } }, "totalOrderValue": { "type": "number", "example": 1000 }, "isTestOrder": { "type": "boolean", "example": false }, "taxAmount": { "type": "number", "example": 100 } } } } } }, "responses": { "200": { "description": "Warranty created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "storeId": { "type": "string", "description": "A unique identifier for a store will be shared as part of the integration kit", "example": "f4c059b2-5b74-4e4c-a3c5-85bc80cf8a09" }, "orderId": { "type": "string", "description": "A unique identifier for the complete successful order placed by a customer on the merchant site. This represents the whole order that can have multiple line items of different quantities.", "maxLength": 48, "example": "83737121380" }, "contractList": { "type": "array", "description": "The list of contracts generated for each quantity in each line item. If any error in generating a contract, the error code and msg will be added for that item instead of the contract id.", "items": { "type": "object", "properties": { "lineItemId": { "type": "string", "example": "374dc3c3-94a3-4b85-a876-8651e461446d" }, "contractId": { "type": "string", "example": "abc12345-6789-4abc-bcde-ef1234567890" }, "isCancelled": { "type": "boolean", "example": false } } } } } } } } }, "207": { "description": "Partial order processing", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "example": true }, "storeId": { "type": "string", "description": "A unique identifier for a store will be shared as part of the integration kit", "example": "f4c059b2-5b74-4e4c-a3c5-85bc80cf8a09" }, "orderId": { "type": "string", "description": "A unique identifier for the complete successful order placed by a customer on the merchant site. This represents the whole order that can have multiple line items of different quantities.", "maxLength": 48, "example": "83737121380" }, "contractList": { "type": "array", "description": "The list of contracts generated for each quantity in each line item. If any error in generating a contract, the error code and msg will be added for that item instead of the contract id.", "items": { "type": "object", "properties": { "lineItemId": { "type": "string", "example": "374dc3c3-94a3-4b85-a876-8651e461446d" }, "contractId": { "type": "string", "example": "abc12345-6789-4abc-bcde-ef1234567890" }, "isCancelled": { "type": "boolean", "example": false } } } }, "errorList": { "type": "array", "description": "The list of contracts generated for each quantity in each line item. If any error in generating a contract, the error code and msg will be added for that item instead of the contract id.", "items": { "type": "object", "properties": { "lineItemId": { "type": "string", "example": "374dc3c3-94a3-4b85-a876-8651e461446d" }, "error": { "type": "string", "example": "planDetails.policyPurchaseDate is required" } } } } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "storeId": { "type": "string", "description": "A unique identifier for a store will be shared as part of the integration kit", "example": "f4c059b2-5b74-4e4c-a3c5-85bc80cf8a09" }, "orderId": { "type": "string", "description": "A unique identifier for the complete successful order placed by a customer on the merchant site. This represents the whole order that can have multiple line items of different quantities.", "maxLength": 48, "example": "83737121380" }, "errorList": { "type": "array", "description": "The list of contracts generated for each quantity in each line item. If any error in generating a contract, the error code and msg will be added for that item instead of the contract id.", "items": { "type": "object", "properties": { "lineItemId": { "type": "string", "example": "374dc3c3-94a3-4b85-a876-8651e461446d" }, "error": { "type": "string", "example": "planDetails.policyPurchaseDate is required" } } } } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "storeId": { "type": "string", "description": "Store Id", "example":"8577825144935" }, "errorCode": { "type": "integer", "description": "error type", "example": 500 }, "errorMessage": { "type": "string", "description": "error message", "example": "Failed to process order with internal service" } } } } } }, "401": { "description": "Authorization Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "storeId": { "type": "string", "description": "Store Id", "example":"8577825144935" }, "errorCode": { "type": "integer", "description": "error type", "example": 401 }, "errorMessage": { "type": "string", "description": "error message", "example": "X-SureBright-Access-Token header is required" } } } } } } } }, "put": { "summary": "Update Warranty", "description": "This endpoint is used to create, update, or cancel warranty contracts for a specific order.\n\n🔄 **Updating Line Item Quantities**\nIf the quantity of a product in the original order is changed (e.g., reduced), the corresponding warranty contract quantity is automatically adjusted to match the updated product quantity.\n\nTo reduce or cancel warranty coverage for a line item, update the `quantity` field inside the relevant `lineItem` object in the `orderLineItemList`.\n\n❌ **Cancelling Line Items**\nTo cancel warranty coverage for a specific line item, set its `quantity` to 0 in the `orderLineItemList`.\nOnce cancelled, a warranty contract cannot be reactivated.\nThis applies to both partial cancellations (some items in the order) and full order cancellations.\n\n🧾 **Handling Full Order Cancellation**\nFor full order cancellations, merchants have two options:\n- Remove the `planDetails` object entirely from the request payload.\n- Set the `quantity` of each relevant `lineItem` in `orderLineItemList` to 0.\n\n⚙️ **Automatic Price and Tenure Updates**\nAny changes to warranty price or tenure (e.g., due to product updates or plan revisions) are handled automatically by the system.", "operationId": "UpdateWarranty", "tags": [ "orders" ], "parameters": [ { "name": "X-SureBright-Access-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Access token for authentication" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "storeId", "orderId", "orderPurchaseDate", "orderLineItemList", "customerDetails" ], "properties": { "storeId": { "type": "string", "description": "A unique identifier for a store will be shared as part of the integration kit", "example": "f4c059b2-5b74-4e4c-a3c5-85bc80cf8a09" }, "orderId": { "type": "string", "description": "Unique identifier for the complete successful order placed by a customer on the merchant site. This represents the whole order that can have multiple line items of different quantities.", "maxLength": 48, "example": "83737121380" }, "orderPurchaseDate": { "type": "string", "format": "date-time", "description": "Date time at which the order was purchased by customer.", "example": "2024-01-07T10:15:30Z" }, "orderLineItemList": { "type": "array", "description": "The lineItemList consists of individual line items representing purchased products and/or products with policies. Each line item is uniquely identified by a lineItemId (String: maximum length 48 characters). The planDetails serve to identify the specific quote option acquired by the customer. OptionId is the combination of product attributes separated by #.", "items": { "type": "object", "required": [ "lineItemId", "totalPrice", "salePrice", "quantity", "productTitle", "productId", "productSKU", "totalOrderValue", "isTestOrder", "tax" ], "properties": { "lineItemId": { "type": "string", "maxLength": 48, "example": "374dc3c3-94a3-4b85-a876-8651e461446d" }, "planDetails": { "type": "object", "description": "Identifies the warranty plan bought for this line item. Send policyPurchaseDate plus one of: quoteId and quoteItemId (from List Quotes by Category), policySKU and policyPrice, or categoryId and tenure. When quoteId and quoteItemId are sent, the other fields are ignored.", "required": [ "policyPurchaseDate" ], "properties": { "policyPurchaseDate": { "type": "string", "format": "date-time", "description": "Date time at which the policy was purchased by the customer. ISO 8601 with a timezone offset or Z.", "example": "2024-01-07T10:15:30Z" }, "quoteId": { "type": "string", "description": "quoteId of the selected quote item from List Quotes by Category. Send with quoteItemId.", "example": "33f21a29-95ca-4150-b5df-afe36f5ef537" }, "quoteItemId": { "type": "string", "description": "quoteItemId of the selected quote item from List Quotes by Category. Send with quoteId.", "example": "a7defcbd-aa07-4e01-9076-c1935af20a98" }, "policySKU": { "type": "string", "description": "Policy SKU shared with the store. Send with policyPrice. A quoteItemId is not accepted here.", "example": "SBW-1U-SHAB-2900" }, "policyPrice": { "type": "number", "description": "Price of the policy purchased by the customer. Required with policySKU. Must be less than salePrice.", "example": 29 }, "categoryId": { "type": "string", "description": "Category of the plan. Send with tenure.", "example": "4c3103e4-38dc-4171-96e5-b4b77ab0e96f" }, "tenure": { "type": "number", "description": "Plan tenure. Must be a positive number. Send with categoryId.", "example": 2 } } }, "totalPrice": { "type": "number", "example": 3300 }, "quantity": { "type": "integer", "example": 3 }, "productTitle": { "type": "string", "example": "GreatCircleUSA 3-in-1 Wood Chipper - 7HP Engine, 3 Max Branch Capacity" }, "productId": { "type": "string", "example": "6673746231399" }, "optionId": { "type": "string", "example": "8577825144935" }, "productSKU": { "type": "string", "example": "ALH05" }, "salePrice": { "type": "number", "example": 1100 }, "listPrice": { "type": "number", "example": 1299 }, "discountAmount": { "type": "number", "example": 199 }, "productURL": { "type": "string", "example": "https://example.com/products/wood-chipper-alh05" } } } }, "customerDetails": { "type": "object", "required": [ "firstName", "lastName", "addressLine1", "city", "state", "country", "zipCode", "customerEmail" ], "properties": { "firstName": { "type": "string", "example": "John" }, "lastName": { "type": "string", "example": "Doe" }, "addressLine1": { "type": "string", "example": "123 Hathway Street" }, "addressLine2": { "type": "string", "example": "Apt 4B" }, "city": { "type": "string", "example": "New York City" }, "state": { "type": "string", "description": "ISO 3166-2 code", "example": "NY" }, "country": { "type": "string", "description": "Country code for USA is US", "example": "US" }, "zipCode": { "type": "string", "example": "10005" }, "customerEmail": { "type": "string", "format": "email", "example": "johndoe@gmail.com" }, "mobileNumber": { "type": "string", "example": "7872323781" } } }, "discount": { "type": "object", "properties": { "discountAmount": { "type": "number", "example": 10 } } }, "totalOrderValue": { "type": "number", "example": 1000 }, "isTestOrder": { "type": "boolean", "example": false }, "taxAmount": { "type": "number", "example": 100 } } } } } }, "responses": { "200": { "description": "Warranty created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "storeId": { "type": "string", "description": "A unique identifier for a store will be shared as part of the integration kit", "example": "f4c059b2-5b74-4e4c-a3c5-85bc80cf8a09" }, "orderId": { "type": "string", "description": "A unique identifier for the complete successful order placed by a customer on the merchant site. This represents the whole order that can have multiple line items of different quantities.", "maxLength": 48, "example": "83737121380" }, "contractList": { "type": "array", "description": "The list of contracts generated for each quantity in each line item. If any error in generating a contract, the error code and msg will be added for that item instead of the contract id.", "items": { "type": "object", "properties": { "lineItemId": { "type": "string", "example": "374dc3c3-94a3-4b85-a876-8651e461446d" }, "contractId": { "type": "string", "example": "abc12345-6789-4abc-bcde-ef1234567890" }, "isCancelled": { "type": "boolean", "example": false } } } } } } } } }, "207": { "description": "Partial order processing", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "example": true }, "storeId": { "type": "string", "description": "A unique identifier for a store will be shared as part of the integration kit", "example": "f4c059b2-5b74-4e4c-a3c5-85bc80cf8a09" }, "orderId": { "type": "string", "description": "A unique identifier for the complete successful order placed by a customer on the merchant site. This represents the whole order that can have multiple line items of different quantities.", "maxLength": 48, "example": "83737121380" }, "contractList": { "type": "array", "description": "The list of contracts generated for each quantity in each line item. If any error in generating a contract, the error code and msg will be added for that item instead of the contract id.", "items": { "type": "object", "properties": { "lineItemId": { "type": "string", "example": "374dc3c3-94a3-4b85-a876-8651e461446d" }, "contractId": { "type": "string", "example": "abc12345-6789-4abc-bcde-ef1234567890" }, "isCancelled": { "type": "boolean", "example": false } } } }, "errorList": { "type": "array", "description": "The list of contracts generated for each quantity in each line item. If any error in generating a contract, the error code and msg will be added for that item instead of the contract id.", "items": { "type": "object", "properties": { "lineItemId": { "type": "string", "example": "374dc3c3-94a3-4b85-a876-8651e461446d" }, "error": { "type": "string", "example": "planDetails.policyPurchaseDate is required" } } } } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "storeId": { "type": "string", "description": "A unique identifier for a store will be shared as part of the integration kit", "example": "f4c059b2-5b74-4e4c-a3c5-85bc80cf8a09" }, "orderId": { "type": "string", "description": "A unique identifier for the complete successful order placed by a customer on the merchant site. This represents the whole order that can have multiple line items of different quantities.", "maxLength": 48, "example": "83737121380" }, "errorList": { "type": "array", "description": "The list of contracts generated for each quantity in each line item. If any error in generating a contract, the error code and msg will be added for that item instead of the contract id.", "items": { "type": "object", "properties": { "lineItemId": { "type": "string", "example": "374dc3c3-94a3-4b85-a876-8651e461446d" }, "error": { "type": "string", "example": "planDetails.policyPurchaseDate is required" } } } } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "storeId": { "type": "string", "description": "Store Id", "example":"8577825144935" }, "errorCode": { "type": "integer", "description": "error type", "example": 500 }, "errorMessage": { "type": "string", "description": "error message", "example": "Failed to process order with internal service" } } } } } }, "401": { "description": "Authorization Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "storeId": { "type": "string", "description": "Store Id", "example":"8577825144935" }, "errorCode": { "type": "integer", "description": "error type", "example": 401 }, "errorMessage": { "type": "string", "description": "error message", "example": "X-SureBright-Access-Token header is required" } } } } } } } } } , "/api/v1/quote/listWarrantyQuotes?storeId={storeId}&country={country}": { "post": { "summary": "List Quotes by Product Details", "description": "This endpoint retrieves a list of warranty quotes based on product details (title, description, and price). The response includes detailed warranty options, pricing, and coverage information similar to other quote endpoints.", "operationId": "listWarrantyQuotes", "tags": [ "quotes" ], "parameters": [ { "name": "storeId", "in": "query", "required": true, "schema": { "type": "string", "example": "ecca4210-09a4-446c-ad87-5e65bd50df12" }, "description": "A unique identifier for a store will be shared as part of the integration kit" }, { "name": "country", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]{2}$", "example": "US" }, "description": "The country code of the identified customer location" }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "example": "AL" }, "description": "The state code of the identified customer location" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "productTitle", "productPrice" ], "properties": { "productTitle": { "type": "string", "description": "The title or name of the product", "example": "Sony Bravia OLED 4K" }, "productDescription": { "type": "string", "description": "The description of the product", "example": "4K LED TV" }, "productPrice": { "type": "number", "description": "The price of the product", "example": 21 } } } } } }, "responses": { "200": { "description": "Quotes Found", "content": { "application/json": { "schema": { "type": "object", "required": [ "warrantyQuoteId", "warrantyQuoteItemList", "coverageWidgetHeading", "coveragePopupHeading", "coverageList" ], "properties": { "lowerPrice": { "type": "number", "format": "float", "example": 0 }, "upperPrice": { "type": "number", "format": "float", "example": 499.99 }, "warrantyQuoteId": { "type": "string", "description": "A unique ID representing this specific return quote in this particular API call", "example": "929d14dd-2937-4290-9818-8fca2a00a9a3" }, "warrantyQuoteItemList": { "type": "array", "description": "A list of warranty offers generated for this particular request", "items": { "type": "object", "properties": { "warrantyTenure": { "type": "integer", "description": "Duration of the warranty in years", "example": 2 }, "warrantyPrice": { "type": "number", "format": "float", "description": "Price of the warranty", "example": 64.99 }, "warrantyQuoteItemId": { "type": "string", "description": "Unique identifier for the warranty quote item", "example": "8c78bc1a-0790-4cd3-a3f9-5ed97bbe59f5" }, "warrantySKU": { "type": "string", "description": "Unique SKU for the warranty quote item", "example": "SBW-1U-SHAB-40099" } } } }, "tncLink": { "type": "string", "description": "Unique link for legal Terms & Conditions of the warranty for each product Category", "example": "https://customer.surebright.com/t-c/098e0e696f20839479dfe4a2804756233d32130f068441e24c6c0dbbc790677ff9718e04396a18dac753d0cf92bcaf63a26d2b666e5326475d0b2ed7475ad7fc" }, "productImageUrl": { "type": "string", "description": "Link of the product image that can be show as part of the warranty offer UI", "example": "https://cdn.shopify.com/s/files/1/0254/6227/6182/products/bedbathandimage.jpg?v=1664467971" }, "coverageWidgetHeading": { "type": "string", "description": "Heading for the various tenure options shown to a customer on the product page", "example": "Add premium product protection" }, "coveragePopupHeading": { "type": "string", "description": "Title that nudges the customers to buy a warranty for their product purchase", "example": "Don't want to spend extra on this product for the next few years? We've got you covered!" }, "coverageList": { "type": "array", "description": "List of coverage options grouped under different sections", "items": { "type": "object", "properties": { "coverageItemType": { "type": "string", "enum": [ "COVERAGE_OPTION", "WHY_SUREBRIGHT" ], "example": "COVERAGE_OPTION" }, "coverageItemTitle": { "type": "string", "example": "Your warranty plan provides," }, "coverageItemList": { "type": "array", "items": { "type": "string" }, "example": [ "Protection against everyday spills (food, beverages, human or pet biological stains, cosmetics, etc)." ] } } } } } } } } }, "511": { "description": "Insufficient Parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 511 }, "errorMessage": { "type": "string", "description": "error message", "example": "Insufficient Parameters" } } } } } }, "512": { "description": "Validation Failed for Input Parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 512 }, "errorMessage": { "type": "string", "description": "error message", "example": "Validation Failed for Input Parameters" } } } } } }, "513": { "description": "Product Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 513 }, "errorMessage": { "type": "string", "description": "error message", "example": "Product Not Found" } } } } } }, "514": { "description": "No Quote Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 514 }, "errorMessage": { "type": "string", "description": "error message", "example": "No Quote Found" } } } } } }, "515": { "description": "Store Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 515 }, "errorMessage": { "type": "string", "description": "error message", "example": "Store Not Found" } } } } } }, "516": { "description": "Not Eligible", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 516 }, "errorMessage": { "type": "string", "description": "error message", "example": "Not Eligible" } } } } } }, "517": { "description": "Category Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 517 }, "errorMessage": { "type": "string", "description": "error message", "example": "Category Not Found" } } } } } }, "500": { "description": "Something Unexpectedly Went Wrong", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 500 }, "errorMessage": { "type": "string", "description": "error message", "example": "Something Unexpectedly Went Wrong" } } } } } } } } } , "/site-platform/api/v1/categorize/product": { "post": { "summary": "Categorize Product", "description": "This endpoint categorizes a product based on its title, description, and other attributes. It returns the SureBright category information including category ID, category name, and SB category name.", "operationId": "categorizeProduct", "tags": [ "product-category" ], "parameters": [ { "name": "X-SureBright-Access-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Access token for authentication" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "productTitle", "storeId" ], "properties": { "productTitle": { "type": "string", "description": "The title or name of the product to be categorized", "example": "Sony Bravia OLED 4K" }, "storeId": { "type": "string", "description": "A unique identifier for a store will be shared as part of the integration kit", "example": "3226a01adbf64d94803dac879d1fba099" }, "description": { "type": "string", "description": "The description of the product", "example": "55-inch 4K OLED Smart TV with HDR" }, "quantity": { "type": "integer", "description": "The quantity of the product", "example": 1 }, "productPrice": { "type": "number", "description": "The price of the product", "example": 21 } } } } } }, "responses": { "200": { "description": "Product categorized successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "Indicates if an error occurred", "example": false }, "message": { "type": "string", "description": "Response message", "example": "Product categorized successfully" }, "lineItemsList": { "type": "object", "description": "The categorized product information", "properties": { "productTitle": { "type": "string", "description": "The title or name of the product", "example": "Sony Bravia OLED 4K" }, "quantity": { "type": "integer", "description": "The quantity of the product", "example": 1 }, "productPrice": { "type": "number", "description": "The price of the product", "example": 21 }, "sbCategoryId": { "type": "string", "description": "Unique identifier for the SureBright category", "example": "aedd580b-9a9e-4ceb-8f9a-f239f04f817a" }, "categoryName": { "type": "string", "description": "The name of the category assigned to the product", "example": "System Warranty - B" }, "sbCategoryName": { "type": "string", "description": "The SureBright category name", "example": "TV_MONITOR" } } } }, "example": { "isError": false, "message": "Product categorized successfully", "lineItemsList": { "productTitle": "Sony Bravia OLED 4K", "quantity": 1, "productPrice": 21, "sbCategoryId": "aedd580b-9a9e-4ceb-8f9a-f239f04f817a", "categoryName": "System Warranty - B", "sbCategoryName": "TV_MONITOR" } } } } } }, "511": { "description": "Insufficient Parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 511 }, "errorMessage": { "type": "string", "description": "error message", "example": "Insufficient Parameters" } } } } } }, "512": { "description": "Validation Failed for Input Parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 512 }, "errorMessage": { "type": "string", "description": "error message", "example": "Validation Failed for Input Parameters" } } } } } }, "513": { "description": "Product Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 513 }, "errorMessage": { "type": "string", "description": "error message", "example": "Product Not Found" } } } } } }, "514": { "description": "No Quote Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 514 }, "errorMessage": { "type": "string", "description": "error message", "example": "No Quote Found" } } } } } }, "515": { "description": "Store Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 515 }, "errorMessage": { "type": "string", "description": "error message", "example": "Store Not Found" } } } } } }, "516": { "description": "Not Eligible", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 516 }, "errorMessage": { "type": "string", "description": "error message", "example": "Not Eligible" } } } } } }, "517": { "description": "Category Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 517 }, "errorMessage": { "type": "string", "description": "error message", "example": "Category Not Found" } } } } } }, "500": { "description": "Something Unexpectedly Went Wrong", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 500 }, "errorMessage": { "type": "string", "description": "error message", "example": "Something Unexpectedly Went Wrong" } } } } } } } } }, "/quote/api/whole-system/listQuotes": { "post": { "summary": "List Quotes for Whole System Warranty", "description": "This endpoint generates warranty quotes for a whole system order. Provide your store, product line items, and installer warranty duration to receive available warranty plans, prices, product coverage details, and terms and conditions. When quotes are available, SureBright saves them and your product details as a proposal that you can update or use to create a contract. For an initial quote request, omit sbProposalId. You can include a new partnerProposalId to associate the proposal with an ID from your system. Save the returned sbProposalId for updated quotes and contract creation. To update quotes for an existing proposal, include sbProposalId or partnerProposalId with your current line items and installer warranty duration. Any supplied partnerProposalId must refer to the same proposal. Quotes are recalculated using the submitted details and current pricing and coverage. Unchanged products, classification, installer warranty duration, pricing, and coverage retain the existing quote and plan IDs; changed details update the proposal and its quotes. Use the quote and plan IDs from the same response when creating or updating a contract. Updating quotes does not automatically update an existing contract.\n\nBackward compatibility: Existing integrations can use sbSalesLeadId to request updated quotes or create and update contracts. It has the same value as sbProposalId in the response. Omit it from the initial quote request. If both identifiers are supplied, their values must match; otherwise, the quote endpoint returns HTTP 409 with code SB_PROPOSAL_ID_MISMATCH. Any supplied partnerProposalId must refer to the same proposal. For new integrations, use sbProposalId.", "operationId": "listWarrantyQuotesForWholeSystemWarranty", "tags": [ "quotes" ], "parameters": [ ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "storeId", "lineItemList", "installerWarrantyDuration" ], "properties": { "storeId": { "type": "string", "description": "A unique identifier for the store", "example": "test-store-id" }, "partnerProposalId": { "type": "string", "description": "The proposal ID from your system. Optional when creating a proposal; use a new ID for a new proposal. Reuse this ID to request updated quotes for the same proposal. If sbProposalId is also supplied, both identifiers must refer to the same proposal.", "example": "9f3e21c6-6bdb-4c7f-9b91-2a4f9a2c7d11" }, "sbProposalId": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The SureBright proposal ID returned by this endpoint. Include it to request updated quotes for an existing proposal. Any supplied partnerProposalId must refer to the same proposal.", "example": "da5747e7-a60d-4625-a91d-ea2728ecf589" }, "lineItemList": { "type": "array", "description": "A list of line items representing the products in the order", "items": { "type": "object", "required": [ "title", "unitPrice", "quantity" ], "properties": { "title": { "type": "string", "description": "The title or name of the product", "example": "PMC Prophecy5 2-Way Floorstanding Speaker (Pair)" }, "unitPrice": { "type": "number", "format": "float", "description": "The unit price of the product purchased", "example": 6500 }, "categoryTag": { "type": "string", "description": "The category tag for the product", "example": "Speaker Floorstanding" }, "quantity": { "type": "integer", "description": "The quantity of the product purchased", "example": 1 }, "description": { "type": "string", "description": "The description of the product", "example": "High-performance floorstanding speaker pair for immersive audio systems." } } } }, "installerWarrantyDuration": { "type": "integer", "description": "The duration of the installer warranty in months", "example": 3 }, "sbSalesLeadId": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Backward compatibility: Existing integrations can use this identifier instead of sbProposalId to request updated quotes. Omit it from the initial quote request. If both are supplied, their values must match. Any supplied partnerProposalId must refer to the same proposal. For new integrations, use sbProposalId.", "example": "da5747e7-a60d-4625-a91d-ea2728ecf589" } }, "example": { "storeId": "test-store-id", "partnerProposalId": "9f3e21c6-6bdb-4c7f-9b91-2a4f9a2c7d11", "lineItemList": [ { "title": "PMC Prophecy5 2-Way Floorstanding Speaker (Pair)", "unitPrice": 6500, "categoryTag": "Speaker Floorstanding", "quantity": 1, "description": "High-performance floorstanding speaker pair for immersive audio systems." } ], "installerWarrantyDuration": 3 } } } } }, "responses": { "200": { "description": "Quotes Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "warrantyQuoteId": { "type": "string", "description": "The ID of the returned warranty quote. Use it together with a warrantyQuoteItemId from this response when creating or updating a contract.", "example": "36eaa6e3-ca1f-4bc1-86da-76caf7a7114d" }, "totalCoveredAmount": { "type": "number", "format": "float", "description": "Total covered amount for the product purchased", "example": 6500.00 }, "sbProposalId": { "type": "string", "description": "The SureBright proposal ID. Use it to request updated quotes or create and update a contract for this proposal. Null when no proposal is available.", "example": "da5747e7-a60d-4625-a91d-ea2728ecf589", "nullable": true }, "sbSalesLeadId": { "type": "string", "description": "Backward compatibility: The same value as sbProposalId. Existing integrations can use it to request updated quotes or create and update contracts. For new integrations, use sbProposalId. Null when no proposal is available.", "example": "da5747e7-a60d-4625-a91d-ea2728ecf589", "nullable": true }, "tncLink": { "type": "string", "description": "Unique link for legal Terms & Conditions of the warranty for each product Category", "example": "https://customer.surebright.com/t-c/098e0e696f20839479dfe4a2804756233d32130f068441e24c6c0dbbc790677f71879502aee2ce87e116739d4dae3332" }, "warrantyQuoteItemList": { "type": "array", "description": "A list of warranty offers generated for this particular request", "items": { "type": "object", "properties": { "warrantyQuoteItemId": { "type": "string", "description": "Unique identifier for the warranty quote item", "example": "a7defcbd-aa07-4e01-9076-c1935af20a98" }, "coverageYears": { "type": "integer", "description": "Duration of the warranty in years", "example": 2 }, "quotePrice": { "type": "number", "format": "float", "description": "Price of the warranty quote", "example": 40.0 } } } }, "coverageWidgetHeading": { "type": "string", "description": "Heading for the various tenure options shown to a customer on the product page", "example": "Add premium product protection" }, "coveragePopupHeading": { "type": "string", "description": "Title that nudges the customers to buy a warranty for their product purchase", "example": "Don't want to spend extra on this product for the next few years? We've got you covered!" }, "coverageList": { "type": "array", "description": "List of coverage options grouped under different sections", "items": { "type": "object", "properties": { "coverageItemType": { "type": "string", "enum": [ "COVERAGE_OPTION", "WHY_SUREBRIGHT_OPTION" ], "example": "COVERAGE_OPTION" }, "coverageItemTitle": { "type": "string", "example": "Your warranty plan provides," }, "coverageItemList": { "type": "array", "items": { "type": "string" }, "example": [ "Comprehensive coverage for mechanical or electrical breakdowns and even power surges", "100% coverage for repairs for extended years that also includes labor and not just parts", "Coverage for inevitable wear and tear affecting the product's functionality after years of usage", "Replacement or reimbursement, if we can't repair it" ] } } } }, "lineItemList": { "type": "array", "description": "A list of line items with full product information and coverage status", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "The title or name of the product", "example": "PMC Prophecy5 2-Way Floorstanding Speaker (Pair)" }, "unitPrice": { "type": "number", "format": "float", "description": "The unit price of the product purchased", "example": 6500 }, "isCovered": { "type": "boolean", "description": "Indicates whether the line item is covered by the warranty", "example": true }, "sbCategoryName": { "type": "string", "description": "The SureBright category name for the product", "example": "Speaker Floorstanding" }, "quantity": { "type": "integer", "description": "The quantity of the product purchased", "example": 1 }, "description": { "type": "string", "description": "The description of the product", "example": "High-performance floorstanding speaker pair for immersive audio systems." } } } } } } } } }, "511": { "description": "Insufficient Parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 511 }, "message": { "type": "string", "description": "error message", "example": "Insufficient Parameters" } } } } } }, "512": { "description": "Validation Failed for Input Parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 512 }, "message": { "type": "string", "description": "error message", "example": "Validation Failed for Input Parameters" } } } } } }, "513": { "description": "No Quote Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 513 }, "message": { "type": "string", "description": "error message", "example": "No Quote Found" } } } } } }, "514": { "description": "Store Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 514 }, "message": { "type": "string", "description": "error message", "example": "Store Not Found" } } } } } }, "515": { "description": "Not Eligible", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 515 }, "message": { "type": "string", "description": "error message", "example": "Not Eligible" } } } } } }, "516": { "description": "Category Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 516 }, "message": { "type": "string", "description": "error message", "example": "Category Not Found" } } } } } }, "500": { "description": "Something Unexpectedly Went Wrong", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 500 }, "message": { "type": "string", "description": "error message", "example": "Something Unexpectedly Went Wrong" } } } } } }, "400": { "description": "sbProposalId must be a non-empty string of at most 200 characters.\n\nBackward compatibility: The same validation applies to sbSalesLeadId when supplied.", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean" }, "message": { "type": "string" }, "code": { "type": "string", "description": "Included for sbProposalId requests.\n\nBackward compatibility: Also included for sbSalesLeadId requests." } } }, "examples": { "invalidProposalId": { "summary": "Invalid sbProposalId", "value": { "isError": true, "message": "sbProposalId must be a non-empty string of at most 200 characters", "code": "INVALID_SB_PROPOSAL_ID" } }, "invalidSalesLeadId": { "summary": "Invalid sbSalesLeadId", "value": { "isError": true, "message": "sbSalesLeadId must be a non-empty string of at most 200 characters", "code": "INVALID_SB_SALES_LEAD_ID" } } } } } }, "404": { "description": "Proposal Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean" }, "message": { "type": "string" }, "code": { "type": "string", "description": "Included for sbProposalId requests.\n\nBackward compatibility: Also included for sbSalesLeadId requests." } } }, "example": { "isError": true, "message": "Proposal Not Found", "code": "SB_PROPOSAL_NOT_FOUND" } } } }, "409": { "description": "PROPOSAL_ID_MISMATCH means partnerProposalId does not refer to the proposal identified by sbProposalId.\n\nBackward compatibility: SB_PROPOSAL_ID_MISMATCH means sbProposalId and sbSalesLeadId have different values. When sbSalesLeadId identifies the proposal, a conflicting partnerProposalId also returns PROPOSAL_ID_MISMATCH.", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean" }, "message": { "type": "string" }, "code": { "type": "string", "description": "Included for sbProposalId requests.\n\nBackward compatibility: Also included for sbSalesLeadId requests." } } }, "example": { "isError": true, "message": "sbProposalId and partnerProposalId must identify the same proposal", "code": "PROPOSAL_ID_MISMATCH" } } } }, "502": { "description": "The quote could not be saved. Request quotes again before creating or updating a contract.", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean" }, "message": { "type": "string" }, "code": { "type": "string", "description": "Included for sbProposalId requests.\n\nBackward compatibility: Also included for sbSalesLeadId requests." } } }, "example": { "isError": true, "message": "Could not persist the partner quote", "code": "QUOTE_PERSISTENCE_FAILED" } } } } } } }, "/partner/api/v1/order/whole-system": { "post": { "summary": "Create / Update Contracts for Whole System Warranty", "description": "This endpoint creates or updates a warranty contract for a whole system proposal. Provide sbProposalId, the selected warranty quote and plan details, and customer information. The covered line items, total covered amount, and installer warranty duration come from the proposal. If a contract already exists for the proposal, it is updated. Covered line items can be updated within 90 days from the original sale date; updates do not restart this window. Customer details and other non-line item fields can still be updated afterward, subject to the usual request validations.\n\nBackward compatibility: Existing integrations can provide sbSalesLeadId instead of sbProposalId. If both are supplied, their values must match; otherwise, the endpoint returns HTTP 400 with errorType 512. For new integrations, use sbProposalId.", "operationId": "createContractsForWholeSystemWarranty", "tags": [ "orders" ], "parameters": [ { "name": "X-SureBright-Access-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Access token for authentication" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "storeId", "warrantyQuoteId", "warrantyQuoteItemId", "warrantyPrice", "warrantyCoverageYears", "customerDetails" ], "anyOf": [ { "required": [ "sbProposalId" ] }, { "required": [ "sbSalesLeadId" ] } ], "properties": { "storeId": { "type": "string", "description": "A unique identifier for the store", "example": "test-store-id" }, "warrantyQuoteId": { "type": "string", "description": "The unique identifier for the warranty quote obtained from the List Quotes for Whole System Warranty endpoint", "example": "36eaa6e3-ca1f-4bc1-86da-76caf7a7114d" }, "warrantyQuoteItemId": { "type": "string", "description": "The unique identifier for the warranty quote item obtained from the List Quotes for Whole System Warranty endpoint", "example": "a7defcbd-aa07-4e01-9076-c1935af20a98" }, "sbProposalId": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The SureBright proposal ID returned by the List Quotes API. Required to identify the proposal, subject to the backward-compatibility exception described above. The proposal must belong to the supplied storeId.", "example": "da5747e7-a60d-4625-a91d-ea2728ecf589" }, "sbSalesLeadId": { "type": "string", "description": "Backward compatibility: Existing integrations can provide this identifier instead of sbProposalId to create or update contracts. It has the same value as sbProposalId. If both are supplied, their values must match. The proposal must belong to the supplied storeId. For new integrations, use sbProposalId.", "example": "da5747e7-a60d-4625-a91d-ea2728ecf589" }, "warrantyPrice": { "type": "number", "format": "float", "description": "Price charged to the customer for the warranty. If it differs from the selected plan price, the difference adjusts your merchant margin.", "example": 40.0 }, "warrantyCoverageYears": { "type": "integer", "description": "Duration of the warranty coverage in years. Must equal the resolved quote item's `coverageYears`; otherwise the request is rejected with 520.", "example": 2 }, "customerDetails": { "type": "object", "description": "Customer information for the warranty contract", "required": [ "customerEmail", "customerFirstName", "customerLastName" ], "properties": { "customerEmail": { "type": "string", "format": "email", "description": "Customer email address", "example": "john.doe@example.com" }, "customerPhone": { "type": "string", "description": "Customer phone number", "example": "+1 (615) 555-0123" }, "customerFirstName": { "type": "string", "description": "Customer first name", "example": "John" }, "customerLastName": { "type": "string", "description": "Customer last name", "example": "Doe" }, "customerAddress1": { "type": "string", "description": "Customer primary address line", "example": "1234 Tulip Grove Rd" }, "customerAddress2": { "type": "string", "description": "Customer secondary address line (apt, suite, etc.)", "example": "Suite 100" }, "customerCity": { "type": "string", "description": "Customer city", "example": "Nashville" }, "customerState": { "type": "string", "description": "Customer state or province", "example": "TN" }, "customerCountry": { "type": "string", "description": "Customer country", "example": "USA" }, "customerZipCode": { "type": "string", "description": "Customer postal/zip code", "example": "37076" }, "addressType": { "type": "string", "description": "Type of address", "enum": ["BILLING", "SHIPPING"], "example": "BILLING" } } } }, "example": { "storeId": "test-store-id", "warrantyQuoteId": "36eaa6e3-ca1f-4bc1-86da-76caf7a7114d", "warrantyQuoteItemId": "a7defcbd-aa07-4e01-9076-c1935af20a98", "sbProposalId": "da5747e7-a60d-4625-a91d-ea2728ecf589", "warrantyPrice": 40.0, "warrantyCoverageYears": 2, "customerDetails": { "customerEmail": "john.doe@example.com", "customerPhone": "+1 (615) 555-0123", "customerFirstName": "John", "customerLastName": "Doe", "customerAddress1": "1234 Tulip Grove Rd", "customerAddress2": "Suite 100", "customerCity": "Nashville", "customerState": "TN", "customerCountry": "USA", "customerZipCode": "37076", "addressType": "BILLING" } } } } } }, "responses": { "200": { "description": "Contract Created or Updated Successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "Indicates if an error occurred", "example": false }, "contractId": { "type": "string", "description": "The unique identifier for the warranty contract created or updated.", "example": "54a3a238407f426e862a0a11cab11164" } } } } } }, "512": { "description": "Validation Failed for Input Parameters. Provide sbProposalId as a non-empty string of at most 200 characters.\n\nBackward compatibility: Existing integrations can provide sbSalesLeadId instead; if both identifiers are supplied, their values must match.", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 512 }, "message": { "type": "string", "description": "error message", "example": "Validation Failed for Input Parameters" }, "errors": { "type": "array", "description": "Details of the request validation failures.", "items": { "type": "string" }, "example": [ "sbProposalId and sbSalesLeadId must identify the same proposal" ] } } } } } }, "513": { "description": "No Quote Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 513 }, "message": { "type": "string", "description": "error message", "example": "No Quote Found" } } } } } }, "514": { "description": "Store Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 514 }, "message": { "type": "string", "description": "error message", "example": "Store Not Found" } } } } } }, "515": { "description": "Sales Lead Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 515 }, "message": { "type": "string", "description": "error message", "example": "Sales Lead Not Found" } } } } } }, "516": { "description": "Contract Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 516 }, "message": { "type": "string", "description": "error message", "example": "Contract not found" } } } } } }, "517": { "description": "Line Items Update Not Allowed: covered line items cannot be changed after 90 days from the original sale date. Updates do not restart this window.", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 517 }, "message": { "type": "string", "description": "error message", "example": "Line items cannot be updated after 90 days of purchase date" } } } } } }, "518": { "description": "Quote ID Mismatch", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 518 }, "message": { "type": "string", "description": "error message", "example": "Quote ID mismatch" } } } } } }, "519": { "description": "Quote Item Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 519 }, "message": { "type": "string", "description": "error message", "example": "Quote item not found" } } } } } }, "520": { "description": "Warranty Coverage Years Mismatch", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 520 }, "message": { "type": "string", "description": "error message", "example": "Warranty coverage years do not match quote item" } } } } } }, "500": { "description": "Something Unexpectedly Went Wrong", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 500 }, "message": { "type": "string", "description": "error message", "example": "Something Unexpectedly Went Wrong" } } } } } }, "401": { "description": "Authorization Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 401 }, "message": { "type": "string", "description": "error message", "example": "X-SureBright-Access-Token header is required" } } } } } } } } }, "/partner/api/v1/order/whole-system/cancel?contractId={contractId}": { "post": { "summary": "Cancel Contract for Whole System Warranty", "description": "This endpoint cancels an existing warranty contract for a whole system order. Provide the contract ID obtained from the Create Contracts for Whole System Warranty endpoint. The API returns the cancellation status of the warranty contract.", "operationId": "cancelContractForWholeSystemWarranty", "tags": [ "orders" ], "parameters": [ { "name": "X-SureBright-Access-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Access token for authentication" }, { "name": "contractId", "in": "query", "required": true, "schema": { "type": "string", "example": "5233a92bfcc04a77920abfa1fe52194a" }, "description": "The unique identifier for the warranty contract to be cancelled" } ], "responses": { "200": { "description": "Contract Cancelled Successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "Indicates if an error occurred", "example": false }, "message": { "type": "string", "description": "Success message", "example": "Contract cancelled successfully" }, "contractId": { "type": "string", "description": "The unique identifier for the cancelled warranty contract", "example": "54a3a238407f426e862a0a11cab11164" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 400 }, "message": { "type": "string", "description": "error message", "example": "contractId is required" } } }, "examples": { "cancellationWindowExpired": { "summary": "contractId is required", "value": { "isError": true, "errorType": 400, "message": "contractId is required" } } } } } }, "401": { "description": "Authorization Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 401 }, "message": { "type": "string", "description": "error message", "example": "X-SureBright-Access-Token header is required" } } } } } }, "503": { "description": "Access Denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 503 }, "message": { "type": "string", "description": "error message", "example": "Contract access denied" } } } } } }, "504": { "description": "Contract Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 504 }, "message": { "type": "string", "description": "error message", "example": "Contract not found" } } } } } }, "505": { "description": "Contract can be cancelled only within 30 days from order creation date", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 505 }, "message": { "type": "string", "description": "error message", "example": "Contract can be cancelled only within 30 days from order creation date" } } } } } }, "502": { "description": "Service Unreachable", "content": { "application/json": { "schema": { "type": "object", "properties": { "isError": { "type": "boolean", "description": "true" }, "errorType": { "type": "integer", "description": "error type", "example": 502 }, "message": { "type": "string", "description": "error message", "example": "Something went wrong" } } } } } } } } }, "/partner/api/v1/servify/claim-service-status":{ "post":{ "summary": "SureBright’s update claim and service status API for Servify", "description": "", "operationId": "updateClaimServiceStatus", "tags": [ "servify" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "externalReferenceId", "claimId", "claimStatus", "serviceId", "serviceType", "serviceStatus" ], "properties": { "externalReferenceId": { "type": "string", "description": "uniqueID for contract", "example": "2db497c6bd37464eb6e59839c1ca5ba1" }, "claimId": { "type": "string", "description": "Unique claim reference Id generated by Servify", "example": "XYZ12321IO" }, "claimStatus": { "type": "string", "description": "Current status of claim", "example": "Open", "enum": ["Open", "Cancelled", "Closed"] }, "serviceId": { "type": "string", "description": "serviceId if one claim can have multiple service request otherwise same as claimId", "example": "G76BBG9B4Z" }, "serviceType": { "type": "string", "description": "Type of service", "example": "Repair", "enum": ["Repair", "Replacement", "Reimbursement", "Theft", "Loss"] }, "serviceStatus": { "type": "string", "description": "Current status of service request", "example": "Service accepted", "enum": [ "Service accepted", "Device received", "Service Initiated", "Parts Pending", "Parts Received", "Service completed", "Service cancelled", "Device ready for pick up", "Device shipped", "Device delivered", "Replacement options provided", "Replacement chosen", "Replacement Device Shipped", "Replacement Device delivered", "Non-return fee charged", "Device not eligible for service", "claim estimation generated", "Document under verification", "Reimbursement Approved", "Technician Initiate journey", "Technician arrived", "Technician OTP verification" ] }, "updateAt": { "type": "string", "format": "date-time", "description": "Date time of update", "example": "2021-09-08T07:59:35.000Z" }, "servifyServiceMode": { "type": "string", "description": "Servify service mode", "example": "WI", "enum": ["WI", "MI", "OS", "PND"] }, "replacementOptions": { "type": "array", "description": "Replacement device options, mandatory only if status \"Replacement Options Provided\" selected", "items": { "type": "string" }, "example": ["Macbook Pro 13' 128GB", "Macbook Pro 13' 256GB", "Macbook Pro 13' 512GB"] }, "deductibleAmount": { "type": "number", "description": "Deductible amount from claim", "example": 120 }, "coveredAmount": { "type": "number", "description": "Total covered amount of claim", "example": 1200 }, "country": { "type": "string", "description": "Country of customer", "example": "US" }, "currency": { "type": "string", "description": "Currency of customer", "example": "USD" }, "claimSubmittedAt": { "type": "string", "format": "date-time", "description": "Date time when claim was raised", "example": "2021-09-08T07:59:35.000Z" }, "remarks": { "type": "string", "description": "Cancellation reason", "example": "" } } } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "Status code", "example": 200 }, "message": { "type": "string", "description": "Success or failure message", "example": "Claim's service status updated successfully" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "Status code", "example": 500 }, "message": { "type": "string", "description": "Error message", "example": "System failure" } } } } } }, "503": { "description": "Temporary outage / DB down", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "Status code", "example": 503 }, "message": { "type": "string", "description": "Error message", "example": "Temporary outage / DB down" } } } } } }, "504": { "description": "API timeout or downstream service timeout", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "Status code", "example": 504 }, "message": { "type": "string", "description": "Error message", "example": "API timeout or downstream service timeout" } } } } } }, "400": { "description": "Request body is malformed / wrong datatype", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "Status code", "example": 400 }, "message": { "type": "string", "description": "Error message", "example": "Invalid JSON format" } } } } } }, "510": { "description": "Missing Mandatory Parameter", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "Status code", "example": 510 }, "message": { "type": "string", "description": "Error message", "example": "Missing mandatory claimId parameter" } } } } } }, "511": { "description": "Invalid Parameter Value", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "Status code", "example": 511 }, "message": { "type": "string", "description": "Error message", "example": "Invalid claimStatus value" } } } } } }, "512": { "description": "Invalid Date Format", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "Status code", "example": 512 }, "message": { "type": "string", "description": "Error message", "example": "Invalid date format for updateAt" } } } } } }, "513": { "description": "Invalid Status Transition", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "Status code", "example": 513 }, "message": { "type": "string", "description": "Error message", "example": "Cannot move from Closed → Open" } } } } } }, "514": { "description": "Replacement Options Required", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "Status code", "example": 514 }, "message": { "type": "string", "description": "Error message", "example": "Replacement options required for status Replacement Options Provided" } } } } } }, "401": { "description": "API key invalid / missing", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "Status code", "example": 401 }, "message": { "type": "string", "description": "Error message", "example": "API key invalid / missing" } } } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "Status code", "example": 403 }, "message": { "type": "string", "description": "Error message", "example": "Access denied to contract / claim" } } } } } }, "515": { "description": "externalReferenceId not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "Status code", "example": 515 }, "message": { "type": "string", "description": "Error message", "example": "externalReferenceId not found" } } } } } }, "516": { "description": "Claim Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "Status code", "example": 516 }, "message": { "type": "string", "description": "Error message", "example": "claimId does not exist" } } } } } }, "517": { "description": "serviceId already exists for claim", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "Status code", "example": 517 }, "message": { "type": "string", "description": "Error message", "example": "serviceId already exists for claim" } } } } } }, "518": { "description": "Status Already Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "Status code", "example": 518 }, "message": { "type": "string", "description": "Error message", "example": "duplicate update, idempotency conflict" } } } } } }, "519": { "description": "Invalid Service Type", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "Status code", "example": 519 }, "message": { "type": "string", "description": "Error message", "example": "Unsupported serviceType" } } } } } }, "520": { "description": "Invalid Currency", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "Status code", "example": 520 }, "message": { "type": "string", "description": "Error message", "example": "Currency not mapped" } } } } } }, "521": { "description": "Invalid Country", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "Status code", "example": 521 }, "message": { "type": "string", "description": "Error message", "example": "Country not supported" } } } } } } } } } } }