Benji Pays Plans API

openapi: 3.2.0
info:
  title: Benji Pays Partner Plans API
  description: 'The Benji Pays Partner API is a JSON over HTTPS API. All endpoints live under `/v2`. Errors follow RFC 7807 and are served as `application/problem+json`. This overview describes the cross-cutting behavior shared by every partner endpoint. Endpoint-specific schemas live with each operation. ## Authentication


    Partner endpoints authenticate with an Auth0 M2M access token in the `Authorization` header:


    ```

    Authorization: Bearer

    ```


    Tokens are obtained from Auth0 with the OAuth 2.0 client-credentials grant against the `https://api.benjipays.com` audience. The token''s actor claim (`distributor`, `partner`, or `organization`) and OAuth scopes determine which routes the caller can reach. Failures return `401 Unauthorized` (missing/expired/invalid credentials) or `403 Forbidden` (wrong actor type or missing scope). ## Request and Correlation IDs


    Two header pairs help with tracing:


    | Header | Direction | Purpose |

    | --- | --- | --- |

    | `X-Request-ID` | request (optional) / response (always) | Unique identifier for one request. Generated as a UUID v4 when the client omits it. |

    | `X-Correlation-ID` | request (optional) / response (always) | Identifier that flows across service boundaries for distributed tracing. Generated as a UUID v4 when omitted. |


    Both IDs are echoed on success and included as `requestId` / `correlationId` extensions on `application/problem+json` error responses. These headers are auto-injected on every operation in this spec — do not redeclare them per route. ## Idempotency


    POST, PATCH, and PUT endpoints accept an `Idempotency-Key` header to make retries safe. - Format: 1–255 characters, alphanumeric only (`[a-zA-Z0-9]+`). - Scope: keys are scoped per actor (no cross-tenant collisions). - Cache: the first response for a given key is cached for 24 hours. - Replay: a duplicate request with the same key and the same body returns the cached response with `X-Idempotency-Replayed: true` only after credentials were resolved by the global authenticate middleware (API key or Auth0 JWT signature check) before the idempotency cache lookup. - Conflict: same key with a different body returns `409 Conflict`. - In-flight: a second request with the same key while the first is still being processed returns `429 Too Many Requests` with `Retry-After` and problem `type` `https://api.benjipays.com/problems/idempotency-processing` (distinct from rate-limit `…/rate-limit-exceeded`). `Idempotency-Key` is auto-injected on every POST/PATCH/PUT operation in this spec — do not redeclare it per route. Routes that intentionally opt out set `x-bp-skip-idempotency: true`. The middleware fails open: if the cache layer is unavailable the request proceeds without idempotency protection. ## Pagination


    List endpoints use offset-based pagination with two query parameters:


    | Parameter | Type | Default | Bounds |

    | --- | --- | --- | --- |

    | `limit` | integer | `20` | `1`–`1000` |

    | `offset` | integer | `0` | `≥ 0` |


    Some endpoints use different bounds (for example usage/billing and autoprocessing forecast). Check the per-operation schema. Responses follow this envelope:


    ```json

    {

    "data": [ /* items */ ],

    "pagination": {

    "limit": 20,

    "offset": 0,

    "hasMore": true,

    "nextOffset": 20,

    "prevOffset": null

    }

    }

    ```


    Many list endpoints also include `pagination.total` (count of matching items across all pages). Per-operation response schemas are authoritative. Use `hasMore` to decide whether to fetch another page and `nextOffset` for the next request rather than computing it on the client. ## Dates and Times


    All **response** timestamps are ISO-8601 strings in UTC (for example `2024-01-01T12:00:00.000Z`). Date-range **query** parameters support two input modes where the endpoint accepts them:


    | Input format | Interpretation |

    | --- | --- |

    | `YYYY-MM-DD` (calendar day) | Full day in **UTC**. Start = `00:00:00.000Z`, end = `23:59:59.999Z` on that date. Same start and end day returns the full UTC day. |

    | ISO-8601 UTC timestamp (e.g.'
  version: 2.0.0
  contact:
    name: Benji Pays API Support
    email: benji@benjipays.com
servers:
- url: https://api.benjipays.com
  description: Development server
security:
- BearerAuth: []
tags:
- name: Plans
  description: Billing plan management for distributors
paths:
  /v2/plans:
    get:
      summary: List plans for authenticated distributor
      description: '**Access:** Requires DISTRIBUTOR actor type


        Returns a paginated list of plans visible to the authenticated distributor. Plans can be filtered by status and partnerId (for custom-priced plans).


        **Visibility:**

        - Distributors see plans with their distributorExternalId

        - Can optionally filter by partnerId for partner-specific custom pricing


        Requires JWT authentication and ''partners:plans:read'' scope.'
      tags:
      - Plans
      security:
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/RequestIdHeader'
      - $ref: '#/components/parameters/CorrelationIdHeader'
      - in: query
        name: partnerId
        schema:
          description: Optional filter for Partner-specific custom-priced plans
          example: 507f1f77bcf86cd799439012
          type: string
          maxLength: 255
        description: Optional filter for Partner-specific custom-priced plans
      - in: query
        name: status
        schema:
          description: Optional filter by plan status
          example: active
          type: string
          enum:
          - active
          - deprecated
        description: Optional filter by plan status
      - in: query
        name: limit
        schema:
          description: 'Number of results per page (default: 20, max: 100)'
          example: 20
          type: integer
          minimum: 1
          maximum: 100
        description: 'Number of results per page (default: 20, max: 100)'
      - in: query
        name: offset
        schema:
          description: 'Number of results to skip for pagination (default: 0)'
          example: 0
          type: integer
          minimum: 0
          maximum: 9007199254740991
        description: 'Number of results to skip for pagination (default: 0)'
      responses:
        '200':
          description: Successful response with paginated list of plans
          content:
            application/json:
              example:
                data:
                - id: 507f1f77bcf86cd799439011
                  distributorExternalId: sherweb
                  name: pro
                  basePrice: 29.99
                  baseAnnualPrice: 299.99
                  priceRanges:
                  - from: 0
                    to: 100
                    rate: 0.25
                  - from: 101
                    to: 500
                    rate: 0.2
                  includedTransactions: 100
                  additionalInvoicePrice: 0.25
                  description: Professional plan
                  planType: pro
                  status: active
                pagination:
                  hasMore: false
                  nextOffset: null
                  prevOffset: null
                  limit: 20
                  offset: 0
              schema:
                $ref: '#/components/schemas/ListPlansResponse'
        '401':
          description: Unauthorized - Invalid or missing authentication token
          content:
            application/problem+json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    description: Problem type URI
                    example: https://api.benjipays.com/problems/not-found
                  title:
                    type: string
                    description: Error title
                    example: Not Found
                  status:
                    type: number
                    description: HTTP status code
                    example: 404
                  detail:
                    type: string
                    description: Error detail message
                    example: Plan not found or not visible to this distributor
                  instance:
                    description: Instance URI
                    example: /v2/plans/507f1f77bcf86cd799439011
                    type: string
                required:
                - type
                - title
                - status
                - detail
                additionalProperties: false
                description: Error response (RFC 7807 Problem Details)
                example:
                  type: https://api.benjipays.com/problems/unauthorized
                  title: Unauthorized
                  status: 401
                  detail: Invalid or missing authentication token
                  instance: /v2/plans
        '403':
          description: Forbidden - Distributor actor type required
          content:
            application/problem+json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    description: Problem type URI
                    example: https://api.benjipays.com/problems/not-found
                  title:
                    type: string
                    description: Error title
                    example: Not Found
                  status:
                    type: number
                    description: HTTP status code
                    example: 404
                  detail:
                    type: string
                    description: Error detail message
                    example: Plan not found or not visible to this distributor
                  instance:
                    description: Instance URI
                    example: /v2/plans/507f1f77bcf86cd799439011
                    type: string
                required:
                - type
                - title
                - status
                - detail
                additionalProperties: false
                description: Error response (RFC 7807 Problem Details)
                example:
                  type: https://api.benjipays.com/problems/forbidden
                  title: Forbidden
                  status: 403
                  detail: Access requires distributor tier
                  instance: /v2/plans
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/problem+json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    description: Problem type URI
                    example: https://api.benjipays.com/problems/not-found
                  title:
                    type: string
                    description: Error title
                    example: Not Found
                  status:
                    type: number
                    description: HTTP status code
                    example: 404
                  detail:
                    type: string
                    description: Error detail message
                    example: Plan not found or not visible to this distributor
                  instance:
                    description: Instance URI
                    example: /v2/plans/507f1f77bcf86cd799439011
                    type: string
                required:
                - type
                - title
                - status
                - detail
                additionalProperties: false
                description: Error response (RFC 7807 Problem Details)
                example:
                  type: https://api.benjipays.com/problems/rate-limit-exceeded
                  title: Too Many Requests
                  status: 429
                  detail: Rate limit exceeded. Please retry after the specified time.
                  instance: /v2/plans
                  retryAfterSeconds: 1
                  limit: 5
      operationId: getV2Plans
      x-operation-id-source: derived
  /v2/plans/{planId}:
    get:
      summary: Get a single plan by ID
      description: '**Access:** Requires DISTRIBUTOR actor type


        Returns details for a specific plan by its MongoDB ObjectId. The plan must be visible to the authenticated distributor.


        **Visibility:**

        - Returns 404 if plan doesn''t exist or doesn''t belong to the distributor (prevents enumeration)


        Requires JWT authentication and ''partners:plans:read'' scope.'
      tags:
      - Plans
      security:
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/RequestIdHeader'
      - $ref: '#/components/parameters/CorrelationIdHeader'
      - in: path
        name: planId
        schema:
          type: string
          pattern: ^[0-9a-fA-F]{24}$
          description: MongoDB ObjectId of the plan
          example: 507f1f77bcf86cd799439011
        required: true
        description: MongoDB ObjectId of the plan
      responses:
        '200':
          description: Successful response with plan details
          content:
            application/json:
              example:
                data:
                  id: 507f1f77bcf86cd799439011
                  distributorExternalId: sherweb
                  name: pro
                  basePrice: 29.99
                  baseAnnualPrice: 299.99
                  priceRanges:
                  - from: 0
                    to: 100
                    rate: 0.25
                  - from: 101
                    to: 500
                    rate: 0.2
                  includedTransactions: 100
                  additionalInvoicePrice: 0.25
                  description: Professional plan
                  planType: pro
                  status: active
              schema:
                $ref: '#/components/schemas/GetPlanResponse'
        '401':
          description: Unauthorized - Invalid or missing authentication token
          content:
            application/problem+json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    description: Problem type URI
                    example: https://api.benjipays.com/problems/not-found
                  title:
                    type: string
                    description: Error title
                    example: Not Found
                  status:
                    type: number
                    description: HTTP status code
                    example: 404
                  detail:
                    type: string
                    description: Error detail message
                    example: Plan not found or not visible to this distributor
                  instance:
                    description: Instance URI
                    example: /v2/plans/507f1f77bcf86cd799439011
                    type: string
                required:
                - type
                - title
                - status
                - detail
                additionalProperties: false
                description: Error response (RFC 7807 Problem Details)
                example:
                  type: https://api.benjipays.com/problems/unauthorized
                  title: Unauthorized
                  status: 401
                  detail: Invalid or missing authentication token
                  instance: /v2/plans
        '403':
          description: Forbidden - Distributor actor type required
          content:
            application/problem+json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    description: Problem type URI
                    example: https://api.benjipays.com/problems/not-found
                  title:
                    type: string
                    description: Error title
                    example: Not Found
                  status:
                    type: number
                    description: HTTP status code
                    example: 404
                  detail:
                    type: string
                    description: Error detail message
                    example: Plan not found or not visible to this distributor
                  instance:
                    description: Instance URI
                    example: /v2/plans/507f1f77bcf86cd799439011
                    type: string
                required:
                - type
                - title
                - status
                - detail
                additionalProperties: false
                description: Error response (RFC 7807 Problem Details)
                example:
                  type: https://api.benjipays.com/problems/forbidden
                  title: Forbidden
                  status: 403
                  detail: Access requires distributor tier
                  instance: /v2/plans
        '404':
          description: Not Found - Plan not found or not visible to distributor
          content:
            application/problem+json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    description: Problem type URI
                    example: https://api.benjipays.com/problems/not-found
                  title:
                    type: string
                    description: Error title
                    example: Not Found
                  status:
                    type: number
                    description: HTTP status code
                    example: 404
                  detail:
                    type: string
                    description: Error detail message
                    example: Plan not found or not visible to this distributor
                  instance:
                    description: Instance URI
                    example: /v2/plans/507f1f77bcf86cd799439011
                    type: string
                required:
                - type
                - title
                - status
                - detail
                additionalProperties: false
                description: Error response (RFC 7807 Problem Details)
                example:
                  type: https://api.benjipays.com/problems/not-found
                  title: Not Found
                  status: 404
                  detail: Plan not found or not visible to this distributor
                  instance: /v2/plans/507f1f77bcf86cd799439011
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/problem+json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    description: Problem type URI
                    example: https://api.benjipays.com/problems/not-found
                  title:
                    type: string
                    description: Error title
                    example: Not Found
                  status:
                    type: number
                    description: HTTP status code
                    example: 404
                  detail:
                    type: string
                    description: Error detail message
                    example: Plan not found or not visible to this distributor
                  instance:
                    description: Instance URI
                    example: /v2/plans/507f1f77bcf86cd799439011
                    type: string
                required:
                - type
                - title
                - status
                - detail
                additionalProperties: false
                description: Error response (RFC 7807 Problem Details)
                example:
                  type: https://api.benjipays.com/problems/rate-limit-exceeded
                  title: Too Many Requests
                  status: 429
                  detail: Rate limit exceeded. Please retry after the specified time.
                  instance: /v2/plans
                  retryAfterSeconds: 1
                  limit: 5
      operationId: getV2PlansByPlanId
      x-operation-id-source: derived
components:
  schemas:
    Plan:
      type: object
      properties:
        id:
          type: string
          description: Plan identifier (same value as path `planId`)
          example: 507f1f77bcf86cd799439011
        distributorExternalId:
          description: Distributor external ID this plan is visible to
          example: sherweb
          type: string
        partnerId:
          description: Partner ID for partner-specific custom pricing
          example: 507f1f77bcf86cd799439012
          type: string
        name:
          type: string
          description: Plan name
          example: pro
        basePrice:
          type: number
          description: Base monthly price
          example: 29.99
        baseAnnualPrice:
          description: Base annual price (discounted)
          example: 299.99
          type: number
        priceRanges:
          type: array
          items:
            type: object
            properties:
              from:
                type: number
                description: Starting transaction count for this tier
                example: 0
              to:
                type: number
                description: Ending transaction count for this tier
                example: 100
              rate:
                type: number
                description: Rate per transaction in this tier
                example: 0.25
            required:
            - from
            - to
            - rate
            additionalProperties: false
            description: Price range for tiered pricing
          description: Tiered pricing ranges
        includedTransactions:
          type: number
          description: Number of transactions included in base price
          example: 100
        additionalInvoicePrice:
          description: Price per additional invoice beyond included
          example: 0.25
          type: number
        description:
          description: Plan description
          example: Professional plan with advanced features
          type: string
        planType:
          description: Plan type identifier
          example: pro
          type: string
        status:
          description: Plan status
          example: active
          type: string
          enum:
          - active
          - deprecated
      required:
      - id
      - name
      - basePrice
      - priceRanges
      - includedTransactions
      additionalProperties: false
      description: Plan details
    GetPlanResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Plan'
      required:
      - data
      additionalProperties: false
      description: Single plan details
    ListPlansResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Plan'
          description: Array of plans
        pagination:
          type: object
          properties:
            hasMore:
              type: boolean
              description: Whether more results are available
              example: false
            nextOffset:
              anyOf:
              - type: number
              - type: 'null'
              description: Offset for next page (null if no more pages)
              example: null
            prevOffset:
              anyOf:
              - type: number
              - type: 'null'
              description: Offset for previous page (null if first page)
              example: null
            limit:
              type: number
              description: Maximum number of results per page
              example: 20
            offset:
              type: number
              description: Number of results skipped
              example: 0
          required:
          - hasMore
          - nextOffset
          - prevOffset
          - limit
          - offset
          additionalProperties: false
          description: Pagination metadata
      required:
      - data
      - pagination
      additionalProperties: false
      description: Paginated list of plans
  parameters:
    RequestIdHeader:
      name: X-Request-ID
      in: header
      required: false
      description: Optional client-supplied unique ID for one request. The server generates a UUID v4 if omitted and always echoes the value in the response.
      schema:
        type: string
        format: uuid
    CorrelationIdHeader:
      name: X-Correlation-ID
      in: header
      required: false
      description: Optional ID that flows across service boundaries for distributed tracing. The server generates a UUID v4 if omitted and always echoes the value in the response.
      schema:
        type: string
        format: uuid
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Auth0 JWT token obtained via OAuth2 client credentials flow. Include the token in the Authorization header as: Bearer <token>'
x-speakeasy-retries:
  strategy: backoff
  backoff:
    initialInterval: 500
    maxInterval: 60000
    maxElapsedTime: 3600000
    exponent: 1.5
  statusCodes:
  - 5XX
  retryConnectionErrors: true
x-provenance:
  method: searched
  source: https://developer.benjipays.com/reference
  harvested: '2026-11-02'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://developer.benjipays.com/reference/get_v2-billing.md
  - https://developer.benjipays.com/reference/get_v2-organizations-organizationid.md
  - https://developer.benjipays.com/reference/get_v2-organizations.md
  - https://developer.benjipays.com/reference/get_v2-partners-partnerid.md
  - https://developer.benjipays.com/reference/get_v2-partners.md
  - https://developer.benjipays.com/reference/get_v2-plans-planid.md
  - https://developer.benjipays.com/reference/get_v2-plans.md
  - https://developer.benjipays.com/reference/get_v2-usage.md
  - https://developer.benjipays.com/reference/get_v2-whoami.md
  - https://developer.benjipays.com/reference/patch_v2-organizations-organizationid-plan.md
  - https://developer.benjipays.com/reference/post_v2-organizations-organizationid-activate.md
  - https://developer.benjipays.com/reference/post_v2-organizations-organizationid-close.md
  - https://developer.benjipays.com/reference/post_v2-organizations-organizationid-resend-invite.md
  - https://developer.benjipays.com/reference/post_v2-organizations-organizationid-suspend.md
  - https://developer.benjipays.com/reference/post_v2-organizations.md
  - https://developer.benjipays.com/reference/post_v2-partners.md
  - https://developer.benjipays.com/reference/post_v2-whoami-echo.md
  merge:
    pages: 17
    deduped: 61
    conflicts_kept_first: 0