Preview an organization billing change

curl --request POST \
  --url https://api.photon.codes/v1/organizations/{organizationId}/billing/preview \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "fixedCharge": {
    "fixedChargeCode": "<string>",
    "increment": 0
  }
}
'

import requests

url = "https://api.photon.codes/v1/organizations/{organizationId}/billing/preview"

payload = { "fixedCharge": {
        "fixedChargeCode": "<string>",
        "increment": 0
    } }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({fixedCharge: {fixedChargeCode: '<string>', increment: 0}})
};

fetch('https://api.photon.codes/v1/organizations/{organizationId}/billing/preview', 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.photon.codes/v1/organizations/{organizationId}/billing/preview",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'fixedCharge' => [
        'fixedChargeCode' => '<string>',
        'increment' => 0
    ]
  ]),
  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://api.photon.codes/v1/organizations/{organizationId}/billing/preview"

	payload := strings.NewReader("{\n  \"fixedCharge\": {\n    \"fixedChargeCode\": \"<string>\",\n    \"increment\": 0\n  }\n}")

	req, _ := http.NewRequest("POST", 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.post("https://api.photon.codes/v1/organizations/{organizationId}/billing/preview")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"fixedCharge\": {\n    \"fixedChargeCode\": \"<string>\",\n    \"increment\": 0\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.photon.codes/v1/organizations/{organizationId}/billing/preview")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"fixedCharge\": {\n    \"fixedChargeCode\": \"<string>\",\n    \"increment\": 0\n  }\n}"

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

{
  "balanceAfterCents": 0,
  "dueNow": {
    "creditsCents": 0,
    "currency": "<string>",
    "discountCents": 0,
    "feesCents": 0,
    "lines": [
      {
        "amountCents": 0,
        "code": "<string>",
        "kind": "fixed_charge",
        "name": "<string>",
        "periodEnd": "<string>",
        "periodStart": "<string>",
        "units": "<string>"
      }
    ],
    "taxesCents": 0,
    "totalCents": 0
  },
  "nextCharge": {
    "amountCents": 0,
    "at": "<string>",
    "currency": "<string>"
  },
  "planChange": {
    "additions": [
      {
        "amountCents": 0,
        "code": "<string>",
        "kind": "fixed_charge",
        "name": "<string>",
        "periodEnd": "<string>",
        "periodStart": "<string>",
        "units": "<string>"
      }
    ],
    "effectiveAt": "<string>",
    "minimumCommitment": {
      "amountCents": 0,
      "currentPeriodAmountCents": 0,
      "currentPeriodEnd": "<string>",
      "currentPeriodStart": "<string>"
    },
    "timing": "immediate",
    "unsoldFixedCharges": [
      {
        "fixedChargeCode": "<string>",
        "quantity": 0
      }
    ],
    "unusedTimeCredit": {
      "amountCents": 0,
      "code": "<string>",
      "name": "<string>",
      "periodEnd": "<string>",
      "periodStart": "<string>"
    }
  },
  "quote": {
    "amount": "<string>",
    "currency": "<string>",
    "currentPeriodEnd": "<string>"
  },
  "timeZone": "<string>"
}

{
  "code": "INVALID_ARGUMENT",
  "status": 400,
  "title": "Invalid Argument",
  "type": "https://photon.codes/docs/problems/invalid-argument"
}

{
  "code": "NOT_AUTHENTICATED",
  "status": 401,
  "title": "Not Authenticated",
  "type": "https://photon.codes/docs/problems/not-authenticated"
}

{
  "code": "FORBIDDEN",
  "status": 403,
  "title": "Forbidden",
  "type": "https://photon.codes/docs/problems/forbidden"
}

{
  "code": "FAILED_PRECONDITION",
  "status": 409,
  "title": "Failed Precondition",
  "type": "https://photon.codes/docs/problems/failed-precondition"
}

{
  "code": "VALIDATION_FAILED",
  "issues": [
    {
      "code": "invalid_type",
      "location": "json",
      "message": "Expected a string.",
      "path": "/name"
    }
  ],
  "status": 422,
  "title": "Request Validation Failed",
  "type": "https://photon.codes/docs/problems/validation-failed"
}

