CheckoutField

PayPal-controlled checkout field for buyer data collection with structured values and validation.

Field Lifecycle:

PENDING: Field needs customer input
COMPLETED: Valid value provided and accepted
REJECTED: Invalid/unacceptable value provided
ERROR: System error during processing

Structured Values: Each field type has a specific value schema based on its requirements. Age verification uses boolean confirmation, text fields use strings, etc.

statusenumRequired

Field completion and validation status: **PENDING**: Field needs customer input - Initial state when field is required - AI agent should collect this information - value field is null or empty **COMPLETED**: Valid value provided and accepted - Customer provided acceptable input - Value passes all validation rules - Cart can proceed with this field resolved **REJECTED**: Invalid or unacceptable value provided - Customer provided input that doesn't meet requirements - validation_issue explains the specific problem - AI agent should request corrected input **ERROR**: System error during processing - Technical failure in field processing - Should retry or escalate to support - Not caused by customer input

Value in"PENDING" | "COMPLETED" | "REJECTED" | "ERROR"

valueobject<11 types>Optional

Structured value based on field type. Each checkout field type has a specific value schema. Use oneOf to validate against the appropriate structure for the field type.

One of the following types

11 types

GiftMessageValue

Gift message content

CustomEngravingTextValue

Custom engraving text specification

CustomSizingInfoValue

Custom sizing measurements

contextobjectOptional

Additional context and metadata for the checkout field. This is a flexible object that can contain any field-specific information needed for validation, display, or processing. The structure varies based on the field type.

validation_issueobject<ValidationIssue>Optional

Associated validation issue when status is REJECTED or ERROR. Provides detailed information about why the field value was not accepted. **When present:** - status is REJECTED: Customer input didn't meet requirements - status is ERROR: System error processing the field **When null:** - status is PENDING: No validation attempted yet - status is COMPLETED: Validation passed successfully

ValidationIssue properties

8 properties

messagestringRequired

Technical message for developers and logging

user_messagestringOptional

Customer-friendly message for end users

contextobject<6 types>Optional

Category-specific context information

One of the following types

6 types

InventoryIssueContext

Context for inventory and stock-related issues

PricingErrorContext

Context for pricing and financial issues

ShippingErrorContext

Context for shipping and address issues

PaymentErrorContext

Context for payment processing issues

DataErrorContext

Context for data validation issues

BusinessRuleErrorContext

Context for business logic violations

resolution_optionsobject<ResolutionOption>[]Optional

Available actions to resolve this issue

On this page

CheckoutField

One of the following types

AgeVerificationValue properties

GiftRecipientEmailValue properties

GiftRecipientNameValue properties

GiftMessageValue properties

DeliveryInstructionsValue properties

DeliveryDatePreferenceValue properties

AllergyInformationValue properties

CustomEngravingTextValue properties

CustomSizingInfoValue properties

object properties

TermsAcceptanceValue properties

PrivacyConsentValue properties

ValidationIssue properties

One of the following types

InventoryIssueContext properties

PricingErrorContext properties

object properties

ShippingErrorContext properties

object properties

PaymentErrorContext properties

DataErrorContext properties

BusinessRuleErrorContext properties

object properties

ResolutionOption properties

object properties

Back to top

On this page

On this page

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more

CheckoutField

One of the following types

AgeVerificationValue properties

GiftRecipientEmailValue properties

GiftRecipientNameValue properties

GiftMessageValue properties

DeliveryInstructionsValue properties

DeliveryDatePreferenceValue properties

AllergyInformationValue properties

CustomEngravingTextValue properties

CustomSizingInfoValue properties

object properties

TermsAcceptanceValue properties

PrivacyConsentValue properties

ValidationIssue properties

One of the following types

InventoryIssueContext properties

PricingErrorContext properties

object properties

ShippingErrorContext properties

object properties

PaymentErrorContext properties

DataErrorContext properties

BusinessRuleErrorContext properties

object properties

ResolutionOption properties

object properties

Back to top

On this page