> ## 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 an offering to a service

> The offering is the sellable variant — price and duration live here, not on the service, so this is the call that makes a service purchasable. It is created ACTIVE; there is no draft step. `pricing` is a rule hierarchy, not a single amount: exactly one DEFAULT rule is required, a STATE rule is rejected without a COUNTRY rule for the same country, and a POSTAL rule is rejected without the matching STATE rule. `country` and `state` accept full names and are stored as ISO codes ("Canada" becomes "CA", "Ontario" becomes "ON"), so read back what you wrote rather than assuming your spelling survived. Anything an order cannot match a region rule for falls through to DEFAULT — including its currency, which is why a catalogue sold abroad needs a COUNTRY rule per currency and not just a translated name. Every id in `skillIds` and `locationIds` must already exist and be active in the project, or the whole call is a 400.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/projects/{projectId}/services/{serviceId}/offerings
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}/offerings:
    post:
      tags:
        - ServiceOfferings
      summary: Add an offering to a service
      description: >-
        The offering is the sellable variant — price and duration live here, not
        on the service, so this is the call that makes a service purchasable. It
        is created ACTIVE; there is no draft step. `pricing` is a rule
        hierarchy, not a single amount: exactly one DEFAULT rule is required, a
        STATE rule is rejected without a COUNTRY rule for the same country, and
        a POSTAL rule is rejected without the matching STATE rule. `country` and
        `state` accept full names and are stored as ISO codes ("Canada" becomes
        "CA", "Ontario" becomes "ON"), so read back what you wrote rather than
        assuming your spelling survived. Anything an order cannot match a region
        rule for falls through to DEFAULT — including its currency, which is why
        a catalogue sold abroad needs a COUNTRY rule per currency and not just a
        translated name. Every id in `skillIds` and `locationIds` must already
        exist and be active in the project, or the whole call is a 400.
      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: Offering data
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: object
                  additionalProperties:
                    type: string
                pricing:
                  type: array
                  items:
                    type: object
                    properties:
                      ruleId:
                        type: string
                        minLength: 1
                      scope:
                        type: string
                        enum:
                          - DEFAULT
                          - COUNTRY
                          - STATE
                          - POSTAL
                        description: >-
                          How specifically a price rule targets a region.
                          Resolution picks the most specific match: POSTAL beats
                          STATE beats COUNTRY beats DEFAULT. DEFAULT is the
                          fallback every offering must define ("any region"). On
                          an order item, `priceScope` reports which one actually
                          applied — seeing DEFAULT where you expected a regional
                          price means the region did not resolve.
                      country:
                        type: string
                        minLength: 1
                      state:
                        type: string
                        minLength: 1
                      postalCodes:
                        type: array
                        items:
                          type: string
                          minLength: 1
                      price:
                        $ref: '#/components/schemas/Money'
                      tax:
                        type: object
                        properties:
                          taxable:
                            type: boolean
                          taxPercentage:
                            type: number
                            minimum: 0
                        required:
                          - taxable
                    required:
                      - ruleId
                      - scope
                      - price
                  minItems: 1
                duration:
                  oneOf:
                    - type: object
                      properties:
                        type:
                          type: string
                          enum:
                            - FIXED
                        minutes:
                          type: integer
                          minimum: 0
                          exclusiveMinimum: true
                      required:
                        - type
                        - minutes
                    - type: object
                      properties:
                        type:
                          type: string
                          enum:
                            - FLEXIBLE
                        defaultMinutes:
                          type: integer
                          minimum: 0
                          exclusiveMinimum: true
                        minMinutes:
                          type: integer
                          minimum: 0
                          exclusiveMinimum: true
                        stepMinutes:
                          type: integer
                          minimum: 0
                          exclusiveMinimum: true
                        pricePerStep:
                          $ref: '#/components/schemas/Money'
                      required:
                        - type
                        - defaultMinutes
                        - minMinutes
                        - stepMinutes
                attributeValues:
                  type: array
                  items:
                    type: object
                    properties:
                      attributeId:
                        type: string
                        minLength: 1
                      attributeNameSnapshot:
                        type: object
                        additionalProperties:
                          type: string
                      attributeType:
                        type: string
                        enum:
                          - STRING
                          - NUMBER
                          - ENUM
                        description: >-
                          Value type of a service attribute. ENUM attributes
                          carry an allowed-values list.
                      value:
                        anyOf:
                          - type: object
                            additionalProperties:
                              type: string
                          - type: number
                          - type: string
                      valueId:
                        type: string
                    required:
                      - attributeId
                      - attributeNameSnapshot
                      - attributeType
                  default: []
                skillIds:
                  type: array
                  items:
                    type: string
                  default: []
                locationIds:
                  type: array
                  items:
                    type: string
                  default: []
                holdDurationMinsOverride:
                  type: integer
                  nullable: true
                  minimum: 0
                  exclusiveMinimum: true
              required:
                - pricing
                - duration
      responses:
        '201':
          description: Offering created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      entityType:
                        type: string
                        enum:
                          - SERVICE_OFFERING
                      projectId:
                        type: string
                      serviceId:
                        type: string
                      offeringId:
                        type: string
                      name:
                        type: object
                        additionalProperties:
                          type: string
                      pricing:
                        type: array
                        items:
                          type: object
                          properties:
                            ruleId:
                              type: string
                              minLength: 1
                            scope:
                              type: string
                              enum:
                                - DEFAULT
                                - COUNTRY
                                - STATE
                                - POSTAL
                              description: >-
                                How specifically a price rule targets a region.
                                Resolution picks the most specific match: POSTAL
                                beats STATE beats COUNTRY beats DEFAULT. DEFAULT
                                is the fallback every offering must define ("any
                                region"). On an order item, `priceScope` reports
                                which one actually applied — seeing DEFAULT
                                where you expected a regional price means the
                                region did not resolve.
                            country:
                              type: string
                              minLength: 1
                            state:
                              type: string
                              minLength: 1
                            postalCodes:
                              type: array
                              items:
                                type: string
                                minLength: 1
                            price:
                              $ref: '#/components/schemas/Money'
                            tax:
                              type: object
                              properties:
                                taxable:
                                  type: boolean
                                taxPercentage:
                                  type: number
                                  minimum: 0
                              required:
                                - taxable
                          required:
                            - ruleId
                            - scope
                            - price
                        minItems: 1
                      duration:
                        oneOf:
                          - type: object
                            properties:
                              type:
                                type: string
                                enum:
                                  - FIXED
                              minutes:
                                type: integer
                                minimum: 0
                                exclusiveMinimum: true
                            required:
                              - type
                              - minutes
                          - type: object
                            properties:
                              type:
                                type: string
                                enum:
                                  - FLEXIBLE
                              defaultMinutes:
                                type: integer
                                minimum: 0
                                exclusiveMinimum: true
                              minMinutes:
                                type: integer
                                minimum: 0
                                exclusiveMinimum: true
                              stepMinutes:
                                type: integer
                                minimum: 0
                                exclusiveMinimum: true
                              pricePerStep:
                                $ref: '#/components/schemas/Money'
                            required:
                              - type
                              - defaultMinutes
                              - minMinutes
                              - stepMinutes
                      attributeValues:
                        type: array
                        items:
                          type: object
                          properties:
                            attributeId:
                              type: string
                              minLength: 1
                            attributeNameSnapshot:
                              type: object
                              additionalProperties:
                                type: string
                            attributeType:
                              type: string
                              enum:
                                - STRING
                                - NUMBER
                                - ENUM
                              description: >-
                                Value type of a service attribute. ENUM
                                attributes carry an allowed-values list.
                            value:
                              anyOf:
                                - type: object
                                  additionalProperties:
                                    type: string
                                - type: number
                                - type: string
                            valueId:
                              type: string
                          required:
                            - attributeId
                            - attributeNameSnapshot
                            - attributeType
                      status:
                        type: string
                        enum:
                          - ACTIVE
                          - INACTIVE
                        description: >-
                          Whether this offering can be booked. An INACTIVE
                          offering rejects new bookings but existing ones stand.
                      skillIds:
                        type: array
                        items:
                          type: string
                        default: []
                      locationIds:
                        type: array
                        items:
                          type: string
                        default: []
                      holdDurationMinsOverride:
                        type: integer
                        nullable: true
                        minimum: 0
                        exclusiveMinimum: true
                      deleted:
                        type: boolean
                      createdAt:
                        type: string
                        format: date-time
                      updatedAt:
                        type: string
                        format: date-time
                      createdBy:
                        type: string
                      updatedBy:
                        type: string
                    required:
                      - entityType
                      - projectId
                      - serviceId
                      - offeringId
                      - pricing
                      - duration
                      - attributeValues
                      - status
                      - deleted
                      - 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'
        '404':
          description: Service not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
components:
  schemas:
    Money:
      type: object
      properties:
        amount:
          type: integer
          minimum: 0
        currency:
          type: string
          minLength: 1
          maxLength: 3
      required:
        - amount
        - currency
    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.