{
  "code": "INTERNAL_ERROR",
  "status": 500,
  "title": "Internal Server Error",
  "type": "https://photon.codes/docs/problems/internal-error"
}

{
  "code": "UPSTREAM_FAILURE",
  "status": 502,
  "title": "Upstream Service Failure",
  "type": "https://photon.codes/docs/problems/upstream-failure"
}

{
  "code": "UPSTREAM_UNAVAILABLE",
  "status": 503,
  "title": "Upstream Service Unavailable",
  "type": "https://photon.codes/docs/problems/upstream-unavailable"
}

{
  "code": "REQUEST_TIMEOUT",
  "status": 504,
  "title": "Request Timeout",
  "type": "https://photon.codes/docs/problems/request-timeout"
}

Organization Billing

Preview an organization billing change

Previews a fixed-charge quantity change on the selected organization’s own subscription, such as SSO. Prices the change by the billing engine exactly as making it would bill it now: dueNow is that invoice, with taxes and the payer’s credits applied. A quantity already paid for this period is not billed again, so a purchase after a release can be free. nextCharge is what is charged in advance at the next period start. For a fixed-charge change, pass quote on with the purchase so it is refused if the price or period no longer hold. This operation does not change billing.

POST

organizations

{organizationId}

billing

preview

Preview an organization billing change

curl --request POST \
  --url https://api.photon.codes/v1/organizations/{organizationId}/billing/preview \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "fixedCharge": {
    "fixedChargeCode": "<string>",
    "increment": 0
  }
}
'

import requests

url = "https://api.photon.codes/v1/organizations/{organizationId}/billing/preview"

payload = { "fixedCharge": {
        "fixedChargeCode": "<string>",
        "increment": 0
    } }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({fixedCharge: {fixedChargeCode: '<string>', increment: 0}})
};

fetch('https://api.photon.codes/v1/organizations/{organizationId}/billing/preview', 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.photon.codes/v1/organizations/{organizationId}/billing/preview",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'fixedCharge' => [
        'fixedChargeCode' => '<string>',
        'increment' => 0
    ]
  ]),
  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://api.photon.codes/v1/organizations/{organizationId}/billing/preview"

	payload := strings.NewReader("{\n  \"fixedCharge\": {\n    \"fixedChargeCode\": \"<string>\",\n    \"increment\": 0\n  }\n}")

	req, _ := http.NewRequest("POST", 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.post("https://api.photon.codes/v1/organizations/{organizationId}/billing/preview")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"fixedCharge\": {\n    \"fixedChargeCode\": \"<string>\",\n    \"increment\": 0\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.photon.codes/v1/organizations/{organizationId}/billing/preview")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"fixedCharge\": {\n    \"fixedChargeCode\": \"<string>\",\n    \"increment\": 0\n  }\n}"

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

{
  "balanceAfterCents": 0,
  "dueNow": {
    "creditsCents": 0,
    "currency": "<string>",
    "discountCents": 0,
    "feesCents": 0,
    "lines": [
      {
        "amountCents": 0,
        "code": "<string>",
        "kind": "fixed_charge",
        "name": "<string>",
        "periodEnd": "<string>",
        "periodStart": "<string>",
        "units": "<string>"
      }
    ],
    "taxesCents": 0,
    "totalCents": 0
  },
  "nextCharge": {
    "amountCents": 0,
    "at": "<string>",
    "currency": "<string>"
  },
  "planChange": {
    "additions": [
      {
        "amountCents": 0,
        "code": "<string>",
        "kind": "fixed_charge",
        "name": "<string>",
        "periodEnd": "<string>",
        "periodStart": "<string>",
        "units": "<string>"
      }
    ],
    "effectiveAt": "<string>",
    "minimumCommitment": {
      "amountCents": 0,
      "currentPeriodAmountCents": 0,
      "currentPeriodEnd": "<string>",
      "currentPeriodStart": "<string>"
    },
    "timing": "immediate",
    "unsoldFixedCharges": [
      {
        "fixedChargeCode": "<string>",
        "quantity": 0
      }
    ],
    "unusedTimeCredit": {
      "amountCents": 0,
      "code": "<string>",
      "name": "<string>",
      "periodEnd": "<string>",
      "periodStart": "<string>"
    }
  },
  "quote": {
    "amount": "<string>",
    "currency": "<string>",
    "currentPeriodEnd": "<string>"
  },
  "timeZone": "<string>"
}

