Choosing a gift

Three things can be sent, and each prices differently. Getting the value rules right is most of the work of integrating.

Products

A single gift card or physical gift. GET /products lists what you can send.

The catalogue is global, except for products restricted to named customers — those appear only for the customers they are restricted to. It is also country-specific: pass country (ISO 3166-1 alpha-2, defaulting to GB) to get the gifts redeemable there, priced for there.

Does it need a value?

Read requiresAmount:

requiresAmount	What to send
false	Omit value. The price is intrinsic — a physical gift, or a digital gift with one denomination.
true	Send a value. Which values are allowed depends on the fields below.

When a value is needed, the product tells you what is acceptable:

• denominations non-empty — the value must be one of these exact amounts. denominationChoices gives the same list pre-formatted for a dropdown, keyed by the canonical numeric value.
• denominations empty — any amount between minAmount and maxAmount is allowed.

GET /products/184

{
  "id": 184,
  "name": "Amazon.co.uk",
  "isDigital": true,
  "currency": "GBP",
  "currencyPrefix": "£",
  "requiresAmount": true,
  "denominations": [],
  "minAmount": 5.00,
  "maxAmount": 500.00,
  "label": "Amazon.co.uk - £5.00–£500.00"
}

Tip

Every product and collection carries a label — the name and its price context, already formatted. If you are building a picker, that is the string to show.

Collections

A set of gifts the recipient chooses from. GET /collections lists yours. Collections are country- and currency-specific, and come in two kinds.

kind	Value
custom	Built for your account at a fixed value. value on the send is ignored.
curated	Global. You choose the value.

For a curated collection, requiresValue is true and:

• allowCustomValue: false — the value must be one of valuePoints.
• allowCustomValue: true — any positive amount is accepted; minValue and maxValue are a hint for your UI, not a limit.

GET /collections/31

{
  "id": 31,
  "name": "Treat yourself",
  "kind": "curated",
  "country": "GB",
  "currency": "GBP",
  "requiresValue": true,
  "allowCustomValue": false,
  "valuePoints": [10.00, 25.00, 50.00, 100.00],
  "minValue": 10.00,
  "maxValue": 100.00
}

Templates

A preset saved in the 1UP web app: the gift, value, country, greeting and expiry, under a name. GET /templates lists them.

Sending one is the simplest call in the API — you supply only who it goes to:

POST /send/template

{
  "templateId": 77,
  "recipients": [{ "email": "aisha@example.com", "name": "Aisha" }]
}

Templates are the right tool when the same gift goes out repeatedly and non-developers should be able to change it. Changing the gift or its value then means editing the template in 1UP, with no deploy on your side.

Currency

A gift carries its own currency; you do not choose one. The order is priced in the gift’s currency, and the funding account you draw from must hold that same currency — see Paying for an order.