Create Order

Intent

Creates an order 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 an order.

Access boundary

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

Successful result

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

Operational notes

Create a draft order for an off-session charge against a saved payment method. The order is created with status=draft and no invoice number; call POST /v1/orders/{id}/finalize to attempt the charge.

The organization must have the off_session_charges_enabled feature flag.

Scopes: orders:write

POST

orders

Create Order

curl --request POST \
  --url https://api.getruba.com/v1/orders/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "<string>",
  "product_id": "<string>",
  "custom_field_data": {},
  "metadata": {},
  "organization_id": "1dbfc517-0bbf-4301-9ba8-555ca42b9737",
  "currency": "<string>",
  "amount": 1,
  "description": "<string>"
}
'

import requests

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

payload = {
    "customer_id": "<string>",
    "product_id": "<string>",
    "custom_field_data": {},
    "metadata": {},
    "organization_id": "1dbfc517-0bbf-4301-9ba8-555ca42b9737",
    "currency": "<string>",
    "amount": 1,
    "description": "<string>"
}
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({
    customer_id: '<string>',
    product_id: '<string>',
    custom_field_data: {},
    metadata: {},
    organization_id: '1dbfc517-0bbf-4301-9ba8-555ca42b9737',
    currency: '<string>',
    amount: 1,
    description: '<string>'
  })
};

fetch('https://api.getruba.com/v1/orders/', 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/orders/",
  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([
    'customer_id' => '<string>',
    'product_id' => '<string>',
    'custom_field_data' => [
        
    ],
    'metadata' => [
        
    ],
    'organization_id' => '1dbfc517-0bbf-4301-9ba8-555ca42b9737',
    'currency' => '<string>',
    'amount' => 1,
    'description' => '<string>'
  ]),
  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/orders/"

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

require 'uri'
require 'net/http'

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

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  \"customer_id\": \"<string>\",\n  \"product_id\": \"<string>\",\n  \"custom_field_data\": {},\n  \"metadata\": {},\n  \"organization_id\": \"1dbfc517-0bbf-4301-9ba8-555ca42b9737\",\n  \"currency\": \"<string>\",\n  \"amount\": 1,\n  \"description\": \"<string>\"\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",
  "paid": true,
  "subtotal_amount": 123,
  "discount_amount": 123,
  "net_amount": 123,
  "tax_amount": 123,
  "total_amount": 123,
  "applied_balance_amount": 123,
  "due_amount": 123,
  "refunded_amount": 123,
  "refunded_tax_amount": 123,
  "currency": "<string>",
  "billing_name": "<string>",
  "billing_address": {
    "line1": "<string>",
    "line2": "<string>",
    "postal_code": "<string>",
    "city": "<string>",
    "state": "<string>"
  },
  "invoice_number": "<string>",
  "is_invoice_generated": true,
  "receipt_number": "<string>",
  "customer_id": "<string>",
  "product_id": "<string>",
  "discount_id": "<string>",
  "subscription_id": "<string>",
  "checkout_id": "<string>",
  "metadata": {},
  "platform_fee_amount": 123,
  "platform_fee_currency": "usd",
  "customer": {
    "id": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "modified_at": "2023-11-07T05:31:56Z",
    "metadata": {},
    "email_verified": true,
    "name": "John Doe",
    "billing_name": "John Doe",
    "billing_address": {
      "line1": "<string>",
      "line2": "<string>",
      "postal_code": "<string>",
      "city": "<string>",
      "state": "<string>"
    },
    "tax_id": {
      "[0]": "<string>"
    },
    "organization_id": "<string>",
    "deleted_at": "2023-11-07T05:31:56Z",
    "avatar_url": "https://www.gravatar.com/avatar/xxx?d=404",
    "external_id": "usr_1337",
    "email": "customer@example.com",
    "locale": "<string>",
    "default_payment_method_id": "<string>"
  },
  "product": {
    "metadata": {},
    "id": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "modified_at": "2023-11-07T05:31:56Z",
    "trial_interval_count": 123,
    "name": "<string>",
    "description": "<string>",
    "recurring_interval_count": 123,
    "is_recurring": true,
    "is_archived": true,
    "organization_id": "<string>"
  },
  "discount": {
    "amount": 123,
    "currency": "<string>",
    "amounts": {},
    "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": "<string>"
  },
  "subscription": {
    "metadata": {},
    "created_at": "2023-11-07T05:31:56Z",
    "modified_at": "2023-11-07T05:31:56Z",
    "id": "<string>",
    "amount": 123,
    "currency": "<string>",
    "recurring_interval_count": 123,
    "current_period_start": "2023-11-07T05:31:56Z",
    "current_period_end": "2023-11-07T05:31:56Z",
    "trial_start": "2023-11-07T05:31:56Z",
    "trial_end": "2023-11-07T05:31:56Z",
    "cancel_at_period_end": true,
    "canceled_at": "2023-11-07T05:31:56Z",
    "started_at": "2023-11-07T05:31:56Z",
    "ends_at": "2023-11-07T05:31:56Z",
    "ended_at": "2023-11-07T05:31:56Z",
    "customer_id": "<string>",
    "product_id": "<string>",
    "discount_id": "<string>",
    "checkout_id": "<string>",
    "customer_cancellation_comment": "<string>",
    "past_due_at": "2023-11-07T05:31:56Z",
    "seats": 123
  },
  "items": [
    {
      "created_at": "2023-11-07T05:31:56Z",
      "modified_at": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "label": "<string>",
      "amount": 123,
      "tax_amount": 123,
      "proration": true,
      "product_price_id": "<string>"
    }
  ],
  "description": "<string>",
  "refundable_amount": 123,
  "refundable_tax_amount": 123,
  "seats": 123,
  "next_payment_attempt_at": "2023-11-07T05:31:56Z",
  "custom_field_data": {}
}

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

