Skip to content

For case management software

Bring RetURN.org IDs Into Your Case Management Software.

Funeral homes and cremation providers can link a family’s case to a RetURN.org ID, activate it, and see their RetURN.org numbers without leaving your software. You earn $1 for every RetURN.org ID activated through it.

How It Works

  1. 1

    Register Your Company

    Fill in the form below. We review it and email you.

  2. 2

    Create Your Key

    In your partner portal, under API Info. Your Organization ID is at the top right.

  3. 3

    Connect Your Providers

    With their RetURN.org Organization ID, or a free sign-up.

  4. 4

    Start Earning

    $1 for every RetURN.org ID activated through your software.

Connecting a Provider

Ask this when a provider sets up your software:

Do You Have a RetURN.org Organization ID?

Yes: they enter it. It’s at the top right of every page in their RetURN.org partner portal. They approve the link in their portal, and you’re connected.

Would You Like One? It’s Free.

No: send them to our sign-up page with your link. They sign up free, get their Organization ID, and come back to enter it. They manage their RetURN.org IDs in their portal.

What You Can Show

What Your Software Can Do

  • Link the provider to a RetURN.org ID and fill in the family’s details, free, before or after activating it
  • RetURN.org IDs on hand, handed to families, paid for and claimed
  • Progress toward their next 25 free RetURN.org IDs
  • Each RetURN.org ID’s status, the case it’s linked to, and whether the family has confirmed their email
  • Orders, with status and tracking
  • Their locations, and how many prepaid activation cards they have left

What It Never Sees

  • Anything the family writes or changes on their page
  • Activation codes, or the codes on their prepaid activation cards
  • The provider’s payment card
  • The provider’s team

The API

Base URL https://return.org/api/portal/v1. Send your key as Authorization: Bearer <key> from your server, never from a web page. To act for a provider, add RetURN-Organization: ORG-XXXXXX with their Organization ID.

Every call is also in returnorg-api-v1.json, an OpenAPI 3.0 file that API tools and code generators can read, and in the full API reference, with every field of a RetURN.org ID’s record. 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.

RequestWhat it does
GET /whoamiYour company and your key. A good first call to check your setup; no RetURN-Organization needed. With it, the provider, and can_be_charged: whether they have a saved card to charge activations to
POST /platform/organizations/linkAsk to link a provider by org_number. Linked once they approve it in their portal. The answer is the same whether or not the Organization ID exists
POST /platform/organizationsSet up a RetURN.org account for a provider that has none (see below). It waits for our approval, and is linked to you at once
GET /platform/organizationsYour linked providers, with your_ref, and the ones still waiting to approve
GET /platform/earningsWhat you’ve earned, activation by activation, newest first, and what we bill you for pay: company this month and last. Optional: since and until (Unix seconds), org_number (one provider), limit (up to 200, the default) and offset. The totals count every match
GET /summaryThe provider’s RetURN.org IDs by status, including how many are paid for and claimed, and progress toward free RetURN.org IDs
GET /ordersThe provider’s label shipments (orders) and what they bought from us (purchases), with status and tracking
GET /locationsThe provider’s locations. has_address says whether an order can ship there
GET /prepaid-cardsHow many of the provider’s prepaid activation cards are unused, used and voided, and which RetURN.org ID each used one went on. Never a card’s code
GET /eventsWhat happened to the provider and its RetURN.org IDs, oldest first: send after with the next_after from the last answer. Types: paid, refunded, claimed (the family’s page was set up), family_confirmed, published, unpublished, case_linked, case_unlinked, distributed, id_linked, linked, unlinked, approved. The full reference explains each
GET /idsThe provider’s RetURN.org IDs, most recently changed first. Add updated_since (Unix seconds) to get only the ones that changed, or case_ref to find the one you linked to that case. 50 at a time; limit (up to 200) and offset page through, and total counts them all. Each says whether it is paid (a provider paid to activate it) and claimed (the family’s page is set up, by the family or by the provider for them), with its case_ref if you linked one
GET /ids/{id}One RetURN.org ID, with its case_ref, family_confirmed (the family confirmed their email), page_url, prefilled (your details for the family are waiting for them to activate it), published (you published those details for the family) and editable_until (for a page you set up before 2026-11-19, else null). For a RetURN.org ID you linked to a case before activating it, which GET /ids doesn’t list yet, it answers with just id, case_ref, paid and claimed
POST /ids/{id}/caseLink a RetURN.org ID to a family’s case: case_ref, your case number, up to 120 characters. Sending it again changes it. Only you see the case numbers you link
DELETE /ids/{id}/caseUnlink it, as when the wrong urn was linked
POST /ids/{id}/linkLink the provider to the RetURN.org ID, free: their name goes on it. Nothing is charged and nobody is emailed. Optional provider_as. New links are limited to 30 an hour and 100 a day per provider
POST /ids/{id}/activateActivate it (see below). Activating twice charges once
POST /ids/{id}/familyFill in the family’s details, free, before or after activating, and publish them for the family once it’s paid for (see below). Nobody is emailed. You can replace them until the family activates the RetURN.org ID; after that, only the family can change the page
POST /ordersOrder packs of 25 prepaid activation cards or 25 RetURN.org IDs for the provider, on their saved card, shipped to one of their locations (see below)

