API Documentation

Version 201308

Introduction

  • The Warranty Life API is a simple REST modeled API.
  • You will require Warranty Life API credentials for access. If you do not already have API credentials, please sign up as a partner, or, if you have already signed up and are missing API credentials, please contact api@warrantylife.com.
  • Any returned field that is not defined in this document should be ignored in order to ensure forward compatibility with updates to this version of the API.
  • This document describes the version of the API identified as 201308.
  • All URLs shown should be prefixed with /api/201308 where the last portion is the version identifier.
  • The protocol and host name to use is

Character Set

UTF-8 is used exclusively.

Authentication

Authentication is done using HTTP Basic Authentication using your API key and API secret as the username and password values. Other forms of authentication may be introduced in future versions of the API.

Sub-Accounts

If you are using sub-accounts then you would append /sub-account-id to your API key when acting on behalf of the sub-account when authenticating. Billing of warranties is based on the authenticated account, so you must use sub-accounts if you want to have separate billing for different stores (such as for franchises) and you are not using separate API keys and secrets for each store. Sub-accounts can be created via the partner store add page where "Remote Id" is the sub-account-id.

Example: If the API key for your primary account was MqUax1IGBQdL and you were sending a request on behalf of the sub-account 43 then you would use MqUax1IGBQdL/43 as the API key (used as the username) for authentication.

Reference IDs, "refIds"

There are a number of fields called or ending in refId. The purpose of these fields is to give you the option to register your own unique identifiers with those objects, allowing you to reference them later using your own identifiers rather than needing to store Warranty Life's identifiers.

Representation Formats

The API currently supports JSON responses, served as application/json, encoded as UTF-8. That media type should always be specified in the request's Accept header.

Responses and Errors

Standard HTTP response codes are returned appropriately in the HTTP Status response header. Possible status codes include:

  • 200: Success (upon a successful GET, or PUT request)
  • 201: Created (upon a successful POST request)
  • 202: Accepted (request was accepted for processing, but the processing has not been completed)
  • 204: No Content (upon a successful DELETE request)
  • 400: Resource Invalid (improperly-formatted request)
  • 401: Unauthorized (incorrect or missing authentication credentials)
  • 403: Rejected/Forbidden (request understood but server is refusing the request)
  • 404: Resource Not Found (requesting a non-existent resource)
  • 405: Method Not Allowed (e.g., trying to POST to a URL that responds only to GET)
  • 406: Not Acceptable (server can’t satisfy the Accept header specified by the client)
  • 500: Application Error

Errors

In most cases, requests that return an "error" status code (4XX or 5XX) will contain a short JSON response body explaining the nature of the error (provided the API call asked for a JSON response). 

{
  "error_code": 0,
  "status_text": "Bad Request",
  "message": "The ID specified does not exist."
}

Other HTTP verbs

Successful POST requests (e.g., to create a new record) will return a status code of 200, 201 or 202. If the status is 201 then the response will include a Location header with the URI of the newly-created resource, and include a JSON representation of the resource in the body of the response. If the status code is 202 then the response will contain an id that will be the identifier for the object once it exists and can be used in future requests.

Successful PUT requests (e.g., to update an existing record) will return a status code of 200 or 202, and include a JSON representation of the resource in the body of the response.

Successful DELETE requests (e.g., to delete an existing record) will return a status code of 204 and no body.

Wildcards

Certain parameters in some of the API calls allow the use of wildcards in parameters used to perform searches. These parameters are marked below like this. In these fields, you may use the asterisk character (*) to represent "zero or more characters at this point." For example "Apple*" would match "Apple", "Appleton", "Applewood", etc. Without the wildcard character used in this example, only "Apple" would match.

Paging

For some API calls, the results are paged, meaning only a subset of all possible results are returned. For these calls, the parameters startAt and limit are used to specify which page of the results should be returned. If these terms are not included, the default of returning the first page of results (startAt=0) will be used with the default number of results.

  • startAt - Specifies the offset to start results
  • limit - Specifies the maximum number of results to return
