Create Benefit

Intent

Creates a benefit 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 benefit.

Access boundary

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

Successful result

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

Operational notes

Create a benefit.

Scopes: benefits:write

POST

benefits

Create Benefit

curl --request POST \
  --url https://api.getruba.com/v1/benefits/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "custom",
  "description": "<string>",
  "properties": {
    "note": "<string>"
  },
  "metadata": {},
  "organization_id": "1dbfc517-0bbf-4301-9ba8-555ca42b9737"
}
'

import requests

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

payload = {
    "type": "custom",
    "description": "<string>",
    "properties": { "note": "<string>" },
    "metadata": {},
    "organization_id": "1dbfc517-0bbf-4301-9ba8-555ca42b9737"
}
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({
    type: 'custom',
    description: '<string>',
    properties: {note: '<string>'},
    metadata: {},
    organization_id: '1dbfc517-0bbf-4301-9ba8-555ca42b9737'
  })
};

fetch('https://api.getruba.com/v1/benefits/', 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/benefits/",
  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([
    'type' => 'custom',
    'description' => '<string>',
    'properties' => [
        'note' => '<string>'
    ],
    'metadata' => [
        
    ],
    'organization_id' => '1dbfc517-0bbf-4301-9ba8-555ca42b9737'
  ]),
  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/benefits/"

	payload := strings.NewReader("{\n  \"type\": \"custom\",\n  \"description\": \"<string>\",\n  \"properties\": {\n    \"note\": \"<string>\"\n  },\n  \"metadata\": {},\n  \"organization_id\": \"1dbfc517-0bbf-4301-9ba8-555ca42b9737\"\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/benefits/")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"type\": \"custom\",\n  \"description\": \"<string>\",\n  \"properties\": {\n    \"note\": \"<string>\"\n  },\n  \"metadata\": {},\n  \"organization_id\": \"1dbfc517-0bbf-4301-9ba8-555ca42b9737\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"type\": \"custom\",\n  \"description\": \"<string>\",\n  \"properties\": {\n    \"note\": \"<string>\"\n  },\n  \"metadata\": {},\n  \"organization_id\": \"1dbfc517-0bbf-4301-9ba8-555ca42b9737\"\n}"

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

{
  "id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "modified_at": "2023-11-07T05:31:56Z",
  "type": "custom",
  "description": "<string>",
  "selectable": true,
  "deletable": true,
  "is_deleted": true,
  "organization_id": "<string>",
  "metadata": {},
  "visibility": "draft",
  "properties": {
    "note": "<string>"
  },
  "visibility_configurable": true
}

{
  "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

Schema to create a benefit of type custom.

type

string

required

Allowed value: "custom"

description

string

required

The description of the benefit. Will be displayed on products having this benefit.

Required string length: 3 - 42

properties

BenefitCustomCreateProperties · object

required

Properties for creating a benefit of type custom.

Show child attributes

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

organization_id

string<uuid4> | null

The organization ID.

Example:

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

visibility

enum<string> | null

The visibility of the benefit in the customer portal.

Available options:

draft,

private,

public

Response

Benefit created.

A benefit of type custom.

Use it to grant any kind of benefit that doesn't fit in the other types.

string<uuid4>

required

The ID of the benefit.

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.

type

string

required

Allowed value: "custom"

description

string

required

The description of the benefit.

selectable

boolean

required

Whether the benefit is selectable when creating a product.

deletable

boolean

required

Whether the benefit is deletable.

is_deleted

boolean

required

Whether the benefit is deleted.

organization_id

string<uuid4>

required

The ID of the organization owning the benefit.

metadata

object

required

Show child attributes

visibility

enum<string>

required

The visibility of the benefit in the customer portal.

Available options:

draft,

private,

public

properties

BenefitCustomProperties · object

required

Properties for a benefit of type custom.

Show child attributes

visibility_configurable

boolean

required

read-only

Create Benefit

curl --request POST \
  --url https://api.getruba.com/v1/benefits/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "custom",
  "description": "<string>",
  "properties": {
    "note": "<string>"
  },
  "metadata": {},
  "organization_id": "1dbfc517-0bbf-4301-9ba8-555ca42b9737"
}
'

import requests

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

payload = {
    "type": "custom",
    "description": "<string>",
    "properties": { "note": "<string>" },
    "metadata": {},
    "organization_id": "1dbfc517-0bbf-4301-9ba8-555ca42b9737"
}
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({
    type: 'custom',
    description: '<string>',
    properties: {note: '<string>'},
    metadata: {},
    organization_id: '1dbfc517-0bbf-4301-9ba8-555ca42b9737'
  })
};

fetch('https://api.getruba.com/v1/benefits/', 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/benefits/",
  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([
    'type' => 'custom',
    'description' => '<string>',
    'properties' => [
        'note' => '<string>'
    ],
    'metadata' => [
        
    ],
    'organization_id' => '1dbfc517-0bbf-4301-9ba8-555ca42b9737'
  ]),
  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/benefits/"

	payload := strings.NewReader("{\n  \"type\": \"custom\",\n  \"description\": \"<string>\",\n  \"properties\": {\n    \"note\": \"<string>\"\n  },\n  \"metadata\": {},\n  \"organization_id\": \"1dbfc517-0bbf-4301-9ba8-555ca42b9737\"\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/benefits/")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"type\": \"custom\",\n  \"description\": \"<string>\",\n  \"properties\": {\n    \"note\": \"<string>\"\n  },\n  \"metadata\": {},\n  \"organization_id\": \"1dbfc517-0bbf-4301-9ba8-555ca42b9737\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"type\": \"custom\",\n  \"description\": \"<string>\",\n  \"properties\": {\n    \"note\": \"<string>\"\n  },\n  \"metadata\": {},\n  \"organization_id\": \"1dbfc517-0bbf-4301-9ba8-555ca42b9737\"\n}"

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

{
  "id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "modified_at": "2023-11-07T05:31:56Z",
  "type": "custom",
  "description": "<string>",
  "selectable": true,
  "deletable": true,
  "is_deleted": true,
  "organization_id": "<string>",
  "metadata": {},
  "visibility": "draft",
  "properties": {
    "note": "<string>"
  },
  "visibility_configurable": true
}

{
  "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 Benefit

Intent

When to call it

Access boundary

Successful result

Operational notes

Authorizations

Body

Response