E-commerce shopping cart

The ecommerce shopping cart lets a New Purchase Website (or any other API client) build the shopping cart with "ecommerce Products" on its own domain (example) and then hand the customer to the existing MyBeezBox ecommerce order funnel for checkout, delivery information, payment, order creation, and post-payment processing.

Use this flow when the product listing and cart UI live outside the legacy MyBeezBox purchase website, but the final ecommerce order must still be created by MyBeezBox.

High-level flow

Responsibilities

The New Purchase Website Shop is responsible for:

• displaying ecommerce products, variants, attributes, prices, and cart controls;
• creating or replacing the temporary cart through the API, preferably from its backend so the partner token is not exposed in the browser;
• redirecting the customer to the returned funnel_url;
• providing a return_url when the customer should come back to the new website after checkout.

MyBeezBox is responsible for:

• storing the cart;
• keeping the cart id attached to the old ecommerce funnel session;
• loading the stored items into the old ecommerce wizard UI;
• collecting delivery and buyer information;
• handling coupons, gift cards, payment, 3DS redirects, and order creation;
• creating the final EcommerceOrder, related Order, order lines, and payment records;
• deleting the cart after the thank-you step is reached (i.e. after the order is successfully finished);
• redirecting to the cart return_url when one exists.

Authentication

The cart API uses standard API v2 Authentication:

Create a cart

Create the cart after the customer has selected products on the new purchase website.

POST /api/v2/ecommerce/cart/
Content-Type: application/json
Authorization: Token <token>

Example request:

{
  "return_url": "https://shop.example.com/cart/checkout-complete",
  "items": [
    {
      "product_id": 12,
      "quantity": 2,
      "variant_id": 56,
      "attribute_values": {
        "61": "blue",
        "63": "XL"
      }
    },
    {
      "product_id": 34,
      "quantity": 1
    }
  ]
}

Example response:

{
  "id": "20d6a0e1-8ce0-4245-b13e-334ac427c699",
  "items": [
    {
      "product_id": 12,
      "quantity": 2,
      "variant_id": 56,
      "attribute_values": {
        "61": "blue",
        "63": "XL"
      }
    },
    {
      "product_id": 34,
      "quantity": 1,
      "variant_id": null,
      "attribute_values": {}
    }
  ],
  "return_url": "https://shop.example.com/cart/checkout-complete",
  "funnel_url": "https://partner.example.com/ecommerce/order/customization/?cart=20d6a0e1-8ce0-4245-b13e-334ac427c699",
  "last_modified": 1609459200000
}

After receiving the response, redirect the customer to funnel_url.

Payload fields

items is required and may be empty. An empty cart is accepted by the API, but the legacy funnel requires at least one product or variant quantity above zero before checkout can continue.

Each item supports:

• product_id: MyBeezBox ecommerce product ID.
• quantity: selected quantity.
• variant_id: optional MyBeezBox variant id. Use null or omit it for a product without a variant.
• attribute_values: optional object mapping Attribute IDs (integer) to one of available Attribute values (string).

return_url is optional. When present, the old funnel redirects the customer to this URL after the order summary step is reached. When it is blank or omitted, the customer stays on the standard MyBeezBox thank-you page.

id is optional. Use it only when replacing an existing cart. The id must belong to an existing cart for the authenticated partner, otherwise the API returns a validation error.

Replace a cart

If the customer changes the cart before being redirected to MyBeezBox, call the same create endpoint with the existing id.

{
  "id": "20d6a0e1-8ce0-4245-b13e-334ac427c699",
  "return_url": "https://shop.example.com/cart/checkout-complete",
  "items": [
    {
      "product_id": 12,
      "quantity": 3,
      "variant_id": 56,
      "attribute_values": {
        "61": "blue",
        "63": "XL"
      }
    }
  ]
}

The existing cart data is overwritten under the same cart id and receives a new last_modified timestamp.

Retrieve a cart

Use this endpoint to inspect a cart that was previously created for the same partner.

GET /api/v2/ecommerce/cart/{id}/
Authorization: Token <token>

If the cart exists, the response has the same shape as the create response. If it does not exist for the authenticated partner, the API returns 404 with:

{
  "detail": "Cart not found"
}

How the cart behaves

The cart is temporary. It is stored in memory, not in a database. The cart expires after 2 hours of the last modification.

Each cart is linked to a partner that created it and only that partner can retrieve the cart.

last_modified is returned as a Unix timestamp in milliseconds. It is updated every time the cart is created or replaced (updated).

The API stores the submitted item data, but the old funnel still applies its own business rules when the customer checks out. Delivery options come from EcommerceSettings, stock is validated by the customization form, pricing is calculated by the ecommerce price calculator, and payment is handled by the existing ecommerce payment flow.

Integration with the old order funnel

The funnel_url returned by the API points to the existing ecommerce wizard customization step with a cart query parameter. The funnel_url is using the domain of the partner that created a cart:

https://<partner's site domain>/ecommerce/shop/customization/?cart=<cart-id>

When the customer opens that URL, the old funnel looks up the cart. If the cart exists:

1. the funnel stores the cart id in the current session so that it can be passed between funnel steps.
2. The customization step initializes the ShoppingCart JS object in the background to control the cart from the funnel (read or update).
3. The customization form is filled with products and quantities stored in the cart.

From that point:

• the cart id is preserved in the wizard step URLs;
• the submitted items are editable in the old customization step;
• delivery mode is selected in the old customization step;
• buyer and delivery information are collected in the old information step;
• payment is processed in the old payment step;
• EcommerceOrderProduct and EcommerceOrderVariant rows are created from the customization data;
• the final Order and payment records are created by the existing order funnel.

The cart API does not create a completed order. The cart is a handoff object that lets the new purchase website start the existing checkout with the selected ecommerce items.

After payment

When the ecommerce summary step is reached, MyBeezBox deletes the cart cata from memory. If the cart has a return_url, MyBeezBox redirects the customer to that URL. If return_url isn't set, the customer sees a standard "Thank-you" page of the order funnel.

Use the return_url to display the final state on the New Purchase Website, for example a confirmation page or a page that polls your own backend for order status. The cart is deleted after checkout, don't rely on it in your "return" page.

Common errors

401 Unauthorized: the request did not include a valid token.

404 Cart not found: the requested cart id does not exist for the authenticated partner, it has expired, or it has already been deleted.

Validation errors can happen when:

• id is provided but does not match an existing cart for the partner;
• attribute_values is not an object;
• an attribute id key is not an integer;
• an attribute value is not a string.