Set who the org's invoices are made out to

Replaces the org’s billing details. Owners’ and admins’ keys only (403 forbidden otherwise). A field that cannot be saved is 400 bad_request with a message saying which and why.

A business may give a VIES-supported VAT ID with its explicit canonical prefix (EL for Greece, XI for Northern Ireland) and in that prefix’s format, regardless of the billing address’s country. A new such VAT ID, or one VIES found invalid before, is checked against VIES before this answers, so vat.status is usually valid or invalid already. If VIES does not answer, the details are saved with the VAT ID unverified and it is checked again later, after 5 minutes and then at doubling intervals of up to 6 hours. An invalid VAT ID is saved too. A business outside the EU may also give a non-EU tax ID, which is stored as not_checked. Consumers give no VAT ID.

PUT/v1/billing

Authorization

AuthorizationBearer token · headerrequired

Org-scoped API key, pols_....

Request body

requiredapplication/json

customer_typeCustomerTyperequired

Whether the org buys as a business (with a company name, and a VAT or tax ID if it has one) or as a consumer.

Allowed:businessconsumer

namestringrequired

The company's legal name, or the consumer's full name.

max length 200

address_line1stringrequired

max length 200

address_line2string

max length 200

postal_codestring

max length 20

citystringrequired

max length 100

countrystringrequired

ISO 3166-1 alpha-2 code of the billing address's country.

matches ^[A-Za-z]{2}$

vat_idstring

A business's VAT ID or tax ID; empty or left out for none. EU and Northern Ireland VAT IDs require an explicit canonical prefix (EL for Greece, XI for Northern Ireland), independent of the address country. Spaces, dots and dashes in such a VAT ID are dropped.

max length 60

Responses

200

The saved billing details.

detailsBillingDetails | nullrequired

Who invoices are made out to; null until saved.

Show properties

Any of:

BillingDetails

customer_typeCustomerTyperequired

Whether the org buys as a business (with a company name, and a VAT or tax ID if it has one) or as a consumer.

Allowed:businessconsumer

namestringrequired

address_line1stringrequired

address_line2stringrequired

postal_codestringrequired

citystringrequired

countrystringrequired

ISO 3166-1 alpha-2 code, upper case.

vat_idstringrequired

The normalized VAT or tax ID; VIES-supported VAT IDs include their canonical prefix. Empty for none.

vatVATInforequired

Show properties

statusVATStatusrequired

none: no VAT ID. unverified: a VAT ID VIES has not answered for yet; it is checked again at next_check_at. valid or invalid: VIES's answer at checked_at. not_checked: a tax ID that VIES does not cover.

Allowed:noneunverifiedvalidinvalidnot_checked

checked_atstring<date-time> | null

When VIES last answered valid or invalid.

consultation_numberstring | null

VIES's consultation number for that answer, which proves the check was made. Null when the deployment makes checks without a requester VAT ID.

next_check_atstring<date-time> | null

When an unverified VAT ID is checked next.

updated_atstring<date-time>required

null

null

429

Rate limited (rate_limited): too many requests or failed authentications from this address, too many requests or lifecycle calls for this org, or too many of its exec, file, computer and CDP calls in progress at once. Retry after Retry-After seconds.

errorobjectrequired

Show properties

codestringrequired

Stable machine-readable code: bad_request (400), unauthorized (401), insufficient_credit (402, no credit left to start a sandbox), forbidden (403), quota_exceeded (403), trial_limit (403, beyond what a trial org may run), not_found (404), conflict (409), billing_details_required (409, save the billing details before topping up), topup_not_available (409, the org cannot top up as it would be taxed; the message says why), withdrawal_consent_required (409, a consumer orders a top-up or the subscription only with withdrawal_consent), desktop_controlled (409, a person viewing the desktop has taken control of it, see control), rate_limited (429, see Retry-After), trial_capacity (429, all trial capacity in use; retry after Retry-After), host_capacity (429, the host is short of memory right now, so nothing new starts there; retry after Retry-After), internal (500), runtime_error (502, the sandbox host failed), payment_provider_error (502, Mollie could not be reached or refused a payment), unavailable (503, the feature is not configured on this deployment), waking (503, the sandbox is still waking from standby or booting; retry), timeout (504, or 408 when a request body stalls).

messagestringrequired

controlDesktopControl

Who has control of a sandbox's desktop. In an error, it is present only with code desktop_controlled.

Show properties

heldbooleanrequired

Someone viewing the desktop has taken control of it.

holderstring

Only when held; their name as the desktop's viewers see it, their user's name or else their API key's.

sincestring<date-time>

Only when held; when they took control.

expires_atstring<date-time>

Only when held; when control lapses unless they use the desktop before.

default

Error.

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

controlDesktopControl

Who has control of a sandbox's desktop. In an error, it is present only with code desktop_controlled.

Show properties

heldbooleanrequired

Someone viewing the desktop has taken control of it.

holderstring

Only when held; their name as the desktop's viewers see it, their user's name or else their API key's.

sincestring<date-time>

Only when held; when they took control.

expires_atstring<date-time>

Only when held; when control lapses unless they use the desktop before.

Request

curl -X PUT 'https://api.pols.so/v1/billing' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "customer_type": "business",
  "name": "Example GmbH",
  "address_line1": "Hauptstraße 1",
  "address_line2": "string",
  "postal_code": "10115",
  "city": "Berlin",
  "country": "DE",
  "vat_id": "DE123456789"
}'

const response = await fetch("https://api.pols.so/v1/billing", {
  method: "PUT",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"customer_type\": \"business\",\n  \"name\": \"Example GmbH\",\n  \"address_line1\": \"Hauptstraße 1\",\n  \"address_line2\": \"string\",\n  \"postal_code\": \"10115\",\n  \"city\": \"Berlin\",\n  \"country\": \"DE\",\n  \"vat_id\": \"DE123456789\"\n}"
});

import requests

response = requests.put(
    "https://api.pols.so/v1/billing",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"customer_type\": \"business\",\n  \"name\": \"Example GmbH\",\n  \"address_line1\": \"Hauptstraße 1\",\n  \"address_line2\": \"string\",\n  \"postal_code\": \"10115\",\n  \"city\": \"Berlin\",\n  \"country\": \"DE\",\n  \"vat_id\": \"DE123456789\"\n}",
)

Response

{
  "details": {
    "customer_type": "business",
    "name": "string",
    "address_line1": "string",
    "address_line2": "string",
    "postal_code": "string",
    "city": "string",
    "country": "string",
    "vat_id": "string",
    "vat": {
      "status": "none",
      "checked_at": "2019-08-24T14:15:22Z",
      "consultation_number": "string",
      "next_check_at": "2019-08-24T14:15:22Z"
    },
    "updated_at": "2019-08-24T14:15:22Z"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "control": {
      "held": true,
      "holder": "Ada",
      "since": "2019-08-24T14:15:22Z",
      "expires_at": "2019-08-24T14:15:22Z"
    }
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "control": {
      "held": true,
      "holder": "Ada",
      "since": "2019-08-24T14:15:22Z",
      "expires_at": "2019-08-24T14:15:22Z"
    }
  }
}