Rentle Orders API

openapi: 3.0.0
info:
  title: Twice Admin API Keys Orders API
  description: API documentation for Twice Admin API
  version: '2023-02-01'
  contact: {}
  x-logo:
    url: https://firebasestorage.googleapis.com/v0/b/rentle-prod.appspot.com/o/logos%2Ftwice-logo-outline-black-padded.png?alt=media&token=c6731aba-03c9-4ce9-a9f0-a68478924fe0
servers:
- url: https://api.twicecommerce.com/admin
  description: Production API
tags:
- name: Orders
  description: Order-related queries
paths:
  /orders/{id}:
    get:
      description: Retrieves a single order by id.
      operationId: orders_get
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: x-rentle-version
        in: header
        description: API Version, e.g `2023-02-01`. See [versioning](/#tag/versioning) page for more details.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderDTO'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestExceptionDTO'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenExceptionDTO'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundExceptionDTO'
        '409':
          description: Conflict.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictExceptionDTO'
        '429':
          description: Quota exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuotaExceededExceptionDTO'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorExceptionDTO'
      summary: Get order
      tags:
      - Orders
    patch:
      description: Update fields of an existing order.
      operationId: orders_update
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: x-rentle-version
        in: header
        description: API Version, e.g `2023-02-01`. See [versioning](/#tag/versioning) page for more details.
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOrderDTO'
      responses:
        '200':
          description: Order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderDTO'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestExceptionDTO'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenExceptionDTO'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundExceptionDTO'
        '409':
          description: Conflict.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictExceptionDTO'
        '429':
          description: Quota exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuotaExceededExceptionDTO'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorExceptionDTO'
      summary: Update order
      tags:
      - Orders
  /orders:
    get:
      description: Retrieves all orders of the authenticated merchant.
      operationId: orders_list
      parameters:
      - name: limit
        required: false
        in: query
        description: How many objects to retrieve.
        x-nestjs_zod-parent-metadata:
          title: Order Query Parameters
        schema:
          minimum: 1
          maximum: 100
          type: integer
      - name: pageToken
        required: false
        in: query
        description: Token to retrieve the next page of results. This is returned in the paged response.
        x-nestjs_zod-parent-metadata:
          title: Order Query Parameters
        schema:
          minLength: 1
          type: string
      - name: createdAt
        required: false
        in: query
        description: Filter by order creation date in ISO 8601 format, e.g., `?createdAt[lt]=2023-04-05T20:00:00.000Z`
        x-nestjs_zod-parent-metadata:
          title: Order Query Parameters
        schema:
          properties:
            gt:
              title: ISO 8601 date-time
              description: Date-time in ISO 8601 format.
              type: string
            gte:
              title: ISO 8601 date-time
              description: Date-time in ISO 8601 format.
              type: string
            lt:
              title: ISO 8601 date-time
              description: Date-time in ISO 8601 format.
              type: string
            lte:
              title: ISO 8601 date-time
              description: Date-time in ISO 8601 format.
              type: string
          type: object
        style: deepObject
      - name: storeId
        required: false
        in: query
        description: Comma-separated id of stores to filter by.
        x-nestjs_zod-parent-metadata:
          title: Order Query Parameters
        schema:
          example: 123,321
          type: string
      - name: x-rentle-version
        in: header
        description: API Version, e.g `2023-02-01`. See [versioning](/#tag/versioning) page for more details.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Paginated list of orders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedOrdersDTO'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestExceptionDTO'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenExceptionDTO'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundExceptionDTO'
        '409':
          description: Conflict.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictExceptionDTO'
        '429':
          description: Quota exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuotaExceededExceptionDTO'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorExceptionDTO'
      summary: Get all orders
      tags:
      - Orders
    post:
      description: Create a new order.
      operationId: orders_create
      parameters:
      - name: x-rentle-version
        in: header
        description: API Version, e.g `2023-02-01`. See [versioning](/#tag/versioning) page for more details.
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderDTO'
      responses:
        '201':
          description: Order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderDTO'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestExceptionDTO'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenExceptionDTO'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundExceptionDTO'
        '409':
          description: Conflict.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictExceptionDTO'
        '429':
          description: Quota exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuotaExceededExceptionDTO'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorExceptionDTO'
      summary: Create order
      tags:
      - Orders
components:
  schemas:
    ConflictExceptionDTO:
      type: object
      properties:
        error:
          type: object
          properties:
            status:
              description: HTTP status code of the response.
              type: number
            code:
              description: Internal text code that represents the type of error.
              type: string
            message:
              description: Human-friendly description of the error
              type: string
            details:
              description: Details about errors in the request body
              type: array
              items:
                type: object
                properties:
                  path:
                    description: Path to the key in the request body, splitted by parts.
                    type: array
                    items:
                      type: string
                  message:
                    description: Specific errors in the value of the field.
                    type: string
                required:
                - path
                - message
          required:
          - status
          - code
          - message
      required:
      - error
      title: Conflict
      example:
        error:
          status: 409
          code: CONFLICT
          message: Conflict error
    OrderDTO:
      type: object
      properties:
        id:
          description: Unique order identifier.
          type: string
        createdAt:
          title: ISO 8601 date-time
          description: Order creation date.
          type: string
        startDate:
          title: ISO 8601 date-time
          description: Start date of order.
          type: string
        initialStartDate:
          title: ISO 8601 date-time
          description: Initial start date of order.
          type: string
        endDate:
          title: ISO 8601 date-time
          description: End date of order. This will show the initial end date even when the order is returned.
          type: string
        returnedDate:
          description: Date when order was returned. If order is not returned, this field is not present.
          title: ISO 8601 date-time
          type: string
        payment:
          description: Payment details for the order.
          type: object
          properties:
            paid:
              description: Paid amount.
              type: integer
              minimum: 0
              maximum: 9007199254740991
            refunded:
              description: Refunded amount.
              type: integer
              minimum: 0
              maximum: 9007199254740991
            authorised:
              description: Authorised amount.
              type: integer
              minimum: 0
              maximum: 9007199254740991
            cancelled:
              description: Cancelled amount.
              type: integer
              minimum: 0
              maximum: 9007199254740991
            captured:
              description: Captured amount.
              type: integer
              minimum: 0
              maximum: 9007199254740991
          required:
          - paid
        deposit:
          description: Deposit details for the order.
          type: object
          properties:
            paid:
              description: Paid amount.
              type: integer
              minimum: 0
              maximum: 9007199254740991
            refunded:
              description: Refunded amount.
              type: integer
              minimum: 0
              maximum: 9007199254740991
            authorised:
              description: Authorised amount.
              type: integer
              minimum: 0
              maximum: 9007199254740991
            cancelled:
              description: Cancelled amount.
              type: integer
              minimum: 0
              maximum: 9007199254740991
            captured:
              description: Captured amount.
              type: integer
              minimum: 0
              maximum: 9007199254740991
          required:
          - paid
        cancellationPolicy:
          description: Order cancellation policy.
          type: array
          items:
            example:
              hoursBefore: 24
              refundPercentage: 50
              displayAs: days
            type: object
            properties:
              hoursBefore:
                description: Hours before the start of the booking when the cancellation is possible.
                type: integer
                minimum: 0
                maximum: 9007199254740991
              refundPercentage:
                description: Percentage of the booking price that will be refunded.
                type: integer
                minimum: 0
                maximum: 100
              displayAs:
                description: Display unit of the cancellation period.
                default: hours
                type: string
                enum:
                - hours
                - days
                - weeks
            required:
            - hoursBefore
            - refundPercentage
        channel:
          description: Channel where the order was created. All orders created via API will have the channel `api`.
          type: string
          enum:
          - admin
          - check_in
          - online
          - booking_link
          - api
          - wix
        state:
          description: Current state of the order.
          type: string
          enum:
          - booked
          - active
          - cancelled
          - completed
        store:
          description: Store where the order belongs to.
          type: object
          properties:
            name:
              description: Name of the store.
              type: string
            storeId:
              description: ID of the store.
              type: string
            address:
              description: Address of the store.
              type: object
              properties:
                address:
                  description: Street address.
                  type: string
                zipCode:
                  description: Zip code.
                  type: string
                city:
                  description: City.
                  type: string
                country:
                  description: Country.
                  type: string
                state:
                  description: State.
                  type: string
                details:
                  description: Additional address details.
                  type: string
              required:
              - address
          required:
          - name
          - storeId
          - address
        customCheckoutFields:
          description: Custom checkout fields filled by the customer during checkout.
          type: array
          items:
            type: object
            properties:
              label:
                title: Localized field
                description: Label of the custom checkout field
                allOf:
                - additionalProperties:
                    type: string
                    description: The property name is the locale code, and the value is the translated text in that locale.
                  type: object
                - type: object
                  properties:
                    def:
                      description: The value in default locale.
                      type: string
                  required:
                  - def
              value:
                description: Value provided by the customer on checkout. The value can be null if the customer did not fill in a checkout field.
                anyOf:
                - type: string
                  nullable: true
                - type: boolean
            required:
            - label
            - value
        customerDetails:
          description: Details of the person who made the order.
          type: object
          properties:
            firstName:
              description: First name of the customer.
              type: string
            lastName:
              description: Last name of the customer.
              type: string
            phone:
              description: Phone number of the customer.
              type: string
            email:
              description: Email of the customer.
              type: string
            marketingConsent:
              description: Whether the customer has given marketing consent.
              type: boolean
            language:
              description: Language of the customer.
              type: string
              enum:
              - fi
              - en
              - ru
              - de
              - sk
              - sv
              - nl
              - hu
              - 'no'
              - fr
              - es
              - it
              - cs
              - da
              - lt
              - et
              - pl
              - sl
              - hr
              - pt
              - br
              - lv
              - tr
              - uk
            address:
              description: Address of the customer.
              type: object
              properties:
                address:
                  description: Street address.
                  type: string
                zipCode:
                  description: Zip code.
                  type: string
                city:
                  description: City.
                  type: string
                country:
                  description: Country.
                  type: string
                state:
                  description: State.
                  type: string
                details:
                  description: Additional address details.
                  type: string
              required:
              - address
            metafields:
              title: Metafields
              description: Additional metafields added to the resource. Each key is a namespace for the metafield group, and the value of each key should be an object, including the data for that metafield namespace as key-value pairs.
              type: object
              additionalProperties:
                type: object
                additionalProperties: {}
            customerId:
              type: string
              description: Unique identifier of the customer.
              nullable: true
          required:
          - firstName
          - lastName
          - phone
          - email
          - marketingConsent
          - customerId
        terms:
          description: Order terms acceptance information.
          type: object
          properties:
            accepted:
              description: Whether the terms were accepted.
              type: boolean
            timestamp:
              description: Timestamp when the terms were accepted.
              title: ISO 8601 date-time
              type: string
          required:
          - accepted
        staffComment:
          description: Internal comment about the order, added by the store staff.
          type: string
        orderNumber:
          description: Order number. May not be present if the order number has not been generated yet.
          type: integer
          minimum: 0
          maximum: 9007199254740991
        externalOrderNumber:
          description: External order number, e.g. from an integrated system. If present, this is typically displayed instead of the internal order number.
          type: string
        prepared:
          description: Whether the order has been marked as prepared.
          type: boolean
        pricing:
          description: Order pricing information.
          type: object
          properties:
            currency:
              description: Currency of the price.
              type: string
            total:
              description: Total price. Includes taxes and discounts.
              type: integer
              minimum: 0
              maximum: 9007199254740991
            subtotal:
              description: Subtotal price. Does not include taxes if pricing has taxes excluded, defined in `taxExcluded`.
              type: integer
              minimum: 0
              maximum: 9007199254740991
            totalTaxes:
              description: Total taxes.
              type: integer
              minimum: 0
              maximum: 9007199254740991
            totalDiscounts:
              description: Total discounts value.
              type: integer
              minimum: 0
              maximum: 9007199254740991
            taxExcluded:
              description: Whether taxes are excluded from the list prices.
              type: boolean
            taxLines:
              description: List of tax lines of the price.
              type: array
              items:
                type: object
                properties:
                  price:
                    description: Price of the tax in minor units
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  rate:
                    description: Tax rate in decimals
                    type: number
                    minimum: 0
                required:
                - price
                - rate
            manualDiscount:
              description: Applied manual discount.
              type: object
              properties:
                percentage:
                  description: Percentage of the discount, if discount was given as percentage
                  type: integer
                  minimum: 0
                  maximum: 100
                value:
                  description: Discount value in minor units
                  type: integer
                  minimum: 0
                  maximum: 9007199254740991
              required:
              - value
            discountCodes:
              description: List of discount codes.
              type: array
              items:
                type: object
                properties:
                  code:
                    description: Discount code.
                    type: string
                  quantity:
                    description: How many times the code was used.
                    type: integer
                    minimum: 0
                    maximum: 9007199254740991
                  value:
                    description: Discount value in minor units.
                    type: integer
                    minimum: 0
                    maximum: 9007199254740991
                required:
                - code
                - quantity
                - value
            deposit:
              description: Deposit information.
              type: object
              properties:
                value:
                  description: Deposit value in minor units.
                  type: integer
                  minimum: 0
                  maximum: 9007199254740991
                type:
                  description: Deposit type.
                  type: string
                  enum:
                  - payment
                  - other
                  - no-deposit
              required:
              - value
              - type
          required:
          - currency
          - total
          - subtotal
          - totalTaxes
          - totalDiscounts
          - taxExcluded
          - taxLines
        bookingComment:
          description: Custom comment field filled during the booking.
          type: object
          properties:
            label:
              title: Localized field
              description: Label of the comment.
              allOf:
              - additionalProperties:
                  type: string
                  description: The property name is the locale code, and the value is the translated text in that locale.
                type: object
              - type: object
                properties:
                  def:
                    description: The value in default locale.
                    type: string
                required:
                - def
            value:
              description: Value of the comment.
              type: string
          required:
          - label
          - value
        metafields:
          allOf:
          - title: Metafields
            description: Additional metafields added to the resource. Each key is a namespace for the metafield group, and the value of each key should be an object, including the data for that metafield namespace as key-value pairs.
            type: object
            additionalProperties:
              type: object
              additionalProperties: {}
          - type: object
            properties:
              skiData:
                type: object
                properties:
                  confirmationNumber:
                    type: string
        persons:
          description: List of the persons in the order.
          type: array
          items:
            example:
              firstName: John
              lastName: Doe
              phone: '+1555555555'
              email: john@doe.com
              marketingConsent: true
              language: en
              address:
                address: 123 Main St
                zipCode: '12345'
                city: New York
                country: United States
                state: New York
              customerId: bcxIwN2buWMAKmUvrF2m
              id: NfjKuaQ9fynvocgMRtb7
              createdAt: '2026-07-19T01:04:27.140Z'
              isLiableCustomer: true
              additionalDetails: []
              staffComment: This customer will arrive 15min late
              itemIds:
              - GNjXy7PiD2nEz2qELgRy
            type: object
            properties:
              firstName:
                description: First name of the person.
                type: string
              lastName:
                description: Last name of the person.
                type: string
              phone:
                description: Phone number of the person.
                type: string
              email:
                description: Email of the person.
                type: string
              marketingConsent:
                description: Whether the person has given marketing consent.
                type: boolean
              language:
                description: Language of the person.
                type: string
                enum:
                - fi
                - en
                - ru
                - de
                - sk
                - sv
                - nl
                - hu
                - 'no'
                - fr
                - es
                - it
                - cs
                - da
                - lt
                - et
                - pl
                - sl
                - hr
                - pt
                - br
                - lv
                - tr
                - uk
              address:
                description: Address of the person.
                type: object
                properties:
                  address:
                    description: Street address.
                    type: string
                  zipCode:
                    description: Zip code.
                    type: string
                  city:
                    description: City.
                    type: string
                  country:
                    description: Country.
                    type: string
                  state:
                    description: State.
                    type: string
                  details:
                    description: Additional address details.
                    type: string
                required:
                - address
              metafields:
                title: Metafields
                description: Additional metafields added to the resource. Each key is a namespace for the metafield group, and the value of each key should be an object, including the data for that metafield namespace as key-value pairs.
                type: object
                additionalProperties:
                  type: object
                  additionalProperties: {}
              customerId:
                type: string
                description: Unique identifier of the customer.
                nullable: true
              id:
                description: Unique ID of the person
                type: string
              createdAt:
                title: ISO 8601 date-time
                description: Person creation date
                type: string
              isLiableCustomer:
                description: Whether the person is the liable customer of the order
                type: boolean
              segment:
                description: Segment of the person, if defined
                type: string
                enum:
                - kid
                - teen
                - adult
                - senior
              additionalDetails:
                description: Additional person details
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                    unit:
                      type: string
                      nullable: true
                    value:
                      type: string
                  required:
                  - name
                  - unit
                  - value
              staffComment:
                description: Internal comment about the person, added by the store staff.
                type: string
              itemIds:
                description: List of the item IDs of the order that belongs to the person
                type: array
                items:
                  type: string
            required:
            - firstName
            - marketingConsent
            - customerId
            - id
            - createdAt
            - isLiableCustomer
            - itemIds
        items:
          description: List of order items.
          type: array
          items:
            example:
              id: GNjXy7PiD2nEz2qELgRy
              productId: fUNFcX1VMTKHNrEgSOu9
              name:
                def: Product name
              itemCodes:
              - PRD-1
              variantId: OwH3rwAUOzNAYFySaEZl
              variantValues:
              - def: Variant name
              startDate: '2026-07-20T01:00:00.000Z'
              endDate: '2026-07-21T01:00:00.000Z'
              durationPeriod: 24h
              customDurationLabel:
                def: 1 day
              cancelled: false
              payment:
                paid: 8000
                refunded: 0
                au

# --- truncated at 32 KB (187 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/rentle/refs/heads/main/openapi/rentle-orders-api-openapi.yml