MulberryCare Checkout

MulberryCare

Checking out for MulberryCare plans can be done using the /api/mulberry-care API endpoint. This API supports passing in a list of line items a customer purchased. For any of these items that are warrantable and eligible for MulberryCare offers, a MulberryCare plan will be created.

Line items

Line items can be passed in with unique line item ids. These will be included in the corresponding warranties in the response to make it easier to match them up. Note that line items with multiple quantity that are eligible for MulberryCare offers will result in multiple unique warranties.

Customer Info

If a customer already has an associated Mulberry customer_id then it can be used in place of customer fields such as email and billing address. If no customer_id is provided then email and the customer's address are required. The newly created customer_id will be provided in the response.

Integrations that require customer activation

When customer activation is required the API response will not include any issued warranty information because the plan has not yet been actually issued. It is only at the time the customer activates that the warranty policy is created.

The mulberry order ID as well as the original client order id will be available on the webhook events to match up any activated plans with the original order.

Integrations using Transactions instead of Product Line items

For integration in which the full product line item breakdown is not available and only the full customer transaction is available the API functions with the same interface.

Including full product details is usually encouraged since it allows us to better classify and understand the best fit for product coverage. When dealing with a customer transaction instead of individual products, a more generic protection coverage is applied by default.

The way transactions can be passed is up to the client. Here is an example of how generic customer transactions can be included as line items:

...
    "line_items": [
        {
            "id": 1,
            "product_title": "walmart.com purchase",
            "product_id": "my-purchase-id-123",
            "product_price": "1200.00",
            "currency": "USD",
            "quantity": 1,
        }
    ],
    ...

API Request Inputs

📘

API Auth

This API uses the standard Mulberry auth using the private bearer token in the header like Authorization: Bearer {token}. Bearer tokens can be found in the partner dashboard or by contacting Mulberry support.

POST /api/mulberry-care request body parameters:

parameter

description

required

type

details

id

unique external order ID

yes

string

customer_id

Mulberry customer id

no

string

Can be used in place of passing customer information fields such as email and billing_address

email

customer e-mail address

no

string

Optional if using customer_id

billing_address

customer billing address

no

object

Optional if using customer_id

shipping_address

customer shipping address

yes

object

line_items

list of items to get coverage on

yes

list

line_items parameters:

parameter

description

required

type

details

id

Optional unique line item id within the order

no

int

Created warranties in the API response will include the original line item id if provided to help match them

product_title

Product title

yes

string

product_id

Product id

yes

string

variant_title

Product variant title

no

string

variant_id

Product variant id

no

string

product_price

Expected as a string value

yes

string

If currency is USD, value should be in string format like "249.99"

currency

Currency code

yes

string

Currently only support USD and CAD

sku

Optional product SKU

no

string

quantity

Product quantity

no

int

Warranties are assigned per product so multiple quantity products can map to multiple warranties (defaults to 1)

detail

Optional detailed metadata that can include images or categorization data

no

object

example:

"detail": {
  "images": [  {  "src": "https://cdn.shopify.com/s/files/1/0014/1865/7881/products/Harper2pc_9458461a-74a5-4756-ad6f-9e4d718b251e.jpg?v=1628268755"}  ]  }

customer address object parameters

parameter

description

required

type

details

first_name

Customer first name

yes

string

last_name

Customer last name

yes

string

address1

Address line 1

yes

string

address2

Address line 2

no

string

Additional address lines past 2 should be added to address2 value

city

City

yes

string

state

