> ## 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.
# Change Subscription
> ### Intent
Applies the supplied changes to the subscription.
### When to call it
Call this when the subscription already exists and its stored values need to change.
### Access boundary
Authorize the request with a token that carries `customer_portal:write`.
### Successful result
A successful request returns `200`. 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;
};
## OpenAPI
````yaml patch /v1/customer-portal/subscriptions/{id}
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/customer-portal/subscriptions/{id}:
patch:
tags:
- customer_portal
- subscriptions
- public
summary: Change Subscription
description: >-
### Intent
Applies the supplied changes to the subscription.
### When to call it
Call this when the subscription already exists and its stored values
need to change.
### Access boundary
Authorize the request with a token that carries `customer_portal:write`.
### Successful result
A successful request returns `200`. The response schema below defines
the body your integration receives.
operationId: customer_portal:subscriptions:update
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid4
description: Identifier of the subscription.
title: Id
description: Identifier of the subscription.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerSubscriptionUpdate'
responses:
'200':
description: '**Response:** Customer subscription updated.'
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerSubscription'
'402':
description: '**Response:** Payment required to apply the subscription update.'
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentFailed'
'403':
description: >-
**Response:** Customer subscription is already canceled or will be
at the end of the period, or the user lacks billing permissions.
content:
application/json:
schema:
$ref: '#/components/schemas/AlreadyCanceledSubscription'
'404':
description: '**Response:** Customer subscription was could not be found.'
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceNotFound'
'422':
description: Request validation failed
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- customer_session:
- customer_portal:write
- member_session:
- customer_portal:write
components:
schemas:
CustomerSubscriptionUpdate:
anyOf:
- $ref: '#/components/schemas/CustomerSubscriptionUpdateProduct'
- $ref: '#/components/schemas/CustomerSubscriptionUpdateSeats'
- $ref: '#/components/schemas/CustomerSubscriptionCancel'
- $ref: '#/components/schemas/CustomerSubscriptionUpdateClear'
CustomerSubscription:
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: The stable identifier for this record.
amount:
type: integer
title: Amount
description: '**Amount:** Amount of the subscription.'
examples:
- 10000
currency:
type: string
title: Currency
description: '**Currency:** Currency of the subscription.'
examples:
- usd
recurring_interval:
$ref: '#/components/schemas/RecurringInterval'
description: '**Recurring Interval:** Interval at which the subscription recurs.'
examples:
- month
recurring_interval_count:
type: integer
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.
status:
$ref: '#/components/schemas/SubscriptionStatus'
description: '**Status:** Status of the subscription.'
examples:
- active
current_period_start:
type: string
format: date-time
title: Current Period Start
description: >-
**Current Period Start:** Start timestamp of the current billing
period.
current_period_end:
type: string
format: date-time
title: Current Period End
description: '**Current Period End:** End timestamp of the current billing period.'
trial_start:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Trial Start
description: '**Trial Start:** Start timestamp of the trial period, if any.'
trial_end:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Trial End
description: '**Trial End:** End timestamp of the trial period, if any.'
cancel_at_period_end:
type: boolean
title: Cancel At Period End
description: >-
Indicates whether the subscription will be canceled at the end of
the current period.
canceled_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Canceled At
description: >-
**Canceled At:** Timestamp when the subscription was canceled. The
subscription might still be active if `cancel_at_period_end` is
`true`.
started_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Started At
description: '**Started At:** Timestamp when the subscription started.'
ends_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Ends At
description: '**Ends At:** Timestamp when the subscription will end.'
ended_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Ended At
description: '**Ended At:** Timestamp when the subscription ended.'
past_due_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Past Due At
description: >-
**Past Due At:** Timestamp when the subscription entered `past_due`
status.
customer_id:
type: string
format: uuid4
title: Customer Id
description: Unique identifier for the subscribed customer.
product_id:
type: string
format: uuid4
title: Product Id
description: Unique identifier for the subscribed product.
discount_id:
anyOf:
- type: string
format: uuid4
- type: 'null'
title: Discount Id
description: Unique identifier for the applied discount, if any.
checkout_id:
anyOf:
- type: string
format: uuid4
- type: 'null'
title: Checkout Id
seats:
anyOf:
- type: integer
- type: 'null'
title: Seats
description: >-
Count of seats for seat-based subscriptions. None for non-seat
subscriptions.
customer_cancellation_reason:
anyOf:
- $ref: '#/components/schemas/CustomerCancellationReason'
- type: 'null'
customer_cancellation_comment:
anyOf:
- type: string
- type: 'null'
title: Customer Cancellation Comment
product:
$ref: '#/components/schemas/CustomerSubscriptionProduct'
prices:
items:
oneOf:
- $ref: '#/components/schemas/LegacyRecurringProductPrice'
- $ref: '#/components/schemas/ProductPrice'
type: array
title: Prices
description: Collection of enabled prices for the subscription.
meters:
items:
$ref: '#/components/schemas/CustomerSubscriptionMeter'
type: array
title: Meters
description: Collection of meters associated with the subscription.
pending_update:
anyOf:
- $ref: '#/components/schemas/PendingSubscriptionUpdate'
- type: 'null'
description: >-
**Pending Update:** Pending subscription update that will be applied
at the beginning of the next period. If `null`, there is no pending
update.
type: object
required:
- created_at
- modified_at
- id
- amount
- currency
- recurring_interval
- recurring_interval_count
- status
- current_period_start
- current_period_end
- trial_start
- trial_end
- cancel_at_period_end
- canceled_at
- started_at
- ends_at
- ended_at
- customer_id
- product_id
- discount_id
- checkout_id
- customer_cancellation_reason
- customer_cancellation_comment
- product
- prices
- meters
- pending_update
title: CustomerSubscription
PaymentFailed:
properties:
error:
type: string
const: PaymentFailed
title: Error
examples:
- PaymentFailed
detail:
type: string
title: Detail
type: object
required:
- error
- detail
title: PaymentFailed
AlreadyCanceledSubscription:
properties:
error:
type: string
const: AlreadyCanceledSubscription
title: Error
examples:
- AlreadyCanceledSubscription
detail:
type: string
title: Detail
type: object
required:
- error
- detail
title: AlreadyCanceledSubscription
ResourceNotFound:
properties:
error:
type: string
const: ResourceNotFound
title: Error
examples:
- ResourceNotFound
detail:
type: string
title: Detail
type: object
required:
- error
- detail
title: ResourceNotFound
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
CustomerSubscriptionUpdateProduct:
properties:
product_id:
type: string
format: uuid4
title: Product Id
description: '**Product Id:** Update subscription to another product.'
type: object
required:
- product_id
title: CustomerSubscriptionUpdateProduct
CustomerSubscriptionUpdateSeats:
properties:
seats:
type: integer
minimum: 1
title: Seats
description: '**Seats:** Update the number of seats for this subscription.'
proration_behavior:
anyOf:
- $ref: '#/components/schemas/SubscriptionProrationBehavior'
- type: 'null'
description: >-
**Proration Behavior:** Determines how to handle the proration
billing. If not provided, will use the default organization setting.
type: object
required:
- seats
title: CustomerSubscriptionUpdateSeats
CustomerSubscriptionCancel:
properties:
cancel_at_period_end:
anyOf:
- type: boolean
- type: 'null'
title: Cancel At Period End
description: >-
Cancel an active subscription once the current period ends.
Or uncancel a subscription currently set to be revoked at period
end.
cancellation_reason:
anyOf:
- $ref: '#/components/schemas/CustomerCancellationReason'
- type: 'null'
description: >-
Customers reason for cancellation.
* `too_expensive`: Too expensive for the customer.
* `missing_features`: Customer is missing certain features.
* `switched_service`: Customer switched to another service.
* `unused`: Customer is not using it enough.
* `customer_service`: Customer is not satisfied with the customer
service.
* `low_quality`: Customer is unhappy with the quality.
* `too_complex`: Customer considers the service too complicated.
* `other`: Other reason(s).
cancellation_comment:
anyOf:
- type: string
- type: 'null'
title: Cancellation Comment
description: >-
**Cancellation Comment:** Customer feedback and why they decided to
cancel.
type: object
title: CustomerSubscriptionCancel
CustomerSubscriptionUpdateClear:
properties:
pending_update:
type: 'null'
title: Pending Update
description: '**Pending Update:** Clear the pending subscription update.'
type: object
required:
- pending_update
title: CustomerSubscriptionUpdateClear
RecurringInterval:
type: string
enum:
- day
- week
- month
- year
title: RecurringInterval
SubscriptionStatus:
type: string
enum:
- incomplete
- incomplete_expired
- trialing
- active
- past_due
- canceled
- unpaid
title: SubscriptionStatus
CustomerCancellationReason:
type: string
enum:
- customer_service
- low_quality
- missing_features
- switched_service
- too_complex
- too_expensive
- unused
- other
title: CustomerCancellationReason
CustomerSubscriptionProduct:
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.
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.
organization:
$ref: '#/components/schemas/CustomerOrganization'
type: object
required:
- 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
- organization
title: CustomerSubscriptionProduct
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'
CustomerSubscriptionMeter:
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: The stable identifier for this record.
consumed_units:
type: number
title: Consumed Units
description: Count of consumed units so far in this billing period.
examples:
- 25
credited_units:
type: integer
title: Credited Units
description: Count of credited units so far in this billing period.
examples:
- 100
amount:
type: integer
title: Amount
description: '**Amount:** Amount due in cents so far in this billing period.'
examples:
- 0
meter_id:
type: string
format: uuid4
title: Meter Id
description: Unique identifier for the meter.
examples:
- d498a884-e2cd-4d3e-8002-f536468a8b22
meter:
$ref: '#/components/schemas/CustomerSubscriptionMeterMeter'
type: object
required:
- created_at
- modified_at
- id
- consumed_units
- credited_units
- amount
- meter_id
- meter
title: CustomerSubscriptionMeter
PendingSubscriptionUpdate:
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: The stable identifier for this record.
applies_at:
type: string
format: date-time
title: Applies At
description: >-
**Applies At:** Date and time when the subscription update will be
applied.
product_id:
anyOf:
- type: string
format: uuid4
- type: 'null'
title: Product Id
description: >-
Identifier of the new product to apply to the subscription. If
`null`, the product won't be changed.
seats:
anyOf:
- type: integer
- type: 'null'
title: Seats
description: >-
Count of seats to apply to the subscription. If `null`, the number
of seats won't be changed.
type: object
required:
- created_at
- modified_at
- id
- applies_at
- product_id
- seats
title: PendingSubscriptionUpdate
description: >-
Pending update to be applied to a subscription at the beginning of the
next period.
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
SubscriptionProrationBehavior:
type: string
enum:
- invoice
- prorate
- next_period
- reset
title: SubscriptionProrationBehavior
TrialInterval:
type: string
enum:
- day
- week
- month
- year
title: TrialInterval
ProductVisibility:
type: string
enum:
- draft
- private
- public
title: Visibility
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.
CustomerOrganization:
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: The stable identifier for this record.
name:
type: string
title: Name
description: >-
**Name:** Organization name shown in checkout, customer portal,
emails etc.
slug:
type: string
title: Slug
description: >-
**Slug:** Unique organization slug in checkout, customer portal and
credit card statements.
avatar_url:
anyOf:
- type: string
- type: 'null'
title: Avatar Url
description: >-
**Avatar Url:** Avatar URL shown in checkout, customer portal,
emails etc.
proration_behavior:
$ref: '#/components/schemas/SubscriptionProrationBehavior'
description: >-
**Proration Behavior:** Proration behavior applied when customer
updates their subscription from the portal.
allow_customer_updates:
type: boolean
title: Allow Customer Updates
description: >-
Indicates whether customers can update their subscriptions from the
customer portal.
customer_portal_settings:
$ref: '#/components/schemas/OrganizationCustomerPortalSettings'
description: >-
**Customer Portal Settings:** Settings related to the customer
portal.
organization_features:
$ref: '#/components/schemas/CustomerOrganizationFeatureSettings'
description: '**Organization Features:** Feature flags for the customer portal.'
type: object
required:
- created_at
- modified_at
- id
- name
- slug
- avatar_url
- proration_behavior
- allow_customer_updates
- customer_portal_settings
title: CustomerOrganization
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.
CustomerSubscriptionMeterMeter:
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: The stable identifier for this record.
name:
type: string
title: Name
description: >-
Name assigned to the meter. Will be shown on customer's invoices and
usage.
type: object
required:
- created_at
- modified_at
- id
- name
title: CustomerSubscriptionMeterMeter
BenefitType:
type: string
enum:
- custom
- discord
- github_repository
- downloadables
- license_keys
- meter_credit
- feature_flag
- slack_shared_channel
title: BenefitType
OrganizationCustomerPortalSettings:
properties:
usage:
$ref: '#/components/schemas/CustomerPortalUsageSettings'
subscription:
$ref: '#/components/schemas/CustomerPortalSubscriptionSettings'
customer:
$ref: '#/components/schemas/CustomerPortalCustomerSettings'
type: object
required:
- usage
- subscription
title: OrganizationCustomerPortalSettings
CustomerOrganizationFeatureSettings:
properties:
member_model_enabled:
type: boolean
title: Member Model Enabled
description: Indicates whether the member model is enabled for this organization.
default: false
checkout_localization_enabled:
type: boolean
title: Checkout Localization Enabled
description: Indicates whether localization is enabled for this organization.
default: false
type: object
title: CustomerOrganizationFeatureSettings
description: Feature flags exposed to the customer portal.
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.
CustomerPortalUsageSettings:
properties:
show:
type: boolean
title: Show
type: object
required:
- show
title: CustomerPortalUsageSettings
CustomerPortalSubscriptionSettings:
properties:
update_seats:
type: boolean
title: Update Seats
update_plan:
type: boolean
title: Update Plan
type: object
required:
- update_seats
- update_plan
title: CustomerPortalSubscriptionSettings
CustomerPortalCustomerSettings:
properties:
allow_email_change:
type: boolean
title: Allow Email Change
type: object
title: CustomerPortalCustomerSettings
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:
customer_session:
type: http
description: >-
**Authentication:** Customer session tokens authenticate buyers within
your organization. Generate one through the [customer session
operation](/api-reference/customer-portal/sessions/create).
scheme: bearer
member_session:
type: http
description: >-
**Authentication:** Member session tokens authenticate team members
within a customer account. Generate one through the [member session
operation](/api-reference/member-portal/sessions/create).
scheme: bearer
````