Skip to content

feat(cart): add terminal status to the cart resource #740

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
prateek-ct wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

feat(cart): add terminal status to the cart resource #740

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 70 additions & 0 deletions docs/specification/cart-mcp.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -196,6 +196,7 @@ Maps to the [Create Cart](cart.md#create-cart) operation.
]
}
],
"status": "active",
"currency": "USD",
"totals": [
{
Expand Down Expand Up @@ -317,6 +318,7 @@ Maps to the [Get Cart](cart.md#get-cart) operation.
]
}
],
"status": "active",
"currency": "USD",
"totals": [
{
Expand All @@ -341,8 +343,71 @@ Maps to the [Get Cart](cart.md#get-cart) operation.
}
```

=== "Ordered"

The buyer completed the purchase in the business UI after a `continue_url`
handoff. The platform reads `ordered` and stops surfacing the cart as
pending:

<!-- ucp:example schema=shopping/cart op=read direction=response extract=$.result.structuredContent -->
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"structuredContent": {
"ucp": {
"version": "{{ ucp_version }}",
"capabilities": {
"dev.ucp.shopping.checkout": [{"version": "{{ ucp_version }}"}],
"dev.ucp.shopping.cart": [{"version": "{{ ucp_version }}"}]
}
},
"id": "cart_abc123",
"line_items": [
{
"id": "li_1",
"item": {
"id": "item_123",
"title": "Red T-Shirt",
"price": 2500
},
"quantity": 2,
"totals": [
{"type": "subtotal", "amount": 5000},
{"type": "total", "amount": 5000}
]
}
],
"status": "ordered",
"currency": "USD",
"totals": [
{
"type": "subtotal",
"amount": 5000
},
{
"type": "total",
"amount": 5000
}
]
},
"content": [
{
"type": "text",
"text": "{\"ucp\":{…},…}"
}
]
}
}
```

=== "Not Found"

The business holds no record for this cart ID. `not_found` does not indicate
whether an order was placed; a retained cart reports a terminal `status`
instead:

<!-- ucp:example schema=common/types/error_response op=read direction=response extract=$.result.structuredContent -->
```json
{
Expand Down Expand Up @@ -481,6 +546,7 @@ Maps to the [Update Cart](cart.md#update-cart) operation.
]
}
],
"status": "active",
"currency": "USD",
"totals": [
{
Expand Down Expand Up @@ -574,6 +640,7 @@ Maps to the [Cancel Cart](cart.md#cancel-cart) operation.
]
}
],
"status": "canceled",
"currency": "USD",
"totals": [
{
Expand Down Expand Up @@ -646,6 +713,9 @@ JSON-RPC `result` with `structuredContent` containing the UCP envelope and
}
```

`update_cart` and `cancel_cart` on a cart whose `status` is terminal return
`cart_not_active` in the same form.

## Conformance

A conforming MCP transport implementation **MUST**:
Expand Down
61 changes: 61 additions & 0 deletions docs/specification/cart-rest.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -157,6 +157,7 @@ All REST endpoints **MUST** be served over HTTPS with minimum TLS version 1.3.
]
}
],
"status": "active",
"currency": "USD",
"totals": [
{
Expand Down Expand Up @@ -247,6 +248,7 @@ All REST endpoints **MUST** be served over HTTPS with minimum TLS version 1.3.
]
}
],
"status": "active",
"currency": "USD",
"totals": [
{
Expand All @@ -263,8 +265,62 @@ All REST endpoints **MUST** be served over HTTPS with minimum TLS version 1.3.
}
```

=== "Ordered"

The buyer completed the purchase in the business UI after a `continue_url`
handoff. The platform reads `ordered` and stops surfacing the cart as
pending:

<!-- ucp:example schema=shopping/cart op=read -->
```json
HTTP/1.1 200 OK
Content-Type: application/json

{
"ucp": {
"version": "{{ ucp_version }}",
"capabilities": {
"dev.ucp.shopping.checkout": [{"version": "{{ ucp_version }}"}],
"dev.ucp.shopping.cart": [{"version": "{{ ucp_version }}"}]
}
},
"id": "cart_abc123",
"line_items": [
{
"id": "li_1",
"item": {
"id": "item_123",
"title": "Red T-Shirt",
"price": 2500
},
"quantity": 2,
"totals": [
{"type": "subtotal", "amount": 5000},
{"type": "total", "amount": 5000}
]
}
],
"status": "ordered",
"currency": "USD",
"totals": [
{
"type": "subtotal",
"amount": 5000
},
{
"type": "total",
"amount": 5000
}
]
}
```

=== "Not Found"

The business holds no record for this cart ID. `not_found` does not indicate
whether an order was placed; a retained cart reports a terminal `status`
instead:

<!-- ucp:example schema=common/types/error_response op=read -->
```json
HTTP/1.1 200 OK
Expand Down Expand Up @@ -382,6 +438,7 @@ All REST endpoints **MUST** be served over HTTPS with minimum TLS version 1.3.
]
}
],
"status": "active",
"currency": "USD",
"totals": [
{
Expand Down Expand Up @@ -452,6 +509,7 @@ All REST endpoints **MUST** be served over HTTPS with minimum TLS version 1.3.
]
}
],
"status": "canceled",
"currency": "USD",
"totals": [
{
Expand Down Expand Up @@ -542,6 +600,9 @@ HTTP 200 and the UCP envelope containing `messages`:
}
```

Update Cart and Cancel Cart on a cart whose `status` is terminal return
`cart_not_active` in the same form.

## Security Considerations

### Authentication
Expand Down
Loading
Loading