Skip to main content

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

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

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.
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
  • Some endpoints may document exceptions or additional nested behaviors