Sign in
API Reference

Campaigns

Campaigns are reusable gift card sending templates. Define a product, amount, sender details, and email design once, then execute the campaign repeatedly with different recipient lists — without repeating the configuration each time.

GET /api/v1/campaigns

List campaigns

Returns a paginated list of campaigns for your organization.

Required scope

campaigns.read

Query parameters

Parameter
Type
Required
Description
search
string
No
Filter by campaign name
page
integer
No
Page number, default 1
pageSize
integer
No
Results per page, default 20, max 100
GET /api/v1/campaigns/{campaignId}

Get campaign

Retrieves full details of a single campaign.

Required scope

campaigns.read

Path parameters

Parameter
Type
Required
Description
campaignId
string
Yes
The campaign ID (e.g. CA-A1B2C3D4)
POST /api/v1/campaigns

Create campaign

Creates a new campaign template. All sending configuration is set here; individual executions can override subject, senderName, and message.

Required scope

campaigns.write
Banner image — The email banner image is fixed to the default Giftronaut logo for security reasons. To use a custom banner, update the template in the Giftronaut Portal ↗.

Request body

JSON
{
  "name": "Q1 Employee Appreciation",
  "cardType": "BRANDED_CARD",
  "productId": "10042",
  "amount": 50.00,
  "subject": "A gift for you from Acme Corp",
  "senderName": "Acme Corp",
  "message": "Thank you for your hard work!",
  "templateId": "12",
  "refundOption": false
}

Request fields

Field
Type
Required
Description
name
string
Yes
Display name for this campaign
cardType
string
Yes
BRANDED_CARD | CHOICE_CARD
productId
string
Yes
Product ID from Catalog
amount
number
Yes
Gift card value in USD
subject
string
Yes
Email subject line
senderName
string
Yes
Sender display name shown to recipients
message
string
No
Personal message included in the gift email
templateId
string
No
Email template ID from Templates
refundOption
boolean
No
Allow recipients to request a refund. Default false
PUT /api/v1/campaigns/{campaignId}

Update campaign

Replaces all fields of an existing campaign. All required fields must be provided.

Required scope

campaigns.write

Path parameters

campaignId
string
Yes
The campaign ID to update

Request body

JSON
{
  "name": "Q1 Employee Appreciation",
  "cardType": "BRANDED_CARD",
  "productId": "10042",
  "amount": 75.00,
  "subject": "A gift for you from Acme Corp",
  "senderName": "Acme Corp",
  "message": "Thank you for your hard work!",
  "templateId": "12",
  "refundOption": false
}

All fields follow the same rules as Create campaign. All required fields must be provided.

DELETE /api/v1/campaigns/{campaignId}

Delete campaign

Soft-deletes a campaign. The campaign will no longer appear in list results and cannot be executed, but historical order data is preserved.

Required scope

campaigns.write

Path parameters

campaignId
string
Yes
The campaign ID to delete
POST /api/v1/campaigns/{campaignId}/orders

Execute campaign order

Sends gift cards to a list of recipients using the campaign's preset configuration. Optionally override subject, senderName, or message for this specific send.

Required scopes

campaigns.write orders.write

Path parameters

campaignId
string
Yes
The campaign ID to execute

Request body

JSON
{
  "recipients": [
    { "email": "alice@giftronaut.com", "firstName": "Alice", "lastName": "Smith" },
    { "email": "bob@giftronaut.com", "firstName": "Bob", "lastName": "Jones" }
  ],
  "idempotencyKey": "campaign-exec-unique-001",
  "senderName": "HR Team",
  "subject": "Your Q1 reward is here",
  "message": "Congratulations on a great quarter!"
}

Request fields

Field
Type
Required
Description
recipients
array
Yes*
List of recipient objects. Required if recipientGroupId is omitted
recipientGroupId
string
Yes*
Send to all members of a saved recipient group
idempotencyKey
string
Yes
Client-generated unique key (max 64 chars). Duplicate requests with the same key return the original order.
senderName
string
No
Overrides campaign's senderName (max 100 chars)
subject
string
No
Overrides campaign's subject (max 200 chars)
message
string
No
Overrides campaign's message (max 2000 chars)

Business rules

  • Provide either recipients or recipientGroupId — not both.
  • Account balance must cover campaign.amount × recipientCount.
  • Campaign orders are always sent immediately (no scheduling).