Create customer
This operation is used to create an Orb customer, who is party to the core billing relationship. See Customer for an overview of the customer resource.
This endpoint is critical in the following Orb functionality:
- Automated charges can be configured by setting
payment_provider
andpayment_provider_id
to automatically issue invoices - Customer ID Aliases can be configured by setting
external_customer_id
- Timezone localization can be configured on a per-customer basis by
setting the
timezone
parameter
Request Body required
- Array [
- ]
metadata object nullable
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
.
Possible values: non-empty
and <= 500 characters
The full name of the customer
Possible values: <= 500 characters
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.
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.
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.
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.
Possible values: [quickbooks
, bill.com
, stripe_charge
, stripe_invoice
, netsuite
]
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.
shipping_address object nullable
billing_address object nullable
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 nullable
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
Country | Type | Description |
---|---|---|
Andorra | ad_nrt | Andorran NRT Number |
Argentina | ar_cuit | Argentinian Tax ID Number |
Australia | au_abn | Australian Business Number (AU ABN) |
Australia | au_arn | Australian Taxation Office Reference Number |
Austria | eu_vat | European VAT Number |
Bahrain | bh_vat | Bahraini VAT Number |
Belgium | eu_vat | European VAT Number |
Bolivia | bo_tin | Bolivian Tax ID |
Brazil | br_cnpj | Brazilian CNPJ Number |
Brazil | br_cpf | Brazilian CPF Number |
Bulgaria | bg_uic | Bulgaria Unified Identification Code |
Bulgaria | eu_vat | European VAT Number |
Canada | ca_bn | Canadian BN |
Canada | ca_gst_hst | Canadian GST/HST Number |
Canada | ca_pst_bc | Canadian PST Number (British Columbia) |
Canada | ca_pst_mb | Canadian PST Number (Manitoba) |
Canada | ca_pst_sk | Canadian PST Number (Saskatchewan) |
Canada | ca_qst | Canadian QST Number (Québec) |
Chile | cl_tin | Chilean TIN |
China | cn_tin | Chinese Tax ID |
Colombia | co_nit | Colombian NIT Number |
Costa Rica | cr_tin | Costa Rican Tax ID |
Croatia | eu_vat | European VAT Number |
Cyprus | eu_vat | European VAT Number |
Czech Republic | eu_vat | European VAT Number |
Denmark | eu_vat | European VAT Number |
Dominican Republic | do_rcn | Dominican RCN Number |
Ecuador | ec_ruc | Ecuadorian RUC Number |
Egypt | eg_tin | Egyptian Tax Identification Number |
El Salvador | sv_nit | El Salvadorian NIT Number |
Estonia | eu_vat | European VAT Number |
EU | eu_oss_vat | European One Stop Shop VAT Number for non-Union scheme |
Finland | eu_vat | European VAT Number |
France | eu_vat | European VAT Number |
Georgia | ge_vat | Georgian VAT |
Germany | eu_vat | European VAT Number |
Greece | eu_vat | European VAT Number |
Hong Kong | hk_br | Hong Kong BR Number |
Hungary | eu_vat | European VAT Number |
Hungary | hu_tin | Hungary Tax Number (adószám) |
Iceland | is_vat | Icelandic VAT |
India | in_gst | Indian GST Number |
Indonesia | id_npwp | Indonesian NPWP Number |
Ireland | eu_vat | European VAT Number |
Israel | il_vat | Israel VAT |
Italy | eu_vat | European VAT Number |
Japan | jp_cn | Japanese Corporate Number (Hōjin Bangō) |
Japan | jp_rn | Japanese Registered Foreign Businesses' Registration Number (Tōroku Kokugai Jigyōsha no Tōroku Bangō) |
Japan | jp_trn | Japanese Tax Registration Number (Tōroku Bangō) |
Kazakhstan | kz_bin | Kazakhstani Business Identification Number |
Kenya | ke_pin | Kenya Revenue Authority Personal Identification Number |
Latvia | eu_vat | European VAT Number |
Liechtenstein | li_uid | Liechtensteinian UID Number |
Lithuania | eu_vat | European VAT Number |
Luxembourg | eu_vat | European VAT Number |
Malaysia | my_frp | Malaysian FRP Number |
Malaysia | my_itn | Malaysian ITN |
Malaysia | my_sst | Malaysian SST Number |
Malta | eu_vat | European VAT Number |
Mexico | mx_rfc | Mexican RFC Number |
Netherlands | eu_vat | European VAT Number |
New Zealand | nz_gst | New Zealand GST Number |
Nigeria | ng_tin | Nigerian Tax Identification Number |
Norway | no_vat | Norwegian VAT Number |
Norway | no_voec | Norwegian VAT on e-commerce Number |
Oman | om_vat | Omani VAT Number |
Peru | pe_ruc | Peruvian RUC Number |
Philippines | ph_tin | Philippines Tax Identification Number |
Poland | eu_vat | European VAT Number |
Portugal | eu_vat | European VAT Number |
Romania | eu_vat | European VAT Number |
Romania | ro_tin | Romanian Tax ID Number |
Russia | ru_inn | Russian INN |
Russia | ru_kpp | Russian KPP |
Saudi Arabia | sa_vat | Saudi Arabia VAT |
Serbia | rs_pib | Serbian PIB Number |
Singapore | sg_gst | Singaporean GST |
Singapore | sg_uen | Singaporean UEN |
Slovakia | eu_vat | European VAT Number |
Slovenia | eu_vat | European VAT Number |
Slovenia | si_tin | Slovenia Tax Number (davčna številka) |
South Africa | za_vat | South African VAT Number |
South Korea | kr_brn | Korean BRN |
Spain | es_cif | Spanish NIF Number (previously Spanish CIF Number) |
Spain | eu_vat | European VAT Number |
Sweden | eu_vat | European VAT Number |
Switzerland | ch_vat | Switzerland VAT Number |
Taiwan | tw_vat | Taiwanese VAT |
Thailand | th_vat | Thai VAT |
Turkey | tr_tin | Turkish Tax Identification Number |
Ukraine | ua_vat | Ukrainian VAT |
United Arab Emirates | ae_trn | United Arab Emirates TRN |
United Kingdom | eu_vat | Northern Ireland VAT Number |
United Kingdom | gb_vat | United Kingdom VAT Number |
United States | us_ein | United States EIN |
Uruguay | uy_ruc | Uruguayan RUC Number |
Venezuela | ve_rif | Venezuelan RIF Number |
Vietnam | vn_tin | Vietnamese Tax ID Number |
Possible values: [AD
, AE
, AR
, AT
, AU
, BE
, BG
, BH
, BO
, BR
, CA
, CH
, CL
, CN
, CO
, CR
, CY
, CZ
, DE
, DK
, EE
, DO
, EC
, EG
, ES
, EU
, FI
, FR
, GB
, GE
, GR
, HK
, HR
, HU
, ID
, IE
, IL
, IN
, IS
, IT
, JP
, KE
, KR
, KZ
, LI
, LT
, LU
, LV
, MT
, MX
, MY
, NG
, NL
, NO
, NZ
, OM
, PE
, PH
, PL
, PT
, RO
, RS
, RU
, SA
, SE
, SG
, SI
, SK
, SV
, TH
, TR
, TW
, UA
, US
, UY
, VE
, VN
, ZA
]
Possible values: [ad_nrt
, ae_trn
, ar_cuit
, eu_vat
, au_abn
, au_arn
, bg_uic
, bh_vat
, bo_tin
, br_cnpj
, br_cpf
, ca_bn
, ca_gst_hst
, ca_pst_bc
, ca_pst_mb
, ca_pst_sk
, ca_qst
, ch_vat
, cl_tin
, cn_tin
, co_nit
, cr_tin
, do_rcn
, ec_ruc
, eg_tin
, es_cif
, eu_oss_vat
, gb_vat
, ge_vat
, hk_br
, hu_tin
, id_npwp
, il_vat
, in_gst
, is_vat
, jp_cn
, jp_rn
, jp_trn
, ke_pin
, kr_brn
, kz_bin
, li_uid
, mx_rfc
, my_frp
, my_itn
, my_sst
, ng_tin
, no_vat
, no_voec
, nz_gst
, om_vat
, pe_ruc
, ph_tin
, ro_tin
, rs_pib
, ru_inn
, ru_kpp
, sa_vat
, sg_gst
, sg_uen
, si_tin
, sv_nit
, th_vat
, tr_tin
, tw_vat
, ua_vat
, us_ein
, uy_ruc
, ve_rif
, vn_tin
, za_vat
]
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.
tax_configuration object nullable
Possible values: [avalara
]
Possible values: [taxjar
]
reporting_configuration object nullable
accounting_sync_configuration object nullable
accounting_providers object[] nullable
Additional email addresses for this customer. If populated, these email addresses will be CC'd for customer communications.
- 201
- 400
- 401
- 404
- 409
- 413
- 429
- 500
Created
Response Headers
Schema
- Array [
- ]
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
.
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.
The full name of the customer
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.
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.
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.
Possible values: [quickbooks
, bill.com
, stripe_charge
, stripe_invoice
, netsuite
]
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.
shipping_address object nullable
billing_address object nullable
The customer's current balance in their currency.
tax_id object nullable
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
Country | Type | Description |
---|---|---|
Andorra | ad_nrt | Andorran NRT Number |
Argentina | ar_cuit | Argentinian Tax ID Number |
Australia | au_abn | Australian Business Number (AU ABN) |
Australia | au_arn | Australian Taxation Office Reference Number |
Austria | eu_vat | European VAT Number |
Bahrain | bh_vat | Bahraini VAT Number |
Belgium | eu_vat | European VAT Number |
Bolivia | bo_tin | Bolivian Tax ID |
Brazil | br_cnpj | Brazilian CNPJ Number |
Brazil | br_cpf | Brazilian CPF Number |
Bulgaria | bg_uic | Bulgaria Unified Identification Code |
Bulgaria | eu_vat | European VAT Number |
Canada | ca_bn | Canadian BN |
Canada | ca_gst_hst | Canadian GST/HST Number |
Canada | ca_pst_bc | Canadian PST Number (British Columbia) |
Canada | ca_pst_mb | Canadian PST Number (Manitoba) |
Canada | ca_pst_sk | Canadian PST Number (Saskatchewan) |
Canada | ca_qst | Canadian QST Number (Québec) |
Chile | cl_tin | Chilean TIN |
China | cn_tin | Chinese Tax ID |
Colombia | co_nit | Colombian NIT Number |
Costa Rica | cr_tin | Costa Rican Tax ID |
Croatia | eu_vat | European VAT Number |
Cyprus | eu_vat | European VAT Number |
Czech Republic | eu_vat | European VAT Number |
Denmark | eu_vat | European VAT Number |
Dominican Republic | do_rcn | Dominican RCN Number |
Ecuador | ec_ruc | Ecuadorian RUC Number |
Egypt | eg_tin | Egyptian Tax Identification Number |
El Salvador | sv_nit | El Salvadorian NIT Number |
Estonia | eu_vat | European VAT Number |
EU | eu_oss_vat | European One Stop Shop VAT Number for non-Union scheme |
Finland | eu_vat | European VAT Number |
France | eu_vat | European VAT Number |
Georgia | ge_vat | Georgian VAT |
Germany | eu_vat | European VAT Number |
Greece | eu_vat | European VAT Number |
Hong Kong | hk_br | Hong Kong BR Number |
Hungary | eu_vat | European VAT Number |
Hungary | hu_tin | Hungary Tax Number (adószám) |
Iceland | is_vat | Icelandic VAT |
India | in_gst | Indian GST Number |
Indonesia | id_npwp | Indonesian NPWP Number |
Ireland | eu_vat | European VAT Number |
Israel | il_vat | Israel VAT |
Italy | eu_vat | European VAT Number |
Japan | jp_cn | Japanese Corporate Number (Hōjin Bangō) |
Japan | jp_rn | Japanese Registered Foreign Businesses' Registration Number (Tōroku Kokugai Jigyōsha no Tōroku Bangō) |
Japan | jp_trn | Japanese Tax Registration Number (Tōroku Bangō) |
Kazakhstan | kz_bin | Kazakhstani Business Identification Number |
Kenya | ke_pin | Kenya Revenue Authority Personal Identification Number |
Latvia | eu_vat | European VAT Number |
Liechtenstein | li_uid | Liechtensteinian UID Number |
Lithuania | eu_vat | European VAT Number |
Luxembourg | eu_vat | European VAT Number |
Malaysia | my_frp | Malaysian FRP Number |
Malaysia | my_itn | Malaysian ITN |
Malaysia | my_sst | Malaysian SST Number |
Malta | eu_vat | European VAT Number |
Mexico | mx_rfc | Mexican RFC Number |
Netherlands | eu_vat | European VAT Number |
New Zealand | nz_gst | New Zealand GST Number |
Nigeria | ng_tin | Nigerian Tax Identification Number |
Norway | no_vat | Norwegian VAT Number |
Norway | no_voec | Norwegian VAT on e-commerce Number |
Oman | om_vat | Omani VAT Number |
Peru | pe_ruc | Peruvian RUC Number |
Philippines | ph_tin | Philippines Tax Identification Number |
Poland | eu_vat | European VAT Number |
Portugal | eu_vat | European VAT Number |
Romania | eu_vat | European VAT Number |
Romania | ro_tin | Romanian Tax ID Number |
Russia | ru_inn | Russian INN |
Russia | ru_kpp | Russian KPP |
Saudi Arabia | sa_vat | Saudi Arabia VAT |
Serbia | rs_pib | Serbian PIB Number |
Singapore | sg_gst | Singaporean GST |
Singapore | sg_uen | Singaporean UEN |
Slovakia | eu_vat | European VAT Number |
Slovenia | eu_vat | European VAT Number |
Slovenia | si_tin | Slovenia Tax Number (davčna številka) |
South Africa | za_vat | South African VAT Number |
South Korea | kr_brn | Korean BRN |
Spain | es_cif | Spanish NIF Number (previously Spanish CIF Number) |
Spain | eu_vat | European VAT Number |
Sweden | eu_vat | European VAT Number |
Switzerland | ch_vat | Switzerland VAT Number |
Taiwan | tw_vat | Taiwanese VAT |
Thailand | th_vat | Thai VAT |
Turkey | tr_tin | Turkish Tax Identification Number |
Ukraine | ua_vat | Ukrainian VAT |
United Arab Emirates | ae_trn | United Arab Emirates TRN |
United Kingdom | eu_vat | Northern Ireland VAT Number |
United Kingdom | gb_vat | United Kingdom VAT Number |
United States | us_ein | United States EIN |
Uruguay | uy_ruc | Uruguayan RUC Number |
Venezuela | ve_rif | Venezuelan RIF Number |
Vietnam | vn_tin | Vietnamese Tax ID Number |
Possible values: [AD
, AE
, AR
, AT
, AU
, BE
, BG
, BH
, BO
, BR
, CA
, CH
, CL
, CN
, CO
, CR
, CY
, CZ
, DE
, DK
, EE
, DO
, EC
, EG
, ES
, EU
, FI
, FR
, GB
, GE
, GR
, HK
, HR
, HU
, ID
, IE
, IL
, IN
, IS
, IT
, JP
, KE
, KR
, KZ
, LI
, LT
, LU
, LV
, MT
, MX
, MY
, NG
, NL
, NO
, NZ
, OM
, PE
, PH
, PL
, PT
, RO
, RS
, RU
, SA
, SE
, SG
, SI
, SK
, SV
, TH
, TR
, TW
, UA
, US
, UY
, VE
, VN
, ZA
]
Possible values: [ad_nrt
, ae_trn
, ar_cuit
, eu_vat
, au_abn
, au_arn
, bg_uic
, bh_vat
, bo_tin
, br_cnpj
, br_cpf
, ca_bn
, ca_gst_hst
, ca_pst_bc
, ca_pst_mb
, ca_pst_sk
, ca_qst
, ch_vat
, cl_tin
, cn_tin
, co_nit
, cr_tin
, do_rcn
, ec_ruc
, eg_tin
, es_cif
, eu_oss_vat
, gb_vat
, ge_vat
, hk_br
, hu_tin
, id_npwp
, il_vat
, in_gst
, is_vat
, jp_cn
, jp_rn
, jp_trn
, ke_pin
, kr_brn
, kz_bin
, li_uid
, mx_rfc
, my_frp
, my_itn
, my_sst
, ng_tin
, no_vat
, no_voec
, nz_gst
, om_vat
, pe_ruc
, ph_tin
, ro_tin
, rs_pib
, ru_inn
, ru_kpp
, sa_vat
, sg_gst
, sg_uen
, si_tin
, sv_nit
, th_vat
, tr_tin
, tw_vat
, ua_vat
, us_ein
, uy_ruc
, ve_rif
, vn_tin
, za_vat
]
accounting_sync_configuration object nullable
accounting_providers object[] required
Possible values: [quickbooks
, netsuite
]
reporting_configuration object nullable
{
"metadata": {},
"id": "string",
"external_customer_id": "string",
"name": "string",
"email": "string",
"timezone": "string",
"payment_provider_id": "string",
"payment_provider": "quickbooks",
"created_at": "2024-12-03T01:24:30.087Z",
"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
}
}
Bad Request
Response Headers
Schema
Possible values: [https://docs.withorb.com/reference/error-responses#400-constraint-violation
]
Possible values: [400
]
Possible values: [https://docs.withorb.com/reference/error-responses#400-duplicate-resource-creation
]
Possible values: [400
]
Possible values: [https://docs.withorb.com/reference/error-responses#400-request-validation-errors
]
Possible values: [400
]
{}
Unauthorized
Response Headers
Schema
Possible values: [https://docs.withorb.com/reference/error-responses#401-authentication-error
]
Possible values: [401
]
{
"type": "https://docs.withorb.com/reference/error-responses#401-authentication-error",
"status": 401,
"detail": "string",
"title": "string"
}
Not Found
Response Headers
Schema
Possible values: [https://docs.withorb.com/reference/error-responses#404-feature-not-available
]
Possible values: [400
]
Possible values: [https://docs.withorb.com/reference/error-responses#404-resource-not-found
]
Possible values: [404
]
Possible values: [https://docs.withorb.com/reference/error-responses#404-url-not-found
]
Possible values: [404
]
{}
Conflict
Response Headers
Schema
Possible values: [https://docs.withorb.com/reference/error-responses#409-resource-conflict
]
Possible values: [409
]
{
"type": "https://docs.withorb.com/reference/error-responses#409-resource-conflict",
"status": 409,
"detail": "string",
"title": "string"
}
Request Entity Too Large
Response Headers
Schema
Possible values: [https://docs.withorb.com/reference/error-responses#413-request-too-large
]
Possible values: [413
]
Possible values: [https://docs.withorb.com/reference/error-responses#413-resource-too-large
]
Possible values: [413
]
Possible values: [https://docs.withorb.com/reference/error-responses#413-too-many-results
]
Possible values: [413
]
{}
Too Many Requests
Response Headers
Schema
Possible values: [https://docs.withorb.com/reference/error-responses#429-too-many-requests
]
Possible values: [429
]
{
"type": "https://docs.withorb.com/reference/error-responses#429-too-many-requests",
"status": 429,
"detail": "string",
"title": "string"
}
Internal Server Error
Response Headers
Schema
Possible values: [https://docs.withorb.com/reference/error-responses#500-internal-server-error
]
{
"type": "https://docs.withorb.com/reference/error-responses#500-internal-server-error",
"status": 0,
"detail": "string",
"title": "string"
}