Example:

If you wanted pages of 50 results each, you might make the following calls to get the first three pages of results:

  1. startAt=0&limit=50 - Returns the first page of 50 results
  2. startAt=50&limit=50 - Returns the second page of 50 results
  3. startAt=100&limit=50 - Returns the third page of 50 results

Developer Testing Tool

An example client written in PHP as a Symfony bundle for the Warranty Life API is available from GitHub at https://github.com/WarrantyLife/ApiExampleBundle.

This example client is also hosted directly on Warranty Life servers (requires a partner account with API access):

Workflow Overview

Warranty Purchases

The general workflow for adding warranty purchases into the system is:

  1. Add the customer if the customer does not already exist in the system
    • If a warranty is purchased then contact information must be provided
    • The customerId can be looked up using a refId if required
  2. Add the purchased item for the customer
    • The productId or productSku must be provided for this step. It is advised that all your products be added ahead of time, otherwise the product may need to be added via a separate API call before this step
  3. If a warranty is purchased, add the purchased warranty

Available warranty plans for a product are based on the price and category of the product. You will want to fetch a list of the categories and warranty plans in order to determine which plans are available for the products you sell so that you can have a ready list for your customers. These lists do not change very often, but you are advised to check for updates periodically (once a week to once a month).

In order to keep the purchase workflow simple it is best to add your products via the API ahead of time. This will allow you to add the purchased item using your SKUs instead of having to do a lookup via the API each time a product is purchased. This also allows you to fetch information via the API about the product including which plans are available for it.

API Endpoints

Categories

Fetch information about a single category

  • GET /api/201308/categories/categoryId

    Returns a single category object.

    ← 200
{
  "id": "categoryId",
  "name": "category name",
  "subCategoryIds": ["categoryId", …],
  "parentCategoryId": "categoryId"
}

    Notes:

    • parentCategoryId may be null, identifying a top-level category

Fetch all categories

  • GET /api/201308/categories

    Returns an array of category objects.

Warranty Plans

Fetch information about a single warranty plan

  • GET /api/201308/warranty-plans/warrantyPlanId 
    ← 200
{
  "id": "warrantyPlanId",
  "applicableCategoryIds": ["categoryId", …],
  "applicableProductFlags": [
      "product flag, at least one in this list must match one of the product's flags",
      …
  ],
  "name": "warranty name",
  "description": "full text description of warranty",
  "deductible": "text description of deductible info",
  "productMinPrice": 0.00,
  "productMaxPrice": 0.00,
  "duration": 0,
  "durationUnit": "[days|months|years]",
  "isDurationFixed": true,
  "partsDuration": 0,
  "partsDurationUnit": "[days|months|years]",
  "labourDuration": 0,
  "labourDurationUnit": "[days|months|years]",
  "rmaShippingCoverage": 0|1|2,
  "serviceLocation": "",
  "claimPhone": "",
  "planAvailableFrom": "yyyy-MM-ddTHH:mm:ssZ",
  "planAvailableTo": "yyyy-MM-ddTHH:mm:ssZ",
  "sellableDuration": 0,
  "sellableDurationUnit": "[days|months|years]",
  "srp": 0.00,
  "wholesaleCost": 0.00,
  "retailerCost": 0.00,
  "retailPrice": 0.00,
  "currencyCode": "[USD|CAD]",
  "billingPeriod": 0,
  "billingPeriodUnit": "[days|months|years]",
  "countryCode": "[US|CA|IN|BD|PH|AU]",
  "termsUrl": "http://www.warrantylife.com/Terms_and_Conditions_Example.pdf",
  "updatedAt": "yyyy-MM-ddTHH:mm:ssZ"
}

    Notes:

    • isDurationFixed: if false, the duration of this warranty depends on conditions as described in the description. If true, you can just rely on the duration and duration unit fields alone.
    • rmaShippingCoverage: 0=No shipping covered; 1=Shipping covered one-way; 2=Shipping covered both ways to/from service location, 3=Three-way shipping which includes packing materials first send to the customer for them to use to ship their item.
    • planAvailableFrom/To: Start and End dates for when this warranty may be purchased through Warranty Life. These values may be null, which should be understood as "currently valid". Start dates may be in the future.
    • countryCode: The country in which this warranty plan is effective.
    • sellableDuration: The length of time after the purchase/repair date that this warranty may be sold to customers. If this is 0, the plan is a "DOP Warranty Plan" and thus may be sold at the time of purchase only.
    • srp: Suggested Retail Price from provider.
    • retailPrice: Our record of your current retail price for customers for this warranty plan.
    • retailerCost: The cost to the retailer for this warranty. For internal user only - not intended for display to customers.
    • wholesaleCost: Wholesale cost of warranty payable to Warranty Life. For internal use only - not intended for display to customers. Not shown to sub-accounts.
    • wholesaleCost vs retailerCost: If you do not have sub-accounts, these values are the same and represent the cost payable to Warranty Life.
    • billingPeriod: For recurring plans this specifies the periodic billing interval, is 0 for non-recurring plans.
    • termsUrl: An absolute URL to the terms and conditions for the plan.

