Create contract recurring discount

curl --request POST \
  --url https://api.useaira.com/v1/contracts/{id}/recurring-discounts \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "amount": 2,
  "description": "<string>",
  "startDate": "2023-12-25",
  "planId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "invoiceCount": 600.5,
  "distributionMode": "proportional"
}
'

import requests

url = "https://api.useaira.com/v1/contracts/{id}/recurring-discounts"

payload = {
    "amount": 2,
    "description": "<string>",
    "startDate": "2023-12-25",
    "planId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "invoiceCount": 600.5,
    "distributionMode": "proportional"
}
headers = {
    "X-API-KEY": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    amount: 2,
    description: '<string>',
    startDate: '2023-12-25',
    planId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    invoiceCount: 600.5,
    distributionMode: 'proportional'
  })
};

fetch('https://api.useaira.com/v1/contracts/{id}/recurring-discounts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.useaira.com/v1/contracts/{id}/recurring-discounts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => 2,
    'description' => '<string>',
    'startDate' => '2023-12-25',
    'planId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'invoiceCount' => 600.5,
    'distributionMode' => 'proportional'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.useaira.com/v1/contracts/{id}/recurring-discounts"

	payload := strings.NewReader("{\n  \"amount\": 2,\n  \"description\": \"<string>\",\n  \"startDate\": \"2023-12-25\",\n  \"planId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"invoiceCount\": 600.5,\n  \"distributionMode\": \"proportional\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-KEY", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.useaira.com/v1/contracts/{id}/recurring-discounts")
  .header("X-API-KEY", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 2,\n  \"description\": \"<string>\",\n  \"startDate\": \"2023-12-25\",\n  \"planId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"invoiceCount\": 600.5,\n  \"distributionMode\": \"proportional\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.useaira.com/v1/contracts/{id}/recurring-discounts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": 2,\n  \"description\": \"<string>\",\n  \"startDate\": \"2023-12-25\",\n  \"planId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"invoiceCount\": 600.5,\n  \"distributionMode\": \"proportional\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "planId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "targetScope": "invoice",
  "method": "fixed",
  "amount": 2,
  "description": "<string>",
  "startDate": "2023-12-25",
  "invoiceCount": 2,
  "distributionMode": "proportional",
  "isActive": true
}

{
  "message": "<string>",
  "code": "<string>",
  "details": {},
  "causations": [
    {
      "message": "<string>",
      "code": "<string>",
      "details": {}
    }
  ]
}

{
  "message": "<string>"
}

POST

contracts

{id}

recurring-discounts

Create contract recurring discount

curl --request POST \
  --url https://api.useaira.com/v1/contracts/{id}/recurring-discounts \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "amount": 2,
  "description": "<string>",
  "startDate": "2023-12-25",
  "planId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "invoiceCount": 600.5,
  "distributionMode": "proportional"
}
'

import requests

url = "https://api.useaira.com/v1/contracts/{id}/recurring-discounts"

payload = {
    "amount": 2,
    "description": "<string>",
    "startDate": "2023-12-25",
    "planId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "invoiceCount": 600.5,
    "distributionMode": "proportional"
}
headers = {
    "X-API-KEY": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    amount: 2,
    description: '<string>',
    startDate: '2023-12-25',
    planId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    invoiceCount: 600.5,
    distributionMode: 'proportional'
  })
};

