Skip to main content
Version: 2026-05

Get a gift request

GET /gift_requests/{id}

Description​

Retrieves a single gift request by its id. The response is a single JSON object you get back from Create a gift request: the gift request's own fields, with its owned associations (the recipient, the shipping_address, the offering, and the line_items) returned inline rather than as references you have to fetch separately. The campaign and the sender come back as small summaries, enough to label the gift request and to fetch the full record when you need more.

When to use​

Reach for this endpoint to read a gift request back after you've created it, to follow its status as the gift is redeemed and delivered, or to pick up the redemption_url to pass on to the recipient. To stop a gift the recipient hasn't redeemed yet, use Cancel a gift request.

To create a gift request in the first place, use Create a gift request. To discover which campaigns are available, browse Campaigns.

Parameters​

Path​

id (string · uuid · required) is the gift request to retrieve. An id that doesn't match a gift request in your account returns 404.

Headers​

AndOpen-API-Version (string · required) is the API version this request targets. Always send 2026-05. Requests authenticate with a bearer token; see Authentication for how to present it and Environments for the regional base URL to send it to.

Worked examples​

A read is a plain GET by id, with no request body. The JavaScript, Python, and Ruby versions fetch the gift request and read a couple of fields off it; swap in the id you're interested in.

curl -X GET https://api.andopen.co/gift_requests/4fb4cb3f-9666-43b5-8884-7f5194483d1a \
-H "Authorization: Bearer <api_key>" \
-H "AndOpen-API-Version: 2026-05"

Response shape​

A successful call returns 200 OK with the gift request as a flat top-level JSON object: the same shape Create a gift request returns.