Fetch information about all warranty plans or all that apply to a category

  • GET /api/201308/warranty-plans

    Returns an array of warranty plan objects

  • GET /api/201308/warranty-plans?categoryId=categoryId

    Returns an array of warranty plan objects

Customer

Fetch a customer by id (or email/refId/orderRefId)

  • GET /api/201308/customers/customerId
  • GET /api/201308/customers?email=email
  • GET /api/201308/customers?refId=refId
  • GET /api/201308/customers?orderRefId=orderRefId 
    ← 200
{
  "id": "customerId",                                     // Return value only
  "email": "email address for user",                      // OPTIONAL
  "refId": "your unique store reference for user",        // OPTIONAL
  "orderRefId": "your unique store reference for order",  // OPTIONAL
  "customerUrl": "http://www.example.com/reg/EXAMPLE123", // Return value only
  "salesRepEmail": "",                                    // OPTIONAL
  "emailAddress": "",                                     // OPTIONAL
  "firstName": "",                                        // REQUIRED¹
  "lastName": "",                                         // REQUIRED¹
  "companyName": "",                                      // OPTIONAL
  "streetAddress": "",                                    // REQUIRED¹
  "city": "",                                             // REQUIRED¹
  "state": "{valid 2 letter postal abbreviation}",        // REQUIRED¹
  "postalCode": "",                                       // REQUIRED¹
  "phone": "",                                            // REQUIRED¹
  "country": "[US|CA|IN|BD|PH|AU]",                       // REQUIRED
  "isWalkIn": false,                                      // OPTIONAL
                                                          // Defaults to false
  "optIn": false                                          // OPTIONAL
                                                          // Defaults to false
}

    Notes:

    • ¹ The customer name, address, and phone number is optional until a warranty is purchased; if not supplied then an attempt to purchase a warranty will fail.
    • customerUrl URL that may be given to the customer allowing them to claim/access their account details

Add a customer

  • POST /api/201308/customers

    POST fields listed above

    → POST /api/201308/customers
{ … }

    ← 201
Location: /api/201308/customers/customerId

Update customer information

  • PUT /api/201308/customers/customerId

    PUT changed fields from list above

    → PUT /api/201308/customers/customerId
{ … }

    ← 200
{ … }

Manufacturer

Fetch a manufacturer by id

  • GET /api/201308/manufacturers/manufacturerId 
    ← 200
{
  "id": "manufacturerId",
  "name": "manufacturerName",
}

Fetch a manufacturer by name

  • GET /api/201308/manufacturers/?name=manufacturerName 
    ← 200
{
  "id": "manufacturerId",
  "name": "manufacturerName",
}

List / Search for Manufacturers (paged array of results)

  • GET /api/201308/manufacturers/?startAt=startAt&limit=limit - all manufacturers
  • GET /api/201308/manufacturers/?name=name&startAt=startAt&limit=limit - search on name 
    ← 200
