Cart checkout (points)

Description

This service initiates the checkout process for all items in the cart for a given mileage activity, generating one or more orders. It allows for specifying delivery details and adding up to 20 custom description fields to each item in the order.

---

Request

Restrictions

• This service requires an authenticated user (consumer or operator).

• Delivery information (addressCode or exchangeCenterId) is only required if the cart contains physical items.

Endpoint

PUT https://<server-url>/api/v4/mileage/{activity_code}/cart/delivery

Path Parameters

Parameter	Type	Description
activity_code	String	The unique code for the mileage activity.

Parameters

Parameter	Location	Description
touchpoint	Query / Header	The identifier for the touchpoint. Use Thalamus-Touchpoint for the header.
token	Query / Header	The authentication token for the API session. Use Thalamus-Token for the header.

Full URL Example

https://<server-url>/api/v4/mileage/MPOINTS/cart/delivery?touchpoint=test&token=...

Request Body

The request body contains order details, delivery information, and the list of items being checked out.

Top-Level Fields

Field	Type	Description
status	String	The desired status of the order, typically "CHECKOUT".
addressCode	String	Delivery Option 1. The code for the consumer's delivery address.
exchangeCenterId	Integer	Delivery Option 2. The ID of the exchange center for pickup.
physicalLocationId	Integer	Delivery Option 3. The ID of a physical location for delivery.
principal	String	Delivery Option 4. The principal of a physical location, formatted as profileField|principalValue (e.g., fiscalId|72857877536).
message	String	Optional. A message to include with the order (e.g., "Fragile").
description2-10	String	Optional. Custom description fields for the overall order.
manualApprovalPending	Boolean	Optional. Set to true if the order requires manual approval.
items	Array	An array of item objects being checked out. See structure below.

items Array Object Fields

Field	Type	Description
itemCode	String	The unique code of the item in the cart.
description1-20	String	Optional. Up to 20 custom description fields for this specific item in the order.

Example 1: Delivery to a Saved Address JSON

{
  "addressCode": "address",
  "status": "CHECKOUT",
  "message": "Fragile",
  "manualApprovalPending": false,
  "items": [
    {
      "itemCode": "t1",
      "description": "Custom item description"
    }
  ]
}

Example 2: Delivery to an Exchange Center JSON

{
  "exchangeCenterId": 1,
  "status": "CHECKOUT",
  "message": "Fragile",
  "manualApprovalPending": false,
  "items": [
    {
      "itemCode": "t1",
      "description": "Custom item description"
    }
  ]
}

Example 3: Delivery to a Physical Location by ID JSON

{
  "physicalLocationId": 5,
  "status": "CHECKOUT",
  "message": "Fragile",
  "manualApprovalPending": false,
  "items": [
    {
      "itemCode": "t1",
      "description": "Custom item description"
    }
  ]
}

Example 4: Delivery to a Physical Location by Principal JSON

{
  "principal": "fiscalId|72857877536",
  "status": "CHECKOUT",
  "message": "Fragile",
  "manualApprovalPending": false,
  "items": [
    {
      "itemCode": "t1",
      "description": "Custom item description"
    }
  ]
}

---

Response

✅ Successful Response: 200 OK

The checkout was successful. The response contains an array of the newly created orders.

Field	Type	Description
orderNumber	Integer	The unique number for the generated order.
creationDate	Timestamp	The date the order was created.
orderState	String	The current state of the order (e.g., "Received").
total	Number	The total point cost of the order.
items	Array	An array of item objects included in this order.

JSON

{
  "orders": [
    {
      "orderNumber": 52,
      "creationDate": 1636575088521,
      "orderState": "Received",
      "message": "Fragile",
      "total": 0.0,
      "physicalLocationOriginId": 5,
      "items": [
        {
          "item": {
            "code": "t1",
            "name": "tomate",
            "itemType": "VIRTUAL_ITEM",
            "price": 0.0
          },
          "quantity": 1,
          "total": 0.0,
          "description": "tomate"
        }
      ]
    }
  ]
}

❌ Unsuccessful Response: 400 Bad Request

Returned for logical errors such as an empty cart, items out of stock, incomplete profile data, or conflicting delivery information.

JSON

{
  "errors": {
    "cart": "IsEmpty",
    "item": "NotInStock",
    "profile": "IncompleteAddress",
    "checkout": "NotUniqueDeliveryMethod"
  }
}

❌ Unsuccessful Response: 404 Not Found

Returned if a specified resource like the activity, address, or exchange center does not exist.

JSON

{
  "errors": {
    "error.message": "NOT_FOUND",
    "address": "InvalidCode",
    "exchangeCenter": "InvalidID"
  }
}