Create a billing plan

POST https://api.tamio.com/v2/products/create/billing-plan

Creates a recurring subscription product with configurable billing cycles, trial periods, retry logic, and cancellation behaviour.

Body Parameters

tax_category string*

Tax category classification UUID for the product

languages LanguageContent*

pricing_model array of object*

JSON

{ "pricing_model": [ { "currency": "EUR", "price": 1000, "billing_cycle": "month", "interval": 1 } ] }

currency string*

Currency code

price integer*

Price per billing cycle in smallest currency unit

billing_cycle string*

Billing cycle unit (day, week, month, year)

dayweekmonthyear

interval integer*

Interval of billing cycles

trial_period integer

retries integer

cancel_action string

cancelpause

cancel_behaviour string

immediateend_of_period

charge_shipping_during_trial boolean

descriptor string

stock integer

Billing plan stock (subscriptions available)

unlimited_stock boolean

Whether subscriptions are unlimited

stock_limit_warning integer

Stock threshold for low-stock warning

on_sale boolean

Whether the plan is marked as on sale

buyable boolean

Whether the plan can be subscribed to

shown boolean

Whether the plan is visible in the storefront

discount_allowed boolean

Whether discount codes can be applied

reviews_allowed boolean

Whether customer reviews are enabled

exclude_from_feed boolean

Whether to exclude from product feeds

hide_if_no_stock boolean

allow_negative_stock boolean

whitelist array of string

google_category integer

release_date string

expiry_date string

new_from string

new_to string

related_products array of string

gallery array of string

custom_fields array of CustomFieldInput

JSON

{ "custom_fields": [ { "language": "string", "name": "string", "type": "dropdown", "required": false, "values": [], "range_from": "string", "range_to": "string" } ] }

language string*

name string*

type string*

dropdownradio-buttonscheckboxestextfieldtextareadate-picker

required boolean*

values array of string

range_from string

range_to string

custom_attributes array of CustomAttributeValue

JSON

{ "custom_attributes": [ { "id": "00000000-0000-0000-0000-000000000000", "values": { "text": {}, "link": {}, "image": "00000000-0000-0000-0000-000000000000" } } ] }

id string*

values object*

JSON

{ "values": { "text": {}, "link": {}, "image": "00000000-0000-0000-0000-000000000000" } }

text object

link object

image string

min_units integer

max_units integer

Responses

200 Product operation successful

Product operation successful

status integer

product Product

400 Bad request. Possible `error_code` values:

Bad request. Possible error_code values:

Code	Description
`1002`	Referenced resource not found (gallery image, related product, variation asset, etc.)
`10060`	Product quota exceeded for your plan
`10065`	Invalid product tax category for the given product type
`10066`	Stock is required (provide stock, unlimited_stock, or stock_breakdown)
`10067`	Minimum units cannot exceed maximum units
`10070`	Variation option languages do not match product languages
`10072`	Variation options must contain all configured languages
`10073`	Variation options must contain all option values
`10074`	A variation option value was not found
`10075`	Variation option value languages are inconsistent
`10076`	Variation pricing is invalid (must match product currencies)
`10078`	Variation stock is invalid
`10079`	Some variations have warehouse stock but not all
`10298`	Subscription payment methods are not activated
`10320`	Invalid client ID for billing plan restriction
`10361`	Custom field checkbox values are invalid
`10362`	Custom field date range is invalid (end must be after start)
`10363`	Custom fields configuration is invalid
`10364`	Custom attributes are invalid
`10365`	One or more digital files not found
`10366`	Stock breakdown format is invalid
`10367`	One or more warehouses not found

status integer

error string

error_code integer

401 Missing or invalid API key

Update a service product

Update a billing plan

/products/create/billing-plan