[
    {
        "id": "manufacturerId",
        "name": "manufacturerName"
    },
    { … }
]

Add a Manufacturer

  • POST /api/201308/manufacturers 
    → POST /api/201308/manufacturers
  "name": "manufacturer name"              // REQUIRED

    ← 201
Location: /api/201308/manufacturers/manufacturerId

Product

Fetch a product by id

  • GET /api/201308/products/productId 
    ← 200
{
    "id": "productId",
    "categoryId": "categoryId",
    "isCategoryKnown": false,
    "manufacturer": {
        "id": "manufacturerId",
        "name": "manufacturerName"
    },
    "mpn": "Manufacturer Part Number",
    "model": "Product Model Name",
    "msrp" : 0.00,
    "msrpCurrency": "[USD|CAD]",
    "upc": "123456789012",
    "ean": "1234567890123",
    "flags": [
        "product information flag",
        …
    ]
}

Notes:

  • isCategoryKnown: If false, the categoryId given should be taken as a suggestion of a default setting only. The correct categoryId for the product should be passed when items are created using the POST /items call.

Search for Products (paged array of results)

  • GET /api/201308/products?sku=sku - by your sku code for the product
  • GET /api/201308/products?q=query - by general search query or barcode

    The query parameter is a string used for a general search such as "Nexus S3" or a barcode such as "123456789012".

  • GET /api/201308/products?model=model&mpn=mpn&upc=UPC code&ean=EAN Barcode&categoryId=categoryId&manufacturerId=manufacturerId&manufacturerName=manufacturerName&startAt=startAt&limit=limit - by specifying specific search terms to search on

    All parameters here are optional, the only limitation is that you must specify at least one of the search parameters.

    Including Warranty Plan information in Product search results

    The three calls above also support the includePlans and includePlansAtPrice parameters. Set includePlans=1 to have warranty plans included in the results per product.

    By default, each product will include a set of all plans that are applicable to its category regardless of price. To narrow the results to only include the plans only applicable for the product's price, you can specify your selling price for the product you are searching for by setting includePlansAtPrice=333.33 where 333.33 is your selling price. If you do not know the selling price of the product, you may request that the warranty plan list be restricted based on each product's MSRP value where known by specifying includePlansAtPrice=MSRP instead.

    ← 200
[
    {
        "id": "productId",
        "categoryId": "categoryId",
        "isCategoryKnown": false,
        "manufacturer": {
            "id": "manufacturerId",
            "name": "manufacturerName"
        },
        "mpn": "Manufacturer Part Number",
        "model": "Product Model Name",
        "msrp" : 0.00,
        "msrpCurrency": "[CAD|USD]",
        "upc": "123456789012",
        "ean": "1234567890123",
        "warrantyPlans": [ { … }, … ]
    }, …
]

Add a Product

  • POST /api/201308/products 
    ← 200
{
    "categoryId":  "categoryId",         // REQUIRED
    "manufacturerId":  "manufacturerId", // REQUIRED
    "model": "Product Model Name",       // REQUIRED
    "mpn": "Manufacturer Part Number",   // OPTIONAL
    "msrp" : 0.00,                       // OPTIONAL
    "msrpCurrency": "[CAD|USD]",         // REQUIRED only when msrp is set
    "upc": "123456789012",               // OPTIONAL
    "ean": "1234567890123",              // OPTIONAL
    "sku": "Store's SKU for product"     // OPTIONAL
}

    → POST /api/201308/products
{ … }

    ← 201
Location: /api/201308/products/productId

Item

