Create Checkout Session

POST

checkouts

curl --request POST \
  --url https://api.getruba.com/v1/checkouts/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "products": [
    "<string>"
  ],
  "trial_interval_count": 500,
  "metadata": {},
  "custom_field_data": {},
  "discount_id": "<string>",
  "allow_discount_codes": true,
  "require_billing_address": false,
  "amount": 1,
  "seats": 5000,
  "min_seats": 5000,
  "max_seats": 5000,
  "allow_trial": true,
  "customer_id": "<string>",
  "is_business_customer": false,
  "external_customer_id": "<string>",
  "customer_name": "John Doe",
  "customer_email": "jsmith@example.com",
  "customer_ip_address": "<string>",
  "customer_billing_name": "<string>",
  "customer_billing_address": {
    "line1": "<string>",
    "line2": "<string>",
    "postal_code": "<string>",
    "city": "<string>",
    "state": "<string>"
  },
  "customer_tax_id": "<string>",
  "customer_metadata": {},
  "subscription_id": "<string>",
  "success_url": "<string>",
  "return_url": "<string>",
  "embed_origin": "<string>",
  "locale": "en",
  "prices": {}
}
'

import requests

url = "https://api.getruba.com/v1/checkouts/"

payload = {
    "products": ["<string>"],
    "trial_interval_count": 500,
    "metadata": {},
    "custom_field_data": {},
    "discount_id": "<string>",
    "allow_discount_codes": True,
    "require_billing_address": False,
    "amount": 1,
    "seats": 5000,
    "min_seats": 5000,
    "max_seats": 5000,
    "allow_trial": True,
    "customer_id": "<string>",
    "is_business_customer": False,
    "external_customer_id": "<string>",
    "customer_name": "John Doe",
    "customer_email": "jsmith@example.com",
    "customer_ip_address": "<string>",
    "customer_billing_name": "<string>",
    "customer_billing_address": {
        "line1": "<string>",
        "line2": "<string>",
        "postal_code": "<string>",
        "city": "<string>",
        "state": "<string>"
    },
    "customer_tax_id": "<string>",
    "customer_metadata": {},
    "subscription_id": "<string>",
    "success_url": "<string>",
    "return_url": "<string>",
    "embed_origin": "<string>",
    "locale": "en",
    "prices": {}
}
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({
    products: ['<string>'],
    trial_interval_count: 500,
    metadata: {},
    custom_field_data: {},
    discount_id: '<string>',
    allow_discount_codes: true,
    require_billing_address: false,
    amount: 1,
    seats: 5000,
    min_seats: 5000,
    max_seats: 5000,
    allow_trial: true,
    customer_id: '<string>',
    is_business_customer: false,
    external_customer_id: '<string>',
    customer_name: 'John Doe',
    customer_email: 'jsmith@example.com',
    customer_ip_address: '<string>',
    customer_billing_name: '<string>',
    customer_billing_address: {
      line1: '<string>',
      line2: '<string>',
      postal_code: '<string>',
      city: '<string>',
      state: '<string>'
    },
    customer_tax_id: '<string>',
    customer_metadata: {},
    subscription_id: '<string>',
    success_url: '<string>',
    return_url: '<string>',
    embed_origin: '<string>',
    locale: 'en',
    prices: {}
  })
};