1 const response = await fetch("https://api.tamio.com/v2/products/create/billing-plan", {
2   method: "POST",
3   headers: {
4     "Authorization": "Bearer YOUR_API_KEY",
5     "Content-Type": "application/json"
6   },
7   body: JSON.stringify({
8     "tax_category": "123e4567-e89b-12d3-a456-426614174000",
9     "languages": "...",
10     "pricing_model": [
11       {
12         "currency": "EUR",
13         "price": 1000,
14         "billing_cycle": "month",
15         "interval": 1
16       }
17     ],
18     "trial_period": 0,
19     "retries": 0,
20     "cancel_action": "cancel",
21     "cancel_behaviour": "immediate",
22     "charge_shipping_during_trial": false,
23     "descriptor": "string",
24     "stock": 100,
25     "unlimited_stock": true,
26     "stock_limit_warning": 10,
27     "on_sale": false,
28     "buyable": true,
29     "shown": true,
30     "discount_allowed": true,
31     "reviews_allowed": true,
32     "exclude_from_feed": false,
33     "hide_if_no_stock": false,
34     "allow_negative_stock": false,
35     "whitelist": [],
36     "google_category": 0,
37     "release_date": "string",
38     "expiry_date": "string",
39     "new_from": "string",
40     "new_to": "string",
41     "related_products": [],
42     "gallery": [],
43     "custom_fields": [
44       {
45         "language": "string",
46         "name": "string",
47         "type": "dropdown",
48         "required": false,
49         "values": [],
50         "range_from": "string",
51         "range_to": "string"
52       }
53     ],
54     "custom_attributes": [
55       {
56         "id": "00000000-0000-0000-0000-000000000000",
57         "values": {
58           "text": {},
59           "link": {},
60           "image": "00000000-0000-0000-0000-000000000000"
61         }
62       }
63     ],
64     "min_units": 0,
65     "max_units": 0
66   })
67 });
68 const data = await response.json();

1 require "uri"
2 require "net/http"
3 require "json"
4 
5 url = URI("https://api.tamio.com/v2/products/create/billing-plan")
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: "123e4567-e89b-12d3-a456-426614174000",
16   languages: "...",
17   pricing_model: [
18     {
19       currency: "EUR",
20       price: 1000,
21       billing_cycle: "month",
22       interval: 1
23     }
24   ],
25   trial_period: 0,
26   retries: 0,
27   cancel_action: "cancel",
28   cancel_behaviour: "immediate",
29   charge_shipping_during_trial: false,
30   descriptor: "string",
31   stock: 100,
32   unlimited_stock: true,
33   stock_limit_warning: 10,
34   on_sale: false,
35   buyable: true,
36   shown: true,
37   discount_allowed: true,
38   reviews_allowed: true,
39   exclude_from_feed: false,
40   hide_if_no_stock: false,
41   allow_negative_stock: false,
42   whitelist: [],
43   google_category: 0,
44   release_date: "string",
45   expiry_date: "string",
46   new_from: "string",
47   new_to: "string",
48   related_products: [],
49   gallery: [],
50   custom_fields: [
51     {
52       language: "string",
53       name: "string",
54       type: "dropdown",
55       required: false,
56       values: [],
57       range_from: "string",
58       range_to: "string"
59     }
60   ],
61   custom_attributes: [
62     {
63       id: "00000000-0000-0000-0000-000000000000",
64       values: {
65         text: {},
66         link: {},
67         image: "00000000-0000-0000-0000-000000000000"
68       }
69     }
70   ],
71   min_units: 0,
72   max_units: 0
73 }.to_json
74 
75 response = https.request(request)
76 puts response.read_body

Responses

