Rye Commissions API
The Commissions API from Rye — 2 operation(s) for commissions.
OpenAPI Specification
openapi: 3.0.0
info:
title: Universal Checkout Betas Commissions API
version: 1.0.5
description: 'Turn any product URL into a completed checkout. Instantly retrieve price, tax, and shipping for any product, and let users buy without ever leaving your native AI experience.
View the [Rye API docs](https://docs.rye.com).'
termsOfService: https://rye.com/terms-of-service
license:
name: UNLICENSED
contact:
name: Rye
email: dev@rye.com
url: https://docs.rye.com
servers:
- url: https://staging.api.rye.com
tags:
- name: Commissions
paths:
/api/v1/commissions/{id}:
get:
operationId: GetCommission
responses:
'200':
description: Commission details
content:
application/json:
schema:
$ref: '#/components/schemas/CommissionResponse'
'401':
description: Authentication Failed
content:
application/json:
schema:
$ref: '#/components/schemas/AuthenticationError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
description: 'Retrieve a commission by id
Returns commission details for the authenticated developer.'
summary: Retrieve commission
tags:
- Commissions
security:
- bearerAuth:
- billing:read
parameters:
- description: The id of the commission to look up
in: path
name: id
required: true
schema:
type: string
/api/v1/commissions:
get:
operationId: ListCommissions
responses:
'200':
description: Paginated commissions response
content:
application/json:
schema:
$ref: '#/components/schemas/CommissionListResponse'
'401':
description: Authentication Failed
content:
application/json:
schema:
$ref: '#/components/schemas/AuthenticationError'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateError'
description: 'List commissions for the authenticated developer
Returns a paginated list of commissions with optional filters using
cursor-based pagination. Pass the `endCursor` from a previous response
as `after` to fetch the next page, or the `startCursor` as `before` to
fetch the previous page. Specifying both `after` and `before` returns 422.'
summary: List commissions
tags:
- Commissions
security:
- bearerAuth:
- billing:read
parameters:
- description: Maximum number of results to return (default 100)
in: query
name: limit
required: false
schema:
format: int32
type: integer
minimum: 1
maximum: 100
- description: Cursor from a previous response's `pageInfo.endCursor`
in: query
name: after
required: false
schema:
type: string
- description: Cursor from a previous response's `pageInfo.startCursor`
in: query
name: before
required: false
schema:
type: string
- in: query
name: type
required: false
schema:
$ref: '#/components/schemas/CommissionType'
- in: query
name: status
required: false
schema:
$ref: '#/components/schemas/CommissionStatus'
- in: query
name: checkoutIntentId
required: false
schema:
type: string
x-codeSamples:
- lang: JavaScript
source: "import CheckoutIntents from 'checkout-intents';\n\nconst client = new CheckoutIntents({\n apiKey: process.env['CHECKOUT_INTENTS_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const commission of client.commissions.list()) {\n console.log(commission.id);\n}"
- lang: Python
source: "import os\nfrom checkout_intents import CheckoutIntents\n\nclient = CheckoutIntents(\n api_key=os.environ.get(\"CHECKOUT_INTENTS_API_KEY\"), # This is the default and can be omitted\n)\npage = client.commissions.list()\npage = page.data[0]\nprint(page.id)"
- lang: Java
source: "package com.rye.example;\n\nimport com.rye.client.CheckoutIntentsClient;\nimport com.rye.client.okhttp.CheckoutIntentsOkHttpClient;\nimport com.rye.models.commissions.CommissionListPage;\nimport com.rye.models.commissions.CommissionListParams;\n\npublic final class Main {\n private Main() {}\n\n public static void main(String[] args) {\n CheckoutIntentsClient client = CheckoutIntentsOkHttpClient.fromEnv();\n\n CommissionListPage page = client.commissions().list();\n }\n}"
- lang: cURL
source: "curl https://staging.api.rye.com/api/v1/commissions \\\n -H \"Authorization: Bearer $CHECKOUT_INTENTS_API_KEY\""
components:
schemas:
AuthenticationError:
properties:
name:
type: string
message:
type: string
stack:
type: string
required:
- name
- message
type: object
additionalProperties: false
ValidateError:
properties:
name:
type: string
message:
type: string
stack:
type: string
status:
type: number
format: double
fields:
$ref: '#/components/schemas/FieldErrors'
required:
- name
- message
- status
- fields
type: object
additionalProperties: false
CommissionStatus:
type: string
enum:
- pending
- confirmed
- updated
- finalized
- refunded
- expired
description: Lifecycle status of a commission record.
CommissionType:
type: string
enum:
- surcharge
- promo_arbitrage
- discount_code
- affiliate
- out_of_band
description: 'Type of commission earned on an order. Canonical definition used by
both the API contract and the internal `@rye-com/ci-commissions` package.'
CommissionListResponse:
properties:
pageInfo:
properties:
endCursor:
type: string
startCursor:
type: string
hasPreviousPage:
type: boolean
hasNextPage:
type: boolean
required:
- hasPreviousPage
- hasNextPage
type: object
data:
items:
$ref: '#/components/schemas/CommissionResponse'
type: array
required:
- pageInfo
- data
type: object
description: 'Paginated commissions response. Use `pageInfo.endCursor` as the next page''s
`after` query parameter to walk forward; use `pageInfo.startCursor` as the
next page''s `before` query parameter to walk backward.'
Money:
properties:
currencyCode:
type: string
example: USD
amountSubunits:
type: integer
format: int32
example: 1500
required:
- currencyCode
- amountSubunits
type: object
NotFoundError:
properties:
name:
type: string
message:
type: string
stack:
type: string
required:
- name
- message
type: object
additionalProperties: false
FieldErrors:
properties: {}
type: object
additionalProperties:
properties:
value: {}
message:
type: string
required:
- message
type: object
SettlementDirection:
type: string
enum:
- rye_owes_developer
- developer_owes_rye
description: 'Direction of settlement: who owes whom once the commission is finalized.'
CommissionResponse:
properties:
finalizedAt:
type: string
format: date-time
description: Time the commission moved to a terminal status. Unset until finalized.
updatedAt:
type: string
format: date-time
description: Time the commission last changed (e.g. status transition).
createdAt:
type: string
format: date-time
description: Time the commission was first recorded.
ryeFee:
$ref: '#/components/schemas/Money'
description: Fee retained by Rye.
developerCommission:
$ref: '#/components/schemas/Money'
description: Commission amount paid to the developer.
settlementDirection:
$ref: '#/components/schemas/SettlementDirection'
description: Whether Rye owes the developer or vice versa once settled.
status:
$ref: '#/components/schemas/CommissionStatus'
description: Lifecycle status, e.g. pending, finalized, refunded.
type:
$ref: '#/components/schemas/CommissionType'
description: Kind of commission, e.g. surcharge, discount_code, affiliate.
checkoutIntentId:
type: string
description: The checkout intent this commission was generated from.
id:
type: string
description: Unique identifier for this commission.
required:
- updatedAt
- createdAt
- ryeFee
- developerCommission
- settlementDirection
- status
- type
- checkoutIntentId
- id
type: object
description: A commission earned (or owed) on a completed checkout intent.
securitySchemes:
bearerAuth:
type: apiKey
in: header
name: Authorization
description: Rye API key