> ## 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 new order

> Creates an order (a cart/purchase record). For a package, add an item with { skuType: "PACKAGE", packageId } — the server derives service, offering, session count (creditCount), price and expiry from the package. For a single session use { skuType: "SINGLE_SESSION", serviceId, offeringId, quantity }. The order item is the credit ledger: its quantityRemaining is what bookings draw down. Currency is fixed at creation.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/projects/{projectId}/orders
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:
    post:
      tags:
        - Orders
      summary: Create a new order
      description: >-
        Creates an order (a cart/purchase record). For a package, add an item
        with { skuType: "PACKAGE", packageId } — the server derives service,
        offering, session count (creditCount), price and expiry from the
        package. For a single session use { skuType: "SINGLE_SESSION",
        serviceId, offeringId, quantity }. The order item is the credit ledger:
        its quantityRemaining is what bookings draw down. Currency is fixed at
        creation.
      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
      requestBody:
        description: Order data
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                clientId:
                  type: string
                  minLength: 1
                  description: The client placing the order.
                  example: cli_01kv8p20m1gnqvxl92xln6awk8
                currency:
                  type: string
                  minLength: 3
                  maxLength: 3
                  description: >-
                    ISO 4217 currency you quoted the buyer. Verified against the
                    price the server resolves for this order's region; a
                    mismatch is a 400.
                  example: CAD
                locale:
                  type: string
                  description: >-
                    The locale your buyer completed this purchase in — typically
                    the language segment of your storefront URL. Normalized to
                    canonical BCP-47 on write, so `en-us` is stored as `en-US`.
                    It is copied onto every booking this order funds and saved
                    as the client's default locale.
                  example: en-US
                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: the
                    `searchId` of the search response the buyer booked from,
                    your opaque `sessionKey`, and the `surface` the list was
                    drawn on. Optional. Stored as given and copied onto every
                    booking this order funds; holds and the booking routes never
                    take one of their own. A `searchId` MarketBox never issued
                    is kept but not counted.
                  example:
                    searchId: srch_01k7q3x9h4e8rb2d6m0z5a7c1n
                    sessionKey: sess-example-01
                    surface: results
                reservationId:
                  type: string
                  minLength: 1
                  description: >-
                    The hold this order funds. Preferred: the hold already knows
                    where the booking happens, so the order and its bookings
                    cannot disagree on price.
                  example: resv_01kx16f0a1c7b2sd91xzq3mn5p
                locationId:
                  type: string
                  minLength: 1
                  description: >-
                    Stored Location for a PHYSICAL booking. Ignored when
                    reservationId is given.
                address:
                  type: object
                  properties:
                    addressOneLine:
                      type: string
                      minLength: 1
                      description: >-
                        The whole address on one line, as a person would write
                        it.
                      example: 10 Main St, Toronto, ON M5V 1A1, Canada
                    streetNumber:
                      type: string
                      minLength: 1
                      description: The street number.
                      example: '10'
                    streetName:
                      type: string
                      minLength: 1
                      description: The street name.
                      example: Main St
                    city:
                      type: string
                      minLength: 1
                      description: The city or town.
                      example: Toronto
                    state:
                      type: string
                      minLength: 1
                      description: >-
                        The state, province or region; an ISO 3166-2 code when
                        one matches.
                      example: 'ON'
                    country:
                      type: string
                      minLength: 1
                      description: >-
                        The country; ISO 3166-1 alpha-2, alpha-3 or the English
                        name.
                      example: CA
                    zipCode:
                      type: string
                      minLength: 1
                      description: The postal or ZIP code, in any national format.
                      example: M5V 1A1
                    unitNumber:
                      type: string
                      nullable: true
                      description: The unit, suite or apartment, if any.
                      example: 4B
                  required:
                    - addressOneLine
                    - streetNumber
                    - streetName
                    - city
                    - state
                    - country
                    - zipCode
                  description: >-
                    Service address for a TRAVEL_ZONE (in-home) booking. Ignored
                    when reservationId or locationId is given.
                items:
                  type: array
                  items:
                    type: object
                    properties:
                      skuType:
                        type: string
                        enum:
                          - SINGLE_SESSION
                          - PACKAGE
                          - SUBSCRIPTION
                          - MEMBERSHIP
                          - DEPOSIT
                        description: >-
                          What kind of line this is: SINGLE_SESSION, PACKAGE,
                          SUBSCRIPTION, MEMBERSHIP, or DEPOSIT.
                        example: PACKAGE
                      packageId:
                        type: string
                        minLength: 1
                        description: >-
                          Required for PACKAGE items. serviceId, offeringId,
                          session count, price and expiry are all derived from
                          the package.
                        example: pkg_01kv7n10k0fnptwk81wkm59vj7
                      serviceId:
                        type: string
                        minLength: 1
                        description: Required for SINGLE_SESSION items.
                        example: srv_01kv60qg12e82acr78edfnjhvv
                      offeringId:
                        type: string
                        minLength: 1
                        description: Required for SINGLE_SESSION items.
                        example: off_01kv60qge5eh59ap0gw0pqrrys
                      quantity:
                        type: integer
                        minimum: 1
                        description: Units to purchase (SINGLE_SESSION).
                        example: 1
                    required:
                      - skuType
                  default: []
                  description: Line items to purchase.
              required:
                - clientId
                - currency
      responses:
        '201':
          description: Order created
          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: >-
            Client, offering, project, reservation, or location not found
            (including a caller-supplied clientId/reservationId/locationId that
            does not resolve in this project)
          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); a line names a service that is not LIVE or
            was deleted, or an offering that is not ACTIVE (NOT_SELLABLE); or a
            PACKAGE line names a DRAFT or ARCHIVED package (PACKAGE_NOT_ACTIVE)
          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.