# Overriding Fees Examples

This document provides examples of how to override fees when creating an agreement by passing custom values in the `csa_order_form_attributes.fees_attributes` parameter.

## Fee Types

The following fee types are available:

- `Fees::Flat` - A flat fee with a fixed cost
- `Fees::Cost` - A fee with quantity and cost (price per unit × quantity)
- `Fees::Discount` - A discount that can be fixed amount or percentage
- `Fees::Attachment` - A fee described in an attachment
- `Fees::Graduated` - A fee with tiered pricing based on quantity
- `Fees::Included` - An included (free) item
- `Fees::Metered` - Usage-based/metered pricing
- `Fees::OneTime` - A one-time fee
- `Fees::Text` - A fee described using free text

## Examples

### Fees::Flat

A flat fee with a fixed cost. Requires `description` and `cost`.

```bash
curl -X POST "https://api.commonpaper.com/v1/agreements" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "TEMPLATE_ID",
    "owner_email": "OWNER_EMAIL",
    "signer_email": "SIGNER_EMAIL",
    "agreement": {
      "csa_order_form_attributes": {
        "fees_attributes": {
          "0": {
            "description": "Platform access fee",
            "type": "Fees::Flat",
            "cost": 10000
          }
        }
      }
    }
  }'
```

### Fees::Cost

A fee with quantity and cost. The total is calculated as `quantity × cost`. Requires `description`, `cost`, and `quantity`.

```bash
curl -X POST "https://api.commonpaper.com/v1/agreements" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "TEMPLATE_ID",
    "owner_email": "OWNER_EMAIL",
    "signer_email": "SIGNER_EMAIL",
    "agreement": {
      "csa_order_form_attributes": {
        "fees_attributes": {
          "0": {
            "description": "User licenses",
            "type": "Fees::Cost",
            "quantity": 10,
            "cost": 5000
          }
        }
      }
    }
  }'
```

### Fees::Discount

A discount that can be either a fixed amount or percentage. Requires `description`, `cost`, `discount_type`, and `discount_duration_type`. If `discount_duration_type` is `multiple_months`, `discount_duration_amount` is also required.

**Fixed Amount Discount (Forever):**

```bash
curl -X POST "https://api.commonpaper.com/v1/agreements" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "TEMPLATE_ID",
    "owner_email": "OWNER_EMAIL",
    "signer_email": "SIGNER_EMAIL",
    "agreement": {
      "csa_order_form_attributes": {
        "fees_attributes": {
          "0": {
            "description": "Early adopter discount",
            "type": "Fees::Discount",
            "cost": 10000,
            "discount_type": "fixed_amount",
            "discount_duration_type": "forever"
          }
        }
      }
    }
  }'
```

**Percentage Discount (Multiple Months):**

```bash
curl -X POST "https://api.commonpaper.com/v1/agreements" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "TEMPLATE_ID",
    "owner_email": "OWNER_EMAIL",
    "signer_email": "SIGNER_EMAIL",
    "agreement": {
      "csa_order_form_attributes": {
        "fees_attributes": {
          "0": {
            "description": "Promotional discount",
            "type": "Fees::Discount",
            "cost": 15,
            "discount_type": "percentage",
            "discount_duration_type": "multiple_months",
            "discount_duration_amount": 6
          }
        }
      }
    }
  }'
```

**Fixed Amount Discount (Once):**

```bash
curl -X POST "https://api.commonpaper.com/v1/agreements" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "TEMPLATE_ID",
    "owner_email": "OWNER_EMAIL",
    "signer_email": "SIGNER_EMAIL",
    "agreement": {
      "csa_order_form_attributes": {
        "fees_attributes": {
          "0": {
            "description": "One-time setup discount",
            "type": "Fees::Discount",
            "cost": 5000,
            "discount_type": "fixed_amount",
            "discount_duration_type": "once"
          }
        }
      }
    }
  }'
```

**Discount Type Values:**
- `fixed_amount` - A fixed dollar amount discount
- `percentage` - A percentage discount

**Discount Duration Type Values:**
- `once` - Applied once
- `multiple_months` - Applied for a specified number of months (requires `discount_duration_amount`)
- `forever` - Applied indefinitely

### Fees::Attachment

A fee described in an attachment. Requires `description` and `attachment_id`.

