GET
/
customers
/
external_customer_id
/
{external_customer_id}
curl --request GET \
  --url https://api.withorb.com/v1/customers/external_customer_id/{external_customer_id} \
  --header 'Authorization: Bearer <token>'
{
  "metadata": {},
  "id": "<string>",
  "external_customer_id": "<string>",
  "name": "<string>",
  "email": "<string>",
  "timezone": "<string>",
  "payment_provider_id": "<string>",
  "payment_provider": "quickbooks",
  "created_at": "2023-11-07T05:31:56Z",
  "shipping_address": {
    "line1": "<string>",
    "line2": "<string>",
    "city": "<string>",
    "state": "<string>",
    "postal_code": "<string>",
    "country": "<string>"
  },
  "billing_address": {
    "line1": "<string>",
    "line2": "<string>",
    "city": "<string>",
    "state": "<string>",
    "postal_code": "<string>",
    "country": "<string>"
  },
  "balance": "<string>",
  "currency": "<string>",
  "tax_id": {
    "country": "AD",
    "type": "ad_nrt",
    "value": "<string>"
  },
  "auto_collection": true,
  "exempt_from_automated_tax": true,
  "email_delivery": true,
  "additional_emails": [
    "<string>"
  ],
  "portal_url": "<string>",
  "accounting_sync_configuration": {
    "excluded": true,
    "accounting_providers": [
      {
        "provider_type": "quickbooks",
        "external_provider_id": "<string>"
      }
    ]
  },
  "reporting_configuration": {
    "exempt": true
  },
  "hierarchy": {
    "parent": {
      "id": "<string>",
      "external_customer_id": "<string>"
    },
    "children": [
      {
        "id": "<string>",
        "external_customer_id": "<string>"
      }
    ]
  }
}

Authorizations

​
Authorization
string
header
required

API Keys can be issued in the Orb's web application.

Path Parameters

​
external_customer_id
string
required

Response

200
application/json
OK

A customer is a buyer of your products, and the other party to the billing relationship.

In Orb, customers are assigned system generated identifiers automatically, but it's often desirable to have these match existing identifiers in your system. To avoid having to denormalize Orb ID information, you can pass in an external_customer_id with your own identifier. See Customer ID Aliases for further information about how these aliases work in Orb.

In addition to having an identifier in your system, a customer may exist in a payment provider solution like Stripe. Use the payment_provider_id and the payment_provider enum field to express this mapping.

A customer also has a timezone (from the standard IANA timezone database), which defaults to your account's timezone. See Timezone localization for information on what this timezone parameter influences within Orb.

​
metadata
object
required

User specified key-value pairs for the resource. If not present, this defaults to an empty dictionary. Individual keys can be removed by setting the value to null, and the entire metadata mapping can be cleared by setting metadata to null.

​
id
string
required
​
external_customer_id
string | null
required

An optional user-defined ID for this customer resource, used throughout the system as an alias for this Customer. Use this field to identify a customer by an existing identifier in your system.

​
name
string
required

The full name of the customer

​
email
string
required

A valid customer email, to be used for notifications. When Orb triggers payment through a payment gateway, this email will be used for any automatically issued receipts.

​
timezone
string
required

A timezone identifier from the IANA timezone database, such as "America/Los_Angeles". This "defaults to your account's timezone if not set. This cannot be changed after customer creation.

​
payment_provider_id
string | null
required

The ID of this customer in an external payments solution, such as Stripe. This is used for creating charges or invoices in the external system via Orb.

​
payment_provider
enum<string> | null
required

This is used for creating charges or invoices in an external system via Orb. When not in test mode, the connection must first be configured in the Orb webapp.

Available options:
quickbooks,
bill.com,
stripe_charge,
stripe_invoice,
netsuite
​
created_at
string
required
​
shipping_address
object | null
required
​
billing_address
object | null
required
​
balance
string
required

The customer's current balance in their currency.

​
currency
string | null
required
​
tax_id
object | null
required

Tax IDs are commonly required to be displayed on customer invoices, which are added to the headers of invoices.

Supported Tax ID Countries and Types