fetch('https://api.getruba.com/v1/checkouts/', 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.getruba.com/v1/checkouts/",
  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([
    'products' => [
        '<string>'
    ],
    'trial_interval_count' => 500,
    'metadata' => [
        
    ],
    'custom_field_data' => [
        
    ],
    'discount_id' => '<string>',
    'allow_discount_codes' => true,
    'require_billing_address' => false,
    'amount' => 1,
    'seats' => 5000,
    'min_seats' => 5000,
    'max_seats' => 5000,
    'allow_trial' => true,
    'customer_id' => '<string>',
    'is_business_customer' => false,
    'external_customer_id' => '<string>',
    'customer_name' => 'John Doe',
    'customer_email' => 'jsmith@example.com',
    'customer_ip_address' => '<string>',
    'customer_billing_name' => '<string>',
    'customer_billing_address' => [
        'line1' => '<string>',
        'line2' => '<string>',
        'postal_code' => '<string>',
        'city' => '<string>',
        'state' => '<string>'
    ],
    'customer_tax_id' => '<string>',
    'customer_metadata' => [
        
    ],
    'subscription_id' => '<string>',
    'success_url' => '<string>',
    'return_url' => '<string>',
    'embed_origin' => '<string>',
    'locale' => 'en',
    'prices' => [
        
    ]
  ]),
  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.getruba.com/v1/checkouts/"

	payload := strings.NewReader("{\n  \"products\": [\n    \"<string>\"\n  ],\n  \"trial_interval_count\": 500,\n  \"metadata\": {},\n  \"custom_field_data\": {},\n  \"discount_id\": \"<string>\",\n  \"allow_discount_codes\": true,\n  \"require_billing_address\": false,\n  \"amount\": 1,\n  \"seats\": 5000,\n  \"min_seats\": 5000,\n  \"max_seats\": 5000,\n  \"allow_trial\": true,\n  \"customer_id\": \"<string>\",\n  \"is_business_customer\": false,\n  \"external_customer_id\": \"<string>\",\n  \"customer_name\": \"John Doe\",\n  \"customer_email\": \"jsmith@example.com\",\n  \"customer_ip_address\": \"<string>\",\n  \"customer_billing_name\": \"<string>\",\n  \"customer_billing_address\": {\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\"\n  },\n  \"customer_tax_id\": \"<string>\",\n  \"customer_metadata\": {},\n  \"subscription_id\": \"<string>\",\n  \"success_url\": \"<string>\",\n  \"return_url\": \"<string>\",\n  \"embed_origin\": \"<string>\",\n  \"locale\": \"en\",\n  \"prices\": {}\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.getruba.com/v1/checkouts/")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"products\": [\n    \"<string>\"\n  ],\n  \"trial_interval_count\": 500,\n  \"metadata\": {},\n  \"custom_field_data\": {},\n  \"discount_id\": \"<string>\",\n  \"allow_discount_codes\": true,\n  \"require_billing_address\": false,\n  \"amount\": 1,\n  \"seats\": 5000,\n  \"min_seats\": 5000,\n  \"max_seats\": 5000,\n  \"allow_trial\": true,\n  \"customer_id\": \"<string>\",\n  \"is_business_customer\": false,\n  \"external_customer_id\": \"<string>\",\n  \"customer_name\": \"John Doe\",\n  \"customer_email\": \"jsmith@example.com\",\n  \"customer_ip_address\": \"<string>\",\n  \"customer_billing_name\": \"<string>\",\n  \"customer_billing_address\": {\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\"\n  },\n  \"customer_tax_id\": \"<string>\",\n  \"customer_metadata\": {},\n  \"subscription_id\": \"<string>\",\n  \"success_url\": \"<string>\",\n  \"return_url\": \"<string>\",\n  \"embed_origin\": \"<string>\",\n  \"locale\": \"en\",\n  \"prices\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.getruba.com/v1/checkouts/")

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  \"products\": [\n    \"<string>\"\n  ],\n  \"trial_interval_count\": 500,\n  \"metadata\": {},\n  \"custom_field_data\": {},\n  \"discount_id\": \"<string>\",\n  \"allow_discount_codes\": true,\n  \"require_billing_address\": false,\n  \"amount\": 1,\n  \"seats\": 5000,\n  \"min_seats\": 5000,\n  \"max_seats\": 5000,\n  \"allow_trial\": true,\n  \"customer_id\": \"<string>\",\n  \"is_business_customer\": false,\n  \"external_customer_id\": \"<string>\",\n  \"customer_name\": \"John Doe\",\n  \"customer_email\": \"jsmith@example.com\",\n  \"customer_ip_address\": \"<string>\",\n  \"customer_billing_name\": \"<string>\",\n  \"customer_billing_address\": {\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\"\n  },\n  \"customer_tax_id\": \"<string>\",\n  \"customer_metadata\": {},\n  \"subscription_id\": \"<string>\",\n  \"success_url\": \"<string>\",\n  \"return_url\": \"<string>\",\n  \"embed_origin\": \"<string>\",\n  \"locale\": \"en\",\n  \"prices\": {}\n}"

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

