For urn manufacturers and providers
The RetURN.org API
Reserve RetURN.org IDs and download their production artwork, or activate RetURN.org IDs and fill in a family’s page, from your own system, without anyone signing in. The API is optional: everything here can also be done in your partner portal.
Getting Started.
- For urn manufacturers, the API is on once your company is approved. Funeral homes and cremation providers, contact us and we’ll turn it on. An administrator then creates a key in your partner portal, under API Info. The key is shown once, when you create it. A key can be limited to one location.
- Send it from your server as Authorization: Bearer <key>, never from a web page, where anyone can read it.
- The base URL is https://return.org/api/portal/v1. Start with GET /whoami: it answers with your company and your key, so you know the setup works.
Requests and answers are JSON, except artwork, which is an SVG file. Times are Unix seconds, and money is in cents (US dollars). v1 stays v1: we add fields and calls, and never remove or rename one, or change what one means, without a v2 and notice. Ignore fields you don’t know. A request body is up to 64 KB. Every call is also in returnorg-api-v1.json, an OpenAPI 3.0 file that API tools and code generators can read. Building software for funeral homes? Your key works a little differently: see case management software.
Keys.
| Key | What it can do |
|---|---|
| Full key | Every call below for your organization, except the ones only a software company makes. Made under API Info once the API is on. |
| Key for one location | A full or read-only key limited to one location sees that location’s RetURN.org IDs, and the ones not at any location yet. It can’t link cases, activate, fill in a family’s page, order, or read GET /prepaid-cards: use a key for the whole organization for those. |
| Read-only key | Every GET call, and nothing that changes anything. It never sees an activation code. Any approved partner can make one under Connect Your Software, for software you already use. |
| Software company’s key | Acts for the providers linked to it. See case management software. |
Each key can make up to 600 requests an hour. Every answer says what’s left in three headers, a refusal included: RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset (seconds until a call is free again). Every answer also has a Request-Id header, and every error repeats it as request_id: quote it when you contact us about a call, and we can find it. Over the limit, you get 429 rate_limited with a Retry-After header: wait that many seconds, then try again. An urn manufacturer can also reserve up to 20 times an hour. If RetURN.org turns your API off, every key your organization holds stops at once.
The Calls.
| Request | What it does |
|---|---|
| GET /whoami | Your company and your key, and can_be_charged: whether there’s a saved card to charge activations and orders to |
| GET /summary | Your RetURN.org IDs by stage (on_hand, incorporated, distributed, claimed, inactive), how many a funeral home has paid to activate, and how many were claimed in each of the last 12 months (UTC). For a provider, free_ids shows progress toward the next 25 free RetURN.org IDs |
| GET /orders | orders: your label shipments, with status and tracking. purchases: what you bought from us, with its order number (like RO-1042), status, tracking and total, and how many of its prepaid activation cards are used. Newest first, up to 100 of each. A key for one location gets its shipments only |
| GET /locations | Your locations. has_address says whether an order can ship there |
| GET /prepaid-cards | How many of your prepaid activation cards are unused, used and voided, and which RetURN.org ID each of the latest 200 used ones went on. Never a card’s code |
| GET /events | What happened to your organization and its RetURN.org IDs (see Keeping up) |
| GET /ids | Your RetURN.org IDs, most recently changed first. Optional: stage, location_id, updated_since (Unix seconds: only the ones that changed since), case_ref (the one you linked to that case), limit (default 50, up to 200) and offset, both whole numbers. The answer’s total counts them all, so you can page through |
| GET /ids/{id} | One RetURN.org ID, with family_confirmed, page_url, prefilled and editable_until (see records). A full key also gets its activation_code until it’s claimed |
| POST /ids/reserve | Urn manufacturers: reserve a block of new RetURN.org IDs (see below) |
| POST /ids/incorporate | Urn manufacturers: mark RetURN.org IDs as used in products (see below) |
| GET /ids/{id}/artwork | Urn manufacturers: one RetURN.org ID’s production artwork (see below) |
| GET /artwork/sheet | Urn manufacturers: up to 100 RetURN.org IDs’ artwork on one sheet (see below) |
| POST /ids/distribute | Providers: mark RetURN.org IDs as handed to a family (see below) |
| POST /ids/{id}/case | Providers: link a RetURN.org ID to a family’s case (see below) |
| DELETE /ids/{id}/case | Providers: unlink it |
| POST /ids/{id}/link | Providers: link your organization to a RetURN.org ID, free (see below) |
| POST /ids/{id}/activate | Providers: activate a RetURN.org ID, on your saved card or with a prepaid activation card (see below) |
| POST /ids/{id}/family | Providers: fill in the family’s details, free, before or after activating, and publish them for the family once it’s paid for (see below) |
| POST /orders | Providers: order prepaid activation cards or RetURN.org IDs on your saved card (see below). A linked software company can order them for you too |
| /platform/… | Software companies only: linking providers, setting up their accounts, and earnings. See case management software |
The API never shows anything the family writes on their page.
Reserving RetURN.org IDs.
Send an Idempotency-Key header with any unique string. A retry with the same key and the same request returns the same block instead of a second one, for 30 days.
POST /ids/reserve
Idempotency-Key: run-2026-11-09-a
{"quantity": 250, "product": "Oak Keepsake", "sku": "OK-200",
"batch": "B-1142", "external_ref": "PO-8841"}
Only quantity is required, up to 250,000 at a time. product (up to 120 characters), sku, batch and external_ref (up to 60 each) are your own labels, and external_ref comes back as internal_ref. Add location_id to reserve for one location (a key for one location reserves at its own when you leave it out), and physical_type (engraving, the default, or label, integrated or other) to say how it goes on the urn. There is a limit on how many reserved RetURN.org IDs can wait to be used at once; over it, you get print_cap, and the message says how many you can reserve. Nothing is charged. An organization that both makes urns and hands RetURN.org IDs to families says which it is reserving as with role: point_of_sale reserves up to 5,000, with no number or block_id, and those RetURN.org IDs do need their codes.
The answer lists each new RetURN.org ID with its number (your running count, as in the portal) and the block_id it was reserved in. It also gives the artwork_version. Each one also comes with an activation_code, which you don’t need: a RetURN.org ID printed or engraved on an urn activates without its code.
Marking RetURN.org IDs as Used.
POST /ids/incorporate
{"ids": ["CP2-R6SY", "HQ7-K2MD"], "product": "Oak Keepsake", "sku": "OK-200"}
Up to 5,000 at a time. product, sku, batch and internal_ref are optional and replace what was there. It’s all or nothing: if one RetURN.org ID isn’t yours or has already gone to a family, nothing is marked, and the error names it. Marking one that’s already marked is fine. The answer says how many: {"ok": true, "count": 2}.
Artwork.
The same SVG files as the portal’s download, every letter an outline, ready for a laser or router. The printing and engraving specifications cover size, fonts and placement.
| Request | What you get |
|---|---|
| GET /ids/{id}/artwork | The full RetURN.org ID, 2.000″ × 0.750″ |
| GET /ids/{id}/artwork?kind=qr | The QR code alone, with its clear space |
| GET /artwork/sheet?ids=CP2-R6SY,HQ7-K2MD | Up to 100 of your RetURN.org IDs on one sheet, four across, with a red hairline cut line around each |
Mark one piece and scan it with two phones before a production run: each should open that RetURN.org ID’s page.
Funeral Homes and Cremation Providers.
With your own key, you can link a family’s case to a RetURN.org ID, link your organization to it and fill in the family’s details for free, activate it, and order. Use a full key for the whole organization. An organization that also makes urns does these in the partner portal for now.
Linking a case: POST /ids/{id}/case
POST /ids/CP2-R6SY/case
{"case_ref": "2026-0412"}
case_ref is your case number, up to 120 characters. Sending it again replaces it, and DELETE /ids/{id}/case removes it, as when the wrong urn was linked. A case puts nothing on the RetURN.org ID: your name goes on it when you link your organization to it, fill in the family’s details, or activate it. The answer has the case_ref, and whether the RetURN.org ID is paid and claimed. GET /ids?case_ref=2026-0412 finds the RetURN.org ID by its case once you hold it. Before that (an urn’s RetURN.org ID you haven’t activated yet), GET /ids/{id} answers with just id, case_ref, paid and claimed.
Linking your organization: POST /ids/{id}/link
POST /ids/CP2-R6SY/link
{"provider_as": "funeral_home"}
Free. Your name goes on the RetURN.org ID as the provider who handed it to the family, as when you add an urn’s RetURN.org ID in the partner portal. Nothing is charged, nobody is emailed, and a scan shows nothing new: the family still activates it, free once you’ve paid for it and $29.99 if not. The body is optional (provider_as, as for activating). It’s refused for a RetURN.org ID another provider holds or paid for (not_linkable), one the family already activated (already_active), and a family’s own, bought from us or reissued for them (family_bought). New links are limited to 30 an hour and 100 a day for your organization (link_limited). The answer says linked, already (true when you were linked before), paid, and price_cents: what activating would cost you now (0 when it’s paid for already).
Activating: POST /ids/{id}/activate
POST /ids/CP2-R6SY/activate
{"provider_as": "funeral_home"}
We charge $17.99, plus sales tax where it applies, to your saved card, and the family isn’t charged. Your administrator adds the card in the partner portal, under Payment Method; can_be_charged on GET /whoami says whether there is one. provider_as is optional: funeral_home, crematory or both. Left out, the setting on your Organization page is used. Your name goes on the RetURN.org ID once it’s paid for.
To use one of your prepaid activation cards instead, send {"prepaid_code": "ABCD-2345"}: the code on the card handed to this family (capitals and dashes don’t matter). Nothing is charged, and that card is used up. We never pick a card for you, because each card is printed with its own code.
The answer says paid: true, pay (card or prepaid) and price_cents, what was charged before tax (0 for a prepaid card). It also says already: true when nothing new was paid, because the RetURN.org ID was already paid for, needs no payment, or a payment you started earlier went through. Activating twice charges once.
Filling in the family’s details: POST /ids/{id}/family
{"full_name": "Ruth Ann Miller", "pronouns": "she/her",
"birth_year": 1941, "death_year": 2026,
"wish_first": "Scatter at the lake", "wish_fallback": "Keep at home"}
Free, before or after you activate the RetURN.org ID. It links your organization to it, as POST /ids/{id}/link does, and keeps the details private: nothing is charged, nobody is emailed, a scan shows nothing, and the RetURN.org ID isn’t claimed. When the family activates it (free if you paid, $29.99 if not), their page starts from these details, with a note saying your organization filled it in; they check it, change anything, and publish it when they’re ready. full_name (up to 120 characters) is required. wish_first and wish_fallback (up to 400 characters each) are what the family wants done with the ashes, first choice and otherwise. pronouns is up to 40 characters, and the years are four digits, from 1850 to next year. For a pet, add "subject_kind": "pet" and its species, such as "Beagle" (up to 80 characters).
Send it again to replace the details, until the family activates the RetURN.org ID; after that it answers 409 locked, and only the family changes the page. The same refusals and limit as linking apply. The answer says saved, linked, paid and price_cents, never what you sent; GET /ids/{id} says prefilled: true while the details wait for the family.
Publishing it for the family. With the family’s permission, add "publish": true and permission_by, the name of the family member who said yes (up to 120 characters), and the page is published now: a scan shows it before anyone activates the RetURN.org ID. It needs wish_first, and the RetURN.org ID has to be paid for first (POST /ids/{id}/activate); otherwise it answers 409 activate_first and saves nothing. We keep the name of who gave permission with the page. Nobody is emailed. Once it’s published, send it again with publish: true to change it; without it, 409 published. The family can still activate the RetURN.org ID, free since it’s paid for: the page they get is the one you published, still public, and from then on only they change it. The answer says published, and so does GET /ids/{id} until the family activates it.
Unpublishing it. Send "publish": false on a page you published and it’s private again, as before you published it: a scan shows nothing. The details stay with you, to change and publish again: {"publish": false} alone keeps the ones you sent before, and with details it keeps those instead. The answer says unpublished: true. Only you can unpublish a page you published, and only until the family activates the RetURN.org ID; after that it’s their page (409 locked). Leaving publish out still answers 409 published, so nothing is unpublished by accident. Nobody is emailed.
Changed on 2026-11-19. This used to need the activation first (409 not_paid), set up the page (claimed) and email the family. It does none of that now. email and consent are still accepted and not needed. family_emailed is always false and editable_until always null.
Ordering: POST /orders
POST /orders
Idempotency-Key: po-2026-0412
{"item": "activation_cards", "quantity": 2, "location_id": "<from GET /locations>"}
item is activation_cards (25 prepaid activation cards a pack, $449.75) or ids (25 RetURN.org IDs with activation sheets a pack, $50). quantity is the number of packs: up to 20 of cards, or 100 of RetURN.org IDs. location_id is where it ships, and that location needs a street address; you can leave it out if you have one location. We charge your saved card, plus sales tax where it applies. An Idempotency-Key header is required, as for reserving.
The answer has the order number (like RO-1042), ship_to (the location’s name), item and packs. The order then shows in GET /orders under purchases; a pack of RetURN.org IDs also shows under orders when it ships.
A software company you’ve linked can place the same order for you, on your saved card, at the same prices (see case management software). Your administrators get the receipt, and the order shows in your history, and in GET /orders as ordered_through, with the company’s name. To stop it, unlink the company in your partner portal.
Handing RetURN.org IDs to a family: POST /ids/distribute
{"ids": ["CP2-R6SY"], "location_id": "<from GET /locations>", "reference": "2026-0412"}
Marks RetURN.org IDs you hold as given to a family, up to 5,000 at a time. location_id and reference (up to 60 characters, which comes back as internal_ref) are optional. Sending it again is safe: a RetURN.org ID you already gave to a family comes back in already and isn’t marked twice. Otherwise it’s all or nothing: one that can’t be given to a family answers wrong_stage, with it in ids, and nothing is marked. Activating a RetURN.org ID does this for you.
Keeping Up With Changes.
Two ways to learn what changed without asking about every RetURN.org ID.
GET /events?after=0 lists what happened to your organization and its RetURN.org IDs, oldest first, up to 100 at a time (limit, up to 200). Each event has an id, a type, when it happened (at) and the return_id (null for an event about your organization). Keep next_after from each answer and send it as after next time. An event never says who did it or anything the family wrote. A key for one location sees only events on RetURN.org IDs at that location, and none about your organization.
| Type | What happened |
|---|---|
| paid | A provider paid for the RetURN.org ID, on a card or with a prepaid activation card |
| refunded | A payment for the RetURN.org ID was refunded |
| claimed | The family’s page was set up, by the family or by the funeral home for them (claimed is now true) |
| family_confirmed | The family confirmed their email address, once, the first time. family_confirmed on GET /ids/{id} says the same at any time |
| published unpublished | The family’s page was made public (by the family, or by you for them), or private again |
| case_linked case_unlinked | A case was linked to the RetURN.org ID, or unlinked. A software company sees only its own |
| distributed | The RetURN.org ID was marked as handed to a family |
| id_linked | A provider was linked to the RetURN.org ID through the API, by POST /ids/{id}/link or /family |
| linked unlinked | A software company was linked to your organization, or unlinked |
| approved | We approved your organization |
GET /ids?updated_since=<Unix seconds> gives every RetURN.org ID that changed since then: paid for, refunded, handed to a family, claimed. It doesn’t see a family confirming their email; GET /events does. Each record carries updated_at: keep the largest you’ve seen and ask from there next time. The second it names comes back again, so skip IDs you already have.
RetURN.org ID Records.
| Field | What it is |
|---|---|
| id | The RetURN.org ID, for example CP2-R6SY |
| number | Your running count of printed and engraved RetURN.org IDs |
| stage | available (reserved), incorporated (used in a product), distributed (handed to a family), claimed (the family’s page is set up) or inactive (retired or replaced) |
| paid | Whether a funeral home has paid to activate it for the family |
| claimed | Whether the family’s page is set up, by the family or by the funeral home for them. It doesn’t mean the family has seen it: see family_confirmed |
| family_confirmed | Whether the family has confirmed their email address. GET /ids/{id} only |
| page_url | The address of the RetURN.org ID’s page. It stays private until it’s published. GET /ids/{id} only |
| prefilled | Whether your details for the family are waiting for the family to activate the RetURN.org ID. GET /ids/{id} only |
| published | Whether you published those details for the family, so a scan shows the page. False once the family activates the RetURN.org ID. GET /ids/{id} only |
| editable_until | Until when you can still change a family’s page you set up before 2026-11-19 (Unix seconds), or null. Null for anything newer. GET /ids/{id} only |
| activation_code | Full keys only, until it’s claimed. GET /ids/{id} only |
| case_ref | The case you linked to it, or null. Nobody else sees it |
| code_free | Whether it activates with the RetURN.org ID alone, as one printed or engraved on an urn does |
| roles | How your organization is related to it: manufacturer, point_of_sale (you hand it to a family), or both |
| assignment physical_type | How it reached you: api if you reserved it here, otherwise how it goes on the urn (label, engraving, integrated or other) |
| product sku batch internal_ref | Your own labels |
| location_id location | The location it belongs to, if any |
| created_at incorporated_at distributed_at claimed_at | When each stage happened (Unix seconds), or null |
| replaced_by | The RetURN.org ID that replaced it, if one did |
Testing.
Ask [email protected] for a sandbox: a test funeral home linked to your account, with test RetURN.org IDs, a test card on file and a test key of its own, plus a test key for your company. A test key starts ro_test_ and works for the sandbox and nothing else: used for a real funeral home it answers test_key, and your live key used for the sandbox answers live_key, so a wrong Organization ID in your code never reaches a real funeral home’s card. Send the sandbox’s Organization ID in RetURN-Organization with your test key and every call works as it does for a real funeral home, except that nothing costs anything. An activation is marked paid without charging a card, and the answer says "sandbox": true. An order is answered with an order number starting RO-SANDBOX- and never shipped. Nothing you do there earns or is billed. We still email the family, so use an email address of your own.
Retries and Payments.
- Reserving, ordering and setting up a provider need an Idempotency-Key header: any unique string, up to 120 characters (a longer one is refused with bad_idempotency_key). Send the same request with the same key again, as after a timeout, and you get the first answer back for 30 days, instead of a second block, order or account. The same key with a different request gets idempotency_reused. An error isn’t kept, so once you fix what it says, the same request with the same key tries again. Idempotency-Key values belong to your organization, not to one API key, so two integrations under one organization shouldn’t use the same values.
- Activating is safe to retry without a key. A RetURN.org ID is paid for once. A second call answers already: true and charges nothing, and two calls at the same moment are charged once: the second may be told payment_unconfirmed while the first is still going through, and gets already: true when it tries again.
- Linking, unlinking a case, and filling in the family’s details are safe to send again. Linking again answers already: true. Unlinking a case that is already unlinked answers 404 no_case: treat it as done. Sending the family’s details again replaces them, until the family activates the RetURN.org ID; after that it answers 409 locked. Nobody is emailed either way.
- payment_unconfirmed means send the same request again in a minute. The card processor didn’t answer, so nobody knows yet whether the card was charged. On the next try we ask the processor about that payment before charging anything, whatever you send, so the card is charged only once.
- card_failed means the bank said no. Nothing was charged. Try again once the bank has cleared it, or the organization can change the card in the partner portal, under Payment Method.
- Nothing is charged twice for the same thing. Activating checks for an earlier payment on that RetURN.org ID before starting a new one. An order is the same order only under the same Idempotency-Key, so send a retry with the key you used: a new key is a new order, charged again.
- Nothing the family writes is ever returned, in any answer or event: not their name, their wishes or their email. You see only whether the page is set up (claimed), whether they confirmed their email (family_confirmed), its address (page_url), and whether your details are still waiting for them (prefilled).
Errors.
An error answers {"ok": false, "error": "…", "code": "…"}. The error is for people and may change; act on the code.
| Code | What it means |
|---|---|
| bad_key | 401. The key is wrong or revoked, your company isn’t approved or active, or the API isn’t on for it. Check the key, or contact us |
| key_read_only | 403. A read-only key can’t change anything. Use a full key |
| key_location | 403. A key for one location can’t do that (link cases, activate, fill in a page, order, or read prepaid cards). Use a key for the whole organization |
| key_platform | 403. A software company’s key can’t make that call |
| key_not_platform | 403. Only a software company’s key can make that call |
| org_unavailable | 403. Your organization isn’t available to the API right now. Contact us |
| not_manufacturer | 403. Reserving, marking as used and artwork are for urn manufacturers. Providers order labels in the partner portal or with POST /orders |
| needs_onboarding | 403. Your company isn’t approved to print or engrave RetURN.org IDs yet. Contact us |
| not_provider | 403. Your organization doesn’t hand RetURN.org IDs to families, so it can’t link cases, activate, fill in a page or order |
| own_key_not_open | 403. An organization that also makes urns links cases, activates, fills in pages and orders in the partner portal for now |
| bad_json | 400. The body isn’t a JSON object. Fix it and send it again |
| bad_field | 400. A field that should be text isn’t, or a required one is missing or doesn’t look right. field names it |
| too_large | 413. The body is over 64 KB. Send fewer RetURN.org IDs in each call |
| idempotency_required | 400. Reserving, ordering and setting up a provider need an Idempotency-Key header |
| bad_idempotency_key | 400. An Idempotency-Key is up to 120 characters |
| idempotency_reused | 409. That Idempotency-Key was used for a different request. Use a new one |
| not_found | 404. That RetURN.org ID doesn’t exist, or isn’t yours |
| location_not_found | 404. That location_id isn’t one of your company’s. GET /locations lists them |
| location_not_yours | 403. The key is limited to a different location |
| bad_stage | 400. stage is available, incorporated, distributed, claimed or inactive |
| bad_updated_since | 400. updated_since is Unix seconds, a whole number |
| bad_cursor | 400. limit and offset on GET /ids, and after and limit on GET /events, are whole numbers |
| test_key | 403. A test key acts only for your sandbox funeral home. Use your live key for a real one |
| live_key | 403. A sandbox funeral home takes your test key, the one starting ro_test_. Your live key acts for real ones only |
| print_cap | 400. Too many reserved RetURN.org IDs are waiting to be used. Mark some as used, or contact us to raise your limit |
| wrong_stage | 409. One of the RetURN.org IDs can’t be marked: it was retired, or it’s already claimed or used. It’s in ids. Nothing was marked; send the others again |
| already_distributed | 409. Another call marked one of the RetURN.org IDs given to a family at the same moment. Nothing was marked; send them again |
| need_ids | 400. Send ids, a list of RetURN.org IDs |
| too_many_ids | 400. Too many RetURN.org IDs in one call: up to 5,000 to mark, or 100 on a sheet |
| bad_location | 400. location_id is the id of one of your locations, as a string |
| bad_kind | 400, artwork. kind is svg or qr |
| need_case_ref | 400. Send case_ref, your case number |
| not_linkable | 404, linking a case or your organization. Another provider holds or paid for this RetURN.org ID, or it no longer works |
| family_bought | 409, linking or filling in the details. This RetURN.org ID is a family’s own (bought from us, or a replacement for theirs), so its page is theirs to fill in |
| link_limited | 429, linking or filling in the details. Your organization linked 30 RetURN.org IDs in the last hour, or 100 today. Try again later, or email [email protected]. Details for a RetURN.org ID you’re already linked to aren’t limited |
| no_case | 404, unlinking a case. You haven’t linked a case to this RetURN.org ID |
| bad_pay | 400, activating. pay is card, or send prepaid_code to use a prepaid activation card, not both |
| bad_prepaid | 400, activating. That prepaid activation code doesn’t match one of your cards. Check it against the card |
| prepaid_used | 409, activating. That prepaid activation card was already used on another RetURN.org ID. Nothing was charged. Email [email protected] and we’ll help |
| not_activatable | 404 or 409, activating or filling in the page. Another provider holds this RetURN.org ID, or it can’t be activated |
| already_active | 409, activating or linking. This RetURN.org ID is already active. Check it with GET /ids/{id} |
| retired | 409, activating, linking or filling in the details. This RetURN.org ID was retired and can’t be activated. Use the family’s other RetURN.org ID |
| paid_by_other | 403, activating. Another organization paid to activate this RetURN.org ID, so it’s theirs to set up |
| checkout_open | 409, activating. A checkout for this RetURN.org ID is open in the provider’s RetURN.org portal. Wait a minute and try again, or ask them to finish it |
| in_progress | 409, activating or ordering. The same activation or order is going through right now. Check it again in a minute |
| bad_year | 400, filling in the page. Years are four digits, between 1850 and now |
| bad_filter | 400, earnings. since, until, limit and offset are whole numbers, and org_number is an Organization ID |
| need_provider_as | 400. provider_as is funeral_home, crematory or both |
| no_card | 409, activating or ordering. There’s no saved card. Your administrator adds one in the partner portal, under Payment Method. Nothing was charged |
| card_failed | 409. The card was declined, or the bank wants you to confirm. Nothing was charged. Try again once the bank has cleared it, or change the card in the partner portal, under Payment Method |
| payment_unconfirmed | 502. We couldn’t confirm the payment with the card processor. Send the same request again in a minute: the card is charged only once |
| payments_unavailable | 409. Payments can’t be taken right now. Nothing was charged. Try again later |
| not_paid | No longer sent since 2026-11-19: the family’s details can be filled in before activating |
| need_name | 400, filling in the page. Send full_name |
| need_email need_consent | No longer sent since 2026-11-19: nobody is emailed |
| need_permission | 400, publishing the details. Send permission_by, the name of the family member who gave permission |
| incomplete | 400, publishing the details. Send wish_first, their first choice |
| activate_first | 409, publishing the details. The RetURN.org ID isn’t paid for. Activate it first with POST /ids/{id}/activate. Nothing was saved |
| published | 409, filling in the details. You published this page: send it again with publish: true and permission_by to change it, or with publish: false to unpublish it |
| not_published | 409, unpublishing. The page isn’t published, or wasn’t published by you, so there’s nothing to unpublish |
| page_written | 409, publishing the details. Someone already wrote on this RetURN.org ID’s page, so it can’t be published for the family |
| bad_subject_kind | 400, filling in the page. subject_kind is person or pet |
| locked | 409, filling in the details. The family has activated this RetURN.org ID: only the family can change its page now |
| bad_item | 400, ordering. item is activation_cards or ids |
| bad_quantity | 400. Reserving: ask for at least 1, up to what you may reserve. Ordering: quantity is a whole number of packs: up to 20 of cards, or 100 of RetURN.org IDs |
| need_location | 400, ordering. You have more than one location: send location_id |
| need_address | 400, ordering. That location has no street address. Your administrator adds one in the partner portal, under Locations |
| rate_limited | 429. Over 600 requests an hour for a key, or 20 reservations an hour for your company. Wait the seconds in the Retry-After header and try again |
| no_endpoint | 404. There’s no such call. Check the path |
| method_not_allowed | 405. That call doesn’t take that method (GET, POST or DELETE) |
| server_error | 500. Something went wrong on our side. Try again; if it keeps happening, contact us |
| (none) | 400 with only a message when a field is missing or wrong, such as a quantity out of range or a year that isn’t four digits; 403 with only a message when your organization isn’t set up for a call; 409 with only a message when a RetURN.org ID is at the wrong stage. The message says what to fix |
Building an integration? Book a call with us, or contact us.