Get item by id

  • GET /api/201308/items/itemId
  • GET /api/201308/items?refId=refId
  • GET /api/201308/items?orderRefId=orderRefId 
    ← 200
{
  "id": "itemId",                                 // Return value only
  "refId": "Unique Line Item ID",                 // OPTIONAL
  "orderRefId": "Unique Order ID",               // OPTIONAL
  "customerId": "customerId",                     // REQUIRED
  "dateOfPurchase": "yyyy-MM-ddTHH:mm:ssZ",       // REQUIRED
  "productId": "Product ID for the item",         // REQUIRED *See below
  "productSku": "Store's SKU for product",        // REQUIRED *See below
  "purchasedCondition": "[NEW|USED|REFURBISHED]", // REQUIRED
  "contractYears": "Length of contract",          // OPTIONAL *See Below
  "pricePaid": 0.00,                              // REQUIRED
  "pricePaidCurrencyCode": "[USD|CAD]",           // REQUIRED
  "taxPaid": 0.00,                                // OPTIONAL
  "shippingPaid": 0.00,                           // OPTIONAL
  "serialNumber": "Item's serial number",         // OPTIONAL
  "serialNumberType": "[ESN|IMEI|MEID]",          // OPTIONAL
  "isRepaired": false,                            // REQUIRED
  "hasDamage": false,                             // REQUIRED
  "categoryId": "Category ID for the product"     // OPTIONAL *See below
}

    Notes:

    • refId: Your unique reference id for line item of sale of the product
    • orderRefId: Your unique store reference for order
    • pricePaid: Price of the item excluding taxes.
    • contractYears: If item was purchased on a contract, as is often the case with cell phones, enter the contract length in years from the given dateOfPurchase.
    • dateOfPurchase: This is used to determine the start of duration of coverage on any associated warranties
    • *productId / productSku: It is required that at least one of these fields is included to identify the product. If both are given, the system will save your productSku for the given productId for use in subsequent calls. productSkus should be your code that is unique to the product. If you do not have a productSku for the product, exclude this field.
    • serialNumberType: Include this field only when the serialNumber's type is known - for example when dealing with IMEI numbers from cell phones.
    • categoryId: Unlike other fields, this one applies to the Product. In some cases, when the product's isCategoryKnown field is false, the category given for a product may not be correct or known. In that case, the categoryId may be specified with the POST /items call made when creating an item to specify the correct product category. If a categoryId is not specified, then the default categoryId for the specified product (via productId/productSku) will be used.
    • isRepaired: Indicates that the item has been repaired or that it will be repaired before being returned to the customer. This may affect which warranty plans are applicable.
    • hasDamage: Indicates that the item has any damage that has not been repaired. This strongly affects which warranty plans are applicable; Most plans are not applicable to any item that has unrepaired damage.
      Note that if hasDamage is true and isRepaired is true, this would indicate that a repair was done, but following the repair, the item still has damage. This may be the case for example if the customer opted not to repair a cracked screen to save money, but did have a repair complted for another vital component.

Add an item

  • POST /api/201308/items

    POST fields listed above

    → POST /api/201308/items
{ … }

    ← 201
Location: /api/201308/items/itemId

Warranty

Get a warranty by id

  • GET /api/201308/warranties/warrantyId
  • GET /api/201308/warranties?refId=refId 
    ← 200
{
  "id": "warrantyId",                                     // Return value only
  "refId": "your unique reference id for warranty",       // OPTIONAL
  "registrationCode": "generated registration code",      // OPTIONAL
  "warrantyUrl": "http://www.example.com/plan/XYZ123",    // Return value only
  "orderRefId": "your unique store reference for order",  // OPTIONAL
  "warrantyPlanId": "warrantyPlanId",                     // REQUIRED
  "itemId": "itemId",                                     // REQUIRED
  "customerId": "customerId",                             // REQUIRED
  "dateOfPurchase": "yyyy-MM-ddTHH:mm:ssZ",               // REQUIRED
  "pricePaid": 0.00,                                      // REQUIRED
  "pricePaidCurrencyCode": "[USD|CAD]",                   // REQUIRED
  "taxPaid": 0.00,                                        // OPTIONAL
  "chargeCustomer: {                                               // OPTIONAL, send value only (never returned)
    "firstName": "First name of customer",                         // REQUIRED
    "lastName": "Last name of customer",                           // REQUIRED
    "email": "Email address of customer",                          // REQUIRED
    "creditCardNumber": "Credit card number",                      // REQUIRED
    "creditCardExpiry": "mm/yyyy",                                 // REQUIRED
    "cvv2": "123",                                                 // REQUIRED
    "streetAddress": "",                                           // REQUIRED
    "city": "",                                                    // REQUIRED
    "state": "{valid 2 letter postal abbreviation}",               // REQUIRED
    "postalCode": "",                                              // REQUIRED
    "country": "[US|CA|IN|BD|PH|AU]",                     // REQUIRED
  }
}

    Notes:

    • registrationCode: This is the registration code for the warranty, which may be generated on the client side under certain circumstances.
    • warrantyUrl: URL that may be given to the customer to allow them to directly look up information about this warranty.
    • dateOfPurchase: date of purchase for the warranty. Note that this may be different from the item's date of purchase. It is the item's date of purchase that is used to determine the start of a warranty's duration of coverage.
    • chargeCustomer: Used if the customer is to be charged directly for the warranty (such as for monthly plans)

