Purchase input fields

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:

{
  "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

string

The field’s machine name. This is the key to use in inputFields on the order line.

string

How to render and validate the value: text, number or select.

boolean

When true, the order line must carry this field with a non-empty value.

string

For a text or number field, a regular expression the value must match. Absent when there is no pattern constraint.

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.

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:

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:

{ "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). 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:

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 } ] }'

Get started

Core concepts

Webhooks

Reference

Purchase input fields

Discover a product’s fields

Reading a field spec

Submit the fields

Validation

A product that needs nothing

​Discover a product’s fields

​Reading a field spec

​Submit the fields

​Validation

​A product that needs nothing

Discover a product’s fields

Reading a field spec

Submit the fields

Validation

A product that needs nothing