Quickstart

Four calls take you from a fresh API key to a gift landing in someone’s inbox.

1. Check your key works

   GET /me tells you which customer the key belongs to, which service account it acts as, and which environment it is valid in. If this works, everything else will.

   curl

   curl https://api.1up.gift/me \
     -H "Authorization: Bearer $API_KEY"

   Node

   const res = await fetch('https://api.1up.gift/me', {
     headers: { Authorization: `Bearer ${process.env.API_KEY}` },
   })
   
   console.log(await res.json())

   C#

   using var http = new HttpClient { BaseAddress = new Uri("https://api.1up.gift") };
   http.DefaultRequestHeaders.Authorization =
       new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("API_KEY"));
   
   var me = await http.GetFromJsonAsync<JsonElement>("/me");

   Response

   {
     "customerId": 412,
     "customerName": "Northwind Ltd",
     "serviceAccountId": 9031,
     "serviceAccountName": "Zapier integration",
     "environment": "production"
   }

2. Find something to send

   GET /products lists the gifts available to you. The fields you care about are id, which you send, and requiresAmount, which tells you whether you must choose a value.

   curl "https://api.1up.gift/products?country=GB&keyword=amazon" \
     -H "Authorization: Bearer $API_KEY"

   Response (trimmed)

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

3. Choose how to pay

   If you pay for orders from a balance you top up, every send names the account to pay from. GET /funding-accounts lists the accounts your key can use; pick one in the gift’s currency and keep its id. If you’re invoiced for orders instead, skip this step and leave accountId out of the send.

   curl https://api.1up.gift/funding-accounts \
     -H "Authorization: Bearer $API_KEY"

   Response

   [
     {
       "id": 5,
       "name": "Master float",
       "isMaster": true,
       "currency": "GBP",
       "balance": 12400.00,
       "label": "Master float (master float) (GBP): £12400.00"
     }
   ]

4. Send it

   POST /send/gift places the order, issues a code per recipient and emails each of them.

   curl

   curl -X POST https://api.1up.gift/send/gift \
     -H "Authorization: Bearer $API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "productId": 184,
       "value": 25.00,
       "country": "GB",
       "accountId": 5,
       "fromName": "The Northwind team",
       "message": "Thanks for a great quarter.",
       "externalReference": "q4-bonus-2026-aisha",
       "recipients": [
         { "email": "aisha@example.com", "name": "Aisha" }
       ]
     }'

   Node

   const res = await fetch('https://api.1up.gift/send/gift', {
     method: 'POST',
     headers: {
       Authorization: `Bearer ${process.env.API_KEY}`,
       'Content-Type': 'application/json',
     },
     body: JSON.stringify({
       productId: 184,
       value: 25.0,
       country: 'GB',
       accountId: 5,
       fromName: 'The Northwind team',
       message: 'Thanks for a great quarter.',
       externalReference: 'q4-bonus-2026-aisha',
       recipients: [{ email: 'aisha@example.com', name: 'Aisha' }],
     }),
   })
   
   const order = await res.json()

   C#

   var response = await http.PostAsJsonAsync("/send/gift", new
   {
       productId = 184,
       value = 25.00m,
       country = "GB",
       accountId = 5,
       fromName = "The Northwind team",
       message = "Thanks for a great quarter.",
       externalReference = "q4-bonus-2026-aisha",
       recipients = new[] { new { email = "aisha@example.com", name = "Aisha" } }
   });

   Response

   {
     "reference": "8KQ2-WRMT-9P4D",
     "giftSelectionType": "gift",
     "value": 25.00,
     "currency": "GBP",
     "codeCount": 1,
     "recipientCount": 1,
     "totalCost": 25.00,
     "deliveryMode": "send",
     "scheduledFor": null,
     "externalReference": "q4-bonus-2026-aisha",
     "codes": []
   }

Always send an externalReference

It is an idempotency key. If your request times out and you retry it, the duplicate is rejected with 409 Conflict rather than sending a second gift. See Idempotency.

Where to next

• Authentication — getting and rotating a key
• Sending gifts — recipients, code batches and scheduling
• Paying for an order — which account the money comes from
• Webhooks — have orders pushed to you