Agency API Agency

Create a billing plan

POST https://api.tamio.com/v2/agency/plans/create

Creates a new agency billing plan with pricing models, quotas, permissions, and overages configuration. At least one pricing model with currency, price, billing cycle, interval, and transaction fees is required.

Note: At least one of price, transaction_fees, or transaction_fees_cents must be greater than zero in each pricing model.

Body Parameters

tax_category string*

Tax category (always "Agency Billing Plan")

Agency Billing Plan

pricing_model array of object*

Pricing configurations for different currencies and billing cycles. At least one of price, transaction_fees, or transaction_fees_cents must be greater than zero.

JSON

{ "pricing_model": [ { "currency": "EUR", "price": 2999, "transaction_fees": 2.5, "transaction_fees_cents": 30, "billing_cycle": "month", "interval": 1 } ] }

currency string*

Three-letter ISO currency code

price integer*

Base price in smallest currency unit (e.g. cents)

transaction_fees number*

Percentage transaction fee (0–100)

transaction_fees_cents integer*

Fixed transaction fee in smallest currency unit per transaction

billing_cycle string*

Billing frequency unit

dayweekmonthyear

interval integer*

Number of billing cycles between charges (e.g. 1 = every month, 3 = quarterly)

buyable boolean

Whether this plan can be purchased by clients

shown boolean

Whether this plan is visible to clients

on_sale boolean

Whether this plan is currently on sale

discount_allowed boolean

Whether discount codes can be applied

unlimited_stock boolean

Whether this plan has unlimited availability

trial_period integer

Trial period in days (0 for no trial)

retries integer

Number of payment retry attempts for failed charges (0–3)

cancel_action string

Action to take when subscription fails after all retries

cancelpause

cancel_behaviour string

When cancellation takes effect

immediateend_of_period

descriptor string

Short text that appears on credit card statements

languages object

Multilingual content keyed by language code. Each language object must contain a title.

quotas object

Resource quotas for clients on this plan

JSON

{ "quotas": { "automations_quota": 50, "transaction_quota": 1000, "datatransfer_quota": 10, "storage_quota": 5, "languages_quota": 3, "products_quota": 100, "domains_quota": 3, "currencies_quota": 5, "teammates_quota": 5, "api_quota": 1000000, "newsletters_quota": 5000, "ai_quota": 100, "sms_balance": 500 } }

automations_quota integer*

Maximum number of automations allowed

transaction_quota integer*

Maximum number of transactions per billing cycle

datatransfer_quota number*

Maximum data transfer in GB per billing cycle

storage_quota number*

Maximum storage in GB

languages_quota integer*

Maximum number of languages

products_quota integer*

Maximum number of products

domains_quota integer*

Maximum number of custom domains

currencies_quota integer*

Maximum number of currencies

teammates_quota integer*

Maximum number of team members

api_quota integer*

Maximum number of API requests per billing cycle

newsletters_quota integer*

Maximum number of newsletter sends per billing cycle

ai_quota integer*

Maximum number of AI generation requests

sms_balance integer*

Number of SMS credits included per billing cycle

permissions object

Feature permissions for clients on this plan. Each key is a feature area (e.g. products, invoices, customers) containing an object with boolean permissions (view, create, edit, remove, etc.)

overages object

Overage pricing when quotas are exceeded

JSON

{ "overages": { "client_overage": true, "charge_client_overage": true, "storage": 0.5, "datatransfer": 0.1, "transactions": 0.05, "domains": 5, "languages": 3, "currencies": 2, "clients": 10, "newsletters": 0.01, "teammates": 8 } }

client_overage boolean*

Whether overage charges are passed to the client

charge_client_overage boolean*

Whether to automatically charge clients for overages

storage number

Price per GB for storage overage

datatransfer number*

Price per GB for data transfer overage

transactions number*

Price per transaction overage

domains number*

Price per additional domain

languages number*

Price per additional language

currencies number*

Price per additional currency

clients number

Price per additional client

newsletters number*

Price per additional newsletter send

teammates number*

Price per additional teammate

Example

