Orders

List orders

Returns a paginated list of orders for your organization. Supports filtering by 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:00",
    "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.00 },
    { "email": "bob@giftronaut.com", "firstName": "Bob", "lastName": "Jones", "amount": 50.00 }
  ],
  "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 — no recipient emails required. You specify how many links to generate and the amount per link; each link becomes a unique URL that your end users can redeem to claim the gift card. This is useful for marketing campaigns, quick-win incentives, in-app rewards, and anywhere email-based delivery does not fit.

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 1 hour before the scheduled send time. Immediate orders cannot be canceled once placed.

Required scope

Error responses

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