> ## Documentation Index
> Fetch the complete documentation index at: https://developer.sodacards.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Purchase input fields

> Discover the fields a product needs, submit them on an order, and handle a product that needs none.

Some products need extra information at purchase time. A game top-up needs the player's account —
for example a player id and a server. A gift card needs nothing. The API tells you which, so you can
build and validate an order line before you place it.

## Discover a product's fields

Read a product (`GET /v1/products/{id}`, or any item from `GET /v1/catalog`). When it needs inputs,
it carries an `inputFields` array. When it needs none, the field is absent.

A top-up product, copied from a real call:

```json theme={null}
{
  "product": {
    "id": "f5baa307-b104-4a08-a6d8-a2b51b4b3292",
    "name": "100 Diamonds",
    "faceValue": { "amount": "100", "currency": "USD" },
    "price": { "amount": "700", "currency": "XOF" },
    "minQuantity": 1,
    "purchasable": true,
    "inputFields": [
      { "key": "player_id", "type": "text", "required": true, "regex": "^[0-9]{6,}$" },
      {
        "key": "server", "type": "select", "required": true,
        "options": [
          { "value": "asia", "label": "Asia" },
          { "value": "asia-1", "label": "Asia Server 1", "parentValue": "asia" }
        ]
      }
    ]
  }
}
```

### Reading a field spec

<ResponseField name="key" type="string">
  The field's machine name. This is the key to use in `inputFields` on the order line.
</ResponseField>

<ResponseField name="type" type="string">
  How to render and validate the value: `text`, `number` or `select`.
</ResponseField>

<ResponseField name="required" type="boolean">
  When `true`, the order line must carry this field with a non-empty value.
</ResponseField>

<ResponseField name="regex" type="string">
  For a `text` or `number` field, a regular expression the value must match. Absent when there is no
  pattern constraint.
</ResponseField>

<ResponseField name="options" type="object[]">
  For a `select` field, the allowed values in display order. Each option has a `value` (what you
  submit), a `label` (for display), and an optional `parentValue`. A `parentValue` gates a cascade:
  the option applies only when the parent field's option of that value is chosen — for example a
  server that belongs to a chosen region.
</ResponseField>

## Submit the fields

Pass `input_fields` on the order line, keyed by each field's `key`. For a `select`, submit the
option's `value`. Copied from a real call:

```bash theme={null}
curl -X POST https://api.sodacards.com/v1/orders \
  -H "X-API-Key: sc_test_..." \
  -H "Idempotency-Key: your-unique-key" \
  -H "Content-Type: application/json" \
  -d '{
    "lines": [
      {
        "product_id": "f5baa307-b104-4a08-a6d8-a2b51b4b3292",
        "quantity": 1,
        "input_fields": { "player_id": "123456", "server": "asia-1" }
      }
    ]
  }'
```

The order is accepted and, in the sandbox, fulfilled at once:

```json theme={null}
{ "order": { "id": "572e24c6-270e-46a0-9b85-edd7eeb5290e", "status": "completed", "total": { "amount": "700", "currency": "XOF" } } }
```

## Validation

The server validates `input_fields` before accepting the order:

* every **required** field must be present and non-empty;
* a value must match its field's **regex** when one is set;
* an **unknown** key is rejected.

A line that fails any of these is refused with `order_rejected` ([see Errors](/errors)). Validate
against the field specs on your side first, so a rejection is the exception, not the flow.

## A product that needs nothing

Most gift cards need no input. Their product has no `inputFields`, and the order line carries only
the product and quantity:

```bash theme={null}
curl -X POST https://api.sodacards.com/v1/orders \
  -H "X-API-Key: sc_test_..." \
  -H "Idempotency-Key: your-unique-key" \
  -H "Content-Type: application/json" \
  -d '{ "lines": [ { "product_id": "a0c4d81e-d668-4dd4-9333-8551cadff904", "quantity": 1 } ] }'
```