Create Discount

Intent

Creates a discount from the values supplied in the request.

When to call it

Call this when your application has collected the required values and is ready to create a discount.

Access boundary

Authorize the request with a token that carries discounts:write.

Successful result

A successful request returns 201. The response schema below defines the body your integration receives.

Operational notes

Create a discount.

Scopes: discounts:write

POST

discounts

Create Discount

curl --request POST \
  --url https://api.getruba.com/v1/discounts/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "metadata": {},
  "code": "<string>",
  "starts_at": "2023-11-07T05:31:56Z",
  "ends_at": "2023-11-07T05:31:56Z",
  "max_redemptions": 1073741824,
  "products": [
    "<string>"
  ],
  "organization_id": "1dbfc517-0bbf-4301-9ba8-555ca42b9737",
  "type": "fixed",
  "duration_in_months": 500,
  "amount": 499999999999,
  "currency": "usd",
  "amounts": {}
}
'

import requests

url = "https://api.getruba.com/v1/discounts/"

payload = {
    "name": "<string>",
    "metadata": {},
    "code": "<string>",
    "starts_at": "2023-11-07T05:31:56Z",
    "ends_at": "2023-11-07T05:31:56Z",
    "max_redemptions": 1073741824,
    "products": ["<string>"],
    "organization_id": "1dbfc517-0bbf-4301-9ba8-555ca42b9737",
    "type": "fixed",
    "duration_in_months": 500,
    "amount": 499999999999,
    "currency": "usd",
    "amounts": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    metadata: {},
    code: '<string>',
    starts_at: '2023-11-07T05:31:56Z',
    ends_at: '2023-11-07T05:31:56Z',
    max_redemptions: 1073741824,
    products: ['<string>'],
    organization_id: '1dbfc517-0bbf-4301-9ba8-555ca42b9737',
    type: 'fixed',
    duration_in_months: 500,
    amount: 499999999999,
    currency: 'usd',
    amounts: {}
  })
};

fetch('https://api.getruba.com/v1/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.getruba.com/v1/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([
    'name' => '<string>',
    'metadata' => [
        
    ],
    'code' => '<string>',
    'starts_at' => '2023-11-07T05:31:56Z',
    'ends_at' => '2023-11-07T05:31:56Z',
    'max_redemptions' => 1073741824,
    'products' => [
        '<string>'
    ],
    'organization_id' => '1dbfc517-0bbf-4301-9ba8-555ca42b9737',
    'type' => 'fixed',
    'duration_in_months' => 500,
    'amount' => 499999999999,
    'currency' => 'usd',
    'amounts' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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.getruba.com/v1/discounts/"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"metadata\": {},\n  \"code\": \"<string>\",\n  \"starts_at\": \"2023-11-07T05:31:56Z\",\n  \"ends_at\": \"2023-11-07T05:31:56Z\",\n  \"max_redemptions\": 1073741824,\n  \"products\": [\n    \"<string>\"\n  ],\n  \"organization_id\": \"1dbfc517-0bbf-4301-9ba8-555ca42b9737\",\n  \"type\": \"fixed\",\n  \"duration_in_months\": 500,\n  \"amount\": 499999999999,\n  \"currency\": \"usd\",\n  \"amounts\": {}\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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.getruba.com/v1/discounts/")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"metadata\": {},\n  \"code\": \"<string>\",\n  \"starts_at\": \"2023-11-07T05:31:56Z\",\n  \"ends_at\": \"2023-11-07T05:31:56Z\",\n  \"max_redemptions\": 1073741824,\n  \"products\": [\n    \"<string>\"\n  ],\n  \"organization_id\": \"1dbfc517-0bbf-4301-9ba8-555ca42b9737\",\n  \"type\": \"fixed\",\n  \"duration_in_months\": 500,\n  \"amount\": 499999999999,\n  \"currency\": \"usd\",\n  \"amounts\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.getruba.com/v1/discounts/")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"metadata\": {},\n  \"code\": \"<string>\",\n  \"starts_at\": \"2023-11-07T05:31:56Z\",\n  \"ends_at\": \"2023-11-07T05:31:56Z\",\n  \"max_redemptions\": 1073741824,\n  \"products\": [\n    \"<string>\"\n  ],\n  \"organization_id\": \"1dbfc517-0bbf-4301-9ba8-555ca42b9737\",\n  \"type\": \"fixed\",\n  \"duration_in_months\": 500,\n  \"amount\": 499999999999,\n  \"currency\": \"usd\",\n  \"amounts\": {}\n}"

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

