Skip to main content
POST
Units. amount is in cents (2500 means $25.00). startDate and endDate are Unix timestamps in milliseconds, sent as numbers.
There is no sandbox. This creates a real program in your account. Nobody is invited until you add people.
  • Check before you retry. This endpoint takes no Idempotency-Key. If a request times out or fails with a 5xx, look for the program with GET /programs before you send it again, or you may create it twice.
  • Card type. An account that isn’t verified for Visa cards gets a gift_card program, whatever you send. The response’s programType says which one you got.
  • Address. Leave out addressId to use your account’s default address (isDefault in GET /addresses). An account that isn’t verified for Visa cards and has no address yet can leave it out too: its programs give gift cards only, which don’t use an address, so Hoppier fills in its own. An account verified for Visa cards needs an address of its own first: save one.
  • Merchants. Look up merchant ids with GET /merchants. Leave out merchantIds to start from your company template’s merchants, as the dashboard does. If the template locks its merchants, you can’t choose them here. A program with no merchants allows every merchant.
  • Invite email. The program gets Hoppier’s standard invite email unless you send inviteEmail: false for none, or your own subject and body. Hoppier sends it only when you add someone with sendEmailAsUsersAreAdded: true. inviteEmailCreated in the response says whether it was saved.
  • Account settings. A custom endDate needs custom end dates turned on for your account, and isFixedAmount: false needs individual amounts turned on. Without them, the request gets 403 feature_not_enabled.
  • Not available here: recurring programs, and a program’s colours and logo. Those come from the dashboard and your company’s program template.

Authorizations

​
Authorization
string
header
required

Send your key in the Authorization header: Authorization: Bearer hk_live.…. The word Bearer is case-sensitive.

Keys are shown once. Treat them like passwords and never put one in code that runs in a browser or an app.

Body

application/json
​
name
string
required

The program's name, as admins and participants see it.

Required string length: 1 - 100
Example:

"Team lunch"

​
programType
enum<string>
required

hoppier_card: a prepaid Visa card. gift_card: each person picks a gift card. An account that isn't verified for Visa cards gets gift_card whatever you send.

Available options:
hoppier_card,
gift_card
​
amount
integer

The amount each person gets, in cents (2500 means $25.00). Required for a fixed-amount program, and at least 100. Leave it out when isFixedAmount is false.

Required range: x >= 0
Example:

2500

​
isFixedAmount
boolean
default:true

false gives each person their own amount, which you set when you add them. Needs individual amounts turned on for your account.

​
currency
enum<string>
default:usd
Available options:
usd
​
addressId
string

One of your company's addresses (ad_…), from GET /addresses. Leave it out to use your account's default address. An account that isn't verified for Visa cards and has no address can leave it out too, and Hoppier fills in its own: that account's programs give gift cards only, which don't use an address.

Example:

"ad_7Ym2p0Lx3Q"

​
startDate
integer

When the program starts, as a Unix timestamp in milliseconds. Defaults to now.

Required range: 1000000000000 <= x <= 4102444800000
Example:

1793491200000

​
endDate
integer

When the program ends, as a Unix timestamp in milliseconds, after startDate. Needs custom end dates turned on for your account. Not with dynamicEndDate.

Required range: 1000000000000 <= x <= 4102444800000
Example:

1795996800000

​
dynamicEndDate
boolean
default:false

true ends each person's card timeFrame days (or hours) after they're added, instead of on one date for everyone.

​
timeFrame
integer

How long each person's card lasts, in period units. Required with dynamicEndDate, and only allowed with it.

Required range: x >= 1
Example:

30

​
period
enum<string>
default:days

The unit of timeFrame.

Available options:
days,
hours
​
merchantIds
integer[]

The merchants the program allows: Visa merchants for a hoppier_card program, gift-card brands for a gift_card program. Look ids up with GET /merchants. Leave it out to start from your company template's merchants.

Required array length: 1 - 100 elements
Required range: x >= 1
​
inviteEmail
default:true

The program's invite email, sent when you add someone with sendEmailAsUsersAreAdded: true. Leave it out (or send true) for Hoppier's standard invite email, send false for none, or send your own. You can change it later in the dashboard.

Response

The new program.

The new program, and whether its invite email was saved.

​
id
string
required

The program's id. Starts with prg_.

Example:

"prg_Z8q3NnW2xK"

​
object
string
required
Allowed value: "program"
​
name
string
required
Example:

"Team lunch"

​
amount
integer
required

The amount each person gets, in cents (2500 means $25.00). 0 on a program where each person has their own amount.

Example:

2500

​
currency
string
required

Lowercase currency code. usd is the only value today.

Example:

"usd"

​
status
enum<string>
required

active: running. inactive: archived. pending: not active yet.

Available options:
active,
inactive,
pending
​
startDate
string
required

When the program starts: a Unix timestamp in milliseconds, as a string. A program with no start date returns the string "undefined", so treat anything that isn't 13 digits as "no start date".

Example:

"1793491200000"

​
createdAt
string
required

Unix milliseconds, as a string.

Example:

"1792504992000"

​
updatedAt
string
required

Unix milliseconds, as a string.

Example:

"1792504992000"

​
isFixedAmount
boolean
required

true: everyone gets the program's amount. false: each person has their own amount, set when they're added.

​
programType
enum<string>
required

hoppier_card: a prepaid Visa card. gift_card: each person picks a gift card. wire_transfer: a money transfer to each person's bank.

Available options:
hoppier_card,
gift_card,
wire_transfer
​
inviteEmailCreated
boolean
required

true when the program's invite email was saved. false when you sent inviteEmail: false, or if saving it failed: then the program still exists, and the first add that asks for the email creates Hoppier's standard one.

​
endDate
string

When the program ends (Unix milliseconds, as a string). Left out when the program has no end date.

Example:

"1795996800000"

​
addressId
string

Id of the program's address, one of your saved addresses. Starts with ad_. Left out when the program's address isn't one of yours, such as the address Hoppier fills in for a gift-card program in an account that hasn't saved one.

Example:

"ad_7Ym2p0Lx3Q"

​
colorHex
string | null

The program's main colour in the Hoppier app.

Example:

"#FF6161"

​
colorHex2
string | null

The program's second colour in the Hoppier app.

Example:

"#FFFFFF"

​
logoUrl
string | null

URL of the program's logo, if it has one.