{
  "id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "modified_at": "2023-11-07T05:31:56Z",
  "payment_processor": "stripe",
  "client_secret": "<string>",
  "url": "<string>",
  "expires_at": "2023-11-07T05:31:56Z",
  "success_url": "<string>",
  "return_url": "<string>",
  "embed_origin": "<string>",
  "amount": 123,
  "discount_amount": 123,
  "net_amount": 123,
  "tax_amount": 123,
  "total_amount": 123,
  "currency": "<string>",
  "allow_trial": true,
  "active_trial_interval_count": 123,
  "trial_end": "2023-11-07T05:31:56Z",
  "organization_id": "<string>",
  "product_id": "<string>",
  "product_price_id": "<string>",
  "discount_id": "<string>",
  "allow_discount_codes": true,
  "require_billing_address": true,
  "is_discount_applicable": true,
  "is_free_product_price": true,
  "is_payment_required": true,
  "is_payment_setup_required": true,
  "is_payment_form_required": true,
  "customer_id": "<string>",
  "is_business_customer": true,
  "customer_name": "<string>",
  "customer_email": "<string>",
  "customer_ip_address": "<string>",
  "customer_billing_name": "<string>",
  "customer_billing_address": {
    "line1": "<string>",
    "line2": "<string>",
    "postal_code": "<string>",
    "city": "<string>",
    "state": "<string>"
  },
  "customer_tax_id": "<string>",
  "payment_processor_metadata": {},
  "billing_address_fields": {},
  "trial_interval_count": 123,
  "metadata": {},
  "external_customer_id": "<string>",
  "products": [
    {
      "id": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "modified_at": "2023-11-07T05:31:56Z",
      "trial_interval_count": 123,
      "name": "<string>",
      "description": "<string>",
      "recurring_interval_count": 123,
      "is_recurring": true,
      "is_archived": true,
      "organization_id": "<string>",
      "prices": [
        {
          "created_at": "2023-11-07T05:31:56Z",
          "modified_at": "2023-11-07T05:31:56Z",
          "id": "<string>",
          "amount_type": "<string>",
          "price_currency": "<string>",
          "is_archived": true,
          "product_id": "<string>",
          "type": "<string>",
          "price_amount": 123,
          "legacy": true
        }
      ],
      "benefits": [
        {
          "id": "<string>",
          "created_at": "2023-11-07T05:31:56Z",
          "modified_at": "2023-11-07T05:31:56Z",
          "description": "<string>",
          "selectable": true,
          "deletable": true,
          "is_deleted": true,
          "organization_id": "<string>"
        }
      ],
      "medias": [
        {
          "id": "<string>",
          "organization_id": "<string>",
          "name": "<string>",
          "path": "<string>",
          "mime_type": "<string>",
          "size": 123,
          "storage_version": "<string>",
          "checksum_etag": "<string>",
          "checksum_sha256_base64": "<string>",
          "checksum_sha256_hex": "<string>",
          "last_modified_at": "2023-11-07T05:31:56Z",
          "version": "<string>",
          "service": "<string>",
          "is_uploaded": true,
          "created_at": "2023-11-07T05:31:56Z",
          "size_readable": "<string>",
          "public_url": "<string>"
        }
      ]
    }
  ],
  "product": {
    "id": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "modified_at": "2023-11-07T05:31:56Z",
    "trial_interval_count": 123,
    "name": "<string>",
    "description": "<string>",
    "recurring_interval_count": 123,
    "is_recurring": true,
    "is_archived": true,
    "organization_id": "<string>",
    "prices": [
      {
        "created_at": "2023-11-07T05:31:56Z",
        "modified_at": "2023-11-07T05:31:56Z",
        "id": "<string>",
        "amount_type": "<string>",
        "price_currency": "<string>",
        "is_archived": true,
        "product_id": "<string>",
        "type": "<string>",
        "price_amount": 123,
        "legacy": true
      }
    ],
    "benefits": [
      {
        "id": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "modified_at": "2023-11-07T05:31:56Z",
        "description": "<string>",
        "selectable": true,
        "deletable": true,
        "is_deleted": true,
        "organization_id": "<string>"
      }
    ],
    "medias": [
      {
        "id": "<string>",
        "organization_id": "<string>",
        "name": "<string>",
        "path": "<string>",
        "mime_type": "<string>",
        "size": 123,
        "storage_version": "<string>",
        "checksum_etag": "<string>",
        "checksum_sha256_base64": "<string>",
        "checksum_sha256_hex": "<string>",
        "last_modified_at": "2023-11-07T05:31:56Z",
        "version": "<string>",
        "service": "<string>",
        "is_uploaded": true,
        "created_at": "2023-11-07T05:31:56Z",
        "size_readable": "<string>",
        "public_url": "<string>"
      }
    ]
  },
  "product_price": {
    "created_at": "2023-11-07T05:31:56Z",
    "modified_at": "2023-11-07T05:31:56Z",
    "id": "<string>",
    "amount_type": "<string>",
    "price_currency": "<string>",
    "is_archived": true,
    "product_id": "<string>",
    "type": "<string>",
    "price_amount": 123,
    "legacy": true
  },
  "prices": {},
  "discount": {
    "amount": 123,
    "currency": "<string>",
    "amounts": {},
    "id": "<string>",
    "name": "<string>",
    "code": "<string>"
  },
  "subscription_id": "<string>",
  "attached_custom_fields": [
    {
      "custom_field_id": "<string>",
      "custom_field": {
        "created_at": "2023-11-07T05:31:56Z",
        "modified_at": "2023-11-07T05:31:56Z",
        "id": "<string>",
        "metadata": {},
        "type": "<string>",
        "slug": "<string>",
        "name": "<string>",
        "organization_id": "<string>",
        "properties": {
          "form_label": "<string>",
          "form_help_text": "<string>",
          "form_placeholder": "<string>",
          "textarea": true,
          "min_length": 1073741823,
          "max_length": 1073741823
        }
      },
      "order": 123,
      "required": true
    }
  ],
  "customer_metadata": {},
  "custom_field_data": {},
  "seats": 123,
  "min_seats": 123,
  "max_seats": 123,
  "locale": "<string>"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Authorizations

Authorization

string

header

required

Authentication: You can generate a Personal Access Token from your settings.

Body

application/json

Create a new checkout session from a list of products. Customers will be able to switch between those products.

Metadata set on the checkout will be copied to the resulting order and/or subscription.

products

string<uuid4>[]

required

Collection of product IDs available to select at that checkout. The first one will be selected by default.

Minimum array length: 1

trial_interval

enum<string> | null

Unit used to measure the trial period.

Available options:

day,

week,

month,

year

trial_interval_count

integer | null

Length of the trial measured in the selected interval.

Required range: 1 <= x <= 1000

metadata

Metadata · object

Metadata map for information your integration needs to retain.

The key must be a string with a maximum length of 40 characters. The value must be either:

A string with a maximum length of 500 characters
An integer
A floating-point number
A boolean

You can store up to 50 key-value pairs.

Show child attributes

custom_field_data

Custom Field Data · object

Map containing values collected through custom fields.

Show child attributes

discount_id

string<uuid4> | null

Identifier of the discount to apply to the checkout.

allow_discount_codes

boolean

default:true

Indicates whether to allow the customer to apply discount codes. If you apply a discount through discount_id, it'll still be applied, but the customer won't be able to change it.

require_billing_address

boolean

default:false

Indicates whether to require the customer to fill their full billing address, instead of just the country. Customers in the US will always be required to fill their full address, regardless of this setting. If you preset the billing address, this setting will be automatically set to true.

amount

integer | null

Amount: Amount in cents, before discounts and taxes. Only useful for custom prices, it'll be ignored for fixed and free prices.

Required range: x >= 0

seats

integer | null

Seats: Predefined number of seats (works with seat-based pricing only).

Required range: 1 <= x <= 10000

min_seats

integer | null

Min Seats: Minimum number of seats (works with seat-based pricing only).

Required range: 1 <= x <= 10000

max_seats

integer | null

Max Seats: Maximum number of seats (works with seat-based pricing only).

Required range: 1 <= x <= 10000

allow_trial

boolean

default:true

Indicates whether to enable the trial period for the checkout session. If false, the trial period will be disabled, even if the selected product has a trial configured.

customer_id

string<uuid4> | null

Identifier of an existing customer in the organization. The customer data will be pre-filled in the checkout form. The resulting order will be linked to this customer.

is_business_customer

boolean

default:false

Indicates whether the customer is a business or an individual. If true, the customer will be required to fill their full billing address and billing name.

external_customer_id

string | null

Identifier of the customer in your system. If a matching customer exists on Ruba, the resulting order will be linked to this customer. Otherwise, a new customer will be created with this external ID set.

customer_name

string | null

Name assigned to the customer.

Maximum string length: 256

Example:

"John Doe"

customer_email

string<email> | null

Email used to identify and contact the customer.

customer_ip_address

string<ipvanyaddress> | null

customer_billing_name

string | null

customer_billing_address

AddressInput · object | null

Customer address used for billing and tax calculations.

Show child attributes

customer_tax_id

string | null

customer_metadata

Customer Metadata · object

Metadata map for information your integration needs to retain that'll be copied to the created customer.

The key must be a string with a maximum length of 40 characters. The value must be either:

A string with a maximum length of 500 characters
An integer
A floating-point number
A boolean

You can store up to 50 key-value pairs.

Show child attributes

subscription_id

string<uuid4> | null

Identifier of a subscription to upgrade. It must be on a free pricing. If checkout is successful, metadata set on this checkout will be copied to the subscription, and existing keys will be overwritten.

success_url

string<uri> | null

Success Url: URL where the customer will be redirected after a successful payment.You can add the checkout_id={CHECKOUT_ID} query parameter to retrieve the checkout session id.

Required string length: 1 - 2083

return_url

string<uri> | null

If provided, a back button will be shown in the checkout to return to this URL.

Required string length: 1 - 2083

embed_origin

string | null

Embed Origin: If you plan to embed the checkout session, set this to the Origin of the embedding page. It'll allow the Ruba iframe to communicate with the parent page.

locale

string | null

Locale: Locale of the customer, given as an IETF BCP 47 language tag. Supported: language code (e.g. en) or language + region (e.g. en-US). If null or unsupported, the locale will default to en.

Pattern: ^[a-zA-Z]{2,3}(-[a-zA-Z]{2}|-[0-9]{3})?$

Example:

"en"

currency

enum<string> | null

Available options:

aed,

all,

amd,

aoa,

ars,

aud,

awg,

azn,

bam,

bbd,

bdt,

bif,

bmd,

bnd,

bob,

brl,

bsd,

bwp,

bzd,

cad,

cdf,

chf,

clp,

cny,

cop,

crc,

cve,

czk,

djf,

dkk,

dop,

dzd,

egp,

etb,

eur,

fjd,

fkp,

gbp,

gel,

gip,

gmd,

gnf,

gtq,

gyd,

hkd,

hnl,

htg,

huf,

idr,

ils,

inr,

isk,

jmd,

jpy,

kes,

kgs,

khr,

kmf,

krw,

kyd,

kzt,

lak,

lkr,

lrd,

lsl,

mad,

mdl,

mga,

mkd,

mnt,

mop,

mur,

mvr,

mwk,

mxn,

myr,

mzn,

nad,

ngn,

nio,

nok,

npr,

nzd,

pab,

pen,

pgk,

php,

pkr,

pln,

pyg,

qar,

ron,

rsd,

rwf,

sar,

sbd,

scr,

sek,

sgd,

shp,

sos,

srd,

szl,

thb,

tjs,

top,

try,

ttd,

twd,

tzs,

uah,

ugx,

usd,

uyu,

uzs,

vnd,

vuv,

wst,

xaf,

xcd,

xcg,

xof,

xpf,

yer,

zar,

zmw

Required string length: 3

prices

Prices · object | null

Prices: Optional mapping of product IDs to a list of ad-hoc prices to create for that product. If not set, catalog prices of the product will be used.

Show child attributes

Response

Response: Checkout session created.

Checkout session data retrieved using an access token.

string<uuid4>

required

The stable identifier for this record.

created_at

string<date-time>

required

The time Ruba created this record.

modified_at

string<date-time> | null

required

The time this record last changed.

payment_processor

enum<string>

required

Payment Processor: Payment processor used.

Available options:

stripe

status

enum<string>

required

Status of the checkout session.

- Open: the checkout session was opened.
    - Expired: the checkout session was expired and is no more accessible.
    - Confirmed: the user on the checkout session clicked Pay. This is not indicative of the payment's success status.
    - Failed: the checkout definitely failed for technical reasons and cannot be retried. In most cases, this state is never reached.
    - Succeeded: the payment on the checkout was performed successfully.

Available options:

open,

expired,

confirmed,

succeeded,

failed

client_secret

string

required

Client Secret: Client secret used to update and complete the checkout session from the client.

url

string

required

Url: URL where the customer can access the checkout session.

expires_at

string<date-time>

required

Expires At: Expiration date and time of the checkout session.

success_url

string

required

Success Url: URL where the customer will be redirected after a successful payment.

return_url

string | null

required

If provided, a back button will be shown in the checkout to return to this URL.

embed_origin

string | null

required

Embed Origin: When checkout is embedded, represents the Origin of the page embedding the checkout. Used as a security measure to send messages only to the embedding page.

amount

integer

required

Amount: Amount in cents, before discounts and taxes.

discount_amount

integer

required

Discount Amount: Discount amount in cents.

net_amount

integer

required

Net Amount: Amount in cents, after discounts but before taxes.

tax_amount

integer | null

required

Tax Amount: Sales tax amount in cents. If null, it means there is no enough information yet to calculate it.

tax_behavior

enum<string> | null

required

Tax Behavior: Tax behavior of the checkout. inclusive means the price includes tax, exclusive means tax is added on top. If null, tax is not yet calculated.

Available options:

inclusive,

exclusive

total_amount

integer

required

Total Amount: Amount in cents, after discounts and taxes.

currency

string

required

Currency: Currency code of the checkout session.

allow_trial

boolean | null

required

Indicates whether to enable the trial period for the checkout session. If false, the trial period will be disabled, even if the selected product has a trial configured.

active_trial_interval

enum<string> | null

required

Active Trial Interval: Interval unit of the trial period, if any. This value is either set from the checkout, if trial_interval is set, or from the selected product.

Available options:

day,

week,

month,

year

active_trial_interval_count

integer | null

required

Count of interval units of the trial period, if any. This value is either set from the checkout, if trial_interval_count is set, or from the selected product.

trial_end

string<date-time> | null

required

Trial End: End date and time of the trial period, if any.

organization_id

string<uuid4>

required

Identifier of the organization owning the checkout session.

product_id

string<uuid4> | null

required

Identifier of the product to checkout.

product_price_id

string<uuid4> | null

required

deprecated

Identifier of the product price to checkout.

discount_id

string<uuid4> | null

required

Identifier of the discount applied to the checkout.

allow_discount_codes

boolean

required

Indicates whether to allow the customer to apply discount codes. If you apply a discount through discount_id, it'll still be applied, but the customer won't be able to change it.

require_billing_address

boolean

required

is_discount_applicable

boolean

required

Indicates whether the discount is applicable to the checkout. Typically, free and custom prices are not discountable.

is_free_product_price

boolean

required

Indicates whether the product price is free, regardless of discounts.

is_payment_required

boolean

required

Indicates whether the checkout requires payment, e.g. in case of free products or discounts that cover the total amount.

is_payment_setup_required

boolean

required

Indicates whether the checkout requires setting up a payment method, regardless of the amount, e.g. subscriptions that have first free cycles.

is_payment_form_required

boolean

required

Indicates whether the checkout requires a payment form, whether because of a payment or payment method setup.

customer_id

string<uuid4> | null

required

is_business_customer

boolean

required

Indicates whether the customer is a business or an individual. If true, the customer will be required to fill their full billing address and billing name.

customer_name

string | null

required

Customer Name: Name of the customer.

customer_email

string | null

required

Email used to identify and contact the customer.

customer_ip_address

string<ipvanyaddress> | null

required

customer_billing_name

string | null

required

customer_billing_address

Address · object | null

required

Customer address used for billing and tax calculations.

Show child attributes

customer_tax_id

string | null

required

payment_processor_metadata

Payment Processor Metadata · object

required

Show child attributes

billing_address_fields

CheckoutBillingAddressFields · object

required

Billing Address Fields: Determines which billing address fields should be disabled, optional or required in the checkout form.

Show child attributes

trial_interval

enum<string> | null

required

Unit used to measure the trial period.

Available options:

day,

week,

month,

year

trial_interval_count

integer | null

required

Length of the trial measured in the selected interval.

metadata

object

required

Show child attributes

external_customer_id

string | null

required

products

CheckoutProduct · object[]

required

Collection of products available to select.

Show child attributes

product

CheckoutProduct · object | null

required

Product: Product selected to checkout.

Show child attributes

product_price

LegacyRecurringProductPriceFixed · object

required

deprecated

A recurring price for a product, i.e. a subscription.

Deprecated: The recurring interval should be set on the product itself.

Show child attributes

prices

Prices · object | null

required

Prices: Mapping of product IDs to their list of prices.

Show child attributes

discount

CheckoutDiscountFixedOnceForeverDuration · object

required

Schema for a fixed amount discount that is applied once or forever.

CheckoutDiscountFixedOnceForeverDuration
CheckoutDiscountFixedRepeatDuration
CheckoutDiscountPercentageOnceForeverDuration
CheckoutDiscountPercentageRepeatDuration

Show child attributes

subscription_id

string<uuid4> | null

required

attached_custom_fields

AttachedCustomField · object[] | null

required

Show child attributes

customer_metadata

Customer Metadata · object

required

Show child attributes

custom_field_data

Custom Field Data · object

Map containing values collected through custom fields.

Show child attributes

seats

integer | null

Seats: Predefined number of seats (works with seat-based pricing only).

min_seats

integer | null

Min Seats: Minimum number of seats (works with seat-based pricing only).

max_seats

integer | null

Max Seats: Maximum number of seats (works with seat-based pricing only).

locale

string | null

Change Checkout Session### Intent Applies the supplied changes to the checkout session. ### When to call it Call this when the checkout session already exists and its stored values need to change. ### Access boundary Authorize the request with a token that carries `checkouts:write`. ### Successful result A successful request returns `200`. The response schema below defines the body your integration receives.

⌘I

Create Checkout Session

curl --request POST \
  --url https://api.getruba.com/v1/checkouts/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "products": [
    "<string>"
  ],
  "trial_interval_count": 500,
  "metadata": {},
  "custom_field_data": {},
  "discount_id": "<string>",
  "allow_discount_codes": true,
  "require_billing_address": false,
  "amount": 1,
  "seats": 5000,
  "min_seats": 5000,
  "max_seats": 5000,
  "allow_trial": true,
  "customer_id": "<string>",
  "is_business_customer": false,
  "external_customer_id": "<string>",
  "customer_name": "John Doe",
  "customer_email": "jsmith@example.com",
  "customer_ip_address": "<string>",
  "customer_billing_name": "<string>",
  "customer_billing_address": {
    "line1": "<string>",
    "line2": "<string>",
    "postal_code": "<string>",
    "city": "<string>",
    "state": "<string>"
  },
  "customer_tax_id": "<string>",
  "customer_metadata": {},
  "subscription_id": "<string>",
  "success_url": "<string>",
  "return_url": "<string>",
  "embed_origin": "<string>",
  "locale": "en",
  "prices": {}
}
'

