The Address entity is a reusable data object referenced across multiple workflows. It is not isolated to checkout - addresses appear in user profiles, item listings, pickup configurations, and shipping fulfilment. Understanding address scope and ownership prevents unexpected access errors.
| Context | Ownership & Purpose |
| User Address Book | Owned by Buyer. Personal delivery locations. Requires delivery = true to appear in checkout and user settings. |
| Item Location | Owned by Merchant. Geographic association for the listing. Required for map-based discovery in Spacetime marketplaces. |
| Pickup Location | Owned by Merchant. Predefined collection points linked to items. Exposed to buyers during checkout. |
| Order Reference | System-attached. Billing and shipping address references attached to Invoice and Order at checkout. |
The Address entity in Arcadier is a reusable data object that supports multiple system functions across Users, Items, Checkout, and Shipping workflows. Because addresses are referenced in different contexts, it is important to understand:
- How addresses are created and stored
- How different address types are distinguished
- How pickup locations are implemented
- How authorization controls address access
Address as a Shared Entity
In Arcadier, addresses are not isolated to a single feature. Instead, they are used across:
- User profile management
- Checkout address book
- Pickup locations
- Item location mapping (e.g. Spacetime template)
An address record can be reused across different workflows depending on how its properties are configured.
Where Addresses can be attached
| Use-Case | Description |
| User Address Book (Checkout & User Profile) | The address book shown in:
Both reference the same address entity. From an API perspective, these are standard user-owned address records. To make an address available in these contexts, the address must have the delivery property set to true. This enables:
|
| Pickup Locations | A pickup location represents a prearranged collection point where the buyer collects an item from the merchant. Pickup addresses are:
Implementation Flow (Pickup Locations)
Special Authorization Case The endpoint: Get Pickup Method by Item ID Allows: Consumers, Guests to retrieve pickup locations for a specific item. This enables checkout location selection without requiring elevated permissions. |
| Item Location (Spacetime) |
Important behavior: Even if multiple items use the same physical address, each item will generate a distinct Address ID upon creation.This ensures item-level independence and location tracking consistency. |
Address Authorization Model
Address access is role-controlled according to the user role. This authorization model ensures user-level privacy, merchant operational flexibility and admin governance control.
- Consumer: Can read and write only their own addresses, with exception: Can read pickup locations for an item using the pickup endpoint.
- Merchant: Can read and write own addresses, and consumer addresses (when necessary for order fulfilment).
- Admin: Can read and write all user addresses within the marketplace.
Where Addresses Sit in the Core Data Model
Entity relationships:
- A User can own multiple Addresses.
- An Item can reference a Pickup Address.
- An Order references billing/shipping addresses selected at checkout.
- Spacetime items require a location-linked Address.