{
  "tax_category": "Agency Billing Plan",
  "pricing_model": [
    {
      "currency": "EUR",
      "price": 2999,
      "billing_cycle": "month",
      "interval": 1,
      "transaction_fees": 0,
      "transaction_fees_cents": 0
    }
  ],
  "buyable": true,
  "shown": true,
  "on_sale": true,
  "discount_allowed": true,
  "unlimited_stock": false,
  "trial_period": 14,
  "retries": 3,
  "cancel_action": "cancel",
  "cancel_behaviour": "end_of_period",
  "descriptor": "ACME STARTER",
  "languages": {
    "en": {
      "title": "Starter Plan",
      "description": "Perfect for small businesses"
    }
  },
  "quotas": {
    "automations_quota": 50,
    "transaction_quota": 1000,
    "datatransfer_quota": 10,
    "storage_quota": 5,
    "languages_quota": 3,
    "products_quota": 100,
    "domains_quota": 3,
    "currencies_quota": 5,
    "teammates_quota": 5,
    "api_quota": 1000000,
    "newsletters_quota": 5000,
    "ai_quota": 100,
    "sms_balance": 500
  },
  "overages": {
    "client_overage": true,
    "charge_client_overage": true,
    "storage": 0.5,
    "datatransfer": 0.1,
    "transactions": 0.05,
    "domains": 5,
    "languages": 3,
    "currencies": 2,
    "clients": 10,
    "newsletters": 0.01,
    "teammates": 8
  }
}

Responses

200 Billing plan created successfully

Billing plan created successfully

status integer

product Product

400 Validation or business-logic error.

Code	Description
`400`	Schema validation failed

401 Unauthorized – invalid or missing Bearer token

Update a billing plan

/agency/plans/create

1 const response = await fetch("https://api.tamio.com/v2/agency/plans/create", {
2   method: "POST",
3   headers: {
4     "Authorization": "Bearer YOUR_API_KEY",
5     "Content-Type": "application/json"
6   },
7   body: JSON.stringify({
8     "tax_category": "Agency Billing Plan",
9     "pricing_model": [
10       {
11         "currency": "EUR",
12         "price": 2999,
13         "billing_cycle": "month",
14         "interval": 1,
15         "transaction_fees": 0,
16         "transaction_fees_cents": 0
17       }
18     ],
19     "buyable": true,
20     "shown": true,
21     "on_sale": true,
22     "discount_allowed": true,
23     "unlimited_stock": false,
24     "trial_period": 14,
25     "retries": 3,
26     "cancel_action": "cancel",
27     "cancel_behaviour": "end_of_period",
28     "descriptor": "ACME STARTER",
29     "languages": {
30       "en": {
31         "title": "Starter Plan",
32         "description": "Perfect for small businesses"
33       }
34     },
35     "quotas": {
36       "automations_quota": 50,
37       "transaction_quota": 1000,
38       "datatransfer_quota": 10,
39       "storage_quota": 5,
40       "languages_quota": 3,
41       "products_quota": 100,
42       "domains_quota": 3,
43       "currencies_quota": 5,
44       "teammates_quota": 5,
45       "api_quota": 1000000,
46       "newsletters_quota": 5000,
47       "ai_quota": 100,
48       "sms_balance": 500
49     },
50     "overages": {
51       "client_overage": true,
52       "charge_client_overage": true,
53       "storage": 0.5,
54       "datatransfer": 0.1,
55       "transactions": 0.05,
56       "domains": 5,
57       "languages": 3,
58       "currencies": 2,
59       "clients": 10,
60       "newsletters": 0.01,
61       "teammates": 8
62     }
63   })
64 });
65 const data = await response.json();

