shop.dev

{
  "$defs": {
    "d0": {
      "properties": {
        "context": {
          "additionalProperties": true,
          "allOf": [
            {
              "$ref": "#/$defs/d1"
            },
            {
              "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/d2"
                  },
                  "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/d2"
                          }
                        ],
                        "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"
        },
        "distance": {
          "allOf": [
            {
              "additionalProperties": true,
              "description": "Stores within max meters of an explicit center. Use coordinates the user or host gave; never derive them. The radius is never widened or clamped.",
              "properties": {
                "center": {
                  "allOf": [
                    {
                      "$ref": "#/$defs/d3"
                    }
                  ]
                },
                "max": {
                  "description": "Inclusive radius in meters.",
                  "minimum": 0,
                  "type": "number"
                }
              },
              "required": [
                "center",
                "max"
              ],
              "title": "Location Distance",
              "type": "object"
            }
          ]
        },
        "filters": {
          "additionalProperties": true,
          "description": "Hard requirements; fields AND. A merchant rejects a filter it cannot evaluate with invalid_input rather than ignoring it; Shopify stores evaluate items only.",
          "properties": {
            "amenities": {
              "description": "Exact amenity IDs, all required.",
              "items": {
                "allOf": [
                  {
                    "$ref": "#/$defs/d2"
                  }
                ],
                "examples": [
                  "dev.ucp.amenity.wi_fi",
                  "dev.ucp.amenity.parking",
                  "dev.ucp.amenity.shopping.in_store_pickup",
                  "dev.ucp.amenity.shopping.curbside_pickup"
                ],
                "title": "Amenity Type"
              },
              "type": "array"
            },
            "hours": {
              "properties": {
                "open_at": {
                  "description": "RFC 3339 instant the store must be open at.",
                  "format": "date-time",
                  "pattern": "(?:[Zz]|[+-](?:[01][0-9]|2[0-3]):[0-5][0-9])$",
                  "type": "string"
                }
              },
              "required": [
                "open_at"
              ],
              "type": "object"
            },
            "items": {
              "description": "Variant IDs from catalog results; returns stores that have all of them available, up to 10 items per call.",
              "items": {
                "minLength": 1,
                "type": "string"
              },
              "minItems": 1,
              "type": "array",
              "uniqueItems": true
            }
          },
          "title": "Location Filter",
          "type": "object"
        },
        "ids": {
          "description": "Store IDs from search_locations, up to 10 per call.",
          "items": {
            "type": "string"
          },
          "minItems": 1,
          "type": "array"
        },
        "serves": {
          "allOf": [
            {
              "additionalProperties": true,
              "description": "Serviceability (can this store deliver to the target), not proximity; use distance for near. Exactly one of point or address. Merchants that cannot evaluate it, Shopify stores included, return invalid_input.",
              "maxProperties": 1,
              "minProperties": 1,
              "properties": {
                "address": {
                  "allOf": [
                    {
                      "$ref": "#/$defs/d1"
                    },
                    {
                      "anyOf": [
                        {
                          "properties": {
                            "address_country": {
                              "minLength": 1,
                              "type": "string"
                            }
                          },
                          "required": [
                            "address_country"
                          ]
                        },
                        {
                          "properties": {
                            "address_region": {
                              "minLength": 1,
                              "type": "string"
                            }
                          },
                          "required": [
                            "address_region"
                          ]
                        },
                        {
                          "properties": {
                            "postal_code": {
                              "minLength": 1,
                              "type": "string"
                            }
                          },
                          "required": [
                            "postal_code"
                          ]
                        }
                      ],
                      "type": "object"
                    }
                  ]
                },
                "point": {
                  "allOf": [
                    {
                      "$ref": "#/$defs/d3"
                    }
                  ]
                }
              },
              "propertyNames": {
                "anyOf": [
                  {
                    "const": "point"
                  },
                  {
                    "const": "address"
                  },
                  {
                    "$ref": "#/$defs/d2"
                  }
                ]
              },
              "title": "Location Serves",
              "type": "object"
            }
          ]
        },
        "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/d2"
              }
            ]
          },
          "title": "Signals",
          "type": "object"
        }
      },
      "required": [
        "ids"
      ],
      "type": "object"
    },
    "d1": {
      "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"
    },
    "d2": {
      "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"
    },
    "d3": {
      "description": "WGS 84 decimal degrees.",
      "properties": {
        "latitude": {
          "maximum": 90,
          "minimum": -90,
          "type": "number"
        },
        "longitude": {
          "maximum": 180,
          "minimum": -180,
          "type": "number"
        }
      },
      "required": [
        "latitude",
        "longitude"
      ],
      "title": "Geo",
      "type": "object"
    }
  },
  "properties": {
    "location": {
      "$ref": "#/$defs/d0",
      "allOf": [
        {
          "not": {
            "required": [
              "attribution"
            ]
          }
        }
      ],
      "type": "object"
    },
    "shop": {
      "description": "Exact seller.domain storefront hostname from offer; no scheme/path; one seller per cart/checkout.",
      "minLength": 1,
      "type": "string"
    }
  },
  "required": [
    "location",
    "shop"
  ],
  "type": "object"
}