> ## Documentation Index
> Fetch the complete documentation index at: https://c-mass.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Carbon Credits Order

> Submits an order for a specified amount of carbon credits (in kilograms) or a designated total price (in SAR halalas). The order remains in the `placed` state until it is matched with available credits, at which point it transitions to the `fulfilled` state. If a total price is specified, the system calculates the corresponding amount of carbon credits based on the unit price of the selected portfolio. Since carbon credits must be purchased in whole kilograms, the final total price may vary slightly from the initially specified amount.



## OpenAPI

````yaml POST /v1/orders
openapi: 3.0.1
info:
  title: c-mass API
  description: API for managing carbon credits, projects, portfolios, and orders
  version: 1.0.0
servers:
  - url: https://carbon-engine.onrender.com
security:
  - bearerAuth: []
paths:
  /v1/orders:
    post:
      tags:
        - Orders
      summary: Create a new carbon credits order
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - amount_kg
              properties:
                portfolioId:
                  type: string
                  description: The portfolio ID
                amount_kg:
                  type: number
                  description: >-
                    The amount of credits to purchase, in kg of CO2. Must be a
                    positive integer.
                description:
                  type: string
                  description: Description of the order
                customer:
                  type: string
                  description: Name of customer
      responses:
        '201':
          description: Order placed successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Order'
        '400':
          description: Missing required fields
        '500':
          description: Server error
      security:
        - bearerAuth: []
components:
  schemas:
    Order:
      type: object
      properties:
        _id:
          description: The unique order id
          type: string
        orderNumber:
          description: The unique order number
          type: string
        customer:
          description: If purchased by customer
          type: string
        description:
          description: Description of the order
          type: string
          nullable: true
        price_sar_halalas:
          description: Total price of the credits purchased in SAR halalas
          type: number
        amount_kg:
          description: Number of carbon credits requested, in kilograms
          type: number
        creditsPurchased:
          description: Number of carbon credits fulfilled, in kilograms
          type: number
        callbackUrl:
          description: Callback URL for order updates (if any)
          type: string
          nullable: true
        state:
          description: >-
            Current status of the order, e.g., `fulfilled`, `placed`, or
            `cancelled`
          type: string
        portfolio:
          description: The portfolio ID related to the order
          type: string
        certificateUrl:
          description: URL to the order page with the certificate of the carbon credits
          type: string
        projectRecords:
          description: List of project records for this order
          type: array
          items:
            type: object
            properties:
              project_id:
                description: The ID of the project
                type: string
              project_category_id:
                description: The category ID of the project
                type: string
              credit_batch_id:
                description: The batch ID for the credits in this project
                type: string
              delta:
                description: Amount of credits allocated to this project
                type: number
              recorded_on:
                description: Date when this allocation was recorded
                type: string
                format: date-time
        invoice:
          type: object
          properties:
            amountDueSarHalalas:
              description: The total amount due in SAR halalas
              type: number
            balanceAppliedSarHalalas:
              description: The balance applied to the invoice in SAR halalas
              type: number
            receiptUrl:
              description: URL to the receipt for this order
              type: string
              nullable: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````