# Authenticated Cart Creation

This store supports authenticated cart creation for AI agents.
Agents may create a cart and return a checkout URL.
Agents must not complete payment automatically.
All purchases require explicit human approval in the shop checkout.

## Token
- Method: POST
- URL: https://demo.agentsfeed.dev/oauth/token
- URL with query parameters: https://demo.agentsfeed.dev/oauth/token?grant_type=client_credentials&scope=cart:write
- Parameters: `grant_type=client_credentials&scope=cart:write`
- Parameter location: URL query, `application/x-www-form-urlencoded` body, or JSON body.
- Token lifetime: 900 seconds

## Endpoint
- Method: POST
- URL: https://demo.agentsfeed.dev/module/agentsfeed/cart
- Content-Type: application/json
- Auth: `Authorization: Bearer <token>`
- Required scope: `cart:write`

## Request schema
```json
{
    "oneOf": [
        {
            "type": "object",
            "additionalProperties": false,
            "required": [
                "product_id"
            ],
            "properties": {
                "product_id": {
                    "type": "integer",
                    "minimum": 1
                },
                "product_attribute_id": {
                    "type": [
                        "integer",
                        "null"
                    ],
                    "minimum": 1
                },
                "quantity": {
                    "type": "integer",
                    "minimum": 1,
                    "default": 1
                }
            }
        },
        {
            "type": "object",
            "additionalProperties": false,
            "required": [
                "items"
            ],
            "properties": {
                "items": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 20,
                    "items": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                            "product_id"
                        ],
                        "properties": {
                            "product_id": {
                                "type": "integer",
                                "minimum": 1
                            },
                            "product_attribute_id": {
                                "type": [
                                    "integer",
                                    "null"
                                ],
                                "minimum": 1
                            },
                            "quantity": {
                                "type": "integer",
                                "minimum": 1,
                                "default": 1
                            }
                        }
                    }
                }
            }
        }
    ]
}
```

## Response schema
```json
{
    "type": "object",
    "required": [
        "cart_id",
        "checkout_url",
        "items",
        "request_id"
    ],
    "properties": {
        "cart_id": {
            "type": "integer"
        },
        "checkout_url": {
            "type": "string",
            "format": "uri"
        },
        "items": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "product_id": {
                        "type": "integer"
                    },
                    "product_attribute_id": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "quantity": {
                        "type": "integer"
                    }
                }
            }
        },
        "request_id": {
            "type": "string"
        }
    }
}
```

## Safety rules
- Send either single-product fields or an `items` array for multiple products.
- Each item may contain only `product_id`, optional `product_attribute_id`, and `quantity`.
- If the product has combinations, send the exact `product_attribute_id` from the catalog feed variant.
- Do not send price overrides, discounts, address data, customer data, custom product payloads, or payment fields.
- The checkout URL opens normal PrestaShop checkout for a human user.
- The API never creates an order and never marks payment complete.

## Example request
```bash
TOKEN=$(curl -s -X POST "https://demo.agentsfeed.dev/oauth/token?grant_type=client_credentials&scope=cart:write" | jq -r .access_token)

curl -X POST "https://demo.agentsfeed.dev/module/agentsfeed/cart" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"product_id":12,"product_attribute_id":34,"quantity":1},{"product_id":15,"quantity":2}]}'
```

## Example response
```json
{
    "cart_id": 123,
    "checkout_url": "https://demo.agentsfeed.dev/module/agentsfeed/checkout?id_cart=123&key=...",
    "items": [
        {
            "product_id": 12,
            "product_attribute_id": 34,
            "quantity": 1
        },
        {
            "product_id": 15,
            "product_attribute_id": null,
            "quantity": 2
        }
    ],
    "request_id": "afreq_example"
}
```

## Failure codes
- `invalid_json`
- `invalid_request`
- `missing_items`
- `invalid_item`
- `too_many_items`
- `unauthorized`
- `forbidden`
- `out_of_stock`
- `rate_limited`
- `internal_error`