Load field options

PATCH /api/reload_customer_app returns choices for a registered customer form field. Dependency filters narrow the list, for example to regions of the selected country.

PATCH/api/reload_customer_app?lang=en

reload_customer_app

Request and response

Request JSON

JSON

{
  "form": "fUserAddress",
  "field_name": "country",
  "filters": {}
}

Response

Send a request to see the backend response.

Request fields

Send form, field_name and filters at the JSON root. Here form identifies the owning form; this helper does not submit that form or save an address.

Property	Purpose
`form`*	Required registered form name, such as `fUserAddress`. The auxiliary endpoint using the options may have a different form.
`field_name`*	Required reloadable field of that form. The address form uses country and state; the city-suggestion form uses region.
`filters`*{}	Required object of criteria for this field’s subfilter. Use an empty object when no criteria are needed; pass the selected country ID in `filters.country` for regions.

Response fields

On success, form_errors is null.

Property	Purpose
`page_data`	Option array for the requested field. The fields of one option are listed below.
`page_data[].key`	Option label: text, a number or translations. For a period, the number of days.
`page_data[].value`	Selected option value to send in the request.
`page_data[].locale`	Countries only: translated names in `printable_name`.
`page_data[].iso_3166_1_a2`	Countries only: ISO code used to display the flag.
`page_data[].suggestions`	Countries only: `true` — city and street suggestions can be requested; `false` — use manual city and street entry.
`page_data[].shipping_locale`	Countries only: locale code used for shipping.
`page_data[].is_shipping_country`	Countries only: `true` when delivery to this country is available.
`page_data[].id`	Region ID.
`page_data[].locales`	Region names keyed by locale code. Missing translations are empty objects.
`page_data[].country`	Two-letter country code (ISO 3166-1 alpha-2).
`page_data[].country_id`	Country ID accepted by `filters.country`.
`page_data[].region_iso`	Stored region ISO code. It can be empty; the response preserves the stored text.

How it works

Country and region requests

These requests load options for the customer address form. In the region example, replace country ID 1 with the selected country option’s value.

Countries

Load enabled countries from fUserAddress.country. The response includes localized names, ISO codes, text-hint availability and the locale used for shipping.

{
  "form": "fUserAddress",
  "field_name": "country",
  "filters": {}
}

Regions of a country

Reload fUserAddress.state with filters.country. Submit the selected option’s value as region when requesting address hints.

{
  "form": "fUserAddress",
  "field_name": "state",
  "filters": {
    "country": 1
  }
}

Seller choices

For the seller selector in sellers_get, request ffSellerAccountViewer.sellers. Use filters.seller_name to narrow the names, filters.id for an exact account, or filters.owner_rating_from for a minimum rating. The response contains at most 15 options: value is the account ID, key is the name, and seller_raiting is the rating. Guests can load it too; the options are the sellers this list shows.

{
  "form": "ffSellerAccountViewer",
  "field_name": "sellers",
  "filters": {}
}

Subscription periods

For subscriptions_subscribe, use fSubscribe.period with the selected tariff ID. option_must_be_present is optional and restricts the result to periods with a price for that option. Returned value is the tariff-cost ID and numeric key is days. Renewal uses fPaidSubsRenewTarriff.period_to_add or .renew_period; renewal settings use fPaidSubsChangeRenewPeriod.renew_period with the same filters.

{
  "form": "fSubscribe",
  "field_name": "period",
  "filters": {
    "tariff": 1
  }
}

For city hints, use form: "fCitySuggestion" and field_name: "region" with the same filters.country. The linked hint pages provide selectors and show the actual option requests and responses.

Discovery, access and errors

This root helper is outside page_data.unauth.paths and page_data.auth.paths. Use its fixed local path with the shared request transport, session cookies and CSRF handling; do not resolve it through API.fromName().

Access is checked by the requested subfilter. The country and region sources shown here require an authenticated, active customer. Address-hint endpoints also require a signed-in session; their availability comes from current Application Load discovery. Form metadata does not grant access.

Missing request keys, unregistered forms and unsupported fields are rejected. Check HTTP status and form_errors separately: HTTP 200 can contain a general error in __all__, including an authorization error. Loading choices does not submit the main hint request.

Pages

Page	Purpose
Address suggestions	Find street suggestions by text within a selected country, region and city using the country’s address-suggestion plugin.
City suggestions	Find cities by text within a selected country and region using the country’s address-suggestion plugin.
Request class	The API class resolves endpoints by `url_name` from Application Load, sends request data and returns the HTTP response together with the API result.
Success and errors	Check an API result, display validation messages, and handle HTTP errors and session changes.
Connected fields and option reloading	Every endpoint tells your storefront what data it accepts. This description is called a form. It comes in the Application Load response (`POST /api/appload`) next to the endpoint’s URL and HTTP method. Read it to know which inputs to show the customer and how to put their values into the request body.