Orb Item API

openapi: 3.2.0
info:
  title: Reference Item API
  description: 'Orb''s API is built with the following principles in mind:


    1. **Predictable developer experience**: Where applicable, the Orb API uses industry-standard patterns such as

    cursor-based pagination and standardized error output. To help with debugging in critical API

    actions, the API always strives to provide detailed and actionable error messages. Aliases

    such as external customer IDs aid in fast integration times.

    2. **Reliably real time**: Orb''s event-based APIs, such as event ingestion are designed to handle extremely high

    throughput and scale with concurrent load. Orb also provides a real-time event-level credits

    ledger and a highly performant webhooks architecture.

    3. **Flexibility at the forefront**: Features like timezone localization and the ability to amend historical usage

    show the flexible nature of the platform.


    You can download the latest OpenAPI spec here - pass `?version=3.0` for an

    OpenAPI 3.0-compatible spec.'
  contact:
    name: Orb, Inc.
    url: https://www.withorb.com/
    email: team@withorb.com
  version: '1.0'
servers:
- url: https://api.withorb.com/v1
  description: Production server
security:
- APIKeyAuth: []
tags:
- name: Item
  description: 'The Item resource represents a sellable product or good. Items are associated with all line items, billable metrics,

    and prices and are used for defining external sync behavior for invoices and tax calculation purposes.'
paths:
  /items:
    get:
      tags:
      - Item
      summary: List items
      description: This endpoint returns a list of all Items, ordered in descending order by creation time.
      operationId: list-items
      parameters:
      - required: false
        style: form
        schema:
          type: integer
          maximum: 100.0
          minimum: 1.0
          title: Limit
          description: The number of items to fetch. Defaults to 20.
          default: 20
        name: limit
        in: query
      - required: false
        style: form
        schema:
          oneOf:
          - type: string
          - type: 'null'
          title: Cursor
          description: Cursor for pagination. This can be populated by the `next_cursor` value returned from the initial request.
        name: cursor
        in: query
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Items'
        '400':
          description: Bad Request
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400Error'
        '401':
          description: Unauthorized
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401Error'
        '404':
          description: Not Found
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404Error'
        '409':
          description: Conflict
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/409Error'
        '413':
          description: Content Too Large
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/413Error'
        '429':
          description: Too Many Requests
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/429Error'
        '500':
          description: Internal Server Error
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/500Error'
    post:
      tags:
      - Item
      summary: Create item
      description: This endpoint is used to create an Item.
      operationId: create-item
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewItem'
        required: true
      responses:
        '201':
          description: Created
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
        '400':
          description: Bad Request
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400Error'
        '401':
          description: Unauthorized
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401Error'
        '404':
          description: Not Found
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404Error'
        '409':
          description: Conflict
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/409Error'
        '413':
          description: Content Too Large
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/413Error'
        '429':
          description: Too Many Requests
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/429Error'
        '500':
          description: Internal Server Error
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/500Error'
  /items/{item_id}:
    get:
      tags:
      - Item
      summary: Fetch item
      description: This endpoint returns an item identified by its item_id.
      operationId: fetch-item
      parameters:
      - required: true
        style: simple
        schema:
          type: string
        name: item_id
        in: path
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
        '400':
          description: Bad Request
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400Error'
        '401':
          description: Unauthorized
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401Error'
        '404':
          description: Not Found
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404Error'
        '409':
          description: Conflict
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/409Error'
        '413':
          description: Content Too Large
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/413Error'
        '429':
          description: Too Many Requests
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/429Error'
        '500':
          description: Internal Server Error
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/500Error'
    put:
      tags:
      - Item
      summary: Update item
      description: This endpoint can be used to update properties on the Item.
      operationId: update-item
      parameters:
      - required: true
        style: simple
        schema:
          type: string
        name: item_id
        in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MapItemRequestParams'
        required: true
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
        '400':
          description: Bad Request
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400Error'
        '401':
          description: Unauthorized
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401Error'
        '404':
          description: Not Found
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404Error'
        '409':
          description: Conflict
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/409Error'
        '413':
          description: Content Too Large
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/413Error'
        '429':
          description: Too Many Requests
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/429Error'
        '500':
          description: Internal Server Error
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/500Error'
  /items/{item_id}/archive:
    post:
      tags:
      - Item
      summary: Archive item
      description: 'This endpoint archives an item, and cascades to archive every price for that item that is still

        active. An item that is already archived cannot be archived again.'
      operationId: archive-item
      parameters:
      - required: true
        style: simple
        schema:
          type: string
        name: item_id
        in: path
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
        '400':
          description: Bad Request
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400Error'
        '401':
          description: Unauthorized
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401Error'
        '404':
          description: Not Found
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404Error'
        '409':
          description: Conflict
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/409Error'
        '413':
          description: Content Too Large
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/413Error'
        '429':
          description: Too Many Requests
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/429Error'
        '500':
          description: Internal Server Error
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/500Error'
components:
  schemas:
    RequestTooLargeError:
      properties:
        type:
          type: string
          enum:
          - https://docs.withorb.com/reference/error-responses#413-request-too-large
          title: Type
        status:
          type: integer
          enum:
          - 413
          title: Status
        detail:
          oneOf:
          - type: string
          - type: 'null'
          title: Detail
        title:
          oneOf:
          - type: string
          - type: 'null'
          title: Title
      type: object
      required:
      - type
      - status
      title: RequestTooLargeError
    401Error:
      $ref: '#/components/schemas/AuthorizationError'
      title: 401Error
    AuthorizationError:
      properties:
        type:
          type: string
          enum:
          - https://docs.withorb.com/reference/error-responses#401-authentication-error
          title: Type
        status:
          type: integer
          enum:
          - 401
          title: Status
        detail:
          oneOf:
          - type: string
          - type: 'null'
          title: Detail
        title:
          oneOf:
          - type: string
          - type: 'null'
          title: Title
      type: object
      required:
      - type
      - status
      title: AuthorizationError
    429Error:
      $ref: '#/components/schemas/TooManyRequests'
      title: 429Error
    FeatureNotAvailableError:
      properties:
        type:
          type: string
          enum:
          - https://docs.withorb.com/reference/error-responses#404-feature-not-available
          title: Type
        status:
          type: integer
          enum:
          - 400
          title: Status
        detail:
          oneOf:
          - type: string
          - type: 'null'
          title: Detail
        title:
          oneOf:
          - type: string
          - type: 'null'
          title: Title
      type: object
      required:
      - type
      - status
      title: FeatureNotAvailableError
    413Error:
      oneOf:
      - $ref: '#/components/schemas/RequestTooLargeError'
      - $ref: '#/components/schemas/ResourceTooLargeError'
      - $ref: '#/components/schemas/TooManyResultsError'
    IdempotencyRequestMismatch:
      properties:
        type:
          type: string
          enum:
          - https://docs.withorb.com/reference/error-responses#409-resource-conflict
          title: Type
        status:
          type: integer
          enum:
          - 409
          title: Status
        detail:
          oneOf:
          - type: string
          - type: 'null'
          title: Detail
        title:
          oneOf:
          - type: string
          - type: 'null'
          title: Title
      type: object
      required:
      - type
      - status
      title: IdempotencyRequestMismatch
    Item:
      properties:
        metadata:
          additionalProperties:
            type: string
          type: object
          title: Metadata
          description: User specified key-value pairs for the resource. If not present, this defaults to an empty dictionary. Individual keys can be removed by setting the value to `null`, and the entire metadata mapping can be cleared by setting `metadata` to `null`.
        id:
          type: string
          title: Id
          description: The Orb-assigned unique identifier for the item.
        name:
          type: string
          title: Name
          description: The name of the item.
        created_at:
          type: string
          format: date-time
          title: Created At
          description: The time at which the item was created.
        external_connections:
          items:
            $ref: '#/components/schemas/ItemExternalConnection'
          type: array
          title: External Connections
          description: A list of external connections for this item, used to sync with external invoicing and tax systems.
        archived_at:
          oneOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Archived At
          description: The time at which the item was archived. If null, the item is not archived.
      type: object
      required:
      - metadata
      - id
      - name
      - created_at
      - external_connections
      title: Item
      description: 'The Item resource represents a sellable product or good. Items are associated with all line items, billable metrics,

        and prices and are used for defining external sync behavior for invoices and tax calculation purposes.'
    MapItemRequestParams:
      properties:
        metadata:
          oneOf:
          - additionalProperties:
              oneOf:
              - type: string
              - type: 'null'
            type: object
          - type: 'null'
          title: Metadata
          description: User-specified key/value pairs for the resource. Individual keys can be removed by setting the value to `null`, and the entire metadata mapping can be cleared by setting `metadata` to `null`.
        name:
          oneOf:
          - type: string
          - type: 'null'
          title: Name
        external_connections:
          oneOf:
          - items:
              $ref: '#/components/schemas/ItemExternalConnection'
            type: array
          - type: 'null'
          title: External Connections
      additionalProperties: false
      type: object
      title: MapItemRequestParams
      description: 'A list of external connections to map an item to. Note that passing `null` will clear existing mappings.

        Orb requires that you pass the full list of mappings; this list will replace the existing item mappings.'
    Items:
      properties:
        data:
          items:
            $ref: '#/components/schemas/Item'
          type: array
          title: Data
        pagination_metadata:
          $ref: '#/components/schemas/PaginationMetadata'
      type: object
      required:
      - data
      - pagination_metadata
      title: Items
    TooManyRequests:
      properties:
        type:
          type: string
          enum:
          - https://docs.withorb.com/reference/error-responses#429-too-many-requests
          title: Type
        status:
          type: integer
          enum:
          - 429
          title: Status
        detail:
          oneOf:
          - type: string
          - type: 'null'
          title: Detail
        title:
          oneOf:
          - type: string
          - type: 'null'
          title: Title
      type: object
      required:
      - type
      - status
      title: TooManyRequests
    ResourceTooLargeError:
      properties:
        type:
          type: string
          enum:
          - https://docs.withorb.com/reference/error-responses#413-resource-too-large
          title: Type
        status:
          type: integer
          enum:
          - 413
          title: Status
        detail:
          oneOf:
          - type: string
          - type: 'null'
          title: Detail
        title:
          oneOf:
          - type: string
          - type: 'null'
          title: Title
      type: object
      required:
      - type
      - status
      title: ResourceTooLargeError
    409Error:
      $ref: '#/components/schemas/IdempotencyRequestMismatch'
      title: 409Error
    ItemExternalConnection:
      properties:
        external_connection_name:
          oneOf:
          - type: string
            enum:
            - stripe
            - quickbooks
            - bill.com
            - netsuite
          - type: string
            enum:
            - taxjar
            - avalara
            - anrok
            - numeral
            - stripe_tax
          title: External Connection Name
          description: The name of the external system this item is connected to.
        external_entity_id:
          type: string
          title: External Entity Id
          description: The identifier of this item in the external system.
      type: object
      required:
      - external_connection_name
      - external_entity_id
      title: ItemExternalConnection
      description: Represents a connection between an Item and an external system for invoicing or tax calculation purposes.
    TooManyResultsError:
      properties:
        type:
          type: string
          enum:
          - https://docs.withorb.com/reference/error-responses#413-too-many-results
          title: Type
        status:
          type: integer
          enum:
          - 413
          title: Status
        detail:
          oneOf:
          - type: string
          - type: 'null'
          title: Detail
        title:
          oneOf:
          - type: string
          - type: 'null'
          title: Title
      type: object
      required:
      - type
      - status
      title: TooManyResultsError
    PaginationMetadata:
      properties:
        has_more:
          type: boolean
          title: Has More
        next_cursor:
          oneOf:
          - type: string
          - type: 'null'
          title: Next Cursor
      type: object
      required:
      - has_more
      - next_cursor
      title: PaginationMetadata
    ServerError:
      properties:
        type:
          type: string
          enum:
          - https://docs.withorb.com/reference/error-responses#500-internal-server-error
          title: Type
        status:
          type: integer
          title: Status
        detail:
          oneOf:
          - type: string
          - type: 'null'
          title: Detail
        title:
          oneOf:
          - type: string
          - type: 'null'
          title: Title
      type: object
      required:
      - type
      - status
      title: ServerError
    ResourceNotFoundError:
      properties:
        type:
          type: string
          enum:
          - https://docs.withorb.com/reference/error-responses#404-resource-not-found
          title: Type
        status:
          type: integer
          enum:
          - 404
          title: Status
        detail:
          oneOf:
          - type: string
          - type: 'null'
          title: Detail
        title:
          type: string
          title: Title
      type: object
      required:
      - type
      - status
      - title
      title: ResourceNotFoundError
    404Error:
      oneOf:
      - $ref: '#/components/schemas/FeatureNotAvailableError'
      - $ref: '#/components/schemas/ResourceNotFoundError'
      - $ref: '#/components/schemas/URLNotFound'
    URLNotFound:
      properties:
        type:
          type: string
          enum:
          - https://docs.withorb.com/reference/error-responses#404-url-not-found
          title: Type
        status:
          type: integer
          enum:
          - 404
          title: Status
        detail:
          oneOf:
          - type: string
          - type: 'null'
          title: Detail
        title:
          oneOf:
          - type: string
          - type: 'null'
          title: Title
      type: object
      required:
      - type
      - status
      title: URLNotFound
    NewItem:
      properties:
        metadata:
          oneOf:
          - additionalProperties:
              oneOf:
              - type: string
              - type: 'null'
            type: object
          - type: 'null'
          title: Metadata
          description: User-specified key/value pairs for the resource. Individual keys can be removed by setting the value to `null`, and the entire metadata mapping can be cleared by setting `metadata` to `null`.
        name:
          type: string
          title: Name
          description: The name of the item.
          examples:
          - API requests
      additionalProperties: false
      type: object
      required:
      - name
      title: NewItem
    DuplicateResourceCreationError:
      properties:
        type:
          type: string
          enum:
          - https://docs.withorb.com/reference/error-responses#400-duplicate-resource-creation
          title: Type
        status:
          type: integer
          enum:
          - 400
          title: Status
        detail:
          oneOf:
          - type: string
          - type: 'null'
          title: Detail
        title:
          oneOf:
          - type: string
          - type: 'null'
          title: Title
      type: object
      required:
      - type
      - status
      title: DuplicateResourceCreationError
    RequestValidationError:
      properties:
        type:
          type: string
          enum:
          - https://docs.withorb.com/reference/error-responses#400-request-validation-errors
          title: Type
        status:
          type: integer
          enum:
          - 400
          title: Status
        detail:
          oneOf:
          - type: string
          - type: 'null'
          title: Detail
        title:
          oneOf:
          - type: string
          - type: 'null'
          title: Title
        validation_errors:
          items: {}
          type: array
          title: Validation Errors
      type: object
      required:
      - type
      - status
      - validation_errors
      title: RequestValidationError
    400Error:
      oneOf:
      - $ref: '#/components/schemas/ConstraintViolationError'
      - $ref: '#/components/schemas/DuplicateResourceCreationError'
      - $ref: '#/components/schemas/RequestValidationError'
    500Error:
      $ref: '#/components/schemas/ServerError'
      title: 500Error
    ConstraintViolationError:
      properties:
        type:
          type: string
          enum:
          - https://docs.withorb.com/reference/error-responses#400-constraint-violation
          title: Type
        status:
          type: integer
          enum:
          - 400
          title: Status
        detail:
          oneOf:
          - type: string
          - type: 'null'
          title: Detail
        title:
          oneOf:
          - type: string
          - type: 'null'
          title: Title
      type: object
      required:
      - type
      - status
      title: ConstraintViolationError
  securitySchemes:
    APIKeyAuth:
      type: http
      description: API Keys can be issued in the Orb's web application.
      scheme: bearer
x-provenance:
  method: harvested
  publisher: Orb
  source: https://docs.withorb.com/api-reference/orb-openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)