Skip to main content

Removing optional values with null and stricter validation of query parameters

· 3 min read
Albert Tiñena
Albert Tiñena
Chief Technology Officer (CTO)
David Sancho
David Sancho
Principal Engineer & Technical Architect

This release makes write operations and query parameters more explicit and predictable.

Integrations can now remove the value of optional fields by sending null, and the API now rejects invalid values in fields, includes and locales instead of silently ignoring them.

Removing optional values with null​

In partial updates (PATCH) and bulk endpoints, fields not included in the request keep their current value. Until now, there was no consistent way to remove the value of an optional field.

Optional fields now accept null to remove their value:

PATCH /api/v1/price-lists/7
{
  "minimum_order_amount": null,
  "global_discount": null
}
  • For text fields, null leaves the field empty.
  • For price list discounts, null sets the discount to 0.
  • Fields such as offer_price, flash_offer, cost_price, minimum_order_amount, supplier_id, brand_id, merchant_categories.google and size_guide_file accept null.
  • Required fields do not accept null.
  • category_ids does not accept an empty list, because a product must always have at least one category.

Updating a price list without sending its discounts no longer resets them: fields not included in the request keep their current value.

Stricter validation of fields and includes​

Query parameter names were already validated strictly: unknown parameters return 400 Bad Request. Now their values are validated as well.

fields​

fields only accepts fields that the resource returns, including localized fields such as name or description. Any other value returns 400 Bad Request:

GET /api/v1/brands?fields=internal_id,nmae
{
  "detail": "Invalid value(s) in 'fields' parameter: nmae. Supported fields: body_html, delivery_time_in_stock, [...], url."
}

Previously, a typo in fields was silently ignored, and the response could contain only the fixed fields (for example, just id).

Write-only fields, such as brand_id or category_ids, cannot be selected with fields either, since they are never returned.

includes​

includes only accepts the nested objects available for the resource (for example, variants, brand, categories and supplier for products):

GET /api/v1/products?includes=variant
{
  "detail": "Invalid value(s) in 'includes' parameter: variant. Supported values: brand, categories, supplier, variants."
}

Resources without nested objects reject any value in includes.

Validated before writing​

In write requests (POST, PATCH), fields and includes are validated before the request is processed. A request with invalid values returns 400 Bad Request without creating or modifying any data.

Locales​

  • locales now only accepts the locales enabled for the store, as documented. Requesting a supported locale that is not enabled for the store (for example, locales=fr-FR in a store without French) now returns 400 Bad Request. Previously, it returned an empty translation for that locale.
  • locales=ALL combined with an unsupported locale (for example, locales=ALL,es-AR) now returns 400 Bad Request. Previously, values after ALL were ignored.
  • An empty locales parameter (for example, locales=) now falls back to the store’s primary locale.
  • Duplicated locales are ignored.

Repeated parameters​

fields, includes and locales can now be repeated, and all their values are combined:

GET /api/v1/products/42?fields=status,model_code&fields=name

Previously, only the last occurrence was taken into account.

What you should check​

If your integration sends fields, includes or locales, make sure that all values are valid for each endpoint, and that you only request locales enabled for the store. Requests that previously returned 200 OK with invalid values will now return 400 Bad Request with a message describing the supported values.

For more details, see:

👉 Field Selection and Response Shape

👉 Localization, Markets and Pricing