1 require "uri"
2 require "net/http"
3 require "json"
4 
5 url = URI("https://api.tamio.com/v2/agency/plans/create")
6 
7 https = Net::HTTP.new(url.host, url.port)
8 https.use_ssl = true
9 
10 request = Net::HTTP::Post.new(url)
11 request["Accept"] = "application/json"
12 request["Authorization"] = "Bearer YOUR_API_KEY"
13 request["Content-Type"] = "application/json"
14 request.body = {
15   tax_category: "Agency Billing Plan",
16   pricing_model: [
17     {
18       currency: "EUR",
19       price: 2999,
20       billing_cycle: "month",
21       interval: 1,
22       transaction_fees: 0,
23       transaction_fees_cents: 0
24     }
25   ],
26   buyable: true,
27   shown: true,
28   on_sale: true,
29   discount_allowed: true,
30   unlimited_stock: false,
31   trial_period: 14,
32   retries: 3,
33   cancel_action: "cancel",
34   cancel_behaviour: "end_of_period",
35   descriptor: "ACME STARTER",
36   languages: {
37     en: {
38       title: "Starter Plan",
39       description: "Perfect for small businesses"
40     }
41   },
42   quotas: {
43     automations_quota: 50,
44     transaction_quota: 1000,
45     datatransfer_quota: 10,
46     storage_quota: 5,
47     languages_quota: 3,
48     products_quota: 100,
49     domains_quota: 3,
50     currencies_quota: 5,
51     teammates_quota: 5,
52     api_quota: 1000000,
53     newsletters_quota: 5000,
54     ai_quota: 100,
55     sms_balance: 500
56   },
57   overages: {
58     client_overage: true,
59     charge_client_overage: true,
60     storage: 0.5,
61     datatransfer: 0.1,
62     transactions: 0.05,
63     domains: 5,
64     languages: 3,
65     currencies: 2,
66     clients: 10,
67     newsletters: 0.01,
68     teammates: 8
69   }
70 }.to_json
71 
72 response = https.request(request)
73 puts response.read_body

Responses

{
  "status": 200,
  "product": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "object": "product",
    "name": "Starter Plan",
    "description": "Perfect for small businesses",
    "seo_title": "Starter Plan - Best for Small Teams",
    "seo_description": "Get started with our affordable starter plan.",
    "classification": "Agency Billing Plan",
    "type": "billing_plan",
    "currency": "EUR",
    "price": 2999,
    "pricing_model": [
      {
        "currency": "EUR",
        "price": 2999,
        "transaction_fees": 0,
        "transaction_fees_cents": 0,
        "billing_cycle": "month",
        "interval": 1,
        "stripe_price_id": "price_1234567890"
      }
    ],
    "stock": null,
    "created": 1700000000,
    "updated_unix": 1700086400,
    "has_variations": false,
    "has_notes": false,
    "is_moss_product": false,
    "billing_cycle": "month",
    "interval": 1,
    "trial_period": 14,
    "descriptor": "ACME STARTER",
    "retries": 3,
    "cancel_action": "cancel",
    "cancel_behaviour": "end_of_period",
    "charge_shipping_during_trial": true,
    "has_stripe_price": false,
    "is_customer_product": false,
    "on_sale": true,
    "discount_allowed": true,
    "reviews_allowed": false,
    "hide_if_no_stock": true,
    "shown": true,
    "buyable": true,
    "whitelist": null,
    "in_stock": true,
    "unlimited_stock": false,
    "min_units": null,
    "max_units": null,
    "stock_limit_warning": null,
    "allow_negative_stock": false,
    "permissions": {
      "products": {
        "view": true,
        "create": true,
        "edit": true,
        "remove": true
      },
      "invoices": {
        "view": true,
        "create": true,
        "edit": true,
        "remove": true
      },
      "customers": {
        "view": true,
        "create": true,
        "edit": true,
        "remove": true
      }
    },
    "quotas": {
      "automations_quota": 50,
      "transaction_quota": 1000,
      "datatransfer_quota": 10,
      "storage_quota": 5,
      "languages_quota": 3,
      "products_quota": 100,
      "domains_quota": 3,
      "currencies_quota": 5,
      "teammates_quota": 5,
      "api_quota": 1000000,
      "newsletters_quota": 5000,
      "ai_quota": 100,
      "sms_balance": 500
    },
    "overages": {
      "client_overage": true,
      "charge_client_overage": true,
      "storage": 0.5,
      "datatransfer": 0.1,
      "transactions": 0.05,
      "domains": 5,
      "languages": 3,
      "currencies": 2,
      "clients": 10,
      "newsletters": 0.01,
      "teammates": 8
    },
    "active_clients": 12,
    "clients": [
      {
        "id": "660e8400-e29b-41d4-a716-446655440000",
        "name": "Acme Corp",
        "email": "[email protected]"
      }
    ],
    "content": {
      "en": {
        "title": "Starter Plan",
        "description": "Perfect for small businesses",
        "slug": "starter-plan"
      }
    },
    "gallery": []
  }
}

