Get a gift request

GET /gift_requests/{id}

Shape changed since 2025-10

The gift-request response changed in 2026-05. If you're upgrading an existing integration, read Gift requests in the migration guide before you start.

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, and the line_items — returned inline rather than as references you have to fetch separately. The campaign is the one exception: it's a cross-resource reference, returned as campaign_id only.

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 once it has been generated.

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 (path) · string · required — the gift request to retrieve. An id that doesn't match a gift request in your tenant returns 404.

Headers

AndOpen-API-Version (header) · string · required — 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 — there's 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"

const response = await fetch(
  "https://api.andopen.co/gift_requests/4fb4cb3f-9666-43b5-8884-7f5194483d1a",
  {
    method: "GET",
    headers: {
      Authorization: "Bearer <api_key>",
      "AndOpen-API-Version": "2026-05",
    },
  },
);

const giftRequest = await response.json();
console.log(giftRequest.status, giftRequest.redemption_url);

import requests

response = requests.get(
    "https://api.andopen.co/gift_requests/4fb4cb3f-9666-43b5-8884-7f5194483d1a",
    headers={
        "Authorization": "Bearer <api_key>",
        "AndOpen-API-Version": "2026-05",
    },
)
response.raise_for_status()

gift_request = response.json()
print(gift_request["status"], gift_request["redemption_url"])

require "net/http"
require "json"

uri = URI("https://api.andopen.co/gift_requests/4fb4cb3f-9666-43b5-8884-7f5194483d1a")

request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer <api_key>"
request["AndOpen-API-Version"] = "2026-05"

response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  http.request(request)
end

gift_request = JSON.parse(response.body)
puts "#{gift_request['status']} #{gift_request['redemption_url']}"

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.

• string · required — the public-facing status. It is one of submitted, redeemed, dispatched, delivered, cancelled. A freshly-created request is submitted; the others are reached as the gift is redeemed, dispatched, and delivered (or cancelled). This is the field you poll this endpoint to follow.
• string · uri · required · nullable — the link the recipient follows to redeem.
• string · uuid · optional · nullable — the campaign this request belongs to. It is a cross-resource reference; fetch the full campaign with Get a campaign.
• object · required — the recipient, returned inline.
• object · required · nullable — the shipping address, returned inline in direct-send mode and null in choice-mode.
• array · required · nullable — the line items, returned inline once locked.

{
  "id": "4fb4cb3f-9666-43b5-8884-7f5194483d1a",
  "status": "submitted",
  "campaign_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "redemption_url": "https://gift.andopen.co/r/abc123",
  "recipient": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f01234567890",
    "first_name": "Alice",
    "last_name": "Smith",
    "email": "alice@example.com"
  },
  "shipping_address": null,
  "line_items": null,
  "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".
• redemption_url can be null on a just-created request. The link is generated shortly after creation, so a read immediately after create may still return null — keep polling until it appears.
• campaign_id is a reference, not an embedded object. Unlike the owned associations, the campaign is returned as an id only; fetch it with Get a campaign.

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.

Status	Meaning
400	The 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).
401	Authentication failed — missing or invalid bearer token.
403	Authorised but not permitted to access this resource.
404	The requested resource does not exist.
429	Too many requests — rate limit exceeded.
500	Internal server error.
503	Service unavailable — the tenant 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, unrecognised, or expired (missing_token, invalid_token, expired_token). A token is only valid in the region it was issued for, so a token presented to the wrong region reads as invalid_token.
• 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 (honour Retry-After on a 503).