fetch('https://api.useaira.com/v1/contracts/{id}/recurring-discounts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.useaira.com/v1/contracts/{id}/recurring-discounts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => 2,
    'description' => '<string>',
    'startDate' => '2023-12-25',
    'planId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'invoiceCount' => 600.5,
    'distributionMode' => 'proportional'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.useaira.com/v1/contracts/{id}/recurring-discounts"

	payload := strings.NewReader("{\n  \"amount\": 2,\n  \"description\": \"<string>\",\n  \"startDate\": \"2023-12-25\",\n  \"planId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"invoiceCount\": 600.5,\n  \"distributionMode\": \"proportional\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-KEY", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.useaira.com/v1/contracts/{id}/recurring-discounts")
  .header("X-API-KEY", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 2,\n  \"description\": \"<string>\",\n  \"startDate\": \"2023-12-25\",\n  \"planId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"invoiceCount\": 600.5,\n  \"distributionMode\": \"proportional\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.useaira.com/v1/contracts/{id}/recurring-discounts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": 2,\n  \"description\": \"<string>\",\n  \"startDate\": \"2023-12-25\",\n  \"planId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"invoiceCount\": 600.5,\n  \"distributionMode\": \"proportional\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "planId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "targetScope": "invoice",
  "method": "fixed",
  "amount": 2,
  "description": "<string>",
  "startDate": "2023-12-25",
  "invoiceCount": 2,
  "distributionMode": "proportional",
  "isActive": true
}

{
  "message": "<string>",
  "code": "<string>",
  "details": {},
  "causations": [
    {
      "message": "<string>",
      "code": "<string>",
      "details": {}
    }
  ]
}

{
  "message": "<string>"
}

Authorizations

X-API-KEY

string

header

required

API Key Authentication.

Path Parameters

string<uuid>

required

Unique identifier for the contract.

Body

application/json

method

enum<string>

required

Discount method: "fixed" (amount in cents) or "percentage" (basis points).

Available options:

fixed,

percentage

amount

number

required

Amount in cents when method is "fixed", or basis points (1-10000, where 10000 = 100%) when method is "percentage".

Required range: x >= 1Must be a multiple of 1

description

string

required

Display text of the discount as it appears on invoices.

Minimum string length: 1

startDate

string<date>

required

Billing-cycle start date the discount starts at. Must match a valid cycle date of the contract.

targetScope

enum<string>

required

Where the discount applies: "invoice", "plan", or "contract_minimum_amount".

Available options:

invoice,

plan,

contract_minimum_amount

planId

string<uuid> | null

Optional plan to scope the discount to. Required when targetScope is "plan".

invoiceCount

number | null

Optional number of invoices the discount applies to, counted from startDate over the open invoices that bill its target; already-issued invoices are frozen and do not consume the count. Null means the discount applies until deactivated.

Required range: 1 <= x <= 1200Must be a multiple of 1

distributionMode

enum<string>

default:proportional

For split invoices: "proportional" divides a fixed discount across invoices; "full" applies it in full to each.

Available options:

proportional,

full

Response

Schema representing a recurring discount configured on a contract. Starting at startDate's billing cycle, the discount is applied to the next invoiceCount invoices that bill its target (all of them when invoiceCount is null), as long as it is active (see isActive).

string<uuid>

required

The unique identifier of the recurring discount in our system.

planId

string<uuid> | null

required

The unique identifier of the plan targeted by the discount, for plan and metric target scopes. Null for invoice and contract_minimum_amount scopes.

targetScope

enum<string>

required

What the discount applies to on each generated invoice: invoice (the whole invoice), plan (the line item group of the targeted plan), metric (the line item of the targeted usage charge), or contract_minimum_amount (the contract minimum commitment line item).

Available options:

invoice,

plan,

metric,

contract_minimum_amount

method

enum<string>

required

How amount is interpreted: fixed subtracts a monetary amount; percentage subtracts a percentage of the targeted amount.

Available options:

fixed,

percentage

amount

number

required

Value of the discount, as a positive integer: whole cents when method is fixed; basis points when method is percentage (1 basis point = 0.01%; maximum 10000 = 100%).

Required range: x >= 1Must be a multiple of 1

description

string

required

Display text of the discount as it appears on invoices.

Minimum string length: 1

startDate

string<date>

required

Billing cycle date the discount starts at. From there it applies to the next invoiceCount invoices that bill its target.

invoiceCount

number | null

required

How many invoices the discount applies to, counted from startDate over the open invoices that bill its target; already-issued invoices are frozen and do not consume the count. Null means the discount applies until deactivated.

Required range: x >= 1Must be a multiple of 1

distributionMode

enum<string>

required

For fixed discounts on contracts that split invoices across payment accounts: full applies the whole amount on each invoice of the cycle; proportional splits the amount across the cycle's invoices in proportion to their totals. Percentage discounts always apply per invoice.

Available options:

proportional,

full

isActive

boolean

required

Whether the discount is applied to new billing cycles. Inactive discounts are kept for history but no longer applied.