Billing and invoices
Update your billing details
Replaces all billing details: send every field, as a missing field is cleared. Each value is checked (for example the tax ID format for its type and country); a rejected value returns 400 with fields, and nothing is saved.
Locking. You can save incomplete details as often as you need. Once complete details are saved (complete: true), they are locked (locked: true) and further updates return 403 BILLING_DETAILS_LOCKED, CC emails included. Contact Hyperprop at finance@hyperprop.com to change locked details. Read the details first and send only when locked is false.
Tax ID types: eu_vat, gb_vat, ch_vat, no_vat, us_ein, ca_bn, au_abn, nz_gst, ae_trn, sg_uen, sg_gst, hk_br, in_gst, il_vat, jp_cn, kr_brn, za_vat, br_cnpj, mx_rfc, sa_vat.
Invoice emails go to the billing email; CC emails are stored as extra invoice contacts. At most 20 updates per 10 minutes per organization (429 RATE_LIMITED with Retry-After).
Access: full-access API keys only (a read-only key gets 403 READ_ONLY_KEY). Dashboard members need manage access to Billing & purchases revenue.
PUT
/
v1
/
organization
/
billing
/
details
Update your billing details
curl --request PUT \
--url https://api.hyperprop.com/platform/v1/organization/billing/details \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"legalName": "Example Trading Ltd.",
"billingEmail": "ap@example.com",
"ccEmails": [
"<string>"
],
"address": {
"line1": "Herengracht 100",
"line2": "<string>",
"city": "Amsterdam",
"state": "<string>",
"postalCode": "1015 BS",
"country": "NL"
}
}
'import requests
url = "https://api.hyperprop.com/platform/v1/organization/billing/details"
payload = {
"legalName": "Example Trading Ltd.",
"billingEmail": "ap@example.com",
"ccEmails": ["<string>"],
"address": {
"line1": "Herengracht 100",
"line2": "<string>",
"city": "Amsterdam",
"state": "<string>",
"postalCode": "1015 BS",
"country": "NL"
}
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
legalName: 'Example Trading Ltd.',
billingEmail: 'ap@example.com',
ccEmails: ['<string>'],
address: {
line1: 'Herengracht 100',
line2: '<string>',
city: 'Amsterdam',
state: '<string>',
postalCode: '1015 BS',
country: 'NL'
}
})
};
fetch('https://api.hyperprop.com/platform/v1/organization/billing/details', 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://api.hyperprop.com/platform/v1/organization/billing/details",
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([
'legalName' => 'Example Trading Ltd.',
'billingEmail' => 'ap@example.com',
'ccEmails' => [
'<string>'
],
'address' => [
'line1' => 'Herengracht 100',
'line2' => '<string>',
'city' => 'Amsterdam',
'state' => '<string>',
'postalCode' => '1015 BS',
'country' => 'NL'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$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://api.hyperprop.com/platform/v1/organization/billing/details"
payload := strings.NewReader("{\n \"legalName\": \"Example Trading Ltd.\",\n \"billingEmail\": \"ap@example.com\",\n \"ccEmails\": [\n \"<string>\"\n ],\n \"address\": {\n \"line1\": \"Herengracht 100\",\n \"line2\": \"<string>\",\n \"city\": \"Amsterdam\",\n \"state\": \"<string>\",\n \"postalCode\": \"1015 BS\",\n \"country\": \"NL\"\n }\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
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://api.hyperprop.com/platform/v1/organization/billing/details")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"legalName\": \"Example Trading Ltd.\",\n \"billingEmail\": \"ap@example.com\",\n \"ccEmails\": [\n \"<string>\"\n ],\n \"address\": {\n \"line1\": \"Herengracht 100\",\n \"line2\": \"<string>\",\n \"city\": \"Amsterdam\",\n \"state\": \"<string>\",\n \"postalCode\": \"1015 BS\",\n \"country\": \"NL\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.hyperprop.com/platform/v1/organization/billing/details")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"legalName\": \"Example Trading Ltd.\",\n \"billingEmail\": \"ap@example.com\",\n \"ccEmails\": [\n \"<string>\"\n ],\n \"address\": {\n \"line1\": \"Herengracht 100\",\n \"line2\": \"<string>\",\n \"city\": \"Amsterdam\",\n \"state\": \"<string>\",\n \"postalCode\": \"1015 BS\",\n \"country\": \"NL\"\n }\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"details": {
"organizationId": "0e9b6a14-7c2d-4b8f-93a1-6d5e2f8c0b47",
"organizationName": "Acme Trading Co",
"legalName": "Example Trading Ltd.",
"billingEmail": "ap@example.com",
"ccEmails": [
"finance@example.com"
],
"address": {
"line1": "Herengracht 100",
"line2": "<string>",
"city": "Amsterdam",
"state": "<string>",
"postalCode": "1015 BS",
"country": "NL"
},
"taxId": {
"type": "eu_vat",
"value": "NL123456789B01"
},
"complete": true,
"missing": [],
"locked": true,
"updatedAt": "2026-10-28T10:12:00.000Z"
}
}
}{
"success": false,
"statusCode": 400,
"error": "Bad Request",
"message": "taxId.value: This does not look like a valid EU VAT number",
"code": "INVALID_BILLING_DETAILS",
"fields": [
{
"field": "taxId.value",
"message": "This does not look like a valid EU VAT number"
}
]
}{
"success": false,
"statusCode": 401,
"error": "Unauthorized",
"message": "Authentication required",
"code": "UNAUTHORIZED"
}{
"success": false,
"statusCode": 403,
"error": "Forbidden",
"message": "Billing details are locked. Contact Hyperprop at finance@hyperprop.com to change them.",
"code": "BILLING_DETAILS_LOCKED"
}{
"success": false,
"statusCode": 409,
"error": "Conflict",
"message": "This Idempotency-Key was already used with a different request body. Use a new key for a different request.",
"code": "IDEMPOTENCY_KEY_REUSED"
}{
"success": false,
"statusCode": 429,
"error": "Too Many Requests",
"message": "Too many requests (limit: 20 per 10 minutes per organization). Retry after `Retry-After` seconds",
"code": "RATE_LIMITED"
}{
"success": false,
"statusCode": 500,
"error": "Internal Server Error",
"message": "An unexpected error occurred",
"code": "INTERNAL_ERROR"
}Authorizations
Organization API key (hp_live_...), sent in the X-API-Key header. Create, rotate and restrict keys in the dashboard or with the API keys endpoints; an organization can have two active keys, so you can rotate without downtime. A full-access key can call every endpoint in this reference. A read-only key can call GET endpoints (and create a trading stream token); any other request returns 403 READ_ONLY_KEY. A key with an IP allowlist returns 403 IP_NOT_ALLOWED from any other address. Each endpoint lists which keys can call it under Access.
Headers
Optional. A value that identifies this operation on your side, at most 255 characters. A retry with the same key, method, path and body within 24 hours returns the original response (with Idempotency-Replayed: true) instead of repeating the change. The same key with a different body returns 409 IDEMPOTENCY_KEY_REUSED; a retry while the first request is still running returns 409 IDEMPOTENCY_KEY_IN_PROGRESS. Server errors (5xx) are not saved, so a retry runs again.
Maximum string length:
255Body
application/json
Maximum string length:
200Example:
"Example Trading Ltd."
Maximum string length:
254Example:
"ap@example.com"
Extra contacts for invoices. Invoice emails currently go to the billing email only.
Maximum array length:
10Maximum string length:
254Show child attributes
Show child attributes
Show child attributes
Show child attributes
⌘I
Update your billing details
curl --request PUT \
--url https://api.hyperprop.com/platform/v1/organization/billing/details \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"legalName": "Example Trading Ltd.",
"billingEmail": "ap@example.com",
"ccEmails": [
"<string>"
],
"address": {
"line1": "Herengracht 100",
"line2": "<string>",
"city": "Amsterdam",
"state": "<string>",
"postalCode": "1015 BS",
"country": "NL"
}
}
'import requests
url = "https://api.hyperprop.com/platform/v1/organization/billing/details"
payload = {
"legalName": "Example Trading Ltd.",
"billingEmail": "ap@example.com",
"ccEmails": ["<string>"],
"address": {
"line1": "Herengracht 100",
"line2": "<string>",
"city": "Amsterdam",
"state": "<string>",
"postalCode": "1015 BS",
"country": "NL"
}
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
legalName: 'Example Trading Ltd.',
billingEmail: 'ap@example.com',
ccEmails: ['<string>'],
address: {
line1: 'Herengracht 100',
line2: '<string>',
city: 'Amsterdam',
state: '<string>',
postalCode: '1015 BS',
country: 'NL'
}
})
};
fetch('https://api.hyperprop.com/platform/v1/organization/billing/details', 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://api.hyperprop.com/platform/v1/organization/billing/details",
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([
'legalName' => 'Example Trading Ltd.',
'billingEmail' => 'ap@example.com',
'ccEmails' => [
'<string>'
],
'address' => [
'line1' => 'Herengracht 100',
'line2' => '<string>',
'city' => 'Amsterdam',
'state' => '<string>',
'postalCode' => '1015 BS',
'country' => 'NL'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$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://api.hyperprop.com/platform/v1/organization/billing/details"
payload := strings.NewReader("{\n \"legalName\": \"Example Trading Ltd.\",\n \"billingEmail\": \"ap@example.com\",\n \"ccEmails\": [\n \"<string>\"\n ],\n \"address\": {\n \"line1\": \"Herengracht 100\",\n \"line2\": \"<string>\",\n \"city\": \"Amsterdam\",\n \"state\": \"<string>\",\n \"postalCode\": \"1015 BS\",\n \"country\": \"NL\"\n }\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
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://api.hyperprop.com/platform/v1/organization/billing/details")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"legalName\": \"Example Trading Ltd.\",\n \"billingEmail\": \"ap@example.com\",\n \"ccEmails\": [\n \"<string>\"\n ],\n \"address\": {\n \"line1\": \"Herengracht 100\",\n \"line2\": \"<string>\",\n \"city\": \"Amsterdam\",\n \"state\": \"<string>\",\n \"postalCode\": \"1015 BS\",\n \"country\": \"NL\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.hyperprop.com/platform/v1/organization/billing/details")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"legalName\": \"Example Trading Ltd.\",\n \"billingEmail\": \"ap@example.com\",\n \"ccEmails\": [\n \"<string>\"\n ],\n \"address\": {\n \"line1\": \"Herengracht 100\",\n \"line2\": \"<string>\",\n \"city\": \"Amsterdam\",\n \"state\": \"<string>\",\n \"postalCode\": \"1015 BS\",\n \"country\": \"NL\"\n }\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"details": {
"organizationId": "0e9b6a14-7c2d-4b8f-93a1-6d5e2f8c0b47",
"organizationName": "Acme Trading Co",
"legalName": "Example Trading Ltd.",
"billingEmail": "ap@example.com",
"ccEmails": [
"finance@example.com"
],
"address": {
"line1": "Herengracht 100",
"line2": "<string>",
"city": "Amsterdam",
"state": "<string>",
"postalCode": "1015 BS",
"country": "NL"
},
"taxId": {
"type": "eu_vat",
"value": "NL123456789B01"
},
"complete": true,
"missing": [],
"locked": true,
"updatedAt": "2026-10-28T10:12:00.000Z"
}
}
}{
"success": false,
"statusCode": 400,
"error": "Bad Request",
"message": "taxId.value: This does not look like a valid EU VAT number",
"code": "INVALID_BILLING_DETAILS",
"fields": [
{
"field": "taxId.value",
"message": "This does not look like a valid EU VAT number"
}
]
}{
"success": false,
"statusCode": 401,
"error": "Unauthorized",
"message": "Authentication required",
"code": "UNAUTHORIZED"
}{
"success": false,
"statusCode": 403,
"error": "Forbidden",
"message": "Billing details are locked. Contact Hyperprop at finance@hyperprop.com to change them.",
"code": "BILLING_DETAILS_LOCKED"
}{
"success": false,
"statusCode": 409,
"error": "Conflict",
"message": "This Idempotency-Key was already used with a different request body. Use a new key for a different request.",
"code": "IDEMPOTENCY_KEY_REUSED"
}{
"success": false,
"statusCode": 429,
"error": "Too Many Requests",
"message": "Too many requests (limit: 20 per 10 minutes per organization). Retry after `Retry-After` seconds",
"code": "RATE_LIMITED"
}{
"success": false,
"statusCode": 500,
"error": "Internal Server Error",
"message": "An unexpected error occurred",
"code": "INTERNAL_ERROR"
}