{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Integrating custom fields at checkout","meta":[{"name":"robots","content":"noindex"}],"llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"integrating-custom-fields-at-checkout","__idx":0},"children":["Integrating custom fields at checkout"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide explains how to collect custom field responses during checkout."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Be sure to read ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/spotnana/basic_custom_field_concepts"},"children":["custom field concepts"]}," to familiarize yourself with this feature before starting to use it."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The flow uses three calls:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Get the custom fields applicable to the booking in progress."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Get the list of options applicable to the custom fields from step 1."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Submit the responses collected from the traveler with the booking request."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"getting-the-applicable-custom-fields","__idx":1},"children":["Getting the applicable custom fields"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Call the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/openapi/customfieldapi/custom-field-v3/getapplicablecustomfields"},"children":["get applicable custom fields"]}," endpoint."," ","The request requires the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["userId"]}," of the traveler and a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bookingContext"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bookingContext"]}," requires a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tripId"]}," and an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["itinerary"]}," object."," ","For an air booking, set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["itineraryType"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AIR"]}," and supply the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["searchId"]}," and the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rateOptionId"]}," of the itinerary the traveler selected. See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/spotnana/air_booking_workflow"},"children":["air booking workflow"]}," for more details regarding these identifiers."," ","Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bookingFlowType"]}," to distinguish a new booking from a modification or a cancellation."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here's a sample ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/openapi/customfieldapi/custom-field-v3/getapplicablecustomfields"},"children":["get applicable custom fields"]}," API request:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"POST /v3/applicable-custom-fields","header":{"title":"POST /v3/applicable-custom-fields","controls":{"copy":{}}},"source":"{\n  \"userId\": \"8d2f6c14-5b73-4a19-9c0e-3f7a2b6d1e84\",\n  \"bookingContext\": {\n    \"tripId\": \"a1c9e70b-42d8-4f36-8b51-6d0c7e29af13\",\n    \"itinerary\": {\n      \"itineraryType\": \"AIR\",\n      \"searchId\": \"a3f1c8d29b6e4705\",\n      \"rateOptionId\": \"7c40e9b2-5d18-4af3-9016-8be2d7c5301f\"\n    },\n    \"bookingFlowType\": \"NEW_BOOKING\",\n    \"pnrCreationProcessType\": \"OBT\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The response contains a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customFields"]}," array with all the details regarding the applicable custom fields for the traveler and the booking flow."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here's a sample ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/openapi/customfieldapi/custom-field-v3/getapplicablecustomfields"},"children":["get applicable custom fields"]}," API response:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"POST /v3/applicable-custom-fields","header":{"title":"POST /v3/applicable-custom-fields","controls":{"copy":{}}},"source":"{\n  \"hasNewCustomFields\": true,\n  \"customFields\": [\n    {\n      \"id\": \"d18c4e73-2fa9-4b60-91cd-7e35a806f2b1\",\n      \"name\": \"Reason for the out of policy booking\",\n      \"armId\": \"6c9a2f84-b073-41de-a52f-38e1c7b094d6\",\n      \"action\": {\n        \"type\": \"AUTO\",\n        \"name\": \"LD\",\n        \"description\": \"Lower fare declined\",\n        \"hidden\": false\n      }\n    },\n    {\n      \"id\": \"9b57e2a4-13cd-4068-8fa1-2e6d09c745b8\",\n      \"name\": \"Which cost center should this trip be charged to?\",\n      \"armId\": \"27df906c-4b81-45ea-93f7-c0a85e1d62b3\",\n      \"action\": {\n        \"type\": \"USER\",\n        \"required\": true,\n        \"format\": {\n          \"type\": \"OPTION_LIST\",\n          \"optionListTypeFormat\": {\n            \"isMultiSelect\": false,\n            \"isPctType\": false\n          },\n          \"customValueFormat\": {\n            \"isCustomValueAllowed\": false\n          }\n        },\n        \"userOptionSource\": {\n          \"type\": \"MANUAL\",\n          \"optionGroupId\": \"e40a71b9-38c6-42fd-8b05-9a71cde264f7\"\n        }\n      }\n    },\n    {\n      \"id\": \"71e8b3d0-5c47-4a92-86fb-2d09e4a15c73\",\n      \"name\": \"Add a note for the travel desk\",\n      \"armId\": \"0f3d97a5-8e21-4cb6-b74d-15a6c0392e8f\",\n      \"action\": {\n        \"type\": \"USER\",\n        \"required\": false,\n        \"format\": {\n          \"type\": \"TEXT_INPUT\",\n          \"userInputFormat\": {\n            \"type\": \"NON_REGEX\",\n            \"allowedChars\": \"ALL\",\n            \"minLength\": 1,\n            \"maxLength\": 120\n          }\n        }\n      }\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"fetching-the-options-for-the-custom-field","__idx":2},"children":["Fetching the options for the custom field"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/openapi/customfieldapi/custom-field-v3/getcustomfieldv3optionlist"},"children":["get options for a custom field arm"]}," API to get the applicable options (e.g., answers for a question) for a custom field."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here's a sample ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/openapi/customfieldapi/custom-field-v3/getcustomfieldv3optionlist"},"children":["get options for a custom field arm"]}," API request:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"POST /v3/companies/{companyId}/custom-fields/{customFieldId}/arms/{armId}/option-list","header":{"title":"POST /v3/companies/{companyId}/custom-fields/{customFieldId}/arms/{armId}/option-list","controls":{"copy":{}}},"source":"{\n  \"paginationParams\": {\n    \"offset\": 0,\n    \"limit\": 50\n  },\n  \"fetchEffectiveAdditionalInfos\": true\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"A sample response for the above API call:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"POST /v3/companies/{companyId}/custom-fields/{customFieldId}/arms/{armId}/option-list","header":{"title":"POST /v3/companies/{companyId}/custom-fields/{customFieldId}/arms/{armId}/option-list","controls":{"copy":{}}},"source":"{\n  \"paginationParams\": {\n    \"totalNumResults\": 3\n  },\n  \"options\": [\n    {\n      \"name\": \"CC-1000\",\n      \"description\": \"Engineering\"\n    },\n    {\n      \"name\": \"CC-2000\",\n      \"description\": \"Sales\"\n    },\n    {\n      \"name\": \"CC-3000\",\n      \"description\": \"Operations\"\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["options"]}," row in the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/spotnana/basic_custom_field_concepts#custom-field-api-parameters"},"children":["custom field API parameters"]}," table for more information about custom field options."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"submitting-the-responses","__idx":3},"children":["Submitting the responses"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send the collected answers in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customFieldV3Responses"]}," array when making a new booking request. For example, in this scenario, update the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customFieldV3Responses"]}," array in the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/openapi/airapi/air/aircreatepnr"},"children":["create air PNR"]}," API request."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here's a sample ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/openapi/airapi/air/aircreatepnr"},"children":["create air PNR"]}," API request:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"POST /v2/air/create-pnr","header":{"title":"POST /v2/air/create-pnr","controls":{"copy":{}}},"source":"// ... payload truncated for focus\n{\n  \"customFieldV3Responses\": [\n    {\n      \"fieldId\": \"d18c4e73-2fa9-4b60-91cd-7e35a806f2b1\",\n      \"armId\": \"6c9a2f84-b073-41de-a52f-38e1c7b094d6\",\n      \"selectedOptions\": [\n        {\n          \"name\": \"LD\",\n          \"description\": \"Lower fare declined\"\n        }\n      ]\n    },\n    {\n      \"fieldId\": \"9b57e2a4-13cd-4068-8fa1-2e6d09c745b8\",\n      \"armId\": \"27df906c-4b81-45ea-93f7-c0a85e1d62b3\",\n      \"selectedOptions\": [\n        {\n          \"name\": \"CC-1000\",\n          \"description\": \"Engineering\"\n        }\n      ]\n    },\n    {\n      \"fieldId\": \"71e8b3d0-5c47-4a92-86fb-2d09e4a15c73\",\n      \"armId\": \"0f3d97a5-8e21-4cb6-b74d-15a6c0392e8f\",\n      \"selectedOptions\": [\n        {\n          \"name\": \"Arriving a day early for an internal review\",\n          \"additionalUserInput\": \"Arriving a day early for an internal review\"\n        }\n      ]\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You'll find the same object in hotel, car, rail, and limo booking creation APIs as well."," ","Send the custom field responses using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customFieldV3Responses"]}," object during the PNR creation."]}]}]},"headings":[{"value":"Integrating custom fields at checkout","id":"integrating-custom-fields-at-checkout","depth":1},{"value":"Getting the applicable custom fields","id":"getting-the-applicable-custom-fields","depth":2},{"value":"Fetching the options for the custom field","id":"fetching-the-options-for-the-custom-field","depth":2},{"value":"Submitting the responses","id":"submitting-the-responses","depth":2}],"frontmatter":{"seo":{"title":"Integrating custom fields at checkout"}},"lastModified":"2026-09-16T16:41:37.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/custom_field_guides/custom_field_checkout_guide","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}