# Patch API V2
**Version**: 2  
**Description**: The core API used to integrate with Patch's service  
**Contact**: Developer Support (engineering@usepatch.com)

## Paths

### /v1/orders/{id}/cancel
**Patch**  
**Summary**: Cancel an order  
**Tags**: Orders  
**OperationId**: cancelOrder  
**Description**: Cancelling an order removes the associated offset allocation from an order. You will not be charged for cancelled orders. Only orders in the `draft` or `placed` state can be cancelled.  
**Parameters**:
- **id** (path, required, string)
- **Patch-Version** (header, integer)  
**Responses**:
- **200**: A placed order is cancellable
- **422**: A complete order is not cancellable
- **403**: An order that is not associated with the requester
- **404**: An order cannot be found

### /v1/orders
**Post**  
**Summary**: Creates an order  
**Tags**: Orders  
**OperationId**: createOrder  
**Description**: Creates an order in the `placed` or `draft`, or `reserved` state.  
**Parameters**:
- **Patch-Version** (header, integer)  
**Responses**:
- **201**: An order is created
- **404**: A request with a project that has no inventory available
- **422**: With too much mass  
**RequestBody**:
- **Content**: application/json  
  
  - **Schema**:
    - **Title**: create_order_request
    - **Type**: object  
    - **Properties**:
      - **project_id**: (string, nullable)
      - **metadata**: (object, nullable)
      - **state**: (string, enum: draft, reserved, placed, nullable)
      - **vintage_year**: (integer, 1900-2226, nullable)
      - **vintage_start_year**: (integer, 1900-2226, nullable)
      - **vintage_end_year**: (integer, 1900-2226, nullable)
      - **total_price**: (integer, minimum 2, nullable)
      - **currency**: (string, nullable)
      - **amount**: (integer, 0-100000000000000, nullable)
      - **unit**: (string, enum: g, nullable)
      - **issued_to**: (order_issued_to reference)

### /v1/orders/{uid}
**Delete**  
**Summary**: Deletes a draft order  
**Tags**: Orders  
**OperationId**: deleteOrder  
**Description**: Deletes an order that is in the `draft` state.  
**Parameters**:
- **uid** (path, required, string)
- **Patch-Version** (header, integer)  
**Responses**:
- **200**: An order line item is deleted
- **422**: Order is not a draft
- **404**: A request with an invalid order uid

### /v1/orders/{order_id}/line_items
**Post**  
**Summary**: Creates an order line item  
**Tags**: Order Line Items  
**OperationId**: createOrderLineItem  
**Description**: Creates a line item on an order that is in the `draft` state.  
**Parameters**:
- **order_id** (path, required, string)
- **Patch-Version** (header, integer)  
**Responses**:
- **201**: An order with total_price and foreign currency is created
- **404**: A request with a project that has no offsets available
- **422**: With too much mass  
**RequestBody**:
- **Content**: application/json  
  
  - **Schema**:
    - **Title**: create_order_line_item_request
    - **Type**: object  
    - **Properties**:
      - **project_id**: (string, required)
      - **vintage_year**: (integer, 1900-2226, nullable)
      - **vintage_start_year**: (integer, 1900-2226, nullable)
      - **vintage_end_year**: (integer, 1900-2226, nullable)
      - **price**: (integer, minimum 2, nullable)
      - **currency**: (string, nullable)
      - **amount**: (integer, 0-100000000000000, nullable)
      - **unit**: (string, enum: g, nullable)

### /v1/orders/{order_id}/line_items/{serial_number}
**Delete**  
**Summary**: Deletes an order line item  
**Tags**: Order Line Items  
**OperationId**: deleteOrderLineItem  
**Description**: Deletes a line item on an order that is in the `draft` state.  
**Parameters**:
- **order_id** (path, required, string)
- **serial_number** (path, required, string)
- **Patch-Version** (header, integer)  
**Responses**:
- **200**: An order line item is deleted
- **422**: Order is not a draft
- **404**: A request with an invalid serial number  
**Patch**
**Summary**: Updates an order line item  
**Tags**: Order Line Items  
**OperationId**: updateOrderLineItem  
**Description**: Updates a line item on an order that is in the `draft` state.  
**Parameters**:
- **order_id** (path, required, string)
- **serial_number** (path, required, string)
- **Patch-Version** (header, integer)  
**Responses**:
- **201**: An order line item is updated with a price and currency
- **422**: With too much mass  
**RequestBody**:
- **Content**: application/json  
  
  - **Schema**:
    - **Title**: update_order_line_item_request
    - **Type**: object  
    - **Properties**:
      - **vintage_year**: (integer, 1900-2226, nullable)
      - **vintage_start_year**: (integer, 1900-2226, nullable)
      - **vintage_end_year**: (integer, 1900-2226, nullable)
      - **price**: (integer, minimum 2, nullable)
      - **currency**: (string, nullable)
      - **amount**: (integer, 0-100000000000000, nullable)
      - **unit**: (string, enum: g, nullable)

### /v1/orders/{id}/place
**Patch**  
**Summary**: Place an order  
**Tags**: Orders  
**OperationId**: placeOrder  
**Description**: Placing an order confirms an order's allocation of offsets. Only orders that are in the `draft` state can be placed.  
**Parameters**:
- **id** (path, required, string)
- **Patch-Version** (header, integer)  
**Responses**:
- **200**: An order is placeable and issued_to is provided
- **422**: An order is not placeable  
**RequestBody**:
- **Content**: application/json  
  
  - **Schema**:
    - **Title**: place_order_request
    - **Type**: object  
    - **Properties**:
      - **issued_to**: (order_issued_to reference)

### /v1/orders/{id}
**Get**  
**Summary**: Retrieves an order  
**Tags**: Orders  
**OperationId**: retrieveOrder  
**Description**: Retrieves a given order and its allocation offsets or negative emissions. You can only retrieve orders associated with the organization you are querying for.  
**Parameters**:
- **id** (path, required, string)
- **Patch-Version** (header, integer)  
**Responses**:
- **404**: An non-existent order
- **200**: Returns the requested order

### /v1/projects
**Get**  
**Summary**: Retrieves a list of projects  
**Tags**: Projects  
**OperationId**: retrieveProjects  
**Description**: Retrieves a list of projects available for purchase on Patch's platform.  
**Parameters**:
- **page** (query, integer)
- **country** (query, string)
- **type** (query, string)
- **minimum_available_mass** (query, integer)
- **Accept-Language** (header, optional, string)
- **Patch-Version** (header, integer)  
**Responses**:
- **200**: Retrieves the available projects
- **422**: With malformed query params

### /v1/projects/{id}
**Get**  
**Summary**: Retrieves a project  
**Tags**: Projects  
**OperationId**: retrieveProject  
**Description**: Retrieves a project available on Patch's platform.  
**Parameters**:
- **id** (path, required, string)
- **Accept-Language** (header, optional, string)
- **Patch-Version** (header, integer)  
**Responses**:
- **404**: A non-existent project
- **403**: A production project with test credentials
- **200**: Returns the requested project

### /v1/projects/technology_types
**Get**  
**Summary**: Retrieves the list of technology_types  
**Tags**: TechnologyTypes  
**OperationId**: retrieveTechnologyTypes  
**Description**: Retrieves a list of all technology_types.  
**Parameters**:
- **Patch-Version** (header, integer)  
**Responses**:
- **200**: Retrieves the available technology_types