Complete Order

Intent

Runs the complete order action.

When to call it

Call this when your workflow reaches the point where it must complete order.

Access boundary

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

Successful result

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

Operational notes

Finalize a draft order and synchronously attempt an off-session charge.

On success, the order transitions to paid and benefit grants fire before the response returns. On failure (decline, missing payment method, SCA challenge), the order stays in draft and a 4xx error is returned.

The request fails with 412 if the order is not in draft status.

Scopes: orders:write

POST

orders

{id}

finalize

Complete Order

curl --request POST \
  --url https://api.getruba.com/v1/orders/{id}/finalize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

import requests

url = "https://api.getruba.com/v1/orders/{id}/finalize"

payload = {}
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({})
};

fetch('https://api.getruba.com/v1/orders/{id}/finalize', 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/{id}/finalize",
  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([
    
  ]),
  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/{id}/finalize"

	payload := strings.NewReader("{}")

	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/{id}/finalize")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.getruba.com/v1/orders/{id}/finalize")

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

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

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

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

Path Parameters

string<uuid4>

required

The order ID.

Body

application/json

Schema to finalize a draft order and trigger an off-session charge.

payment_method_id

string<uuid4> | null

ID of the payment method to charge. Must belong to the order's customer. Falls back to the customer's default payment method when unset.

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

Build Order Invoice### Intent Runs the build order invoice action. ### When to call it Call this when your workflow reaches the point where it must build order invoice. ### Access boundary Authorize the request with a token that carries `orders:read`. ### Successful result A successful request returns `202`. The response schema below defines the body your integration receives. ### Operational notes Trigger generation of an order's invoice. **Scopes**: `orders:read`

Complete Order

curl --request POST \
  --url https://api.getruba.com/v1/orders/{id}/finalize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

import requests

url = "https://api.getruba.com/v1/orders/{id}/finalize"

payload = {}
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({})
};

fetch('https://api.getruba.com/v1/orders/{id}/finalize', 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/{id}/finalize",
  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([
    
  ]),
  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/{id}/finalize"

	payload := strings.NewReader("{}")

	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/{id}/finalize")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.getruba.com/v1/orders/{id}/finalize")

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

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

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<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

Complete Order

Intent

When to call it

Access boundary

Successful result

Operational notes

Authorizations

Path Parameters

Body

Response