Change an invitation's permission group

PUT/v1/api/store/{team_slug}/setting/invite/{invite}

v1Operation ID v1_public_invite_update_put

Changes which permission group the person will join with. No email is sent.

The path takes the invitation's id from the list: a UUID, not a hash id.

Use PUT. PATCH has no rules and fails with 500.

An expired invitation is left as it is, and the call still succeeds: check expired in the response.

Permission

Needs the Manage Settings permission. The team owner always has it.

Path parameters

• team_slugstringrequired

  Your team slug, shown as Team ID next to your API key in Profile.

  • Example your-team
• invitestring (uuid)required

  The invitation's id from the invitation list: a UUID, not a hash id.

  • Example 0b5e8c1a-3f4d-4c2b-9a7e-1d2c3b4a5f60

Request body

application/json, required.

• role_idstringrequired

  One of this team's permission groups, from GET /v1/api/store/{team_slug}/setting/group.

Response

200Successful response.

• dataobjectrequired
  Child fields (5)

  • emailstringrequired
  • expiredbooleanrequired

    True two months after the invitation was first created.

  • expired_atstring (date-time)required

    When it expires: two months after it was created. Resending does not move this date.

  • idstring (uuid)required

    The invitation's id: a UUID, not a hash id. Use it in the invitation paths.

  • roleobject | null

    The permission group the person will join with. Null if that group was deleted since.

    Child fields (5)

    • idstringrequired
    • namestringrequired
    • permissionsarray of stringsrequired

      The group's permission keys, as "Get a permission group" returns them.

    • usersarray of objectsrequired

      The members who already hold this group.

      Fields of each item (4)

      • avatar_urlstring | nullrequired
      • emailstringrequired
      • idstringrequired
      • namestringrequired
    • versionintegerrequired
• statusintegerrequired
• successbooleanrequired

Errors

• 401The API key is missing or wrong (unauthenticated).

• 403You are not allowed to do this. api_access_not_in_plan: your team's plan doesn't include API access (Pro and above, with an active subscription or trial), so every request answers this until the team upgrades. When your role lacks the permission the operation needs, the body is only {"message": "Insufficient Permission"}. Other refusals use the error envelope, with unauthorized or user_is_not_authorized.

  When

  Your role lacks Manage Settings. The body is {"message": "Insufficient Permission"}, without the error envelope.

  Fix

  Use the key of a member whose role has Manage Settings, or the owner's.

• 404Not found. page_not_found: the team slug is unknown, you are not a member of the team, or an id in the path is not one of this team's. code: null, with a message that starts "No query results for": there is no record with that id.

  When

  No invitation of your team has this id. error.code is null; error.message names the record type.

  Fix

  Use an id from the invitations list.

  When

  role_id is not one of your team's permission groups. error.code is null; error.message names the record type.

  Fix

  Use a group id from the groups list.

• 422The request was refused and changed nothing. validation_failed lists what to fix in error.fields; other codes name a business rule, explained in error.message. A few checks answer with only {"message": "..."}. An operation that calls another service (a payment provider, a carrier, an accounting app) can answer connect_timeout ("Please retry again") when that service does not answer in time: the change may or may not have happened there, so read the record back before you retry.

  When

  role_id is missing or not an id (validation_failed).

  Fix

  Send a group id from the groups list.

Related

• GETList invitations/v1/api/store/{team_slug}/setting/invite
• GETList permission groups/v1/api/store/{team_slug}/setting/group

Example request

curl

curl -X PUT 'https://secure.yoprint.com/v1/api/store/your-team/setting/invite/0b5e8c1a-3f4d-4c2b-9a7e-1d2c3b4a5f60' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "role_id": "drvVENtzY33bqP"  }'

Example response 200

Response

{
  "data": {
    "email": "jordan@example.com",
    "expired": false,
    "expired_at": "2027-01-03T09:00:00+00:00",
    "id": "0b5e8c1a-3f4d-4c2b-9a7e-1d2c3b4a5f60",
    "role": {
      "id": "drvVENtzY33bqP",
      "name": "Production",
      "permissions": [
        "view_all_order",
        "update_all_order"
      ],
      "users": [
        {
          "avatar_url": null,
          "email": "alex@example.com",
          "id": "E6LjYJJimQNFVF",
          "name": "Alex Rivera"
        }
      ],
      "version": 3
    }
  },
  "status": 200,
  "success": true
}