Declared fields extension

Use the declared fields extension to collect the extra cart and checkout information that a business needs, beyond the fields that UCP defines. The extension defines how the business shares field definitions with your agent, how your agent submits values, and how captured values appear on orders.

Shopify returns localized fields: country-specific information that checkout needs for the buyer's destination, such as a personal customs code for shipments to South Korea. For details, see Localized fields.

• Extension name: dev.shopify.shopping.declared_fields
• Version: 2026-08-25
• Extends: dev.ucp.shopping.cart, dev.ucp.shopping.checkout, dev.ucp.shopping.order
• Schema: Declared fields JSON Schema

The extension has its own version, separate from UCP's. Version 2026-08-25 requires version 2026-08-25 or later of UCP.

The extension supports the following features:

• Receive required and optional fields that checkout needs.
• Learn why the business collects each field from its governed purpose.
• Submit declared field values as key and value entries.
• Carry cart fields and accepted values into checkout.
• Read captured values as read-only order fields.
• Receive errors for invalid values in messages[].

The extension depends on at least one of the following capabilities:

• Cart capability
• Checkout capability
• Order capability

Anchor to DiscoveryDiscovery

The business profile advertises support for declared fields. A single capability declaration lists every resource that supports declared fields:

A business can support declared fields on carts, checkouts, orders, or any combination of those resources, by narrowing extends. Before your agent submits or expects declared field values, check which resources the profile extends. Cart-to-checkout continuity applies when the profile extends both carts and checkouts.

If checkout requires a declared field, and your agent doesn't support dev.shopify.shopping.declared_fields, then the checkout returns status: "requires_escalation" with a redirect_to_checkout_required message (severity requires_buyer_input) and a continue_url, following the checkout escalation flow. The buyer then fills in the fields in Shopify checkout.

Anchor to SchemaSchema

When this capability is active, the extension adds an optional declared_fields array to each resource named in extends:

The declared_fields arrays in responses are ordered, and their order is the recommended presentation order. Preserve the order that the business returns.

Anchor to Declared fieldDeclared field

Each declared field contains the definition and current value of a field that the business defines. Cart, checkout, and order fields share the following properties:

The following properties depend on the resource:

Cart fields omit required, so they don't indicate whether checkout requires a value. Order fields omit both properties, because they're read-only.

Anchor to Localized fieldsLocalized fields

A checkout includes localized fields when the buyer's destination needs information that UCP doesn't define, such as a personal customs code for shipments to South Korea, or a CPF or CNPJ for Brazil. Which fields appear depends on the business's country, the delivery destination, and the location that the order ships from. The set of fields can change when the delivery address changes.

Localized fields have the following properties:

• key is Shopify's name for the field, for example shipping_credential_kr or tax_credential_br.
• title is the label to show the buyer.
• value_schema is { "type": "string" }, and presentation is { "preferred_control": "text" }.
• purpose is dev.shopify.shopping.declared_fields.generic.
• On a checkout, required says whether checkout can complete without a value.

The business validates the submitted value, and reports an invalid value as described in Invalid values.

Anchor to Purpose vocabularyPurpose vocabulary

A field's key and value_schema describe its identity and shape, but not why the business collects its data or how the data might affect the commerce outcome. That's why every declared field includes a required purpose, which gives your agent that governed signal.

Well-known purposes convey exact, portable intent. The field's key is still the unique identifier for that field instance, and it doesn't determine or change the purpose's meaning. The value_schema describes the portable kind of value, and the business's validation is authoritative for any limits that it sets. Shopify returns the following purpose:

Treat a purpose that you don't recognize as opaque, and use the field definition only for rendering and validation.

Businesses can't use a generic or open purpose to bypass a core field, a dedicated capability, or any safety restriction of the declared fields extension. An unknown purpose doesn't authorize trusted behavior or relax these restrictions.

Anchor to Value schema and presentationValue schema and presentation

Every field definition includes a required value_schema. Cart and checkout field definitions can also include presentation. Order fields don't carry input presentation hints, because they're read-only.

The two properties have separate responsibilities:

Shopify's declared field values are strings. A null value means that the field has no submitted value, or that your agent cleared it.

Anchor to JSON valueJSON value

