Guides — Giftronaut API

Base URL

https://api.giftronaut.com/api/v1

Both Sandbox and Production use the same URL. The environment is determined by your credentials. See Sandbox vs Production for details.

Required headers

Header	Value	Required
`Authorization`	`Bearer {access_token}`	Yes
`Content-Type`	`application/json`	For POST/PUT/PATCH
`X-Request-Id`	UUID v4	Recommended

Request example

POST /api/v1/orders/branded-cards
Authorization: Bearer eyJhbGci...
Content-Type: application/json
X-Request-Id: 550e8400-e29b-41d4-a716-446655440000

{
  "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
  "productId": "10042",
  "sendTiming": { "type": "IMMEDIATE" },
  "emailSetting": {
    "senderName": "Giftronaut Rewards",
    "subject": "Your gift has arrived!",
    "message": "Thank you for your contribution."
  },
  "recipients": [
    { "email": "alice@giftronaut.com", "firstName": "Alice", "lastName": "Kim", "amount": 50 }
  ]
}

Response example

Successful responses wrap the resource in a top-level data object:

{
  "data": {
    "orderId": "OT-20260315-A8F2",
    "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
    "totalCost": { "amount": 50, "currency": "USD" },
    "recipientCount": 1,
    "sendTiming": { "type": "IMMEDIATE", "scheduled": null },
    "createdAt": "2026-03-15T09:30:00Z",
    "recipients": [
      {
        "email": "alice@giftronaut.com",
        "amount": { "amount": 50, "currency": "USD" },
        "cost": { "amount": 50, "currency": "USD" }
      }
    ]
  }
}

Correlation ID

If you include X-Request-Id, it is echoed back in every response. This makes it easy to trace a specific request in logs or support tickets.