openapi: 3.0.1
info:
  title: Paddle Addresses Businesses API
  description: Paddle Billing API for subscription and recurring revenue management. As a merchant of record, Paddle manages products, prices, customers, addresses, businesses, subscriptions, transactions, invoices, adjustments, discounts, reports, and webhook notifications while handling global sales tax, payment processing, fraud, and compliance on the seller's behalf. This is a curated OpenAPI description of the public REST endpoints; Paddle publishes the canonical OpenAPI at https://github.com/PaddleHQ/paddle-openapi.
  termsOfService: https://www.paddle.com/legal/terms
  contact:
    name: Paddle Support
    url: https://www.paddle.com/support
  version: '1.0'
servers:
- url: https://api.paddle.com
  description: Production
- url: https://sandbox-api.paddle.com
  description: Sandbox
security:
- bearerAuth: []
tags:
- name: Businesses
paths:
  /customers/{customer_id}/businesses:
    parameters:
    - $ref: '#/components/parameters/customerId'
    get:
      operationId: list-businesses
      tags:
      - Businesses
      summary: List businesses for a customer
      responses:
        '200':
          description: Returns a paginated list of businesses.
          content:
            application/json:
              schema:
                type: object
    post:
      operationId: create-business
      tags:
      - Businesses
      summary: Create a business for a customer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Business'
      responses:
        '201':
          description: Returns the created business.
          content:
            application/json:
              schema:
                type: object
  /customers/{customer_id}/businesses/{business_id}:
    parameters:
    - $ref: '#/components/parameters/customerId'
    - $ref: '#/components/parameters/businessId'
    get:
      operationId: get-business
      tags:
      - Businesses
      summary: Get a business for a customer
      responses:
        '200':
          description: Returns a business.
          content:
            application/json:
              schema:
                type: object
    patch:
      operationId: update-business
      tags:
      - Businesses
      summary: Update a business for a customer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Business'
      responses:
        '200':
          description: Returns the updated business.
          content:
            application/json:
              schema:
                type: object
components:
  parameters:
    customerId:
      name: customer_id
      in: path
      required: true
      schema:
        type: string
    businessId:
      name: business_id
      in: path
      required: true
      schema:
        type: string
  schemas:
    Business:
      type: object
      required:
      - name
      properties:
        name:
          type: string
        company_number:
          type: string
          nullable: true
        tax_identifier:
          type: string
          nullable: true
        contacts:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              email:
                type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Authenticate with your Paddle API key passed in the Authorization header with the Bearer prefix, e.g. `Authorization: Bearer pdl_live_apikey_...`.'