> ## 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.

# Create a sellable package (bundle) for an offering

> Sells `creditCount` prepaid sessions of one offering as a single bundle. The parent service must already carry an ACTIVE business model of type PACKAGE — without it this is a 400, and that guard is the usual reason a first package create fails, so add the business model before the package. The offering must belong to the service named in the path and not be deleted, or 404. Pricing is FLAT and cannot be changed: each rule's amount is the total for the WHOLE bundle, not per session, so a 10-session bundle at 45000 charges 45000 once. The `pricing` array obeys the same rules as an offering's — exactly one DEFAULT rule, children require parents, country and state coerce to ISO codes. Defaults if omitted: status ACTIVE (so it is on sale the moment it is created — send DRAFT if it is not ready), capacity 1, and validityDays null meaning credits never expire.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/projects/{projectId}/services/{serviceId}/offerings/{offeringId}/packages
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/{offeringId}/packages:
    post:
      tags:
        - ServicePackages
      summary: Create a sellable package (bundle) for an offering
      description: >-
        Sells `creditCount` prepaid sessions of one offering as a single bundle.
        The parent service must already carry an ACTIVE business model of type
        PACKAGE — without it this is a 400, and that guard is the usual reason a
        first package create fails, so add the business model before the
        package. The offering must belong to the service named in the path and
        not be deleted, or 404. Pricing is FLAT and cannot be changed: each
        rule's amount is the total for the WHOLE bundle, not per session, so a
        10-session bundle at 45000 charges 45000 once. The `pricing` array obeys
        the same rules as an offering's — exactly one DEFAULT rule, children
        require parents, country and state coerce to ISO codes. Defaults if
        omitted: status ACTIVE (so it is on sale the moment it is created — send
        DRAFT if it is not ready), capacity 1, and validityDays null meaning
        credits never expire.
      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
        - schema:
            type: string
            minLength: 1
            description: >-
              The offering — one bookable variant of a service, carrying its own
              duration and regional pricing rules.
            example: off_01kv60qge5eh59ap0gw0pqrrys
          required: true
          description: >-
            The offering — one bookable variant of a service, carrying its own
            duration and regional pricing rules.
          name: offeringId
          in: path
      requestBody:
        description: Package data
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: object
                  additionalProperties:
                    type: string
                description:
                  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
                creditCount:
                  type: integer
                  minimum: 0
                  exclusiveMinimum: true
                discountPercent:
                  type: number
                  minimum: 0
                  maximum: 100
                  description: >-
                    Percentage discount (0-100) recorded when this package's
                    prices were seeded from the offering's prices (price =
                    offering price * creditCount * (1 - discountPercent/100)).
                    Informational metadata only: `pricing` is the authoritative
                    source of the amounts charged. Individual prices can be
                    manually overridden after seeding, and the offering's prices
                    may change later, so this value is not guaranteed to match
                    the actual prices - never derive amounts from it.
                validityDays:
                  type: integer
                  nullable: true
                  minimum: 0
                  exclusiveMinimum: true
                  default: null
                status:
                  type: string
                  enum:
                    - DRAFT
                    - ACTIVE
                    - ARCHIVED
                  default: ACTIVE
                  description: >-
                    Lifecycle of the package bundle. ARCHIVED hides it from the
                    storefront and blocks new orders, but order items already
                    placed against it stay bookable.
                capacity:
                  type: integer
                  minimum: 0
                  exclusiveMinimum: true
                  default: 1
              required:
                - pricing
                - creditCount
      responses:
        '201':
          description: Package created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ServicePackage'
                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: Offering 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
    ServicePackage:
      type: object
      properties:
        entityType:
          type: string
          enum:
            - SERVICE_PACKAGE
        projectId:
          type: string
        serviceId:
          type: string
        offeringId:
          type: string
        packageId:
          type: string
        name:
          type: object
          additionalProperties:
            type: string
        description:
          type: object
          additionalProperties:
            type: string
        pricingModel:
          type: string
          enum:
            - PER_SESSION
            - FLAT
        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
        creditCount:
          type: integer
          minimum: 0
          exclusiveMinimum: true
        discountPercent:
          type: number
          minimum: 0
          maximum: 100
          description: >-
            Percentage discount (0-100) recorded when this package's prices were
            seeded from the offering's prices (price = offering price *
            creditCount * (1 - discountPercent/100)). Informational metadata
            only: `pricing` is the authoritative source of the amounts charged.
            Individual prices can be manually overridden after seeding, and the
            offering's prices may change later, so this value is not guaranteed
            to match the actual prices - never derive amounts from it.
        validityDays:
          type: integer
          nullable: true
          minimum: 0
          exclusiveMinimum: true
        status:
          type: string
          enum:
            - DRAFT
            - ACTIVE
            - ARCHIVED
          description: >-
            Lifecycle of the package bundle. ARCHIVED hides it from the
            storefront and blocks new orders, but order items already placed
            against it stay bookable.
        capacity:
          type: integer
          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
        - packageId
        - pricingModel
        - pricing
        - creditCount
        - validityDays
        - status
        - capacity
        - deleted
        - createdAt
        - updatedAt
        - createdBy
        - updatedBy
    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.