CountryTypeDescription
Andorraad_nrtAndorran NRT Number
Argentinaar_cuitArgentinian Tax ID Number
Australiaau_abnAustralian Business Number (AU ABN)
Australiaau_arnAustralian Taxation Office Reference Number
Austriaeu_vatEuropean VAT Number
Bahrainbh_vatBahraini VAT Number
Belgiumeu_vatEuropean VAT Number
Boliviabo_tinBolivian Tax ID
Brazilbr_cnpjBrazilian CNPJ Number
Brazilbr_cpfBrazilian CPF Number
Bulgariabg_uicBulgaria Unified Identification Code
Bulgariaeu_vatEuropean VAT Number
Canadaca_bnCanadian BN
Canadaca_gst_hstCanadian GST/HST Number
Canadaca_pst_bcCanadian PST Number (British Columbia)
Canadaca_pst_mbCanadian PST Number (Manitoba)
Canadaca_pst_skCanadian PST Number (Saskatchewan)
Canadaca_qstCanadian QST Number (Québec)
Chilecl_tinChilean TIN
Chinacn_tinChinese Tax ID
Colombiaco_nitColombian NIT Number
Costa Ricacr_tinCosta Rican Tax ID
Croatiaeu_vatEuropean VAT Number
Cypruseu_vatEuropean VAT Number
Czech Republiceu_vatEuropean VAT Number
Denmarkeu_vatEuropean VAT Number
Dominican Republicdo_rcnDominican RCN Number
Ecuadorec_rucEcuadorian RUC Number
Egypteg_tinEgyptian Tax Identification Number
El Salvadorsv_nitEl Salvadorian NIT Number
Estoniaeu_vatEuropean VAT Number
EUeu_oss_vatEuropean One Stop Shop VAT Number for non-Union scheme
Finlandeu_vatEuropean VAT Number
Franceeu_vatEuropean VAT Number
Georgiage_vatGeorgian VAT
Germanyeu_vatEuropean VAT Number
Greeceeu_vatEuropean VAT Number
Hong Konghk_brHong Kong BR Number
Hungaryeu_vatEuropean VAT Number
Hungaryhu_tinHungary Tax Number (adószám)
Icelandis_vatIcelandic VAT
Indiain_gstIndian GST Number
Indonesiaid_npwpIndonesian NPWP Number
Irelandeu_vatEuropean VAT Number
Israelil_vatIsrael VAT
Italyeu_vatEuropean VAT Number
Japanjp_cnJapanese Corporate Number (Hōjin Bangō)
Japanjp_rnJapanese Registered Foreign Businesses' Registration Number (Tōroku Kokugai Jigyōsha no Tōroku Bangō)
Japanjp_trnJapanese Tax Registration Number (Tōroku Bangō)
Kazakhstankz_binKazakhstani Business Identification Number
Kenyake_pinKenya Revenue Authority Personal Identification Number
Latviaeu_vatEuropean VAT Number
Liechtensteinli_uidLiechtensteinian UID Number
Lithuaniaeu_vatEuropean VAT Number
Luxembourgeu_vatEuropean VAT Number
Malaysiamy_frpMalaysian FRP Number
Malaysiamy_itnMalaysian ITN
Malaysiamy_sstMalaysian SST Number
Maltaeu_vat European VAT Number
Mexicomx_rfcMexican RFC Number
Netherlandseu_vatEuropean VAT Number
New Zealandnz_gstNew Zealand GST Number
Nigeriang_tinNigerian Tax Identification Number
Norwayno_vatNorwegian VAT Number
Norwayno_voecNorwegian VAT on e-commerce Number
Omanom_vatOmani VAT Number
Perupe_rucPeruvian RUC Number
Philippinesph_tin Philippines Tax Identification Number
Polandeu_vatEuropean VAT Number
Portugaleu_vatEuropean VAT Number
Romaniaeu_vatEuropean VAT Number
Romaniaro_tinRomanian Tax ID Number
Russiaru_innRussian INN
Russiaru_kppRussian KPP
Saudi Arabiasa_vatSaudi Arabia VAT
Serbiars_pibSerbian PIB Number
Singaporesg_gstSingaporean GST
Singaporesg_uenSingaporean UEN
Slovakiaeu_vatEuropean VAT Number
Sloveniaeu_vatEuropean VAT Number
Sloveniasi_tinSlovenia Tax Number (davčna številka)
South Africaza_vatSouth African VAT Number
South Koreakr_brnKorean BRN
Spaines_cifSpanish NIF Number (previously Spanish CIF Number)
Spaineu_vatEuropean VAT Number
Swedeneu_vatEuropean VAT Number
Switzerlandch_vatSwitzerland VAT Number
Taiwantw_vatTaiwanese VAT
Thailandth_vatThai VAT
Turkeytr_tinTurkish Tax Identification Number
Ukraineua_vatUkrainian VAT
United Arab Emiratesae_trnUnited Arab Emirates TRN
United Kingdomeu_vatNorthern Ireland VAT Number
United Kingdomgb_vatUnited Kingdom VAT Number
United Statesus_einUnited States EIN
Uruguayuy_rucUruguayan RUC Number
Venezuelave_rifVenezuelan RIF Number
Vietnamvn_tinVietnamese Tax ID Number
​
auto_collection
boolean
required
​
exempt_from_automated_tax
boolean | null
required
​
email_delivery
boolean
required
​
additional_emails
string[]
required
​
portal_url
string | null
required
​
hierarchy
object
required

The hierarchical relationships for this customer.

​
accounting_sync_configuration
object | null
​
reporting_configuration
object | null

Was this page helpful?