Authorizations

Authorization

string

header

required

You can generate a Personal Access Token from your settings.

Body

application/json

Schema to create a draft order for an off-session charge.

customer_id

string<uuid4>

required

The ID of the customer the order is for. Must belong to the order's organization.

product_id

string<uuid4>

required

The ID of the one-time product to charge for. Must belong to the order's organization. Only fixed-price and free products are supported.

custom_field_data

Custom Field Data · object

Key-value object storing custom field values.

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"

currency

string | null

The currency to charge in (ISO 4217, lowercase, e.g. usd). Defaults to the organization's default currency; specify it to force a different one, or when the product isn't priced in the organization's default currency.

amount

integer | null

A custom amount to charge, in the smallest currency unit. Overrides the product's price; defaults to the product's configured price (0 for free products). A positive amount must be at least the currency's minimum.

Required range: x >= 0

description

string | null

A custom description for the order's line item, shown on the invoice and receipt (e.g. 5,000 tokens). Defaults to the product name.

Maximum string length: 500

Response

Successful Response

string<uuid4>

required

The stable identifier for this record.

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.

status

enum<string>

required

Available options:

draft,

pending,

paid,

refunded,

partially_refunded,

void

Example:

"paid"

paid

boolean

required

Whether the order has been paid for.

Example:

true

subtotal_amount

integer

required

Amount in cents, before discounts and taxes.

Example:

10000

discount_amount

integer

required

Discount amount in cents.

Example:

1000

net_amount

integer

required

Amount in cents, after discounts but before taxes.

Example:

9000

tax_amount

integer

required

Sales tax amount in cents.

Example:

720

total_amount

integer

required

Amount in cents, after discounts and taxes.

Example:

9720

applied_balance_amount

integer

required

Customer's balance amount applied to this invoice. Can increase the total amount paid, if the customer has a negative balance, or decrease it, if the customer has a positive balance.Amount in cents.

Example:

0

due_amount

integer

required

Amount in cents that is due for this order.

Example:

0

refunded_amount

integer

required

Amount refunded in cents.

Example:

0

refunded_tax_amount

integer

required

Sales tax refunded in cents.

Example:

0

currency

string

required

Example:

"usd"

billing_reason

enum<string>

required

Available options:

purchase,

subscription_create,

subscription_cycle,

subscription_update

billing_name

string | null

required

The name of the customer that should appear on the invoice.

billing_address

Address · object | null

required

Show child attributes

invoice_number

string | null

required

The invoice number associated with this order. null while the order is in draft status; assigned at finalize.

is_invoice_generated

boolean

required

Whether an invoice has been generated for this order.

receipt_number

string | null

required

The receipt number for this order. Set once the order is paid for organizations with receipts enabled. When set, a downloadable receipt PDF can be obtained via the receipt endpoint.

customer_id

string<uuid4>

required

product_id

string<uuid4> | null

required

discount_id

string<uuid4> | null

required

subscription_id

string<uuid4> | null

required

checkout_id

string<uuid4> | null

required

metadata

object

required

Show child attributes

platform_fee_amount

integer

required

Platform fee amount in cents.

Example:

500

platform_fee_currency

string | null

required

Currency of the platform fee.

Example:

"usd"

customer

OrderCustomer · object

required

Show child attributes

product

OrderProduct · object | null

required

Show child attributes

discount

DiscountFixedOnceForeverDurationBase · object

required

DiscountFixedOnceForeverDurationBase
DiscountFixedRepeatDurationBase
DiscountPercentageOnceForeverDurationBase
DiscountPercentageRepeatDurationBase

Show child attributes

subscription

OrderSubscription · object | null

required

Show child attributes

items

OrderItemSchema · object[]

required

Line items composing the order.

Show child attributes

description

string

required

A summary description of the order.

Example:

"Pro Plan"

refundable_amount

integer

required

read-only

Amount in cents that can still be refunded (net, before taxes). Accounts for any applied customer balance and previous refunds.

Example:

9000

refundable_tax_amount

integer

required

read-only

Sales tax in cents that would be refunded if the full refundable amount is refunded.

Example:

720

seats

integer | null

Number of seats purchased (for seat-based one-time orders).

next_payment_attempt_at

string<date-time> | null

When the next automatic payment retry is scheduled. null if the order is not in dunning or all retries have been exhausted.

custom_field_data

Custom Field Data · object

Key-value object storing custom field values.

Show child attributes

Export Orders### Intent Reads the orders without changing it. ### When to call it Call this after your application has received or stored the identifier for the orders. ### Access boundary Authorize the request with a token that carries `orders:read`. ### Successful result A successful request returns `200`. The response schema below defines the body your integration receives. ### Operational notes Export orders as a CSV file. **Scopes**: `orders:read`

Create Order

curl --request POST \
  --url https://api.getruba.com/v1/orders/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "<string>",
  "product_id": "<string>",
  "custom_field_data": {},
  "metadata": {},
  "organization_id": "1dbfc517-0bbf-4301-9ba8-555ca42b9737",
  "currency": "<string>",
  "amount": 1,
  "description": "<string>"
}
'

import requests

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

payload = {
    "customer_id": "<string>",
    "product_id": "<string>",
    "custom_field_data": {},
    "metadata": {},
    "organization_id": "1dbfc517-0bbf-4301-9ba8-555ca42b9737",
    "currency": "<string>",
    "amount": 1,
    "description": "<string>"
}
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({
    customer_id: '<string>',
    product_id: '<string>',
    custom_field_data: {},
    metadata: {},
    organization_id: '1dbfc517-0bbf-4301-9ba8-555ca42b9737',
    currency: '<string>',
    amount: 1,
    description: '<string>'
  })
};