import requests

url = "https://api.getruba.com/v1/checkouts/"

payload = {
    "products": ["<string>"],
    "trial_interval_count": 500,
    "metadata": {},
    "custom_field_data": {},
    "discount_id": "<string>",
    "allow_discount_codes": True,
    "require_billing_address": False,
    "amount": 1,
    "seats": 5000,
    "min_seats": 5000,
    "max_seats": 5000,
    "allow_trial": True,
    "customer_id": "<string>",
    "is_business_customer": False,
    "external_customer_id": "<string>",
    "customer_name": "John Doe",
    "customer_email": "jsmith@example.com",
    "customer_ip_address": "<string>",
    "customer_billing_name": "<string>",
    "customer_billing_address": {
        "line1": "<string>",
        "line2": "<string>",
        "postal_code": "<string>",
        "city": "<string>",
        "state": "<string>"
    },
    "customer_tax_id": "<string>",
    "customer_metadata": {},
    "subscription_id": "<string>",
    "success_url": "<string>",
    "return_url": "<string>",
    "embed_origin": "<string>",
    "locale": "en",
    "prices": {}
}
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({
    products: ['<string>'],
    trial_interval_count: 500,
    metadata: {},
    custom_field_data: {},
    discount_id: '<string>',
    allow_discount_codes: true,
    require_billing_address: false,
    amount: 1,
    seats: 5000,
    min_seats: 5000,
    max_seats: 5000,
    allow_trial: true,
    customer_id: '<string>',
    is_business_customer: false,
    external_customer_id: '<string>',
    customer_name: 'John Doe',
    customer_email: 'jsmith@example.com',
    customer_ip_address: '<string>',
    customer_billing_name: '<string>',
    customer_billing_address: {
      line1: '<string>',
      line2: '<string>',
      postal_code: '<string>',
      city: '<string>',
      state: '<string>'
    },
    customer_tax_id: '<string>',
    customer_metadata: {},
    subscription_id: '<string>',
    success_url: '<string>',
    return_url: '<string>',
    embed_origin: '<string>',
    locale: 'en',
    prices: {}
  })
};

