Create an e-invoicing business region

POST

/v1/einvoice/business-regions

POST

/v1/einvoice/business-regions

from zuora import ZuoraClient, InvoiceFiltersRequestType, InvoiceFiltersCondition
client = ZuoraClient(
    token="YOUR_TOKEN_HERE",
)
client.e_invoicing.post_create_e_invoicing_business_region(
    business_name="legal business name",
    business_number="20002039",
    business_number_schema_id="88",
    city="Tokyo",
    country="JP",
    endpoint_id="8992",
    endpoint_scheme_id="88",
    postal_code="368779",
    invoice_filters=[
        InvoiceFiltersRequestType(
            condition=InvoiceFiltersCondition(
                field="SoldToContact.Country",
                operator="eq",
                value="India",
            ),
        )
    ],
    service_provider_id="4028948972a2bf990172bc9b27724ddc",
    tax_register_number="TAX393999",
    trade_name="Zuora",
    file_format=[
        "string"
    ],
)

{
  "id": "4028b2aa8890c524018890c7e9ef3826",
  "country": "JP",
  "businessName": "legal business name",
  "businessNumber": "20002039",
  "businessNumberSchemaId": "88",
  "tradeName": "Zuora",
  "taxRegisterNumber": "TAX393999",
  "state": "",
  "city": "Tokyo",
  "postalCode": "368779",
  "addressLine1": "",
  "addressLine2": "",
  "contactName": "",
  "phoneNumber": "",
  "email": "",
  "serviceProviderId": "4028948972a2bf990172bc9b27724ddc",
  "businessRegionNumber": "EIBR-00000002",
  "digitalSignatureEnable": false,
  "digitalSignatureBoxEnable": false,
  "digitalSignatureBoxPosX": 0,
  "digitalSignatureBoxPosY": 0,
  "responseMapping": {},
  "invoiceFilters": [
    {
      "condition": {
        "field": "SoldToContact.Country",
        "operator": "eq",
        "value": "India"
      },
      "objectType": "Invoice"
    }
  ],
  "fileFormat": []
}

Creates an e-invoicing business region.

You must create business regions to store the business detail information as a seller. If you have multiple GSTINs for different states, you can create multiple business region objects for India.

The business region objects can be looked up according to the country and state, and its related fields can be mapped accordingly within the e-invoice file template.

Note: This operation is available only if you have the E-Invoicing feature in Early Adopter phase enabled.

Authentication

AuthorizationBearer

Use Bearer {{token}} in the Authorization header for authentication.

Headers

Content-EncodingstringOptional

Include the Content-Encoding: gzip header to compress a request. With this header specified, you should upload a gzipped file for the request payload instead of sending the JSON payload.

Zuora-Org-IdsstringOptional

Comma separated IDs. If you have Zuora Multi-Org enabled, you can use this header to specify which orgs to perform the operation in. If you do not have Zuora Multi-Org enabled, you should not set this header.

The IDs must be a sub-set of the user’s accessible orgs. If you specify an org that the user does not have access to, the operation fails. This header is important in Multi-Org (MO) setups because it defines the organization context under which the API should operate—mainly used for read access or data visibility filtering. If the header is not set, the operation is performed in scope of the user’s accessible orgs.

Request

This endpoint expects an object.

businessNamestringRequired<=255 characters

The full official name that the Seller is registered with the relevant legal authority.

countrystringRequired

The short name of a country or region where you must comply with e-invoicing requirements. For example, IN for India. For the full list of country names and codes, see View countries or regions.

addressLine1stringOptional

The first line of the Seller's address, which is often a street address or business name.

addressLine2stringOptional

The second line of the Seller's address, which is often the name of a building.

businessNumberstringOptional

The specify the unique identifier number of the legal entity or person that you do business with.

For example, you must use a GSTIN for India and Tax Identification Number (TIN) for Saudi Arabia.

businessNumberSchemaIdstringOptional

The identification scheme identifier that an official registrar issues to identify the Seller as a legal entity or person.

citystringOptional

The the name of the city where the business is located.

contactNamestringOptional<=255 characters

The name of the Seller contact to receive e-invoicing data.

digitalSignatureEnablebooleanOptionalDefaults to false

