Field selection and response shape

The OpenTiendas API lets you control which fields are returned for a resource, and which related resources are embedded in the response.

This helps keep responses lightweight, predictable, and consistent across endpoints.

How it works

When querying a resource directly, you can control the response shape using the following query parameters:

fields — selects which fields of the current resource are returned
includes — includes related resources as nested objects

Both parameters accept multiple values separated by commas. You can also repeat the parameter, and all its values are combined:

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

Duplicated values are ignored.

Field selection (`fields`)

Fixed and default fields

All resources expose a fixed set of fields and a default set of fields.

Fixed fields are always included and cannot be excluded.
They uniquely identify the resource and define its structure (for example, id).
Default fields represent the minimal, canonical representation of the resource.
They are returned when the resource is nested, and when the resource is queried without specifying the fields parameter.

Field selection rules

When fields is not specified, the response includes only:
- all fixed fields, and
- the resource’s default fields
When fields is specified, the response includes only:
- all fixed fields, and
- the fields explicitly listed in fields

Valid field names

fields only accepts fields that the resource returns in its responses:

fields of the resource itself (for example, status or model_code for products), and
localized fields, which are requested by name at the same level, without the translations prefix (for example, name or description). See Localization, Markets and Pricing.

Write-only fields (for example, brand_id or category_ids for products) are only accepted in request bodies and cannot be selected with fields.

Related objects such as variants or customer are requested with includes, not with fields.

If fields contains a value that is not a valid field of the resource, the API returns 400 Bad Request, listing the invalid values and the supported fields:

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."
}

Nested objects (`includes`)

Some resources have related nested objects (for example, variants for products, or customer for orders).

To include a nested object, you must explicitly request it using includes query parameter.

Nested objects are never returned by default unless documented otherwise.
Each included object is returned using its own fixed and default fields.

The nested objects available for each resource are listed in its API reference, under Nested objects. If includes contains a value that is not a nested object of the resource, the API returns 400 Bad Request:

GET /api/v1/products?includes=variant

{
  "detail": "Invalid value(s) in 'includes' parameter: variant. Supported values: brand, categories, supplier, variants."
}

Resources without nested objects (for example, brands) reject any value in includes.

note

fields and includes apply to the primary resource of the endpoint being queried, whether the response returns:

a single resource (e.g. GET /api/v1/brands/{id}), or
a collection of resources (e.g. GET /api/v1/brands).

In list endpoints, the rules are applied to each item in the collection.

They do not cascade into nested objects.

Usage examples

The following examples illustrate how to combine fields and includes to control the response shape in real scenarios.

Get an order including line items

For orders, line_items is a field of the order resource. It is not included by default, so you must explicitly request it using fields.

GET /api/v1/orders/1267?fields=created_at,total,line_items

{
  "id": 1267,
  "created_at": "2026-03-18T10:15:22Z",
  "total": {
    "gross": { "amount": "120.00", "currency": "EUR" },
    "net": { "amount": "99.17", "currency": "EUR" },
    "tax": { "amount": "20.83", "currency": "EUR" }
  },
  "line_items": [
    {
      "id": 101,
      "product_id": 2001,
      "variant_id": 3001,
      "sku": "SKU-12345",
      "ean": "8431234567890",
      "display_name": "Wireless Mouse",
      "tax_rate": "0.21",
      "quantity": 2,
      "unit_price": {
        "list_price": {
          "gross": { "amount": "30.00000", "currency": "EUR" }
        },
        "final_price": {
          "gross": { "amount": "28.00000", "currency": "EUR" },
          "net": { "amount": "23.14049", "currency": "EUR" }
        }
      },
      "discounts_applied": [
        {
          "type": "voucher",
          "amount": { "amount": "4.00", "currency": "EUR" },
          "description": "Spring Sale Voucher"
        }
      ],
      "additional_services": [
        {
          "display_name": "Gift Wrapping",
          "internal_id": "GW-001",
          "quantity": 2,
          "unit_price": {
            "gross": { "amount": "2.00000", "currency": "EUR" },
            "net": { "amount": "1.65289", "currency": "EUR" }
          },
          "tax_rate": "0.21"
        }
      ],
      "total": {
        "gross": { "amount": "56.00000", "currency": "EUR" },
        "net": { "amount": "46.28099", "currency": "EUR" },
        "tax": { "amount": "9.71901", "currency": "EUR" }
      }
    }
  ]
}