FieldDescription
reference (string · required)A human-readable handle for the gift request, unique within your account and stable for its lifetime. Show it to your own users and quote it to support; the API itself takes the id.
status (string · required)The public-facing status, one of submitted, redeemed, dispatched, delivered, cancelled. A freshly-created request is submitted, or redeemed for a direct send; the others are reached as the gift is redeemed, dispatched, and delivered, or cancelled. This is the field you poll to follow. delivered is not terminal, as the per-field notes below explain.
cancellable (boolean · required)Whether Cancel a gift request would accept this gift request as it stands. true only while status is submitted.
invitation_method (string · required)How this send reaches the recipient, one of email_invitation, direct_message_invitation, sender_provided_address. Fixed when the gift request is created, from the request's own invitation_method or else the campaign's.
campaign (object · required · nullable)The campaign this request belongs to, embedded as an { id, name, web_url } summary. null for an ad-hoc send that belongs to no campaign. Fetch the rest of the campaign with Get a campaign.
redemption_url (string · uri · required)The link the recipient follows to redeem. Always set, from the moment the gift request is created.
web_url (string · uri · required)The gift request's page in the &Open web app, on your organization's own domain. This is the sender-facing view and needs a signed-in session, so show it to your own users rather than the recipient.
recipient (object · required)The recipient, returned inline.
sender (object · required)The user recorded as responsible for the send, embedded as an { id, name, email } summary. Read their team and budget with Get a user.
shipping_address (object · required · nullable)The shipping address, returned inline in direct-send mode and null in choice mode.
offering (object · required)What was put in front of the recipient: the items on offer, whether they receive all of them or choose one, and whether they see them at redemption.
line_items (array · required · nullable)The line items, returned inline once locked.
email_message (object · required · nullable)The personal message that went into the invitation email, or null when the send carries none.
invitation_subject (string · required · nullable)The invitation email's subject line, or null when the send carries no invitation email.
notecard_message (string · required · nullable)The note packed with a Marketplace physical gift, or null when the send carries none.
lifecycle_events (object · required)When each step of the gift request happened, from the invitation email to delivery. Every key is always present and stays null until its event occurs.
cost (object · required · nullable)What the gift request cost, split into named { amount, currency } parts that add up to total. null until every part is final.
payment (object · required)How the gift request is paid for, one of invoice, card, and where the payment stands, one of invoiced, not_charged, pending, paid, failed, refunded.
accounting (object · required)The cost_centre and purchase_order the gift request is charged to, each null when none is assigned.
Response · 200
{
"id": "4fb4cb3f-9666-43b5-8884-7f5194483d1a",
"reference": "ACME-M5RD6J8",
"status": "redeemed",
"cancellable": false,
"invitation_method": "email_invitation",
"campaign": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Q4 Customer Appreciation",
"web_url": "https://acme.andopen.co/sender/gift-history/campaigns/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
},
"redemption_url": "https://acme.andopen.co/r/iacrG1q74eXGDW",
"web_url": "https://acme.andopen.co/sender/gift-history/4fb4cb3f-9666-43b5-8884-7f5194483d1a",
"recipient": {
"id": "b2c3d4e5-f6a7-8901-bcde-f01234567890",
"thank_you_count": 1,
"first_name": "Alice",
"last_name": "Smith",
"name": "Alice Smith",
"email": "alice@example.com"
},
"sender": {
"id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210",
"name": "Dana Okafor",
"email": "dana@acme.example"
},
"shipping_address": null,
"offering": {
"selection_mode": "one",
"visible_at_redemption": true,
"line_items": [
{
"id": "f6a7b8c9-d0e1-2345-6789-0abcdef01234",
"sku": "NOTEBOOK-A5",
"variant_id": "a7b8c9d0-e1f2-3456-789a-bcdef0123456",
"name": "Leather Notebook",
"quantity": 1,
"images": [
{
"name": "leather-notebook.jpg",
"url": "https://files.andopen.co/rndd63mwgj94j2vf3v2ngnye0hkn",
"urls": {
"thumbnail": "https://files.andopen.co/vw2mvwevyqxh98l7esf67nvunr4h",
"large": "https://files.andopen.co/mz4rc8kx1nvq7j93wtf5bd2hs0yl",
"large_wide": "https://files.andopen.co/q7pz3n8htv2ke0d5rjw94flxs6cb"
}
}
]
}
]
},
"line_items": [
{
"id": "d4e5f6a7-b8c9-0123-4567-890abcdef012",
"sku": "HOODIE-L-BLK",
"variant_id": "c3d4e5f6-a7b8-9012-cdef-012345678901",
"name": "Hoodie: Large / Black",
"quantity": 1,
"images": [
{
"name": "hoodie-black.jpg",
"url": "https://files.andopen.co/8k2mfp4qz7x9v1c3b5n0jhtl",
"urls": {
"thumbnail": "https://files.andopen.co/p3wq7m2zx8k4n6v0bjhtldsf",
"large": "https://files.andopen.co/r9td5c1yfw3jq7n2vk8mzbxh",
"large_wide": "https://files.andopen.co/h4nj8sv2qd6kz0wt3mfy9lpc"
}
}
]
}
],
"email_message": {
"subject": "A small thank-you",
"body": "Thanks for being a great customer!"
},
"invitation_subject": "A small thank-you",
"notecard_message": null,
"lifecycle_events": {
"invitation_email_sent_at": "2026-04-16T10:31:00.000Z",
"invitation_first_opened_at": "2026-04-16T18:40:00.000Z",
"invitation_last_opened_at": "2026-04-17T08:12:00.000Z",
"reminder_sent_at": null,
"redeemed_at": "2026-04-18T14:05:00.000Z",
"dispatched_at": null,
"delivered_at": null
},
"cost": {
"gift": {
"amount": 6000,
"currency": "EUR"
},
"greeting_card": {
"amount": 0,
"currency": "EUR"
},
"subtotal": {
"amount": 6000,
"currency": "EUR"
},
"handling": {
"amount": 300,
"currency": "EUR"
},
"shipping": {
"amount": 995,
"currency": "EUR"
},
"duties": {
"amount": 0,
"currency": "EUR"
},
"taxes": {
"amount": 0,
"currency": "EUR"
},
"fees": {
"amount": 0,
"currency": "EUR"
},
"total": {
"amount": 7295,
"currency": "EUR"
}
},
"payment": {
"method": "card",
"status": "paid",
"failure_reason": null
},
"accounting": {
"cost_centre": {
"id": "3d6f0a1e-8c2b-4e57-9a10-5b7c2e4f6a8d",
"code": "MKT-001",
"name": "Marketing"
},
"purchase_order": {
"id": "9b2e4c6a-1f3d-4a58-8e70-2c4d6f8a0b1e",
"code": "PO-2026-0042",
"name": "Q4 client gifting"
}
},
"created_at": "2026-04-16T10:30:00.000Z",
"updated_at": "2026-04-16T10:30:00.000Z"
}

