Assign a customer managed plan or update renewal settings

curl --request PUT \
  --url https://app.famulor.io/api/v1/platform/users/{user_id}/plan \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "plan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "expected_version": 2,
  "max_debit_credits": 6500000000000,
  "workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "ends_at": "2023-11-07T05:31:56Z",
  "enable_auto_topup": true,
  "auto_topup_consent_token": "<string>",
  "quote_token": "<string>"
}
'

import requests

url = "https://app.famulor.io/api/v1/platform/users/{user_id}/plan"

payload = {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "plan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "expected_version": 2,
    "max_debit_credits": 6500000000000,
    "workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "ends_at": "2023-11-07T05:31:56Z",
    "enable_auto_topup": True,
    "auto_topup_consent_token": "<string>",
    "quote_token": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    request_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    plan_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    expected_version: 2,
    max_debit_credits: 6500000000000,
    workspace_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    ends_at: '2023-11-07T05:31:56Z',
    enable_auto_topup: true,
    auto_topup_consent_token: '<string>',
    quote_token: '<string>'
  })
};

fetch('https://app.famulor.io/api/v1/platform/users/{user_id}/plan', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.famulor.io/api/v1/platform/users/{user_id}/plan",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'request_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'plan_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'expected_version' => 2,
    'max_debit_credits' => 6500000000000,
    'workspace_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'ends_at' => '2023-11-07T05:31:56Z',
    'enable_auto_topup' => true,
    'auto_topup_consent_token' => '<string>',
    'quote_token' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.famulor.io/api/v1/platform/users/{user_id}/plan"

	payload := strings.NewReader("{\n  \"request_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"plan_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"expected_version\": 2,\n  \"max_debit_credits\": 6500000000000,\n  \"workspace_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"ends_at\": \"2023-11-07T05:31:56Z\",\n  \"enable_auto_topup\": true,\n  \"auto_topup_consent_token\": \"<string>\",\n  \"quote_token\": \"<string>\"\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://app.famulor.io/api/v1/platform/users/{user_id}/plan")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"request_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"plan_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"expected_version\": 2,\n  \"max_debit_credits\": 6500000000000,\n  \"workspace_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"ends_at\": \"2023-11-07T05:31:56Z\",\n  \"enable_auto_topup\": true,\n  \"auto_topup_consent_token\": \"<string>\",\n  \"quote_token\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.famulor.io/api/v1/platform/users/{user_id}/plan")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"request_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"plan_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"expected_version\": 2,\n  \"max_debit_credits\": 6500000000000,\n  \"workspace_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"ends_at\": \"2023-11-07T05:31:56Z\",\n  \"enable_auto_topup\": true,\n  \"auto_topup_consent_token\": \"<string>\",\n  \"quote_token\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "status": "active",
    "workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "version": 2,
    "required_credits": 1,
    "message": "<string>"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key."
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry after the indicated delay."
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "<string>"
  }
}

White Label

Assign a customer managed plan or update renewal settings

Requires live owner/admin membership and Whitelabel entitlement in the calling credential’s reseller workspace. Operates only on that reseller’s customer workspaces, including when the acting user is a platform administrator. Funds a monthly or yearly customer plan from the reseller workspace. Yearly funding reserves twelve monthly credit allowances and delivers them month by month. Included services are funded with the plan. The customer must have no current plan before a new assignment; existing managed agreements only permit renewal-settings changes through this operation. Read the overview first, supply the selected interval quote token, accept a maximum net debit, and supply its version (null for a new assignment). An idempotency UUID protects retries with identical input. Auto-top-up requires the reviewed settings consent token whenever choosing that policy, including for already-enabled rules; enabling a disabled rule also requires explicit consent. Required scope: platform:write.

PUT

platform

users

{user_id}

plan

Assign a customer managed plan or update renewal settings

curl --request PUT \
  --url https://app.famulor.io/api/v1/platform/users/{user_id}/plan \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "plan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "expected_version": 2,
  "max_debit_credits": 6500000000000,
  "workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "ends_at": "2023-11-07T05:31:56Z",
  "enable_auto_topup": true,
  "auto_topup_consent_token": "<string>",
  "quote_token": "<string>"
}
'

import requests

url = "https://app.famulor.io/api/v1/platform/users/{user_id}/plan"

payload = {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "plan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "expected_version": 2,
    "max_debit_credits": 6500000000000,
    "workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "ends_at": "2023-11-07T05:31:56Z",
    "enable_auto_topup": True,
    "auto_topup_consent_token": "<string>",
    "quote_token": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    request_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    plan_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    expected_version: 2,
    max_debit_credits: 6500000000000,
    workspace_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    ends_at: '2023-11-07T05:31:56Z',
    enable_auto_topup: true,
    auto_topup_consent_token: '<string>',
    quote_token: '<string>'
  })
};

