{"openapi":"3.0.1","tags":[{"name":"Orders"},{"name":"Projects"},{"name":"TechnologyTypes"}],"info":{"title":"Patch API V1","version":"1","description":"The core API used to integrate with Patch's service","contact":{"name":"Developer Support","email":"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.\n","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Patch-Version","in":"header","schema":{"type":"integer"}}],"responses":{"200":{"description":"a placed order is cancellable","content":{"application/json":{"schema":{"title":"order_response","type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","nullable":true},"data":{"$ref":"#/components/schemas/order"}},"required":["success","error","data"]}}}},"422":{"description":"a complete order is not cancellable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}},"403":{"description":"an order that is not associated with the requester","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}},"404":{"description":"an order cannot be found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}}}}},"/v1/orders":{"post":{"summary":"Creates an order","tags":["Orders"],"operationId":"createOrder","description":"Creates an order in the `placed` or `draft`, or `reserved` state.\n","parameters":[{"name":"Patch-Version","in":"header","schema":{"type":"integer"}}],"responses":{"201":{"description":"an order is created","content":{"application/json":{"schema":{"title":"order_response","type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","nullable":true},"data":{"$ref":"#/components/schemas/order"}},"required":["success","error","data"]}}}},"404":{"description":"a request with a project that has no inventory available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}},"422":{"description":"with too much mass","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}}},"requestBody":{"content":{"application/json":{"schema":{"title":"create_order_request","type":"object","properties":{"mass_g":{"type":"integer","maximum":100000000000000,"minimum":0,"nullable":true},"total_price_cents_usd":{"type":"integer","minimum":2,"nullable":true},"project_id":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"state":{"type":"string","enum":["draft","reserved","placed"],"nullable":true},"vintage_year":{"type":"integer","maximum":2226,"minimum":1900,"nullable":true},"total_price":{"type":"integer","minimum":2,"nullable":true},"currency":{"type":"string","nullable":true},"amount":{"type":"integer","maximum":100000000000000,"minimum":0,"nullable":true},"unit":{"type":"string","enum":["g"],"nullable":true},"issued_to":{"$ref":"#/components/schemas/order_issued_to"}}}}},"required":true}},"get":{"summary":"Retrieves a list of orders","tags":["Orders"],"operationId":"retrieveOrders","description":"Retrieves a list of orders and its allocation offsets or negative emissions. You can only retrieve orders associated with the organization you are querying for.\n","parameters":[{"name":"page","in":"query","schema":{"type":"integer"}},{"name":"metadata","in":"query","required":false,"schema":{"type":"string"}},{"name":"metadata[example1]","in":"query","required":false,"schema":{"type":"string"}},{"name":"metadata[example2]","in":"query","required":false,"schema":{"type":"string"}},{"name":"Patch-Version","in":"header","schema":{"type":"integer"}}],"responses":{"422":{"description":"with malformed query params","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}},"400":{"description":"with malformed metadata (hash) query params","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}},"200":{"description":"with valid params","content":{"application/json":{"schema":{"title":"order_list_response","type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/order"}},"meta":{"$ref":"#/components/schemas/meta_index_object"}},"required":["success","error","data","meta"]}}}}}}},"/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\n","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Patch-Version","in":"header","schema":{"type":"integer"}}],"responses":{"200":{"description":"an order is placeable and issued_to is provided","content":{"application/json":{"schema":{"title":"order_response","type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","nullable":true},"data":{"$ref":"#/components/schemas/order"}},"required":["success","error","data"]}}}},"422":{"description":"an order is not placeable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}}},"requestBody":{"content":{"application/json":{"schema":{"title":"place_order_request","type":"object","properties":{"issued_to":{"$ref":"#/components/schemas/order_issued_to"}}}}}}}},"/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.\n","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Patch-Version","in":"header","schema":{"type":"integer"}}],"responses":{"404":{"description":"an non-existent order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}},"200":{"description":"Returns the requested order","content":{"application/json":{"schema":{"title":"order_response","type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","nullable":true},"data":{"$ref":"#/components/schemas/order"}},"required":["success","error","data"]}}}}}}},"/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.\n","parameters":[{"name":"page","in":"query","schema":{"type":"integer"}},{"name":"country","in":"query","schema":{"type":"string"}},{"name":"type","in":"query","schema":{"type":"string"}},{"name":"minimum_available_mass","in":"query","schema":{"type":"integer"}},{"name":"Accept-Language","in":"header","required":false,"schema":{"type":"string"}},{"name":"Patch-Version","in":"header","schema":{"type":"integer"}}],"responses":{"200":{"description":"Retrieves the available projects","content":{"application/json":{"schema":{"title":"project_list_response","type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/project"}},"meta":{"$ref":"#/components/schemas/meta_index_object"}},"required":["success","error","data","meta"]}}}},"422":{"description":"with malformed query params","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}}}}},"/v1/projects/{id}":{"get":{"summary":"Retrieves a project","tags":["Projects"],"operationId":"retrieveProject","description":"Retrieves a project available on Patch's platform.\n","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Accept-Language","in":"header","required":false,"schema":{"type":"string"}},{"name":"Patch-Version","in":"header","schema":{"type":"integer"}}],"responses":{"404":{"description":"a non-existent project","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}},"403":{"description":"a production project with test credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}},"200":{"description":"Returns the requested project","content":{"application/json":{"schema":{"title":"project_response","type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","nullable":true},"data":{"$ref":"#/components/schemas/project"}},"required":["success","error","data"]}}}}}}},"/v1/projects/technology_types":{"get":{"summary":"Retrieves the list of technology_types","tags":["TechnologyTypes"],"operationId":"retrieveTechnologyTypes","description":"Retrieves a list of all technology_types.\n","parameters":[{"name":"Patch-Version","in":"header","schema":{"type":"integer"}}],"responses":{"200":{"description":"Retrieves the available technology_types","content":{"application/json":{"schema":{"title":"technology_type_list_response","type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/technology_type"}}},"required":["success","error","data"]}}}}}}}},"servers":[{"url":"{defaultUrl}","variables":{"defaultUrl":{"default":"https://api.patch.io"}}}],"security":[{"bearer_auth":[]}],"components":{"securitySchemes":{"bearer_auth":{"type":"http","scheme":"bearer"}},"schemas":{"error_response":{"title":"error_response","type":"object","properties":{"success":{"type":"boolean"},"error":{"properties":{"code":{"type":"integer"},"message":{"type":"string"}},"required":["code","message"]},"data":{"type":"object","nullable":true}},"required":["success","error","data"]},"create_success_response":{"title":"create_success_response","type":"object","properties":{"success":{"type":"boolean"},"error":{"properties":{"code":{"type":"integer"},"message":{"type":"string"}},"required":["code","message"]}},"required":["success","error","data"]},"order":{"title":"order","properties":{"id":{"description":"A unique uid for the record. UIDs will be prepended by ord_prod or ord_test depending on the mode it was created in.","type":"string"},"created_at":{"type":"string","format":"date-time","description":"The timestamp at which the order was created"},"mass_g":{"type":"integer","description":"DEPRECATED, use `amount` and `unit` fields instead. The amount of carbon offsets in grams purchased through this order.","maximum":100000000000000,"minimum":0},"production":{"description":"A boolean indicating if this order is a production or demo mode order.","type":"boolean"},"state":{"description":"The current state of the order.","type":"string","enum":["draft","reserved","placed","processing","complete","cancelled"]},"amount":{"description":"The amount in `unit`s purchased through this order.","type":"integer","maximum":100000000000000,"minimum":0},"unit":{"description":"The unit of measurement (ie \"g\" or \"Wh\") for the `amount` ordered.","type":"string"},"price":{"description":"The total price for the `amount` ordered. Prices are always represented in the smallest currency unit (ie cents for USD).","type":"integer"},"patch_fee":{"description":"The Patch Fee for this order. Patch Fee is always represented in the smallest currency unit (ie cents for USD).","type":"integer"},"currency":{"description":"The currency code for the `price` and `patch_fee`.","type":"string"},"allocation_state":{"description":"DEPRECATED. Indicates if the order has been fully allocated to projects.","type":"string","enum":["allocated"]},"price_cents_usd":{"description":"DEPRECATED, use the `price` and `currency` fields instead. The total price in cents USD of the carbon offsets purchased through this order.","type":"integer","nullable":true},"patch_fee_cents_usd":{"description":"DEPRECATED, use the `patch_fee` and `currency` fields instead. The Patch Fee in cents USD for this order.","type":"integer","nullable":true},"allocations":{"description":"DEPRECATED. An array containing the inventory allocations for this order.","type":"array","items":{"$ref":"#/components/schemas/allocation"}},"registry_url":{"description":"The URL of this order in the public registry. Use this URL to access the order's accompanying certificate.","type":"string"},"metadata":{"description":"An optional JSON object containing metadata for this order.","type":"object"},"inventory":{"description":"An array containing the inventory allocated for this order. Inventory is grouped by project, vintage year, and price.","type":"array","items":{"$ref":"#/components/schemas/order_inventory"}},"issued_to":{"description":"An object containing the name & email of the party the inventory will be issued to.","type":"object","allOf":[{"$ref":"#/components/schemas/order_issued_to"}]}},"required":["id","mass_g","production","state","amount","unit","price","patch_fee","currency","allocation_state","price_cents_usd","patch_fee_cents_usd","metadata"]},"allocation":{"title":"allocation","type":"object","properties":{"id":{"description":"A unique uid for the record. UIDs will be prepended by all_prod or all_test depending on the mode it was created in.","type":"string"},"production":{"description":"A boolean indicating if this project is a production or demo mode project.","type":"boolean"},"mass_g":{"description":"The amount (in grams) of allocated carbon offsets.","type":"integer"}},"required":["id","production","mass_g"]},"photo":{"title":"photo","type":"object","properties":{"url":{"type":"string"},"id":{"type":"string"}},"required":["url","id"]},"technology_type":{"title":"technology_type","description":"An object containing the technology type's name, slug and parent_technology_type.","type":"object","properties":{"slug":{"description":"Unique identifier for this type of technology.","type":"string"},"name":{"description":"Display name of this technology type.","type":"string"},"parent_technology_type":{"title":"parent_technology_type","description":"An object containing the parent technology type's name and slug.","type":"object","properties":{"slug":{"description":"Unique identifier for this type of technology.","type":"string"},"name":{"description":"Name of this technology type.","type":"string"}}}},"required":["name","slug"]},"project":{"title":"project","type":"object","properties":{"id":{"description":"A unique uid for the record. UIDs will be prepended by pro_prod or pro_test depending on the mode it was created in.","type":"string"},"production":{"description":"A boolean indicating if this project is a production or demo mode project.","type":"boolean"},"name":{"description":"The name of the project.","type":"string"},"description":{"description":"The description of the project.","type":"string"},"type":{"description":"DEPRECATED. Favor the technology_type field instead.","type":"string"},"mechanism":{"description":"The mechanism of the project. One of: removal, avoidance, avoidance_and_removal.","type":"string"},"country":{"description":"The country of origin of the project.","type":"string"},"state":{"description":"The state where this project is located.","type":"string","nullable":true},"latitude":{"description":"The latitude at which this project is located.","type":"number","format":"float","nullable":true},"longitude":{"description":"The longitude at which this project is located.","type":"number","format":"float","nullable":true},"developer":{"description":"The name of the project developer.","type":"string"},"photos":{"description":"An array of URLs for photos of the project.","type":"array","items":{"$ref":"#/components/schemas/photo"},"nullable":true},"average_price_per_tonne_cents_usd":{"description":"DEPRECATED. The average price per tonne in USD cents for carbon offsets supplied by this project.","type":"integer"},"remaining_mass_g":{"description":"DEPRECATED. The remaining mass in grams available for purchase for this project.","type":"integer"},"verifier":{"description":"The name of the project verifier, when applicable. A verifier is the organization that verifies the calculations of the actual amount of greenhouse gas emissions that have been avoided or sequestered through implementation of the project.","type":"string"},"standard":{"description":"An object returning the Standard associated with this project, when applicable. Standards provide guidance on GHG quantification, monitoring, and reporting. Standards can include protocols/methodologies and guidance documents.","nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/standard"}]},"sdgs":{"description":"An array returning the UN Sustainable Development Goals associated with this project.","type":"array","items":{"$ref":"#/components/schemas/sdg"},"nullable":true},"tagline":{"type":"string","description":"A short description of the project."},"technology_type":{"description":"An object containing the technology type's name, slug and parent_technology_type.","type":"object","$ref":"#/components/schemas/technology_type"},"highlights":{"description":"DEPRECATED. An array of objects containing the highlight's slug, title, and a URL for the corresponding icon. A highlight's title is a short string that spotlights a characteristic about the project. Highlights are deprecated and not populated for recent projects.","type":"array","items":{"$ref":"#/components/schemas/highlight"}},"inventory":{"description":"An array of objects containing available inventory for a project. Available inventory is grouped by a project's vintage year and returns amount and pricing available for a given vintage year.","type":"array","items":{"$ref":"#/components/schemas/inventory"}}},"required":["id","production","name","description","country","developer","average_price_per_tonne_cents_usd","remaining_mass_g","technology_type","highlights","inventory"]},"meta_index_object":{"title":"meta_index_object","type":"object","properties":{"prev_page":{"type":"integer","nullable":true},"next_page":{"type":"integer","nullable":true}}},"standard":{"title":"standard","properties":{"type":{"description":"The standard type.","type":"string"},"acronym":{"description":"The acronym for the standard.","type":"string"},"description":{"description":"The description of the standard.","type":"string"}},"required":["type","acronym","description"]},"sdg":{"title":"sdg","properties":{"title":{"description":"The title of the Sustainable Development Goal.","type":"string"},"number":{"description":"The Sustainable Development Goal number.","type":"integer"},"description":{"description":"The description of the Sustainable Development Goal.","type":"string"},"url":{"description":"The url to an information page for the Sustainable Development Goal.","type":"string"}},"required":["title","number","description","url"]},"highlight":{"title":"highlight","type":"object","properties":{"slug":{"description":"A unique identifier for each highlight.","type":"string"},"title":{"description":"A short string that spotlights a characteristic about the project.","type":"string"},"icon_url":{"description":"A URL for the corresponding icon.","type":"string"}},"required":["slug","title","icon_url"]},"inventory":{"title":"inventory","type":"object","properties":{"vintage_year":{"description":"The year in which the climate impacts of the project occurred, or will occur.","type":"integer"},"amount_available":{"description":"The amount available for this vintage year.","type":"integer"},"price":{"description":"The price per tonne (1,000,000 g) or MWh (1,000,000 Wh) of inventory. Prices are always represented in the smallest currency unit (ie cents for USD).","type":"integer"},"currency":{"description":"The currency code for `price`.","type":"string"},"unit":{"description":"The unit of measurement (ie \"g\" or \"Wh\") for `amount_available`.","type":"string"}},"required":["vintage_year","amount_available","price","currency","unit"]},"order_issued_to":{"title":"order_issued_to","description":"An object containing the name & email of the party the inventory will be issued to.","type":"object","properties":{"name":{"description":"The name of the issuee","type":"string","nullable":true},"email":{"description":"The email address of the issuee","type":"string","nullable":true}}},"order_inventory":{"title":"order_inventory","type":"object","properties":{"project":{"description":"An object containing information about the project associated with the inventory allocated.","type":"object","allOf":[{"$ref":"#/components/schemas/order_inventory_project"}]},"vintage_year":{"description":"The year in which the climate impacts of the project occurred, or will occur.","type":"integer"},"amount":{"description":"The amount ordered for the given project and vintage year.","type":"integer"},"unit":{"description":"The unit of measurement (ie \"g\" or \"Wh\") for the `amount` ordered for the given project and vintage year.","type":"string"},"price":{"description":"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).","type":"integer"},"currency":{"description":"The currency code for the `price`.","type":"string"}},"required":["project","vintage_year","amount","unit","price","currency"]},"order_inventory_project":{"title":"order_inventory_project","type":"object","properties":{"id":{"description":"The unique uid for a project. UIDs will be prepended by pro_prod or pro_test depending on the mode it was created in.","type":"string"},"name":{"description":"The name of the project.","type":"string"}},"required":["id","name"]}}}}