LPU looks after memberships and payments. One fulfillment hub looks after shipping, returns, and delivery questions in every region. A direct connection between LPU and the hub replaces the monthly CSV export.
LPU sends each bundle to one fulfillment hub. The hub picks the warehouse, ships the bundle, and helps members with any delivery question. The Mainfactor US store is one of the four warehouses.
For the teams that build the connection between LPU and the fulfillment hub. The connection has two calls: LPU sends each bundle to the hub, and the hub posts each status back to LPU. The API calls each bundle an entitlement: one member's right to one bundle for one bundle year.
This spec is a proposal. Every part of it is open to change: the flow, the fields, the answers, and the security. Tell us what fits your systems and what does not. We will settle the details with your team before anyone builds the connection.
address_locked, and LPU locks the address form.shipped with tracking, and the member sees it on LPU.delivered or returned.LPU sends the full record when an entitlement is ready to ship, and again after each change. The hub keeps the record with the highest version.
| Field | Content |
|---|---|
id | The entitlement ID, for example u_8f2c:bundle-2026-2027. Treat it as an opaque string. |
version | A whole number that goes up with each change |
status | active, cancelled (a refund, a chargeback, or a downgrade), or deleted. A deleted record holds no personal data. The hub then erases the personal data that it holds for the entitlement, except data that the law requires it to keep. |
items | Item codes and quantities |
shipping | Name, email, phone, address, and the tax ID where customs needs it (Brazil, Chile, Mexico) |
{
"id": "u_8f2c:bundle-2026-2027",
"version": 3,
"status": "active",
"items": [{ "code": "bundle-2026-2027", "quantity": 1 }],
"shipping": {
"name": "Alex Example",
"email": "alex@example.com",
"phone": "+1 555 0100",
"address": {
"line1": "100 Example Street",
"line2": "",
"city": "Los Angeles",
"state": "CA",
"postal_code": "90001",
"country": "US"
},
"tax_id": null
}
}
Example record with made-up data.
| Answer | Meaning | What LPU does |
|---|---|---|
200 accepted | The hub takes the entitlement and owns it from this point. The hub also answers 200 to a repeat or to an older version. | Saves the hub reference |
422 rejected | The data needs a fix, or the hub does not ship to that country | Shows the message to the member and asks for a fix. For unknown_item, LPU alerts HiFi. |
409 locked | It is too late to change or cancel the bundle | Keeps the change for later bundles and tells the member |
No answer, or a 5xx error | The hub is down | Sends it again for up to 72 hours, then alerts HiFi |
A 200 answer holds the hub reference for the entitlement. A 422 answer holds a reason and a message that LPU can show to the member. The reasons are invalid_address, country_not_served, and unknown_item.
200 { "reference": "HUB-10442" }
422 { "reason": "invalid_address", "message": "The postal code does not match the city." }
Example answers with made-up data.
The hub posts each later step. Each status holds occurred_at, the time of the step in ISO 8601 UTC. LPU answers 200, or 404 for an ID that LPU did not send. This endpoint returns no member data.
| Status | When | Extra fields |
|---|---|---|
address_locked | The address can no longer change | None |
shipped | A package left the warehouse. The hub posts one shipped status for each package. | Carrier, tracking number, tracking URL, items, shipping cost |
delivered, returned | The carrier reports the result (optional) | Tracking number |
problem | A problem after acceptance, for example the carrier refuses the address | Reason, message for the member |
{
"status": "shipped",
"occurred_at": "2026-12-02T15:04:05Z",
"carrier": "UPS",
"tracking_number": "1Z999AA10123456784",
"tracking_url": "https://example.com/track/1Z999AA10123456784",
"items": [{ "code": "bundle-2026-2027", "quantity": 1 }],
"shipping_cost": { "amount": 1450, "currency": "USD" }
}
Example status with made-up data. Amounts are in the smallest unit of the currency, for example cents.
X-LPU-Signature header holds an HMAC-SHA256, in hex, of the X-LPU-Timestamp value, a period, and the raw body. Only LPU and the hub hold the secret.