fetch('https://app.famulor.io/api/v1/platform/users/{user_id}/plan', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.famulor.io/api/v1/platform/users/{user_id}/plan",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'request_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'plan_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'expected_version' => 2,
    'max_debit_credits' => 6500000000000,
    'workspace_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'ends_at' => '2023-11-07T05:31:56Z',
    'enable_auto_topup' => true,
    'auto_topup_consent_token' => '<string>',
    'quote_token' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.famulor.io/api/v1/platform/users/{user_id}/plan"

	payload := strings.NewReader("{\n  \"request_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"plan_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"expected_version\": 2,\n  \"max_debit_credits\": 6500000000000,\n  \"workspace_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"ends_at\": \"2023-11-07T05:31:56Z\",\n  \"enable_auto_topup\": true,\n  \"auto_topup_consent_token\": \"<string>\",\n  \"quote_token\": \"<string>\"\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://app.famulor.io/api/v1/platform/users/{user_id}/plan")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"request_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"plan_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"expected_version\": 2,\n  \"max_debit_credits\": 6500000000000,\n  \"workspace_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"ends_at\": \"2023-11-07T05:31:56Z\",\n  \"enable_auto_topup\": true,\n  \"auto_topup_consent_token\": \"<string>\",\n  \"quote_token\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.famulor.io/api/v1/platform/users/{user_id}/plan")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"request_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"plan_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"expected_version\": 2,\n  \"max_debit_credits\": 6500000000000,\n  \"workspace_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"ends_at\": \"2023-11-07T05:31:56Z\",\n  \"enable_auto_topup\": true,\n  \"auto_topup_consent_token\": \"<string>\",\n  \"quote_token\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "status": "active",
    "workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "version": 2,
    "required_credits": 1,
    "message": "<string>"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key."
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry after the indicated delay."
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "<string>"
  }
}

Authorizations

Authorization

string

header

required

API key (fam_..., created under Settings → API Keys) or an OAuth 2.0 access token (fam_at_...). REST operations also require API Access for the credential's workspace. Keys can be restricted to scopes such as assistants:read, calls:write, campaigns:write, automations:read, dashboards:read, dashboards:write, leads:write, segments:write, loop:read, loop:write, phone_numbers:write, sip_trunks:write, knowledge:write, voices:read, billing:read, billing:write, settings:write, platform:read, platform:write; a *:write scope implies the matching *:read. Automation and dashboard endpoints also accept the legacy calls:* scope. Keys without scope restrictions have full access within the workspace's available capabilities.

Path Parameters

user_id

string<uuid>

required

Customer user UUID.

Body

application/json

request_id

string<uuid>

required

Unique idempotency UUID. Reuse the same UUID only with identical input after an ambiguous response.

plan_id

string<uuid>

required

Reseller plan UUID from the current overview.

billing_interval

enum<string>

required

Monthly funding, or yearly funding with monthly allowance delivery.

Available options:

monthly,

yearly

shortage_policy

enum<string>

required

wait preserves remaining credits and retries funding; auto_topup uses the reseller saved top-up settings when funding is short.

Available options:

wait,

auto_topup

expected_version

integer | null

required

Current managed plan version from the overview. Use null only when assigning the first managed plan.

Required range: x >= 1

max_debit_credits

number

required

Maximum net credit debit accepted for this change after refundable credits. The operation fails if the current quote exceeds this amount.

Required range: 0 <= x <= 13000000000000

workspace_id

string<uuid>

Customer workspace UUID. Required when the customer workspace cannot be selected unambiguously.

ends_at

string<date-time> | null

Optional future end timestamp. Omit or use null for no scheduled end.

enable_auto_topup

boolean

Explicit consent to enable the reseller workspace existing auto-top-up settings. May lead to a saved-card charge; requires a configured amount and saved payment method.

Consent token from the reviewed overview auto-top-up settings. Required when shortage_policy is auto_topup, including when automatic top-up is already enabled; settings changes invalidate this token.

Pattern: ^[a-f0-9]{64}$

quote_token

string

Selected offer monthly_quote_token or yearly_quote_token from the reviewed overview. Required for a new assignment; not required when editing only existing agreement settings. Any change to the catalog or funding terms invalidates it.

Pattern: ^[a-f0-9]{64}$

Response

Managed plan operation result.

data

object

required

Show child attributes