> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getruba.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Checkout Link
> ### Intent
Creates a checkout link from the values supplied in the request.
### When to call it
Call this when your application has collected the required values and is ready to create a checkout link.
### Access boundary
Authorize the request with a token that carries `checkout_links:write`.
### Successful result
A successful request returns `201`. The response schema below defines the body your integration receives.
export const RubaSocials = () => {
if (typeof document === "undefined") {
return null;
}
const inject = () => {
const footer = document.getElementById("footer");
if (!footer || document.getElementById("ruba-socials")) {
return false;
}
const isDark = document.querySelector("html.dark") || document.querySelector('html[class*="dark"]');
const lineColor = isDark ? "#383838" : "#e8e8ed";
const iconColor = isDark ? "#8e8e93" : "#86868b";
const markColor = isDark ? "#ffffff" : "#08080c";
const hoverColor = "#0071e3";
const div = document.createElement("div");
div.id = "ruba-socials";
div.style.cssText = `display:flex;align-items:center;gap:20px;padding-top:20px;margin-top:20px;border-top:1px solid ${lineColor};width:100%`;
const logo = `Ruba`;
const spacer = ``;
const ig = ``;
const li = ``;
const x = ``;
const github = ``;
div.innerHTML = logo + spacer + ig + li + x + github;
footer.appendChild(div);
return true;
};
if (!document.documentElement.dataset.rubaSocialsObserver) {
document.documentElement.dataset.rubaSocialsObserver = "true";
const observer = new MutationObserver(() => {
if (!document.getElementById("ruba-socials")) {
inject();
}
});
observer.observe(document.body, {
childList: true,
subtree: true
});
}
setTimeout(() => {
if (!inject()) {
const interval = setInterval(() => {
if (inject()) {
clearInterval(interval);
}
}, 500);
setTimeout(() => clearInterval(interval), 10000);
}
}, 300);
return null;
};
Trying to spin up a one-time checkout session? Checkout Links are likely **not** the right fit.
Checkout Links are reusable URLs that produce a checkout session the moment they are opened. They work well when you want to kick off a purchase from a website or social post.
When you need to launch a checkout for a user **inside** your own product, reach for the [Checkout Sessions API](/api-reference/checkouts/create-session) instead.
## OpenAPI
````yaml post /v1/checkout-links/
openapi: 3.1.0
info:
title: Ruba API
summary: Ruba HTTP and Webhooks API
description: '**Details:** Read the docs at https://docs.getruba.com/api-reference.'
version: 2026-04
servers:
- url: https://api.getruba.com
description: '**Details:** Production environment.'
x-speakeasy-server-id: production
- url: https://sandbox-api.getruba.com
description: '**Details:** Sandbox environment.'
x-speakeasy-server-id: sandbox
security: []
tags:
- name: public
description: >-
**Details:** Endpoints shown and documented in the Ruba API documentation
and available in our SDKs.
- name: private
description: >-
**Details:** Endpoints that should appear in the schema only in
development to generate our internal JS SDK.
paths:
/v1/checkout-links/:
post:
tags:
- checkout-links
- public
summary: Create Checkout Link
description: >-
### Intent
Creates a checkout link from the values supplied in the request.
### When to call it
Call this when your application has collected the required values and is
ready to create a checkout link.
### Access boundary
Authorize the request with a token that carries `checkout_links:write`.
### Successful result
A successful request returns `201`. The response schema below defines
the body your integration receives.
operationId: checkout-links:create
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CheckoutLinkCreate'
responses:
'201':
description: '**Response:** Checkout link created.'
content:
application/json:
schema:
$ref: '#/components/schemas/CheckoutLink'
'422':
description: Request validation failed
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- oidc:
- checkout_links:write
- pat:
- checkout_links:write
- oat:
- checkout_links:write
components:
schemas:
CheckoutLinkCreate:
anyOf:
- $ref: '#/components/schemas/CheckoutLinkCreateProductPrice'
- $ref: '#/components/schemas/CheckoutLinkCreateProduct'
- $ref: '#/components/schemas/CheckoutLinkCreateProducts'
CheckoutLink:
properties:
id:
type: string
format: uuid4
title: Id
description: The stable identifier for this record.
created_at:
type: string
format: date-time
title: Created At
description: The time Ruba created this record.
modified_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Modified At
description: The time this record last changed.
trial_interval:
anyOf:
- $ref: '#/components/schemas/TrialInterval'
- type: 'null'
description: Unit used to measure the trial period.
trial_interval_count:
anyOf:
- type: integer
- type: 'null'
title: Trial Interval Count
description: Length of the trial measured in the selected interval.
metadata:
$ref: '#/components/schemas/MetadataOutputType'
payment_processor:
$ref: '#/components/schemas/PaymentProcessor'
description: '**Payment Processor:** Payment processor used.'
client_secret:
type: string
title: Client Secret
description: '**Client Secret:** Client secret used to access the checkout link.'
success_url:
anyOf:
- type: string
- type: 'null'
title: Success Url
description: >-
**Success Url:** URL where the customer will be redirected after a
successful payment.
return_url:
anyOf:
- type: string
- type: 'null'
title: Return Url
description: >-
If provided, a back button will be shown in the checkout to return
to this URL.
label:
anyOf:
- type: string
- type: 'null'
title: Label
description: '**Label:** Optional label to distinguish links internally.'
allow_discount_codes:
type: boolean
title: Allow Discount Codes
description: >-
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:
type: boolean
title: Require Billing Address
description: >-
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.
discount_id:
anyOf:
- type: string
format: uuid4
- type: 'null'
title: Discount Id
description: >-
Identifier of the discount to apply to the checkout. If the discount
is not applicable anymore when opening the checkout link, it'll be
ignored.
seats:
anyOf:
- type: integer
- type: 'null'
title: Seats
description: >-
**Seats:** Seat quantity locked into this checkout link. Every
linked product must support seat pricing and accept the specified
quantity. Ruba ignores the value if a product's configuration no
longer supports it when checkout begins.
organization_id:
type: string
format: uuid4
title: Organization Id
description: Identifier of the organization.
examples:
- 1dbfc517-0bbf-4301-9ba8-555ca42b9737
x-ruba-selector-widget:
displayProperty: name
resourceName: Organization
resourceRoot: /v1/organizations
products:
items:
$ref: '#/components/schemas/CheckoutLinkProduct'
type: array
title: Products
discount:
anyOf:
- oneOf:
- $ref: '#/components/schemas/DiscountFixedOnceForeverDurationBase'
- $ref: '#/components/schemas/DiscountFixedRepeatDurationBase'
- $ref: >-
#/components/schemas/DiscountPercentageOnceForeverDurationBase
- $ref: '#/components/schemas/DiscountPercentageRepeatDurationBase'
title: CheckoutLinkDiscount
- type: 'null'
title: Discount
url:
type: string
title: Url
readOnly: true
type: object
required:
- id
- created_at
- modified_at
- trial_interval
- trial_interval_count
- metadata
- payment_processor
- client_secret
- success_url
- return_url
- label
- allow_discount_codes
- require_billing_address
- discount_id
- seats
- organization_id
- products
- discount
- url
title: CheckoutLink
description: Checkout link data.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
CheckoutLinkCreateProductPrice:
properties:
metadata:
additionalProperties:
anyOf:
- type: string
maxLength: 500
minLength: 1
- type: integer
- type: number
- type: boolean
propertyNames:
maxLength: 40
minLength: 1
type: object
maxProperties: 50
title: Metadata
description: |-
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**.
trial_interval:
anyOf:
- $ref: '#/components/schemas/TrialInterval'
- type: 'null'
description: Unit used to measure the trial period.
trial_interval_count:
anyOf:
- type: integer
maximum: 1000
minimum: 1
- type: 'null'
title: Trial Interval Count
description: Length of the trial measured in the selected interval.
payment_processor:
type: string
const: stripe
title: Payment Processor
description: >-
**Payment Processor:** Payment processor to use. Currently only
Stripe is supported.
label:
anyOf:
- type: string
- type: 'null'
title: Label
description: '**Label:** Optional label to distinguish links internally.'
allow_discount_codes:
type: boolean
title: Allow Discount Codes
description: >-
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.
default: true
require_billing_address:
type: boolean
title: Require Billing Address
description: >-
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.
default: false
discount_id:
anyOf:
- type: string
format: uuid4
- type: 'null'
title: Discount Id
description: >-
Identifier of the discount to apply to the checkout. If the discount
is not applicable anymore when opening the checkout link, it'll be
ignored.
seats:
anyOf:
- type: integer
maximum: 10000
minimum: 1
- type: 'null'
title: Seats
description: >-
**Seats:** Seat quantity locked into this checkout link. Every
linked product must support seat pricing and accept the specified
quantity. Ruba ignores the value if a product's configuration no
longer supports it when checkout begins.
success_url:
anyOf:
- type: string
maxLength: 2083
minLength: 1
format: uri
- type: 'null'
title: Success Url
description: >-
**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.
return_url:
anyOf:
- type: string
maxLength: 2083
minLength: 1
format: uri
- type: 'null'
title: Return Url
description: >-
If provided, a back button will be shown in the checkout to return
to this URL.
product_price_id:
type: string
format: uuid4
title: Product Price Id
type: object
required:
- payment_processor
- product_price_id
title: CheckoutLinkCreateProductPrice
description: |-
Schema to create a new checkout link from a a single product price.
**Deprecated**: Use `CheckoutLinkCreateProducts` instead.
CheckoutLinkCreateProduct:
properties:
metadata:
additionalProperties:
anyOf:
- type: string
maxLength: 500
minLength: 1
- type: integer
- type: number
- type: boolean
propertyNames:
maxLength: 40
minLength: 1
type: object
maxProperties: 50
title: Metadata
description: |-
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**.
trial_interval:
anyOf:
- $ref: '#/components/schemas/TrialInterval'
- type: 'null'
description: Unit used to measure the trial period.
trial_interval_count:
anyOf:
- type: integer
maximum: 1000
minimum: 1
- type: 'null'
title: Trial Interval Count
description: Length of the trial measured in the selected interval.
payment_processor:
type: string
const: stripe
title: Payment Processor
description: >-
**Payment Processor:** Payment processor to use. Currently only
Stripe is supported.
label:
anyOf:
- type: string
- type: 'null'
title: Label
description: '**Label:** Optional label to distinguish links internally.'
allow_discount_codes:
type: boolean
title: Allow Discount Codes
description: >-
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.
default: true
require_billing_address:
type: boolean
title: Require Billing Address
description: >-
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.
default: false
discount_id:
anyOf:
- type: string
format: uuid4
- type: 'null'
title: Discount Id
description: >-
Identifier of the discount to apply to the checkout. If the discount
is not applicable anymore when opening the checkout link, it'll be
ignored.
seats:
anyOf:
- type: integer
maximum: 10000
minimum: 1
- type: 'null'
title: Seats
description: >-
**Seats:** Seat quantity locked into this checkout link. Every
linked product must support seat pricing and accept the specified
quantity. Ruba ignores the value if a product's configuration no
longer supports it when checkout begins.
success_url:
anyOf:
- type: string
maxLength: 2083
minLength: 1
format: uri
- type: 'null'
title: Success Url
description: >-
**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.
return_url:
anyOf:
- type: string
maxLength: 2083
minLength: 1
format: uri
- type: 'null'
title: Return Url
description: >-
If provided, a back button will be shown in the checkout to return
to this URL.
product_id:
type: string
format: uuid4
title: Product Id
type: object
required:
- payment_processor
- product_id
title: CheckoutLinkCreateProduct
description: |-
Schema to create a new checkout link from a a single product.
**Deprecated**: Use `CheckoutLinkCreateProducts` instead.
CheckoutLinkCreateProducts:
properties:
metadata:
additionalProperties:
anyOf:
- type: string
maxLength: 500
minLength: 1
- type: integer
- type: number
- type: boolean
propertyNames:
maxLength: 40
minLength: 1
type: object
maxProperties: 50
title: Metadata
description: |-
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**.
trial_interval:
anyOf:
- $ref: '#/components/schemas/TrialInterval'
- type: 'null'
description: Unit used to measure the trial period.
trial_interval_count:
anyOf:
- type: integer
maximum: 1000
minimum: 1
- type: 'null'
title: Trial Interval Count
description: Length of the trial measured in the selected interval.
payment_processor:
type: string
const: stripe
title: Payment Processor
description: >-
**Payment Processor:** Payment processor to use. Currently only
Stripe is supported.
label:
anyOf:
- type: string
- type: 'null'
title: Label
description: '**Label:** Optional label to distinguish links internally.'
allow_discount_codes:
type: boolean
title: Allow Discount Codes
description: >-
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.
default: true
require_billing_address:
type: boolean
title: Require Billing Address
description: >-
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.
default: false
discount_id:
anyOf:
- type: string
format: uuid4
- type: 'null'
title: Discount Id
description: >-
Identifier of the discount to apply to the checkout. If the discount
is not applicable anymore when opening the checkout link, it'll be
ignored.
seats:
anyOf:
- type: integer
maximum: 10000
minimum: 1
- type: 'null'
title: Seats
description: >-
**Seats:** Seat quantity locked into this checkout link. Every
linked product must support seat pricing and accept the specified
quantity. Ruba ignores the value if a product's configuration no
longer supports it when checkout begins.
success_url:
anyOf:
- type: string
maxLength: 2083
minLength: 1
format: uri
- type: 'null'
title: Success Url
description: >-
**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.
return_url:
anyOf:
- type: string
maxLength: 2083
minLength: 1
format: uri
- type: 'null'
title: Return Url
description: >-
If provided, a back button will be shown in the checkout to return
to this URL.
products:
items:
type: string
format: uuid4
type: array
minItems: 1
title: Products
description: Collection of products that will be available to select at checkout.
type: object
required:
- payment_processor
- products
title: CheckoutLinkCreateProducts
description: Schema used to create a new checkout link.
TrialInterval:
type: string
enum:
- day
- week
- month
- year
title: TrialInterval
MetadataOutputType:
additionalProperties:
anyOf:
- type: string
- type: integer
- type: number
- type: boolean
type: object
PaymentProcessor:
type: string
enum:
- stripe
title: PaymentProcessor
CheckoutLinkProduct:
properties:
metadata:
$ref: '#/components/schemas/MetadataOutputType'
id:
type: string
format: uuid4
title: Id
description: The stable identifier for this record.
created_at:
type: string
format: date-time
title: Created At
description: The time Ruba created this record.
modified_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Modified At
description: The time this record last changed.
trial_interval:
anyOf:
- $ref: '#/components/schemas/TrialInterval'
- type: 'null'
description: Unit used to measure the trial period.
trial_interval_count:
anyOf:
- type: integer
- type: 'null'
title: Trial Interval Count
description: Length of the trial measured in the selected interval.
name:
type: string
title: Name
description: Customer-facing name assigned to the product.
description:
anyOf:
- type: string
- type: 'null'
title: Description
description: Customer-facing description attached to the product.
visibility:
$ref: '#/components/schemas/ProductVisibility'
description: Controls where customers can discover the product.
recurring_interval:
anyOf:
- $ref: '#/components/schemas/RecurringInterval'
- type: 'null'
description: >-
**Recurring Interval:** Recurring interval of the product. If
`None`, the product is a one-time purchase.
recurring_interval_count:
anyOf:
- type: integer
- type: 'null'
title: Recurring Interval Count
description: >-
Count of interval units of the subscription. If this is set to 1 the
charge will happen every interval (e.g. every month), if set to 2 it
will be every other month, and so on. None for one-time products.
is_recurring:
type: boolean
title: Is Recurring
description: Indicates whether the product is a subscription.
is_archived:
type: boolean
title: Is Archived
description: Indicates whether the product is archived and no longer available.
organization_id:
type: string
format: uuid4
title: Organization Id
description: Unique identifier for the organization owning the product.
prices:
items:
oneOf:
- $ref: '#/components/schemas/LegacyRecurringProductPrice'
- $ref: '#/components/schemas/ProductPrice'
type: array
title: Prices
description: Collection of prices for this product.
benefits:
items:
$ref: '#/components/schemas/BenefitPublic'
type: array
title: BenefitPublic
description: Collection of benefits granted by the product.
medias:
items:
$ref: '#/components/schemas/ProductMediaFileRead'
type: array
title: Medias
description: Collection of medias associated to the product.
type: object
required:
- metadata
- id
- created_at
- modified_at
- trial_interval
- trial_interval_count
- name
- description
- visibility
- recurring_interval
- recurring_interval_count
- is_recurring
- is_archived
- organization_id
- prices
- benefits
- medias
title: CheckoutLinkProduct
description: Product data for a checkout link.
DiscountFixedOnceForeverDurationBase:
properties:
duration:
$ref: '#/components/schemas/DiscountDuration'
type:
$ref: '#/components/schemas/DiscountType'
amount:
type: integer
title: Amount
deprecated: true
examples:
- 1000
currency:
type: string
title: Currency
deprecated: true
examples:
- usd
amounts:
additionalProperties:
type: integer
type: object
title: Amounts
description: >-
**Amounts:** Map of currency to fixed amount to discount from the
total.
examples:
- eur: 900
usd: 1000
created_at:
type: string
format: date-time
title: Created At
description: The time Ruba created this record.
modified_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Modified At
description: The time this record last changed.
id:
type: string
format: uuid4
title: Id
description: The stable identifier for this record.
metadata:
$ref: '#/components/schemas/MetadataOutputType'
name:
type: string
title: Name
description: >-
**Name:** Name of the discount. Will be displayed to the customer
when the discount is applied.
code:
anyOf:
- type: string
- type: 'null'
title: Code
description: >-
**Code:** Code customers can use to apply the discount during
checkout.
starts_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Starts At
description: '**Starts At:** Timestamp after which the discount is redeemable.'
ends_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Ends At
description: >-
**Ends At:** Timestamp after which the discount is no longer
redeemable.
max_redemptions:
anyOf:
- type: integer
- type: 'null'
title: Max Redemptions
description: >-
**Max Redemptions:** Maximum number of times the discount can be
redeemed.
redemptions_count:
type: integer
title: Redemptions Count
description: Count of times the discount has been redeemed.
organization_id:
type: string
format: uuid4
title: Organization Id
description: Identifier of the organization.
examples:
- 1dbfc517-0bbf-4301-9ba8-555ca42b9737
x-ruba-selector-widget:
displayProperty: name
resourceName: Organization
resourceRoot: /v1/organizations
type: object
required:
- duration
- type
- amount
- currency
- amounts
- created_at
- modified_at
- id
- metadata
- name
- code
- starts_at
- ends_at
- max_redemptions
- redemptions_count
- organization_id
title: DiscountFixedOnceForeverDurationBase
DiscountFixedRepeatDurationBase:
properties:
duration:
$ref: '#/components/schemas/DiscountDuration'
duration_in_months:
type: integer
title: Duration In Months
type:
$ref: '#/components/schemas/DiscountType'
amount:
type: integer
title: Amount
deprecated: true
examples:
- 1000
currency:
type: string
title: Currency
deprecated: true
examples:
- usd
amounts:
additionalProperties:
type: integer
type: object
title: Amounts
description: >-
**Amounts:** Map of currency to fixed amount to discount from the
total.
examples:
- eur: 900
usd: 1000
created_at:
type: string
format: date-time
title: Created At
description: The time Ruba created this record.
modified_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Modified At
description: The time this record last changed.
id:
type: string
format: uuid4
title: Id
description: The stable identifier for this record.
metadata:
$ref: '#/components/schemas/MetadataOutputType'
name:
type: string
title: Name
description: >-
**Name:** Name of the discount. Will be displayed to the customer
when the discount is applied.
code:
anyOf:
- type: string
- type: 'null'
title: Code
description: >-
**Code:** Code customers can use to apply the discount during
checkout.
starts_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Starts At
description: '**Starts At:** Timestamp after which the discount is redeemable.'
ends_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Ends At
description: >-
**Ends At:** Timestamp after which the discount is no longer
redeemable.
max_redemptions:
anyOf:
- type: integer
- type: 'null'
title: Max Redemptions
description: >-
**Max Redemptions:** Maximum number of times the discount can be
redeemed.
redemptions_count:
type: integer
title: Redemptions Count
description: Count of times the discount has been redeemed.
organization_id:
type: string
format: uuid4
title: Organization Id
description: Identifier of the organization.
examples:
- 1dbfc517-0bbf-4301-9ba8-555ca42b9737
x-ruba-selector-widget:
displayProperty: name
resourceName: Organization
resourceRoot: /v1/organizations
type: object
required:
- duration
- duration_in_months
- type
- amount
- currency
- amounts
- created_at
- modified_at
- id
- metadata
- name
- code
- starts_at
- ends_at
- max_redemptions
- redemptions_count
- organization_id
title: DiscountFixedRepeatDurationBase
DiscountPercentageOnceForeverDurationBase:
properties:
duration:
$ref: '#/components/schemas/DiscountDuration'
type:
$ref: '#/components/schemas/DiscountType'
basis_points:
type: integer
title: Basis Points
description: >-
**Basis Points:** Discount percentage in basis points. A basis point
is 1/100th of a percent. For example, 1000 basis points equals a 10%
discount.
examples:
- 1000
created_at:
type: string
format: date-time
title: Created At
description: The time Ruba created this record.
modified_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Modified At
description: The time this record last changed.
id:
type: string
format: uuid4
title: Id
description: The stable identifier for this record.
metadata:
$ref: '#/components/schemas/MetadataOutputType'
name:
type: string
title: Name
description: >-
**Name:** Name of the discount. Will be displayed to the customer
when the discount is applied.
code:
anyOf:
- type: string
- type: 'null'
title: Code
description: >-
**Code:** Code customers can use to apply the discount during
checkout.
starts_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Starts At
description: '**Starts At:** Timestamp after which the discount is redeemable.'
ends_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Ends At
description: >-
**Ends At:** Timestamp after which the discount is no longer
redeemable.
max_redemptions:
anyOf:
- type: integer
- type: 'null'
title: Max Redemptions
description: >-
**Max Redemptions:** Maximum number of times the discount can be
redeemed.
redemptions_count:
type: integer
title: Redemptions Count
description: Count of times the discount has been redeemed.
organization_id:
type: string
format: uuid4
title: Organization Id
description: Identifier of the organization.
examples:
- 1dbfc517-0bbf-4301-9ba8-555ca42b9737
x-ruba-selector-widget:
displayProperty: name
resourceName: Organization
resourceRoot: /v1/organizations
type: object
required:
- duration
- type
- basis_points
- created_at
- modified_at
- id
- metadata
- name
- code
- starts_at
- ends_at
- max_redemptions
- redemptions_count
- organization_id
title: DiscountPercentageOnceForeverDurationBase
DiscountPercentageRepeatDurationBase:
properties:
duration:
$ref: '#/components/schemas/DiscountDuration'
duration_in_months:
type: integer
title: Duration In Months
type:
$ref: '#/components/schemas/DiscountType'
basis_points:
type: integer
title: Basis Points
description: >-
**Basis Points:** Discount percentage in basis points. A basis point
is 1/100th of a percent. For example, 1000 basis points equals a 10%
discount.
examples:
- 1000
created_at:
type: string
format: date-time
title: Created At
description: The time Ruba created this record.
modified_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Modified At
description: The time this record last changed.
id:
type: string
format: uuid4
title: Id
description: The stable identifier for this record.
metadata:
$ref: '#/components/schemas/MetadataOutputType'
name:
type: string
title: Name
description: >-
**Name:** Name of the discount. Will be displayed to the customer
when the discount is applied.
code:
anyOf:
- type: string
- type: 'null'
title: Code
description: >-
**Code:** Code customers can use to apply the discount during
checkout.
starts_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Starts At
description: '**Starts At:** Timestamp after which the discount is redeemable.'
ends_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Ends At
description: >-
**Ends At:** Timestamp after which the discount is no longer
redeemable.
max_redemptions:
anyOf:
- type: integer
- type: 'null'
title: Max Redemptions
description: >-
**Max Redemptions:** Maximum number of times the discount can be
redeemed.
redemptions_count:
type: integer
title: Redemptions Count
description: Count of times the discount has been redeemed.
organization_id:
type: string
format: uuid4
title: Organization Id
description: Identifier of the organization.
examples:
- 1dbfc517-0bbf-4301-9ba8-555ca42b9737
x-ruba-selector-widget:
displayProperty: name
resourceName: Organization
resourceRoot: /v1/organizations
type: object
required:
- duration
- duration_in_months
- type
- basis_points
- created_at
- modified_at
- id
- metadata
- name
- code
- starts_at
- ends_at
- max_redemptions
- redemptions_count
- organization_id
title: DiscountPercentageRepeatDurationBase
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
ProductVisibility:
type: string
enum:
- draft
- private
- public
title: Visibility
RecurringInterval:
type: string
enum:
- day
- week
- month
- year
title: RecurringInterval
LegacyRecurringProductPrice:
oneOf:
- $ref: '#/components/schemas/LegacyRecurringProductPriceFixed'
- $ref: '#/components/schemas/LegacyRecurringProductPriceCustom'
discriminator:
propertyName: amount_type
mapping:
custom:
$ref: '#/components/schemas/LegacyRecurringProductPriceCustom'
fixed:
$ref: '#/components/schemas/LegacyRecurringProductPriceFixed'
ProductPrice:
oneOf:
- $ref: '#/components/schemas/ProductPriceFixed'
- $ref: '#/components/schemas/ProductPriceCustom'
- $ref: '#/components/schemas/ProductPriceSeatBased'
- $ref: '#/components/schemas/ProductPriceMeteredUnit'
discriminator:
propertyName: amount_type
mapping:
custom:
$ref: '#/components/schemas/ProductPriceCustom'
fixed:
$ref: '#/components/schemas/ProductPriceFixed'
metered_unit:
$ref: '#/components/schemas/ProductPriceMeteredUnit'
seat_based:
$ref: '#/components/schemas/ProductPriceSeatBased'
BenefitPublic:
properties:
id:
type: string
format: uuid4
title: Id
description: Unique identifier for the benefit.
created_at:
type: string
format: date-time
title: Created At
description: The time Ruba created this record.
modified_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Modified At
description: The time this record last changed.
type:
$ref: '#/components/schemas/BenefitType'
description: '**Type:** Type of the benefit.'
description:
type: string
title: Description
description: Description attached to the benefit.
selectable:
type: boolean
title: Selectable
description: Indicates whether the benefit is selectable when creating a product.
deletable:
type: boolean
title: Deletable
description: Indicates whether the benefit is deletable.
is_deleted:
type: boolean
title: Is Deleted
description: Indicates whether the benefit is deleted.
organization_id:
type: string
format: uuid4
title: Organization Id
description: Unique identifier for the organization owning the benefit.
type: object
required:
- id
- created_at
- modified_at
- type
- description
- selectable
- deletable
- is_deleted
- organization_id
title: BenefitPublic
ProductMediaFileRead:
properties:
id:
type: string
format: uuid4
title: Id
description: The stable identifier for this record.
organization_id:
type: string
format: uuid4
title: Organization Id
name:
type: string
title: Name
path:
type: string
title: Path
mime_type:
type: string
title: Mime Type
size:
type: integer
title: Size
storage_version:
anyOf:
- type: string
- type: 'null'
title: Storage Version
checksum_etag:
anyOf:
- type: string
- type: 'null'
title: Checksum Etag
checksum_sha256_base64:
anyOf:
- type: string
- type: 'null'
title: Checksum Sha256 Base64
checksum_sha256_hex:
anyOf:
- type: string
- type: 'null'
title: Checksum Sha256 Hex
last_modified_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Last Modified At
version:
anyOf:
- type: string
- type: 'null'
title: Version
service:
type: string
const: product_media
title: Service
is_uploaded:
type: boolean
title: Is Uploaded
created_at:
type: string
format: date-time
title: Created At
size_readable:
type: string
title: Size Readable
readOnly: true
public_url:
type: string
title: Public Url
readOnly: true
type: object
required:
- id
- organization_id
- name
- path
- mime_type
- size
- storage_version
- checksum_etag
- checksum_sha256_base64
- checksum_sha256_hex
- last_modified_at
- version
- service
- is_uploaded
- created_at
- size_readable
- public_url
title: ProductMediaFileRead
description: File to be used as a product media file.
DiscountDuration:
type: string
enum:
- once
- forever
- repeating
title: DiscountDuration
DiscountType:
type: string
enum:
- fixed
- percentage
title: DiscountType
LegacyRecurringProductPriceFixed:
properties:
created_at:
type: string
format: date-time
title: Created At
description: The time Ruba created this record.
modified_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Modified At
description: The time this record last changed.
id:
type: string
format: uuid4
title: Id
description: Unique identifier for the price.
source:
$ref: '#/components/schemas/ProductPriceSource'
description: >-
**Source:** Source of the price . `catalog` is a predefined price,
while `ad_hoc` is a price created dynamically on a Checkout session.
amount_type:
type: string
const: fixed
title: Amount Type
price_currency:
type: string
title: Price Currency
description: '**Price Currency:** Currency in which the customer will be charged.'
tax_behavior:
anyOf:
- $ref: '#/components/schemas/TaxBehaviorOption'
- type: 'null'
description: >-
**Tax Behavior:** Tax behavior of the price. If null, it defaults to
the organization's default tax behavior.
is_archived:
type: boolean
title: Is Archived
description: Indicates whether the price is archived and no longer available.
product_id:
type: string
format: uuid4
title: Product Id
description: Unique identifier for the product owning the price.
type:
type: string
const: recurring
title: Type
description: '**Type:** Type of the price.'
recurring_interval:
$ref: '#/components/schemas/RecurringInterval'
description: '**Recurring Interval:** Recurring interval of the price.'
price_amount:
type: integer
title: Price Amount
description: '**Price Amount:** Price in cents.'
legacy:
type: boolean
const: true
title: Legacy
readOnly: true
type: object
required:
- created_at
- modified_at
- id
- source
- amount_type
- price_currency
- tax_behavior
- is_archived
- product_id
- type
- recurring_interval
- price_amount
- legacy
title: LegacyRecurringProductPriceFixed
description: >-
A recurring price for a product, i.e. a subscription.
**Deprecated**: The recurring interval should be set on the product
itself.
LegacyRecurringProductPriceCustom:
properties:
created_at:
type: string
format: date-time
title: Created At
description: The time Ruba created this record.
modified_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Modified At
description: The time this record last changed.
id:
type: string
format: uuid4
title: Id
description: Unique identifier for the price.
source:
$ref: '#/components/schemas/ProductPriceSource'
description: >-
**Source:** Source of the price . `catalog` is a predefined price,
while `ad_hoc` is a price created dynamically on a Checkout session.
amount_type:
type: string
const: custom
title: Amount Type
price_currency:
type: string
title: Price Currency
description: '**Price Currency:** Currency in which the customer will be charged.'
tax_behavior:
anyOf:
- $ref: '#/components/schemas/TaxBehaviorOption'
- type: 'null'
description: >-
**Tax Behavior:** Tax behavior of the price. If null, it defaults to
the organization's default tax behavior.
is_archived:
type: boolean
title: Is Archived
description: Indicates whether the price is archived and no longer available.
product_id:
type: string
format: uuid4
title: Product Id
description: Unique identifier for the product owning the price.
type:
type: string
const: recurring
title: Type
description: '**Type:** Type of the price.'
recurring_interval:
$ref: '#/components/schemas/RecurringInterval'
description: '**Recurring Interval:** Recurring interval of the price.'
minimum_amount:
type: integer
title: Minimum Amount
description: >-
**Minimum Amount:** Minimum amount the customer can pay. If 0, the
price is 'free or pay what you want'.
maximum_amount:
anyOf:
- type: integer
- type: 'null'
title: Maximum Amount
description: '**Maximum Amount:** Maximum amount the customer can pay.'
preset_amount:
anyOf:
- type: integer
- type: 'null'
title: Preset Amount
description: '**Preset Amount:** Initial amount shown to the customer.'
legacy:
type: boolean
const: true
title: Legacy
readOnly: true
type: object
required:
- created_at
- modified_at
- id
- source
- amount_type
- price_currency
- tax_behavior
- is_archived
- product_id
- type
- recurring_interval
- minimum_amount
- maximum_amount
- preset_amount
- legacy
title: LegacyRecurringProductPriceCustom
description: >-
A pay-what-you-want recurring price for a product, i.e. a subscription.
**Deprecated**: The recurring interval should be set on the product
itself.
ProductPriceFixed:
properties:
created_at:
type: string
format: date-time
title: Created At
description: The time Ruba created this record.
modified_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Modified At
description: The time this record last changed.
id:
type: string
format: uuid4
title: Id
description: Unique identifier for the price.
source:
$ref: '#/components/schemas/ProductPriceSource'
description: >-
**Source:** Source of the price . `catalog` is a predefined price,
while `ad_hoc` is a price created dynamically on a Checkout session.
amount_type:
type: string
const: fixed
title: Amount Type
price_currency:
type: string
title: Price Currency
description: '**Price Currency:** Currency in which the customer will be charged.'
tax_behavior:
anyOf:
- $ref: '#/components/schemas/TaxBehaviorOption'
- type: 'null'
description: >-
**Tax Behavior:** Tax behavior of the price. If null, it defaults to
the organization's default tax behavior.
is_archived:
type: boolean
title: Is Archived
description: Indicates whether the price is archived and no longer available.
product_id:
type: string
format: uuid4
title: Product Id
description: Unique identifier for the product owning the price.
price_amount:
type: integer
title: Price Amount
description: '**Price Amount:** Price in cents.'
type: object
required:
- created_at
- modified_at
- id
- source
- amount_type
- price_currency
- tax_behavior
- is_archived
- product_id
- price_amount
title: ProductPriceFixed
description: Object representing fixed price for a product.
ProductPriceCustom:
properties:
created_at:
type: string
format: date-time
title: Created At
description: The time Ruba created this record.
modified_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Modified At
description: The time this record last changed.
id:
type: string
format: uuid4
title: Id
description: Unique identifier for the price.
source:
$ref: '#/components/schemas/ProductPriceSource'
description: >-
**Source:** Source of the price . `catalog` is a predefined price,
while `ad_hoc` is a price created dynamically on a Checkout session.
amount_type:
type: string
const: custom
title: Amount Type
price_currency:
type: string
title: Price Currency
description: '**Price Currency:** Currency in which the customer will be charged.'
tax_behavior:
anyOf:
- $ref: '#/components/schemas/TaxBehaviorOption'
- type: 'null'
description: >-
**Tax Behavior:** Tax behavior of the price. If null, it defaults to
the organization's default tax behavior.
is_archived:
type: boolean
title: Is Archived
description: Indicates whether the price is archived and no longer available.
product_id:
type: string
format: uuid4
title: Product Id
description: Unique identifier for the product owning the price.
minimum_amount:
type: integer
title: Minimum Amount
description: >-
**Minimum Amount:** Minimum amount the customer can pay. If 0, the
price is 'free or pay what you want'.
maximum_amount:
anyOf:
- type: integer
- type: 'null'
title: Maximum Amount
description: '**Maximum Amount:** Maximum amount the customer can pay.'
preset_amount:
anyOf:
- type: integer
- type: 'null'
title: Preset Amount
description: '**Preset Amount:** Initial amount shown to the customer.'
type: object
required:
- created_at
- modified_at
- id
- source
- amount_type
- price_currency
- tax_behavior
- is_archived
- product_id
- minimum_amount
- maximum_amount
- preset_amount
title: ProductPriceCustom
description: Object representing pay-what-you-want price for a product.
ProductPriceSeatBased:
properties:
created_at:
type: string
format: date-time
title: Created At
description: The time Ruba created this record.
modified_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Modified At
description: The time this record last changed.
id:
type: string
format: uuid4
title: Id
description: Unique identifier for the price.
source:
$ref: '#/components/schemas/ProductPriceSource'
description: >-
**Source:** Source of the price . `catalog` is a predefined price,
while `ad_hoc` is a price created dynamically on a Checkout session.
amount_type:
type: string
const: seat_based
title: Amount Type
price_currency:
type: string
title: Price Currency
description: '**Price Currency:** Currency in which the customer will be charged.'
tax_behavior:
anyOf:
- $ref: '#/components/schemas/TaxBehaviorOption'
- type: 'null'
description: >-
**Tax Behavior:** Tax behavior of the price. If null, it defaults to
the organization's default tax behavior.
is_archived:
type: boolean
title: Is Archived
description: Indicates whether the price is archived and no longer available.
product_id:
type: string
format: uuid4
title: Product Id
description: Unique identifier for the product owning the price.
seat_tiers:
$ref: '#/components/schemas/ProductPriceSeatTiers-Output'
description: '**Seat Tiers:** Tiered pricing based on seat quantity.'
type: object
required:
- created_at
- modified_at
- id
- source
- amount_type
- price_currency
- tax_behavior
- is_archived
- product_id
- seat_tiers
title: ProductPriceSeatBased
description: Object representing seat-based price for a product.
ProductPriceMeteredUnit:
properties:
created_at:
type: string
format: date-time
title: Created At
description: The time Ruba created this record.
modified_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Modified At
description: The time this record last changed.
id:
type: string
format: uuid4
title: Id
description: Unique identifier for the price.
source:
$ref: '#/components/schemas/ProductPriceSource'
description: >-
**Source:** Source of the price . `catalog` is a predefined price,
while `ad_hoc` is a price created dynamically on a Checkout session.
amount_type:
type: string
const: metered_unit
title: Amount Type
price_currency:
type: string
title: Price Currency
description: '**Price Currency:** Currency in which the customer will be charged.'
tax_behavior:
anyOf:
- $ref: '#/components/schemas/TaxBehaviorOption'
- type: 'null'
description: >-
**Tax Behavior:** Tax behavior of the price. If null, it defaults to
the organization's default tax behavior.
is_archived:
type: boolean
title: Is Archived
description: Indicates whether the price is archived and no longer available.
product_id:
type: string
format: uuid4
title: Product Id
description: Unique identifier for the product owning the price.
unit_amount:
type: string
pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
title: Unit Amount
description: '**Unit Amount:** Price per unit in cents.'
cap_amount:
anyOf:
- type: integer
- type: 'null'
title: Cap Amount
description: >-
**Cap Amount:** Maximum amount in cents that can be charged,
regardless of the number of units consumed.
meter_id:
type: string
format: uuid4
title: Meter Id
description: Unique identifier for the meter associated to the price.
meter:
$ref: '#/components/schemas/ProductPriceMeter'
description: '**Meter:** Meter associated to the price.'
type: object
required:
- created_at
- modified_at
- id
- source
- amount_type
- price_currency
- tax_behavior
- is_archived
- product_id
- unit_amount
- cap_amount
- meter_id
- meter
title: ProductPriceMeteredUnit
description: >-
Object representing metered, usage-based, price for a product, with a
fixed unit price.
BenefitType:
type: string
enum:
- custom
- discord
- github_repository
- downloadables
- license_keys
- meter_credit
- feature_flag
- slack_shared_channel
title: BenefitType
ProductPriceSource:
type: string
enum:
- catalog
- ad_hoc
title: ProductPriceSource
TaxBehaviorOption:
type: string
enum:
- location
- inclusive
- exclusive
title: TaxBehaviorOption
ProductPriceSeatTiers-Output:
properties:
seat_tier_type:
$ref: '#/components/schemas/SeatTierType'
description: >-
**Seat Tier Type:** How tiers are applied. 'volume' prices all seats
at the matching tier's rate. 'graduated' prices each tier's range
independently.
default: volume
tiers:
items:
$ref: '#/components/schemas/ProductPriceSeatTier'
type: array
minItems: 1
title: Tiers
description: Collection of pricing tiers.
minimum_seats:
type: integer
title: Minimum Seats
description: >-
**Minimum Seats:** Minimum number of seats required for purchase,
derived from first tier.
readOnly: true
maximum_seats:
anyOf:
- type: integer
- type: 'null'
title: Maximum Seats
description: >-
**Maximum Seats:** Maximum number of seats allowed for purchase,
derived from last tier. None for unlimited.
readOnly: true
type: object
required:
- tiers
- minimum_seats
- maximum_seats
title: ProductPriceSeatTiers
description: |-
List of pricing tiers for seat-based pricing.
The minimum and maximum seat limits are derived from the tiers:
- minimum_seats = first tier's min_seats
- maximum_seats = last tier's max_seats (None for unlimited)
ProductPriceMeter:
properties:
id:
type: string
format: uuid4
title: Id
description: The stable identifier for this record.
name:
type: string
title: Name
description: Name assigned to the meter.
unit:
$ref: '#/components/schemas/MeterUnit'
description: '**Unit:** Unit of the meter.'
custom_label:
anyOf:
- type: string
- type: 'null'
title: Custom Label
description: '**Custom Label:** Label for the custom unit.'
custom_multiplier:
anyOf:
- type: integer
- type: 'null'
title: Custom Multiplier
description: >-
**Custom Multiplier:** Multiplier to convert from base unit to
display scale.
type: object
required:
- id
- name
- unit
title: ProductPriceMeter
description: Object representing meter associated to a metered price.
SeatTierType:
type: string
enum:
- volume
- graduated
title: SeatTierType
ProductPriceSeatTier:
properties:
min_seats:
type: integer
minimum: 1
title: Min Seats
description: '**Min Seats:** Minimum number of seats (inclusive).'
max_seats:
anyOf:
- type: integer
minimum: 1
- type: 'null'
title: Max Seats
description: >-
**Max Seats:** Maximum number of seats (inclusive). None for
unlimited.
price_per_seat:
type: integer
minimum: 0
title: Price Per Seat
description: '**Price Per Seat:** Price per seat in cents for this tier.'
type: object
required:
- min_seats
- price_per_seat
title: ProductPriceSeatTier
description: Object representing pricing tier for seat-based pricing.
MeterUnit:
type: string
enum:
- scalar
- token
- custom
title: MeterUnit
securitySchemes:
oidc:
type: openIdConnect
openIdConnectUrl: /.well-known/openid-configuration
pat:
type: http
description: >-
**Authentication:** You can generate a **Personal Access Token** from
your [settings](https://getruba.com/settings).
scheme: bearer
oat:
type: http
description: >-
**Authentication:** You can generate an **Organization Access Token**
from your organization's settings.
scheme: bearer
````