Send a collection
const url = 'https://api.1up.gift/send/collection';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"collectionId":1,"value":1,"source":"example","recipients":[{"email":"example","name":"example","quantity":1}],"codeQuantity":1,"wrappingKey":"example","fromName":"example","message":"example","sendAt":"2026-04-15T12:00:00Z","accountId":1,"expiryAfterDays":1,"externalReference":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.1up.gift/send/collection \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "collectionId": 1, "value": 1, "source": "example", "recipients": [ { "email": "example", "name": "example", "quantity": 1 } ], "codeQuantity": 1, "wrappingKey": "example", "fromName": "example", "message": "example", "sendAt": "2026-04-15T12:00:00Z", "accountId": 1, "expiryAfterDays": 1, "externalReference": "example" }'Places an order against a collection, letting each recipient pick their own gift from it. The
collection’s own country and currency apply. Delivery, idempotency and funding work exactly as they
do for POST /send/gift.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”Send a collection, letting each recipient choose their own gift from it.
object
The collection to send, from GET /collections.
The per-recipient face value. Curated collections only; ignored for custom collections.
Where this order came from, for your own reporting — for example zapier. Optional; defaults
to api. Normalised to a short lower-case token.
Who receives the gift. Each recipient is emailed their code. Mutually exclusive with
codeQuantity.
One recipient of a send. Each recipient produces quantity codes, each its own order line, and is
emailed their code or codes.
object
The address the gift is emailed to.
The recipient’s name, used to address the gift. Optional.
How many codes this recipient gets, 1–1000. Defaults to 1.
How many anonymous codes to generate, 1–5000. Nothing is emailed and no recipients are recorded.
Mutually exclusive with recipients.
The gift wrapping — the box colours and emoji the recipient sees. Defaults to default. A
template send falls back to the template’s wrapping when this is omitted.
Who the gift is from, as shown to the recipient. At most 32 characters.
A personal message shown with the gift. At most 256 characters.
When to deliver, as an absolute UTC instant. Omit to send immediately. Must be in the future when supplied, and is ignored for a code batch, which is always generated straight away.
The account to fund the order from, from GET /funding-accounts, in the order’s currency.
Required if you pay for orders from a balance you top up. Omit it if you’re invoiced for orders
instead.
Days after claiming that gifts expire. Enterprise plans only; ignored on every other plan, which use the default expiry policy.
An idempotency key from your own system, at most 128 characters. When supplied it is stamped on the order and must be unique for your customer: reusing a value — whatever else the request carries — is rejected with 409 Conflict, so a retried request cannot place the same gift twice. Omit it, or send blank, to opt out. It is echoed back on the response.
Examplegenerated
{ "collectionId": 1, "value": 1, "source": "example", "recipients": [ { "email": "example", "name": "example", "quantity": 1 } ], "codeQuantity": 1, "wrappingKey": "example", "fromName": "example", "message": "example", "sendAt": "2026-04-15T12:00:00Z", "accountId": 1, "expiryAfterDays": 1, "externalReference": "example"}Send a collection, letting each recipient choose their own gift from it.
object
The collection to send, from GET /collections.
The per-recipient face value. Curated collections only; ignored for custom collections.
Where this order came from, for your own reporting — for example zapier. Optional; defaults
to api. Normalised to a short lower-case token.
Who receives the gift. Each recipient is emailed their code. Mutually exclusive with
codeQuantity.
One recipient of a send. Each recipient produces quantity codes, each its own order line, and is
emailed their code or codes.
object
The address the gift is emailed to.
The recipient’s name, used to address the gift. Optional.
How many codes this recipient gets, 1–1000. Defaults to 1.
How many anonymous codes to generate, 1–5000. Nothing is emailed and no recipients are recorded.
Mutually exclusive with recipients.
The gift wrapping — the box colours and emoji the recipient sees. Defaults to default. A
template send falls back to the template’s wrapping when this is omitted.
Who the gift is from, as shown to the recipient. At most 32 characters.
A personal message shown with the gift. At most 256 characters.
When to deliver, as an absolute UTC instant. Omit to send immediately. Must be in the future when supplied, and is ignored for a code batch, which is always generated straight away.
The account to fund the order from, from GET /funding-accounts, in the order’s currency.
Required if you pay for orders from a balance you top up. Omit it if you’re invoiced for orders
instead.
Days after claiming that gifts expire. Enterprise plans only; ignored on every other plan, which use the default expiry policy.
An idempotency key from your own system, at most 128 characters. When supplied it is stamped on the order and must be unique for your customer: reusing a value — whatever else the request carries — is rejected with 409 Conflict, so a retried request cannot place the same gift twice. Omit it, or send blank, to opt out. It is echoed back on the response.
Examplegenerated
{ "collectionId": 1, "value": 1, "source": "example", "recipients": [ { "email": "example", "name": "example", "quantity": 1 } ], "codeQuantity": 1, "wrappingKey": "example", "fromName": "example", "message": "example", "sendAt": "2026-04-15T12:00:00Z", "accountId": 1, "expiryAfterDays": 1, "externalReference": "example"}Send a collection, letting each recipient choose their own gift from it.
object
The collection to send, from GET /collections.
The per-recipient face value. Curated collections only; ignored for custom collections.
Where this order came from, for your own reporting — for example zapier. Optional; defaults
to api. Normalised to a short lower-case token.
Who receives the gift. Each recipient is emailed their code. Mutually exclusive with
codeQuantity.
One recipient of a send. Each recipient produces quantity codes, each its own order line, and is
emailed their code or codes.
object
The address the gift is emailed to.
The recipient’s name, used to address the gift. Optional.
How many codes this recipient gets, 1–1000. Defaults to 1.
How many anonymous codes to generate, 1–5000. Nothing is emailed and no recipients are recorded.
Mutually exclusive with recipients.
The gift wrapping — the box colours and emoji the recipient sees. Defaults to default. A
template send falls back to the template’s wrapping when this is omitted.
Who the gift is from, as shown to the recipient. At most 32 characters.
A personal message shown with the gift. At most 256 characters.
When to deliver, as an absolute UTC instant. Omit to send immediately. Must be in the future when supplied, and is ignored for a code batch, which is always generated straight away.
The account to fund the order from, from GET /funding-accounts, in the order’s currency.
Required if you pay for orders from a balance you top up. Omit it if you’re invoiced for orders
instead.
Days after claiming that gifts expire. Enterprise plans only; ignored on every other plan, which use the default expiry policy.
An idempotency key from your own system, at most 128 characters. When supplied it is stamped on the order and must be unique for your customer: reusing a value — whatever else the request carries — is rejected with 409 Conflict, so a retried request cannot place the same gift twice. Omit it, or send blank, to opt out. It is echoed back on the response.
Examplegenerated
{ "collectionId": 1, "value": 1, "source": "example", "recipients": [ { "email": "example", "name": "example", "quantity": 1 } ], "codeQuantity": 1, "wrappingKey": "example", "fromName": "example", "message": "example", "sendAt": "2026-04-15T12:00:00Z", "accountId": 1, "expiryAfterDays": 1, "externalReference": "example"}Responses
Section titled “Responses”The order was placed and the codes issued.
A placed order. All three send endpoints return this shape.
object
The order’s public reference — an opaque, non-sequential key used to identify it everywhere else.
gift for a single product, or gifts for a collection.
The per-code face value.
The ISO code of the currency the order is priced in — the gift’s own currency.
How many codes were issued.
How many distinct recipients the codes went to. Zero for a code batch.
What the order cost you, in the order’s currency.
send when recipients were notified, or manual for an anonymous code batch.
When the send is scheduled to go out, or null when it went immediately.
The idempotency key you stamped on this order, echoed back, or null if you sent none.
The issued codes. Returned for a code batch; empty when recipients were emailed directly.
One issued gift code.
object
The code the recipient enters to claim their gift.
The PIN that goes with the code.
A ready-to-share link that opens the claim page for this code.
A placed order. All three send endpoints return this shape.
object
The order’s public reference — an opaque, non-sequential key used to identify it everywhere else.
gift for a single product, or gifts for a collection.
The per-code face value.
The ISO code of the currency the order is priced in — the gift’s own currency.
How many codes were issued.
How many distinct recipients the codes went to. Zero for a code batch.
What the order cost you, in the order’s currency.
send when recipients were notified, or manual for an anonymous code batch.
When the send is scheduled to go out, or null when it went immediately.
The idempotency key you stamped on this order, echoed back, or null if you sent none.
The issued codes. Returned for a code batch; empty when recipients were emailed directly.
One issued gift code.
object
The code the recipient enters to claim their gift.
The PIN that goes with the code.
A ready-to-share link that opens the claim page for this code.
Examplegenerated
{ "reference": "example", "giftSelectionType": "example", "value": 1, "currency": "example", "codeCount": 1, "recipientCount": 1, "totalCost": 1, "deliveryMode": "example", "scheduledFor": "2026-04-15T12:00:00Z", "externalReference": "example", "codes": [ { "code": "example", "pin": "example", "redemptionUrl": "example" } ]}A placed order. All three send endpoints return this shape.
object
The order’s public reference — an opaque, non-sequential key used to identify it everywhere else.
gift for a single product, or gifts for a collection.
The per-code face value.
The ISO code of the currency the order is priced in — the gift’s own currency.
How many codes were issued.
How many distinct recipients the codes went to. Zero for a code batch.
What the order cost you, in the order’s currency.
send when recipients were notified, or manual for an anonymous code batch.
When the send is scheduled to go out, or null when it went immediately.
The idempotency key you stamped on this order, echoed back, or null if you sent none.
The issued codes. Returned for a code batch; empty when recipients were emailed directly.
One issued gift code.
object
The code the recipient enters to claim their gift.
The PIN that goes with the code.
A ready-to-share link that opens the claim page for this code.
Examplegenerated
{ "reference": "example", "giftSelectionType": "example", "value": 1, "currency": "example", "codeCount": 1, "recipientCount": 1, "totalCost": 1, "deliveryMode": "example", "scheduledFor": "2026-04-15T12:00:00Z", "externalReference": "example", "codes": [ { "code": "example", "pin": "example", "redemptionUrl": "example" } ]}The request is invalid — see the error field.
object
object
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example"}object
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example"}The funding account has insufficient balance.
object
object
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example"}object
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example"}The externalReference has already been used on another order.
object
object
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example"}object
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example"}