```bash
curl -X POST "https://api.commonpaper.com/v1/agreements" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "TEMPLATE_ID",
    "owner_email": "OWNER_EMAIL",
    "signer_email": "SIGNER_EMAIL",
    "agreement": {
      "csa_order_form_attributes": {
        "fees_attributes": {
          "0": {
            "description": "Custom pricing schedule",
            "type": "Fees::Attachment",
            "attachment_id": "ATTACHMENT_ID"
          }
        }
      }
    }
  }'
```

### Fees::Graduated

A fee with tiered pricing based on quantity. Requires `description` and `graduated_fee_tiers_attributes`. Each tier requires `upper_limit` and at least one of `price_per_unit` or `flat_price`.

```bash
curl -X POST "https://api.commonpaper.com/v1/agreements" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "TEMPLATE_ID",
    "owner_email": "OWNER_EMAIL",
    "signer_email": "SIGNER_EMAIL",
    "agreement": {
      "csa_order_form_attributes": {
        "fees_attributes": {
          "0": {
            "description": "Volume-based pricing",
            "type": "Fees::Graduated",
            "graduated_fee_tiers_attributes": {
              "0": {
                "upper_limit": 10,
                "price_per_unit": 50,
                "flat_price": 1000
              },
              "1": {
                "upper_limit": 100,
                "price_per_unit": 40,
                "flat_price": 500
              },
              "2": {
                "upper_limit": 1000,
                "price_per_unit": 30,
                "flat_price": 100
              }
            }
          }
        }
      }
    }
  }'
```

### Fees::Included

An included (free) item. Requires `description`. Optionally accepts `quantity`.

```bash
curl -X POST "https://api.commonpaper.com/v1/agreements" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "TEMPLATE_ID",
    "owner_email": "OWNER_EMAIL",
    "signer_email": "SIGNER_EMAIL",
    "agreement": {
      "csa_order_form_attributes": {
        "fees_attributes": {
          "0": {
            "description": "Basic support included",
            "type": "Fees::Included",
            "quantity": 1
          }
        }
      }
    }
  }'
```

### Fees::Metered

Usage-based/metered pricing. Requires `description` and `cost`.

```bash
curl -X POST "https://api.commonpaper.com/v1/agreements" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "TEMPLATE_ID",
    "owner_email": "OWNER_EMAIL",
    "signer_email": "SIGNER_EMAIL",
    "agreement": {
      "csa_order_form_attributes": {
        "fees_attributes": {
          "0": {
            "description": "API calls per 1,000",
            "type": "Fees::Metered",
            "cost": 90
          }
        }
      }
    }
  }'
```

### Fees::OneTime

A one-time fee. Requires `description` and `cost`.

```bash
curl -X POST "https://api.commonpaper.com/v1/agreements" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "TEMPLATE_ID",
    "owner_email": "OWNER_EMAIL",
    "signer_email": "SIGNER_EMAIL",
    "agreement": {
      "csa_order_form_attributes": {
        "fees_attributes": {
          "0": {
            "description": "Setup fee",
            "type": "Fees::OneTime",
            "cost": 50000
          }
        }
      }
    }
  }'
```

### Fees::Text

A fee described using free text. Requires `description`.

```bash
curl -X POST "https://api.commonpaper.com/v1/agreements" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "TEMPLATE_ID",
    "owner_email": "OWNER_EMAIL",
    "signer_email": "SIGNER_EMAIL",
    "agreement": {
      "csa_order_form_attributes": {
        "fees_attributes": {
          "0": {
            "description": "Custom pricing: Contact sales for enterprise pricing",
            "type": "Fees::Text"
          }
        }
      }
    }
  }'
```

## Multiple Fees Example

You can combine multiple fee types in a single request:

```bash
curl -X POST "https://api.commonpaper.com/v1/agreements" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "TEMPLATE_ID",
    "owner_email": "OWNER_EMAIL",
    "signer_email": "SIGNER_EMAIL",
    "agreement": {
      "csa_order_form_attributes": {
        "fees_attributes": {
          "0": {
            "description": "Base subscription",
            "type": "Fees::Flat",
            "cost": 10000
          },
          "1": {
            "description": "User licenses",
            "type": "Fees::Cost",
            "quantity": 5,
            "cost": 2000
          },
          "2": {
            "description": "Early adopter discount",
            "type": "Fees::Discount",
            "cost": 5000,
            "discount_type": "fixed_amount",
            "discount_duration_type": "forever"
          },
          "3": {
            "description": "Setup fee",
            "type": "Fees::OneTime",
            "cost": 25000
          }
        }
      }
    }
  }'
```