Sign in
API Reference

Orders

Place gift card orders, retrieve order history, cancel scheduled orders, and resend to recipients.

GET /api/v1/orders

List orders

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

Required scope

orders.read

Query parameters

Parameter
Type
Required
Description
page
integer
No
Page number, default 1
pageSize
integer
No
Results per page, default 20, max 100
orderType
string
No
ONE_TIME | SMART | LINK
cardType
string
No
BRANDED_CARD | CHOICE_CARD
status
string
No
PENDING | IN_PROGRESS | COMPLETE | CANCELED
startDate
string
No
ISO-8601 date, e.g. 2024-01-01
endDate
string
No
ISO-8601 date, e.g. 2024-12-31
searchKeyword
string
No
Search by card name or creator
GET /api/v1/orders/{orderId}

Get order

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

Required scope

orders.read

Path parameters

orderId
string
Yes
The order ID
POST /api/v1/orders/branded-cards

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

orders.write

Request body

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

Request body fields

Field
Type
Required
Description
idempotencyKey
string
Yes
Client-generated unique key (max 64 chars). Duplicate requests with the same key return the original order.
productId
string
Yes
Branded card product ID from the catalog API
sendTiming
object
Yes
Controls when the gift cards are delivered to recipients
sendTiming.type
string
Yes
IMMEDIATE | SCHEDULED
sendTiming.scheduledAt
string
SCHEDULED only
ISO-8601 datetime, e.g. 2024-03-01T09:00:00
sendTiming.timezone
string
SCHEDULED only
IANA timezone, e.g. America/New_York
emailSetting
object
Yes
Customizes the gift email sent to recipients.
emailSetting.senderName
string
Yes
Display name shown in the email From header
emailSetting.subject
string
Yes
Email subject line
emailSetting.message
string
No
Personal message included in the gift email
emailSetting.templateId
string
No
Email template ID. Falls back to the organization's default template.
recipients
array
Yes
One or more recipient objects (see below)
recipients[].email
string
Yes
Recipient email address
recipients[].amount
number
Yes
Per-recipient card value in the product's local currency (e.g. JPY for Japanese cards)
recipients[].firstName
string
No
Recipient first name
recipients[].lastName
string
No
Recipient last name
recipients[].company
string
No
Recipient company
recipients[].department
string
No
Recipient department
refundOption
boolean
No
false (default) = 180-day expiry; true = 30-day expiry

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.

Giftronaut Refund Option — 30 Day Expiration
Enhance your campaign ROI by setting the expiration period to 30 days and receiving 70% of unredeemed funds upon expiration. Ideal for consumer promotions and campaigns.
How It Works
Giftronaut returns 70% of unredeemed funds to your account upon expiration.
Example: If a $100 gift card expires unredeemed, $70 will be credited back to your account.
POST /api/v1/orders/choice-cards

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

orders.write

Request body

JSON
{
  "idempotencyKey": "order-choice-unique-001",
  "productId": "55",
  "sendTiming": {
    "type": "IMMEDIATE"
  },
  "emailSetting": {
    "senderName": "Acme Corp",
    "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": "Acme", "department": "Sales" }
  ],
  "refundOption": false
}

Request body fields

Field
Type
Required
Description
idempotencyKey
string
Yes
Client-generated unique key (max 64 chars). Duplicate requests with the same key return the original order.
productId
string
Yes
Choice card design ID from the catalog API
sendTiming
object
Yes
Controls when the gift cards are delivered to recipients
sendTiming.type
string
Yes
IMMEDIATE | SCHEDULED
sendTiming.scheduledAt
string
SCHEDULED only
ISO-8601 datetime
sendTiming.timezone
string
SCHEDULED only
IANA timezone
emailSetting
object
Yes
Customizes the gift email sent to recipients.
emailSetting.senderName
string
Yes
Display name shown in the email From header
emailSetting.subject
string
Yes
Email subject line
emailSetting.message
string
No
Personal message included in the gift email
emailSetting.templateId
string
No
Email template ID. Falls back to the organization's default template.
recipients
array
Yes
One or more recipient objects; each specifies their own balance amount
recipients[].email
string
Yes
Recipient email address
recipients[].amount
number
Yes
Balance loaded onto this recipient's choice card (must be positive)
recipients[].firstName
string
No
Recipient first name
recipients[].lastName
string
No
Recipient last name
recipients[].company
string
No
Recipient company
recipients[].department
string
No
Recipient department
refundOption
boolean
No
false (default) = 180-day expiry; true = 30-day expiry

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.

Giftronaut Refund Option — 30 Day Expiration
Enhance your campaign ROI by setting the expiration period to 30 days and receiving 70% of unredeemed funds upon expiration. Ideal for consumer promotions and campaigns.
How It Works
Giftronaut returns 70% of unredeemed funds to your account upon expiration.
Example: If a $100 gift card expires unredeemed, $70 will be credited back to your account.
DELETE /api/v1/orders/{orderId}/cancel

Cancel order

Cancels a scheduled order. The request must be made at least 1 hour before the scheduled send time. Immediate orders cannot be canceled once placed.

Required scope

orders.cancel

Error responses

409
ORDER_NOT_CANCELABLE — order is not scheduled, already dispatched, or the 1-hour window has passed.
POST /api/v1/orders/{orderId}/resend

Resend order

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

Required scope

orders.write

Request body

Field
Type
Required
Description
recipients
array
required
List of recipients to resend to.
recipients[].email
string
required
Email address of the recipient to resend to.
recipients[].updatedEmail
string
optional
New email address to use instead. If provided, the gift card is sent to this address.
JSON
{
  "recipients": [
    {
      "email": "jane.doe@giftronaut.com",
      "updatedEmail": "newemail@giftronaut.com"
    }
  ]
}

Response

Field
Type
Description
orderId
string
The order ID that was requeued.
requeued
integer
Number of recipients successfully requeued for resend.