Post Purchase Checkout

Attaches one or more warranties to an existing order after the original sale, converting it into a full warranty order. You collect payment for the warranty yourself, then call this endpoint to record the sale and initiate coverage.

Before you call it, the order must have been submitted to POST /api/carts without a warranty. That submission creates the order and automatically generates warranty offers for its line items. Those offers must still be unsold; nothing here creates an offer, it buys one the order already carries.

Post Purchase Checkout Endpoint

HTTP method: POST

Authentication: Private Bearer Token

Staging Endpoint: https://partner-staging.getmulberry.com/api/post-purchase-checkout

Production Endpoint: https://partner.getmulberry.com/api/post-purchase-checkout

📘

No offer ID required

You don't need to capture or store the internal warranty_offer_id. Pass the same product_id (or variant_id) you used in POST /api/carts and Mulberry resolves the offer for you. Passing warranty_offer_id directly is still supported.

curl --request POST \
     --url https://partner-staging.getmulberry.com/api/post-purchase-checkout \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer [insert private token]' \
     --header 'Content-Type: application/json' \
     --data '
{
  "id": "ORDER-12345",
  "line_items": [
    {
      "product_id": "SOFA-001"
    }
  ]
}'

Line item fields:

Every line item must identify the offer it is buying, with at least one of warranty_offer_id, product_id/variant_id, or a non-empty products array. Sending an offer ID and a product ID together is fine.

* At least one of these four is required, so the offer can be identified. A line item carrying none of them is refused.

A line_item_id is the reliable way to identify which item a purchase is for. An offer ID cannot do it: the same warranty offer is carried by every line item in its category and price band, so an offer ID says which term was bought, not which item.

Warranty fields:

The warranty object names the term you sold rather than the offer it came from, and states what the customer paid. The price you send is recorded as the amount paid, so a warranty sold off the list price is reported at what the customer was actually charged.

A warranty object names a term, not an item, so it must travel with a line_item_id, a product_id/variant_id, or a products array. If more than one warranty is offered at the same term for the item, pass a warranty_offer_id to choose between them.

Quantity

One warranty is attached per unit bought, and quantity defaults to 1. It must be a whole number, and no more than 20 for a single line item. How you write it doesn't matter — 2, 2.0 and "2" all buy two — but a fractional, zero or negative quantity is refused rather than rounded: a warranty bought zero times would retire the offer without covering anything.

Bundles

A line item can cover a bundle — one offer over several products, priced on the bundle total. Buying it attaches one warranty with one covered product per bundle member, so every member is claimable against the single premium.

To buy a bundled offer, send any one of its products — a product_id or variant_id — or list the members in a products array. Each identifies the same offer, so you do not need to know which product the bundle is stored under. What a bundle covers was fixed when the offer was generated, so the products you send locate the offer rather than redefining its coverage, and any prices sent alongside them are informational.

🚧

One line item per offer

Send one line item for each offer you are buying, not one per bundled product. Listing a bundle's products as separate line items asks for the same offer several times and attaches duplicate coverage.

Request Examples

Attach by product ID (recommended)

{
  "id": "ORDER-12345",
  "line_items": [
    { "product_id": "SOFA-001" }
  ]
}

Attach by warranty offer ID

{
  "id": "ORDER-12345",
  "line_items": [
    { "warranty_offer_id": "d177c5c3-e549-416f-b048-db0e7ac46758" }
  ]
}

Multiple line items

{
  "id": "ORDER-12345",
  "line_items": [
    { "product_id": "SOFA-001" },
    { "product_id": "CHAIR-002" }
  ]
}

A chosen term, at the price you charged

{
  "id": "ORDER-12345",
  "line_items": [
    {
      "line_item_id": 91827,
      "quantity": 1,
      "warranty": {
        "warranty_duration": 24,
        "warranty_price": "129.99"
      }
    }
  ]
}

Responses

A request is all or nothing. If any line item can't be bought, the whole request is refused and no coverage is attached.

Success

A warranty order was created. The response carries its Mulberry order ID.

{
  "id": "c1662e9684b7429ab82b89d97890b064"
}

A 400 is returned when the following apply. The bodies are quoted verbatim, and the API says plan where this page says warranty:

• A product is named but no unsold offer on the order covers it, or the offer covering it was already bought by an earlier line item in the same request.
  JSON

  { "error": "No warranty offer found for product SOFA-001 on order ORDER-12345. It may already have been claimed by another line item in this request - one bundled offer covers several products but is bought once." }

• A line item identifies no offer at all.
  JSON

  { "error": "Each line item must include either a warranty_offer_id, a product_id/variant_id, or a products array to identify the warranty offer." }

• A warranty object names a term without naming the item it is for.
  JSON

  { "error": "A line item selecting a plan by warranty_duration must also name the item it is for, with a line_item_id, a product_id/variant_id, or a products array." }

• The term asked for is not offered on the item, or is offered by more than one warranty and no warranty_offer_id chooses between them.
  JSON

  { "error": "No 24-month plan is offered for this item. Available plans: 12 months (regular), 36 months (regular)." }

• A quantity is not a positive whole number, or is above 20 for one line item.
• The same line_item_id is named twice.
• line_items is empty, or the payload fails validation.

Relationship to /api/carts

🚧

Order must exist first

Calling POST /api/post-purchase-checkout with an id that was never sent to POST /api/carts returns a 404.