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:json "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": []
}