Preview a project billing change

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

import requests

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

payload = {
    "category": "<string>",
    "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({category: '<string>', fixedCharge: {fixedChargeCode: '<string>', increment: 0}})
};

fetch('https://api.photon.codes/v1/organizations/{organizationId}/billing/projects/{projectId}/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/projects/{projectId}/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([
    'category' => '<string>',
    '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/projects/{projectId}/preview"

	payload := strings.NewReader("{\n  \"category\": \"<string>\",\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/projects/{projectId}/preview")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"category\": \"<string>\",\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/projects/{projectId}/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  \"category\": \"<string>\",\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 a project billing change

Previews a change on the selected project’s subscription in the supplied category: a fixed-charge quantity change, or a plan change with the held fixed charges it carries over. 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. An upgrade bills the replaced plan’s usage to date and the new plan from now, less the replaced plan’s unused time; planChange says when it applies and which held fixed charges the target does not sell: released first for a change that applies now, released with a downgrade when it applies. additions quotes what is added once an upgrade applies, each billed when it is added, in planChange.additions and outside dueNow. Supply both organizationId and projectId; the organization must pay for the project.

POST

organizations

{organizationId}

billing

projects

{projectId}

preview

Preview a project billing change

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

import requests

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

payload = {
    "category": "<string>",
    "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({category: '<string>', fixedCharge: {fixedChargeCode: '<string>', increment: 0}})
};

fetch('https://api.photon.codes/v1/organizations/{organizationId}/billing/projects/{projectId}/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/projects/{projectId}/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([
    'category' => '<string>',
    '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/projects/{projectId}/preview"

	payload := strings.NewReader("{\n  \"category\": \"<string>\",\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/projects/{projectId}/preview")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"category\": \"<string>\",\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/projects/{projectId}/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  \"category\": \"<string>\",\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

projectId

string

required

The project being billed.

Body

application/json

Option 1
Option 2

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 a project billing change

Authorizations

Path Parameters

Body

Response