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

# Update an order item quantity

> Changes quantity only — the unit price stays as resolved when the line was added, so re-pricing an existing line is not possible through this endpoint. Remove the line and add it again if the price must change. Returns the whole order with its recalculated totals.



## OpenAPI

````yaml /api-reference/openapi.json patch /v1/projects/{projectId}/orders/{orderId}/items/{orderItemId}
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/{orderItemId}:
    patch:
      tags:
        - Orders
      summary: Update an order item quantity
      description: >-
        Changes quantity only — the unit price stays as resolved when the line
        was added, so re-pricing an existing line is not possible through this
        endpoint. Remove the line and add it again if the price must change.
        Returns the whole order with its recalculated totals.
      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
        - schema:
            type: string
            minLength: 1
            description: >-
              The order item — one line of an order. A PACKAGE item funds many
              bookings; a SINGLE_SESSION item funds one.
            example: oi_01kv8m92p6kdszxo25aoq9dzn1
          required: true
          description: >-
            The order item — one line of an order. A PACKAGE item funds many
            bookings; a SINGLE_SESSION item funds one.
          name: orderItemId
          in: path
      requestBody:
        description: Item update
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                quantity:
                  type: integer
                  minimum: 1
              required:
                - quantity
      responses:
        '200':
          description: Item updated
          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
          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 item not found
          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.