Orders

List orders

Returns a paginated list of orders for your organization. Supports filtering by order type, status, card type, and date range.

Required scope

Query parameters

Get order

Retrieves the full details of a single order by its ID.

Required scope

Path parameters

Response fields — recipients

Each entry in recipients represents a single gift card issuance. Most fields are self-describing; two are order-type dependent:

Create branded card order

Places a branded gift card order. Each recipient can receive a different amount in the product's local currency. Supports immediate and scheduled delivery.

Required scope

Request body

{
  "idempotencyKey": "order-unique-key-001",
  "productId": "10042",
  "sendTiming": {
    "type": "SCHEDULED",
    "scheduledAt": "2024-03-01T09:00:00Z",
    "timezone": "America/New_York"
  },
  "emailSetting": {
    "senderName": "Giftronaut",
    "subject": "A gift for you!",
    "message": "Thank you for your hard work.",
    "templateId": "12"
  },
  "recipients": [
    { "email": "alice@giftronaut.com", "firstName": "Alice", "lastName": "Smith", "company": "Giftronaut", "department": "Engineering", "amount": 50 },
    { "email": "bob@giftronaut.com", "firstName": "Bob", "lastName": "Jones", "amount": 50 }
  ],
  "refundOption": false
}

Request body fields

Business rules

• For SCHEDULED, both scheduledAt and timezone are required. For IMMEDIATE, neither may be provided.
• Account balance must cover the sum of all recipient amounts converted to USD.
• Each recipient's amount must match a valid price point for the selected product.

Refund Option

If the refundOption value is set to true, the following expiration and refund policies apply.

Create choice card order

Places a choice card order where each recipient selects their own gift from a curated collection. Each recipient can receive a different balance amount.

Required scope

Request body

{
  "idempotencyKey": "order-choice-unique-001",
  "productId": "55",
  "sendTiming": {
    "type": "IMMEDIATE"
  },
  "emailSetting": {
    "senderName": "Giftronaut",
    "subject": "Choose your gift!",
    "message": "We appreciate everything you do.",
    "templateId": "12"
  },
  "recipients": [
    { "email": "alice@giftronaut.com", "firstName": "Alice", "lastName": "Smith", "amount": 100.00 },
    { "email": "bob@giftronaut.com", "firstName": "Bob", "lastName": "Jones", "amount": 50.00, "company": "Giftronaut", "department": "Sales" }
  ],
  "refundOption": false
}

Request body fields

Business rules

• Every recipient must include a positive amount.
• Account balance must cover the sum of all recipient amounts.
• Each recipient's amount must fall within the range configured for your organization (see catalog choice cards).

Refund Option

If the refundOption value is set to true, the following expiration and refund policies apply.

Create reward link order

Creates a batch of redeemable gift card links without requiring recipient email addresses. You specify how many links to generate and the amount per link; each link is a unique URL that end users can use to redeem a gift card. This is useful for marketing campaigns, quick-win incentives, in-app rewards, and other use cases where email-based delivery is not suitable.

Required scope

Request body

{
  "idempotencyKey": "reward-link-unique-001",
  "cardType": "BRANDED_CARD",
  "productId": "101",
  "quantity": 50,
  "amountPerLink": 25.00,
  "refundOption": false
}

Request body fields

Response

On success, returns HTTP 201 with the newly created order summary. The orderId returned here is the one used for polling via Get order. totalCost is always in USD and equals amountPerLink × quantity converted at the product's current exchange rate (for branded cards) or 1:1 (for choice cards).

Business rules

• Account balance must cover totalCost in USD at request time — the full amount is deducted immediately.
• For branded cards, amountPerLink must match an allowed price step of the product.
• For choice cards, amountPerLink must be within the organization's configured min / max range.
• quantity is capped at 500 per request. For larger batches, submit multiple requests with distinct idempotency keys.
• Individual links appear in the recipients[].rewardLink field of Get order only after the order reaches status: "COMPLETE".

Refund Option

If the refundOption value is set to true, the following expiration and refund policies apply.

Cancel order

Cancels a scheduled order. The request must be made at least 10 minutes before the scheduled send time. Immediate orders cannot be canceled once placed. The held balance is refunded to your account immediately.

Required scope

Error responses

Response

Resend order

Resends gift cards to specific recipients. Optionally update a recipient's email address before resending.

Required scope

Request body

{
  "recipients": [
    {
      "email": "jane.doe@giftronaut.com",
      "updatedEmail": "newemail@giftronaut.com"
    }
  ]
}

Response

Send test email (preview)

Sends a preview of the choice-card gift email to an address you control — rendered with the exact same layout as the real delivery email, including a working redeem button that opens a live preview of the redeem page (issued under Giftronaut's internal demo account). Your balance is never charged and nothing appears in your order history. Personalization variables such as {{First Name}} render as placeholder text. A daily limit applies (default 10 per day). Choice cards only.

Required scope

Request body

Response

Request order limit increase

Submit a request to raise your organization's daily and monthly order spending limits (USD). The request is not applied immediately — it is queued for review and you'll be notified once approved (typically within 1–2 business days). Send the daily and monthly limits you currently see as a confirmation check: if they don't match our records, the request is rejected with 409 STALE_LIMIT_SNAPSHOT so you can refresh and retry.

Required scope

Request body

{
  "currentDailyLimitUsd": 500,
  "currentMonthlyLimitUsd": 4000,
  "requestedDailyLimitUsd": 1000,
  "requestedMonthlyLimitUsd": 8000
}

Response