fetch('https://api.getruba.com/v1/checkouts/', 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.getruba.com/v1/checkouts/",
  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([
    'products' => [
        '<string>'
    ],
    'trial_interval_count' => 500,
    'metadata' => [
        
    ],
    'custom_field_data' => [
        
    ],
    'discount_id' => '<string>',
    'allow_discount_codes' => true,
    'require_billing_address' => false,
    'amount' => 1,
    'seats' => 5000,
    'min_seats' => 5000,
    'max_seats' => 5000,
    'allow_trial' => true,
    'customer_id' => '<string>',
    'is_business_customer' => false,
    'external_customer_id' => '<string>',
    'customer_name' => 'John Doe',
    'customer_email' => 'jsmith@example.com',
    'customer_ip_address' => '<string>',
    'customer_billing_name' => '<string>',
    'customer_billing_address' => [
        'line1' => '<string>',
        'line2' => '<string>',
        'postal_code' => '<string>',
        'city' => '<string>',
        'state' => '<string>'
    ],
    'customer_tax_id' => '<string>',
    'customer_metadata' => [
        
    ],
    'subscription_id' => '<string>',
    'success_url' => '<string>',
    'return_url' => '<string>',
    'embed_origin' => '<string>',
    'locale' => 'en',
    'prices' => [
        
    ]
  ]),
  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.getruba.com/v1/checkouts/"

	payload := strings.NewReader("{\n  \"products\": [\n    \"<string>\"\n  ],\n  \"trial_interval_count\": 500,\n  \"metadata\": {},\n  \"custom_field_data\": {},\n  \"discount_id\": \"<string>\",\n  \"allow_discount_codes\": true,\n  \"require_billing_address\": false,\n  \"amount\": 1,\n  \"seats\": 5000,\n  \"min_seats\": 5000,\n  \"max_seats\": 5000,\n  \"allow_trial\": true,\n  \"customer_id\": \"<string>\",\n  \"is_business_customer\": false,\n  \"external_customer_id\": \"<string>\",\n  \"customer_name\": \"John Doe\",\n  \"customer_email\": \"jsmith@example.com\",\n  \"customer_ip_address\": \"<string>\",\n  \"customer_billing_name\": \"<string>\",\n  \"customer_billing_address\": {\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\"\n  },\n  \"customer_tax_id\": \"<string>\",\n  \"customer_metadata\": {},\n  \"subscription_id\": \"<string>\",\n  \"success_url\": \"<string>\",\n  \"return_url\": \"<string>\",\n  \"embed_origin\": \"<string>\",\n  \"locale\": \"en\",\n  \"prices\": {}\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.getruba.com/v1/checkouts/")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"products\": [\n    \"<string>\"\n  ],\n  \"trial_interval_count\": 500,\n  \"metadata\": {},\n  \"custom_field_data\": {},\n  \"discount_id\": \"<string>\",\n  \"allow_discount_codes\": true,\n  \"require_billing_address\": false,\n  \"amount\": 1,\n  \"seats\": 5000,\n  \"min_seats\": 5000,\n  \"max_seats\": 5000,\n  \"allow_trial\": true,\n  \"customer_id\": \"<string>\",\n  \"is_business_customer\": false,\n  \"external_customer_id\": \"<string>\",\n  \"customer_name\": \"John Doe\",\n  \"customer_email\": \"jsmith@example.com\",\n  \"customer_ip_address\": \"<string>\",\n  \"customer_billing_name\": \"<string>\",\n  \"customer_billing_address\": {\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\"\n  },\n  \"customer_tax_id\": \"<string>\",\n  \"customer_metadata\": {},\n  \"subscription_id\": \"<string>\",\n  \"success_url\": \"<string>\",\n  \"return_url\": \"<string>\",\n  \"embed_origin\": \"<string>\",\n  \"locale\": \"en\",\n  \"prices\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.getruba.com/v1/checkouts/")

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  \"products\": [\n    \"<string>\"\n  ],\n  \"trial_interval_count\": 500,\n  \"metadata\": {},\n  \"custom_field_data\": {},\n  \"discount_id\": \"<string>\",\n  \"allow_discount_codes\": true,\n  \"require_billing_address\": false,\n  \"amount\": 1,\n  \"seats\": 5000,\n  \"min_seats\": 5000,\n  \"max_seats\": 5000,\n  \"allow_trial\": true,\n  \"customer_id\": \"<string>\",\n  \"is_business_customer\": false,\n  \"external_customer_id\": \"<string>\",\n  \"customer_name\": \"John Doe\",\n  \"customer_email\": \"jsmith@example.com\",\n  \"customer_ip_address\": \"<string>\",\n  \"customer_billing_name\": \"<string>\",\n  \"customer_billing_address\": {\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\"\n  },\n  \"customer_tax_id\": \"<string>\",\n  \"customer_metadata\": {},\n  \"subscription_id\": \"<string>\",\n  \"success_url\": \"<string>\",\n  \"return_url\": \"<string>\",\n  \"embed_origin\": \"<string>\",\n  \"locale\": \"en\",\n  \"prices\": {}\n}"

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