1	const response = await fetch("https://api.tamio.com/v2/agency/plans/create", {
2	method: "POST",
3	headers: {
4	"Authorization": "Bearer YOUR_API_KEY",
5	"Content-Type": "application/json"
6	},
7	body: JSON.stringify({
8	"tax_category": "Agency Billing Plan",
9	"pricing_model": [
10	{
11	"currency": "EUR",
12	"price": 2999,
13	"billing_cycle": "month",
14	"interval": 1,
15	"transaction_fees": 0,
16	"transaction_fees_cents": 0
17	}
18	],
19	"buyable": true,
20	"shown": true,
21	"on_sale": true,
22	"discount_allowed": true,
23	"unlimited_stock": false,
24	"trial_period": 14,
25	"retries": 3,
26	"cancel_action": "cancel",
27	"cancel_behaviour": "end_of_period",
28	"descriptor": "ACME STARTER",
29	"languages": {
30	"en": {
31	"title": "Starter Plan",
32	"description": "Perfect for small businesses"
33	}
34	},
35	"quotas": {
36	"automations_quota": 50,
37	"transaction_quota": 1000,
38	"datatransfer_quota": 10,
39	"storage_quota": 5,
40	"languages_quota": 3,
41	"products_quota": 100,
42	"domains_quota": 3,
43	"currencies_quota": 5,
44	"teammates_quota": 5,
45	"api_quota": 1000000,
46	"newsletters_quota": 5000,
47	"ai_quota": 100,
48	"sms_balance": 500
49	},
50	"overages": {
51	"client_overage": true,
52	"charge_client_overage": true,
53	"storage": 0.5,
54	"datatransfer": 0.1,
55	"transactions": 0.05,
56	"domains": 5,
57	"languages": 3,
58	"currencies": 2,
59	"clients": 10,
60	"newsletters": 0.01,
61	"teammates": 8
62	}
63	})
64	});
65	const data = await response.json();

1	require "uri"
2	require "net/http"
3	require "json"
4
5	url = URI("https://api.tamio.com/v2/agency/plans/create")
6
7	https = Net::HTTP.new(url.host, url.port)
8	https.use_ssl = true
9
10	request = Net::HTTP::Post.new(url)
11	request["Accept"] = "application/json"
12	request["Authorization"] = "Bearer YOUR_API_KEY"
13	request["Content-Type"] = "application/json"
14	request.body = {
15	tax_category: "Agency Billing Plan",
16	pricing_model: [
17	{
18	currency: "EUR",
19	price: 2999,
20	billing_cycle: "month",
21	interval: 1,
22	transaction_fees: 0,
23	transaction_fees_cents: 0
24	}
25	],
26	buyable: true,
27	shown: true,
28	on_sale: true,
29	discount_allowed: true,
30	unlimited_stock: false,
31	trial_period: 14,
32	retries: 3,
33	cancel_action: "cancel",
34	cancel_behaviour: "end_of_period",
35	descriptor: "ACME STARTER",
36	languages: {
37	en: {
38	title: "Starter Plan",
39	description: "Perfect for small businesses"
40	}
41	},
42	quotas: {
43	automations_quota: 50,
44	transaction_quota: 1000,
45	datatransfer_quota: 10,
46	storage_quota: 5,
47	languages_quota: 3,
48	products_quota: 100,
49	domains_quota: 3,
50	currencies_quota: 5,
51	teammates_quota: 5,
52	api_quota: 1000000,
53	newsletters_quota: 5000,
54	ai_quota: 100,
55	sms_balance: 500
56	},
57	overages: {
58	client_overage: true,
59	charge_client_overage: true,
60	storage: 0.5,
61	datatransfer: 0.1,
62	transactions: 0.05,
63	domains: 5,
64	languages: 3,
65	currencies: 2,
66	clients: 10,
67	newsletters: 0.01,
68	teammates: 8
69	}
70	}.to_json
71
72	response = https.request(request)
73	puts response.read_body