{
  "status": 200,
  "product": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "object": "product",
    "name": "Premium Widget",
    "description": "High-quality premium widget with advanced features",
    "seo_title": "Premium Widget | Buy Online",
    "seo_description": "Shop the Premium Widget — built to last with advanced features.",
    "classification": "Tangible Goods",
    "is_moss_product": false,
    "created": 1700000000,
    "updated_unix": 1700100000,
    "currency": "EUR",
    "type": "physical_product",
    "pricing_model": [
      {
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "currency": "EUR",
        "price": 2999,
        "acquisition_price": 1200,
        "recommended_seller_price": 3499,
        "billing_cycle": "month",
        "interval": 1
      }
    ],
    "price": 2999,
    "stock": 150,
    "has_variations": true,
    "has_notes": false,
    "sample": false,
    "release_date": "2024-06-01T00:00:00Z",
    "release_date_unix": 1717200000,
    "expiry_date": "2025-12-31T23:59:59Z",
    "expiry_date_unix": 1767225599,
    "new_from": "2024-06-01T00:00:00Z",
    "new_from_unix": 1717200000,
    "new_to": "2024-09-01T00:00:00Z",
    "new_to_unix": 1725148800,
    "exclude_from_feed": false,
    "google_category": 5322,
    "in_stock": true,
    "unlimited_stock": false,
    "min_units": 1,
    "max_units": 100,
    "stock_limit_warning": 10,
    "allow_negative_stock": false,
    "on_sale": true,
    "discount_allowed": true,
    "reviews_allowed": true,
    "hide_if_no_stock": false,
    "shown": true,
    "buyable": true,
    "custom_fields": [],
    "whitelist": [
      "[email protected]"
    ],
    "additional_information": {
      "brand": "WidgetCorp",
      "model": "WX-3000",
      "asin": "B09V3KXJPB",
      "upc": "012345678905",
      "mpn": "WX3K-BLK",
      "isbn": "978-3-16-148410-0",
      "ean": "4006381333931",
      "gtin": "00012345678905",
      "sku": "WDG-PRM-001",
      "hscode": "8471.30",
      "condition": "new",
      "country_of_origin": "DE",
      "packaging_type": "box",
      "detailed_description": "string",
      "nshift_parcel_amount": 1,
      "nshift_quick_id": "string",
      "parcels": {}
    },
    "weight": 2.5,
    "net_weight": 2.1,
    "dimensions": {
      "length": 30,
      "width": 20,
      "height": 10
    },
    "packs": [
      {
        "id": "770e8400-e29b-41d4-a716-446655440002",
        "label": {
          "en": "6-Pack",
          "de": "6er-Pack"
        },
        "stock": 50,
        "multiples": true
      }
    ],
    "stock_breakdown": [
      {
        "warehouse": "880e8400-e29b-41d4-a716-446655440003",
        "stock": 75
      }
    ],
    "delivery_type": "file",
    "license_type": "autogenerated",
    "delivery_url": "https://downloads.example.com/premium-widget",
    "number_of_downloads": 5,
    "licenses": [
      "XXXX-YYYY-ZZZZ-1111",
      "XXXX-YYYY-ZZZZ-2222"
    ],
    "digital_files": [],
    "billing_cycle": "month",
    "interval": 1,
    "trial_period": 14,
    "descriptor": "ACME PREMIUM",
    "retries": 2,
    "cancel_action": "cancel",
    "cancel_behaviour": "end_of_period",
    "has_stripe_price": true,
    "charge_shipping_during_trial": false,
    "is_customer_product": false,
    "clients": [
      {
        "id": "990e8400-e29b-41d4-a716-446655440004",
        "name": "Acme Corp",
        "email": "[email protected]"
      }
    ],
    "gallery": [
      {
        "public_url": "https://pub.ox31.com/uploads/product-image-abc123.jpg",
        "alt_text": "Premium Widget front view",
        "asset_id": "aa0e8400-e29b-41d4-a716-446655440005"
      }
    ],
    "has_image": true,
    "languages": {
      "en": {
        "title": "Premium Widget",
        "description": "High-quality premium widget",
        "slug": "premium-widget"
      },
      "de": {
        "title": "Premium-Widget",
        "description": "Hochwertiges Premium-Widget",
        "slug": "premium-widget"
      }
    },
    "variations": {
      "options": [
        {
          "name": "Size",
          "values": [
            "Small",
            "Medium",
            "Large"
          ]
        }
      ],
      "variants": [
        {
          "id": "bb0e8400-e29b-41d4-a716-446655440006",
          "stock": 25,
          "options": {
            "en": {
              "size": "Large",
              "color": "Blue"
            }
          },
          "stock_breakdown": []
        }
      ]
    },
    "invoices": 342,
    "customers": 198,
    "subscriptions": 45,
    "lifetime_revenue": 1025000,
    "related_products": [
      "cc0e8400-e29b-41d4-a716-446655440007",
      "dd0e8400-e29b-41d4-a716-446655440008"
    ]
  }
}