Sign-up link for a provider with no account

https://return.org/apply/?via=ORG-XXXXXX&ref=<your customer ID>

Use your own Organization ID in via. The ref comes back as your_ref in GET /platform/organizations, so you know which customer signed up. Your key can make up to 600 requests an hour for each provider it acts for, and another 600 for calls that name no provider. Over that, you get 429 rate_limited with a Retry-After header: wait that many seconds, then try again. Your company can set up 20 accounts an hour and 100 a day, across all its keys; over that, the same 429. Every answer has a Request-Id header: quote it when you contact us about a call.

Setting up a provider: POST /platform/organizations

Send an Idempotency-Key header (any unique string), so a retry never sets them up twice. We email the contact an invitation to their portal. If they already have an account, you get already_has_account: ask them to link you instead.

{"organization": {"name": "Shady Oaks Cremation", "provider_as": "both",
                  "website": "https://shadyoaks.example",
                  "address": {"address1": "1 Main St", "city": "Frederick",
                              "state": "MD", "postal": "21701"}},
 "contact": {"first_name": "Dana", "last_name": "Reyes",
             "email": "[email protected]", "phone": "301-555-0100"},
 "your_ref": "CUST-1187"}

Required: name (up to 120 characters), provider_as (funeral_home, crematory or both), city and state, and the contact’s first_name, last_name (up to 40 characters each) and email. your_ref (up to 120 characters) is your own reference for the provider, and comes back in GET /platform/organizations. The answer has their org_number, status (pending until we approve them; your key works for them after that) and invited (whether the invitation email went out).

Activating: POST /ids/{id}/activate

pay says who pays:

  • card, the default: $17.99, plus sales tax where it applies, on the provider’s saved card. You earn $1. Check can_be_charged on GET /whoami first.
  • company: you bill the provider and keep your $1. We bill you $16.99 for each activation, once a month. We set this up with you first.
  • prepaid_code instead of pay: the code on one of the provider’s own prepaid activation cards, the one handed to this family (capitals and dashes don’t matter). Nothing is charged, that card is used up, and you earn $1. We never pick a card, because each card is printed with its own code.

Optional provider_as: funeral_home, crematory or both; left out, the provider’s own setting is used. The provider’s name goes on the RetURN.org ID, if linking or filling in hadn’t put it there already. The answer says paid: true, pay and price_cents (what was charged, before tax), and already: true when nothing new was paid, because the RetURN.org ID was already paid for, needs no payment, or a payment started earlier went through.

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 the provider activates the RetURN.org ID. It links the provider 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 the provider paid, $29.99 if not), their page starts from these details, with a note naming the provider; they check it, change anything, and publish it. 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. For a pet, add "subject_kind": "pet" and its species, such as "Beagle". Send it again to replace the details until the family activates it; after that it answers 409 locked. The answer says saved, linked, paid and price_cents (what activating would cost the provider now), never what you sent.

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, and the page is published now, so a scan shows it before anyone activates the RetURN.org ID. It needs wish_first, and the provider has to have paid for the RetURN.org ID first (POST /ids/{id}/activate); otherwise it answers 409 activate_first and saves nothing. 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 it, free: the page they get is the published one, and from then on only they change it. The answer says published.