In this example:

line_items is selected through fields, because it is a field of the order resource.
When fields is specified, the response contains:
- fixed fields (id), and
- only the fields explicitly requested.
In this example, default order fields such as payment_status or delivery_method are omitted because they were not requested.

Get an order with line items and customer

GET /api/v1/orders/1267?fields=created_at,total,line_items&includes=customer

{
  "id": 1267,
  "created_at": "2026-03-18T10:15:22Z",
  "total": {
    "gross": { "amount": "120.00", "currency": "EUR" },
    "net": { "amount": "99.17", "currency": "EUR" },
    "tax": { "amount": "20.83", "currency": "EUR" }
  },
  "line_items": [
    {
      "id": 101,
      "product_id": 2001,
      "variant_id": 3001,
      "sku": "SKU-12345",
      "ean": "8431234567890",
      "display_name": "Wireless Mouse",
      "tax_rate": "0.21",
      "quantity": 2
      [...]
    }
  ],
  "customer": {
    "id": 501,
    "email": "john.smith@example.com",
    "full_name": "John Smith",
    "created_at": "2025-12-01T09:00:00Z",
    "preferred_locale": "es-ES"
  }
}

In this example:

line_items is requested with fields.
customer is a related object and is requested with includes.
The fields parameter does not cascade into customer. The included object follows its own field rules.

Get a product including variants

For products, variants is a related nested resource and must be requested using includes.

GET /api/v1/products/42?includes=variants

{
  "id": 42,
  "internal_id": "urban-shoe",
  "product_structure": "with-variants",
  "status": "published",
  "product_kind": "physical",
  "model_code": "urbn_2026",
  "tax_category": "standard",
  "images": [
    {
      "id": 101,
      "fullsize": "https://media.example.com/product/urban-shoe-1.jpg?width=1200",
      "position": 0
    }
  ],
  "variants_count": 2,
  "translations": {
    "en-GB": {
      "url": "https://shop.example.com/urban-shoe/",
      "name": "Urban Shoe",
      "slug_base": "urban-shoe",
      "slug": "urban-shoe-2026"
    }
  },
  "variants": [
    {
      "id": 201,
      "sku": "urbn-41",
      "ean": "1234567890123",
      "status": "published",
      "available_stock": 12
    },
    {
      "id": 202,
      "sku": "urbn-42",
      "ean": "1234567890124",
      "status": "published",
      "available_stock": 0
    }
  ]
}

In this example:

variants must be explicitly requested via includes.
The product still returns its default fields unless fields is specified.
Each variant follows its own fixed/default fields.

Example with field selection + includes

GET /api/v1/products/42?fields=status,product_structure&includes=variants

{
  "id": 42,
  "status": "published",
  "product_structure": "with-variants",
  "variants": [
    {
      "id": 201,
      "sku": "urbn-41",
      "status": "published",
      "available_stock": 12
    }
  ]
}

In this example:

Product fields are reduced to only those explicitly requested.
variants are still included using their default representation.

Combining multiple includes

You can request multiple related resources:

GET /api/v1/products/42?includes=variants,brand,categories

Each included resource:

is independent
follows its own fixed + default fields
does not inherit the parent fields parameter

Best practices

Use fields to reduce payload size when you only need a subset of fields
Use includes only for related resources you actually need
Do not assume nested objects will contain all available fields unless explicitly documented

Additional considerations

Fixed fields are always returned, even when fields is specified
Included resources do not inherit the parent resource’s fields parameter
Invalid values in fields or includes return 400 Bad Request. In write requests (POST, PATCH), they are validated before any change is applied, so a request with invalid values does not modify any data
Some endpoints may document exceptions or additional nested behaviors

How it works​

Field selection (fields)​

Fixed and default fields​

Field selection rules​

Valid field names​

Nested objects (includes)​

Usage examples​

Get an order including line items​

Get an order with line items and customer​

Get a product including variants​

Example with field selection + includes​

Combining multiple includes​

Best practices​

Additional considerations​

How it works

Field selection (`fields`)

Fixed and default fields

Field selection rules

Valid field names

Nested objects (`includes`)

Usage examples

Get an order including line items

Get an order with line items and customer

Get a product including variants

Example with field selection + includes

Combining multiple includes

Best practices

Additional considerations