The value property can contain any JSON value. It's always present on returned field definitions and on submitted field entries. A non-null value must match the field's value_schema. A null value explicitly represents an unset or cleared value.

Anchor to Declared field value schemaDeclared field value schema

The value_schema property is a JSON Schema Draft 2020-12 object that describes the non-null value that the field carries. Shopify returns the following value schemas:

Every $ref in a value_schema must be a local fragment under #/$defs/, which resolves within the same shopify_shopping_declared_fields.json schema document. The extension doesn't allow external references, so your agent never needs to fetch another schema.

Anchor to PresentationPresentation

The presentation property contains optional, non-normative rendering hints. Its properties don't affect whether a submitted value is valid. Your agent must tolerate unknown properties and values. If your agent doesn't recognize a hint, then it should fall back to a control that's appropriate for value_schema.

The presentation object contains the following property:

Anchor to OperationsOperations

Your agent submits declared field values through the standard create and update operations for carts and checkouts.

Anchor to Effects on resource stateEffects on resource state

Declared field values can affect other cart or checkout state that the business calculates, including totals. Your agent must process the complete returned resource, and must not assume that an update affects only declared_fields.

Anchor to Cart and checkout behaviorCart and checkout behavior

Carts and checkouts handle declared field values in the same way. Requests behave in the following ways:

• Replaced values: A request that includes declared_fields entries replaces all the submitted values. Include every field whose value you want to keep, not only the field that you change. A field that the request omits loses its value.
• Unchanged values: Omit declared_fields, or send an empty array, to keep all the current values.
• Clear values: Send "value": null for the field's key.
• Request format: Submit only key and value for each entry. The business ignores any definition properties that you include.
• Unknown keys: The business ignores entries whose key doesn't match a configured field.

Responses behave in the following ways:

• declared_fields contains all configured fields, with current values merged into each entry.
• Render declared fields in the order that the business returns them.
• value is null for fields that have no submitted value, or that your agent cleared.
• The business validates non-null values, and reports invalid values in messages[], as described in Invalid values.

Only checkout enforces requiredness. A cart is an exploratory resource with no completion operation, so cart fields omit required, and an unset value on its own doesn't cause a cart create or update operation to fail. Your agent can collect values while the buyer is still in the cart flow. On a checkout, a field with required: true needs a value before checkout can complete.

Anchor to Cart-to-checkout continuityCart-to-checkout continuity

When your agent converts a cart to a checkout with cart_id, and this extension is active for both resources, the business initializes the checkout with the field definitions and accepted values from the cart. The checkout response adds checkout-specific metadata, including required. Your agent doesn't need to resubmit accepted cart values in the create_checkout request. As part of the Cart capability's normal conversion behavior, the business ignores any overlapping declared field values in that request.

The business can add checkout-only fields. The first checkout response is authoritative for the checkout's current definitions and values. After the checkout is active, your agent should submit further declared field updates to the checkout. While the business keeps the linked cart, it should reflect accepted checkout updates in cart responses.

Anchor to Order behaviorOrder behavior

The business returns order declared fields in order read responses and event payloads. These fields are read-only:

• The business can return values captured at checkout completion, including values carried forward from the cart.
• You can't update order declared fields through order operations.
• Use value_schema to interpret each machine-readable value.
• Preserve the field order that the business returns.

Anchor to Invalid valuesInvalid values

If the business can't accept a submitted declared field value, then the field still appears in declared_fields, and the business reports the problem in the messages[] array:

The following error code applies to declared field validation:

Anchor to ExamplesExamples

Anchor to Checkout with declared field definitionsCheckout with declared field definitions

When your agent creates or updates a checkout, the response includes the declared fields that the business needs. This checkout ships to South Korea. Values are null until your agent submits them:

A cart response returns the same fields without required.

Anchor to Submitting declared field valuesSubmitting declared field values

Your agent submits values in create_checkout, update_checkout, create_cart, or update_cart:

The response returns the same fields as the checkout example, with the submitted value in value.

Anchor to Clearing a valueClearing a value

To clear a value, send null for its key, and include the other values that you want to keep:

Anchor to Order with declared field valuesOrder with declared field values

Order responses expose the definitions and values captured at checkout completion, without required or presentation: