openapi: 3.0.3
info:
  title: Patch Order Line Items API
  description: 'The Patch REST API allows developers to access the full carbon removal marketplace, create and manage orders for carbon offsets, retrieve estimates for CO2 compensation costs, browse available carbon projects, and integrate sustainability features into applications. Authentication is via Bearer token API keys obtained from the Patch dashboard, with separate test and production key environments supported.

    '
  version: '2'
  contact:
    email: engineering@usepatch.com
  x-api-id: patch:patch-api
servers:
- url: https://api.patch.io
  description: Patch API production server
security:
- bearer_auth: []
tags:
- name: Order Line Items
  description: Manage individual line items within draft orders
paths:
  /v1/orders/{order_id}/line_items:
    post:
      summary: Creates an order line item
      description: Creates a line item on an order that is in the `draft` state.
      operationId: create_order_line_item
      tags:
      - Order Line Items
      parameters:
      - name: order_id
        in: path
        required: true
        schema:
          type: string
        description: The order ID
      - name: Patch-Version
        in: header
        schema:
          type: integer
          default: 2
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderLineItemRequest'
      responses:
        '200':
          description: The created order line item
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderLineItemResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/orders/{order_id}/line_items/{serial_number}:
    patch:
      summary: Updates an order line item
      description: Updates a line item on an order that is in the `draft` state.
      operationId: update_order_line_item
      tags:
      - Order Line Items
      parameters:
      - name: order_id
        in: path
        required: true
        schema:
          type: string
        description: The order ID
      - name: serial_number
        in: path
        required: true
        schema:
          type: string
        description: The line item serial number
      - name: Patch-Version
        in: header
        schema:
          type: integer
          default: 2
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOrderLineItemRequest'
      responses:
        '200':
          description: The updated order line item
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderLineItemResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      summary: Deletes an order line item
      description: Deletes a line item on an order that is in the `draft` state.
      operationId: delete_order_line_item
      tags:
      - Order Line Items
      parameters:
      - name: order_id
        in: path
        required: true
        schema:
          type: string
        description: The order ID
      - name: serial_number
        in: path
        required: true
        schema:
          type: string
        description: The line item serial number
      - name: Patch-Version
        in: header
        schema:
          type: integer
          default: 2
      responses:
        '200':
          description: The deleted order line item confirmation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteOrderLineItemResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorResponse:
      type: object
      description: API error response
      properties:
        success:
          type: boolean
          example: false
          description: Always false for error responses
        error:
          type: string
          description: Error message describing what went wrong
    CreateOrderLineItemRequest:
      type: object
      description: Request body for creating an order line item
      required:
      - project_id
      properties:
        project_id:
          type: string
          description: ID of the carbon project for this line item
        vintage_year:
          type: integer
          description: Specific vintage year for the carbon credits
        vintage_start_year:
          type: integer
          description: Start year of the vintage range
        vintage_end_year:
          type: integer
          description: End year of the vintage range
        price:
          type: integer
          description: Price in the smallest currency unit
        currency:
          type: string
          description: ISO 4217 currency code
        amount:
          type: integer
          description: Amount of carbon offset in grams of CO2 equivalent
        unit:
          type: string
          description: Unit of measurement
    OrderLineItemResponse:
      type: object
      description: API response wrapping an OrderLineItem
      properties:
        success:
          type: boolean
          description: Whether the request was successful
        error:
          type: string
          nullable: true
          description: Error message if the request failed
        data:
          $ref: '#/components/schemas/OrderLineItem'
    OrderLineItemProject:
      type: object
      description: Project reference within an order line item
      properties:
        id:
          type: string
          description: Project identifier
        name:
          type: string
          description: Project name
    OrderLineItem:
      type: object
      description: An individual line item within an order
      properties:
        id:
          type: string
          description: Unique identifier for the line item
        project:
          $ref: '#/components/schemas/OrderLineItemProject'
        vintage_year:
          type: integer
          description: Specific vintage year for the carbon credits
        vintage_start_year:
          type: integer
          description: Start year of the vintage range
        vintage_end_year:
          type: integer
          description: End year of the vintage range
        amount:
          type: integer
          description: Amount of carbon offset in grams of CO2 equivalent
        unit:
          type: string
          description: Unit of measurement
        price:
          type: integer
          description: Price in the smallest currency unit
        currency:
          type: string
          description: ISO 4217 currency code
    UpdateOrderLineItemRequest:
      type: object
      description: Request body for updating an order line item
      properties:
        vintage_year:
          type: integer
          description: Specific vintage year for the carbon credits
        vintage_start_year:
          type: integer
          description: Start year of the vintage range
        vintage_end_year:
          type: integer
          description: End year of the vintage range
        price:
          type: integer
          description: Price in the smallest currency unit
        currency:
          type: string
          description: ISO 4217 currency code
        amount:
          type: integer
          description: Amount of carbon offset in grams of CO2 equivalent
        unit:
          type: string
          description: Unit of measurement
    DeleteOrderLineItemResponse:
      type: object
      description: API response confirming order line item deletion
      properties:
        success:
          type: boolean
          description: Whether the deletion was successful
        error:
          type: string
          nullable: true
          description: Error message if the deletion failed
        data:
          type: object
          properties:
            id:
              type: string
              description: ID of the deleted line item
  securitySchemes:
    bearer_auth:
      type: http
      scheme: bearer
      description: 'Bearer token API key obtained from the Patch dashboard. Use test keys for sandbox and production keys for live orders.

        '