State passed as abbreviated state values (ex: "NY, "CA")

yes

string

zip

Zip code

yes

string

country_code

Two letter country code (for example: "US")

yes

string

phone

Customer phone number

no

string

Sample payload

Here is a sample request payload:

{
    "id": "order-12345",
    "email": "[email protected]",
    "line_items":
    [
        {
            "id": 1,
            "product_title": "The Couch",
            "variant_title": "Green",
            "product_id": "product-1234567",
            "variant_id": "variant-7654321",
            "product_price": "3850.00",
            "currency": "USD",
            "sku": "COUCH-123",
            "quantity": 1,
            "detail":
            {
                "images":
                [
                    {
                        "src": "https://cdn.shopify.com/s/files/1/0014/1865/7881/products/Harper2pc_9458461a-74a5-4756-ad6f-9e4d718b251e.jpg?v=1628268755"
                    },
                    {
                        "src": "https://cdn.shopify.com/s/files/1/0014/1865/7881/products/Harper-2pc-Sectional-Sleeper-On-Camera-Pecan_copy_2_fa151f19-9c72-464a-a2e8-829188e3277a.jpg?v=1569327333"
                    }
                ]
            }
        }
    ],
    "billing_address":
    {
        "first_name": "Michael",
        "last_name": "Jordan",
        "address1": "100 Main St",
        "address2": "",
        "phone": "1234567890",
        "city": "New York",
        "state": "NY",
        "zip": "10001",
        "country_code": "US"
    },
    "shipping_address":
    {
        "first_name": "Michael",
        "last_name": "Jordan",
        "address1": "100 Main St",
        "address2": "",
        "phone": "1234567890",
        "city": "New York",
        "state": "NY",
        "zip": "10001",
        "country_code": "US"
    }
}
{
    "id": "order-12345",
    "customer_id": "1aba293a0fa347edaabb5ffca3ce25bd",
    "line_items":
    [
        {
            "id": 1,
            "product_title": "The Chair",
            "variant_title": "Green",
            "product_id": "product-1234567",
            "variant_id": "variant-7654321",
            "product_price": "3850.00",
            "currency": "USD",
            "sku": "CHAIR-123",
            "quantity": 1,
            "detail":
            {
                "images":
                [
                    {
                        "src": "https://cdn.shopify.com/s/files/1/0014/1865/7881/products/Harper2pc_9458461a-74a5-4756-ad6f-9e4d718b251e.jpg?v=1628268755"
                    },
                    {
                        "src": "https://cdn.shopify.com/s/files/1/0014/1865/7881/products/Harper-2pc-Sectional-Sleeper-On-Camera-Pecan_copy_2_fa151f19-9c72-464a-a2e8-829188e3277a.jpg?v=1569327333"
                    }
                ]
            }
        }
    ]
}

Sample response

And here is a sample response:

{
	"id": "6e0650f72d52459baf2f79c2d135b701",
	"external_id": "order-12345",
	"customer": {
		"id": "1aba293a0fa347edaabb5ffca3ce25bd"
	},
	"warranties": [{
		"id": "4c415ad0373048f28fe99ba7af880964",
		"line_item_id": 1,
		"product_id": "product-1234567",
		"duration_months": 12,
		"warranty_start_date": "2021-10-07 17:49:24.079121+00:00",
		"warranty_end_date": "2022-10-07 17:49:24.079121+00:00",
		"policy_terms_url": "https://terms.getmulberry.com/20210210_shield_multiproduct",
		"coverage_details": {
			"long": [
				"Accidental rips & tears",
				"Seam separation",
				"Broken zippers",
				"Minor burn or heat marks, up to one inch in length",
				"All stain types",
				"Extended coverage for product defects, past the limited warranty",
				"Free repairs and fast replacements, with no additional fees"
			],
			"short": [
				"Rips & tears",
				"Seam separation",
				"Broken zippers",
				"Minor burn or heat marks",
				"Accidental stains",
				"Product defects, once the limited warranty expires",
				"Free repairs and fast replacements"
			]
		},
		"purchase_window_days": 60,
		"available_upgrade_plans": [{
				"price": "34.99",
				"currency": "USD",
				"duration_months": 36
			},
			{
				"price": "54.99",
				"currency": "USD",
				"duration_months": 60
			}
		]
	}]
}
{
	"id": "6e0650f72d52459baf2f79c2d135b701",
	"external_id": "order-12345",
	"customer": {
		"id": "1aba293a0fa347edaabb5ffca3ce25bd"
	},
	"warranties": []
}