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

# Add a business model to a service

> Declares a way the service can be sold, and gates what you can build on it — a service cannot have packages created against it until it carries an active PACKAGE model, so this call usually comes before the first package. The model is created active. Nothing here is deduplicated: posting the same `type` twice leaves two rows, both live, so list before you add. `type` cannot be changed afterwards, only deactivated, so pick it deliberately. `paymentOptions` sets when money is taken and must hold at least one option. `fees` are additional charges — a booking fee, an admin fee — attached to this business model and applied automatically to any order line sold under it. Each fee is charged once per order however many lines it governs, and surfaces as its own entry in the order summary rather than being folded into tax. A FLAT fee is a bare minor-unit figure that takes the currency of whatever order it lands on; use a PERCENT fee if you need it to scale.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/projects/{projectId}/services/{serviceId}/business-models
openapi: 3.0.0
info:
  title: MarketBox 2.0 Open API
  version: 1.0.0
  description: >-
    The MarketBox public API for building booking experiences. Core model:
    create an order, then draw its order items down into bookings. Single
    bookings reference an order item per service line; package bookings draw one
    PACKAGE item down across N sessions. To schedule a package, build a slate
    (POST /availability/package-slate) and book it by slateId (POST
    /orders/{orderId}/package-bookings). See the guides for end-to-end
    walkthroughs.
  contact:
    name: MarketBox support
servers:
  - url: https://apiv2.gomarketbox.com
    description: MarketBox Open API
security:
  - ApiKeyAuth: []
