pricklymails-com Billing API

openapi: 3.2.0
info:
  title: Pricklymails Com Billing API
  version: 0.9.0
  contact:
    email: support@pricklymails.com
  license:
    name: Proprietary
  description: 'Operations tagged billing across 2 of this provider''s published API definitions: pricklymails-com-openapi.json, pricklymails-com-openapi.yaml. Each path carries the servers of the definition it was published in.'
tags:
- name: Billing
  description: Checkout and billing portal sessions.
paths:
  /api/billing/checkout:
    post:
      tags:
      - Billing
      summary: Creates a checkout session for a plan or a token top-up
      description: Creates a hosted checkout session for a plan subscription or a token top-up and returns the URL to redirect the buyer to. The terms are accepted on the hosted page, in the language given by `locale`. Returns `503 Service Unavailable` when billing is not available. Returns `400 Bad Request` when the plan code, billing cycle, top-up quantity, or locale is invalid. Returns `409 Conflict` when the account already has an active paid subscription.
      operationId: create_checkout_session
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCheckoutRequest'
        required: true
      responses:
        '200':
          description: Hosted checkout redirect URL.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutSessionResponse'
        '400':
          description: Unrecognized plan code, billing cycle, top-up quantity, or locale.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '401':
          description: Missing or invalid JWT.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '409':
          description: Caller already has an active paid subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '503':
          description: Billing is not available.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
      security:
      - jwt: []
  /api/billing/portal:
    post:
      tags:
      - Billing
      summary: Creates a billing portal session
      description: Creates a hosted billing portal session, where the caller manages the subscription and payment details, and returns the URL to redirect to. Returns `503 Service Unavailable` when billing is not available. Returns `404 Not Found` when the caller has no billing account.
      operationId: create_billing_portal_session
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePortalRequest'
        required: true
      responses:
        '200':
          description: Hosted billing portal redirect URL.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalSessionResponse'
        '401':
          description: Missing or invalid JWT.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '404':
          description: Caller has no billing account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '503':
          description: Billing is not available.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
      security:
      - jwt: []
components:
  schemas:
    ApiErrorBody:
      type: object
      description: 'Error envelope returned with every non-success status: `{ "error": { "code", "message" } }`.'
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ApiErrorDetail'
          description: Error detail.
    CheckoutTargetRequest:
      oneOf:
      - type: object
        description: Subscribe to a plan.
        required:
        - plan
        - cycle
        - type
        properties:
          cycle:
            type: string
            description: Billing cycle (`"monthly"` or `"yearly"`).
          plan:
            type: string
            description: Plan code (e.g. `"starter"`, `"pro"`, `"business"`, `"enterprise"`).
          type:
            type: string
            enum:
            - plan
      - type: object
        description: One-time credit top-up.
        required:
        - token_quantity
        - type
        properties:
          token_quantity:
            type: integer
            format: int32
            description: 'Number of tokens to purchase.

              Must be a multiple of the top-up step, between the minimum and maximum quantities (inclusive).

              `GET /api/config` returns these values as `topup.step_tokens`, `topup.min_tokens` and `topup.max_tokens`.'
            minimum: 0
          type:
            type: string
            enum:
            - top_up
      description: Checkout target from the request body.
    CheckoutSessionResponse:
      type: object
      description: JSON response body for `POST /api/billing/checkout`.
      required:
      - url
      properties:
        url:
          type: string
          description: Hosted checkout URL to redirect the user to.
    CreatePortalRequest:
      type: object
      description: Request body for `POST /api/billing/portal`.
      required:
      - return_url
      properties:
        return_url:
          type: string
          description: URL the user is redirected to when they leave the billing portal.
    CreateCheckoutRequest:
      type: object
      description: Request body for `POST /api/billing/checkout`.
      required:
      - target
      - success_url
      - cancel_url
      properties:
        cancel_url:
          type: string
          description: URL the buyer is redirected to when they cancel the checkout.
        locale:
          type:
          - string
          - 'null'
          description: 'Language of the hosted checkout page and of the terms the buyer accepts there (`"en"` or `"fr"`).

            English when absent.'
        success_url:
          type: string
          description: URL the buyer is redirected to after a successful payment.
        target:
          $ref: '#/components/schemas/CheckoutTargetRequest'
          description: 'What to check out: a plan subscription or a credit top-up.'
    PortalSessionResponse:
      type: object
      description: JSON response body for `POST /api/billing/portal`.
      required:
      - url
      properties:
        url:
          type: string
          description: Hosted billing portal URL to redirect the user to.
    ApiErrorDetail:
      type: object
      description: Detail of an error response.
      required:
      - code
      properties:
        code:
          type: string
          description: Stable key identifying the error (for example `"verify.invalid_uuid"`). Clients localize by this key.
        message:
          type:
          - string
          - 'null'
          description: 'Present on most error kinds and equal to `code`; the API returns no localized text.

            Absent for error kinds that carry no extra detail.'
  securitySchemes:
    bearer_api_key:
      type: http
      scheme: bearer
      description: A `pm_live_*` or `pm_test_*` API key.
    jwt:
      type: http
      scheme: bearer
      description: A short-lived token from `/api/auth/login`, or `/oauth/token` for an agent.
x-refined-from:
- pricklymails-com-openapi.json
- pricklymails-com-openapi.yaml