Change Customer by External ID

PATCH

customers

external

{external_id}

Change Customer by External ID

curl --request PATCH \
  --url https://api.getruba.com/v1/customers/external/{external_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "metadata": {},
  "email": "customer@example.com",
  "name": "John Doe",
  "billing_address": {
    "line1": "<string>",
    "line2": "<string>",
    "postal_code": "<string>",
    "city": "<string>",
    "state": "<string>"
  },
  "tax_id": "<string>",
  "locale": "en"
}
'

import requests

url = "https://api.getruba.com/v1/customers/external/{external_id}"

payload = {
    "metadata": {},
    "email": "customer@example.com",
    "name": "John Doe",
    "billing_address": {
        "line1": "<string>",
        "line2": "<string>",
        "postal_code": "<string>",
        "city": "<string>",
        "state": "<string>"
    },
    "tax_id": "<string>",
    "locale": "en"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    metadata: {},
    email: 'customer@example.com',
    name: 'John Doe',
    billing_address: {
      line1: '<string>',
      line2: '<string>',
      postal_code: '<string>',
      city: '<string>',
      state: '<string>'
    },
    tax_id: '<string>',
    locale: 'en'
  })
};

fetch('https://api.getruba.com/v1/customers/external/{external_id}', 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/customers/external/{external_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'metadata' => [
        
    ],
    'email' => 'customer@example.com',
    'name' => 'John Doe',
    'billing_address' => [
        'line1' => '<string>',
        'line2' => '<string>',
        'postal_code' => '<string>',
        'city' => '<string>',
        'state' => '<string>'
    ],
    'tax_id' => '<string>',
    'locale' => 'en'
  ]),
  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/customers/external/{external_id}"

	payload := strings.NewReader("{\n  \"metadata\": {},\n  \"email\": \"customer@example.com\",\n  \"name\": \"John Doe\",\n  \"billing_address\": {\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\"\n  },\n  \"tax_id\": \"<string>\",\n  \"locale\": \"en\"\n}")

	req, _ := http.NewRequest("PATCH", 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.patch("https://api.getruba.com/v1/customers/external/{external_id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"metadata\": {},\n  \"email\": \"customer@example.com\",\n  \"name\": \"John Doe\",\n  \"billing_address\": {\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\"\n  },\n  \"tax_id\": \"<string>\",\n  \"locale\": \"en\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.getruba.com/v1/customers/external/{external_id}")

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

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"metadata\": {},\n  \"email\": \"customer@example.com\",\n  \"name\": \"John Doe\",\n  \"billing_address\": {\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\"\n  },\n  \"tax_id\": \"<string>\",\n  \"locale\": \"en\"\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",
  "metadata": {},
  "email": "<string>",
  "email_verified": true,
  "type": "<string>",
  "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",
  "locale": "<string>",
  "default_payment_method_id": "<string>"
}

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

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

Authorizations

Authorization

string

header

required

Authentication: You can generate a Personal Access Token from your settings.

Path Parameters

external_id

string

required

Identifier of the customer external.

Body

application/json

metadata

Metadata · object

Metadata map for information your integration needs to retain.

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

string<email> | null

Email: Email address of the customer. This must be unique within the organization.

Example:

"customer@example.com"

name

string | null

Name assigned to the customer.

Maximum string length: 256

Example:

"John Doe"

billing_address

AddressInput · object | null

Show child attributes

tax_id

string | null

locale

string | null

Locale: Locale of the customer, given as an IETF BCP 47 language tag. Supported: language code (e.g. en) or language + region (e.g. en-US). If null or unsupported, the locale will default to en.

Pattern: ^[a-zA-Z]{2,3}(-[a-zA-Z]{2}|-[0-9]{3})?$

Example:

"en"

Response

Response: Customer updated.

CustomerIndividual
CustomerTeam

Object representing customer in an organization.

string<uuid4>

required

Unique identifier for the customer.

Example:

"992fae2a-2a17-4b7a-8d9e-e287cf90131b"

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.

metadata

object

required

Show child attributes

string

required

Email: Email address of the customer. This must be unique within the organization.

Example:

"customer@example.com"

email_verified

boolean

required

Indicates whether the customer email address is verified. The address is automatically verified when the customer accesses the customer portal using their email address.

Example:

true

type

string

required

Type: Type of customer.

Allowed value: "individual"

Example:

"individual"

name

string | null

required

Name assigned to the customer.

Example:

"John Doe"

billing_name

string | null

required

Billing Name: Name that should appear on the customer's invoices. Falls back to the customer name when not explicitly set.

Example:

"John Doe"

billing_address

Address · object | null

required

Show child attributes

tax_id

Tax Id · object | null

required

Show child attributes

organization_id

string<uuid4>

required

Unique identifier for the organization owning the customer.

Example:

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

deleted_at

string<date-time> | null

required

Deleted At: Timestamp for when the customer was soft deleted.

avatar_url

string | null

required

Example:

"https://www.gravatar.com/avatar/xxx?d=404"

external_id

string | null

Unique identifier for the customer in your system. This must be unique within the organization. Once set, it can't be updated.

Example:

"usr_1337"

locale

string | null

default_payment_method_id

string<uuid4> | null

Unique identifier for the customer's default payment method, if any. Use the payment methods endpoint to retrieve its details.

Delete Customer### Intent Removes the customer. ### When to call it Call this only after your application has identified the customer that should be removed. ### Access boundary Authorize the request with a token that carries `customers:write`. ### Successful result A successful request returns `204` without a response document. ### Operational notes This action cannot be undone and will immediately: - Cancel any active subscriptions for the customer - Revoke all their benefits - Clear any `external_id` Use it only in the context of deleting a user within your own service. Otherwise, use more granular API endpoints to cancel a specific subscription or revoke certain benefits. Note: The customers information will nonetheless be retained for historic orders and subscriptions. Set `anonymize=true` to also anonymize PII for GDPR compliance.

⌘I

Change Customer by External ID

curl --request PATCH \
  --url https://api.getruba.com/v1/customers/external/{external_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "metadata": {},
  "email": "customer@example.com",
  "name": "John Doe",
  "billing_address": {
    "line1": "<string>",
    "line2": "<string>",
    "postal_code": "<string>",
    "city": "<string>",
    "state": "<string>"
  },
  "tax_id": "<string>",
  "locale": "en"
}
'

import requests

url = "https://api.getruba.com/v1/customers/external/{external_id}"

payload = {
    "metadata": {},
    "email": "customer@example.com",
    "name": "John Doe",
    "billing_address": {
        "line1": "<string>",
        "line2": "<string>",
        "postal_code": "<string>",
        "city": "<string>",
        "state": "<string>"
    },
    "tax_id": "<string>",
    "locale": "en"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    metadata: {},
    email: 'customer@example.com',
    name: 'John Doe',
    billing_address: {
      line1: '<string>',
      line2: '<string>',
      postal_code: '<string>',
      city: '<string>',
      state: '<string>'
    },
    tax_id: '<string>',
    locale: 'en'
  })
};

fetch('https://api.getruba.com/v1/customers/external/{external_id}', 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/customers/external/{external_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'metadata' => [
        
    ],
    'email' => 'customer@example.com',
    'name' => 'John Doe',
    'billing_address' => [
        'line1' => '<string>',
        'line2' => '<string>',
        'postal_code' => '<string>',
        'city' => '<string>',
        'state' => '<string>'
    ],
    'tax_id' => '<string>',
    'locale' => 'en'
  ]),
  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/customers/external/{external_id}"

	payload := strings.NewReader("{\n  \"metadata\": {},\n  \"email\": \"customer@example.com\",\n  \"name\": \"John Doe\",\n  \"billing_address\": {\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\"\n  },\n  \"tax_id\": \"<string>\",\n  \"locale\": \"en\"\n}")

	req, _ := http.NewRequest("PATCH", 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.patch("https://api.getruba.com/v1/customers/external/{external_id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"metadata\": {},\n  \"email\": \"customer@example.com\",\n  \"name\": \"John Doe\",\n  \"billing_address\": {\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\"\n  },\n  \"tax_id\": \"<string>\",\n  \"locale\": \"en\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.getruba.com/v1/customers/external/{external_id}")

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

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"metadata\": {},\n  \"email\": \"customer@example.com\",\n  \"name\": \"John Doe\",\n  \"billing_address\": {\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\"\n  },\n  \"tax_id\": \"<string>\",\n  \"locale\": \"en\"\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",
  "metadata": {},
  "email": "<string>",
  "email_verified": true,
  "type": "<string>",
  "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",
  "locale": "<string>",
  "default_payment_method_id": "<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

Change Customer by External ID

Intent

When to call it

Access boundary

Successful result

Authorizations

Path Parameters

Body

Response