paths:
  /v1/projects/{projectId}/services/{serviceId}/business-models:
    post:
      tags:
        - ServiceBusinessModels
      summary: Add a business model to a service
      description: >-
        Declares a way the service can be sold, and gates what you can build on
        it — a service cannot have packages created against it until it carries
        an active PACKAGE model, so this call usually comes before the first
        package. The model is created active. Nothing here is deduplicated:
        posting the same `type` twice leaves two rows, both live, so list before
        you add. `type` cannot be changed afterwards, only deactivated, so pick
        it deliberately. `paymentOptions` sets when money is taken and must hold
        at least one option. `fees` are additional charges — a booking fee, an
        admin fee — attached to this business model and applied automatically to
        any order line sold under it. Each fee is charged once per order however
        many lines it governs, and surfaces as its own entry in the order
        summary rather than being folded into tax. A FLAT fee is a bare
        minor-unit figure that takes the currency of whatever order it lands on;
        use a PERCENT fee if you need it to scale.
      parameters:
        - schema:
            type: string
            minLength: 1
            description: >-
              The project (tenant) that owns the resource. Every resource in
              this API is scoped to a project, and your API key is restricted to
              the projects it was issued for — a project outside that scope
              returns 403.
            example: prj_01kv60qgnef2kt3pvqgwmkbzfr
          required: true
          description: >-
            The project (tenant) that owns the resource. Every resource in this
            API is scoped to a project, and your API key is restricted to the
            projects it was issued for — a project outside that scope returns
            403.
          name: projectId
          in: path
        - schema:
            type: string
            minLength: 1
            description: >-
              The service — the sellable thing (a lesson, a treatment).
              Offerings hang off a service and carry the duration and price.
            example: srv_01kv60qg12e82acr78edfnjhvv
          required: true
          description: >-
            The service — the sellable thing (a lesson, a treatment). Offerings
            hang off a service and carry the duration and price.
          name: serviceId
          in: path
      requestBody:
        description: Business model data
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - SINGLE_BOOKING
                    - PACKAGE
                    - SCHEDULED_PACKAGE
                    - SCHEDULED_SUBSCRIPTION
                    - FLEXIBLE_SUBSCRIPTION
                  description: >-
                    How the service is sold. SINGLE_BOOKING is one booking at a
                    time; PACKAGE sells prepaid credits drawn down by later
                    bookings; the SCHEDULED_* and FLEXIBLE_* variants add
                    recurrence and subscription billing. This drives which order
                    item skuType applies.
                paymentOptions:
                  type: array
                  items:
                    type: string
                    enum:
                      - PAY_WHILE_BOOKING
                      - PAY_AFTER_SERVICE_DELIVERED
                      - NO_PAYMENT
                      - PAY_FULL_PRICE_WHILE_PURCHASING
                      - PAY_BEGINNING_OF_MONTH
                      - PAY_END_OF_MONTH
                  minItems: 1
                fees:
                  type: array
                  items:
                    type: object
                    properties:
                      feeId:
                        type: string
                        minLength: 1
                        description: >-
                          Stable identifier for this fee, unique within the
                          business model.
                        example: fee_booking
                      name:
                        type: object
                        additionalProperties:
                          type: string
                        description: >-
                          Buyer-facing label, rendered as its own line on the
                          order summary.
                        example:
                          en: Booking fee
                      calculation:
                        type: string
                        enum:
                          - FLAT
                          - PERCENT
                        description: >-
                          How a service fee is calculated. FLAT charges a fixed
                          amount; PERCENT charges a percentage of the pre-tax
                          total of the lines the fee governs.
                        example: FLAT
                      amount:
                        type: integer
                        minimum: 0
                        description: >-
                          FLAT fees only. Integer minor units, charged in
                          whatever currency the order is placed in — 2500 is
                          CA$25.00 on a CAD order and US$25.00 on a USD one. Use
                          a PERCENT fee if you need it to scale.
                        example: 2500
                      percentage:
                        type: number
                        minimum: 0
                        maximum: 100
                        description: >-
                          PERCENT fees only. Applied to the pre-tax total of
                          this business model's lines on the order.
                        example: 5
                      taxable:
                        type: boolean
                        default: false
                        description: >-
                          When true, the fee is taxed at the rate of the order
                          lines it is charged alongside (sessions or packages
                          sold under this business model) that are taxed at a
                          positive rate. Lines that are not taxable or taxed at
                          0% lend no rate; if none of the lines is taxed, the
                          fee is not taxed either.
                        example: false
                    required:
                      - feeId
                      - name
                      - calculation
                  maxItems: 20
                  default: []
                  description: >-
                    Service fees — additional charges attached to this business
                    model, applied to any order line sold under it. Each fee
                    applies once per order regardless of how many lines it
                    governs, and appears as its own entry on the order summary
                    rather than being folded into tax.
                  example:
                    - feeId: fee_booking
                      name:
                        en: Booking fee
                      calculation: FLAT
                      amount: 2500
                      taxable: false
                    - feeId: fee_admin
                      name:
                        en: Admin fee
                      calculation: PERCENT
                      percentage: 5
                      taxable: true
                config:
                  type: object
                  properties: {}
                  default: {}
                  additionalProperties:
                    nullable: true
              required:
                - type
                - paymentOptions
      responses:
        '201':
          description: Business model created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      entityType:
                        type: string
                        enum:
                          - SERVICE_BUSINESS_MODEL
                      projectId:
                        type: string
                      serviceId:
                        type: string
                      businessModelId:
                        type: string
                      type:
                        type: string
                        enum:
                          - SINGLE_BOOKING
                          - PACKAGE
                          - SCHEDULED_PACKAGE
                          - SCHEDULED_SUBSCRIPTION
                          - FLEXIBLE_SUBSCRIPTION
                        description: >-
                          How the service is sold. SINGLE_BOOKING is one booking
                          at a time; PACKAGE sells prepaid credits drawn down by
                          later bookings; the SCHEDULED_* and FLEXIBLE_*
                          variants add recurrence and subscription billing. This
                          drives which order item skuType applies.
                      paymentOptions:
                        type: array
                        items:
                          type: string
                          enum:
                            - PAY_WHILE_BOOKING
                            - PAY_AFTER_SERVICE_DELIVERED
                            - NO_PAYMENT
                            - PAY_FULL_PRICE_WHILE_PURCHASING
                            - PAY_BEGINNING_OF_MONTH
                            - PAY_END_OF_MONTH
                      fees:
                        type: array
                        items:
                          type: object
                          properties:
                            feeId:
                              type: string
                              minLength: 1
                              description: >-
                                Stable identifier for this fee, unique within
                                the business model.
                              example: fee_booking
                            name:
                              type: object
                              additionalProperties:
                                type: string
                              description: >-
                                Buyer-facing label, rendered as its own line on
                                the order summary.
                              example:
                                en: Booking fee
                            calculation:
                              type: string
                              enum:
                                - FLAT
                                - PERCENT
                              description: >-
                                How a service fee is calculated. FLAT charges a
                                fixed amount; PERCENT charges a percentage of
                                the pre-tax total of the lines the fee governs.
                              example: FLAT
                            amount:
                              type: integer
                              minimum: 0
                              description: >-
                                FLAT fees only. Integer minor units, charged in
                                whatever currency the order is placed in — 2500
                                is CA$25.00 on a CAD order and US$25.00 on a USD
                                one. Use a PERCENT fee if you need it to scale.
                              example: 2500
                            percentage:
                              type: number
                              minimum: 0
                              maximum: 100
                              description: >-
                                PERCENT fees only. Applied to the pre-tax total
                                of this business model's lines on the order.
                              example: 5
                            taxable:
                              type: boolean
                              default: false
                              description: >-
                                When true, the fee is taxed at the rate of the
                                order lines it is charged alongside (sessions or
                                packages sold under this business model) that
                                are taxed at a positive rate. Lines that are not
                                taxable or taxed at 0% lend no rate; if none of
                                the lines is taxed, the fee is not taxed either.
                              example: false
                          required:
                            - feeId
                            - name
                            - calculation
                        maxItems: 20
                        description: >-
                          Service fees — additional charges attached to this
                          business model, applied to any order line sold under
                          it. Each fee applies once per order regardless of how
                          many lines it governs, and appears as its own entry on
                          the order summary rather than being folded into tax.
                        example:
                          - feeId: fee_booking
                            name:
                              en: Booking fee
                            calculation: FLAT
                            amount: 2500
                            taxable: false
                          - feeId: fee_admin
                            name:
                              en: Admin fee
                            calculation: PERCENT
                            percentage: 5
                            taxable: true
                      config:
                        type: object
                        properties: {}
                        additionalProperties:
                          nullable: true
                      active:
                        type: boolean
                      createdAt:
                        type: string
                        format: date-time
                      updatedAt:
                        type: string
                        format: date-time
                      createdBy:
                        type: string
                      updatedBy:
                        type: string
                    required:
                      - entityType
                      - projectId
                      - serviceId
                      - businessModelId
                      - type
                      - paymentOptions
                      - config
                      - active
                      - createdAt
                      - updatedAt
                      - createdBy
                      - updatedBy
                required:
                  - data
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '403':
          description: API key cannot access this project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
components:
  schemas:
    ErrorMessage:
      type: object
      properties:
        code:
          type: string
          description: Stable machine-readable error code, e.g. NOT_FOUND.
        message:
          type: string
          description: Human-readable description of what went wrong.
        statusCode:
          type: integer
          description: The HTTP status code of this response.
        requestId:
          type: string
          description: >-
            The id of this request, also returned as the X-Request-Id header.
            Quote it in a support ticket.
      required:
        - code
        - message
        - statusCode
        - requestId
      example:
        code: NOT_FOUND
        message: Booking not found
        statusCode: 404
        requestId: a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        API key minted in the MarketBox dashboard. Scope is restricted to the
        projects you select at creation time. Every route needs the key's
        standard API access (`*`) except `POST /v1/projects/{projectId}/events`,
        which needs `events:write`; a key without `*` is refused with 403
        `CAPABILITY_NOT_GRANTED`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.