---
title: "Report one paid customer order"
method: POST
path: "/v1/orders"
tags: ["Store"]
---

# Report one paid customer order

`POST /v1/orders`

## Request

- Base URL: `https://carbonguru.io`
- URL: `https://carbonguru.io/v1/orders`
- Auth: HTTP bearer

Idempotent on order_ref: a second call with the same reference returns the first result. mode is preview while automatic offsetting is off, or for every order posted with a test key (matched, summed, nothing bought), and charged when the receiver created the order; it is null for any other receiver status, because inventing one would state something the receiver did not. A test key's order is stored as test:<order_ref>, and an order_ref that starts with test: in any letter case, or runs past 186 characters, is refused. Any field other than order_ref, currency, line_items and generic is refused. At least one of line_items and generic is required: generic is {carbon_kg} (kilograms the merchant declares) or {spend_usd} (a budget converted through the platform reverse quote at the merchant's product). Kilograms round up to the whole kilogram once, when the order is built. The order may be in any currency: the kilograms come from each product's footprint times its quantity.

## Request body

- object: At least one of line_items and generic is required.
  - `order_ref` string, required: The order's id in the merchant's own system. At most 186 characters; it must not start with test:.
  - `currency` string: ISO 4217, as the store recorded it. Never assumed.
  - `generic` object: An order by kilograms or by dollars, alongside or instead of line_items: exactly one of carbon_kg (kilograms the merchant declares; rounds up to the whole kilogram when the order is built) or spend_usd (a budget; converted to whole kilograms through the platform reverse quote at the merchant's product, so the charge is the product price for those kilograms plus the processing fee).
    - `carbon_kg` number
    - `spend_usd` number
  - `line_items` object[]
    - `identifier` string, required
    - `quantity` integer

## Response `200`

The receiver's outcome for this order.

- object
  - `order_ref` string, required
  - `mode` 'preview' | 'charged' | 'null', nullable, required
  - `status` string, required: The receiver's own status, verbatim.
  - `matched` integer, nullable
  - `skipped_refs` string[], nullable
  - `carbon_kg` number, nullable
  - `token` string, nullable

## Other responses

- `401`: No valid credential. Every authentication failure returns this one document.
- `402`: The account's plan does not include this capability. Carries min_tier and upgrade_url.
- `403`: A missing scope, an exhausted analysis allowance, or an object that is not the caller's.
- `404`: No such resource.
- `422`: The request's fields are wrong. errors[] names them.

---

[API](https://skmtc.dev/carbonguru/apis/carbonguru-api.md) · [All operations](https://skmtc.dev/carbonguru/apis/carbonguru-api/llms.txt) · [OpenAPI document](https://skmtc.dev/carbonguru/apis/carbonguru-api/revisions/26dcbe7a8500?raw)