Get a set of warranties by id

  • GET /api/201308/warranties?orderRefId=orderRefId
  • GET /api/201308/items/itemId/warranties 
    ← 200
[ { … } ]

Add a warranty

  • POST /api/201308/warranties
  • POST /api/201308/items/itemId/warranties

    POST fields listed above

    → POST /api/201308/warranties
{ … }

    ← 202
{ "id": "warrantyId" }

Invalidate a warranty

  • DELETE /api/201308/warranties/warrantyId (return/refund)

    Used when a warranty has been returned.

    → DELETE /api/201308/warranties/warrantyId

    ← 204

Receipt

Get receipt by id

  • GET /api/201308/receipts/receiptId
    • ← 200
{
  "id": "receiptId",                              // Return value only
  "orderRefId": "Unique Order ID",               // REQUIRED
  "customerRefId": "customerRefId",               // REQUIRED
  "dateOfPurchase": "yyyy-MM-ddTHH:mm:ssZ",       // REQUIRED
  "mimeType": "mime type of the receipt",         // REQUIRED *See below
  "content": "receipt content",                   // REQUIRED *See below
  "location": "URL for receipt"                   // Return value only
}

    Notes:

    • mimeType: The mime type of the content
    • content: A base64 encoded version of the content, this value is not returned when fetched (location is sent instead)

Add a receipt

  • POST /api/201308/receipts

    POST fields listed above

    → POST /api/201308/receipts
{ … }

    ← 201
Location: /api/201308/receipts/receiptId

Voucher Batch

Generate a voucher batch

  • POST /api/201308/voucher-batch 
    → POST /api/201308/voucher-batch
{
  "qty": "How many codes to generate" // REQUIRED
  "warrantyPlanId": "The warranty plan the vouchers may be redeemed for" // REQUIRED
  "note": "An optional note about this batch of codes" // OPTIONAL
}

    ← 201
{
    "id": "ID of the voucher batch",
    "voucherCodes": [
      "Voucher code",
      ...
    ],
    "warrantyPlanId": "The warranty plan the vouchers may be redeemed for",
    "note": "Note",
}

Update a voucher as sold

  • PUT /api/201308/voucher/voucherCode 
    → PUT /api/201308/voucher/voucherCode
{
  "orderRefId": "Your unique invoice or order number for the order involved" // OPTIONAL
  "refId": "Your unique id referring to the product sold" // OPTIONAL
  "dateOfPurchase": "The date that the customer purchased it from you" // REQUIRED
  "model": "The model name of the product (e.g. 'iPhone XS 128GB')" // OPTIONAL
  "mpn": "The manufacturer part number of the product (e.g. 'A1778')" // OPTIONAL
  "make": "The make or manufacturer name of the product" // OPTIONAL
  "deviceValue": "The value you assigned to the product" // OPTIONAL
}

    ← 204 (No content)