{
  "code": "INVALID_ARGUMENT",
  "status": 400,
  "title": "Invalid Argument",
  "type": "https://photon.codes/docs/problems/invalid-argument"
}

{
  "code": "NOT_AUTHENTICATED",
  "status": 401,
  "title": "Not Authenticated",
  "type": "https://photon.codes/docs/problems/not-authenticated"
}

{
  "code": "FORBIDDEN",
  "status": 403,
  "title": "Forbidden",
  "type": "https://photon.codes/docs/problems/forbidden"
}

{
  "code": "FAILED_PRECONDITION",
  "status": 409,
  "title": "Failed Precondition",
  "type": "https://photon.codes/docs/problems/failed-precondition"
}

{
  "code": "VALIDATION_FAILED",
  "issues": [
    {
      "code": "invalid_type",
      "location": "json",
      "message": "Expected a string.",
      "path": "/name"
    }
  ],
  "status": 422,
  "title": "Request Validation Failed",
  "type": "https://photon.codes/docs/problems/validation-failed"
}

{
  "code": "INTERNAL_ERROR",
  "status": 500,
  "title": "Internal Server Error",
  "type": "https://photon.codes/docs/problems/internal-error"
}

{
  "code": "UPSTREAM_FAILURE",
  "status": 502,
  "title": "Upstream Service Failure",
  "type": "https://photon.codes/docs/problems/upstream-failure"
}

{
  "code": "UPSTREAM_UNAVAILABLE",
  "status": 503,
  "title": "Upstream Service Unavailable",
  "type": "https://photon.codes/docs/problems/upstream-unavailable"
}

{
  "code": "REQUEST_TIMEOUT",
  "status": 504,
  "title": "Request Timeout",
  "type": "https://photon.codes/docs/problems/request-timeout"
}

Authorizations

Authorization

string

header

required

Account Service Key, prefixed with pho_ask_, sent as Authorization: Bearer <key>. Acts on behalf of its owning account, subject to the permissions and credential restrictions of each operation. Account access tokens and OAuth grants also use the Bearer header. In organizations that require SSO, Account Service Keys are not accepted for managing the organization's SSO settings, deleting the organization, or checking whether it can be deleted.

Path Parameters

organizationId

string

required

Body

application/json

fixedCharge

object

required

A quantity change made now, as a purchase or release makes it.

Show child attributes

Response

What the change would bill.

balanceAfterCents

integer | null

required

The payer's credit balance once dueNow is charged: the credit the change issues included, less what dueNow uses. In dueNow's currency. Null when the change charges nothing now (a downgrade).

Required range: -9007199254740991 <= x <= 9007199254740991

dueNow

object

required

Charged when the change is made, priced as the change bills it. No lines when it charges nothing now.

Show child attributes

nextCharge

object | null

required

What is charged in advance at the next period start for what is held after the change. Usage and a minimum commitment are billed after the period. Null when nothing is, or the subscription ends first.

Show child attributes

planChange

object | null

required

Set for a plan change, null otherwise.

Show child attributes

quote

object | null

required

Set for a fixed-charge change, null otherwise: the unit price, currency and period the preview was priced on. Pass them on with the purchase so it is refused if they no longer hold.

Show child attributes

timeZone

string

required

The IANA time zone the payer is billed in, e.g. America/Los_Angeles. Billing periods start and end at its midnights, so read their calendar dates in it.

⌘I

Get started

Problems

Endpoints

Event Delivery WebSocket

Event schemas

Preview an organization billing change

Authorizations

Path Parameters

Body

Response