---
title: "Add one line to a cart"
method: POST
path: "/v1/offsets/cart/items"
tags: ["Offsets"]
---

# Add one line to a cart

`POST /v1/offsets/cart/items`

## Request

- Base URL: `https://carbonguru.io`
- URL: `https://carbonguru.io/v1/offsets/cart/items`
- Auth: HTTP bearer

Name carbonguru_id (an item this account analysed, optionally with its session_id) or carbon_kg with a name (an ad-hoc footprint). A session_id on its own names no footprint and is refused, which is what the shipped route does. Adding charges nothing; subscription_mode monthly makes the line recurring and it still charges nothing until a person completes the checkout in a browser. The answer is the named cart, read back.

## Request body

- object
  - `type` 'offset' | 'removal', required
  - `carbonguru_id` string: An item this account analysed.
  - `session_id` string: The analysis session the item belongs to. A companion to the two identities, never one itself.
  - `carbon_kg` number
  - `name` string: Required with carbon_kg.
  - `subscription_mode` 'onetime' | 'monthly'
  - `product_id` union: The product the line buys: a product_id from /v1/offset-products, or its numeric id. Default: the account's default product for the type (GET /v1/offsets/defaults). A named product sets the cart; an unknown one is refused (422 unknown_product).
    - string
    - integer

## Response `201`

The named cart, read back.

- object
  - `cart` object, required
    - `type` 'offset' | 'removal', required
    - `items` object[], required
      - `item_key` string: Delete this line at DELETE /v1/offsets/cart/items/{item_key}.
      - `name` string
      - `description` string
      - `quantity` number, nullable
      - `type` 'offset' | 'removal'
      - `carbon_kg` number, nullable
      - `metric_tons` number, nullable
      - `cost_usd` number, nullable: This line's price, all-in.
      - `social_cost_usd` number, nullable
      - `carbonguru_id` string, nullable: The analysed item this offset is for.
      - `portfolio_name` string, nullable
      - `subscription_mode` 'monthly' | 'null', nullable
      - `subscription_recurring_price_usd` number, nullable
    - `totals` object, required: Totals of THIS cart. total_cost_usd is the amount checkout charges for it: one all-in number.
      - `item_count` integer
      - `total_carbon_kg` number
      - `total_cost_usd` number
    - `links` object, required
      - `checkout` string
      - `cart` string

## 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)