> ## 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 item to an order

> Adds a line and returns the whole order with its items, so you never need a follow-up read to get the new total. You do not send a price: the server resolves it from the offering against the order's `pricingRegion`, which is what keeps the charge honest. A line whose resolved currency differs from the order's is rejected with 400 rather than silently converted — if you hit that, the order resolved a different region than you expected, so check `priceScope` on the existing items. A PACKAGE line cannot be added here (400 `VALIDATION_ERROR`): packages are bought when the order is created, by `packageId` in `POST /orders`.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/projects/{projectId}/orders/{orderId}/items
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}/orders/{orderId}/items:
    post:
      tags:
        - Orders
      summary: Add an item to an order
      description: >-
        Adds a line and returns the whole order with its items, so you never
        need a follow-up read to get the new total. You do not send a price: the
        server resolves it from the offering against the order's
        `pricingRegion`, which is what keeps the charge honest. A line whose
        resolved currency differs from the order's is rejected with 400 rather
        than silently converted — if you hit that, the order resolved a
        different region than you expected, so check `priceScope` on the
        existing items. A PACKAGE line cannot be added here (400
        `VALIDATION_ERROR`): packages are bought when the order is created, by
        `packageId` in `POST /orders`.
      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 order — the commercial record. Order items are drawn down into
              bookings.
            example: ord_01kv8m92p4jcrywn14znp8cym0
          required: true
          description: >-
            The order — the commercial record. Order items are drawn down into
            bookings.
          name: orderId
          in: path
      requestBody:
        description: Item data
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                skuType:
                  type: string
                  enum:
                    - SINGLE_SESSION
                    - SUBSCRIPTION
                    - MEMBERSHIP
                    - DEPOSIT
                  description: >-
                    What kind of line this is. PACKAGE is not accepted here: a
                    package is bought when the order is created, by packageId.
                serviceId:
                  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
                offeringId:
                  type: string
                  minLength: 1
                  description: >-
                    The offering — one bookable variant of a service, carrying
                    its own duration and regional pricing rules.
                  example: off_01kv60qge5eh59ap0gw0pqrrys
                quantity:
                  type: integer
                  minimum: 1
              required:
                - skuType
                - serviceId
                - offeringId
                - quantity
      responses:
        '201':
          description: Item added
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      order:
                        $ref: '#/components/schemas/Order'
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/OrderItem'
                      summary:
                        type: object
                        properties:
                          currency:
                            type: string
                          lines:
                            type: array
                            items:
                              type: object
                              properties:
                                orderItemId:
                                  type: string
                                label:
                                  type: object
                                  nullable: true
                                  additionalProperties:
                                    type: string
                                skuType:
                                  type: string
                                  enum:
                                    - SINGLE_SESSION
                                    - PACKAGE
                                    - SUBSCRIPTION
                                    - MEMBERSHIP
                                    - DEPOSIT
                                quantity:
                                  type: integer
                                  minimum: 0
                                unitPrice:
                                  $ref: '#/components/schemas/Money'
                                lineTotal:
                                  $ref: '#/components/schemas/Money'
                                tax:
                                  $ref: '#/components/schemas/Money'
                                taxable:
                                  type: boolean
                                priceRuleId:
                                  type: string
                                  nullable: true
                                  description: >-
                                    Which regional price rule this line resolved
                                    to. Compare against the offering/package
                                    `pricing[]` to see exactly which price was
                                    applied.
                                priceScope:
                                  type: string
                                  nullable: true
                                  enum:
                                    - DEFAULT
                                    - COUNTRY
                                    - STATE
                                    - POSTAL
                                    - null
                                  description: >-
                                    Specificity of the matched rule: DEFAULT,
                                    COUNTRY, STATE or POSTAL. DEFAULT means no
                                    regional rule matched and the fallback price
                                    was used.
                              required:
                                - orderItemId
                                - label
                                - skuType
                                - quantity
                                - unitPrice
                                - lineTotal
                                - tax
                                - taxable
                          fees:
                            type: array
                            items:
                              type: object
                              properties:
                                feeId:
                                  type: string
                                  description: The fee as configured on the business model.
                                businessModelId:
                                  type: string
                                  description: >-
                                    The business model that levied this fee —
                                    the commercial definition the charge belongs
                                    to.
                                name:
                                  type: object
                                  additionalProperties:
                                    type: string
                                  description: >-
                                    Buyer-facing label, snapshotted at purchase
                                    time.
                                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.
                                percentage:
                                  type: number
                                  nullable: true
                                  description: >-
                                    Echoed for PERCENT fees so the buyer can be
                                    shown the rate that applied (e.g. "Admin fee
                                    (5%)"). Absent for FLAT fees.
                                basis:
                                  type: object
                                  properties:
                                    amount:
                                      type: integer
                                      minimum: 0
                                    currency:
                                      type: string
                                      minLength: 1
                                      maxLength: 3
                                  required:
                                    - amount
                                    - currency
                                  description: >-
                                    Pre-tax total of this business model's lines
                                    — what a PERCENT fee was calculated against.
                                    Reported for FLAT fees too, so the figure is
                                    auditable.
                                amount:
                                  $ref: '#/components/schemas/Money'
                                tax:
                                  type: object
                                  properties:
                                    amount:
                                      type: integer
                                      minimum: 0
                                    currency:
                                      type: string
                                      minLength: 1
                                      maxLength: 3
                                  required:
                                    - amount
                                    - currency
                                  description: >-
                                    Tax on this fee, at the rate of its
                                    governing lines that are taxed at a positive
                                    rate. Zero when the fee is not taxable, or
                                    when none of those lines is taxed (each
                                    untaxed line says why in its
                                    taxExemptReason).
                                taxable:
                                  type: boolean
                              required:
                                - feeId
                                - businessModelId
                                - name
                                - calculation
                                - basis
                                - amount
                                - tax
                                - taxable
                            description: >-
                              Service fees levied by the business models on this
                              order. Each is a discrete charge in its own right.
                              The fee amounts are NOT in `subtotal` or
                              `taxTotal`, but tax charged on a fee IS added to
                              `taxTotal`. Applied once per fee however many
                              lines it governs.
                          feeTotal:
                            type: object
                            properties:
                              amount:
                                type: integer
                                minimum: 0
                              currency:
                                type: string
                                minLength: 1
                                maxLength: 3
                            required:
                              - amount
                              - currency
                            description: >-
                              Sum of `fees[].amount`. Sits outside `subtotal`,
                              so `total = subtotal + feeTotal + taxTotal`.
                          subtotal:
                            $ref: '#/components/schemas/Money'
                          taxTotal:
                            $ref: '#/components/schemas/Money'
                          total:
                            $ref: '#/components/schemas/Money'
                          amountPaid:
                            $ref: '#/components/schemas/Money'
                          amountRefunded:
                            $ref: '#/components/schemas/Money'
                          amountDue:
                            $ref: '#/components/schemas/Money'
                        required:
                          - currency
                          - lines
                          - fees
                          - feeTotal
                          - subtotal
                          - taxTotal
                          - total
                          - amountPaid
                          - amountRefunded
                          - amountDue
                    required:
                      - order
                      - items
                      - summary
                required:
                  - data
        '400':
          description: >-
            Validation error (including skuType PACKAGE, which is bought at
            order create), or currency mismatch
          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: Order or offering not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '422':
          description: >-
            The service has no active rate of the kind the line implies, e.g. a
            SINGLE_SESSION line on a service with no active SINGLE_BOOKING rate
            (SERVICE_NOT_SOLD_AS); or the line names a service that is not LIVE
            or was deleted, or an offering that is not ACTIVE (NOT_SELLABLE)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
components:
  schemas:
    Order:
      type: object
      properties:
        projectId:
          type: string
        tenantId:
          type: string
        orderId:
          type: string
        clientId:
          type: string
        currency:
          type: string
          minLength: 3
          maxLength: 3
        subtotal:
          $ref: '#/components/schemas/Money'
        feeTotal:
          $ref: '#/components/schemas/Money'
        tax:
          $ref: '#/components/schemas/Money'
        total:
          $ref: '#/components/schemas/Money'
        amountPaid:
          $ref: '#/components/schemas/Money'
        amountRefunded:
          $ref: '#/components/schemas/Money'
        status:
          type: string
          enum:
            - DRAFT
            - PENDING
            - PAID
            - CANCELLED
        statusUpdatedAt:
          type: string
          format: date-time
        cancellationReason:
          type: string
          nullable: true
        cancelledBy:
          type: string
          nullable: true
        paymentMethod:
          type: string
          enum:
            - STRIPE
            - CASH
            - EXTERNAL
            - COMP
            - MIXED
            - LEGACY
        settledAt:
          type: string
          format: date-time
        amountComped:
          $ref: '#/components/schemas/Money'
        pricingRegion:
          type: object
          nullable: true
          properties:
            country:
              type: string
              nullable: true
            state:
              type: string
              nullable: true
            postalCode:
              type: string
              nullable: true
        locale:
          type: string
        attribution:
          type: object
          properties:
            searchId:
              type: string
              minLength: 1
              maxLength: 128
              description: >-
                The `searchId` of the MarketBox search response the buyer booked
                from — the `X-MB-Search-Id` header / body field of every search
                route. Stored as given; a value MarketBox never issued is kept
                but not trusted.
              example: srch_01k7q3x9h4e8rb2d6m0z5a7c1n
            sessionKey:
              type: string
              minLength: 1
              maxLength: 64
              description: >-
                The same opaque per-session key you send with site events, at
                most 64 characters. Never an email, IP or user id.
              example: sess-example-01
            surface:
              type: string
              enum:
                - home
                - results
                - listing
                - site_search
                - profile
                - widget
                - assistant
                - other
              description: Where on your site the buyer started the purchase.
              example: results
          additionalProperties: false
          description: >-
            Which search and site session this purchase came from. Optional; set
            once on the order and copied onto every booking it funds. See the
            search-log guide, "Booking attribution".
        deleted:
          type: boolean
        version:
          type: integer
          minimum: 0
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        createdBy:
          type: string
        updatedBy:
          type: string
      required:
        - projectId
        - tenantId
        - orderId
        - clientId
        - currency
        - subtotal
        - tax
        - total
        - amountPaid
        - amountRefunded
        - status
        - statusUpdatedAt
        - deleted
        - version
        - createdAt
        - updatedAt
        - createdBy
        - updatedBy
    OrderItem:
      type: object
      properties:
        projectId:
          type: string
        orderId:
          type: string
        orderItemId:
          type: string
        skuType:
          type: string
          enum:
            - SINGLE_SESSION
            - PACKAGE
            - SUBSCRIPTION
            - MEMBERSHIP
            - DEPOSIT
        serviceId:
          type: string
        offeringId:
          type: string
        packageId:
          type: string
          nullable: true
        quantity:
          type: integer
          minimum: 0
          exclusiveMinimum: true
        quantityAllocated:
          type: integer
          minimum: 0
        quantityRemaining:
          type: integer
          minimum: 0
        unitPrice:
          $ref: '#/components/schemas/Money'
        lineTotal:
          $ref: '#/components/schemas/Money'
        taxSnapshot:
          type: object
          nullable: true
          properties:
            taxable:
              type: boolean
            taxPercentage:
              type: number
              minimum: 0
          required:
            - taxable
        feeSnapshot:
          type: array
          nullable: true
          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
        businessModelId:
          type: string
          nullable: true
        label:
          type: object
          nullable: true
          additionalProperties:
            type: string
        priceRuleId:
          type: string
          nullable: true
          description: >-
            Which regional price rule this line resolved to. Compare against the
            offering/package `pricing[]` to see exactly which price was applied.
        priceScope:
          type: string
          nullable: true
          enum:
            - DEFAULT
            - COUNTRY
            - STATE
            - POSTAL
            - null
          description: >-
            Specificity of the matched rule: DEFAULT, COUNTRY, STATE or POSTAL.
            DEFAULT means no regional rule matched and the fallback price was
            used.
        priceSource:
          type: string
          enum:
            - RULE
            - MANUAL
          description: >-
            Where this line’s price came from. RULE: resolved from the offering
            or package `pricing[]` (see `priceRuleId`). MANUAL: set by staff
            when the order was created, in place of the rule price;
            `priceRuleId` is null and `unitPrice` will not match any rule.
            Absent on items written before this field existed.
        taxExemptReason:
          type: string
          enum:
            - NO_RATE
            - NOT_TAXABLE
            - ZERO_RATE
            - MIGRATED_V1
            - PACKAGE_EXEMPT_LEGACY
          description: >-
            Why this line carries no tax. NO_RATE: neither the matched price
            rule, its parent rules, nor the service set a rate. NOT_TAXABLE: the
            resolved tax settings mark it not taxable. ZERO_RATE: taxable at 0%.
            MIGRATED_V1: imported from MarketBox v1, which recorded tax on the
            order rather than per line. PACKAGE_EXEMPT_LEGACY: a package line
            written while package purchases were untaxed (June–September 2026).
            Absent when the line is taxed at a positive rate, and on lines
            written before this field existed.
        expiresAt:
          type: string
          nullable: true
          format: date-time
        deleted:
          type: boolean
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        createdBy:
          type: string
        updatedBy:
          type: string
      required:
        - projectId
        - orderId
        - orderItemId
        - skuType
        - serviceId
        - offeringId
        - quantity
        - quantityAllocated
        - quantityRemaining
        - unitPrice
        - lineTotal
        - deleted
        - createdAt
        - updatedAt
        - createdBy
        - updatedBy
    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.