Whether the e-invoicing service provider signs PDF files for billing documents.

digitalSignatureBoxEnablebooleanOptionalDefaults to false

Whether the digital signature box is displayed on PDF files for billing documents.

digitalSignatureBoxPosXdoubleOptional>=0

The X-coordinate to determine where the digital signature box is displayed on PDF files for billing documents.

digitalSignatureBoxPosYdoubleOptional>=0

The Y-coordinate to determine where the digital signature box is displayed on PDF files for billing documents.

emailstringOptional

The email address of the Seller contact to receive e-invoicing data.

endpointIdstringOptional

The Seller’s electronic address, to which the application-level response to the e-invoice file might be delivered.

endpointSchemeIdstringOptional

The identification scheme identifier of the Seller's electronic address.

phoneNumberstringOptional

The business phone number of the Seller contact to receive e-invoicing data.

postalCodestringOptional

The short code that can identify the business address.

responseMappingmap from strings to stringsOptional

Container for e-invoicing response field mappings that map values from the e-invoicing service provider’s response data to fields on the EInvoiceData object in Zuora. Each response field mapping consists of a field name and a field path.

Note: This field is applicable only to the Sovos or Avalara service provider.

For more information, see Configure e-invoicing response field mappings.

processTypeenumOptional

The process type of the e-invoicing business region.

If the service provider is Sovos, specify the process type as Clearance or ClearanceWithCancellation.
If the service provider is Avalara, specify the process type as Clearance or PEPPOLNetwork.
If the service provider is PEPPOL, leave this field empty.

Allowed values:

invoiceEnabledbooleanOptionalDefaults to false

This field controls whether the invoice should be supported by the process type or not. For some countries, this field is required to be set to true. For more information, see Manage country-specific configurations.

creditMemoEnabledbooleanOptionalDefaults to false

This field controls whether the credit memo should be supported by the process type or not. For some countries, this field is required to be set to true. For more information, see Manage country-specific configurations.

debitMemoEnabledbooleanOptionalDefaults to false

This field controls whether the debit memo should be supported by the process type or not. For some countries, this field is required to be set to true. For more information, see Manage country-specific configurations.

invoiceFilterslist of objectsOptional

The documents belonging to the e-invoicing business region.

creditMemoFilterslist of objectsOptional

The documents belonging to the e-invoicing business region.

debitMemoFilterslist of objectsOptional

The documents belonging to the e-invoicing business region.

serviceProviderIdstringOptional

The unique ID of the e-invoicing service provider that is associated to the business region.

statestringOptional

The name of the state or province where the business is located.

taxRegisterNumberstringOptional

The Seller’s VAT identifier (also known as Seller VAT identification number) or the local identification (defined by the Seller’s address) of the Seller for tax purposes, or a reference that enables the Seller to state the registered tax status.

tradeNamestringOptional<=100 characters

The name that the Seller is known as, other than the legal business name.

fileFormatlist of stringsOptional

You can define the file format for each business category as shown in the following example:

fileFormat” : {

“B2B” : [ “XML” ],

“B2C” : [ ],

“B2G” : [ “XML” ]

}

Note: This field is optional; however, if you use Avalara integration, it becomes a mandatory field.

Response headers

Content-EncodingstringOptional

This header is returned if you specify the Accept-Encoding: gzip request header and the response contains over 1000 bytes of data.

Note that only the following MIME types support gzipped responses:

application/json
application/xml
text/html
text/csv
text/plain

RateLimit-LimitstringOptional

The request limit quota for the time window closest to exhaustion. See rate limits for more information.

RateLimit-Remainingdouble

The number of requests remaining in the time window closest to quota exhaustion. See rate limits for more information.

RateLimit-Resetdouble

The number of seconds until the quota resets for the time window closest to quota exhaustion. See rate limits for more information.

Zuora-Request-IdstringOptional

The Zuora internal identifier of the API call. You cannot control the value of this header.

Zuora-Track-IdstringOptional

A custom identifier for tracing the API call. If you specified a tracing identifier in the request headers, Zuora returns the same tracing identifier. Otherwise, Zuora does not set this header.

Concurrency-Limit-TypestringOptional

