Skip to content

Commit b6ffc2d

Browse files
committed
Add one-time use shipping destination hint
1 parent 1470418 commit b6ffc2d

2 files changed

Lines changed: 83 additions & 0 deletions

File tree

docs/specification/fulfillment.md

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -154,6 +154,28 @@ method.
154154
}
155155
```
156156

157+
## One-Time Use Destinations
158+
159+
Platforms **MAY** set `one_time_use: true` on any shipping destination when
160+
the address should not be retained beyond the immediate transaction — typical
161+
cases include gifts, gift-registry purchases, and care-of shipments where the
162+
destination belongs to someone other than the buyer.
163+
164+
Businesses **SHOULD** accept the field when present and avoid adding the
165+
address to the buyer's address book or using it to enrich profiles built from
166+
past purchases (recommendations, audiences, marketing). Businesses **MAY**
167+
still retain the address where needed for order records, fulfillment, fraud
168+
prevention, customer support, tax, and legal compliance. No business-profile
169+
support declaration is required — this is a best-effort hint.
170+
171+
The field applies to *this destination only*. Buyer-wide consent signals
172+
belong in [`dev.ucp.shopping.buyer_consent`](buyer-consent.md); `one_time_use`
173+
is independent of `buyer_consent.marketing` and applies even when the buyer
174+
has otherwise consented to marketing. The field is echoed back on the
175+
response, so platforms can verify the business preserved the hint.
176+
177+
See the [Gift Example](#gift-example) for usage.
178+
157179
## Rendering
158180

159181
Fulfillment options are designed for **method-agnostic rendering**. Platforms
@@ -407,6 +429,61 @@ so no extension needed.
407429
}
408430
```
409431

432+
### Gift Example
433+
434+
A buyer ships a gift to a recipient and marks the destination as one-time use,
435+
so the recipient's address is not added to the buyer's saved addresses or
436+
marketing audience. See [One-Time Use Destinations](#one-time-use-destinations)
437+
for the full behavior contract.
438+
439+
```json
440+
{
441+
"fulfillment": {
442+
"methods": [
443+
{
444+
"id": "method_1",
445+
"type": "shipping",
446+
"line_item_ids": ["gift_box"],
447+
"selected_destination_id": "dest_recipient",
448+
"destinations": [
449+
{
450+
"id": "dest_recipient",
451+
"first_name": "Pat",
452+
"last_name": "Recipient",
453+
"street_address": "123 Recipient St",
454+
"address_locality": "Springfield",
455+
"address_region": "IL",
456+
"postal_code": "62701",
457+
"address_country": "US",
458+
"one_time_use": true
459+
}
460+
],
461+
"groups": [
462+
{
463+
"id": "package_1",
464+
"line_item_ids": ["gift_box"],
465+
"selected_option_id": "standard",
466+
"options": [
467+
{
468+
"id": "standard",
469+
"title": "Standard Shipping",
470+
"description": "Arrives Dec 12-15 via USPS",
471+
"totals": [
472+
{
473+
"type": "total",
474+
"amount": 500
475+
}
476+
]
477+
}
478+
]
479+
}
480+
]
481+
}
482+
]
483+
}
484+
}
485+
```
486+
410487
### Split Groups
411488

412489
**Config:** Platform profile requires `config.supports_multi_group: true`

source/schemas/shopping/types/shipping_destination.json

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,12 @@
1616
"type": "string",
1717
"description": "ID specific to this shipping destination.",
1818
"ucp_request": "optional"
19+
},
20+
"one_time_use": {
21+
"type": "boolean",
22+
"default": false,
23+
"ucp_request": "optional",
24+
"description": "Best-effort hint that this destination should not be retained beyond the immediate transaction (e.g., not added to the buyer's address book or marketing profile)."
1925
}
2026
},
2127
"required": [

0 commit comments

Comments
 (0)