Per-field notes​

  • shipping_address and line_items come back null until they're set. shipping_address is null until an address is provided, and line_items until the items are locked or chosen.
  • line_items is null, never [], before items are locked. For direct-send the items lock at creation, so line_items is populated from the start. For choice mode they lock at redemption, so the field stays null until the recipient chooses. Treat null as "not yet locked", not "no items".
  • delivered covers partial fulfillment, and it is not terminal. It means the gift reached the recipient, including a request whose remaining items failed or were cancelled, and the status can change again while a remaining item is retried. Don't treat it as the end of the lifecycle or stop polling on it.
  • campaign and sender are summaries, so they carry a label, an id, and little else. Use the name to display the gift request, and the id to fetch the full campaign or user when you need more than the label. The campaign summary also carries its own web_url.
  • offering.line_items and line_items hold different sets, and never the same item twice. Before redemption offering.line_items carries what the recipient was shown and line_items is null; after redemption line_items carries what they chose and offering.line_items carries what they left. Voucher, cause, and gift-set offerings are not represented yet and come back null.
  • recipient.thank_you_count counts the thank-yous the recipient has sent for this gift, and starts at 0. recipient.name joins their first and last name, and stays null until they supply at least one of the two.
  • invitation_method decides who passes the link on. With email_invitation, &Open emails the recipient their redemption_url. With direct_message_invitation, &Open sends nothing, so share the link yourself. With sender_provided_address, the gift ships to the address you supplied and there's no invitation at all.
  • invitation_subject, once the invitation email is sent, is the subject it went out with, and later edits don't change it. It can be null briefly while the email is being delivered, and for invitations sent before &Open recorded subjects.
  • invitation_subject, before the invitation email is sent, is the subject a send made now would carry: your email_message.subject, else the campaign's default_email_message.subject, else the subject set in the campaign's theme (or, with none, your organization's default theme), else &Open's standard subject line. It's null when invitation_method isn't email_invitation.
  • notecard_message is the handwritten note the vendor packs with a Marketplace physical gift: the notecard_message sent on Create a gift request, or else the campaign's default note at the time of the send. It's sent verbatim, with no template substitution, and it's independent of email_message.
  • lifecycle_events holds seven timestamps, each null until its event happens. Use them to answer questions status can't, such as whether the recipient has opened their link yet:
    • invitation_email_sent_at: when the invitation email was sent. Stays null for a send with no invitation email.
    • invitation_first_opened_at: the recipient's first load of redemption_url. Set once and never moves.
    • invitation_last_opened_at: their most recent load. It moves forward on each open, so it equals invitation_first_opened_at after a single open.
    • reminder_sent_at: when &Open sent the reminder to redeem. A gift request gets at most one.
    • redeemed_at: when the recipient committed their choice, or, for a send whose address you supplied, the first fulfillment step.
    • dispatched_at: when the carrier dispatched the gift. Stays null for a gift that reaches the recipient without a carrier dispatch.
    • delivered_at: when the gift reached the recipient.
  • cost is null until every part is final: the items are locked, and shipping is settled or doesn't apply. A redeemed gift request can still have cost: null while its shipping is worked out. From dispatched onward, cost is always set.
  • cost stays null on a gift request cancelled before redemption. One cancelled after redemption keeps its cost.
  • Every cost figure is in your account's currency, in the smallest currency unit, so the parts add up exactly. subtotal is gift + greeting_card, and total is subtotal + handling + shipping + duties + taxes + fees. In the example, 6000 of gifts, 300 handling, and 995 shipping make a total of 7295, which is €72.95.
  • A cost part that isn't charged is 0. Every part is always present and never null.
  • cost.gift is the gifts themselves: physical gifts, gift sets, digital gifts, and cause gifts combined.
  • cost.greeting_card is the paid greeting card, available only on gifts sent from your warehouse stock. It's always 0 on a Marketplace gift, whose handwritten note is priced into gift.
  • cost.handling is charged only on Marketplace gifts, and is 0 otherwise.
  • cost.duties, cost.taxes, and cost.fees are import charges on an international shipment from your warehouse stock. They're 0 on a domestic shipment, and always 0 on a Marketplace gift. shipping is the delivery charge without them.
  • When payment.method is invoice, shipping and its import charges are billed to you separately each month.
  • cost covers every item chosen at redemption, including any that later fail or are cancelled on a delivered gift request.
  • cost can change slightly between reads when a part is priced in another currency, because &Open converts it at the latest exchange rate each time.
  • Refunding a card charge doesn't change cost. payment.status reports the refund.
  • payment is on every gift request. method is invoice when the gift is billed to your organization's account, and card when it's charged to the team's saved card.
  • payment.status is never null, so you can read it without checking method first. It's always invoiced when method is invoice, and doesn't report whether the invoice has been paid.
  • For a card, payment.status is not_charged until &Open attempts a charge, including when it never will. It's then pending until the charge succeeds, including while it waits for review or a retry. failed means the charge failed or couldn't be made.
  • payment.failure_reason is a human-readable message, set only when a card charge failed for a reason your organization can fix, such as a declined card. Show it to your users, but don't branch on it: its wording can change.
  • accounting.cost_centre and accounting.purchase_order are each null when none is assigned, whether or not your account uses cost centers and purchase orders. A purchase order's name can also be null.
  • You can't set a cost center or purchase order on Create a gift request, or filter List gift requests by either.
  • cost, payment, and accounting are identical on this endpoint, List gift requests, and webhook payloads. The gift request summary embedded in other resources doesn't carry them.

Error cases​

Every failure uses the shared error model: a top-level errors array of objects carrying type, code, message, and (for field-level problems) param. See Errors for the full type/code taxonomy and how to handle each category; the codes below are the ones this endpoint produces.

StatusMeaning
400The request is malformed or violates a precondition. Typical triggers are a missing or unsupported `AndOpen-API-Version` header, a request body that is not valid JSON, or pagination parameters that fail server-side validation (`limit` non-numeric or non-positive, `after` referencing a record that does not exist).
401Authentication failed: missing or invalid bearer token.
403Authorized but not permitted to access this resource.
404The requested resource does not exist.
429Too many requests. Rate limit exceeded.
500Internal server error.
503Service unavailable. The account may be under maintenance. Check the `Retry-After` header.

Every error carries a type, one of: validation_error, authentication_error, authorization_error, not_found_error, rate_limit_error, api_error.

A read takes no body, so there's nothing to validate. The failure you'll handle most is a missing resource:

  • 404 not_found: no gift request with that id.
  • 401 authentication_error: the token is missing, unrecognized, or expired (unauthorized). A token is only valid in the region it was issued for, so one presented to the wrong region fails the same way.
  • 403 authorization_error: the token authenticated but isn't allowed to read this resource (forbidden, insufficient_scope).
  • 400 api_error: unsupported_api_version when the AndOpen-API-Version header is missing or unsupported (returned before authentication).
  • 429 rate_limit_error: you've exceeded the rate limit; back off using the Retry-After header.
  • 500 / 503 api_error: a fault on our side; rare, and safe to retry after a short delay (honor Retry-After on a 503).