{
  "openapi": "3.0.3",
  "info": {
    "title": "RetURN.org Partner API",
    "version": "1.0 (2026-11-19)",
    "description": "The RetURN.org Partner API, v1. The full reference, with examples, is at https://return.org/industry-partners/api/ and, for software companies, https://return.org/industry-partners/software/#api.\n\nSend the key from your server as `Authorization: Bearer <key>`, never from a web page. Requests and answers are JSON, except artwork (SVG). Times are Unix seconds; money is in US cents.\n\nEach key may make 600 requests an hour; a software company's key, 600 an hour for each provider it acts for. Every answer to a key says what is left, a refusal included: `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` (seconds until a call is free again). A 401 has none: there's no key to count. Over that: 429 `rate_limited`, with a Retry-After header that says how long to wait. An urn manufacturer may also reserve 20 times an hour.\n\nEvery answer carries a `Request-Id` header; quote it to us about a call and we can find it. Every error answers `{\"ok\": false, \"error\": \"...\", \"code\": \"...\", \"request_id\": \"...\"}`. Act on `code`; `error` is for people. Each call lists the codes it can answer in `x-error-codes`. We may add a code: treat one you don't know by its HTTP status. Two codes come from the router itself, on any path: `no_endpoint` (404, no such call) and `method_not_allowed` (405, the path is right but the method isn't). `server_error` (500) is our fault: send the same request again later, with the same Idempotency-Key if it took one. Nothing the family writes on their page is ever returned.\n\nv1 stays v1: we add fields to answers and new calls, and never remove or rename one, or change what one means, without a v2 and notice to every key's organization. Ignore fields you don't know. Request bodies are up to 64 KB. An Idempotency-Key belongs to the organization, not to the API key: two integrations under one organization shouldn’t use the same values.\n\nTesting: a test key starts `ro_test_` and acts only for your sandbox funeral home. Used for a real provider, it answers 403 `test_key`, so a wrong RetURN-Organization header while testing never reaches a real provider's card. Your live key, the other way round, answers 403 `live_key` for a sandbox, so test with the test key. Ask info@RetURN.org for a sandbox; it comes with a test key.",
    "contact": {
      "name": "RetURN.org",
      "url": "https://return.org/contact/"
    },
    "license": {
      "name": "CC BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    }
  },
  "servers": [
    {
      "url": "https://return.org/api/portal/v1"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Everyone",
      "description": "Calls any key may make: who you are, your RetURN.org IDs, orders, locations and what happened to them."
    },
    {
      "name": "Urn manufacturers",
      "description": "For an urn manufacturer that prints or engraves RetURN.org IDs: reserving them, getting their artwork, and marking them used in a product."
    },
    {
      "name": "Providers",
      "description": "For a funeral home or crematory, or the software it uses: linking a case, activating a RetURN.org ID, filling in the family's page, and ordering."
    },
    {
      "name": "Software companies",
      "description": "For a software company's key only: the providers linked to it, setting one up, asking to link one, and what it earns."
    }
  ],
  "paths": {
    "/whoami": {
      "get": {
        "operationId": "getWhoami",
        "summary": "Your organization and your key",
        "description": "A good first call. A software company's key without RetURN-Organization gets its own company; with it, the provider.\n\nWho may call it: any key.\n\nError codes: `test_key`, `live_key`, `bad_key`, `organization_required`, `not_linked`, `org_unavailable`, `rate_limited`, `server_error`.",
        "x-error-codes": [
          "test_key",
          "live_key",
          "bad_key",
          "organization_required",
          "not_linked",
          "org_unavailable",
          "rate_limited",
          "server_error"
        ],
        "x-keys": "any key.",
        "responses": {
          "200": {
            "description": "Your organization and key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Whoami"
                },
                "example": {
                  "ok": true,
                  "organization": {
                    "id": "25252c91-9f57-4e4f-b099-21b4f97e15bd",
                    "name": "Lakeside Funeral Home",
                    "org_number": "ORG-EWQSFD",
                    "platform": false,
                    "manufacturer": false,
                    "point_of_sale": true,
                    "api_enabled": true,
                    "status": "active",
                    "sandbox": false
                  },
                  "can_be_charged": true,
                  "key": {
                    "name": "Case system",
                    "prefix": "ro_live_BREC",
                    "scope": "full",
                    "location_id": null,
                    "test": false
                  }
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Organization"
          }
        ],
        "tags": [
          "Everyone"
        ]
      }
    },
    "/summary": {
      "get": {
        "operationId": "getSummary",
        "summary": "RetURN.org IDs in numbers",
        "description": "Counts only: no family, no card.\n\nWho may call it: any key (full, read-only, or a software company's with RetURN-Organization).\n\nError codes: `test_key`, `live_key`, `bad_key`, `rate_limited`, `server_error`, `organization_required`, `not_linked`, `org_unavailable`.",
        "x-error-codes": [
          "test_key",
          "live_key",
          "bad_key",
          "rate_limited",
          "server_error",
          "organization_required",
          "not_linked",
          "org_unavailable"
        ],
        "x-keys": "any key (full, read-only, or a software company's with RetURN-Organization).",
        "responses": {
          "200": {
            "description": "The counts.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Summary"
                },
                "example": {
                  "ok": true,
                  "organization": {
                    "id": "25252c91-9f57-4e4f-b099-21b4f97e15bd",
                    "org_number": "ORG-EWQSFD",
                    "name": "Lakeside Funeral Home",
                    "manufacturer": false,
                    "provider": true
                  },
                  "location_id": null,
                  "ids": {
                    "total": 3,
                    "on_hand": 1,
                    "incorporated": 0,
                    "distributed": 1,
                    "paid": 0,
                    "claimed": 1,
                    "inactive": 0
                  },
                  "free_ids": {
                    "activations_counted": 0,
                    "per_pack": 15,
                    "pack_size": 25,
                    "toward_next_pack": 0,
                    "to_go": 15,
                    "packs_earned": 0,
                    "packs_shipped": 0,
                    "packs_on_the_way": 0
                  },
                  "monthly_activations": [
                    {
                      "month": "2025-12",
                      "count": 0
                    },
                    {
                      "month": "2026-01",
                      "count": 0
                    },
                    {
                      "month": "2026-02",
                      "count": 0
                    },
                    {
                      "month": "2026-03",
                      "count": 0
                    },
                    {
                      "month": "2026-04",
                      "count": 0
                    },
                    {
                      "month": "2026-05",
                      "count": 0
                    },
                    {
                      "month": "2026-06",
                      "count": 0
                    },
                    {
                      "month": "2026-07",
                      "count": 0
                    },
                    {
                      "month": "2026-08",
                      "count": 0
                    },
                    {
                      "month": "2026-09",
                      "count": 0
                    },
                    {
                      "month": "2026-10",
                      "count": 0
                    },
                    {
                      "month": "2026-11",
                      "count": 1
                    }
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Organization"
          }
        ],
        "tags": [
          "Everyone"
        ]
      }
    },
    "/orders": {
      "get": {
        "operationId": "listOrders",
        "summary": "Orders and purchases",
        "description": "orders: label shipments with status and tracking. purchases: what the organization bought from RetURN.org, including through POST /orders. Neither list pages: each answers the newest 100.\n\nWho may call it: any key (full, read-only, or a software company's with RetURN-Organization).\n\nError codes: `test_key`, `live_key`, `bad_key`, `rate_limited`, `server_error`, `organization_required`, `not_linked`, `org_unavailable`.",
        "x-error-codes": [
          "test_key",
          "live_key",
          "bad_key",
          "rate_limited",
          "server_error",
          "organization_required",
          "not_linked",
          "org_unavailable"
        ],
        "x-keys": "any key (full, read-only, or a software company's with RetURN-Organization).",
        "responses": {
          "200": {
            "description": "Label shipments and purchases, newest first.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Orders"
                },
                "example": {
                  "ok": true,
                  "orders": [],
                  "purchases": [
                    {
                      "order": "RO-1001",
                      "item": "activation_cards",
                      "packs": 1,
                      "card_packs": 0,
                      "status": "paid",
                      "created_at": 1794623086,
                      "paid_at": 1794623086,
                      "shipped_at": null,
                      "carrier": "",
                      "tracking": "",
                      "total_cents": 44975,
                      "tax_cents": 0,
                      "cards": {
                        "made": 25,
                        "used": 0,
                        "voided": 0
                      },
                      "ordered_through": null
                    }
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Organization"
          }
        ],
        "tags": [
          "Everyone"
        ]
      },
      "post": {
        "operationId": "createOrder",
        "summary": "Order packs on the saved card",
        "description": "Packs of 25 prepaid activation cards or 25 RetURN.org IDs, charged to the organization's saved card plus sales tax, shipped to one of its locations. A retry with the same Idempotency-Key gets the same order back and one charge.\n\nWho may call it: a provider's own full key for the whole organization, or a software company's key with RetURN-Organization, for a provider linked to it. The company's order is charged to that provider's saved card at the same prices, kept in the provider's order history as ordered through the company, and earns the company nothing.\n\nError codes: `payments_unavailable`, `idempotency_required`, `idempotency_reused`, `bad_json`, `too_large`, `bad_field`, `bad_item`, `bad_quantity`, `not_provider`, `location_not_found`, `need_location`, `need_address`, `no_card`, `card_failed`, `payment_unconfirmed`, `key_read_only`, `key_location`, `own_key_not_open`, `test_key`, `live_key`, `bad_key`, `rate_limited`, `server_error`, `organization_required`, `not_linked`, `org_unavailable`, `bad_idempotency_key`, `in_progress`.",
        "x-error-codes": [
          "payments_unavailable",
          "idempotency_required",
          "idempotency_reused",
          "bad_json",
          "too_large",
          "bad_field",
          "bad_item",
          "bad_quantity",
          "not_provider",
          "location_not_found",
          "need_location",
          "need_address",
          "no_card",
          "card_failed",
          "payment_unconfirmed",
          "key_read_only",
          "key_location",
          "own_key_not_open",
          "test_key",
          "live_key",
          "bad_key",
          "rate_limited",
          "server_error",
          "organization_required",
          "not_linked",
          "org_unavailable",
          "bad_idempotency_key",
          "in_progress"
        ],
        "x-keys": "a provider's own full key for the whole organization, or a software company's key with RetURN-Organization, for a provider linked to it.",
        "responses": {
          "200": {
            "description": "Paid for. `already: true` when an earlier try at this order went through.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderResponse"
                },
                "example": {
                  "ok": true,
                  "paid": true,
                  "order": "RO-1001",
                  "ship_to": "Branch A",
                  "item": "activation_cards",
                  "packs": 1
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "413": {
            "$ref": "#/components/responses/E413"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/Organization"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrderRequest"
              },
              "example": {
                "item": "activation_cards",
                "quantity": 1,
                "location_id": "7eccad49-c480-4b0b-a64e-479a8e870c6c"
              }
            }
          }
        },
        "tags": [
          "Providers"
        ]
      }
    },
    "/locations": {
      "get": {
        "operationId": "listLocations",
        "summary": "Active locations",
        "description": "For POST /orders' location_id. A key for one location sees that one.\n\nWho may call it: any key (full, read-only, or a software company's with RetURN-Organization).\n\nError codes: `test_key`, `live_key`, `bad_key`, `rate_limited`, `server_error`, `organization_required`, `not_linked`, `org_unavailable`.",
        "x-error-codes": [
          "test_key",
          "live_key",
          "bad_key",
          "rate_limited",
          "server_error",
          "organization_required",
          "not_linked",
          "org_unavailable"
        ],
        "x-keys": "any key (full, read-only, or a software company's with RetURN-Organization).",
        "responses": {
          "200": {
            "description": "The active locations.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Locations"
                },
                "example": {
                  "ok": true,
                  "locations": [
                    {
                      "id": "7eccad49-c480-4b0b-a64e-479a8e870c6c",
                      "name": "Branch A",
                      "city": "Bethesda",
                      "state": "MD",
                      "has_address": true
                    },
                    {
                      "id": "b36fb64e-1ac9-448e-b83e-7c93f4a2f990",
                      "name": "Branch B",
                      "city": "Rockville",
                      "state": "",
                      "has_address": false
                    }
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Organization"
          }
        ],
        "tags": [
          "Everyone"
        ]
      }
    },
    "/prepaid-cards": {
      "get": {
        "operationId": "getPrepaidCards",
        "summary": "Prepaid activation card counts",
        "description": "Unused, used and voided, and which RetURN.org ID each used card went on. Never a code.\n\nWho may call it: any key for the whole organization (not a key for one location).\n\nError codes: `key_location`, `test_key`, `live_key`, `bad_key`, `rate_limited`, `server_error`, `organization_required`, `not_linked`, `org_unavailable`.",
        "x-error-codes": [
          "key_location",
          "test_key",
          "live_key",
          "bad_key",
          "rate_limited",
          "server_error",
          "organization_required",
          "not_linked",
          "org_unavailable"
        ],
        "x-keys": "any key for the whole organization (not a key for one location).",
        "responses": {
          "200": {
            "description": "The counts.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrepaidCards"
                },
                "example": {
                  "ok": true,
                  "unused": 0,
                  "used": 0,
                  "voided": 0,
                  "used_on": []
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Organization"
          }
        ],
        "tags": [
          "Everyone"
        ]
      }
    },
    "/events": {
      "get": {
        "operationId": "listEvents",
        "summary": "What happened, oldest first",
        "description": "Events about the organization and its RetURN.org IDs after the id in `after`. Each says only its type, when, and which RetURN.org ID: never who, never what the family wrote. A key for one location sees only events on RetURN.org IDs at that location: none about the organization (`linked`, `approved`) and none on RetURN.org IDs with no location.\n\nWho may call it: any key (full, read-only, or a software company's with RetURN-Organization).\n\nError codes: `bad_cursor`, `test_key`, `live_key`, `bad_key`, `rate_limited`, `server_error`, `organization_required`, `not_linked`, `org_unavailable`.",
        "x-error-codes": [
          "bad_cursor",
          "test_key",
          "live_key",
          "bad_key",
          "rate_limited",
          "server_error",
          "organization_required",
          "not_linked",
          "org_unavailable"
        ],
        "x-keys": "any key (full, read-only, or a software company's with RetURN-Organization).",
        "responses": {
          "200": {
            "description": "Events after `after`, oldest first.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Events"
                },
                "example": {
                  "ok": true,
                  "events": [
                    {
                      "id": 20,
                      "type": "linked",
                      "at": 1794623086,
                      "return_id": null
                    },
                    {
                      "id": 30,
                      "type": "distributed",
                      "at": 1794623086,
                      "return_id": "X47-ZEQH"
                    },
                    {
                      "id": 31,
                      "type": "case_linked",
                      "at": 1794623086,
                      "return_id": "428-9BK9"
                    }
                  ],
                  "next_after": 31
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Organization"
          },
          {
            "name": "after",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            },
            "description": "The `id` of the last event you've read, or 0 for the first. Send `next_after` from the last answer."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 100
            },
            "description": "How many events to answer, up to 200. A value that isn't a number is `400 bad_cursor`."
          }
        ],
        "tags": [
          "Everyone"
        ]
      }
    },
    "/ids": {
      "get": {
        "operationId": "listIds",
        "summary": "RetURN.org IDs, newest change first",
        "description": "Every RetURN.org ID the organization holds. case_ref finds the one this caller linked to that case, among those the provider holds. Page with `limit` and `offset`; `total` counts every match. To keep up with changes, poll `GET /events` instead: it has a real cursor.\n\nWho may call it: any key (full, read-only, or a software company's with RetURN-Organization).\n\nError codes: `bad_stage`, `bad_updated_since`, `location_not_found`, `location_not_yours`, `test_key`, `live_key`, `bad_cursor`, `bad_key`, `rate_limited`, `server_error`, `organization_required`, `not_linked`, `org_unavailable`.",
        "x-error-codes": [
          "bad_stage",
          "bad_updated_since",
          "location_not_found",
          "location_not_yours",
          "test_key",
          "live_key",
          "bad_cursor",
          "bad_key",
          "rate_limited",
          "server_error",
          "organization_required",
          "not_linked",
          "org_unavailable"
        ],
        "x-keys": "any key (full, read-only, or a software company's with RetURN-Organization).",
        "responses": {
          "200": {
            "description": "A page of RetURN.org IDs.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IdList"
                },
                "example": {
                  "ok": true,
                  "total": 3,
                  "ids": [
                    {
                      "id": "NA8-C26Z",
                      "stage": "available",
                      "assignment": "label",
                      "product": "",
                      "sku": "",
                      "batch": null,
                      "internal_ref": "",
                      "physical_type": "label",
                      "location_id": "7eccad49-c480-4b0b-a64e-479a8e870c6c",
                      "location": "Branch A",
                      "roles": [
                        "point_of_sale"
                      ],
                      "created_at": 1794623086,
                      "incorporated_at": null,
                      "distributed_at": null,
                      "claimed_at": null,
                      "updated_at": 1794623086,
                      "claimed": false,
                      "paid": false,
                      "code_free": false,
                      "replaced_by": null,
                      "number": null,
                      "case_ref": null
                    },
                    {
                      "id": "X47-ZEQH",
                      "stage": "distributed",
                      "assignment": "label",
                      "product": "",
                      "sku": "",
                      "batch": null,
                      "internal_ref": "Case 4412",
                      "physical_type": "label",
                      "location_id": "7eccad49-c480-4b0b-a64e-479a8e870c6c",
                      "location": "Branch A",
                      "roles": [
                        "point_of_sale"
                      ],
                      "created_at": 1794623086,
                      "incorporated_at": null,
                      "distributed_at": 1794623086,
                      "claimed_at": null,
                      "updated_at": 1794623086,
                      "claimed": false,
                      "paid": false,
                      "code_free": false,
                      "replaced_by": null,
                      "number": null,
                      "case_ref": null
                    }
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Organization"
          },
          {
            "name": "stage",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "available",
                "incorporated",
                "distributed",
                "claimed",
                "inactive"
              ]
            },
            "description": "Only RetURN.org IDs at this stage."
          },
          {
            "name": "location_id",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Only RetURN.org IDs at this location (`GET /locations`)."
          },
          {
            "name": "updated_since",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Only RetURN.org IDs whose record changed at or after this time (Unix seconds). Send the largest `updated_at` you've seen; the RetURN.org IDs from that second come back again, so skip the ones you have. `GET /events` is cheaper to poll."
          },
          {
            "name": "case_ref",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 120
            },
            "description": "Only the RetURN.org ID this caller linked to this case (`POST /ids/{id}/case`), among those the organization holds."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            },
            "description": "Page size, up to 200 (default 50). A whole number, or 400 bad_cursor."
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            },
            "description": "How many to skip, for the next page. A whole number, or 400 bad_cursor."
          }
        ],
        "tags": [
          "Everyone"
        ]
      }
    },
    "/ids/{id}": {
      "get": {
        "operationId": "getId",
        "summary": "One RetURN.org ID",
        "description": "With family_confirmed, page_url and editable_until, and for a full key the activation_code until it is claimed. For a RetURN.org ID this caller linked to a case but the provider doesn't hold yet, a CaseOnlyRecord.\n\nWho may call it: any key (full, read-only, or a software company's with RetURN-Organization).\n\nError codes: `not_found`, `test_key`, `live_key`, `bad_key`, `rate_limited`, `server_error`, `organization_required`, `not_linked`, `org_unavailable`.",
        "x-error-codes": [
          "not_found",
          "test_key",
          "live_key",
          "bad_key",
          "rate_limited",
          "server_error",
          "organization_required",
          "not_linked",
          "org_unavailable"
        ],
        "x-keys": "any key (full, read-only, or a software company's with RetURN-Organization).",
        "responses": {
          "200": {
            "description": "The RetURN.org ID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IdOne"
                },
                "example": {
                  "ok": true,
                  "id_record": {
                    "id": "NA8-C26Z",
                    "stage": "available",
                    "assignment": "label",
                    "product": "",
                    "sku": "",
                    "batch": null,
                    "internal_ref": "",
                    "physical_type": "label",
                    "location_id": "7eccad49-c480-4b0b-a64e-479a8e870c6c",
                    "location": "Branch A",
                    "roles": [
                      "point_of_sale"
                    ],
                    "created_at": 1794623086,
                    "incorporated_at": null,
                    "distributed_at": null,
                    "claimed_at": null,
                    "updated_at": 1794623086,
                    "claimed": false,
                    "paid": false,
                    "code_free": false,
                    "replaced_by": null,
                    "number": null,
                    "case_ref": null,
                    "family_confirmed": false,
                    "page_url": "https://return.org/id/NA8-C26Z/",
                    "editable_until": null,
                    "prefilled": false,
                    "published": false,
                    "activation_code": "CVK3-RTSN"
                  }
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/pid"
          },
          {
            "$ref": "#/components/parameters/Organization"
          }
        ],
        "tags": [
          "Everyone"
        ]
      }
    },
    "/ids/reserve": {
      "post": {
        "operationId": "reserveIds",
        "summary": "Reserve a block of RetURN.org IDs",
        "description": "For an urn manufacturer to print or engrave. Nothing is charged. An organization that is both an urn manufacturer and a provider says which with `role`. role point_of_sale reserves up to 5,000, with no `number` and no `block_id`, and those RetURN.org IDs need their codes.\n\nWho may call it: a full key of an urn manufacturer (a key for one location reserves at that location).\n\nError codes: `not_manufacturer`, `idempotency_required`, `bad_idempotency_key`, `idempotency_reused`, `bad_json`, `too_large`, `bad_field`, `needs_onboarding`, `print_cap`, `location_not_found`, `location_not_yours`, `key_read_only`, `key_platform`, `rate_limited`, `test_key`, `live_key`, `bad_key`, `server_error`, `bad_quantity`, `bad_location`, `not_provider`.",
        "x-error-codes": [
          "not_manufacturer",
          "idempotency_required",
          "bad_idempotency_key",
          "idempotency_reused",
          "bad_json",
          "too_large",
          "bad_field",
          "needs_onboarding",
          "print_cap",
          "location_not_found",
          "location_not_yours",
          "key_read_only",
          "key_platform",
          "rate_limited",
          "test_key",
          "live_key",
          "bad_key",
          "server_error",
          "bad_quantity",
          "bad_location",
          "not_provider"
        ],
        "x-keys": "a full key of an urn manufacturer (a key for one location may reserve too; send its location_id to reserve there).",
        "responses": {
          "200": {
            "description": "The block, with each RetURN.org ID's code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReserveResponse"
                },
                "example": {
                  "ok": true,
                  "count": 2,
                  "ids": [
                    {
                      "id": "52T-JZBA",
                      "activation_code": "7HZD-RH39",
                      "stage": "available",
                      "assignment": "api",
                      "block_id": "051d5382-fee4-4b31-9f39-bd640c12784e",
                      "number": 1
                    },
                    {
                      "id": "0AF-33H9",
                      "activation_code": "94MW-SCPP",
                      "stage": "available",
                      "assignment": "api",
                      "block_id": "051d5382-fee4-4b31-9f39-bd640c12784e",
                      "number": 2
                    }
                  ],
                  "artwork_version": "1.0"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "413": {
            "$ref": "#/components/responses/E413"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReserveRequest"
              },
              "example": {
                "quantity": 2,
                "product": "Oak Keepsake Urn",
                "sku": "OAK-K1",
                "batch": "2026-11-A"
              }
            }
          }
        },
        "tags": [
          "Urn manufacturers"
        ]
      }
    },
    "/ids/incorporate": {
      "post": {
        "operationId": "markIdsIncorporated",
        "summary": "Mark RetURN.org IDs as used in products",
        "description": "All or nothing. Marking one already marked is fine. Safe to send again: an earlier date is kept.\n\nWho may call it: a full key of an urn manufacturer.\n\nError codes: `bad_json`, `too_large`, `bad_field`, `not_found`, `key_read_only`, `key_platform`, `test_key`, `live_key`, `bad_key`, `rate_limited`, `server_error`, `need_ids`, `too_many_ids`, `wrong_stage`, `not_manufacturer`.",
        "x-error-codes": [
          "bad_json",
          "too_large",
          "bad_field",
          "not_found",
          "key_read_only",
          "key_platform",
          "test_key",
          "live_key",
          "bad_key",
          "rate_limited",
          "server_error",
          "need_ids",
          "too_many_ids",
          "wrong_stage",
          "not_manufacturer"
        ],
        "x-keys": "a full key of an urn manufacturer.",
        "responses": {
          "200": {
            "description": "All of them are marked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Count"
                },
                "example": {
                  "ok": true,
                  "count": 1
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "413": {
            "$ref": "#/components/responses/E413"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/IncorporateRequest"
              },
              "example": {
                "ids": [
                  "52T-JZBA"
                ],
                "sku": "OAK-K1"
              }
            }
          }
        },
        "tags": [
          "Urn manufacturers"
        ]
      }
    },
    "/ids/distribute": {
      "post": {
        "operationId": "markIdsDistributed",
        "summary": "Mark RetURN.org IDs as handed to a family",
        "description": "Safe to send again: a RetURN.org ID you already gave to a family comes back in `already` and is not marked twice. Otherwise all or nothing: one that can't be given to a family answers `wrong_stage`, with it in `ids`, and nothing is marked. Activating does this too.\n\nWho may call it: a full key of an organization that hands RetURN.org IDs to families.\n\nError codes: `bad_json`, `too_large`, `bad_field`, `not_found`, `already_distributed`, `location_not_found`, `location_not_yours`, `key_read_only`, `key_platform`, `test_key`, `live_key`, `bad_key`, `rate_limited`, `server_error`, `need_ids`, `too_many_ids`, `wrong_stage`, `bad_location`, `not_provider`.",
        "x-error-codes": [
          "bad_json",
          "too_large",
          "bad_field",
          "not_found",
          "already_distributed",
          "location_not_found",
          "location_not_yours",
          "key_read_only",
          "key_platform",
          "test_key",
          "live_key",
          "bad_key",
          "rate_limited",
          "server_error",
          "need_ids",
          "too_many_ids",
          "wrong_stage",
          "bad_location",
          "not_provider"
        ],
        "x-keys": "a full key of an organization that hands RetURN.org IDs to families.",
        "responses": {
          "200": {
            "description": "All of them are marked, or were already.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DistributeResponse"
                },
                "example": {
                  "ok": true,
                  "count": 1,
                  "already": []
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "413": {
            "$ref": "#/components/responses/E413"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DistributeRequest"
              },
              "example": {
                "ids": [
                  "X47-ZEQH"
                ],
                "location_id": "7eccad49-c480-4b0b-a64e-479a8e870c6c",
                "reference": "Case 4412"
              }
            }
          }
        },
        "tags": [
          "Providers"
        ]
      }
    },
    "/ids/{id}/artwork": {
      "get": {
        "operationId": "getIdArtwork",
        "summary": "Production artwork for one RetURN.org ID",
        "description": "svg (the default): the full RetURN.org ID, 2.000in x 0.750in, every letter an outline. qr: the QR code alone with its clear space.\n\nWho may call it: any key of an urn manufacturer.\n\nError codes: `not_manufacturer`, `not_found`, `test_key`, `live_key`, `bad_key`, `rate_limited`, `server_error`, `organization_required`, `not_linked`, `org_unavailable`, `bad_kind`.",
        "x-error-codes": [
          "not_manufacturer",
          "not_found",
          "test_key",
          "live_key",
          "bad_key",
          "rate_limited",
          "server_error",
          "organization_required",
          "not_linked",
          "org_unavailable",
          "bad_kind"
        ],
        "x-keys": "any key of an urn manufacturer.",
        "responses": {
          "200": {
            "description": "An SVG file, sent as a download named after the RetURN.org ID.",
            "content": {
              "image/svg+xml": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Content-Disposition": {
                "description": "`attachment`, with the file's name.",
                "schema": {
                  "type": "string",
                  "example": "attachment; filename=\"CP2-R6SY.svg\""
                }
              },
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/pid"
          },
          {
            "$ref": "#/components/parameters/Organization"
          },
          {
            "name": "kind",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "svg",
                "qr"
              ],
              "default": "svg"
            },
            "description": "`svg` (the default): the full RetURN.org ID. `qr`: the QR code alone."
          }
        ],
        "tags": [
          "Urn manufacturers"
        ]
      }
    },
    "/artwork/sheet": {
      "get": {
        "operationId": "getArtworkSheet",
        "summary": "Artwork for up to 100 RetURN.org IDs on one sheet",
        "description": "Four across, with a red hairline cut line around each.\n\nWho may call it: any key of an urn manufacturer.\n\nError codes: `not_manufacturer`, `not_found`, `test_key`, `live_key`, `bad_key`, `rate_limited`, `server_error`, `organization_required`, `not_linked`, `org_unavailable`, `need_ids`, `too_many_ids`.",
        "x-error-codes": [
          "not_manufacturer",
          "not_found",
          "test_key",
          "live_key",
          "bad_key",
          "rate_limited",
          "server_error",
          "organization_required",
          "not_linked",
          "org_unavailable",
          "need_ids",
          "too_many_ids"
        ],
        "x-keys": "any key of an urn manufacturer.",
        "responses": {
          "200": {
            "description": "An SVG file, sent as a download.",
            "content": {
              "image/svg+xml": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Content-Disposition": {
                "description": "`attachment`, with the file's name.",
                "schema": {
                  "type": "string",
                  "example": "attachment; filename=\"CP2-R6SY.svg\""
                }
              },
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Organization"
          },
          {
            "name": "ids",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "RetURN.org IDs separated by commas, up to 100."
          }
        ],
        "tags": [
          "Urn manufacturers"
        ]
      }
    },
    "/ids/{id}/case": {
      "post": {
        "operationId": "linkCase",
        "summary": "Link a family's case to a RetURN.org ID",
        "description": "Records the case for this caller only and puts nothing on the RetURN.org ID. Sending it again replaces it.\n\nWho may call it: a provider's own full key for the whole organization (a pure provider whose API RetURN.org turned on), or a software company's key with RetURN-Organization. Not a read-only key, not a key for one location.\n\nError codes: `need_case_ref`, `not_linkable`, `bad_json`, `too_large`, `bad_field`, `key_read_only`, `key_location`, `not_provider`, `own_key_not_open`, `test_key`, `live_key`, `bad_key`, `rate_limited`, `server_error`, `organization_required`, `not_linked`, `org_unavailable`.",
        "x-error-codes": [
          "need_case_ref",
          "not_linkable",
          "bad_json",
          "too_large",
          "bad_field",
          "key_read_only",
          "key_location",
          "not_provider",
          "own_key_not_open",
          "test_key",
          "live_key",
          "bad_key",
          "rate_limited",
          "server_error",
          "organization_required",
          "not_linked",
          "org_unavailable"
        ],
        "x-keys": "a provider's own full key for the whole organization (a pure provider whose API RetURN.org turned on), or a software company's key with RetURN-Organization. Not a read-only key, not a key for one location.",
        "responses": {
          "200": {
            "description": "Linked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CaseResponse"
                },
                "example": {
                  "ok": true,
                  "id": "428-9BK9",
                  "case_ref": "LAKESIDE-2026-0412",
                  "claimed": false,
                  "paid": false
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "413": {
            "$ref": "#/components/responses/E413"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/pid"
          },
          {
            "$ref": "#/components/parameters/Organization"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CaseRequest"
              },
              "example": {
                "case_ref": "LAKESIDE-2026-0412"
              }
            }
          }
        },
        "tags": [
          "Providers"
        ]
      },
      "delete": {
        "operationId": "unlinkCase",
        "summary": "Unlink a case",
        "description": "Removes the case this caller linked, as when the wrong urn was linked. Sending it again after it worked answers `404 no_case`: treat that as done.\n\nWho may call it: a provider's own full key for the whole organization (a pure provider whose API RetURN.org turned on), or a software company's key with RetURN-Organization. Not a read-only key, not a key for one location.\n\nError codes: `no_case`, `key_read_only`, `key_location`, `not_provider`, `own_key_not_open`, `test_key`, `live_key`, `bad_key`, `rate_limited`, `server_error`, `organization_required`, `not_linked`, `org_unavailable`.",
        "x-error-codes": [
          "no_case",
          "key_read_only",
          "key_location",
          "not_provider",
          "own_key_not_open",
          "test_key",
          "live_key",
          "bad_key",
          "rate_limited",
          "server_error",
          "organization_required",
          "not_linked",
          "org_unavailable"
        ],
        "x-keys": "a provider's own full key for the whole organization (a pure provider whose API RetURN.org turned on), or a software company's key with RetURN-Organization. Not a read-only key, not a key for one location.",
        "responses": {
          "200": {
            "description": "Unlinked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnlinkResponse"
                },
                "example": {
                  "ok": true,
                  "id": "428-9BK9",
                  "case_ref": null
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/pid"
          },
          {
            "$ref": "#/components/parameters/Organization"
          }
        ],
        "tags": [
          "Providers"
        ]
      }
    },
    "/ids/{id}/link": {
      "post": {
        "operationId": "linkId",
        "summary": "Link your organization to a RetURN.org ID, free",
        "description": "Links this provider to an unclaimed RetURN.org ID as its point of sale, for free: its name goes on the ID, as on an urn's ID linked in the partner portal. Nothing is charged, nobody is emailed, and a scan shows nothing new: the family still activates the ID, free once a provider has paid for it (POST /ids/{id}/activate, $17.99) and $29.99 if not. Refused for an ID another provider holds or paid for, a retired one, one the family already activated, a family's own (bought from RetURN.org, or a replacement label for theirs: `409 family_bought`), and between the sandbox and real IDs. New links are limited to 30 an hour and 100 a day per organization (`429 link_limited`). Sending it again changes nothing and answers `already: true`.\n\nWho may call it: a provider's own full key for the whole organization (a pure provider whose API RetURN.org turned on), or a software company's key with RetURN-Organization. Not a read-only key, not a key for one location.\n\nError codes: `need_provider_as`, `not_linkable`, `retired`, `already_active`, `family_bought`, `link_limited`, `bad_json`, `too_large`, `bad_field`, `key_read_only`, `key_location`, `not_provider`, `own_key_not_open`, `test_key`, `live_key`, `bad_key`, `rate_limited`, `server_error`, `organization_required`, `not_linked`, `org_unavailable`.",
        "x-error-codes": [
          "need_provider_as",
          "not_linkable",
          "retired",
          "already_active",
          "family_bought",
          "link_limited",
          "bad_json",
          "too_large",
          "bad_field",
          "key_read_only",
          "key_location",
          "not_provider",
          "own_key_not_open",
          "test_key",
          "live_key",
          "bad_key",
          "rate_limited",
          "server_error",
          "organization_required",
          "not_linked",
          "org_unavailable"
        ],
        "x-keys": "a provider's own full key for the whole organization (a pure provider whose API RetURN.org turned on), or a software company's key with RetURN-Organization. Not a read-only key, not a key for one location.",
        "responses": {
          "200": {
            "description": "Linked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IdLinkResponse"
                },
                "example": {
                  "ok": true,
                  "id": "428-9BK9",
                  "linked": true,
                  "already": false,
                  "claimed": false,
                  "paid": false,
                  "price_cents": 1799
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "413": {
            "$ref": "#/components/responses/E413"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/pid"
          },
          {
            "$ref": "#/components/parameters/Organization"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/IdLinkRequest"
              },
              "example": {
                "provider_as": "funeral_home"
              }
            }
          }
        },
        "tags": [
          "Providers"
        ]
      }
    },
    "/ids/{id}/activate": {
      "post": {
        "operationId": "activateId",
        "summary": "Activate a RetURN.org ID",
        "description": "Pays for it ($17.99), so the family isn't charged, and puts the provider on it. Linking and filling in the family's details are free (POST /ids/{id}/link and /family); this is the step that costs. Safe to retry: it is paid for once, and a payment started earlier is checked before any new one.\n\nWho may call it: a provider's own full key for the whole organization (a pure provider whose API RetURN.org turned on), or a software company's key with RetURN-Organization. Not a read-only key, not a key for one location. pay: company is for a software company only.\n\nError codes: `bad_pay`, `billing_not_set_up`, `not_activatable`, `already_active`, `bad_prepaid`, `prepaid_used`, `payments_unavailable`, `no_card`, `in_progress`, `card_failed`, `payment_unconfirmed`, `need_provider_as`, `bad_json`, `too_large`, `bad_field`, `key_read_only`, `key_location`, `not_provider`, `own_key_not_open`, `test_key`, `live_key`, `bad_key`, `rate_limited`, `server_error`, `organization_required`, `not_linked`, `org_unavailable`, `retired`, `paid_by_other`, `checkout_open`.",
        "x-error-codes": [
          "bad_pay",
          "billing_not_set_up",
          "not_activatable",
          "already_active",
          "bad_prepaid",
          "prepaid_used",
          "payments_unavailable",
          "no_card",
          "in_progress",
          "card_failed",
          "payment_unconfirmed",
          "need_provider_as",
          "bad_json",
          "too_large",
          "bad_field",
          "key_read_only",
          "key_location",
          "not_provider",
          "own_key_not_open",
          "test_key",
          "live_key",
          "bad_key",
          "rate_limited",
          "server_error",
          "organization_required",
          "not_linked",
          "org_unavailable",
          "retired",
          "paid_by_other",
          "checkout_open"
        ],
        "x-keys": "a provider's own full key for the whole organization (a pure provider whose API RetURN.org turned on), or a software company's key with RetURN-Organization. Not a read-only key, not a key for one location. pay: company is for a software company only.",
        "responses": {
          "200": {
            "description": "Paid for. `already: true` when nothing new was paid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ActivateResponse"
                },
                "example": {
                  "ok": true,
                  "id": "428-9BK9",
                  "paid": true,
                  "pay": "card",
                  "price_cents": 1799
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "413": {
            "$ref": "#/components/responses/E413"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/pid"
          },
          {
            "$ref": "#/components/parameters/Organization"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ActivateRequest"
              },
              "example": {
                "pay": "card"
              }
            }
          }
        },
        "tags": [
          "Providers"
        ]
      }
    },
    "/ids/{id}/family": {
      "post": {
        "operationId": "fillFamilyPage",
        "summary": "Fill in the family's details, free",
        "description": "The family's details, filled in for them, before or after you pay to activate the RetURN.org ID (2026-11-19). Free: it links your organization to the ID as POST /ids/{id}/link does and keeps the details private. Nothing is charged, nobody is emailed, a scan shows nothing, and the ID stays unclaimed. When the family activates it themselves (free if a provider paid, $29.99 if not), their page starts from these details, and it stays private until they publish it. Send it again to replace the details, until the family activates it; after that it answers `409 locked`. Nothing the family wrote is ever sent back.\n\nPublishing for the family (2026-11-19): send `publish: true` with `wish_first` and `permission_by` (the name of the family member who gave permission) and the page is published now, so a scan shows it before anyone activates the RetURN.org ID. Only once the ID is paid for: unpaid, it answers `409 activate_first` and saves nothing, so call POST /ids/{id}/activate first. Without `permission_by` it answers `400 need_permission`, without `wish_first` `400 incomplete`. Once published, send it again with `publish: true` to change the page; without it, `409 published`. Nobody is emailed.\n\nUnpublishing (2026-11-19): send `publish: false` on a page you published and it is private again, as before you published it: a scan shows nothing, and the details stay with you to change and publish again. `{\"publish\": false}` alone keeps the details you sent before; with details, those are kept instead. The answer says `unpublished: true`. Only the provider that published the page, and only until the family activates the RetURN.org ID: after that the page is theirs (`409 locked`). On a page that isn't published, `{\"publish\": false}` alone answers `409 not_published`; with details it saves them privately, as always. Leaving `publish` out of a call on a published page still answers `409 published`, so nothing is unpublished by accident. Nobody is emailed; GET /events says `unpublished`. The family can still activate the ID (free, as it is paid for); their page is the published one, still public, and from then on only they change it.\n\nUntil 2026-11-19 this needed the activation first (`409 not_paid`), set up the page (claimed) and emailed the family; it does neither now. `email` and `consent` are still accepted and no longer needed.\n\nWho may call it: a provider's own full key for the whole organization (a pure provider whose API RetURN.org turned on), or a software company's key with RetURN-Organization. Not a read-only key, not a key for one location. Only the provider holding the RetURN.org ID, or one free to link it.\n\nError codes: `need_name`, `bad_subject_kind`, `bad_year`, `need_permission`, `incomplete`, `activate_first`, `published`, `not_published`, `page_written`, `not_activatable`, `retired`, `locked`, `family_bought`, `link_limited`, `bad_json`, `too_large`, `bad_field`, `key_read_only`, `key_location`, `not_provider`, `own_key_not_open`, `test_key`, `live_key`, `bad_key`, `rate_limited`, `server_error`, `organization_required`, `not_linked`, `org_unavailable`.",
        "x-error-codes": [
          "need_name",
          "bad_subject_kind",
          "bad_year",
          "need_permission",
          "incomplete",
          "activate_first",
          "published",
          "not_published",
          "page_written",
          "not_activatable",
          "retired",
          "locked",
          "family_bought",
          "link_limited",
          "bad_json",
          "too_large",
          "bad_field",
          "key_read_only",
          "key_location",
          "not_provider",
          "own_key_not_open",
          "test_key",
          "live_key",
          "bad_key",
          "rate_limited",
          "server_error",
          "organization_required",
          "not_linked",
          "org_unavailable"
        ],
        "x-keys": "a provider's own full key for the whole organization (a pure provider whose API RetURN.org turned on), or a software company's key with RetURN-Organization. Not a read-only key, not a key for one location. Only the provider holding the RetURN.org ID, or one free to link it.",
        "responses": {
          "200": {
            "description": "Saved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FamilyResponse"
                },
                "example": {
                  "ok": true,
                  "id": "428-9BK9",
                  "saved": true,
                  "linked": true,
                  "published": false,
                  "unpublished": false,
                  "family_emailed": false,
                  "editable_until": null,
                  "paid": false,
                  "price_cents": 1799
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "413": {
            "$ref": "#/components/responses/E413"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/pid"
          },
          {
            "$ref": "#/components/parameters/Organization"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FamilyRequest"
              },
              "example": {
                "full_name": "Ruth Ann Miller",
                "birth_year": 1941,
                "death_year": 2026
              }
            }
          }
        },
        "tags": [
          "Providers"
        ]
      }
    },
    "/platform/organizations": {
      "get": {
        "operationId": "listLinkedProviders",
        "summary": "Your linked providers",
        "description": "And the ones you asked to link that haven't answered yet.\n\nWho may call it: a software company's key.\n\nError codes: `key_not_platform`, `bad_key`, `rate_limited`, `server_error`.",
        "x-error-codes": [
          "key_not_platform",
          "bad_key",
          "rate_limited",
          "server_error"
        ],
        "x-keys": "a software company's key.",
        "responses": {
          "200": {
            "description": "Linked providers, and the ones still waiting to answer.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlatformOrganizations"
                },
                "example": {
                  "ok": true,
                  "organizations": [
                    {
                      "org_number": "ORG-EWQSFD",
                      "name": "Lakeside Funeral Home",
                      "status": "active",
                      "linked_via": "provider",
                      "linked_at": 1794623086,
                      "your_ref": ""
                    }
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        },
        "tags": [
          "Software companies"
        ]
      },
      "post": {
        "operationId": "setUpProvider",
        "summary": "Set up an account for a provider that has none",
        "description": "It waits for RetURN.org's approval, its contact is emailed an invitation, and it is linked to you at once. Your key works for it once it is approved. Your company may set up 20 accounts an hour and 100 a day, across all its keys; over that, 429 rate_limited with Retry-After. A test key gets the same checks and an answer with `sandbox: true`, and nothing is made or emailed.\n\nWho may call it: a software company's key.\n\nError codes: `idempotency_required`, `bad_idempotency_key`, `idempotency_reused`, `already_has_account`, `bad_json`, `too_large`, `key_not_platform`, `bad_key`, `rate_limited`, `server_error`, `bad_field`, `need_provider_as`.",
        "x-error-codes": [
          "idempotency_required",
          "bad_idempotency_key",
          "idempotency_reused",
          "already_has_account",
          "bad_json",
          "too_large",
          "key_not_platform",
          "bad_key",
          "rate_limited",
          "server_error",
          "bad_field",
          "need_provider_as"
        ],
        "x-keys": "a software company's key.",
        "responses": {
          "200": {
            "description": "Set up and waiting for approval. A retry with the same Idempotency-Key gets this same answer.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProvisionResponse"
                },
                "example": {
                  "ok": true,
                  "org_number": "ORG-6CFDE2",
                  "status": "pending",
                  "invited": true
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "413": {
            "$ref": "#/components/responses/E413"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProvisionRequest"
              },
              "example": {
                "organization": {
                  "name": "Shady Oaks Cremation",
                  "provider_as": "both",
                  "address": {
                    "address1": "12 Elm St",
                    "city": "Frederick",
                    "state": "MD",
                    "postal": "21701"
                  }
                },
                "contact": {
                  "first_name": "Dana",
                  "last_name": "Reyes",
                  "email": "dana@shadyoaks.example"
                },
                "your_ref": "cust-5521"
              }
            }
          }
        },
        "tags": [
          "Software companies"
        ]
      }
    },
    "/platform/organizations/link": {
      "post": {
        "operationId": "askToLinkProvider",
        "summary": "Ask to link a provider that has an account",
        "description": "The provider's administrator approves it in the partner portal; until then nothing is linked. A test key can't ask a real provider (403 test_key).\n\nWho may call it: a software company's key.\n\nError codes: `bad_json`, `too_large`, `bad_field`, `key_not_platform`, `test_key`, `live_key`, `bad_key`, `rate_limited`, `server_error`, `need_org_number`.",
        "x-error-codes": [
          "bad_json",
          "too_large",
          "bad_field",
          "key_not_platform",
          "test_key",
          "live_key",
          "bad_key",
          "rate_limited",
          "server_error",
          "need_org_number"
        ],
        "x-keys": "a software company's key.",
        "responses": {
          "200": {
            "description": "Asked, or already linked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LinkResponse"
                },
                "example": {
                  "ok": true,
                  "org_number": "ORG-K7M2QX",
                  "status": "waiting_for_provider"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "413": {
            "$ref": "#/components/responses/E413"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LinkRequest"
              },
              "example": {
                "org_number": "ORG-K7M2QX"
              }
            }
          }
        },
        "tags": [
          "Software companies"
        ]
      }
    },
    "/platform/earnings": {
      "get": {
        "operationId": "getEarnings",
        "summary": "What you've earned, and what you're billed",
        "description": "Your $1 for each activation through your key, paid on the provider's saved card or with one of its prepaid activation cards, newest first. We pay it each quarter, as you choose on your portal's Payouts page. Activations you bill yourself (pay: company) are in `billed`, not here: you keep that $1. The totals count every match that wasn't reversed (items include those, with `reversed: true`); items pages with limit and offset.\n\nWho may call it: a software company's key.\n\nError codes: `bad_filter`, `key_not_platform`, `bad_key`, `rate_limited`, `server_error`.",
        "x-error-codes": [
          "bad_filter",
          "key_not_platform",
          "bad_key",
          "rate_limited",
          "server_error"
        ],
        "x-keys": "a software company's key.",
        "responses": {
          "200": {
            "description": "Earnings and billing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Earnings"
                },
                "example": {
                  "ok": true,
                  "earnings": {
                    "activations": 0,
                    "total_cents": 0,
                    "per_activation_cents": 100,
                    "items": []
                  },
                  "billed": {
                    "on": false,
                    "per_activation_cents": 1699,
                    "this_month": {
                      "activations": 0,
                      "total_cents": 0
                    },
                    "last_month": {
                      "activations": 0,
                      "total_cents": 0
                    }
                  }
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Request-Id": {
                "$ref": "#/components/headers/Request-Id"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        },
        "parameters": [
          {
            "name": "since",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Only earnings at or after this time (Unix seconds)."
          },
          {
            "name": "until",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Only earnings before this time (Unix seconds)."
          },
          {
            "name": "org_number",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Only this provider's earnings, by its RetURN.org Organization ID (ORG-XXXXXX)."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 200
            },
            "description": "How many `items` to answer, up to 200 (the default)."
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            },
            "description": "How many `items` to skip, for the next page."
          }
        ],
        "tags": [
          "Software companies"
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "A key from the partner portal (API Info, or Connect Your Software for a read-only key). Keys start with ro_live_. Kinds: full, read (GET calls only), platform (a software company's)."
      }
    },
    "parameters": {
      "Organization": {
        "name": "RetURN-Organization",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string",
          "example": "ORG-7KQ2MD"
        },
        "description": "A software company's key only: the RetURN.org Organization ID of the linked provider it is acting for. Required for a software company's key on every call except /whoami and /platform/*."
      },
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": true,
        "schema": {
          "type": "string",
          "maxLength": 120
        },
        "description": "Any unique string. The same request with the same key gets the first answer back for 30 days; the same key with a different request gets idempotency_reused. Errors are not kept."
      },
      "pid": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "pattern": "^[A-Za-z0-9-]{4,20}$",
          "example": "CP2-R6SY"
        },
        "description": "A RetURN.org ID. Case, dashes and look-alike letters don't matter."
      }
    },
    "responses": {
      "E400": {
        "description": "A field, query parameter or header is missing or wrong. `bad_field` names the field in `field`.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "ok": false,
              "error": "case_ref is text.",
              "code": "bad_field",
              "field": "case_ref",
              "request_id": "req_3f9a1c2b7d4e5f60"
            }
          }
        },
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/Request-Id"
          }
        }
      },
      "E401": {
        "description": "`bad_key`: the key is missing, wrong, revoked, or its organization or API is switched off. The answer is the same whichever it is.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "ok": false,
              "error": "That API key is not valid.",
              "code": "bad_key",
              "request_id": "req_3f9a1c2b7d4e5f60"
            }
          }
        },
        "headers": {
          "WWW-Authenticate": {
            "schema": {
              "type": "string"
            },
            "description": "`Bearer realm=\"RetURN.org\"`"
          },
          "Request-Id": {
            "$ref": "#/components/headers/Request-Id"
          }
        }
      },
      "E403": {
        "description": "This key or organization can't make this call. `code` says why.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "ok": false,
              "error": "This key is read-only. It can read, never change.",
              "code": "key_read_only",
              "request_id": "req_3f9a1c2b7d4e5f60"
            }
          }
        },
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/Request-Id"
          }
        }
      },
      "E404": {
        "description": "Not found, or not yours. A RetURN.org ID that exists but isn't yours gets the same answer as one that doesn't exist.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "ok": false,
              "error": "That RetURN.org ID is not one of yours.",
              "code": "not_found",
              "request_id": "req_3f9a1c2b7d4e5f60"
            }
          }
        },
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/Request-Id"
          }
        }
      },
      "E409": {
        "description": "The request conflicts with the RetURN.org ID's state, a payment or an earlier request.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "ok": false,
              "error": "35B-WJFR is claimed, so it cannot be marked given to a family.",
              "code": "wrong_stage",
              "ids": [
                "35B-WJFR"
              ],
              "request_id": "req_3f9a1c2b7d4e5f60"
            }
          }
        },
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/Request-Id"
          }
        }
      },
      "E429": {
        "description": "Too many requests.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "ok": false,
              "error": "Too many API requests. Slow down and try again.",
              "code": "rate_limited",
              "request_id": "req_3f9a1c2b7d4e5f60"
            }
          }
        },
        "headers": {
          "Retry-After": {
            "description": "Seconds to wait before trying again: the real wait on the sliding hour.",
            "schema": {
              "type": "integer"
            }
          },
          "RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimit-Limit"
          },
          "RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimit-Remaining"
          },
          "RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimit-Reset"
          },
          "Request-Id": {
            "$ref": "#/components/headers/Request-Id"
          }
        }
      },
      "E500": {
        "description": "`server_error`: something went wrong on RetURN.org's side. Send the same request again later; a call that took an Idempotency-Key is safe to send again with the same one.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "ok": false,
              "error": "Something went wrong on our side.",
              "code": "server_error",
              "request_id": "req_3f9a1c2b7d4e5f60"
            }
          }
        },
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/Request-Id"
          }
        }
      },
      "E502": {
        "description": "The card processor didn't answer. Send the same request again in a minute: the card is charged only once.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "ok": false,
              "error": "We couldn’t confirm this payment with the card processor. Send the same request again in a minute: the card is charged only once.",
              "code": "payment_unconfirmed",
              "request_id": "req_3f9a1c2b7d4e5f60"
            }
          }
        },
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/Request-Id"
          }
        }
      },
      "E413": {
        "description": "`too_large`: the body is over 64 KB. Send fewer RetURN.org IDs in each call.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "ok": false,
              "error": "The request body is over 64 KB. Send fewer RetURN.org IDs in each call.",
              "code": "too_large",
              "request_id": "req_3f9a1c2b7d4e5f60"
            }
          }
        },
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/Request-Id"
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "enum": [
              false
            ],
            "description": "Always false on an error."
          },
          "error": {
            "type": "string",
            "description": "For people. May be reworded at any time."
          },
          "code": {
            "type": "string",
            "description": "For code: act on this. The codes a call can answer are in its `x-error-codes`. A new code may be added; treat one you don't know by the HTTP status."
          },
          "ids": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "With `wrong_stage`: the RetURN.org ID that stopped the call."
          },
          "field": {
            "type": "string",
            "description": "With `bad_field`: the field to fix, like `case_ref` or `organization.address.state`."
          },
          "request_id": {
            "type": "string",
            "description": "This request's id, the same as the Request-Id header. Quote it to us about this call."
          }
        },
        "required": [
          "ok",
          "error",
          "code",
          "request_id"
        ],
        "description": "What every refusal answers."
      },
      "Organization": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The organization's internal id. Use `org_number` with people."
          },
          "name": {
            "type": "string",
            "description": "The organization's name."
          },
          "org_number": {
            "type": "string",
            "description": "RetURN.org Organization ID, ORG-XXXXXX."
          },
          "platform": {
            "type": "boolean",
            "description": "A software company."
          },
          "manufacturer": {
            "type": "boolean",
            "description": "An urn manufacturer."
          },
          "point_of_sale": {
            "type": "boolean",
            "description": "Hands RetURN.org IDs to families."
          },
          "api_enabled": {
            "type": "boolean",
            "description": "RetURN.org has turned this organization's own API keys on."
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "active",
              "inactive"
            ],
            "description": "pending: waiting for RetURN.org's approval. active. inactive: no longer a partner."
          },
          "sandbox": {
            "type": "boolean",
            "description": "A sandbox organization, like your test funeral home. Its RetURN.org IDs never meet real ones, and nothing there is charged."
          }
        },
        "description": "The organization this key acts for.",
        "required": [
          "id",
          "name",
          "org_number",
          "platform",
          "manufacturer",
          "point_of_sale",
          "api_enabled",
          "status",
          "sandbox"
        ]
      },
      "Key": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "The name it was given when it was made."
          },
          "prefix": {
            "type": "string",
            "description": "The key's first characters, for telling keys apart: ro_live_ for a live key, ro_test_ for a test key."
          },
          "scope": {
            "type": "string",
            "enum": [
              "full",
              "read",
              "platform"
            ],
            "description": "full: reads and writes. read: GET calls only. platform: a software company's."
          },
          "location_id": {
            "type": "string",
            "nullable": true,
            "description": "The one location this key is for, or null for the whole organization."
          },
          "test": {
            "type": "boolean",
            "description": "A test key: it acts only for sandbox organizations, never a real one."
          }
        },
        "description": "The key that made this call.",
        "required": [
          "name",
          "prefix",
          "scope",
          "location_id",
          "test"
        ]
      },
      "Whoami": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "description": "Always true on a success.",
            "enum": [
              true
            ]
          },
          "organization": {
            "$ref": "#/components/schemas/Organization"
          },
          "can_be_charged": {
            "type": "boolean",
            "description": "There is a saved card to charge activations and orders to. Left out when a software company's key asks about itself (no RetURN-Organization header)."
          },
          "key": {
            "$ref": "#/components/schemas/Key"
          }
        },
        "required": [
          "ok",
          "organization",
          "key"
        ],
        "description": "Who this key is and what it acts for."
      },
      "Summary": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "description": "Always true on a success.",
            "enum": [
              true
            ]
          },
          "organization": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "The organization's internal id."
              },
              "org_number": {
                "type": "string",
                "description": "Its RetURN.org Organization ID."
              },
              "name": {
                "type": "string",
                "description": "Its name."
              },
              "manufacturer": {
                "type": "boolean",
                "description": "An urn manufacturer."
              },
              "provider": {
                "type": "boolean",
                "description": "Hands RetURN.org IDs to families."
              }
            },
            "description": "The organization the counts are for.",
            "required": [
              "id",
              "org_number",
              "name",
              "manufacturer",
              "provider"
            ]
          },
          "location_id": {
            "type": "string",
            "nullable": true,
            "description": "The key's one location, when the counts cover only it; null for the whole organization."
          },
          "ids": {
            "type": "object",
            "properties": {
              "total": {
                "type": "integer",
                "description": "Every RetURN.org ID the organization (or location) holds."
              },
              "on_hand": {
                "type": "integer",
                "description": "Stage available."
              },
              "incorporated": {
                "type": "integer",
                "description": "Stage incorporated: used in a product, not yet handed over."
              },
              "distributed": {
                "type": "integer",
                "description": "Stage distributed: handed to a family, page not set up yet."
              },
              "paid": {
                "type": "integer",
                "description": "Paid for by a provider, so the family is not charged."
              },
              "claimed": {
                "type": "integer",
                "description": "The family's page is set up, by the family or by the funeral home for them."
              },
              "inactive": {
                "type": "integer",
                "description": "Retired or replaced."
              }
            },
            "description": "RetURN.org IDs by stage. Each is counted once, at its stage now.",
            "required": [
              "total",
              "on_hand",
              "incorporated",
              "distributed",
              "paid",
              "claimed",
              "inactive"
            ]
          },
          "free_ids": {
            "type": "object",
            "properties": {
              "activations_counted": {
                "type": "integer",
                "description": "Activations counted toward free packs."
              },
              "per_pack": {
                "type": "integer",
                "description": "Activations that earn one free pack."
              },
              "pack_size": {
                "type": "integer",
                "description": "RetURN.org IDs in a free pack."
              },
              "toward_next_pack": {
                "type": "integer",
                "description": "Activations counted toward the next free pack."
              },
              "to_go": {
                "type": "integer",
                "description": "Activations still needed for the next free pack."
              },
              "packs_earned": {
                "type": "integer",
                "description": "Free packs earned so far."
              },
              "packs_shipped": {
                "type": "integer",
                "description": "Free packs shipped."
              },
              "packs_on_the_way": {
                "type": "integer",
                "description": "Free packs earned and not shipped yet."
              }
            },
            "description": "Progress toward free packs of RetURN.org IDs. Null unless the organization hands RetURN.org IDs to families.",
            "nullable": true,
            "required": [
              "activations_counted",
              "per_pack",
              "pack_size",
              "toward_next_pack",
              "to_go",
              "packs_earned",
              "packs_shipped",
              "packs_on_the_way"
            ]
          },
          "monthly_activations": {
            "type": "array",
            "description": "RetURN.org IDs claimed in each of the last 12 calendar months (UTC), oldest first.",
            "items": {
              "type": "object",
              "properties": {
                "month": {
                  "type": "string",
                  "example": "2026-11",
                  "description": "The calendar month, YYYY-MM."
                },
                "count": {
                  "type": "integer",
                  "description": "RetURN.org IDs claimed that month."
                }
              },
              "required": [
                "month",
                "count"
              ]
            }
          }
        },
        "description": "Counts of the organization's RetURN.org IDs.",
        "required": [
          "ok",
          "organization",
          "location_id",
          "ids",
          "free_ids",
          "monthly_activations"
        ]
      },
      "LabelShipment": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The shipment's id."
          },
          "quantity": {
            "type": "integer",
            "description": "Labels in it."
          },
          "status": {
            "type": "string",
            "enum": [
              "placed",
              "in_production",
              "shipped",
              "cancelled"
            ],
            "description": "Where it is."
          },
          "location": {
            "type": "string",
            "nullable": true,
            "description": "The location's name, or null."
          },
          "location_id": {
            "type": "string",
            "nullable": true,
            "description": "The location it ships to, or null."
          },
          "created_at": {
            "type": "integer",
            "description": "Unix seconds."
          },
          "shipped_at": {
            "type": "integer",
            "nullable": true,
            "description": "Unix seconds, or null."
          },
          "tracking": {
            "type": "string",
            "nullable": true,
            "description": "The carrier's tracking number, once shipped."
          },
          "ship_to": {
            "type": "string",
            "nullable": true,
            "description": "The address it ships to, as one line."
          },
          "ids_issued": {
            "type": "integer",
            "description": "RetURN.org IDs made for it."
          },
          "ids_available": {
            "type": "integer",
            "description": "Of those, how many are still available (not handed over)."
          },
          "order": {
            "type": "string",
            "nullable": true,
            "description": "The purchase it ships for (RO-1042), if any."
          },
          "unit_price_cents": {
            "type": "integer",
            "nullable": true,
            "description": "What each was quoted at when ordered, not today's price."
          },
          "total_cents": {
            "type": "integer",
            "nullable": true,
            "description": "What the shipment was quoted at when ordered."
          },
          "ordered_through": {
            "type": "string",
            "nullable": true,
            "description": "The software company that placed the purchase it ships for, on the provider's saved card, or null."
          }
        },
        "description": "A shipment of printed RetURN.org ID labels.",
        "required": [
          "id",
          "quantity",
          "status",
          "location",
          "location_id",
          "created_at",
          "shipped_at",
          "tracking",
          "ship_to",
          "ids_issued",
          "ids_available",
          "order",
          "unit_price_cents",
          "total_cents",
          "ordered_through"
        ]
      },
      "Purchase": {
        "type": "object",
        "properties": {
          "order": {
            "type": "string",
            "example": "RO-1042",
            "description": "Its order number, as `POST /orders` answers it."
          },
          "item": {
            "type": "string",
            "enum": [
              "activation_cards",
              "ids",
              "starter_kit",
              "labels",
              "sample",
              "id"
            ],
            "description": "`activation_cards` and `ids` are what `POST /orders` sells. The others are bought in the portal."
          },
          "packs": {
            "type": "integer",
            "description": "Packs ordered."
          },
          "card_packs": {
            "type": "integer",
            "description": "Packs of prepaid activation cards added to a starter kit or RetURN.org IDs."
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "paid",
              "shipped",
              "cancelled"
            ],
            "description": "Where it is."
          },
          "created_at": {
            "type": "integer",
            "description": "Unix seconds."
          },
          "paid_at": {
            "type": "integer",
            "nullable": true,
            "description": "Unix seconds, or null."
          },
          "shipped_at": {
            "type": "integer",
            "nullable": true,
            "description": "Unix seconds, or null."
          },
          "carrier": {
            "type": "string",
            "description": "The carrier, once shipped, or empty."
          },
          "tracking": {
            "type": "string",
            "description": "The tracking number, once shipped, or empty."
          },
          "total_cents": {
            "type": "integer",
            "nullable": true,
            "description": "What was charged, tax included, once paid."
          },
          "tax_cents": {
            "type": "integer",
            "nullable": true,
            "description": "Sales tax charged, once paid."
          },
          "cards": {
            "type": "object",
            "properties": {
              "made": {
                "type": "integer",
                "description": "Cards it made."
              },
              "used": {
                "type": "integer",
                "description": "Of those, how many were used to activate a RetURN.org ID."
              },
              "voided": {
                "type": "integer",
                "description": "Of those, how many were voided."
              }
            },
            "description": "Counts of the prepaid activation cards it made, or null.",
            "nullable": true,
            "required": [
              "made",
              "used",
              "voided"
            ]
          },
          "ordered_through": {
            "type": "string",
            "nullable": true,
            "description": "The software company that placed it with `POST /orders`, on the provider's saved card, or null when the provider did."
          }
        },
        "description": "Something the organization bought from RetURN.org, in the portal or with `POST /orders`.",
        "required": [
          "order",
          "item",
          "packs",
          "card_packs",
          "status",
          "created_at",
          "paid_at",
          "shipped_at",
          "carrier",
          "tracking",
          "total_cents",
          "tax_cents",
          "cards",
          "ordered_through"
        ]
      },
      "Orders": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "description": "Always true on a success.",
            "enum": [
              true
            ]
          },
          "orders": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LabelShipment"
            },
            "description": "Label shipments, newest first, up to 100."
          },
          "purchases": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Purchase"
            },
            "description": "What the organization bought, newest first, up to 100. Always empty for a key for one location."
          }
        },
        "description": "Label shipments and purchases.",
        "required": [
          "ok",
          "orders",
          "purchases"
        ]
      },
      "Location": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Send it as `location_id`."
          },
          "name": {
            "type": "string",
            "description": "Its name."
          },
          "city": {
            "type": "string",
            "description": "Its city, or empty."
          },
          "state": {
            "type": "string",
            "description": "Its state, or empty."
          },
          "has_address": {
            "type": "boolean",
            "description": "A full street address, so an order can ship there."
          }
        },
        "description": "One of the organization's active locations.",
        "required": [
          "id",
          "name",
          "city",
          "state",
          "has_address"
        ]
      },
      "Locations": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "description": "Always true on a success.",
            "enum": [
              true
            ]
          },
          "locations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Location"
            },
            "description": "A key for one location sees only that one."
          }
        },
        "description": "The organization's active locations, by name.",
        "required": [
          "ok",
          "locations"
        ]
      },
      "PrepaidCards": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "description": "Always true on a success.",
            "enum": [
              true
            ]
          },
          "unused": {
            "type": "integer",
            "description": "Cards not used or voided yet."
          },
          "used": {
            "type": "integer",
            "description": "Cards used to activate a RetURN.org ID."
          },
          "voided": {
            "type": "integer",
            "description": "Cards voided before they were used."
          },
          "used_on": {
            "type": "array",
            "description": "Which RetURN.org ID each used card went on, newest first. The latest 200 only; `used` counts them all. Never a code.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "RetURN.org ID."
                },
                "used_at": {
                  "type": "integer",
                  "description": "Unix seconds."
                }
              },
              "required": [
                "id",
                "used_at"
              ]
            }
          }
        },
        "description": "The organization's prepaid activation cards, counted. Never a code.",
        "required": [
          "ok",
          "unused",
          "used",
          "voided",
          "used_on"
        ]
      },
      "Event": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "Send the last one as `after`."
          },
          "type": {
            "type": "string",
            "enum": [
              "paid",
              "refunded",
              "claimed",
              "family_confirmed",
              "published",
              "unpublished",
              "case_linked",
              "case_unlinked",
              "distributed",
              "id_linked",
              "linked",
              "unlinked",
              "approved"
            ],
            "description": "claimed: the family's page was set up. family_confirmed: the family confirmed their email, once, the first time. id_linked: a provider was linked to the RetURN.org ID through the API (POST /ids/{id}/link or /family). A software company sees only its own case_linked, case_unlinked, linked and unlinked."
          },
          "at": {
            "type": "integer",
            "description": "Unix seconds."
          },
          "return_id": {
            "type": "string",
            "nullable": true,
            "description": "The RetURN.org ID, or null for an event about the organization."
          }
        },
        "description": "One thing that happened. Only its type, when, and which RetURN.org ID.",
        "required": [
          "id",
          "type",
          "at",
          "return_id"
        ]
      },
      "Events": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "description": "Always true on a success.",
            "enum": [
              true
            ]
          },
          "events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Event"
            },
            "description": "Up to `limit`. Empty when nothing is new. A key for one location sees only events on RetURN.org IDs at that location, and none about the organization."
          },
          "next_after": {
            "type": "integer",
            "description": "Send as `after` next time. The same as `after` when nothing is new."
          }
        },
        "description": "Events after `after`, oldest first.",
        "required": [
          "ok",
          "events",
          "next_after"
        ]
      },
      "IdRecord": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "CP2-R6SY",
            "description": "The RetURN.org ID."
          },
          "stage": {
            "type": "string",
            "enum": [
              "available",
              "incorporated",
              "distributed",
              "claimed",
              "inactive"
            ],
            "description": "available: not used or handed over yet. incorporated: used in a product. distributed: handed to a family. claimed: the family's page is set up. inactive: retired or replaced."
          },
          "assignment": {
            "type": "string",
            "description": "api when reserved through the API, otherwise its physical form."
          },
          "product": {
            "type": "string",
            "nullable": true,
            "description": "The product it went into, or empty."
          },
          "sku": {
            "type": "string",
            "nullable": true,
            "description": "The product's SKU, or empty."
          },
          "batch": {
            "type": "string",
            "nullable": true,
            "description": "The batch it was made in, or null."
          },
          "internal_ref": {
            "type": "string",
            "nullable": true,
            "description": "Your own reference (reserve's `external_ref`, distribute's `reference`), or empty."
          },
          "physical_type": {
            "type": "string",
            "nullable": true,
            "description": "What it is printed or engraved on."
          },
          "location_id": {
            "type": "string",
            "nullable": true,
            "description": "The location that holds it, or null."
          },
          "location": {
            "type": "string",
            "nullable": true,
            "description": "That location's name, or null."
          },
          "roles": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "manufacturer",
                "point_of_sale"
              ]
            },
            "description": "How this organization holds it: as its manufacturer, as the provider that hands it to a family, or both."
          },
          "created_at": {
            "type": "integer",
            "description": "Unix seconds."
          },
          "incorporated_at": {
            "type": "integer",
            "nullable": true,
            "description": "Unix seconds, or null."
          },
          "distributed_at": {
            "type": "integer",
            "nullable": true,
            "description": "Unix seconds, or null."
          },
          "claimed_at": {
            "type": "integer",
            "nullable": true,
            "description": "Unix seconds, or null."
          },
          "claimed": {
            "type": "boolean",
            "description": "The family's page is set up, by the family or by the funeral home for them. See family_confirmed."
          },
          "paid": {
            "type": "boolean",
            "description": "A provider paid to activate it."
          },
          "code_free": {
            "type": "boolean",
            "description": "Activates with the RetURN.org ID alone (printed or engraved on an urn)."
          },
          "replaced_by": {
            "type": "string",
            "nullable": true,
            "description": "The RetURN.org ID that replaced this one, or null."
          },
          "number": {
            "type": "integer",
            "nullable": true,
            "description": "The manufacturer's running count of printed and engraved RetURN.org IDs."
          },
          "case_ref": {
            "type": "string",
            "nullable": true,
            "description": "The case this caller linked to it."
          },
          "updated_at": {
            "type": "integer",
            "description": "When this record last changed, in Unix seconds. GET /ids sorts on it and updated_since compares with it: keep the largest you've seen and ask from there."
          }
        },
        "description": "A RetURN.org ID the organization holds.",
        "required": [
          "id",
          "stage",
          "assignment",
          "product",
          "sku",
          "batch",
          "internal_ref",
          "physical_type",
          "location_id",
          "location",
          "roles",
          "created_at",
          "incorporated_at",
          "distributed_at",
          "claimed_at",
          "claimed",
          "paid",
          "code_free",
          "replaced_by",
          "number",
          "case_ref",
          "updated_at"
        ]
      },
      "IdRecordDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/IdRecord"
          },
          {
            "type": "object",
            "properties": {
              "family_confirmed": {
                "type": "boolean",
                "description": "Claimed, and the family confirmed their email address."
              },
              "page_url": {
                "type": "string",
                "example": "https://return.org/id/CP2-R6SY/",
                "description": "The address of the family's page."
              },
              "editable_until": {
                "type": "integer",
                "nullable": true,
                "description": "Until when this caller may change a family's page it set up before 2026-11-19 (Unix seconds), or null. POST /ids/{id}/family sets up no page since then, so it is null for anything newer."
              },
              "activation_code": {
                "type": "string",
                "description": "Full keys only, and only until the RetURN.org ID is claimed."
              },
              "prefilled": {
                "type": "boolean",
                "description": "Your organization's details for the family are waiting for the family's activation (POST /ids/{id}/family). False once the family activates it."
              },
              "published": {
                "type": "boolean",
                "description": "You published those details for the family (POST /ids/{id}/family with publish: true), so a scan shows the page. False once the family activates the RetURN.org ID: the page is theirs then."
              }
            },
            "required": [
              "family_confirmed",
              "page_url",
              "editable_until",
              "prefilled",
              "published"
            ]
          }
        ],
        "description": "One RetURN.org ID, with what software needs about its family's page. Never what the family wrote."
      },
      "CaseOnlyRecord": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The RetURN.org ID."
          },
          "case_ref": {
            "type": "string",
            "description": "The case this caller linked to it."
          },
          "claimed": {
            "type": "boolean",
            "description": "The family's page is set up."
          },
          "paid": {
            "type": "boolean",
            "description": "A provider paid to activate it."
          }
        },
        "description": "A RetURN.org ID this caller linked to a case but the provider does not hold yet.",
        "required": [
          "id",
          "case_ref",
          "claimed",
          "paid"
        ]
      },
      "IdList": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "description": "Always true on a success.",
            "enum": [
              true
            ]
          },
          "total": {
            "type": "integer",
            "description": "Every match, for paging."
          },
          "ids": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/IdRecord"
            },
            "description": "Up to `limit`, from `offset`."
          }
        },
        "description": "A page of the organization's RetURN.org IDs, newest change first.",
        "required": [
          "ok",
          "total",
          "ids"
        ]
      },
      "IdOne": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "description": "Always true on a success.",
            "enum": [
              true
            ]
          },
          "id_record": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/IdRecordDetail"
              },
              {
                "$ref": "#/components/schemas/CaseOnlyRecord"
              }
            ],
            "description": "The record, or a CaseOnlyRecord for a RetURN.org ID this caller linked to a case that the organization doesn't hold yet."
          }
        },
        "description": "One RetURN.org ID.",
        "required": [
          "ok",
          "id_record"
        ]
      },
      "ReserveRequest": {
        "type": "object",
        "properties": {
          "quantity": {
            "type": "integer",
            "minimum": 1,
            "maximum": 250000,
            "description": "Up to 250,000 for a manufacturer's reservation, within its limit of reserved RetURN.org IDs waiting to be used; 5,000 for role point_of_sale."
          },
          "product": {
            "type": "string",
            "maxLength": 120,
            "description": "The product they go into."
          },
          "sku": {
            "type": "string",
            "maxLength": 60,
            "description": "The product's SKU."
          },
          "batch": {
            "type": "string",
            "maxLength": 60,
            "description": "The batch they are made in."
          },
          "external_ref": {
            "type": "string",
            "maxLength": 60,
            "description": "Comes back as internal_ref."
          },
          "location_id": {
            "type": "string",
            "description": "The location that holds them. A key for one location reserves at that location only when this is sent."
          },
          "physical_type": {
            "type": "string",
            "enum": [
              "label",
              "engraving",
              "integrated",
              "other"
            ],
            "default": "engraving",
            "description": "What they are printed or engraved on."
          },
          "role": {
            "type": "string",
            "enum": [
              "manufacturer",
              "point_of_sale"
            ],
            "description": "Only for an organization that is both."
          }
        },
        "required": [
          "quantity"
        ],
        "description": "A block of RetURN.org IDs to reserve."
      },
      "ReservedId": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The RetURN.org ID."
          },
          "activation_code": {
            "type": "string",
            "description": "Its activation code. A RetURN.org ID printed or engraved on an urn activates without its code; the code is for one handed over without the urn."
          },
          "stage": {
            "type": "string",
            "enum": [
              "available"
            ],
            "description": "Always available."
          },
          "assignment": {
            "type": "string",
            "description": "Always api."
          },
          "block_id": {
            "type": "string",
            "nullable": true,
            "description": "The block it was reserved in. Null for role point_of_sale."
          },
          "number": {
            "type": "integer",
            "nullable": true,
            "description": "The manufacturer's running count of its printed and engraved RetURN.org IDs. Left out for role point_of_sale."
          }
        },
        "description": "A RetURN.org ID just reserved.",
        "required": [
          "id",
          "activation_code",
          "stage",
          "assignment",
          "block_id"
        ]
      },
      "ReserveResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "description": "Always true on a success.",
            "enum": [
              true
            ]
          },
          "count": {
            "type": "integer",
            "description": "How many were reserved."
          },
          "ids": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ReservedId"
            },
            "description": "The RetURN.org IDs, with their codes."
          },
          "artwork_version": {
            "type": "string",
            "example": "1.0",
            "description": "The artwork version to print them with."
          }
        },
        "description": "The block just reserved.",
        "required": [
          "ok",
          "count",
          "ids",
          "artwork_version"
        ]
      },
      "IncorporateRequest": {
        "type": "object",
        "properties": {
          "ids": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "minItems": 1,
            "maxItems": 5000,
            "description": "The RetURN.org IDs. All of them are marked, or none."
          },
          "product": {
            "type": "string",
            "maxLength": 120,
            "description": "The product they went into. Kept from the first call."
          },
          "sku": {
            "type": "string",
            "maxLength": 60,
            "description": "The product's SKU."
          },
          "batch": {
            "type": "string",
            "maxLength": 60,
            "description": "The batch."
          },
          "internal_ref": {
            "type": "string",
            "maxLength": 60,
            "description": "Your own reference."
          }
        },
        "required": [
          "ids"
        ],
        "description": "The RetURN.org IDs used in a product."
      },
      "DistributeRequest": {
        "type": "object",
        "properties": {
          "ids": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "minItems": 1,
            "maxItems": 5000,
            "description": "The RetURN.org IDs. All of them are marked, or none, except those you had already handed over."
          },
          "location_id": {
            "type": "string",
            "description": "The location that handed them over."
          },
          "reference": {
            "type": "string",
            "maxLength": 60,
            "description": "Comes back as internal_ref."
          }
        },
        "required": [
          "ids"
        ],
        "description": "The RetURN.org IDs handed to a family."
      },
      "Count": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "description": "Always true on a success.",
            "enum": [
              true
            ]
          },
          "count": {
            "type": "integer",
            "description": "How many RetURN.org IDs this call marked."
          }
        },
        "description": "How many were marked.",
        "required": [
          "ok",
          "count"
        ]
      },
      "CaseRequest": {
        "type": "object",
        "properties": {
          "case_ref": {
            "type": "string",
            "maxLength": 120,
            "description": "Your case number or id."
          }
        },
        "required": [
          "case_ref"
        ],
        "description": "The family's case in your software."
      },
      "CaseResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "description": "Always true on a success.",
            "enum": [
              true
            ]
          },
          "id": {
            "type": "string",
            "description": "The RetURN.org ID."
          },
          "case_ref": {
            "type": "string",
            "description": "The case it is linked to."
          },
          "claimed": {
            "type": "boolean",
            "description": "The family's page is set up."
          },
          "paid": {
            "type": "boolean",
            "description": "A provider paid to activate it."
          }
        },
        "description": "The case now linked.",
        "required": [
          "ok",
          "id",
          "case_ref",
          "claimed",
          "paid"
        ]
      },
      "UnlinkResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "description": "Always true on a success.",
            "enum": [
              true
            ]
          },
          "id": {
            "type": "string",
            "description": "The RetURN.org ID."
          },
          "case_ref": {
            "type": "string",
            "nullable": true,
            "description": "Always null."
          }
        },
        "description": "The case is no longer linked.",
        "required": [
          "ok",
          "id",
          "case_ref"
        ]
      },
      "ActivateRequest": {
        "type": "object",
        "properties": {
          "pay": {
            "type": "string",
            "enum": [
              "card",
              "company",
              "prepaid"
            ],
            "description": "card (the default): the provider's saved card, $17.99 plus sales tax. company: a software company that bills the provider itself; RetURN.org bills it $16.99 a month later. prepaid: send prepaid_code (pay may be left out)."
          },
          "prepaid_code": {
            "type": "string",
            "description": "The code on one of the provider's own prepaid activation cards, the one handed to this family. Case, spaces and dashes don't matter. Through a software company's key, the company earns its $1."
          },
          "provider_as": {
            "type": "string",
            "enum": [
              "funeral_home",
              "crematory",
              "both"
            ],
            "description": "How the provider served this family. Left out, the answer on the organization's Organization page in the portal stands."
          }
        },
        "description": "How to pay. An empty body pays with the saved card."
      },
      "ActivateResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "description": "Always true on a success.",
            "enum": [
              true
            ]
          },
          "id": {
            "type": "string",
            "description": "The RetURN.org ID."
          },
          "paid": {
            "type": "boolean",
            "enum": [
              true
            ],
            "description": "Always true."
          },
          "pay": {
            "type": "string",
            "enum": [
              "card",
              "company",
              "prepaid"
            ],
            "description": "How it was paid. When it was already paid for, how that payment was made."
          },
          "price_cents": {
            "type": "integer",
            "description": "What was charged, before tax: 1799 on a card, 1699 billed to a software company, 0 for a prepaid card or a RetURN.org ID that was free. When it was already paid for by this provider (a retry after a lost answer, say), what that payment was, so the answer is the same as the first one's. Nothing new is charged."
          },
          "already": {
            "type": "boolean",
            "description": "Present and true when nothing new was paid: it was already paid for, or an earlier payment went through."
          },
          "sandbox": {
            "type": "boolean",
            "description": "Present and true when the sandbox answered: nothing was charged."
          }
        },
        "description": "The RetURN.org ID is paid for.",
        "required": [
          "ok",
          "id",
          "paid",
          "pay",
          "price_cents"
        ]
      },
      "FamilyRequest": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "maxLength": 254,
            "description": "Accepted and not used since 2026-11-19: nobody is emailed. Was required on the first save."
          },
          "consent": {
            "type": "boolean",
            "enum": [
              true
            ],
            "description": "Accepted and not used since 2026-11-19. Was required on the first save."
          },
          "full_name": {
            "type": "string",
            "maxLength": 120,
            "description": "The name of the person or pet whose ashes the urn holds. Required, except in {\"publish\": false} alone, which unpublishes (2026-11-19)."
          },
          "subject_kind": {
            "type": "string",
            "enum": [
              "person",
              "pet"
            ],
            "default": "person",
            "description": "A person or a pet."
          },
          "species": {
            "type": "string",
            "maxLength": 80,
            "description": "Kept only for a pet."
          },
          "pronouns": {
            "type": "string",
            "maxLength": 40,
            "description": "The person's pronouns, if the family gave them."
          },
          "birth_year": {
            "type": "integer",
            "minimum": 1850,
            "description": "The year they were born. Not after next year."
          },
          "death_year": {
            "type": "integer",
            "minimum": 1850,
            "description": "Up to next year, and not before birth_year."
          },
          "wish_first": {
            "type": "string",
            "maxLength": 400,
            "description": "What the family wants done with the ashes."
          },
          "wish_fallback": {
            "type": "string",
            "maxLength": 400,
            "description": "What should happen if that can't be done."
          },
          "publish": {
            "type": "boolean",
            "description": "true publishes the page for the family now (2026-11-19), so a scan shows it before anyone activates the RetURN.org ID. Only on a RetURN.org ID that is paid for (409 activate_first otherwise), and needs wish_first and permission_by. Left out, the details stay private until the family publishes them. false does the same, and on a page you published it also unpublishes it (2026-11-19): the page is private again and the details stay; sent alone, it keeps the details you sent before."
          },
          "permission_by": {
            "type": "string",
            "maxLength": 120,
            "description": "With publish: true, the name of the family member who gave permission to publish the page. Recorded with it."
          }
        },
        "description": "What the family asked to have on their page. full_name is required, except in {\"publish\": false} alone."
      },
      "FamilyResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "description": "Always true on a success.",
            "enum": [
              true
            ]
          },
          "id": {
            "type": "string",
            "description": "The RetURN.org ID."
          },
          "saved": {
            "type": "boolean",
            "enum": [
              true
            ],
            "description": "Always true."
          },
          "family_emailed": {
            "type": "boolean",
            "enum": [
              false
            ],
            "description": "Always false since 2026-11-19: nobody is emailed."
          },
          "editable_until": {
            "type": "integer",
            "nullable": true,
            "description": "Always null since 2026-11-19: you can replace the details until the family activates the RetURN.org ID."
          },
          "linked": {
            "type": "boolean",
            "enum": [
              true
            ],
            "description": "Your organization is linked to the RetURN.org ID."
          },
          "published": {
            "type": "boolean",
            "description": "The page is published for the family (you sent publish: true), so a scan shows it."
          },
          "unpublished": {
            "type": "boolean",
            "description": "This call made a page you had published private again (you sent publish: false, 2026-11-19). False otherwise."
          },
          "paid": {
            "type": "boolean",
            "description": "A provider paid to activate it."
          },
          "price_cents": {
            "type": "integer",
            "description": "What activating it would cost you now, before tax: 1799, or 0 when it is paid for already or free."
          }
        },
        "description": "The details were saved: privately, or published when you sent publish: true. Nothing the family wrote comes back.",
        "required": [
          "ok",
          "id",
          "saved",
          "linked",
          "published",
          "unpublished",
          "family_emailed",
          "editable_until",
          "paid",
          "price_cents"
        ]
      },
      "OrderRequest": {
        "type": "object",
        "properties": {
          "item": {
            "type": "string",
            "enum": [
              "activation_cards",
              "ids"
            ],
            "description": "activation_cards: a pack of 25 prepaid activation cards, $449.75. ids: a pack of 25 RetURN.org IDs with activation sheets, $50. Plus sales tax."
          },
          "quantity": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "description": "Packs: up to 20 of activation_cards, 100 of ids."
          },
          "location_id": {
            "type": "string",
            "description": "Where it ships (GET /locations). Needs a street address. May be left out when the organization has one location."
          }
        },
        "required": [
          "item"
        ],
        "description": "What to order."
      },
      "OrderResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "description": "Always true on a success.",
            "enum": [
              true
            ]
          },
          "paid": {
            "type": "boolean",
            "enum": [
              true
            ],
            "description": "Always true."
          },
          "order": {
            "type": "string",
            "example": "RO-1042",
            "description": "The order number, as `GET /orders` lists it under purchases."
          },
          "ship_to": {
            "type": "string",
            "description": "The location's name."
          },
          "already": {
            "type": "boolean",
            "description": "Present and true when an earlier try at the same order went through."
          },
          "item": {
            "type": "string",
            "description": "What was ordered. Left out when `already` is true."
          },
          "packs": {
            "type": "integer",
            "description": "Packs ordered. Left out when `already` is true."
          },
          "sandbox": {
            "type": "boolean",
            "description": "Present and true when the sandbox answered: nothing was charged."
          }
        },
        "description": "The order is paid for.",
        "required": [
          "ok",
          "paid",
          "order",
          "ship_to"
        ]
      },
      "PlatformOrganizations": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "description": "Always true on a success.",
            "enum": [
              true
            ]
          },
          "organizations": {
            "type": "array",
            "items": {
              "oneOf": [
                {
                  "type": "object",
                  "properties": {
                    "org_number": {
                      "type": "string",
                      "description": "Its RetURN.org Organization ID. Send it as RetURN-Organization."
                    },
                    "name": {
                      "type": "string",
                      "description": "Its name."
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "pending",
                        "active",
                        "inactive"
                      ],
                      "description": "pending: waiting for RetURN.org's approval; your key works for it once it is active."
                    },
                    "linked_via": {
                      "type": "string",
                      "enum": [
                        "provider",
                        "request",
                        "signup",
                        "provisioned"
                      ],
                      "description": "How the link was made: the provider linked you, it said yes to your request, it signed up through your link, or you set it up."
                    },
                    "linked_at": {
                      "type": "integer",
                      "description": "Unix seconds."
                    },
                    "your_ref": {
                      "type": "string",
                      "description": "Your reference for the provider, from the sign-up link's ref or your_ref when you set it up. Empty otherwise."
                    }
                  },
                  "description": "A linked provider.",
                  "required": [
                    "org_number",
                    "name",
                    "status",
                    "linked_via",
                    "linked_at",
                    "your_ref"
                  ]
                },
                {
                  "type": "object",
                  "properties": {
                    "org_number": {
                      "type": "string",
                      "description": "The Organization ID you asked about."
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "waiting_for_provider"
                      ],
                      "description": "Not linked yet."
                    },
                    "requested_at": {
                      "type": "integer",
                      "description": "Unix seconds."
                    }
                  },
                  "description": "A provider you asked to link that hasn't answered.",
                  "required": [
                    "org_number",
                    "status",
                    "requested_at"
                  ]
                }
              ]
            },
            "description": "Linked providers by name, then the ones you asked to link that haven't answered."
          }
        },
        "description": "Your providers.",
        "required": [
          "ok",
          "organizations"
        ]
      },
      "LinkRequest": {
        "type": "object",
        "properties": {
          "org_number": {
            "type": "string",
            "description": "The provider's RetURN.org Organization ID (ORG-XXXXXX). Case and dashes don't matter."
          }
        },
        "required": [
          "org_number"
        ],
        "description": "The provider to ask."
      },
      "LinkResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "description": "Always true on a success.",
            "enum": [
              true
            ]
          },
          "org_number": {
            "type": "string",
            "description": "The Organization ID you sent, tidied."
          },
          "status": {
            "type": "string",
            "enum": [
              "linked",
              "waiting_for_provider"
            ],
            "description": "linked: already linked. waiting_for_provider: asked, or asked before; nothing is linked until the provider says yes."
          }
        },
        "description": "The same answer whether or not the Organization ID exists.",
        "required": [
          "ok",
          "org_number",
          "status"
        ]
      },
      "ProvisionRequest": {
        "type": "object",
        "properties": {
          "organization": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "maxLength": 120,
                "description": "Its name, as families know it."
              },
              "provider_as": {
                "type": "string",
                "enum": [
                  "funeral_home",
                  "crematory",
                  "both"
                ],
                "description": "A funeral home, a crematory, or both."
              },
              "website": {
                "type": "string",
                "maxLength": 200,
                "description": "Its website."
              },
              "phone": {
                "type": "string",
                "maxLength": 40,
                "description": "Its phone number."
              },
              "address": {
                "type": "object",
                "properties": {
                  "address1": {
                    "type": "string",
                    "maxLength": 120,
                    "description": "Street address."
                  },
                  "address2": {
                    "type": "string",
                    "maxLength": 120,
                    "description": "Suite or unit."
                  },
                  "city": {
                    "type": "string",
                    "maxLength": 80,
                    "description": "City."
                  },
                  "state": {
                    "type": "string",
                    "maxLength": 40,
                    "description": "State."
                  },
                  "postal": {
                    "type": "string",
                    "maxLength": 12,
                    "description": "ZIP code."
                  }
                },
                "required": [
                  "city",
                  "state"
                ],
                "description": "Its main location. It becomes the first location."
              }
            },
            "required": [
              "name",
              "provider_as",
              "address"
            ],
            "description": "The provider."
          },
          "contact": {
            "type": "object",
            "properties": {
              "first_name": {
                "type": "string",
                "maxLength": 40,
                "description": "First name."
              },
              "last_name": {
                "type": "string",
                "maxLength": 40,
                "description": "Last name."
              },
              "email": {
                "type": "string",
                "maxLength": 254,
                "description": "Email address. The invitation goes here."
              },
              "phone": {
                "type": "string",
                "maxLength": 40,
                "description": "Phone number."
              }
            },
            "required": [
              "first_name",
              "last_name",
              "email"
            ],
            "description": "The person at the provider who gets the invitation and becomes its administrator."
          },
          "your_ref": {
            "type": "string",
            "maxLength": 120,
            "description": "Your own reference for the provider; comes back as your_ref in GET /platform/organizations."
          }
        },
        "required": [
          "organization",
          "contact"
        ],
        "description": "The provider to set up, and the person to invite."
      },
      "ProvisionResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "description": "Always true on a success.",
            "enum": [
              true
            ]
          },
          "org_number": {
            "type": "string",
            "description": "Its RetURN.org Organization ID. Send it as RetURN-Organization once it is approved. A test key gets ORG-SANDBOX: nothing was made."
          },
          "status": {
            "type": "string",
            "enum": [
              "pending"
            ],
            "description": "Always pending: it waits for RetURN.org's approval."
          },
          "invited": {
            "type": "boolean",
            "description": "The invitation email to the contact went out. Always false for a test key."
          },
          "sandbox": {
            "type": "boolean",
            "description": "Present and true for a test key: the request was checked and answered, and no account was made or emailed."
          }
        },
        "description": "The provider's new account.",
        "required": [
          "ok",
          "org_number",
          "status",
          "invited"
        ]
      },
      "Earnings": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "description": "Always true on a success.",
            "enum": [
              true
            ]
          },
          "earnings": {
            "type": "object",
            "properties": {
              "activations": {
                "type": "integer",
                "description": "Matches not reversed."
              },
              "total_cents": {
                "type": "integer",
                "description": "Matches not reversed."
              },
              "per_activation_cents": {
                "type": "integer",
                "example": 100,
                "description": "What you earn for each."
              },
              "items": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "RetURN.org ID."
                    },
                    "org_number": {
                      "type": "string",
                      "description": "The provider's Organization ID."
                    },
                    "organization": {
                      "type": "string",
                      "description": "The provider's name."
                    },
                    "cents": {
                      "type": "integer",
                      "description": "What you earned."
                    },
                    "earned_at": {
                      "type": "integer",
                      "description": "Unix seconds."
                    },
                    "reversed": {
                      "type": "boolean",
                      "description": "The payment, or the pack the prepaid card came in, was refunded, so the $1 was taken back."
                    }
                  },
                  "required": [
                    "id",
                    "org_number",
                    "organization",
                    "cents",
                    "earned_at",
                    "reversed"
                  ]
                },
                "description": "Each earning, up to `limit`, from `offset`, reversed ones included."
              }
            },
            "description": "Your $1 for each activation through your key, paid on the provider's saved card or with one of its prepaid activation cards, newest first. We pay it each quarter, as you choose on your portal's Payouts page. Activations you bill yourself (pay: company) are in `billed`, not here: you keep that $1.",
            "required": [
              "activations",
              "total_cents",
              "per_activation_cents",
              "items"
            ]
          },
          "billed": {
            "type": "object",
            "properties": {
              "on": {
                "type": "boolean",
                "description": "pay: company is set up for you."
              },
              "per_activation_cents": {
                "type": "integer",
                "example": 1699,
                "description": "What RetURN.org bills you for each."
              },
              "this_month": {
                "type": "object",
                "properties": {
                  "activations": {
                    "type": "integer",
                    "description": "Activations billed."
                  },
                  "total_cents": {
                    "type": "integer",
                    "description": "What they come to."
                  }
                },
                "description": "This calendar month so far.",
                "required": [
                  "activations",
                  "total_cents"
                ]
              },
              "last_month": {
                "type": "object",
                "properties": {
                  "activations": {
                    "type": "integer",
                    "description": "Activations billed."
                  },
                  "total_cents": {
                    "type": "integer",
                    "description": "What they come to."
                  }
                },
                "description": "Last calendar month.",
                "required": [
                  "activations",
                  "total_cents"
                ]
              }
            },
            "description": "Activations you paid for with pay: company, by calendar month (US Eastern).",
            "required": [
              "on",
              "per_activation_cents",
              "this_month",
              "last_month"
            ]
          }
        },
        "description": "What you earned and what you are billed.",
        "required": [
          "ok",
          "earnings",
          "billed"
        ]
      },
      "DistributeResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "description": "Always true on a success.",
            "enum": [
              true
            ]
          },
          "count": {
            "type": "integer",
            "description": "How many were marked by this call."
          },
          "already": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The RetURN.org IDs you sent that you had already given to a family. They are not marked again."
          }
        },
        "description": "How many were marked, and which were already.",
        "required": [
          "ok",
          "count",
          "already"
        ]
      },
      "IdLinkRequest": {
        "type": "object",
        "properties": {
          "provider_as": {
            "type": "string",
            "enum": [
              "funeral_home",
              "crematory",
              "both"
            ],
            "description": "Which line of the family's page your name fills: funeral home, cremation, or both. Left out, your organization's own answer decides."
          }
        },
        "description": "Optional. An empty body links with your organization's own answer."
      },
      "IdLinkResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "enum": [
              true
            ],
            "description": "Always true on a success."
          },
          "id": {
            "type": "string",
            "description": "The RetURN.org ID."
          },
          "linked": {
            "type": "boolean",
            "enum": [
              true
            ],
            "description": "Always true."
          },
          "already": {
            "type": "boolean",
            "description": "Your organization was linked to it before this call."
          },
          "claimed": {
            "type": "boolean",
            "enum": [
              false
            ],
            "description": "Always false: an ID the family activated can't be linked."
          },
          "paid": {
            "type": "boolean",
            "description": "A provider paid to activate it."
          },
          "price_cents": {
            "type": "integer",
            "description": "What activating it would cost you now, before tax: 1799, or 0 when it is paid for already or free."
          }
        },
        "description": "The RetURN.org ID, linked to your organization.",
        "required": [
          "ok",
          "id",
          "linked",
          "already",
          "claimed",
          "paid",
          "price_cents"
        ]
      }
    },
    "headers": {
      "RateLimit-Limit": {
        "description": "Calls this key may make in any hour (600). A software company's key has this many for each provider it acts for.",
        "schema": {
          "type": "integer",
          "example": 600
        }
      },
      "RateLimit-Remaining": {
        "description": "Calls left in the hour, this one counted.",
        "schema": {
          "type": "integer",
          "example": 599
        }
      },
      "RateLimit-Reset": {
        "description": "Seconds until the oldest call in the hour stops counting, so one more is free. The window slides; it doesn't reset on the hour.",
        "schema": {
          "type": "integer",
          "example": 3600
        }
      },
      "Request-Id": {
        "description": "This request's id, on every answer. Quote it to us about a call, and we can find it.",
        "schema": {
          "type": "string",
          "example": "req_3f9a1c2b7d4e5f60"
        }
      }
    }
  }
}