{
  "id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "modified_at": "2023-11-07T05:31:56Z",
  "payment_processor": "stripe",
  "client_secret": "<string>",
  "url": "<string>",
  "expires_at": "2023-11-07T05:31:56Z",
  "success_url": "<string>",
  "return_url": "<string>",
  "embed_origin": "<string>",
  "amount": 123,
  "discount_amount": 123,
  "net_amount": 123,
  "tax_amount": 123,
  "total_amount": 123,
  "currency": "<string>",
  "allow_trial": true,
  "active_trial_interval_count": 123,
  "trial_end": "2023-11-07T05:31:56Z",
  "organization_id": "<string>",
  "product_id": "<string>",
  "product_price_id": "<string>",
  "discount_id": "<string>",
  "allow_discount_codes": true,
  "require_billing_address": true,
  "is_discount_applicable": true,
  "is_free_product_price": true,
  "is_payment_required": true,
  "is_payment_setup_required": true,
  "is_payment_form_required": true,
  "customer_id": "<string>",
  "is_business_customer": true,
  "customer_name": "<string>",
  "customer_email": "<string>",
  "customer_ip_address": "<string>",
  "customer_billing_name": "<string>",
  "customer_billing_address": {
    "line1": "<string>",
    "line2": "<string>",
    "postal_code": "<string>",
    "city": "<string>",
    "state": "<string>"
  },
  "customer_tax_id": "<string>",
  "payment_processor_metadata": {},
  "billing_address_fields": {},
  "trial_interval_count": 123,
  "metadata": {},
  "external_customer_id": "<string>",
  "products": [
    {
      "id": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "modified_at": "2023-11-07T05:31:56Z",
      "trial_interval_count": 123,
      "name": "<string>",
      "description": "<string>",
      "recurring_interval_count": 123,
      "is_recurring": true,
      "is_archived": true,
      "organization_id": "<string>",
      "prices": [
        {
          "created_at": "2023-11-07T05:31:56Z",
          "modified_at": "2023-11-07T05:31:56Z",
          "id": "<string>",
          "amount_type": "<string>",
          "price_currency": "<string>",
          "is_archived": true,
          "product_id": "<string>",
          "type": "<string>",
          "price_amount": 123,
          "legacy": true
        }
      ],
      "benefits": [
        {
          "id": "<string>",
          "created_at": "2023-11-07T05:31:56Z",
          "modified_at": "2023-11-07T05:31:56Z",
          "description": "<string>",
          "selectable": true,
          "deletable": true,
          "is_deleted": true,
          "organization_id": "<string>"
        }
      ],
      "medias": [
        {
          "id": "<string>",
          "organization_id": "<string>",
          "name": "<string>",
          "path": "<string>",
          "mime_type": "<string>",
          "size": 123,
          "storage_version": "<string>",
          "checksum_etag": "<string>",
          "checksum_sha256_base64": "<string>",
          "checksum_sha256_hex": "<string>",
          "last_modified_at": "2023-11-07T05:31:56Z",
          "version": "<string>",
          "service": "<string>",
          "is_uploaded": true,
          "created_at": "2023-11-07T05:31:56Z",
          "size_readable": "<string>",
          "public_url": "<string>"
        }
      ]
    }
  ],
  "product": {
    "id": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "modified_at": "2023-11-07T05:31:56Z",
    "trial_interval_count": 123,
    "name": "<string>",
    "description": "<string>",
    "recurring_interval_count": 123,
    "is_recurring": true,
    "is_archived": true,
    "organization_id": "<string>",
    "prices": [
      {
        "created_at": "2023-11-07T05:31:56Z",
        "modified_at": "2023-11-07T05:31:56Z",
        "id": "<string>",
        "amount_type": "<string>",
        "price_currency": "<string>",
        "is_archived": true,
        "product_id": "<string>",
        "type": "<string>",
        "price_amount": 123,
        "legacy": true
      }
    ],
    "benefits": [
      {
        "id": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "modified_at": "2023-11-07T05:31:56Z",
        "description": "<string>",
        "selectable": true,
        "deletable": true,
        "is_deleted": true,
        "organization_id": "<string>"
      }
    ],
    "medias": [
      {
        "id": "<string>",
        "organization_id": "<string>",
        "name": "<string>",
        "path": "<string>",
        "mime_type": "<string>",
        "size": 123,
        "storage_version": "<string>",
        "checksum_etag": "<string>",
        "checksum_sha256_base64": "<string>",
        "checksum_sha256_hex": "<string>",
        "last_modified_at": "2023-11-07T05:31:56Z",
        "version": "<string>",
        "service": "<string>",
        "is_uploaded": true,
        "created_at": "2023-11-07T05:31:56Z",
        "size_readable": "<string>",
        "public_url": "<string>"
      }
    ]
  },
  "product_price": {
    "created_at": "2023-11-07T05:31:56Z",
    "modified_at": "2023-11-07T05:31:56Z",
    "id": "<string>",
    "amount_type": "<string>",
    "price_currency": "<string>",
    "is_archived": true,
    "product_id": "<string>",
    "type": "<string>",
    "price_amount": 123,
    "legacy": true
  },
  "prices": {},
  "discount": {
    "amount": 123,
    "currency": "<string>",
    "amounts": {},
    "id": "<string>",
    "name": "<string>",
    "code": "<string>"
  },
  "subscription_id": "<string>",
  "attached_custom_fields": [
    {
      "custom_field_id": "<string>",
      "custom_field": {
        "created_at": "2023-11-07T05:31:56Z",
        "modified_at": "2023-11-07T05:31:56Z",
        "id": "<string>",
        "metadata": {},
        "type": "<string>",
        "slug": "<string>",
        "name": "<string>",
        "organization_id": "<string>",
        "properties": {
          "form_label": "<string>",
          "form_help_text": "<string>",
          "form_placeholder": "<string>",
          "textarea": true,
          "min_length": 1073741823,
          "max_length": 1073741823
        }
      },
      "order": 123,
      "required": true
    }
  ],
  "customer_metadata": {},
  "custom_field_data": {},
  "seats": 123,
  "min_seats": 123,
  "max_seats": 123,
  "locale": "<string>"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Read This First

Create a Sale

Collect and Reconcile

Manage Recurring Revenue

Model Customer Access

Power the Customer Portal

Configure the Platform

React to State Changes

Create Checkout Session

Intent

When to call it

Access boundary

Successful result

Authorizations

Body

Response