On this page
No Headings
PayPal-controlled checkout field for buyer data collection with structured values and validation.
Field Lifecycle:
Structured Values: Each field type has a specific value schema based on its requirements. Age verification uses boolean confirmation, text fields use strings, etc.
objecttyperequiredstring"AGE_VERIFICATION_18_PLUS", "AGE_VERIFICATION_21_PLUS", "GIFT_RECIPIENT_EMAIL", "GIFT_RECIPIENT_NAME", "GIFT_MESSAGE", "DELIVERY_INSTRUCTIONS", "DELIVERY_DATE_PREFERENCE", "ALLERGY_INFORMATION", "CUSTOM_ENGRAVING_TEXT", "CUSTOM_SIZING_INFO", "TERMS_ACCEPTANCE", "PRIVACY_CONSENT"PayPal-approved checkout field type
statusrequiredstring"PENDING", "COMPLETED", "REJECTED", "ERROR"Field completion and validation status:
PENDING: Field needs customer input
COMPLETED: Valid value provided and accepted
REJECTED: Invalid or unacceptable value provided
ERROR: System error during processing
valueStructured 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.
oneOf[0]objectAge verification confirmation value
typerequiredstring"AGE_VERIFICATION_18_PLUS", "AGE_VERIFICATION_21_PLUS"This should match the CheckField type.
confirmedrequiredbooleanWhether age verification was confirmed
verification_methodstring"self_declaration", "id_verification", "third_party"Method used for age verification
verification_datestringdate-timeWhen verification was completed
oneOf[1]objectGift recipient email information
typerequiredstring"GIFT_RECIPIENT_EMAIL"This should match the CheckField type.
emailrequiredstringemailRecipient's email address
verifiedbooleanWhether email was verified
oneOf[2]objectGift recipient name information
typerequiredstring"GIFT_RECIPIENT_NAME"This should match the CheckField type.
namerequiredstringRecipient's full name
first_namestringRecipient's first name
last_namestringRecipient's last name
oneOf[3]objectGift message content
typerequiredstring"GIFT_MESSAGE"This should match the CheckField type.
messagerequiredstringPersonal message for the recipient
sender_namestringName of the person sending the gift
oneOf[4]objectSpecial delivery instructions
typerequiredstring"DELIVERY_INSTRUCTIONS"This should match the CheckField type.
instructionsrequiredstringSpecial delivery instructions
access_codestringBuilding or gate access code
contact_phonestringContact phone for delivery
oneOf[5]objectPreferred delivery date and time
typerequiredstring"DELIVERY_DATE_PREFERENCE"This should match the CheckField type.
preferred_datestringdatePreferred delivery date
time_windowstring"morning", "afternoon", "evening", "anytime"Preferred time window
specific_timestring^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$Specific preferred time (HH:MM format)
oneOf[6]objectAllergy and medical restriction information
typerequiredstring"ALLERGY_INFORMATION"This should match the CheckField type.
allergiesarrayList of known allergies
itemsstringseveritystring"mild", "moderate", "severe", "life_threatening"Allergy severity level
medicationsarrayMedications to avoid
itemsstringemergency_contactstringEmergency contact information
oneOf[7]objectCustom engraving text specification
typerequiredstring"CUSTOM_ENGRAVING_TEXT"This should match the CheckField type.
textrequiredstringText to be engraved
fontstring"arial", "times", "script", "block"Preferred font style
sizestring"small", "medium", "large"Text size preference
positionstring"front", "back", "side", "bottom"Engraving position
oneOf[8]objectCustom sizing measurements
typerequiredstring"CUSTOM_SIZING_INFO"This should match the CheckField type.
measurementsobjectBody measurements
cheststringChest measurement
waiststringWaist measurement
heightstringHeight measurement
weightstringWeight
size_preferencestring"tight", "regular", "loose"Fit preference
special_requirementsstringSpecial sizing requirements
oneOf[9]objectTerms and conditions acceptance
typerequiredstring"TERMS_ACCEPTANCE"This should match the CheckField type.
acceptedrequiredbooleanWhether terms were accepted
terms_versionrequiredstringVersion of terms accepted
acceptance_datestringdate-timeWhen terms were accepted
ip_addressstringIP address of acceptance
oneOf[10]objectPrivacy policy consent
typerequiredstring"PRIVACY_CONSENT"This should match the CheckField type.
consentedrequiredbooleanWhether privacy policy was consented to
consent_typesarrayTypes of consent given
itemsstring"data_processing", "marketing", "third_party_sharing", "analytics"policy_versionstringPrivacy policy version
consent_datestringdate-timeWhen consent was given
contextobjectAdditional 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_issueobjectAssociated validation issue when status is REJECTED or ERROR. Provides detailed information about why the field value was not accepted.
When present:
When null:
coderequiredstring"INVENTORY_ISSUE", "PRICING_ERROR", "SHIPPING_ERROR", "PAYMENT_ERROR", "DATA_ERROR", "BUSINESS_RULE_ERROR"Consolidated error category
typerequiredstring"MISSING_FIELD", "INVALID_DATA", "BUSINESS_RULE"Type classification for error handling
messagerequiredstringTechnical message for developers and logging
user_messagestringCustomer-friendly message for end users
variant_idstringSpecific item ID if the issue is item-specific
fieldstringSpecific field name if the issue is field-specific
contextCategory-specific context information
anyOf[0]objectContext for inventory and stock-related issues
specific_issuestring"ITEM_OUT_OF_STOCK", "INSUFFICIENT_INVENTORY", "BACK_ORDERED", "PRE_ORDER_ONLY", "ITEM_DISCONTINUED", "LOW_STOCK_WARNING", "INVENTORY_RESERVED", "SEASONAL_UNAVAILABLE", "VARIANT_NOT_AVAILABLE", "CUSTOM_OPTION_UNAVAILABLE"Specific inventory issue type
item_idstringProduct item identifier
variant_idstringProduct variant identifier if applicable
available_quantityintegerCurrently available quantity
requested_quantityintegerRequested quantity
reserved_quantityintegerQuantity reserved for other transactions
restock_datestringdate-timeExpected restock date
estimated_ship_datestringdate-timeEstimated shipping date for back-orders
back_order_limitintegerMaximum allowed back-order quantity
current_back_ordersintegerCurrent number of back-orders
discontinuation_datestringdate-timeDate product was discontinued
suggested_alternativesarrayAlternative product IDs
itemsstringupgrade_availablebooleanWhether newer version is available
seasonal_start_datestringdate-timeWhen seasonal product becomes available
last_soldstringdate-timeWhen item was last sold
anyOf[1]objectContext for pricing and financial issues
specific_issuestring"PRICE_MISMATCH", "DISCOUNT_EXPIRED", "DISCOUNT_USAGE_LIMIT_EXCEEDED", "DISCOUNT_CUSTOMER_INELIGIBLE", "DISCOUNT_MINIMUM_NOT_MET", "TAX_CALCULATION_FAILED", "CURRENCY_NOT_SUPPORTED", "CURRENCY_MISMATCH", "PROMOTIONAL_CONFLICT"Specific pricing issue type
variant_idstringItem with pricing issue
original_pricestringOriginal price value
current_pricestringCurrent price value
currency_codestringCurrency code
price_change_reasonstring"promotional_ended", "promotional_started", "market_adjustment", "cost_increase", "seasonal_pricing", "component_cost_increase", "terms_updated"Reason for price change
price_increasestringAmount of price increase
price_decreasestringAmount of price decrease
coupon_codestringCoupon code with issues
usage_limitintegerCoupon usage limit
current_usageintegerCurrent coupon usage count
expiration_datestringdate-timeDiscount expiration date
minimum_order_amountstringMinimum order for discount
supported_currenciesarrayList of supported currencies
itemsstringfound_currenciesarrayMultiple currencies found in cart
itemsstringtax_service_errorstringTax calculation service error
current_datestringdate-timeCurrent system date for comparisons
discount_amountstringDiscount amount that was applied
required_currency_consistencybooleanWhether all items must use same currency
mixed_itemsarrayItems with different currencies
itemsobjectvariant_idstringcurrencystringanyOf[2]objectContext for shipping and address issues
specific_issuestring"MISSING_SHIPPING_ADDRESS", "SHIPPING_ADDRESS_INVALID", "SHIPPING_TO_PO_BOX_NOT_ALLOWED", "NO_SHIPPING_OPTIONS", "INTERNATIONAL_SHIPPING_RESTRICTED", "REGION_RESTRICTED", "OVERSIZED_ITEM_SHIPPING", "HAZARDOUS_MATERIAL_SHIPPING", "SHIPPING_ZONE_NOT_COVERED", "MISSING_COORDINATES_FOR_ENHANCED_DELIVERY"Specific shipping issue type
validation_failuresarraySpecific address validation failures
itemsstringsuggested_correctionsobjectSuggested address corrections
postal_codestringaddress_line_1stringadmin_area_2stringaddress_quality_scorenumberAddress validation quality score
restricted_itemsarrayItems with shipping restrictions
itemsstringrestriction_reasonstring"signature_required", "age_verification_required", "export_controlled", "hazardous_material", "oversized_item", "po_box_restriction"Reason for shipping restriction
po_box_detectedbooleanWhether PO Box was detected
destination_countrystringDestination country code
restricted_regionstringRestricted region identifier
supported_countriesarrayList of supported countries
itemsstringprovided_addressstringAddress string that failed validation
anyOf[3]objectContext for payment processing issues
specific_issuestring"PAYMENT_AMOUNT_TOO_LARGE", "PAYMENT_AMOUNT_TOO_SMALL", "PAYMENT_METHOD_NOT_ACCEPTED", "CURRENCY_CONVERSION_FAILED", "PAYMENT_PROCESSOR_UNAVAILABLE", "MERCHANT_ACCOUNT_ISSUE", "PAYMENT_DECLINED", "PAYMENT_INSUFFICIENT_FUNDS", "PAYMENT_EXPIRED", "PAYMENT_FRAUD_DETECTED"Specific payment issue type
order_totalstringTotal order amount
payment_limitstringMaximum payment limit
minimum_amountstringMinimum payment amount
excess_amountstringAmount exceeding limit
payment_methodstringPayment method being used
currency_codestringTransaction currency
from_currencystringSource currency for conversion
to_currencystringTarget currency for conversion
conversion_servicestringCurrency conversion service status
supported_payment_methodsarrayList of supported payment methods
itemsstringprocessor_error_codestringPayment processor specific error code
decline_reasonstringReason for payment decline
payment_tokenstringPayment token that was declined
anyOf[4]objectContext for data validation issues
specific_issuestring"MISSING_CHECKOUT_FIELDS", "MISSING_PAYMENT_METHOD", "MISSING_POLICY_ACCEPTANCE", "REQUIRED_FIELD_MISSING", "INVALID_EMAIL_FORMAT", "INVALID_PHONE_FORMAT", "FIELD_VALUE_TOO_LONG", "FIELD_VALUE_TOO_SHORT", "INVALID_DATE_FORMAT", "FUTURE_DATE_NOT_ALLOWED", "INVALID_CUSTOMER_DATA", "ITEM_NOT_FOUND", "INVALID_ITEM_DATA", "ITEM_ATTRIBUTE_MISMATCH"Specific data validation issue type
field_namestringName of the field with validation error
provided_valuestringValue that failed validation
expected_formatstringExpected format description
max_lengthintegerMaximum allowed length
min_lengthintegerMinimum required length
current_lengthintegerCurrent value length
regex_patternstringRequired regex pattern
suggested_valuestringSuggested corrected value
allowed_valuesarrayList of allowed values for enum fields
itemsstringrequired_fieldsarrayList of required field names
itemsstringfield_descriptionsobjectDescriptions for required fields
anyOf[5]objectContext for business logic violations
specific_issuestring"MINIMUM_ORDER_NOT_MET", "MINIMUM_QUANTITY_NOT_MET", "MAXIMUM_QUANTITY_EXCEEDED", "CART_LIMIT_EXCEEDED", "CUSTOMER_ACCOUNT_SUSPENDED", "PURCHASE_LIMIT_EXCEEDED", "BULK_ORDER_APPROVAL_REQUIRED", "STORE_TEMPORARILY_CLOSED", "AGE_RESTRICTED_PRODUCT", "LOYALTY_PROGRAM_VALIDATION_FAILED", "BUSINESS_HOURS_RESTRICTION", "PRODUCT_ARCHIVED"Specific business rule issue type
current_amountstringCurrent order amount
required_amountstringRequired minimum amount
maximum_amountstringMaximum allowed amount
remaining_amountstringAmount needed to meet minimum
account_statusstringCustomer account status
suspension_reasonstringReason for account suspension
suspension_datestringdate-timeDate of account suspension
monthly_limitstringMonthly purchase limit
current_month_totalstringCurrent month purchase total
reset_datestringdate-timeWhen limits reset
total_quantityintegerTotal quantity in bulk order
approval_thresholdintegerQuantity requiring approval
maintenance_end_timestringdate-timeWhen maintenance ends
service_statusstringCurrent service status
retry_afterintegerSeconds before retry recommended
contact_infostringSupport contact information
restricted_itemsarrayItems with restrictions
itemsstringage_requirementintegerRequired minimum age
business_hoursobjectStore business hours
open_timestringclose_timestringtimezonestringshortage_amountstringAmount needed to meet minimum requirements
exceeds_bystringAmount by which limit is exceeded
resolution_optionsarrayAvailable actions to resolve this issue
itemsobjectAvailable action to resolve a validation issue
actionrequiredstring"REDIRECT_TO_MERCHANT", "MODIFY_CART", "ACCEPT_NEW_PRICE", "ACCEPT_BACK_ORDER", "SUGGEST_ALTERNATIVE", "REMOVE_ITEM", "UPDATE_ADDRESS", "PROVIDE_MISSING_FIELD", "USE_DIFFERENT_PAYMENT", "SPLIT_ORDER", "CONTACT_SUPPORT", "RETRY_LATER", "REQUEST_APPROVAL", "WAIT_FOR_RESTOCK", "USE_DIFFERENT_CURRENCY", "ACCEPT_PRE_ORDER", "UPDATE_SHIPPING_METHOD", "ACCEPT_TERMS", "VERIFY_ACCOUNT", "APPLY_DIFFERENT_COUPON", "REMOVE_COUPON", "CHOOSE_DIFFERENT_VARIANT"Machine-readable action identifier
labelrequiredstringHuman-readable action label
urlstringuriURL to redirect to for resolution
metadataobjectAdditional action metadata
cost_impactstringFinancial impact of this action
prioritystring"HIGH", "MEDIUM", "LOW"Priority level for this resolution
auto_applicablebooleanWhether this action can be applied automatically
estimated_timestringEstimated time for resolution
redirect_requiredbooleanWhether this action requires user redirect