Unpublishing it. Send "publish": false on a page the provider published and it’s private again: a scan shows nothing, and the details stay, to change and publish again ({"publish": false} alone keeps the ones sent before). The answer says unpublished: true. Only for the provider that published it, and only until the family activates the RetURN.org ID (409 locked after). Leaving publish out still answers 409 published. Nobody is emailed.

Changed on 2026-11-19. This used to need the activation first (409 not_paid), set up the page 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 for a provider: 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, one of the provider’s locations with a street address; leave it out if they have one location. We charge the provider’s saved card, at the prices they pay themselves, plus sales tax where it applies. An Idempotency-Key header is required: the same request with the same key gets the same order back and one charge. The answer has the order number (like RO-1042), ship_to, item and packs. The order shows in the provider’s history, and in GET /orders, as ordered through you, and the provider’s administrators get the receipt. You earn nothing on orders.

Retries and payments

  • Setting up a provider and ordering need an 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 account or order. A new key is a new order, charged again. The same key with a different request gets idempotency_reused. An error isn’t kept, so the same request tries again once you fix what it says.
  • 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 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 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 their bank has cleared it, or the provider can change the card in their portal, under Payment Method.
  • Nothing the family writes is ever returned, in any answer or event. You see only claimed, family_confirmed, page_url, prefilled and published.

Errors

An error answers {"ok": false, "error": "…", "code": "…"}. The error is for people and may change; act on the code.

CodeWhat it means
bad_key401. The key is wrong, revoked, or your company isn’t approved
organization_required400. Add the RetURN-Organization header
not_linked404. That provider isn’t linked to you, or has unlinked you
org_unavailable403. That provider is waiting for our approval, is no longer active, or has its API turned off
key_platform403. A software company’s key can’t make that call
not_provider403. That organization doesn’t hand RetURN.org IDs to families, so it can’t link cases or activate them
not_manufacturer403. Artwork is for urn manufacturers
bad_json400. The body isn’t a JSON object. Fix it and send it again
bad_field400. A field that should be text isn’t, or a required one is missing or doesn’t look right. field names it
too_large413. The body is over 64 KB. Send fewer RetURN.org IDs in each call
not_found404. That RetURN.org ID doesn’t exist, or isn’t the provider’s
bad_stage400. stage is available, incorporated, distributed, claimed or inactive
bad_updated_since400. updated_since is Unix seconds, a whole number
bad_cursor400. limit and offset on GET /ids, and after and limit on GET /events, are whole numbers
test_key403. A test key acts only for your sandbox funeral home. Use your live key for a real one
live_key403. A sandbox funeral home takes your test key, the one starting ro_test_. Your live key acts for real ones only
bad_filter400. since, until, limit and offset on GET /platform/earnings are whole numbers
location_not_found404. That location_id isn’t one of the provider’s. GET /locations lists them
need_case_ref400, linking a case. Send case_ref
not_linkable404, linking a case. Another provider holds this RetURN.org ID, or it no longer works
no_case404, unlinking a case. You haven’t linked a case to this RetURN.org ID for this provider
bad_pay400, activating. pay is card or company, or send prepaid_code to use a prepaid activation card, not both
billing_not_set_up403. pay: company isn’t set up for you yet. Email us
bad_prepaid400, activating. That prepaid activation code doesn’t match one of the provider’s cards. Check it against the card
prepaid_used409, activating. That prepaid activation card was already used on another RetURN.org ID. Nothing was charged. Email [email protected] and we’ll help
no_card409. The provider has no saved card. Their administrator adds one in their portal, under Payment Method
card_failed409. The card was declined, or the bank wants the provider to confirm. Nothing was charged. You can try again once their bank has cleared it; they can also change the card in their portal, under Payment Method
payment_unconfirmed502. We couldn’t confirm the payment with the card processor. Send the same request again in a minute: the card is charged only once
family_bought409, 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_limited429, linking or filling in the details. The provider linked 30 RetURN.org IDs in the last hour, or 100 today. Try again later. Details for a RetURN.org ID the provider already holds aren’t limited
already_active409. This RetURN.org ID is already active. Check it with GET /ids/{id}
retired409, 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_other403. Another organization paid to activate this RetURN.org ID, so it’s theirs to set up
checkout_open409. 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
not_activatable404 or 409, activating or filling in the page. Another provider holds this RetURN.org ID, or it can’t be activated
in_progress409. The same activation or order is going through right now. Check it again in a minute
payments_unavailable409. Activations and orders can’t be paid for right now. Try again later
need_provider_as400. provider_as is funeral_home, crematory or both
not_paidNo longer sent since 2026-11-19: the family’s details can be filled in before activating
locked409, filling in the details. The family has activated this RetURN.org ID: only the family can change its page now
need_name400, filling in the page. Send full_name
need_email
need_consent
No longer sent since 2026-11-19: nobody is emailed
need_permission
incomplete
400, publishing the details. Send permission_by (who gave permission) and wish_first
activate_first409, publishing the details. The RetURN.org ID isn’t paid for: activate it first. Nothing was saved
published409, filling in the details. The page was published for the family: send it again with publish: true to change it, or publish: false to unpublish it
not_published409, unpublishing. The page isn’t published, or the provider didn’t publish it
page_written409, publishing the details. Someone already wrote on this page, so it can’t be published for the family
bad_subject_kind400, filling in the page. subject_kind is person or pet
bad_item400, ordering. item is activation_cards or ids
bad_quantity400, ordering. quantity is a whole number of packs: up to 20 of cards, or 100 of RetURN.org IDs
need_location400, ordering. The provider has more than one location: send location_id
need_address400, ordering. That location has no street address. The provider’s administrator adds one in their portal, under Locations
already_has_account409, setting up a provider. They already have an account: ask them to link you in their portal
idempotency_required400. Setting up a provider and ordering need an Idempotency-Key header
idempotency_reused409. That Idempotency-Key was used for a different request. Use a new one
bad_idempotency_key400. An Idempotency-Key is up to 120 characters
bad_field400, setting up a provider. A required field is missing or doesn’t look right. The message says which
need_provider_as400, setting up a provider. provider_as is funeral_home, crematory or both
need_org_number400, linking. Send org_number, the provider’s Organization ID
rate_limited429. Over 600 requests an hour for that provider. Wait the seconds in the Retry-After header and try again. RateLimit-Remaining on every answer says how many are left
no_endpoint404. There’s no such call. Check the path
method_not_allowed405. That call doesn’t take that method (GET, POST or DELETE)
server_error500. Something went wrong on our side. Try again; if it keeps happening, contact us
(none)400 with only a message, for the few refusals left without a code. The message says what to fix

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, an order is answered with an order number starting RO-SANDBOX- and never charged or shipped, and the answer says "sandbox": true. Nothing you do there earns or is billed. We still email the family, so use an email address of your own.

