> ## Documentation Index
> Fetch the complete documentation index at: https://docs.piriod.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve customer



## OpenAPI

````yaml GET /customers/{id}/
openapi: 3.0.3
info:
  title: Piriod API
  version: 1.0.0
  description: >
    Piriod API for billing, payments, procurement and collections.


    All requests require:

    - `Authorization: Token <api_token>` header.

    - `x-simple-workspace: <workspace_id>` header (the account/workspace
    identifier).

    - Optionally `x-piriod-test-mode: true` to operate against test-mode data.


    See the Documentation tab for getting started, integration flows,
    authentication,

    error handling and pagination/filtering guides.
servers:
  - url: https://api.piriod.com
    description: Production
security:
  - TokenAuth: []
paths:
  /customers/{id}/:
    parameters:
      - $ref: '#/components/parameters/IdPath'
      - $ref: '#/components/parameters/WorkspaceHeader'
      - $ref: '#/components/parameters/TestModeHeader'
    get:
      tags:
        - Billing
      summary: Retrieve customer
      responses:
        '200':
          description: The customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    IdPath:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: Resource identifier.
    WorkspaceHeader:
      name: x-simple-workspace
      in: header
      required: true
      schema:
        type: string
      description: Workspace (account) identifier. Required for every request.
      example: acc_01H8XYZ123ABC
    TestModeHeader:
      name: x-piriod-test-mode
      in: header
      required: false
      schema:
        type: boolean
        default: false
      description: Whether to operate against test-mode data. Defaults to `false`.
  schemas:
    Customer:
      type: object
      properties:
        id:
          type: string
          readOnly: true
          example: cus_01H8XYZ123ABC
        name:
          type: string
          maxLength: 100
        address:
          type: string
          maxLength: 64
        country:
          $ref: '#/components/schemas/Country'
        state:
          $ref: '#/components/schemas/State'
        currency:
          type: string
          description: ISO currency code (e.g. CLP, USD).
          example: CLP
        email:
          type: string
          format: email
          nullable: true
        phone:
          type: string
          nullable: true
          maxLength: 16
        website:
          type: string
          format: uri
          nullable: true
        zip_code:
          type: string
          nullable: true
          maxLength: 16
        manager:
          type: string
          nullable: true
          maxLength: 64
          description: Account manager name (free text).
        reference:
          type: string
          nullable: true
          maxLength: 64
          description: External reference for the customer.
        tax_id:
          type: string
          nullable: true
          maxLength: 32
          description: >
            Tax identifier. Required when the customer's country has tax
            regulation

            (e.g. Chile RUT, Mexico RFC, Colombia NIT) and matches the account's
            country.
        tax_settings:
          type: object
          description: >
            Country-specific tax configuration. Schema and required keys depend
            on the

            tax agency of the customer's country.
        metadata:
          type: object
          description: Arbitrary key/value metadata. Filterable via `?metadata__key=value`.
        send_invoices:
          type: boolean
          default: true
          description: Whether to email invoices to the customer.
        send_collections:
          type: boolean
          default: true
          description: Whether to email collection reminders to the customer.
        send_vouchers:
          type: boolean
          default: true
          description: Whether to email payment receipts to the customer.
        status:
          type: string
          enum:
            - active
            - archived
            - pending
          default: active
        contacts:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/Contact'
        sources:
          type: array
          readOnly: true
          items:
            type: string
          description: IDs of reusable payment sources currently chargeable or pending.
        aggregations:
          allOf:
            - $ref: '#/components/schemas/Aggregations'
          readOnly: true
        test_mode:
          type: boolean
          readOnly: true
        created:
          type: string
          format: date-time
          readOnly: true
        updated:
          type: string
          format: date-time
          readOnly: true
      required:
        - name
        - address
        - country
        - state
    Country:
      type: object
      properties:
        id:
          type: string
          example: CL
        name:
          type: string
          example: Chile
        code:
          type: string
          example: '+56'
        has_regulation:
          type: boolean
        currencies:
          type: array
          items:
            type: string
            example: CLP
    State:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        country:
          type: string
          example: CL
    Contact:
      type: object
      properties:
        id:
          type: string
          readOnly: true
          example: con_01H8XYZ123ABC
        customer:
          type: string
          nullable: true
          description: Customer ID this contact belongs to.
        orgunit:
          type: string
          nullable: true
          description: Organisation unit ID. Optional sub-grouping inside a customer.
        name:
          type: string
          maxLength: 64
        email:
          type: string
          format: email
        phone:
          type: string
          maxLength: 12
          nullable: true
        invoicing:
          type: boolean
          default: true
          description: Whether this contact receives invoice emails.
        collections:
          type: boolean
          default: true
          description: Whether this contact receives collection reminders.
        created:
          type: string
          format: date-time
          readOnly: true
        updated:
          type: string
          format: date-time
          readOnly: true
      required:
        - name
        - email
    Aggregations:
      type: object
      properties:
        sales:
          type: number
          format: decimal
          description: Total finalized + paid sales for the customer.
        sales_current_period:
          type: number
          format: decimal
          description: Sales finalized within the current calendar month.
        balance:
          type: number
          format: decimal
          description: >-
            Outstanding balance across non-succeeded payments on
            finalized/pending invoices.
    Error:
      type: object
      properties:
        detail:
          type: string
          description: Human-readable error message.
      example:
        detail: Authentication credentials were not provided.
  responses:
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    TokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: |
        Use header `Authorization: Token <api_token>`.
        API tokens are obtained from the Piriod dashboard.

````