Skip to main content

Update customer by external ID​

This endpoint is used to update customer details given an external_customer_id (see Customer ID Aliases). Note that the resource and semantics of this endpoint exactly mirror Update Customer.

Path Parameters
    external_customer_id string required
Request Body
    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 nullable

    The full name of the customer

    email string nullable

    Possible values: Value must match regular expression (?i)\b[A-Z0-9._%+-]+@[A-Z0-9.-]{1,63}\.[A-Z]{2,63}\b

    A valid customer email, to be used for invoicing and notifications.

    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.
    • if the provider is an invoicing provider (stripe_invoice, quickbooks, bill.com, netsuite), any product mappings must first be configured with the Orb team.
    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
    Australiaau_abnAustralian Business Number (AU ABN)
    Australiaau_arnAustralian Taxation Office Reference Number
    Austriaeu_vatEuropean VAT number
    Belgiumeu_vatEuropean VAT number
    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
    Croatiaeu_vatEuropean VAT number
    Cypruseu_vatEuropean VAT number
    Czech Republiceu_vatEuropean VAT number
    Denmarkeu_vatEuropean VAT number
    Egypteg_tinEgyptian Tax Identification 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ō)
    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
    Norwayno_vatNorwegian VAT number
    Philippinesph_tin Philippines Tax Identification Number
    Polandeu_vatEuropean VAT number
    Portugaleu_vatEuropean VAT number
    Romaniaeu_vatEuropean VAT number
    Russiaru_innRussian INN
    Russiaru_kppRussian KPP
    Saudi Arabiasg_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
    country string required

    Possible values: [AD, AE, AT, AU, BE, BG, BR, CA, CH, CL, CY, CZ, DE, DK, EE, EG, ES, EU, FI, FR, GB, GE, GR, HK, HR, HU, ID, IE, IL, IN, IS, IT, JP, KE, KR, LI, LT, LU, LV, MT, MX, MY, NL, NO, NZ, PH, PL, PT, RO, RU, SA, SE, SG, SI, SK, TH, TR, TW, UA, US, ZA]

    type string required

    Possible values: [ad_nrt, ae_trn, eu_vat, au_abn, au_arn, bg_uic, br_cnpj, br_cpf, ca_bn, ca_gst_hst, ca_pst_bc, ca_pst_mb, ca_pst_sk, ca_qst, ch_vat, cl_tin, 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, li_uid, mx_rfc, my_frp, my_itn, my_sst, no_vat, nz_gst, ph_tin, ru_inn, ru_kpp, sa_vat, sg_gst, sg_uen, si_tin, th_vat, tr_tin, tw_vat, ua_vat, us_ein, 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.

    additional_emails string[] nullable

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

    email_delivery boolean 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
  • ]
    • external_customer_id string nullable

    The external customer ID. This can only be set if empty and the customer has no past or current subscriptions.

Responses

OK

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
      Australiaau_abnAustralian Business Number (AU ABN)
      Australiaau_arnAustralian Taxation Office Reference Number
      Austriaeu_vatEuropean VAT number
      Belgiumeu_vatEuropean VAT number
      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
      Croatiaeu_vatEuropean VAT number
      Cypruseu_vatEuropean VAT number
      Czech Republiceu_vatEuropean VAT number
      Denmarkeu_vatEuropean VAT number
      Egypteg_tinEgyptian Tax Identification 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ō)
      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
      Norwayno_vatNorwegian VAT number
      Philippinesph_tin Philippines Tax Identification Number
      Polandeu_vatEuropean VAT number
      Portugaleu_vatEuropean VAT number
      Romaniaeu_vatEuropean VAT number
      Russiaru_innRussian INN
      Russiaru_kppRussian KPP
      Saudi Arabiasg_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
      country string required

      Possible values: [AD, AE, AT, AU, BE, BG, BR, CA, CH, CL, CY, CZ, DE, DK, EE, EG, ES, EU, FI, FR, GB, GE, GR, HK, HR, HU, ID, IE, IL, IN, IS, IT, JP, KE, KR, LI, LT, LU, LV, MT, MX, MY, NL, NO, NZ, PH, PL, PT, RO, RU, SA, SE, SG, SI, SK, TH, TR, TW, UA, US, ZA]

      type string required

      Possible values: [ad_nrt, ae_trn, eu_vat, au_abn, au_arn, bg_uic, br_cnpj, br_cpf, ca_bn, ca_gst_hst, ca_pst_bc, ca_pst_mb, ca_pst_sk, ca_qst, ch_vat, cl_tin, 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, li_uid, mx_rfc, my_frp, my_itn, my_sst, no_vat, nz_gst, ph_tin, ru_inn, ru_kpp, sa_vat, sg_gst, sg_uen, si_tin, th_vat, tr_tin, tw_vat, ua_vat, us_ein, za_vat]

      value string required
      auto_collection boolean 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...