Skip to content

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.

  1. 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.
  2. Send it from your server as Authorization: Bearer <key>, never from a web page, where anyone can read it.
  3. 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.

KeyWhat it can do
Full keyEvery 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 locationA 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 keyEvery 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 keyActs 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.

RequestWhat it does
GET /whoamiYour company and your key, and can_be_charged: whether there’s a saved card to charge activations and orders to
GET /summaryYour 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 /ordersorders: 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 /locationsYour locations. has_address says whether an order can ship there
GET /prepaid-cardsHow 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 /eventsWhat happened to your organization and its RetURN.org IDs (see Keeping up)
GET /idsYour 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/reserveUrn manufacturers: reserve a block of new RetURN.org IDs (see below)
POST /ids/incorporateUrn manufacturers: mark RetURN.org IDs as used in products (see below)
GET /ids/{id}/artworkUrn manufacturers: one RetURN.org ID’s production artwork (see below)
GET /artwork/sheetUrn manufacturers: up to 100 RetURN.org IDs’ artwork on one sheet (see below)
POST /ids/distributeProviders: mark RetURN.org IDs as handed to a family (see below)
POST /ids/{id}/caseProviders: link a RetURN.org ID to a family’s case (see below)
DELETE /ids/{id}/caseProviders: unlink it
POST /ids/{id}/linkProviders: link your organization to a RetURN.org ID, free (see below)
POST /ids/{id}/activateProviders: activate a RetURN.org ID, on your saved card or with a prepaid activation card (see below)
POST /ids/{id}/familyProviders: 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 /ordersProviders: 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.

RequestWhat you get
GET /ids/{id}/artworkThe full RetURN.org ID, 2.000″ × 0.750″
GET /ids/{id}/artwork?kind=qrThe QR code alone, with its clear space
GET /artwork/sheet?ids=CP2-R6SY,HQ7-K2MDUp 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.

TypeWhat happened
paidA provider paid for the RetURN.org ID, on a card or with a prepaid activation card
refundedA payment for the RetURN.org ID was refunded
claimedThe family’s page was set up, by the family or by the funeral home for them (claimed is now true)
family_confirmedThe 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
distributedThe RetURN.org ID was marked as handed to a family
id_linkedA 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
approvedWe 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.

FieldWhat it is
idThe RetURN.org ID, for example CP2-R6SY
numberYour running count of printed and engraved RetURN.org IDs
stageavailable (reserved), incorporated (used in a product), distributed (handed to a family), claimed (the family’s page is set up) or inactive (retired or replaced)
paidWhether a funeral home has paid to activate it for the family
claimedWhether 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_confirmedWhether the family has confirmed their email address. GET /ids/{id} only
page_urlThe address of the RetURN.org ID’s page. It stays private until it’s published. GET /ids/{id} only
prefilledWhether your details for the family are waiting for the family to activate the RetURN.org ID. GET /ids/{id} only
publishedWhether 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_untilUntil 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_codeFull keys only, until it’s claimed. GET /ids/{id} only
case_refThe case you linked to it, or null. Nobody else sees it
code_freeWhether it activates with the RetURN.org ID alone, as one printed or engraved on an urn does
rolesHow 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_byThe 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.

CodeWhat it means
bad_key401. 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_only403. A read-only key can’t change anything. Use a full key
key_location403. 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_platform403. A software company’s key can’t make that call
key_not_platform403. Only a software company’s key can make that call
org_unavailable403. Your organization isn’t available to the API right now. Contact us
not_manufacturer403. Reserving, marking as used and artwork are for urn manufacturers. Providers order labels in the partner portal or with POST /orders
needs_onboarding403. Your company isn’t approved to print or engrave RetURN.org IDs yet. Contact us
not_provider403. 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_open403. An organization that also makes urns links cases, activates, fills in pages and orders in the partner portal for now
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
idempotency_required400. Reserving, ordering and setting up a provider need an Idempotency-Key header
bad_idempotency_key400. An Idempotency-Key is up to 120 characters
idempotency_reused409. That Idempotency-Key was used for a different request. Use a new one
not_found404. That RetURN.org ID doesn’t exist, or isn’t yours
location_not_found404. That location_id isn’t one of your company’s. GET /locations lists them
location_not_yours403. The key is limited to a different location
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
print_cap400. Too many reserved RetURN.org IDs are waiting to be used. Mark some as used, or contact us to raise your limit
wrong_stage409. 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_distributed409. Another call marked one of the RetURN.org IDs given to a family at the same moment. Nothing was marked; send them again
need_ids400. Send ids, a list of RetURN.org IDs
too_many_ids400. Too many RetURN.org IDs in one call: up to 5,000 to mark, or 100 on a sheet
bad_location400. location_id is the id of one of your locations, as a string
bad_kind400, artwork. kind is svg or qr
need_case_ref400. Send case_ref, your case number
not_linkable404, linking a case or your organization. Another provider holds or paid for this RetURN.org ID, or it no longer works
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. 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_case404, unlinking a case. You haven’t linked a case to this RetURN.org ID
bad_pay400, activating. pay is card, or send prepaid_code to use a prepaid activation card, not both
bad_prepaid400, activating. That prepaid activation code doesn’t match one of your 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
not_activatable404 or 409, activating or filling in the page. Another provider holds this RetURN.org ID, or it can’t be activated
already_active409, activating or linking. 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, activating. Another organization paid to activate this RetURN.org ID, so it’s theirs to set up
checkout_open409, 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_progress409, activating or ordering. The same activation or order is going through right now. Check it again in a minute
bad_year400, filling in the page. Years are four digits, between 1850 and now
bad_filter400, earnings. since, until, limit and offset are whole numbers, and org_number is an Organization ID
need_provider_as400. provider_as is funeral_home, crematory or both
no_card409, activating or ordering. There’s no saved card. Your administrator adds one in the partner portal, under Payment Method. Nothing was charged
card_failed409. 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_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
payments_unavailable409. Payments can’t be taken right now. Nothing was charged. Try again later
not_paidNo longer sent since 2026-11-19: the family’s details can be filled in before activating
need_name400, filling in the page. Send full_name
need_email
need_consent
No longer sent since 2026-11-19: nobody is emailed
need_permission400, publishing the details. Send permission_by, the name of the family member who gave permission
incomplete400, publishing the details. Send wish_first, their first choice
activate_first409, publishing the details. The RetURN.org ID isn’t paid for. Activate it first with POST /ids/{id}/activate. Nothing was saved
published409, 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_published409, unpublishing. The page isn’t published, or wasn’t published by you, so there’s nothing to unpublish
page_written409, publishing the details. Someone already wrote on this RetURN.org ID’s page, so it can’t be published for the family
bad_subject_kind400, filling in the page. subject_kind is person or pet
locked409, filling in the details. The family has activated this RetURN.org ID: only the family can change its page now
bad_item400, ordering. item is activation_cards or ids
bad_quantity400. 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_location400, ordering. You have more than one location: send location_id
need_address400, ordering. That location has no street address. Your administrator adds one in the partner portal, under Locations
rate_limited429. 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_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 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.