Register Your Company

We review every registration and email you when you’re approved, usually within one business day.

Frequently Asked Questions

What do we earn?

$1 for every RetURN.org ID activated through your software, whether the provider pays on their card or with one of their prepaid activation cards. If that payment is refunded, the $1 is too. When you bill the provider yourself, you keep your $1 then. An order of prepaid activation cards or RetURN.org IDs earns nothing. We pay what you’ve earned each quarter, by check or as store credit, or give it to scholarships for the funeral profession if you’d like. Your portal’s Payouts page shows what you’ve earned and lets you choose.

Can we see what the family writes?

No. Your software can fill in the family’s details and replace them until the family activates the RetURN.org ID. After that only the family can change the page, and nothing on it comes back to you.

Who pays for an activation?

Your choice, each time:

  • The provider’s card: we charge $17.99, plus sales tax where it applies, to the card they save in their portal, and pay you $1.
  • You: you bill the provider and keep your $1. We bill you $16.99 for each activation, once a month. We set this up with you first.
  • A prepaid activation card: the provider bought it ahead of time, so nothing is charged. Send the code from the card handed to the family.
Why does a provider approve the link?

A linked company can activate RetURN.org IDs and order prepaid activation cards and RetURN.org IDs on the provider’s card, so the provider says yes first. Anyone who knows an Organization ID can ask; only the provider can approve.

Why doesn’t linking a case put the provider’s name on the RetURN.org ID?

A case number is only your software’s note, and a RetURN.org ID can end up on a different urn than planned. The provider’s name goes on it when you link the provider to it (POST /ids/{id}/link), fill in the family’s details, or activate it. Linking and filling in are free.

What if a provider stops using our software?

They unlink you in their portal, under Connect Your Software, and your key stops working for them at once.

Book a Call

Tell us about your software and your customers. Pick a date and time that works for you. We’ll set aside 45 minutes on Google Meet, though most conversations take less time.

Prefer to send a message? Contact us.

Register your company