The type of the concurrency limit, which can be Default, High-volume transactions, or Object Query.

For more information, see Concurrent request limits.

Concurrency-Limit-Limitinteger

The total number of the permitted concurrent requests.

For more information, see Concurrent request limits.

Concurrency-Limit-Remaininginteger

The remaining number of the permitted concurrent requests.

For more information, see Concurrent request limits.

Response

idstringOptional

The unique ID of the e-invoicing business region.

countrystringOptional

The short name of a country or region where you must comply with e-invoicing requirements. For example, IN for India. For the full list of country names and codes, see View countries or regions.

businessNamestringOptional<=255 characters

The full official name that the Seller is registered with the relevant legal authority.

businessNumberstringOptional

The specify the unique identifier number of the legal entity or person that you do business with.

For example, you must use a GSTIN for India and Tax Identification Number (TIN) for Saudi Arabia.

businessNumberSchemaIdstringOptional

The identification scheme identifier that an official registrar issues to identify the Seller as a legal entity or person.

tradeNamestring or nullOptional<=100 characters

The name that the Seller is known as, other than the legal business name.

endpointIdstringOptional

The Seller’s electronic address, to which the application-level response to the e-invoice file might be delivered.

endpointSchemeIdstringOptional

The identification scheme identifier of the Seller’s electronic address.

taxRegisterNumberstring or nullOptional

statestring or nullOptional

The name of the state or province where the business is located.

citystringOptional

The the name of the city where the business is located.

postalCodestringOptional

The short code that can identify the business address.

addressLine1string or nullOptional

The first line of the Seller’s address, which is often a street address or business name.

addressLine2string or nullOptional

The second line of the Seller’s address, which is often the name of a building.

contactNamestring or nullOptional<=255 characters

The name of the Seller contact to receive e-invoicing data.

phoneNumberstring or nullOptional

The business phone number of the Seller contact to receive e-invoicing data.

emailstring or nullOptional

The email address of the Seller contact to receive e-invoicing data.

serviceProviderIdstringOptional

The unique ID of the e-invoicing service provider that is associated to the business region.

businessRegionNumberstringOptional

The unique number of the e-invoicing business region.

digitalSignatureEnablebooleanOptionalDefaults to false

Whether the e-invoicing service provider signs PDF files for billing documents.

digitalSignatureBoxEnablebooleanOptionalDefaults to false

Whether the digital signature box is displayed on PDF files for billing documents.

digitalSignatureBoxPosXdoubleOptional>=0

The X-coordinate to determine where the digital signature box is displayed on PDF files for billing documents.

digitalSignatureBoxPosYdoubleOptional>=0

The Y-coordinate to determine where the digital signature box is displayed on PDF files for billing documents.

responseMappingmap from strings to stringsOptional

Note: This field is applicable only to the Sovos or Avalara service provider.

For more information, see Configure e-invoicing response field mappings.

processTypeenumOptional

The process type of the e-invoicing business region.

If the service provider is Sovos, the process type is Clearance or ClearanceWithCancellation.
If the service provider is Avalara, the process type is Clearance or PEPPOLNetwork.
If the service provider is PEPPOL, the process type is Unknown.

Allowed values:

invoiceEnabledbooleanOptionalDefaults to false

It will control whether the invoice should be supported by the process type or not. This field is available when the service provider is Sovos or Avalara.

creditMemoEnabledbooleanOptionalDefaults to false

It will control whether the credit memo should be supported by the process type or not. This field is available when the service provider is Sovos or Avalara.

debitMemoEnabledbooleanOptionalDefaults to false

It will control whether the debit memo should be supported by the process type or not. This field is available when the service provider is Sovos or Avalara.

invoiceFilterslist of objectsOptional

The documents belonging to the e-invoicing business region.

creditMemoFilterslist of objectsOptional

The documents belonging to the e-invoicing business region.

debitMemoFilterslist of objectsOptional

The documents belonging to the e-invoicing business region.

fileFormatlist of stringsOptional

The file format for each business category. An example response is ”[ “application/xml”, “application/vnd.oasis.ubl+xml” ]”

successbooleanOptional

Indicats if the request succeeds.

Errors

4XX

Client Request Error

500

Internal Server Error