Update a Document Return Envelope

Method: POST

Production endpoint: https://next-api.checkissuing.com/documents/update

Sandbox endpoint: https://next-sb-api.checkissuing.com/documents/update

This authenticated endpoint changes only the Return Envelope assignment of a document owned by the OAuth credential's client. The token must include the api.access scope. A request cannot select a different client, including when the token's user is staff.

Lifecycle safety

Only a non-deleted, unsent document in status 1 can be updated. Status 2 documents are already eligible for print-package generation, so processing, sent, and cancelled documents are rejected instead of leaving an existing print artifact stale. Assignment, mail-profile recalculation, and fee-refresh intent commit or roll back together.

Parameters

Parameter	Type	Required	Description
`id`	Integer	Yes	Positive id of an active document owned by the OAuth client.
`return_envelope_id`	Integer\|null	No	Omit to preserve the existing assignment; send `null` or integer `0` to clear it; send a positive active, client-owned id to assign or change it. The target client's `return_envelope_enabled` setting must allow a new/change assignment.

The legacy aliases sp_return_envelope, return_envelope, and reply_envelope remain accepted, but new integrations should send return_envelope_id. Empty strings, No Return Envelope, signed numbers, decimals, exponent notation, booleans, arrays, inactive/deleted ids, and foreign-client ids are rejected. Other document fields are not accepted by this bounded update operation.

Response compatibility

The document object includes these mail-profile keys: return_envelope_id (int|null), mail_class (letter | large_envelope | large_envelope_intl | priority | null), mail_class_reason (letter | sheet_count_triggered_large_envelope | weight_triggered_large_envelope | priority_upgrade | null), sheet_count (int|null), check_sheet_count (int), insert_sheet_count (int), computed_weight_oz (number|null), and large_envelope (bool). A priority-upgrade postage_message is returned whenever a priority upgrade occurs.

{
  "status": 1,
  "document": {
    "id": 4607,
    "client_id": 1100,
    "status_id": 1,
    "postage_id": 1,
    "return_envelope_id": 42,
    "mail_class": "letter",
    "mail_class_reason": "letter",
    "sheet_count": 2,
    "computed_weight_oz": 0.680,
    "large_envelope": false
  }
}

Errors

Invalid or insufficiently scoped OAuth credentials return HTTP 403 with the established status: 0 access-denied body. Invalid ids, ownership, lifecycle, unsupported-field, and Return Envelope validation failures retain the legacy Document API status: 0, errors, and error_message response envelope and perform no mutation.