fetch('https://api.getruba.com/v1/orders/', 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/orders/",
  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([
    'customer_id' => '<string>',
    'product_id' => '<string>',
    'custom_field_data' => [
        
    ],
    'metadata' => [
        
    ],
    'organization_id' => '1dbfc517-0bbf-4301-9ba8-555ca42b9737',
    'currency' => '<string>',
    'amount' => 1,
    'description' => '<string>'
  ]),
  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/orders/"

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

require 'uri'
require 'net/http'

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

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  \"customer_id\": \"<string>\",\n  \"product_id\": \"<string>\",\n  \"custom_field_data\": {},\n  \"metadata\": {},\n  \"organization_id\": \"1dbfc517-0bbf-4301-9ba8-555ca42b9737\",\n  \"currency\": \"<string>\",\n  \"amount\": 1,\n  \"description\": \"<string>\"\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",
  "paid": true,
  "subtotal_amount": 123,
  "discount_amount": 123,
  "net_amount": 123,
  "tax_amount": 123,
  "total_amount": 123,
  "applied_balance_amount": 123,
  "due_amount": 123,
  "refunded_amount": 123,
  "refunded_tax_amount": 123,
  "currency": "<string>",
  "billing_name": "<string>",
  "billing_address": {
    "line1": "<string>",
    "line2": "<string>",
    "postal_code": "<string>",
    "city": "<string>",
    "state": "<string>"
  },
  "invoice_number": "<string>",
  "is_invoice_generated": true,
  "receipt_number": "<string>",
  "customer_id": "<string>",
  "product_id": "<string>",
  "discount_id": "<string>",
  "subscription_id": "<string>",
  "checkout_id": "<string>",
  "metadata": {},
  "platform_fee_amount": 123,
  "platform_fee_currency": "usd",
  "customer": {
    "id": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "modified_at": "2023-11-07T05:31:56Z",
    "metadata": {},
    "email_verified": true,
    "name": "John Doe",
    "billing_name": "John Doe",
    "billing_address": {
      "line1": "<string>",
      "line2": "<string>",
      "postal_code": "<string>",
      "city": "<string>",
      "state": "<string>"
    },
    "tax_id": {
      "[0]": "<string>"
    },
    "organization_id": "<string>",
    "deleted_at": "2023-11-07T05:31:56Z",
    "avatar_url": "https://www.gravatar.com/avatar/xxx?d=404",
    "external_id": "usr_1337",
    "email": "customer@example.com",
    "locale": "<string>",
    "default_payment_method_id": "<string>"
  },
  "product": {
    "metadata": {},
    "id": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "modified_at": "2023-11-07T05:31:56Z",
    "trial_interval_count": 123,
    "name": "<string>",
    "description": "<string>",
    "recurring_interval_count": 123,
    "is_recurring": true,
    "is_archived": true,
    "organization_id": "<string>"
  },
  "discount": {
    "amount": 123,
    "currency": "<string>",
    "amounts": {},
    "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": "<string>"
  },
  "subscription": {
    "metadata": {},
    "created_at": "2023-11-07T05:31:56Z",
    "modified_at": "2023-11-07T05:31:56Z",
    "id": "<string>",
    "amount": 123,
    "currency": "<string>",
    "recurring_interval_count": 123,
    "current_period_start": "2023-11-07T05:31:56Z",
    "current_period_end": "2023-11-07T05:31:56Z",
    "trial_start": "2023-11-07T05:31:56Z",
    "trial_end": "2023-11-07T05:31:56Z",
    "cancel_at_period_end": true,
    "canceled_at": "2023-11-07T05:31:56Z",
    "started_at": "2023-11-07T05:31:56Z",
    "ends_at": "2023-11-07T05:31:56Z",
    "ended_at": "2023-11-07T05:31:56Z",
    "customer_id": "<string>",
    "product_id": "<string>",
    "discount_id": "<string>",
    "checkout_id": "<string>",
    "customer_cancellation_comment": "<string>",
    "past_due_at": "2023-11-07T05:31:56Z",
    "seats": 123
  },
  "items": [
    {
      "created_at": "2023-11-07T05:31:56Z",
      "modified_at": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "label": "<string>",
      "amount": 123,
      "tax_amount": 123,
      "proration": true,
      "product_price_id": "<string>"
    }
  ],
  "description": "<string>",
  "refundable_amount": 123,
  "refundable_tax_amount": 123,
  "seats": 123,
  "next_payment_attempt_at": "2023-11-07T05:31:56Z",
  "custom_field_data": {}
}

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

Intent

When to call it

Access boundary

Successful result

Operational notes

Authorizations

Body

Response