Create

Create a new fee for a merchant organization. A Fee represents a charge that can be applied to subscriptions. Cadence is defined when creating a Price for the fee.

POST /v0/fees

Create

cURL

curl --request POST \
  --url https://api.paygentic.io/v0/fees \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "merchantId": "<string>",
  "productId": "<string>",
  "itemId": "<string>"
}
'

201

{
  "id": "fee_w9x0y1z2a3b4c5d6",
  "object": "fee",
  "createdAt": "2024-01-15T10:30:00Z",
  "description": "One-time setup fee for new customers",
  "merchantId": "org_e7f8g9h0i1j2k3l4",
  "name": "Setup Fee",
  "productId": "prod_m5n6o7p8q9r0s1t2",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Authorizations

Authorization · string · header · required

API key authentication

Body

application/json

name · string · required

Human-readable label identifying the fee. Sample values: 'Setup Fee', 'Monthly Subscription', 'Compliance Update', 'Annual License'

description · string · required

Explanatory text describing what the fee represents. Sample values: 'One-time setup fee for new customers', 'Monthly base subscription charge', 'Yearly compliance and security update fee'

merchantId · string · required

The unique identifier of the merchant organization associated with the fee.

Pattern: ^org_[a-zA-Z0-9]+$

productId · string

The product this fee belongs to. Required unless itemId is supplied, in which case the product is derived from that item's catalog.

Pattern: ^prod_[a-zA-Z0-9]+$

itemId · string

Optional item tag, used to map this fee's invoice lines to an external accounting/tax identity. When supplied, productId is derived from the item's catalog and a supplied productId that disagrees is rejected.

Pattern: ^itm_[a-zA-Z0-9]+$

Response

201

application/json

Fee created successfully

id · string · required

Pattern: ^fee_[a-zA-Z0-9]+$

object · enum<string> · default: fee · required

Available options: fee

name · string · required

description · string · required

merchantId · string · required

Unique identifier for an organization

Pattern: ^org_[a-zA-Z0-9]+$

productId · string · required

The product this fee belongs to. Always populated; derived from the item's catalog when the fee is tagged with an item.

Pattern: ^prod_[a-zA-Z0-9]+$

itemId · string | null · required

The item this fee is tagged with, or null when untagged. Used to map this fee's invoice lines to an external accounting/tax identity.

Pattern: ^itm_[a-zA-Z0-9]+$

createdAt · string<date-time> · required

updatedAt · string<date-time> · required