{
  "duration": "once",
  "type": "fixed",
  "amount": 1000,
  "currency": "usd",
  "amounts": {
    "eur": 900,
    "usd": 1000
  },
  "created_at": "2023-11-07T05:31:56Z",
  "modified_at": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "metadata": {},
  "name": "<string>",
  "code": "<string>",
  "starts_at": "2023-11-07T05:31:56Z",
  "ends_at": "2023-11-07T05:31:56Z",
  "max_redemptions": 123,
  "redemptions_count": 123,
  "organization_id": "1dbfc517-0bbf-4301-9ba8-555ca42b9737",
  "products": [
    {
      "metadata": {},
      "id": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "modified_at": "2023-11-07T05:31:56Z",
      "trial_interval": "day",
      "trial_interval_count": 123,
      "name": "<string>",
      "description": "<string>",
      "visibility": "draft",
      "recurring_interval": "day",
      "recurring_interval_count": 123,
      "is_recurring": true,
      "is_archived": true,
      "organization_id": "<string>"
    }
  ]
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Authorizations

Authorization

string

header

required

You can generate an Organization Access Token from your organization's settings.

Body

application/json

DiscountFixedCreate
DiscountPercentageCreate

Schema to create a fixed amount discount.

name

string

required

Name of the discount. Will be displayed to the customer when the discount is applied.

Minimum string length: 1

duration

enum<string>

required

For subscriptions, determines if the discount should be applied once on the first invoice, forever, or for a certain number of months determined by duration_in_months.

Available options:

once,

forever,

repeating

metadata

Metadata · object

Key-value object allowing you to store additional information.

The key must be a string with a maximum length of 40 characters. The value must be either:

A string with a maximum length of 500 characters
An integer
A floating-point number
A boolean

You can store up to 50 key-value pairs.

Show child attributes

code

string | null

Code customers can use to apply the discount during checkout. Must be between 3 and 256 characters long and contain only alphanumeric characters.If not provided, the discount can only be applied via the API.

starts_at

string<date-time> | null

Optional timestamp after which the discount is redeemable.

ends_at

string<date-time> | null

Optional timestamp after which the discount is no longer redeemable.

max_redemptions

integer | null

Optional maximum number of times the discount can be redeemed.

Required range: 1 <= x <= 2147483647

products

string<uuid4>[] | null

List of product IDs the discount can be applied to.

organization_id

string<uuid4> | null

The organization ID.

Example:

"1dbfc517-0bbf-4301-9ba8-555ca42b9737"

type

string

default:fixed

Allowed value: "fixed"

duration_in_months

integer | null

Number of months the discount should be applied.

Required when duration is repeating. Must be omitted otherwise.

For this to work on yearly pricing, you should multiply this by 12. For example, to apply the discount for 2 years, set this to 24.

Required range: 1 <= x <= 999

amount

integer | null

deprecated

Fixed amount to discount from the invoice total.

Required range: 0 <= x <= 999999999999

currency

enum<string> | null

default:usd

deprecated

The currency of the fixed amount discount.

Available options:

aed,

all,

amd,

aoa,

ars,

aud,

awg,

azn,

bam,

bbd,

bdt,

bif,

bmd,

bnd,

bob,

brl,

bsd,

bwp,

bzd,

cad,

cdf,

chf,

clp,

cny,

cop,

crc,

cve,

czk,

djf,

dkk,

dop,

dzd,

egp,

etb,

eur,

fjd,

fkp,

gbp,

gel,

gip,

gmd,

gnf,

gtq,

gyd,

hkd,

hnl,

htg,

huf,

idr,

ils,

inr,

isk,

jmd,

jpy,

kes,

kgs,

khr,

kmf,

krw,

kyd,

kzt,

lak,

lkr,

lrd,

lsl,

mad,

mdl,

mga,

mkd,

mnt,

mop,

mur,

mvr,

mwk,

mxn,

myr,

mzn,

nad,

ngn,

nio,

nok,

npr,

nzd,

pab,

pen,

pgk,

php,

pkr,

pln,

pyg,

qar,

ron,

rsd,

rwf,

sar,

sbd,

scr,

sek,

sgd,

shp,

sos,

srd,

szl,

thb,

tjs,

top,

try,

ttd,

twd,

tzs,

uah,

ugx,

usd,

uyu,

uzs,

vnd,

vuv,

wst,

xaf,

xcd,

xcg,

xof,

xpf,

yer,

zar,

zmw

amounts

Amounts · object | null

Map of currency to fixed amount to discount from the total. This allows specifying different discount amounts for different currencies.

Show child attributes

Response

Discount created.

DiscountFixedOnceForeverDuration
DiscountFixedRepeatDuration
DiscountPercentageOnceForeverDuration
DiscountPercentageRepeatDuration

Schema for a fixed amount discount that is applied once or forever.

duration

enum<string>

required

Available options:

once,

forever,

repeating

type

enum<string>

required

Available options:

fixed,

percentage

amount

integer

required

deprecated

Example:

1000

currency

string

required

deprecated

Example:

"usd"

amounts

Amounts · object

required

Map of currency to fixed amount to discount from the total.

Show child attributes

Example:

{ "eur": 900, "usd": 1000 }

created_at

string<date-time>

required

The time Ruba created this record.

modified_at

string<date-time> | null

required

The time this record last changed.

string<uuid4>

required

The stable identifier for this record.

metadata

object

required

Show child attributes

name

string

required

Name of the discount. Will be displayed to the customer when the discount is applied.

code

string | null

required

Code customers can use to apply the discount during checkout.

starts_at

string<date-time> | null

required

Timestamp after which the discount is redeemable.

ends_at

string<date-time> | null

required

Timestamp after which the discount is no longer redeemable.

max_redemptions

integer | null

required

Maximum number of times the discount can be redeemed.

redemptions_count

integer

required

Number of times the discount has been redeemed.

organization_id

string<uuid4>

required

The organization ID.

Example:

"1dbfc517-0bbf-4301-9ba8-555ca42b9737"

products

DiscountProduct · object[]

required

Show child attributes

Create Discount

curl --request POST \
  --url https://api.getruba.com/v1/discounts/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "metadata": {},
  "code": "<string>",
  "starts_at": "2023-11-07T05:31:56Z",
  "ends_at": "2023-11-07T05:31:56Z",
  "max_redemptions": 1073741824,
  "products": [
    "<string>"
  ],
  "organization_id": "1dbfc517-0bbf-4301-9ba8-555ca42b9737",
  "type": "fixed",
  "duration_in_months": 500,
  "amount": 499999999999,
  "currency": "usd",
  "amounts": {}
}
'