1	const response = await fetch("https://api.tamio.com/v2/products/create/billing-plan", {
2	method: "POST",
3	headers: {
4	"Authorization": "Bearer YOUR_API_KEY",
5	"Content-Type": "application/json"
6	},
7	body: JSON.stringify({
8	"tax_category": "123e4567-e89b-12d3-a456-426614174000",
9	"languages": "...",
10	"pricing_model": [
11	{
12	"currency": "EUR",
13	"price": 1000,
14	"billing_cycle": "month",
15	"interval": 1
16	}
17	],
18	"trial_period": 0,
19	"retries": 0,
20	"cancel_action": "cancel",
21	"cancel_behaviour": "immediate",
22	"charge_shipping_during_trial": false,
23	"descriptor": "string",
24	"stock": 100,
25	"unlimited_stock": true,
26	"stock_limit_warning": 10,
27	"on_sale": false,
28	"buyable": true,
29	"shown": true,
30	"discount_allowed": true,
31	"reviews_allowed": true,
32	"exclude_from_feed": false,
33	"hide_if_no_stock": false,
34	"allow_negative_stock": false,
35	"whitelist": [],
36	"google_category": 0,
37	"release_date": "string",
38	"expiry_date": "string",
39	"new_from": "string",
40	"new_to": "string",
41	"related_products": [],
42	"gallery": [],
43	"custom_fields": [
44	{
45	"language": "string",
46	"name": "string",
47	"type": "dropdown",
48	"required": false,
49	"values": [],
50	"range_from": "string",
51	"range_to": "string"
52	}
53	],
54	"custom_attributes": [
55	{
56	"id": "00000000-0000-0000-0000-000000000000",
57	"values": {
58	"text": {},
59	"link": {},
60	"image": "00000000-0000-0000-0000-000000000000"
61	}
62	}
63	],
64	"min_units": 0,
65	"max_units": 0
66	})
67	});
68	const data = await response.json();

1	require "uri"
2	require "net/http"
3	require "json"
4
5	url = URI("https://api.tamio.com/v2/products/create/billing-plan")
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: "123e4567-e89b-12d3-a456-426614174000",
16	languages: "...",
17	pricing_model: [
18	{
19	currency: "EUR",
20	price: 1000,
21	billing_cycle: "month",
22	interval: 1
23	}
24	],
25	trial_period: 0,
26	retries: 0,
27	cancel_action: "cancel",
28	cancel_behaviour: "immediate",
29	charge_shipping_during_trial: false,
30	descriptor: "string",
31	stock: 100,
32	unlimited_stock: true,
33	stock_limit_warning: 10,
34	on_sale: false,
35	buyable: true,
36	shown: true,
37	discount_allowed: true,
38	reviews_allowed: true,
39	exclude_from_feed: false,
40	hide_if_no_stock: false,
41	allow_negative_stock: false,
42	whitelist: [],
43	google_category: 0,
44	release_date: "string",
45	expiry_date: "string",
46	new_from: "string",
47	new_to: "string",
48	related_products: [],
49	gallery: [],
50	custom_fields: [
51	{
52	language: "string",
53	name: "string",
54	type: "dropdown",
55	required: false,
56	values: [],
57	range_from: "string",
58	range_to: "string"
59	}
60	],
61	custom_attributes: [
62	{
63	id: "00000000-0000-0000-0000-000000000000",
64	values: {
65	text: {},
66	link: {},
67	image: "00000000-0000-0000-0000-000000000000"
68	}
69	}
70	],
71	min_units: 0,
72	max_units: 0
73	}.to_json
74
75	response = https.request(request)
76	puts response.read_body