Setup a subscription

1. Create a customer and an agreement

Before creating a subscription, ensure you have a customer and an agreement set up.

2. Define the product

To create a new product use the following API call:

curl --request POST \
--url https://api.properpayments.io/products \
--header 'Authorization: YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"name": "Coffee Gold"
}'

3. Define tax rates

If not done before, set up the tax rates you need using this API call:

curl --request POST \
--url https://api.properpayments.io/tax-rates \
--header 'Authorization: YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"displayName": "DK Tax",
"taxMode": "Exclusive",
"rate": 0.25,
"description": "Tax to use on Danish customers"
}'

4. Create the subscription

Besides the pricing, quantity and tax, you can set the billing scheme, billing frequency and payment terms when configuring a subscription:

• Billing scheme: Defines the billing model, such as "Licensed" or "Metered", determining how the subscription is billed.
• Billing frequency: Specifies the frequency and schedule for billing. Key details include:
  • interval: The interval of each billing period (e.g. Week, Month, Year)
  • intervalCount: The number of intervals between the invoices (e.g. 1 for every month)
• Payment terms: Determines when and how payments are collected relative to each billing cycle. This includes:
  • timing: Timing of payment, e.g. "PayInArrears" to bill after the billing period or "PayInAdvance" to bill upfront
  • fixedBy: The reference point for calculated dates (either fixed by "IssueDate" or "DueDate")
  • dayOfCycle: Specific the day within the cycle for payment (e.g. 1 for the first day of the month)
  • dueOffsetDays and dueOffsetUnit: Define a time interval between the issue and the due date
• Pricing: Define either a fixed unit price or tiered pricing.
• Start date: The date when the subscription becomes active, setting the start of the subscription.
• Billing start date: The date when the billing of the subscription starts, setting the start of the first billing cycle. In most cases, it is the same as the start date.
• Initial billing: If the start date and billing start date differ, you can choose whether the first charge of the subscription should be prorated or not charged.
• End date: Option to set an end date if the subscription is time-limited.
• Custom description: Option to set a custom description that will be shown on the invoice instead of the product name.

To create a subscription, use the following API call:

curl --request POST \
--url https://api.properpayments.io/subscriptions \
--header 'Authorization: YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"agreementId": "agr_zmrbe5de6wws91xv",
"productId": "pro_2ffi58altaea5nuh",
"customDescription": "Premium Subscription: Hardware, Software & Support"
"billingScheme": "Licensed",
"pricing": {
  "unitPrice": {
    "currency": "EUR",
    "amount": 100
  },
  "tiered": {
    "tierType": "Volume",
    "tiers": [
      {
        "upTo": 1,
        "unitPrice": {
          "currency": "EUR",
          "amount": 100
        },
        "flatFee": {
          "currency": "EUR",
          "amount": 100
        }
      }
    ]
  }
},
"quantity": 5,
"taxRateId": "tax_3erf87dkgjh",
"billingFrequency": {
  "interval": "Week",
  "intervalCount": 1
},
"paymentTerms": {
  "timing": "PayInAdvance",
  "fixedBy": "DueDate",
  "dayOfCycle": 1,
  "dueOffsetDays": 7,
  "dueOffsetUnit": "Day"
},
"startDate": "2024-06-01",
"billingStartDate": "2024-06-01",
"initialBilling": "NoCharge",
"endDate": "2028-06-01"
}'

You can also add metadata to the subscription to store any notes for internal reference.