Rye Billing API

openapi: 3.0.0
info:
  title: Universal Checkout Betas Billing 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: Billing
paths:
  /api/v1/billing/balance:
    get:
      operationId: GetBalance
      responses:
        '200':
          description: Balance in smallest currency unit and currency code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceResponse'
        '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: Get current drawdown balance for the authenticated developer
      summary: Get drawdown balance
      tags:
      - Billing
      security:
      - bearerAuth:
        - billing:read
      parameters: []
      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\nconst response = await client.billing.getBalance();\n\nconsole.log(response.balance);"
      - 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)\nresponse = client.billing.get_balance()\nprint(response.balance)"
      - lang: Java
        source: "package com.rye.example;\n\nimport com.rye.client.CheckoutIntentsClient;\nimport com.rye.client.okhttp.CheckoutIntentsOkHttpClient;\nimport com.rye.models.billing.BillingGetBalanceParams;\nimport com.rye.models.billing.BillingGetBalanceResponse;\n\npublic final class Main {\n    private Main() {}\n\n    public static void main(String[] args) {\n        CheckoutIntentsClient client = CheckoutIntentsOkHttpClient.fromEnv();\n\n        BillingGetBalanceResponse response = client.billing().getBalance();\n    }\n}"
      - lang: cURL
        source: "curl https://staging.api.rye.com/api/v1/billing/balance \\\n    -H \"Authorization: Bearer $CHECKOUT_INTENTS_API_KEY\""
  /api/v1/billing:
    get:
      operationId: GetSettings
      responses:
        '200':
          description: Billing configuration including drawdown settings and balance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingResponse'
        '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: Get billing configuration and balance for the authenticated developer
      summary: Get billing info
      tags:
      - Billing
      security:
      - bearerAuth:
        - billing:read
      parameters: []
  /api/v1/billing/drawdown:
    post:
      operationId: SetupDrawdown
      responses:
        '200':
          description: Updated billing configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingResponse'
        '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: Set up or update drawdown billing for the authenticated developer
      summary: Setup drawdown billing
      tags:
      - Billing
      security:
      - bearerAuth:
        - billing:write
      parameters: []
      requestBody:
        description: Drawdown settings to configure
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetupDrawdownParams'
              description: ''
  /api/v1/billing/drawdown/topup:
    post:
      operationId: CreateTopUpInvoice
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '400':
          description: ''
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                required:
                - message
                type: object
        '401':
          description: Authentication Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
        '409':
          description: ''
          content:
            application/json:
              schema:
                properties:
                  invoice:
                    anyOf:
                    - $ref: '#/components/schemas/Invoice'
                    - $ref: '#/components/schemas/DuplicateInvoice'
                    nullable: true
                  message:
                    type: string
                required:
                - invoice
                - message
                type: object
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateError'
        '503':
          description: ''
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                required:
                - message
                type: object
      description: 'Request an on-demand top-up invoice..

        Requires drawdown billing to be enabled. Only one unpaid top-up invoice

        is allowed at a time.'
      summary: Create on-demand top-up invoice
      tags:
      - Billing
      security:
      - bearerAuth:
        - billing:write
      parameters: []
      requestBody:
        description: Top-up parameters
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTopUpParams'
              description: ''
      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\nconst response = await client.billing.createTopupInvoice({ amountSubunits: 500000 });\n\nconsole.log(response.id);"
      - 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)\nresponse = client.billing.create_topup_invoice(\n    amount_subunits=500000,\n)\nprint(response.id)"
      - lang: Java
        source: "package com.rye.example;\n\nimport com.rye.client.CheckoutIntentsClient;\nimport com.rye.client.okhttp.CheckoutIntentsOkHttpClient;\nimport com.rye.models.billing.BillingCreateTopupInvoiceParams;\nimport com.rye.models.billing.BillingCreateTopupInvoiceResponse;\n\npublic final class Main {\n    private Main() {}\n\n    public static void main(String[] args) {\n        CheckoutIntentsClient client = CheckoutIntentsOkHttpClient.fromEnv();\n\n        BillingCreateTopupInvoiceParams params = BillingCreateTopupInvoiceParams.builder()\n            .amountSubunits(500000)\n            .build();\n        BillingCreateTopupInvoiceResponse response = client.billing().createTopupInvoice(params);\n    }\n}"
      - lang: cURL
        source: "curl https://staging.api.rye.com/api/v1/billing/drawdown/topup \\\n    -H 'Content-Type: application/json' \\\n    -H \"Authorization: Bearer $CHECKOUT_INTENTS_API_KEY\" \\\n    -d '{\n          \"amountSubunits\": 500000,\n          \"chargeAutomatically\": false\n        }'"
  /api/v1/billing/drawdown/topup/{invoiceId}:
    delete:
      operationId: CancelTopUpInvoice
      responses:
        '204':
          description: No Content
        '400':
          description: ''
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                required:
                - message
                type: object
        '401':
          description: Authentication Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
        '404':
          description: ''
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                required:
                - message
                type: object
        '409':
          description: ''
          content:
            application/json:
              schema:
                properties:
                  status:
                    type: string
                  invoiceId:
                    type: string
                  message:
                    type: string
                required:
                - status
                - invoiceId
                - message
                type: object
      description: 'Cancel/void an unpaid top-up invoice.

        Only invoices in open state can be cancelled.'
      summary: Cancel top-up invoice
      tags:
      - Billing
      security:
      - bearerAuth:
        - billing:write
      parameters:
      - description: The Stripe invoice ID to cancel
        in: path
        name: invoiceId
        required: true
        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\nawait client.billing.cancelTopupInvoice('invoiceId');"
      - 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)\nclient.billing.cancel_topup_invoice(\n    \"invoiceId\",\n)"
      - lang: Java
        source: "package com.rye.example;\n\nimport com.rye.client.CheckoutIntentsClient;\nimport com.rye.client.okhttp.CheckoutIntentsOkHttpClient;\nimport com.rye.models.billing.BillingCancelTopupInvoiceParams;\n\npublic final class Main {\n    private Main() {}\n\n    public static void main(String[] args) {\n        CheckoutIntentsClient client = CheckoutIntentsOkHttpClient.fromEnv();\n\n        client.billing().cancelTopupInvoice(\"invoiceId\");\n    }\n}"
      - lang: cURL
        source: "curl https://staging.api.rye.com/api/v1/billing/drawdown/topup/$INVOICE_ID \\\n    -X DELETE \\\n    -H \"Authorization: Bearer $CHECKOUT_INTENTS_API_KEY\""
  /api/v1/billing/transactions:
    get:
      operationId: ListTransactions
      responses:
        '200':
          description: Paginated list of balance transactions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionsResponse'
        '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 drawdown balance transactions for the authenticated developer
      summary: List drawdown transactions
      tags:
      - Billing
      security:
      - bearerAuth:
        - billing:read
      parameters:
      - description: Maximum number of transactions to return (default 20)
        in: query
        name: limit
        required: false
        schema:
          default: 20
          format: int32
          type: integer
          minimum: 1
          maximum: 100
      - description: Cursor for forward pagination (transaction ID to start after)
        in: query
        name: after
        required: false
        schema:
          type: string
      - description: Cursor for backward pagination (transaction ID to end before)
        in: query
        name: before
        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 billingListTransactionsResponse of client.billing.listTransactions()) {\n  console.log(billingListTransactionsResponse.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.billing.list_transactions()\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.billing.BillingListTransactionsPage;\nimport com.rye.models.billing.BillingListTransactionsParams;\n\npublic final class Main {\n    private Main() {}\n\n    public static void main(String[] args) {\n        CheckoutIntentsClient client = CheckoutIntentsOkHttpClient.fromEnv();\n\n        BillingListTransactionsPage page = client.billing().listTransactions();\n    }\n}"
      - lang: cURL
        source: "curl https://staging.api.rye.com/api/v1/billing/transactions \\\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
    CreateTopUpParams:
      properties:
        chargeAutomatically:
          type: boolean
          description: 'Override whether to automatically charge the invoice.

            Defaults to the developer''s drawdown config value if not specified.'
          example: false
        amountSubunits:
          type: integer
          format: int32
          description: Amount in smallest currency unit (e.g. cents).
          example: 500000
          minimum: 1
      required:
      - amountSubunits
      type: object
    Omit_Invoice.amount-or-bankTransferDetails_:
      $ref: '#/components/schemas/Pick_Invoice.Exclude_keyofInvoice.amount-or-bankTransferDetails__'
      description: Construct a type with the properties of T except for those in type K.
    Pick_Invoice.Exclude_keyofInvoice.amount-or-bankTransferDetails__:
      properties:
        id:
          type: string
          example: in_abc123
        status:
          $ref: '#/components/schemas/InvoiceStatus'
        url:
          type: string
          example: https://invoice.stripe.com/i/acct_xxx/test_xxx
      required:
      - id
      - status
      - url
      type: object
      description: From T, pick a set of properties whose keys are in the union K
    Invoice:
      properties:
        bankTransferDetails:
          $ref: '#/components/schemas/BankTransferDetails'
        url:
          type: string
          nullable: true
          example: https://invoice.stripe.com/i/acct_xxx/test_xxx
        amount:
          $ref: '#/components/schemas/Money'
        status:
          $ref: '#/components/schemas/InvoiceStatus'
        id:
          type: string
          example: in_abc123
      required:
      - bankTransferDetails
      - url
      - amount
      - status
      - id
      type: object
    TransactionResponse:
      properties:
        createdAt:
          type: string
          format: date-time
        metadata:
          $ref: '#/components/schemas/Record_string.string_'
        description:
          type: string
          example: 'Balance debit for order #12345'
        amount:
          $ref: '#/components/schemas/Money'
        id:
          type: string
          example: cbtxn_abc123
      required:
      - createdAt
      - amount
      - id
      type: object
    BillingResponse:
      properties:
        drawdown:
          properties:
            balance:
              allOf:
              - $ref: '#/components/schemas/Money'
              nullable: true
            config:
              properties:
                chargeAutomatically:
                  type: boolean
                currency:
                  type: string
                  example: USD
                minBalanceSubunits:
                  type: number
                  format: double
                  example: 200000
                targetBalanceSubunits:
                  type: number
                  format: double
                  example: 1000000
              required:
              - chargeAutomatically
              - currency
              - minBalanceSubunits
              - targetBalanceSubunits
              type: object
              nullable: true
            enabled:
              type: boolean
          required:
          - balance
          - config
          - enabled
          type: object
      required:
      - drawdown
      type: object
    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
    DuplicateInvoice:
      allOf:
      - $ref: '#/components/schemas/Omit_Invoice.amount-or-bankTransferDetails_'
      - properties:
          bankTransferDetails:
            allOf:
            - $ref: '#/components/schemas/BankTransferDetails'
            nullable: true
          amount:
            allOf:
            - $ref: '#/components/schemas/Money'
            nullable: true
        required:
        - bankTransferDetails
        - amount
        type: object
      description: Degraded invoice returned when full details are unavailable (e.g. Stripe fetch failed)
    InvoiceStatus:
      type: string
      enum:
      - draft
      - open
      - paid
      - uncollectible
      - void
      - unknown
    FieldErrors:
      properties: {}
      type: object
      additionalProperties:
        properties:
          value: {}
          message:
            type: string
        required:
        - message
        type: object
    Money:
      properties:
        currencyCode:
          type: string
          example: USD
        amountSubunits:
          type: integer
          format: int32
          example: 1500
      required:
      - currencyCode
      - amountSubunits
      type: object
    SetupDrawdownParams:
      properties:
        chargeAutomatically:
          type: boolean
          description: 'Whether to automatically charge the invoice when created.

            Defaults to true if not specified.'
          example: true
        minBalanceSubunits:
          type: integer
          format: int32
          description: 'Minimum balance threshold in smallest currency unit (e.g. cents).

            A top-up is triggered when balance falls below this value.'
          example: 200000
          minimum: 10
        targetBalanceSubunits:
          type: integer
          format: int32
          description: 'Target balance in smallest currency unit (e.g. cents). When balance

            drops below minBalanceSubunits, a top-up invoice is created to

            replenish to this amount.'
          example: 1000000
          minimum: 100
      required:
      - minBalanceSubunits
      - targetBalanceSubunits
      type: object
    BalanceResponse:
      properties:
        drawdownEnabled:
          type: boolean
        balance:
          $ref: '#/components/schemas/Money'
      required:
      - drawdownEnabled
      - balance
      type: object
    TransactionsResponse:
      properties:
        pageInfo:
          properties:
            startCursor:
              type: string
              example: cbtxn_abc123
            endCursor:
              type: string
              example: cbtxn_xyz789
            hasPreviousPage:
              type: boolean
            hasNextPage:
              type: boolean
          required:
          - hasPreviousPage
          - hasNextPage
          type: object
        data:
          items:
            $ref: '#/components/schemas/TransactionResponse'
          type: array
      required:
      - pageInfo
      - data
      type: object
    Record_string.string_:
      properties: {}
      additionalProperties:
        type: string
      type: object
      description: Construct a type with a set of properties K of type T
    BankTransferDetails:
      description: Vendor-agnostic bank transfer details for push-based payment
      properties:
        routingNumber:
          type: string
        accountNumber:
          type: string
        bankName:
          type: string
        accountHolderName:
          type: string
      required:
      - routingNumber
      - accountNumber
      - bankName
      - accountHolderName
      type: object
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Rye API key