---
title: "Creates an order"
method: POST
path: "/v1/orders"
tags: ["Orders"]
---

# Creates an order

`POST /v1/orders`

Creates an order in the `placed` or `draft`, or `reserved` state.

## Headers

- `Patch-Version` integer

## Request body

- object
  - `mass_g` integer, nullable
  - `total_price_cents_usd` integer, nullable
  - `project_id` string, nullable
  - `metadata` object, nullable
  - `state` 'draft' | 'reserved' | 'placed', nullable
  - `vintage_year` integer, nullable
  - `total_price` integer, nullable
  - `currency` string, nullable
  - `amount` integer, nullable
  - `unit` 'g', nullable
  - `issued_to` OrderIssuedTo — An object containing the name & email of the party the inventory will be issued to.
    - `name` string, nullable — The name of the issuee
    - `email` string, nullable — The email address of the issuee

## Response `201`

an order is created

- object
  - `success` boolean, required
  - `error` object, nullable, required
  - `data` Order, required
    - `id` string, required — A unique uid for the record. UIDs will be prepended by ord_prod or ord_test depending on the mode it was created in.
    - `created_at` string, date-time — The timestamp at which the order was created
    - `mass_g` integer, required — DEPRECATED, use `amount` and `unit` fields instead. The amount of carbon offsets in grams purchased through this order.
    - `production` boolean, required — A boolean indicating if this order is a production or demo mode order.
    - `state` 'draft' | 'reserved' | 'placed' | 'processing' | 'complete' | 'cancelled', required — The current state of the order.
    - `amount` integer, required — The amount in `unit`s purchased through this order.
    - `unit` string, required — The unit of measurement (ie "g" or "Wh") for the `amount` ordered.
    - `price` integer, required — The total price for the `amount` ordered. Prices are always represented in the smallest currency unit (ie cents for USD).
    - `patch_fee` integer, required — The Patch Fee for this order. Patch Fee is always represented in the smallest currency unit (ie cents for USD).
    - `currency` string, required — The currency code for the `price` and `patch_fee`.
    - `allocation_state` 'allocated', required — DEPRECATED. Indicates if the order has been fully allocated to projects.
    - `price_cents_usd` integer, nullable, required — DEPRECATED, use the `price` and `currency` fields instead. The total price in cents USD of the carbon offsets purchased through this order.
    - `patch_fee_cents_usd` integer, nullable, required — DEPRECATED, use the `patch_fee` and `currency` fields instead. The Patch Fee in cents USD for this order.
    - `allocations` Allocation[] — DEPRECATED. An array containing the inventory allocations for this order.
      - `id` string, required — A unique uid for the record. UIDs will be prepended by all_prod or all_test depending on the mode it was created in.
      - `production` boolean, required — A boolean indicating if this project is a production or demo mode project.
      - `mass_g` integer, required — The amount (in grams) of allocated carbon offsets.
    - `registry_url` string — The URL of this order in the public registry. Use this URL to access the order's accompanying certificate.
    - `metadata` object, required — An optional JSON object containing metadata for this order.
    - `inventory` OrderInventory[] — An array containing the inventory allocated for this order. Inventory is grouped by project, vintage year, and price.
      - `project` OrderInventoryProject, required
        - `id` string, required — The unique uid for a project. UIDs will be prepended by pro_prod or pro_test depending on the mode it was created in.
        - `name` string, required — The name of the project.
      - `vintage_year` integer, required — The year in which the climate impacts of the project occurred, or will occur.
      - `amount` integer, required — The amount ordered for the given project and vintage year.
      - `unit` string, required — The unit of measurement (ie "g" or "Wh") for the `amount` ordered for the given project and vintage year.
      - `price` integer, required — The price for the given amount ordered for the given project and vintage year. Does not include any Patch fee. Prices are always represented in the smallest currency unit (ie cents for USD).
      - `currency` string, required — The currency code for the `price`.
    - `issued_to` OrderIssuedTo — An object containing the name & email of the party the inventory will be issued to.
      - `name` string, nullable — The name of the issuee
      - `email` string, nullable — The email address of the issuee

## Other responses

- `404` — a request with a project that has no inventory available
- `422` — with too much mass

---

[API](https://skmtc.dev/patch/apis/patch-api-v1.md) · [All operations](https://skmtc.dev/patch/apis/patch-api-v1/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/patch/patch-api-v1/revisions/9de29e2a01fc/schema)