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 costFees::Cost - A fee with quantity and cost (price per unit × quantity)Fees::Discount - A discount that can be fixed amount or percentageFees::Attachment - A fee described in an attachmentFees::Graduated - A fee with tiered pricing based on quantityFees::Included - An included (free) itemFees::Metered - Usage-based/metered pricingFees::OneTime - A one-time feeFees::Text - A fee described using free text
Examples
Fees::Flat
A flat fee with a fixed cost. Requires description and cost.
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.
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):
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):
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):
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 discountpercentage - A percentage discount
Discount Duration Type Values:
once - Applied oncemultiple_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.
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.
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.
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.
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.
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.
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:
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 } } } } }'
Last modified on January 27, 2026
