Copy page

Documentation

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.

Code
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.

Code
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):

Code
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):

Code
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):

Code
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.

Code
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.

Code
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.

Code
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.

Code
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.

Code
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.

Code
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:

Code
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
          }
        }
      }
    }
  }'