import requests

url = "https://api.getruba.com/v1/discounts/"

payload = {
    "name": "<string>",
    "metadata": {},
    "code": "<string>",
    "starts_at": "2023-11-07T05:31:56Z",
    "ends_at": "2023-11-07T05:31:56Z",
    "max_redemptions": 1073741824,
    "products": ["<string>"],
    "organization_id": "1dbfc517-0bbf-4301-9ba8-555ca42b9737",
    "type": "fixed",
    "duration_in_months": 500,
    "amount": 499999999999,
    "currency": "usd",
    "amounts": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    metadata: {},
    code: '<string>',
    starts_at: '2023-11-07T05:31:56Z',
    ends_at: '2023-11-07T05:31:56Z',
    max_redemptions: 1073741824,
    products: ['<string>'],
    organization_id: '1dbfc517-0bbf-4301-9ba8-555ca42b9737',
    type: 'fixed',
    duration_in_months: 500,
    amount: 499999999999,
    currency: 'usd',
    amounts: {}
  })
};

fetch('https://api.getruba.com/v1/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.getruba.com/v1/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([
    'name' => '<string>',
    'metadata' => [
        
    ],
    'code' => '<string>',
    'starts_at' => '2023-11-07T05:31:56Z',
    'ends_at' => '2023-11-07T05:31:56Z',
    'max_redemptions' => 1073741824,
    'products' => [
        '<string>'
    ],
    'organization_id' => '1dbfc517-0bbf-4301-9ba8-555ca42b9737',
    'type' => 'fixed',
    'duration_in_months' => 500,
    'amount' => 499999999999,
    'currency' => 'usd',
    'amounts' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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.getruba.com/v1/discounts/"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"metadata\": {},\n  \"code\": \"<string>\",\n  \"starts_at\": \"2023-11-07T05:31:56Z\",\n  \"ends_at\": \"2023-11-07T05:31:56Z\",\n  \"max_redemptions\": 1073741824,\n  \"products\": [\n    \"<string>\"\n  ],\n  \"organization_id\": \"1dbfc517-0bbf-4301-9ba8-555ca42b9737\",\n  \"type\": \"fixed\",\n  \"duration_in_months\": 500,\n  \"amount\": 499999999999,\n  \"currency\": \"usd\",\n  \"amounts\": {}\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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.getruba.com/v1/discounts/")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"metadata\": {},\n  \"code\": \"<string>\",\n  \"starts_at\": \"2023-11-07T05:31:56Z\",\n  \"ends_at\": \"2023-11-07T05:31:56Z\",\n  \"max_redemptions\": 1073741824,\n  \"products\": [\n    \"<string>\"\n  ],\n  \"organization_id\": \"1dbfc517-0bbf-4301-9ba8-555ca42b9737\",\n  \"type\": \"fixed\",\n  \"duration_in_months\": 500,\n  \"amount\": 499999999999,\n  \"currency\": \"usd\",\n  \"amounts\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.getruba.com/v1/discounts/")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"metadata\": {},\n  \"code\": \"<string>\",\n  \"starts_at\": \"2023-11-07T05:31:56Z\",\n  \"ends_at\": \"2023-11-07T05:31:56Z\",\n  \"max_redemptions\": 1073741824,\n  \"products\": [\n    \"<string>\"\n  ],\n  \"organization_id\": \"1dbfc517-0bbf-4301-9ba8-555ca42b9737\",\n  \"type\": \"fixed\",\n  \"duration_in_months\": 500,\n  \"amount\": 499999999999,\n  \"currency\": \"usd\",\n  \"amounts\": {}\n}"

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

