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

# Create a barber service

> The service is added to the catalog for this barber's sole or primary joined location and assigned to this barber.



## OpenAPI

````yaml /api-reference/Services/openapi.yaml post /barbers/{barberId}/catalogServices
openapi: 3.0.0
info:
  title: Services
  version: 0.1.0
  contact:
    name: Guile Engineering
    url: https://www.guile.app
    email: engineering@guile.app
  license:
    name: MIT
    url: https://opensource.org/license/mit
  description: |-
    The Services API provides operations for managing services
    within the Guile platform.

    Services are created at the shop level and can be assigned to
    individual barbers within that shop.

    Services can be configured as base services, add-ons, or bundles.

    A base service is a standalone service without any additional
    included services.

    An add-on is a service that can be added to an appointment for
    an additional cost.

    A bundle is a base service that includes one or more add-ons with
    a fixed cost and duration. Add-on prices and durations are ignored
    when added to a bundle. A customer cannot remove add-ons from a
    bundle when creating an appointment.

    A bundle cannot be configured as an add-on or another bundle.
servers:
  - url: https://api.guile.app
    variables: {}
  - url: https://guile.fly.dev
    variables: {}
security: []
tags:
  - name: Services
    description: Shop catalog pricing, duration, and visibility
paths:
  /barbers/{barberId}/catalogServices:
    post:
      tags:
        - Services
      summary: Create a barber service
      description: >-
        The service is added to the catalog for this barber's sole or primary
        joined location and assigned to this barber.
      operationId: createBarberService
      parameters:
        - name: barberId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/resourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createService'
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/barberService'
        '400':
          description: >-
            Bad Request.

            The request body, request headers, and/or query parameters are not
            well-formed.



            This problem response may have one of the following `type` values:

            *
            [https://docs.guile.app/problems/badRequest](https://docs.guile.app/problems/badRequest)
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/apiProblem'
        '401':
          description: >-
            Unauthorized.

            The operation requires authentication but no authentication or
            insufficient authentication was given.



            This problem response may have one of the following `type` values:

            *
            [https://docs.guile.app/problems/unauthorized](https://docs.guile.app/problems/unauthorized)
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/apiProblem'
        '403':
          description: >-
            Forbidden.

            The authenticated caller is not authorized to perform the requested
            operation.



            This problem response may have one of the following `type` values:

            *
            [https://docs.guile.app/problems/forbidden](https://docs.guile.app/problems/forbidden)
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/apiProblem'
        '409':
          description: >-
            Conflict.

            The request conflicts with the state of the application.



            This problem response may have one of the following `type` values:

            *
            [https://docs.guile.app/problems/conflict](https://docs.guile.app/problems/conflict)

            *
            [https://docs.guile.app/problems/duplicateServiceName](https://docs.guile.app/problems/duplicateServiceName)
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/apiProblem'
        '422':
          description: >-
            Unprocessable Entity.

            The request body and/or query parameters were well-formed but
            otherwise invalid.



            This problem response may have one of the following `type` values:

            *
            [https://docs.guile.app/problems/unprocessableEntity](https://docs.guile.app/problems/unprocessableEntity)

            *
            [https://docs.guile.app/problems/ineligibleServiceDuration](https://docs.guile.app/problems/ineligibleServiceDuration)

            *
            [https://docs.guile.app/problems/bundleCannotBeConfiguredAsAddOn](https://docs.guile.app/problems/bundleCannotBeConfiguredAsAddOn)

            *
            [https://docs.guile.app/problems/serviceCatalogUnavailable](https://docs.guile.app/problems/serviceCatalogUnavailable)
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/apiProblem'
        '429':
          description: >-
            Too Many Requests.

            The client has sent too many requests in a given amount of time.



            This problem response may have one of the following `type` values:

            *
            [https://docs.guile.app/problems/tooManyRequests](https://docs.guile.app/problems/tooManyRequests)
          headers:
            Retry-After:
              required: true
              description: The number of seconds to wait before retrying the request.
              schema:
                type: integer
                format: uint32
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/apiProblem'
      security:
        - BearerAuth: []
components:
  schemas:
    resourceId:
      type: string
      description: >-
        The unique, opaque system identifier for a resource.

        This case-sensitive ID is also used as path parameters in URLs or in
        other

        properties or parameters that reference a resource by ID rather than
        URL.
    createService:
      type: object
      required:
        - name
        - visibility
        - bundledAddOns
        - categories
        - description
      properties:
        name:
          type: string
          description: The display name for this service.
          example: Skin Fade
        duration:
          type: string
          format: duration
          description: The duration of the service.
          example: PT30M
        visibility:
          allOf:
            - $ref: '#/components/schemas/visibility'
          description: |-
            The visibility of the service.
            Hidden services are not visible to customers.
        cost:
          allOf:
            - $ref: '#/components/schemas/money'
          description: The cost of the service, excluding any fees or taxes.
          example: '45.00'
        addOn:
          allOf:
            - $ref: '#/components/schemas/ServiceConfiguration'
          description: If set, the configuration for this service when used as an add-on.
        bundledAddOns:
          type: array
          items:
            $ref: '#/components/schemas/Common.ServiceReference'
          minItems: 0
          description: Additional add-on services included in this service bundle.
          example:
            - id: service-123
              name: Beard Trim
        categories:
          type: array
          items:
            $ref: '#/components/schemas/ServiceCategoryReference'
          description: The categories for this service.
          example:
            - id: afada02b-e9fe
              name: Shaving
          default: []
        description:
          type: string
          maxLength: 500
          description: The description of this service.
          example: Expertly transitioned fade with optional designs on the side.
        ageRestrictions:
          allOf:
            - $ref: '#/components/schemas/AgeRestriction'
          description: The age restrictions, if any, for this service.
      description: |2-
          Properties for creating a new service for a barber.

          A service can be configured as a base service, add-on, or bundle.
          When configured as a bundle, the service cannot be configured as
          an add-on or included in another bundle.

          Services that are not bundles and have configurations for being
          used as a base service, an add-on, or both.
    barberService:
      type: object
      required:
        - id
        - barber
        - service
        - visibility
        - availableForOffHours
        - createdAt
        - updatedAt
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/resourceId'
          description: The unique identifier for this barber service assignment.
        barber:
          allOf:
            - $ref: '#/components/schemas/Common.BarberReference'
          description: The barber this service is assigned to.
        service:
          allOf:
            - $ref: '#/components/schemas/service'
          description: The service that is assigned to the barber.
        visibility:
          allOf:
            - $ref: '#/components/schemas/visibility'
          description: |-
            The visibility of the service for this barber.
            Hidden services are not visible to customers.
        cost:
          allOf:
            - $ref: '#/components/schemas/money'
          description: >-
            The barber-specific cost override for the service, excluding any
            fees or taxes.
          example: '45.00'
        availableForOffHours:
          type: boolean
          description: >-
            Whether this service is available for off-hours bookings.

            When false, the service cannot be booked during off-hours time
            slots.
          default: false
        createdAt:
          type: string
          format: date-time
          description: |-
            The date-time when this resource was created, in
            [RFC 3339](https://tools.ietf.org/html/rfc3339) date-time
            `YYYY-MM-DDThh:mm:ss.sssZ` format, UTC. This is derived and
            immutable.
        updatedAt:
          type: string
          format: date-time
          description: |-
            The date-time when this resource was updated, in
            [RFC 3339](https://tools.ietf.org/html/rfc3339) date-time
            `YYYY-MM-DDThh:mm:ss.sssZ` format, UTC. This is derived and
            immutable.
      description: Representation of a service assigned to a barber.
    apiProblem:
      type: object
      required:
        - type
        - title
        - occurredAt
        - id
        - status
      properties:
        type:
          allOf:
            - $ref: '#/components/schemas/uri'
          description: A URI reference that identifies the problem type.
        title:
          type: string
          maxLength: 120
          description: >-
            A short, human-readable summary of the problem type. The title is
            usually the same for all

            problems with the same `type`.
        occurredAt:
          type: string
          format: date-time
          description: >-
            The date-time when this problem occurred, in [RFC
            3339](https://tools.ietf.org/html/rfc3339)

            date-time `YYYY-MM-DDThh:mm:ss.sssZ` format, UTC. This is derived
            and immutable.
        detail:
          type: string
          maxLength: 256
          description: >-
            A human-readable explanation specific to this occurrence of the
            problem.
        id:
          allOf:
            - $ref: '#/components/schemas/resourceId'
          description: >-
            The unique identifier for this problem. This is an immutable opaque
            string.
        status:
          allOf:
            - $ref: '#/components/schemas/statusCode'
          description: >-
            The [HTTP status
            code](https://datatracker.ietf.org/doc/html/rfc7231#section-6)for
            this

            occurrence of the problem.
        instance:
          allOf:
            - $ref: '#/components/schemas/uri'
          maxLength: 2048
          description: >-
            A URI reference that identifies the specific occurrence of the
            problem. This is the URI of an

            API resource that the problem is related to, with a unique error
            correlation ID URI fragment.
        attributes:
          type: object
          additionalProperties: {}
          description: >-
            Additional optional attributes related to the problem. This data
            conforms to the schema

            associated with the error type.
        recovery:
          allOf:
            - $ref: '#/components/schemas/clientFailureRecovery'
          description: The recovery contract for this problem occurrence.
        problems:
          type: array
          items:
            $ref: '#/components/schemas/problem'
          maxItems: 128
          description: |-
            Optional root-causes if there are multiple problems in the request
            or API call processing.
      description: >-
        API problem or error response, as per

        [RFC 9457
        application/problem+json](https://tools.ietf.org/html/rfc9457).
    visibility:
      type: string
      enum:
        - visible
        - hidden
      description: The visibility of a resource.
    money:
      type: string
      pattern: ^-?(0|[1-9][0-9]*)\.[0-9][0-9]$
      format: decimal
      description: >-
        A monetary amount in the lowest denomination for the given currency.

        The numeric value is represented as a string so that it can be exact
        with no

        loss of precision. Values may be positive or negative.
      example: '456.78'
    ServiceConfiguration:
      type: object
      required:
        - duration
        - cost
      properties:
        duration:
          type: string
          format: duration
          description: The duration of the service.
          example: PT30M
        cost:
          allOf:
            - $ref: '#/components/schemas/money'
          description: The cost of the service, excluding any fees or taxes.
          example: '45.00'
      description: Composable fields for service configuration.
    Common.ServiceReference:
      type: object
      required:
        - id
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/resourceId'
          description: The unique identifier for the service.
        name:
          type: string
          description: The display name for this service.
        cost:
          allOf:
            - $ref: '#/components/schemas/money'
          description: The cost of the service, excluding any fees or taxes.
        duration:
          type: string
          format: duration
          description: The duration of the service.
      description: |-
        A reference to a service resource. This contains a subset of properties
        for the service. Use Service for the full resource entity.
    ServiceCategoryReference:
      type: object
      required:
        - id
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/resourceId'
          description: The unique identifier for the service category.
        name:
          type: string
          description: The name of the service category.
      description: A reference to a service category.
      example:
        id: afada02b-e9fe
        name: Shaving
    AgeRestriction:
      type: object
      properties:
        min:
          type: integer
          format: int32
          nullable: true
          description: The minimum age for this service.
          example: 18
        max:
          type: integer
          format: int32
          nullable: true
          description: The maximum age for this service.
          example: 100
      description: Age restrictions for a service.
    Common.BarberReference:
      type: object
      required:
        - id
        - givenName
        - surname
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/resourceId'
          description: The unique identifier of the barber profile.
        givenName:
          type: string
          minLength: 1
          maxLength: 55
          format: text
          description: The given name of the barber.
        surname:
          type: string
          minLength: 1
          maxLength: 55
          format: text
          description: The surname of the barber.
        preferredName:
          type: string
          maxLength: 55
          format: text
          description: The preferred name of the barber.
        biography:
          type: string
          maxLength: 2000
          format: text
          description: A short biography of the barber.
        spokenLanguages:
          type: array
          items:
            $ref: '#/components/schemas/spokenLanguageTag'
          minItems: 1
          description: Languages the barber speaks, as IETF BCP 47 language tags.
        experience:
          type: integer
          format: int32
          minimum: 0
          maximum: 100
          description: |-
            Years of professional barbering experience.

            Omitted when the barber has not set a value.
        instagram:
          type: string
          minLength: 1
          maxLength: 30
          pattern: ^[A-Za-z0-9](?:[A-Za-z0-9._]{0,28}[A-Za-z0-9])?$
          description: |-
            Public Instagram username for the booking page, without a leading @.
            Absent when unset. Not a private messaging channel.
        urlSlug:
          allOf:
            - $ref: '#/components/schemas/bookingSlug'
          description: The barber's public booking slug, used in profile links.
        profileImage_URL:
          type: string
          maxLength: 255
          format: uri
          description: A URL to the barber's profile image.
      description: |-
        A reference to a barber resource. This contains a subset of properties
        for the barber. Use Barber for the full resource entity.
    service:
      type: object
      required:
        - name
        - visibility
        - bundledAddOns
        - categories
        - description
        - id
        - createdAt
        - updatedAt
      properties:
        name:
          type: string
          description: The display name for this service.
          example: Skin Fade
        duration:
          type: string
          format: duration
          description: The duration of the service.
          example: PT30M
        visibility:
          allOf:
            - $ref: '#/components/schemas/visibility'
          description: |-
            The visibility of the service.
            Hidden services are not visible to customers.
        cost:
          allOf:
            - $ref: '#/components/schemas/money'
          description: The cost of the service, excluding any fees or taxes.
          example: '45.00'
        addOn:
          allOf:
            - $ref: '#/components/schemas/ServiceConfiguration'
          description: If set, the configuration for this service when used as an add-on.
        bundledAddOns:
          type: array
          items:
            $ref: '#/components/schemas/Common.ServiceReference'
          minItems: 0
          description: Additional add-on services included in this service bundle.
          example:
            - id: service-123
              name: Beard Trim
        categories:
          type: array
          items:
            $ref: '#/components/schemas/ServiceCategoryReference'
          description: The categories for this service.
          example:
            - id: afada02b-e9fe
              name: Shaving
          default: []
        description:
          type: string
          maxLength: 500
          description: The description of this service.
          example: Expertly transitioned fade with optional designs on the side.
        ageRestrictions:
          allOf:
            - $ref: '#/components/schemas/AgeRestriction'
          description: The age restrictions, if any, for this service.
        id:
          allOf:
            - $ref: '#/components/schemas/resourceId'
          description: The unique identifier for this service.
        createdAt:
          type: string
          format: date-time
          description: |-
            The date-time when this resource was created, in
            [RFC 3339](https://tools.ietf.org/html/rfc3339) date-time
            `YYYY-MM-DDThh:mm:ss.sssZ` format, UTC. This is derived and
            immutable.
        updatedAt:
          type: string
          format: date-time
          description: |-
            The date-time when this resource was updated, in
            [RFC 3339](https://tools.ietf.org/html/rfc3339) date-time
            `YYYY-MM-DDThh:mm:ss.sssZ` format, UTC. This is derived and
            immutable.
      description: Representation of a service performed by a barber.
    uri:
      type: string
      maxLength: 1024
      format: uri
      description: A URI reference to an internal or external resource.
    statusCode:
      type: integer
      format: uint16
      minimum: 100
      maximum: 599
      description: The HTTP status code for a response.
    clientFailureRecovery:
      type: object
      required:
        - outcome
        - retry
      properties:
        outcome:
          allOf:
            - $ref: '#/components/schemas/clientFailureOutcome'
          description: The known outcome of the request.
        retry:
          allOf:
            - $ref: '#/components/schemas/clientRetryDirective'
          description: The safe retry action for the request.
        sessionAction:
          allOf:
            - $ref: '#/components/schemas/clientSessionAction'
          description: The session action required before the request can continue.
        rateLimit:
          allOf:
            - $ref: '#/components/schemas/rateLimit'
          description: The rate limit state that prevented the request.
      description: The recovery contract for a failed client request.
    problem:
      type: object
      required:
        - type
        - title
        - occurredAt
        - id
        - status
      properties:
        type:
          allOf:
            - $ref: '#/components/schemas/uri'
          description: A URI reference that identifies the problem type.
        title:
          type: string
          maxLength: 120
          description: >-
            A short, human-readable summary of the problem type. The title is
            usually the same for all

            problems with the same `type`.
        occurredAt:
          type: string
          format: date-time
          description: >-
            The date-time when this problem occurred, in [RFC
            3339](https://tools.ietf.org/html/rfc3339)

            date-time `YYYY-MM-DDThh:mm:ss.sssZ` format, UTC. This is derived
            and immutable.
        detail:
          type: string
          maxLength: 256
          description: >-
            A human-readable explanation specific to this occurrence of the
            problem.
        id:
          allOf:
            - $ref: '#/components/schemas/resourceId'
          description: >-
            The unique identifier for this problem. This is an immutable opaque
            string.
        status:
          allOf:
            - $ref: '#/components/schemas/statusCode'
          description: >-
            The [HTTP status
            code](https://datatracker.ietf.org/doc/html/rfc7231#section-6)for
            this

            occurrence of the problem.
        instance:
          allOf:
            - $ref: '#/components/schemas/uri'
          maxLength: 2048
          description: >-
            A URI reference that identifies the specific occurrence of the
            problem. This is the URI of an

            API resource that the problem is related to, with a unique error
            correlation ID URI fragment.
        attributes:
          type: object
          additionalProperties: {}
          description: >-
            Additional optional attributes related to the problem. This data
            conforms to the schema

            associated with the error type.
      description: >-
        Standard problem or error response, as per

        [RFC 9457
        application/problem+json](https://tools.ietf.org/html/rfc9457).
    spokenLanguageTag:
      type: string
      enum:
        - ar
        - de
        - en
        - es
        - fr
        - ko
        - ru
        - tl
        - vi
        - zh
      description: An IETF BCP 47 language tag supported on barber profiles.
    bookingSlug:
      type: string
      minLength: 3
      maxLength: 40
      pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
      description: A barber's public booking slug, used in profile links.
    clientFailureOutcome:
      type: string
      enum:
        - notApplied
        - unknown
      description: The known outcome of a failed client request.
    clientRetryDirective:
      type: string
      enum:
        - doNotRetry
        - retrySameRequest
        - retrySameRequestAfterDelay
      description: The safe retry action for a failed client request.
    clientSessionAction:
      type: string
      enum:
        - refresh
        - signIn
      description: The session action required before a failed request can continue.
    rateLimit:
      type: object
      required:
        - limit
        - remaining
        - resetsAt
      properties:
        limit:
          type: integer
          format: uint64
          description: The maximum number of requests allowed in the active window.
        remaining:
          type: integer
          format: uint64
          description: The number of requests remaining in the active window.
        resetsAt:
          type: string
          format: date-time
          description: >-
            The date-time when the active window resets, in [RFC
            3339](https://tools.ietf.org/html/rfc3339) date-time
            `YYYY-MM-DDThh:mm:ss.sssZ` format, UTC.
      description: The rate limit state for the request.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: Bearer

````