shop.dev

{
  "$defs": {
    "d0": {
      "description": "Reverse domain, 2+ segments.",
      "examples": [
        "dev.ucp.shopping.checkout",
        "dev.ucp.common.identity_linking",
        "com.example.loyalty_gold",
        "com.example-shop.checkout",
        "com.2example.cart",
        "uk.co.example-shop.checkout",
        "xn--p1ai.example.checkout"
      ],
      "pattern": "^[a-z](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9_])?)+$",
      "title": "Reverse Domain Name",
      "type": "string"
    }
  },
  "properties": {
    "cart": {
      "allOf": [
        {
          "allOf": [
            {
              "$schema": "https://json-schema.org/draft/2020-12/schema",
              "additionalProperties": true,
              "name": "dev.ucp.shopping.cart",
              "properties": {
                "buyer": {
                  "additionalProperties": true,
                  "description": "Buyer details for personalized estimates.",
                  "properties": {
                    "email": {
                      "type": "string"
                    },
                    "first_name": {
                      "type": "string"
                    },
                    "last_name": {
                      "type": "string"
                    },
                    "phone_number": {
                      "description": "Buyer phone in E.164.",
                      "type": "string"
                    }
                  },
                  "title": "Buyer",
                  "type": "object"
                },
                "context": {
                  "allOf": [
                    {
                      "additionalProperties": true,
                      "allOf": [
                        {
                          "additionalProperties": true,
                          "description": "Coarse locality; not an address.",
                          "properties": {
                            "address_country": {
                              "description": "ISO 3166-1 alpha-2, e.g. US.",
                              "type": "string"
                            },
                            "address_region": {
                              "type": "string"
                            },
                            "postal_code": {
                              "type": "string"
                            }
                          },
                          "title": "Locality",
                          "type": "object"
                        },
                        {
                          "additionalProperties": true,
                          "properties": {
                            "currency": {
                              "description": "ISO 4217 preference/filter currency; verify output.",
                              "type": "string"
                            },
                            "eligibility": {
                              "description": "Nonidentifying reverse-domain benefits; ignore unknowns.",
                              "items": {
                                "$ref": "#/$defs/d0"
                              },
                              "type": "array",
                              "uniqueItems": true
                            },
                            "intent": {
                              "description": "Relevance hint, e.g. 'gift under $50'.",
                              "type": "string"
                            },
                            "language": {
                              "description": "BCP 47 preference, e.g. fr-CA.",
                              "type": "string"
                            },
                            "location": {
                              "description": "Opaque merchant location ID, not locality.",
                              "type": "string"
                            },
                            "payment": {
                              "description": "Advertised handlers, most preferred first; ignore unknowns.",
                              "items": {
                                "properties": {
                                  "handler": {
                                    "allOf": [
                                      {
                                        "$ref": "#/$defs/d0"
                                      }
                                    ],
                                    "description": "Merchant ucp.payment_handlers key."
                                  },
                                  "types": {
                                    "description": "Instrument types, most preferred first; ignore unknowns.",
                                    "items": {
                                      "type": "string"
                                    },
                                    "type": "array"
                                  }
                                },
                                "required": [
                                  "handler"
                                ],
                                "type": "object"
                              },
                              "type": "array"
                            }
                          },
                          "type": "object"
                        }
                      ],
                      "description": "Soft relevance/localization; checkout wins.",
                      "title": "Context",
                      "type": "object"
                    }
                  ],
                  "description": "Soft pricing/availability/currency hints; geo-IP may fallback."
                },
                "line_items": {
                  "description": "On update send every line; omissions delete, not merge.",
                  "items": {
                    "description": "Uses parent cart/checkout currency.",
                    "properties": {
                      "item": {
                        "properties": {
                          "id": {
                            "description": "Copy exact returned variant ID; never rebuild/truncate.",
                            "type": "string"
                          },
                          "quantity_unit": {
                            "allOf": [
                              {
                                "allOf": [
                                  {
                                    "if": {
                                      "properties": {
                                        "unit": {
                                          "const": "C62"
                                        }
                                      },
                                      "required": [
                                        "unit"
                                      ]
                                    },
                                    "properties": {
                                      "display_text": {
                                        "description": "Printable label for unrecognized units.",
                                        "type": "string"
                                      },
                                      "scale": {
                                        "default": 0,
                                        "description": "One step = 10^-scale units; omitted=0; C62 needs 0.",
                                        "maximum": 15,
                                        "minimum": 0,
                                        "type": "integer"
                                      },
                                      "unit": {
                                        "description": "UN/CEFACT Rec 20 code, else stable opaque custom ID.",
                                        "type": "string"
                                      }
                                    },
                                    "required": [
                                      "unit",
                                      "display_text"
                                    ],
                                    "then": {
                                      "properties": {
                                        "scale": {
                                          "const": 0
                                        }
                                      }
                                    },
                                    "title": "Unit",
                                    "type": "object"
                                  },
                                  {
                                    "properties": {
                                      "increment": {
                                        "default": 1,
                                        "description": "Step multiple (default 1); merchant may revise/reject, never reinterpret.",
                                        "minimum": 1,
                                        "type": "integer"
                                      }
                                    },
                                    "type": "object"
                                  }
                                ],
                                "description": "Sale basis is unit+scale, not display_text/increment.",
                                "title": "Quantity Unit"
                              }
                            ],
                            "description": "Omit for merchant basis; else assert unit/scale. C62/0 = each."
                          }
                        },
                        "required": [
                          "id"
                        ],
                        "title": "Item",
                        "type": "object"
                      },
                      "quantity": {
                        "description": "Integer sale-basis steps; missing quantity_unit is not each.",
                        "maximum": 9007199254740991,
                        "minimum": 1,
                        "type": "integer"
                      }
                    },
                    "required": [
                      "item",
                      "quantity"
                    ],
                    "title": "Line Item",
                    "type": "object"
                  },
                  "type": "array"
                },
                "signals": {
                  "additionalProperties": true,
                  "description": "Observed/verified platform facts; no buyer claims.",
                  "properties": {
                    "dev.ucp.buyer_ip": {
                      "type": "string"
                    },
                    "dev.ucp.user_agent": {
                      "type": "string"
                    }
                  },
                  "propertyNames": {
                    "allOf": [
                      {
                        "$ref": "#/$defs/d0"
                      }
                    ]
                  },
                  "title": "Signals",
                  "type": "object"
                }
              },
              "required": [
                "line_items"
              ],
              "title": "Cart",
              "type": "object",
              "version": "2026-08-25"
            },
            {
              "properties": {
                "discounts": {
                  "properties": {
                    "codes": {
                      "description": "Replace case-insensitively; [] clears all.",
                      "items": {
                        "type": "string"
                      },
                      "type": "array"
                    }
                  },
                  "type": "object"
                }
              },
              "type": "object"
            }
          ],
          "title": "Cart with Discount"
        },
        {
          "not": {
            "required": [
              "attribution"
            ]
          }
        }
      ],
      "type": "object"
    },
    "meta": {
      "properties": {
        "idempotency-key": {
          "description": "UUID for one write; reuse for exact retries. complete_checkout derives if omitted.",
          "format": "uuid",
          "type": "string"
        }
      },
      "type": "object"
    },
    "shop": {
      "description": "Exact seller.domain storefront hostname from offer; no scheme/path; one seller per cart/checkout.",
      "minLength": 1,
      "type": "string"
    }
  },
  "required": [
    "cart",
    "shop"
  ],
  "type": "object"
}