{
  "duration": "once",
  "type": "fixed",
  "amount": 1000,
  "currency": "usd",
  "amounts": {
    "eur": 900,
    "usd": 1000
  },
  "created_at": "2023-11-07T05:31:56Z",
  "modified_at": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "metadata": {},
  "name": "<string>",
  "code": "<string>",
  "starts_at": "2023-11-07T05:31:56Z",
  "ends_at": "2023-11-07T05:31:56Z",
  "max_redemptions": 123,
  "redemptions_count": 123,
  "organization_id": "1dbfc517-0bbf-4301-9ba8-555ca42b9737",
  "products": [
    {
      "metadata": {},
      "id": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "modified_at": "2023-11-07T05:31:56Z",
      "trial_interval": "day",
      "trial_interval_count": 123,
      "name": "<string>",
      "description": "<string>",
      "visibility": "draft",
      "recurring_interval": "day",
      "recurring_interval_count": 123,
      "is_recurring": true,
      "is_archived": true,
      "organization_id": "<string>"
    }
  ]
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Read This First

Create a Sale

Collect and Reconcile

Manage Recurring Revenue

Model Customer Access

Power the Customer Portal

Configure the Platform

React to State Changes

Create Discount

Intent

When to call it

Access boundary

Successful result

Operational notes

Authorizations

Body

Response