ucp/source/schemas/shopping/cart.json at aba594371a648e572e0908bcc53ea0bfd8cfac04 · Universal-Commerce-Protocol/ucp · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://ucp.dev/schemas/shopping/cart.json",
  "name": "dev.ucp.shopping.cart",
  "title": "Cart",
  "description": "Shopping cart with estimated pricing before checkout. Lightweight pre-purchase exploration with no payment info or complex status states.",
  "$defs": {
    "checkout": {
      "title": "Checkout with Cart",
      "description": "Checkout extended with cart capability. Adds cart_id to create_checkout for cart-to-checkout conversion.",
      "allOf": [
        {
          "$ref": "checkout.json"
        },
        {
          "type": "object",
          "properties": {
            "cart_id": {
              "type": "string",
              "description": "Cart ID to convert to checkout. Business MUST use cart contents (line_items, context, buyer) and MUST ignore overlapping fields in checkout payload.",
              "ucp_request": {
                "create": "optional",
                "update": "omit"
              }
            }
          }
        }
      ]
    }
  },
  "type": "object",
  "required": [
    "ucp",
    "id",
    "line_items",
    "currency",
    "totals"
  ],
  "additionalProperties": true,
  "properties": {
    "ucp": {
      "$ref": "../ucp.json#/$defs/response_cart_schema",
      "ucp_request": "omit"
    },
    "id": {
      "type": "string",
      "description": "Unique cart identifier.",
      "ucp_request": {
        "create": "omit",
        "update": "required"
      }
    },
    "line_items": {
      "type": "array",
      "items": {
        "$ref": "types/line_item.json"
      },
      "description": "Cart line items. Same structure as checkout. Full replacement on update.",
      "ucp_request": {
        "create": "required",
        "update": "required"
      }
    },
    "context": {
      "$ref": "types/context.json",
      "description": "Buyer signals for localization (country, region, postal_code). Merchant uses for pricing, availability, currency. Falls back to geo-IP if omitted.",
      "ucp_request": {
        "create": "optional",
        "update": "optional"
      }
    },
    "buyer": {
      "$ref": "types/buyer.json",
      "description": "Optional buyer information for personalized estimates.",
      "ucp_request": {
        "create": "optional",
        "update": "optional"
      }
    },
    "currency": {
      "type": "string",
      "description": "ISO 4217 currency code. Determined by merchant based on context or geo-IP.",
      "ucp_request": "omit"
    },
    "totals": {
      "$ref": "types/totals.json",
      "description": "Estimated cost breakdown. May be partial if shipping/tax not yet calculable.",
      "ucp_request": "omit"
    },
    "messages": {
      "type": "array",
      "items": {
        "$ref": "types/message.json"
      },
      "description": "Validation messages, warnings, or informational notices.",
      "ucp_request": "omit"
    },
    "links": {
      "type": "array",
      "items": {
        "$ref": "types/link.json"
      },
      "description": "Optional merchant links (policies, FAQs).",
      "ucp_request": "omit"
    },
    "continue_url": {
      "type": "string",
      "format": "uri",
      "description": "URL for cart handoff and session recovery. Enables sharing and human-in-the-loop flows.",
      "ucp_request": "omit"
    },
    "expires_at": {
      "type": "string",
      "format": "date-time",
      "description": "Cart expiry timestamp (RFC 3339). Optional.",
      "ucp_request": "omit"
    }
  }
}