Orders

List orders

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

orderType: ONE_TIME · SMART · LINK · CAMPAIGN · REWARD — cardType: BRANDED_CARD · CHOICE_CARD

Client order reference for looking up and tracking orders: filter with clientOrderId. Similarly, you can pull individual orders using either your client order reference, or the order ID provided by Giftronaut.

View order history and balance ledger: orders here, ledger in the Balance API.

Required scope

Query parameters

Get order

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

Required scope

Path parameters

Response fields — recipients

LINK: This will return the reward link in recipients[].rewardLink once the order is complete. The GET /api/v1/orders/{orderId} response for a completed reward link order includes each link in recipients[].rewardLink.

Giftronaut order ID · Recipient email and reward link

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.

Each recipient in a Giftronaut order can receive a different amount. Attach your own client order reference to orders through idempotencyKey for internal tracking (e.g., transaction number or campaign name).

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.
• The total cost of an order is the sum of all recipient amounts converted to USD.
• 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

When refundOption is set to true, the following expiration and refund policies apply based on refundOptionDays (30 / 60 / 90). Omitting refundOptionDays with refundOption: true defaults to 30 days (50% refund).

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

When refundOption is set to true, the following expiration and refund policies apply based on refundOptionDays (30 / 60 / 90). Omitting refundOptionDays with refundOption: true defaults to 30 days (50% refund).

Create reward link order

A Giftronaut reward link order generates up to 500 unique gift card links in a single request. 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.

The API returns a unique reward link for each gift card. Your system delivers the reward link however you want: Slack, QR codes, SMS, in-app UI, CRM campaigns, or lead capture forms. Reward links should be treated as secrets.

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

When refundOption is set to true, the following expiration and refund policies apply based on refundOptionDays (30 / 60 / 90). Omitting refundOptionDays with refundOption: true defaults to 30 days (50% refund).

Cancel order

Giftronaut cancels only scheduled orders, and only at least 10 minutes before the send time. Immediate orders and reward link orders cannot be canceled. Once a Giftronaut order is sent, it cannot be canceled, returned, or exchanged.

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. 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.

Increased daily and monthly order limits can be requested through the API and are typically approved within 1–2 business days.

Required scope

Request body

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

Response