POST
/
customers
Create customer
curl --request POST \
  --url https://api.withorb.com/v1/customers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "metadata": {},
  "name": "<string>",
  "email": "jsmith@example.com",
  "timezone": "<string>",
  "external_customer_id": "<string>",
  "payment_provider_id": "<string>",
  "payment_provider": "quickbooks",
  "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>"
  },
  "currency": "<string>",
  "tax_id": {
    "country": "AD",
    "type": "ad_nrt",
    "value": "<string>"
  },
  "auto_collection": true,
  "auto_issuance": true,
  "email_delivery": true,
  "tax_configuration": {
    "tax_exempt": true,
    "tax_provider": "avalara",
    "tax_exemption_code": "<string>"
  },
  "reporting_configuration": {
    "exempt": true
  },
  "accounting_sync_configuration": {
    "excluded": true,
    "accounting_providers": [
      {
        "provider_type": "<string>",
        "external_provider_id": "<string>"
      }
    ]
  },
  "additional_emails": [
    "jsmith@example.com"
  ],
  "hierarchy": {
    "parent_customer_id": "<string>",
    "child_customer_ids": [
      "<string>"
    ]
  }
}'
{
  "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,
  "auto_issuance": 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.

Body

application/json
​
name
string
required

The full name of the customer

Required string length: 1 - 500
​
email
string<email>
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.

Maximum length: 500
​
metadata
object | null

User-specified key/value pairs for the resource. Individual keys can be removed by setting the value to null, and the entire metadata mapping can be cleared by setting metadata to null.

​
timezone
string | null

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.

​
external_customer_id
string | null

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.

​
payment_provider_id
string | null

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

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
​
shipping_address
object | null
​
billing_address
object | null
​
currency
string | null

An ISO 4217 currency string used for the customer's invoices and balance. If not set at creation time, will be set at subscription creation time.

​
tax_id
object | null

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
Albaniaal_tinAlbania Tax Identification Number
Andorraad_nrtAndorran NRT Number
Angolaao_tinAngola Tax Identification Number
Argentinaar_cuitArgentinian Tax ID Number
Armeniaam_tinArmenia Tax Identification Number
Arubaaw_tinAruba Tax Identification Number
Australiaau_abnAustralian Business Number (AU ABN)
Australiaau_arnAustralian Taxation Office Reference Number
Austriaeu_vatEuropean VAT Number
Azerbaijanaz_tinAzerbaijan Tax Identification Number
Bahamasbs_tinBahamas Tax Identification Number
Bahrainbh_vatBahraini VAT Number
Bangladeshbd_binBangladesh Business Identification Number
Barbadosbb_tinBarbados Tax Identification Number
Belarusby_tinBelarus TIN Number
Belgiumeu_vatEuropean VAT Number
Beninbj_ifuBenin Tax Identification Number (Identifiant Fiscal Unique)
Boliviabo_tinBolivian Tax ID
Bosnia and Herzegovinaba_tinBosnia and Herzegovina Tax Identification Number
Brazilbr_cnpjBrazilian CNPJ Number
Brazilbr_cpfBrazilian CPF Number
Bulgariabg_uicBulgaria Unified Identification Code
Bulgariaeu_vatEuropean VAT Number
Burkina Fasobf_ifuBurkina Faso Tax Identification Number (Numéro d'Identifiant Fiscal Unique)
Cambodiakh_tinCambodia Tax Identification Number
Camerooncm_niuCameroon Tax Identification Number (Numéro d'Identifiant fiscal Unique)
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)
Cape Verdecv_nifCape Verde Tax Identification Number (Número de Identificação Fiscal)
Chilecl_tinChilean TIN
Chinacn_tinChinese Tax ID
Colombiaco_nitColombian NIT Number
Congo-Kinshasacd_nifCongo (DR) Tax Identification Number (Número de Identificação Fiscal)
Costa Ricacr_tinCosta Rican Tax ID
Croatiaeu_vatEuropean VAT Number
Croatiahr_oibCroatian Personal Identification Number (OIB)
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
Ethiopiaet_tinEthiopia Tax Identification Number
European Unioneu_oss_vatEuropean One Stop Shop VAT Number for non-Union scheme
Finlandeu_vatEuropean VAT Number
Franceeu_vatEuropean VAT Number
Georgiage_vatGeorgian VAT
Germanyde_stnGerman Tax Number (Steuernummer)
Germanyeu_vatEuropean VAT Number
Greeceeu_vatEuropean VAT Number
Guineagn_nifGuinea Tax Identification Number (Número de Identificação Fiscal)
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
Kyrgyzstankg_tinKyrgyzstan Tax Identification Number
Laosla_tinLaos Tax Identification Number
Latviaeu_vatEuropean VAT Number
Liechtensteinli_uidLiechtensteinian UID Number
Liechtensteinli_vatLiechtenstein VAT Number
Lithuaniaeu_vatEuropean VAT Number
Luxembourgeu_vatEuropean VAT Number
Malaysiamy_frpMalaysian FRP Number
Malaysiamy_itnMalaysian ITN
Malaysiamy_sstMalaysian SST Number
Maltaeu_vatEuropean VAT Number
Mauritaniamr_nifMauritania Tax Identification Number (Número de Identificação Fiscal)
Mexicomx_rfcMexican RFC Number
Moldovamd_vatMoldova VAT Number
Montenegrome_pibMontenegro PIB Number
Moroccoma_vatMorocco VAT Number
Nepalnp_panNepal PAN Number
Netherlandseu_vatEuropean VAT Number
New Zealandnz_gstNew Zealand GST Number
Nigeriang_tinNigerian Tax Identification Number
North Macedoniamk_vatNorth Macedonia VAT Number
Northern Irelandeu_vatNorthern Ireland VAT Number
Norwayno_vatNorwegian VAT Number
Norwayno_voecNorwegian VAT on e-commerce Number
Omanom_vatOmani VAT Number
Perupe_rucPeruvian RUC Number
Philippinesph_tinPhilippines 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
Senegalsn_nineaSenegal NINEA Number
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
Surinamesr_finSuriname FIN Number
Swedeneu_vatEuropean VAT Number
Switzerlandch_uidSwitzerland UID Number
Switzerlandch_vatSwitzerland VAT Number
Taiwantw_vatTaiwanese VAT
Tajikistantj_tinTajikistan Tax Identification Number
Tanzaniatz_vatTanzania VAT Number
Thailandth_vatThai VAT
Turkeytr_tinTurkish Tax Identification Number
Ugandaug_tinUganda Tax Identification Number
Ukraineua_vatUkrainian VAT
United Arab Emiratesae_trnUnited Arab Emirates TRN
United Kingdomgb_vatUnited Kingdom VAT Number
United Statesus_einUnited States EIN
Uruguayuy_rucUruguayan RUC Number
Uzbekistanuz_tinUzbekistan TIN Number
Uzbekistanuz_vatUzbekistan VAT Number
Venezuelave_rifVenezuelan RIF Number
Vietnamvn_tinVietnamese Tax ID Number
Zambiazm_tinZambia Tax Identification Number
Zimbabwezw_tinZimbabwe Tax Identification Number
​
auto_collection
boolean | null

Used to determine if invoices for this customer will automatically attempt to charge a saved payment method, if available. This parameter defaults to True when a payment provider is provided on customer creation.

​
auto_issuance
boolean | null

Used to determine if invoices for this customer will be automatically issued. If true, invoices will be automatically issued. If false, invoices will require manual approval. If null is specified, the customer's auto issuance setting will be inherited from the account-level setting.

​
email_delivery
boolean | null
​
tax_configuration
object | null
​
reporting_configuration
object | null
​
accounting_sync_configuration
object | null
​
additional_emails
string<email>[] | null

Additional email addresses for this customer. If populated, these email addresses will be CC'd for customer communications. The total number of email addresses (including the primary email) cannot exceed 50.

​
hierarchy
object | null

The hierarchical relationships for this customer.

Response

Created

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<date-time>
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
Albaniaal_tinAlbania Tax Identification Number
Andorraad_nrtAndorran NRT Number
Angolaao_tinAngola Tax Identification Number
Argentinaar_cuitArgentinian Tax ID Number
Armeniaam_tinArmenia Tax Identification Number
Arubaaw_tinAruba Tax Identification Number
Australiaau_abnAustralian Business Number (AU ABN)
Australiaau_arnAustralian Taxation Office Reference Number
Austriaeu_vatEuropean VAT Number
Azerbaijanaz_tinAzerbaijan Tax Identification Number
Bahamasbs_tinBahamas Tax Identification Number
Bahrainbh_vatBahraini VAT Number
Bangladeshbd_binBangladesh Business Identification Number
Barbadosbb_tinBarbados Tax Identification Number
Belarusby_tinBelarus TIN Number
Belgiumeu_vatEuropean VAT Number
Beninbj_ifuBenin Tax Identification Number (Identifiant Fiscal Unique)
Boliviabo_tinBolivian Tax ID
Bosnia and Herzegovinaba_tinBosnia and Herzegovina Tax Identification Number
Brazilbr_cnpjBrazilian CNPJ Number
Brazilbr_cpfBrazilian CPF Number
Bulgariabg_uicBulgaria Unified Identification Code
Bulgariaeu_vatEuropean VAT Number
Burkina Fasobf_ifuBurkina Faso Tax Identification Number (Numéro d'Identifiant Fiscal Unique)
Cambodiakh_tinCambodia Tax Identification Number
Camerooncm_niuCameroon Tax Identification Number (Numéro d'Identifiant fiscal Unique)
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)
Cape Verdecv_nifCape Verde Tax Identification Number (Número de Identificação Fiscal)
Chilecl_tinChilean TIN
Chinacn_tinChinese Tax ID
Colombiaco_nitColombian NIT Number
Congo-Kinshasacd_nifCongo (DR) Tax Identification Number (Número de Identificação Fiscal)
Costa Ricacr_tinCosta Rican Tax ID
Croatiaeu_vatEuropean VAT Number
Croatiahr_oibCroatian Personal Identification Number (OIB)
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
Ethiopiaet_tinEthiopia Tax Identification Number
European Unioneu_oss_vatEuropean One Stop Shop VAT Number for non-Union scheme
Finlandeu_vatEuropean VAT Number
Franceeu_vatEuropean VAT Number
Georgiage_vatGeorgian VAT
Germanyde_stnGerman Tax Number (Steuernummer)
Germanyeu_vatEuropean VAT Number
Greeceeu_vatEuropean VAT Number
Guineagn_nifGuinea Tax Identification Number (Número de Identificação Fiscal)
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
Kyrgyzstankg_tinKyrgyzstan Tax Identification Number
Laosla_tinLaos Tax Identification Number
Latviaeu_vatEuropean VAT Number
Liechtensteinli_uidLiechtensteinian UID Number
Liechtensteinli_vatLiechtenstein VAT Number
Lithuaniaeu_vatEuropean VAT Number
Luxembourgeu_vatEuropean VAT Number
Malaysiamy_frpMalaysian FRP Number
Malaysiamy_itnMalaysian ITN
Malaysiamy_sstMalaysian SST Number
Maltaeu_vatEuropean VAT Number
Mauritaniamr_nifMauritania Tax Identification Number (Número de Identificação Fiscal)
Mexicomx_rfcMexican RFC Number
Moldovamd_vatMoldova VAT Number
Montenegrome_pibMontenegro PIB Number
Moroccoma_vatMorocco VAT Number
Nepalnp_panNepal PAN Number
Netherlandseu_vatEuropean VAT Number
New Zealandnz_gstNew Zealand GST Number
Nigeriang_tinNigerian Tax Identification Number
North Macedoniamk_vatNorth Macedonia VAT Number
Northern Irelandeu_vatNorthern Ireland VAT Number
Norwayno_vatNorwegian VAT Number
Norwayno_voecNorwegian VAT on e-commerce Number
Omanom_vatOmani VAT Number
Perupe_rucPeruvian RUC Number
Philippinesph_tinPhilippines 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
Senegalsn_nineaSenegal NINEA Number
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
Surinamesr_finSuriname FIN Number
Swedeneu_vatEuropean VAT Number
Switzerlandch_uidSwitzerland UID Number
Switzerlandch_vatSwitzerland VAT Number
Taiwantw_vatTaiwanese VAT
Tajikistantj_tinTajikistan Tax Identification Number
Tanzaniatz_vatTanzania VAT Number
Thailandth_vatThai VAT
Turkeytr_tinTurkish Tax Identification Number
Ugandaug_tinUganda Tax Identification Number
Ukraineua_vatUkrainian VAT
United Arab Emiratesae_trnUnited Arab Emirates TRN
United Kingdomgb_vatUnited Kingdom VAT Number
United Statesus_einUnited States EIN
Uruguayuy_rucUruguayan RUC Number
Uzbekistanuz_tinUzbekistan TIN Number
Uzbekistanuz_vatUzbekistan VAT Number
Venezuelave_rifVenezuelan RIF Number
Vietnamvn_tinVietnamese Tax ID Number
Zambiazm_tinZambia Tax Identification Number
Zimbabwezw_tinZimbabwe Tax Identification Number
​
auto_collection
boolean
required
​
exempt_from_automated_tax
boolean | null
required
​
email_delivery
boolean
required
​
auto_issuance
boolean | null
required

Whether invoices for this customer should be automatically issued. If true, invoices will be automatically issued. If false, invoices will require manual approval. If null, inherits the account-level setting.

​
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