Skip to main content

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 and payment_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
    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.

    property name* string nullable
    name string required

    Possible values: non-empty and <= 500 characters

    The full name of the customer

    email email required

    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.

    timezone string nullable

    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 nullable

    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 nullable

    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 string nullable

    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
    line1 string nullable
    line2 string nullable
    city string nullable
    state string nullable
    postal_code string nullable
    country string nullable
    billing_address object nullable
    line1 string nullable
    line2 string nullable
    city string nullable
    state string nullable
    postal_code string nullable
    country string nullable
    currency string 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​

    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
    country string required

    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]

    type string required

    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]

    value string required
    auto_collection boolean nullable

    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.

    email_delivery boolean nullable
    tax_configuration object nullable
    oneOf
    tax_exempt boolean required
    tax_provider string required

    Possible values: [avalara]

    tax_exemption_code string nullable
    reporting_configuration object nullable
    exempt boolean required
    accounting_sync_configuration object nullable
    excluded boolean nullable
    accounting_providers object[] nullable
  • Array [
    • provider_type string required
    external_provider_id string required
  • ]
    • additional_emails string[] nullable

    Additional email addresses for this customer. If populated, these email addresses will be CC'd for customer communications.

Responses

Created

Response Headers
    Schema
      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.

      property name* string
      id string required
      external_customer_id string nullable 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 nullable 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 string nullable required

      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.

      created_at date-time required
      shipping_address object nullable
      line1 string nullable required
      line2 string nullable required
      city string nullable required
      state string nullable required
      postal_code string nullable required
      country string nullable required
      billing_address object nullable
      line1 string nullable required
      line2 string nullable required
      city string nullable required
      state string nullable required
      postal_code string nullable required
      country string nullable required
      balance string required

      The customer's current balance in their currency.

      currency string nullable required
      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​

      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
      country string required

      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]

      type string required

      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]

      value string required
      auto_collection boolean required
      exempt_from_automated_tax boolean nullable required
      email_delivery boolean required
      additional_emails string[] required
      portal_url string nullable required
      accounting_sync_configuration object nullable
      excluded boolean required
      accounting_providers object[] required
    • Array [
      • provider_type string required

      Possible values: [quickbooks, netsuite]

      external_provider_id string nullable required
    • ]
      • reporting_configuration object nullable
      exempt boolean required
    Loading...