# Advanced features > For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt). The Chargebee API offers additional features such as custom HTTP request headers, custom fields, metadata. Moreover, the ability to set up multiple business entities, payment sources, and gateway accounts is also available. The sections below describe how to use these features. ## Specifying business entity If your site has multiple business entities, you can pass the `chargebee-business-entity-id: ` custom HTTP header to specify the business entity for which Chargebee should perform the operation. Here `` is the unique identifier of a business entity. The following sample shows how to [create a customer](/docs/api/customers/create-a-customer) within a business entity: #### Alternative to passing the header As an alternative to passing the request header, for some create operations, you can specify the `business_entity_id` using a query string parameter. See the [create customer](/docs/api/customers/create-a-customer#business_entity_id) endpoint for example. **Note** If the header and query string parameter are passed together in an API call, their values must be the same or an error is returned. ## Providing user details Passing user details like IP address, email address, and device information from your website to Chargebee is always useful. IP address information is routed to the payment gateway, where it is validated against active fraud detection filters, and used for EU tax validation, referral integration, and event reports. Email addresses and device information, even more ubiquitous, are used for identification. Chargebee supports the following custom HTTP request headers for providing such user details: - `chargebee-request-origin-ip`: Used to provide the IP address, of your customer/user, from where the request originated. For example, `202.170.207.70`. - `chargebee-request-origin-user`: Used to provide the email address of your customer/user. Use this when the email address has only ASCII characters. For example, `amara@acme.com`. - `chargebee-request-origin-user-encoded`: Used to provide the [Base64-encoded](https://datatracker.ietf.org/doc/html/rfc4648#section-4) email address of your customer/user. Use this if the email address has [UTF-8](https://en.wikipedia.org/wiki/UTF-8) characters (such as `user.квіточка@example.com`). When this header is provided, the header `chargebee-request-origin-user` is ignored. - `chargebee-request-origin-device`: Used to provide a string indicating the device from which the request was made. For example, `Android`, `Ubuntu`, or `iOS`. ### Using Origin IP and Device Data with Chargebee APIs When making API calls to Chargebee, including the `chargebee-request-origin-ip` and `chargebee-request-origin-device` details can provide valuable context about the user initiating the request. This information can enhance fraud detection and may be required by certain payment gateways. This document outlines the advantages of providing `chargebee-request-origin-ip` and `chargebee-request-origin-device` data and explains what happens if these details are omitted. **Information about Origin IP and Device Data** When you make a Chargebee API call, sending the `chargebee-request-origin-ip` and `chargebee-request-origin-device` details add more context about the user making the request. This additional information can be crucial for payment gateways to assess transaction legitimacy. However, if you're using Chargebee's [frontend capabilities](https://www.chargebee.com/checkout-portal-docs/#overview) or [hosted pages](/docs/api/hosted_pages), this information is automatically managed, and you don't need to provide it separately. **Advantages of providing this information** - **Compliance with gateway requirements**: Some payment gateways require `chargebee-request-origin-ip` and `chargebee-request-origin-device` details to process transactions. - **Enhanced fraud detection**: Certain gateways use this data to identify potential fraud based on their specific fraud detection rules. **What happens if these details are missing?** If you don't provide the `chargebee-request-origin-ip` and `chargebee-request-origin-device` details when making a Chargebee API call such as when using the [create\_subscription\_for\_items](/docs/api/subscriptions/create-subscription-for-items) API, you can still proceed with the transaction. However, for API calls involving payments from end customers, it's recommended to include this information to: - **Improve fraud prevention**: Enhances the chances of successful fraud detection by providing more context. - **Meet gateway requirements**: Some gateways might have mandatory requirements for this data, and omitting it could lead to processing issues. **Note**: For Stripe, SEPA, iDEAL, ACH, and Bancontact: - `chargebee-request-origin-ip` and `chargebee-request-origin-device` are mandatory. Failing to provide these parameters will cause the flow to fail. - The bank owner's name and email are mandatory only if the payment method is stored for recurring payments. For one-time payments, the bank owner's name and email are optional. - Bank owner's name and email are mandatory for ACH if the payment method is stored for recurring or one-time payments. ### Examples[](#examples) Providing user details with the email address containing only ASCII characters: Providing user details with the email address containing UTF-8 characters (here `user.квіточка@example.com`): ## Disabling webhooks and emails Sometimes you would want to disable emails or webhooks for the events that are generated for a particular api call. Typically you would need this when you are migrating customers from your system to Chargebee via api. One option would be to disable all the emails(/webhooks) for all events during the import process. But then you would still want to send emails for new customers who are signing up. Chargebee supports custom http headers on each api request that allow you to control the actions that are triggered on the events generated by that particular api call. - To skip all actions to be done on the events pass the header **chargebee-event-actions** with value **all-disabled** - To skip only emails pass the header **chargebee-event-email** with value **all-disabled** - Similarly to skip only webhooks pass **chargebee-event-webhook** with value **all-disabled** **Note:** Reminder mails (such as card expiry) and other scheduled events **cannot** be disabled using this option ## Custom Fields Use [custom fields](https://www.chargebee.com/docs/billing/1.0/site-configuration/custom_fields) to track additional information on Chargebee resources. You can create custom fields on **customers**, **subscriptions**, **invoices**, **credit notes**, **plans**, and **addons**. After you create a custom field, you can add it to hosted checkout pages and invoices, and access it through the web interface and API. **Note:** You can [create custom fields](https://www.chargebee.com/docs/billing/1.0/site-configuration/custom_fields#creating-custom-fields) only through the web interface, not through the API. ### Filtering by custom field values You can filter the response of [List operations](/docs/api/v2/pcv-1/list-ops) by custom field values. This feature is turned off by default. To turn it on, contact [Chargebee Support](https://www.chargebee.com/docs/billing/1.0/kb/getting-started/how-to-contact-chargebees-support-team?utm_source=docs_api&utm_medium=content&utm_campaign=support). After it's turned on, the custom field filter parameters appear on the List API documentation pages when you're logged in. Custom field filters support the following operators: `is`, `is_not`, `starts_with`, `in`, `not_in`, and `is_present`. Use the exact, case-sensitive API name of the custom field in filter parameters. If the API name does not match exactly, the filter is ignored and the API returns unfiltered results. For example, if the API name is `cf_MemberID`, passing `cf_memberID` does not apply the filter. You can find the API name in **Settings > Configure Chargebee > Custom Fields**, or via the [Retrieve custom field metadata](/docs/api/v2/pcv-1/custom_field_configs/retrieve-the-meta-data) API. **Note:** - You can use only text-based (string) custom fields as filters. Numeric custom fields aren't supported. - You can use up to five custom field filters per entity. - Custom field API names are case-sensitive. Use the exact API name as configured on your site. #### Example[](#example) This example uses the [List Customers API](/docs/api/v2/pcv-1/customers/list-customers) to list customers by the `cf_team` custom field and the `email` standard field. For example, to filter customers by a custom field whose API name is `cf_MemberID`: Pass `cf_MemberID`, not `cf_memberID`. The filter is ignored if the casing does not match the API name configured on your site. ## Metadata Some resources in Chargebee support an attribute called `metadata` or `meta_data` that can be used to store additional information for the resource. The data can be stored in JSON format. The following resources support this: - [Subscriptions](/docs/api/subscriptions) - [Customers](/docs/api/customers) - [Items](/docs/api/items) - [Item prices](/docs/api/item_prices) - [Coupons](/docs/api/coupons) Metadata can be passed in both the "create" as well as "update" operations against the resource. #### Limitations of metadata - Metadata has a character limit of 65,535. - Metadata information is not surfaced on any customer-facing artifacts such as hosted pages or invoices. - When using the "list" APIs, you cannot filter resources based on information stored within metadata. - Metadata is not returned by the [Export APIs](/docs/api/exports). **Tip** You can use [custom fields](/docs/api/v2/pcv-1/advanced-features#custom-fields) instead of metadata to overcome the above limitations. ## Multiple gateway accounts Chargebee supports configuring multiple gateway accounts for a gateway type. For example, you can configure multiple Authorize.net accounts to process different currencies. The default Gateway account to use for each currency can be configured using [Smart Routing](https://www.chargebee.com/docs/gateway_settings.html#smart-routing). However, you can override the selected gateway for each transaction in Chargebee. To do this pass the `gateway_account_id` parameter when calling the following APIs: **Caution** Passing `gateway`, `card[gateway]`, `payment_method[gateway]` parameters would result in an error in this case since those parameters only resolve the gateway and not the specific account for that gateway. **Customer-related requests:** - [Create a customer](/docs/api/customers/create-a-customer) - [Update payment method for a customer](/docs/api/customers/update-payment-method-for-a-customer) **Subscription-related requests:** - [Create a subscription](/docs/api/subscriptions/create-subscription-for-items) - [Update a subscription](/docs/api/subscriptions/update-subscription-for-items) - [Import a subscription](/docs/api/subscriptions/import-subscription-for-items) **Card-related requests:** - [Update card for a customer](/docs/api/cards/update-card-for-a-customer) - [Switch gateway](/docs/api/cards/switch-gateway) **Hosted Page-related requests:** - [Checkout new subscription](/docs/api/hosted_pages/create-checkout-for-a-new-subscription) - [Checkout existing subscription](/docs/api/hosted_pages/create-checkout-to-update-a-subscription) - [Manage payment sources](/docs/api/hosted_pages/manage-payment-sources) ## Multiple payment sources Chargebee supports multiple payment methods/sources for a customer. So a customer can have a Card and a Paypal Account linked to them, or they can have multiple cards. Moreover, you can mark one of them as Primary and one as Backup payment source. The purpose of a Backup payment source is that if a charge made via the Primary payment source fails, then the backup payment source will be automatically used for processing the transaction. **Updating a payment source:** 1. To update the Primary payment source for a customer: - Use any of the create payment source APIs with '**replace\_primary\_payment\_source**' set to '**true**'. This will update the payment source and make it the Primary payment source for the customer. 2. To update alternate payment sources: - Delete the payment source that you want to update - Create a payment source for the customer using any of the create payment source APIs An optional parameter, **payment\_source\_id**, is available in the following APIs: **Subscription APIs:** If you want to attach a particular payment source to a specific subscription, then pass the parameter in the following APIs: - [Create subscription for items](/docs/api/subscriptions/create-subscription-for-items) - [Import subscription for items](/docs/api/subscriptions/import-subscription-for-items) - [Override Billing Profile](/docs/api/subscriptions/override-billing-profile) **Invoice APIs:** Pass this parameter in the following APIs to collect the payment using a specific payment source: - [Create an invoice](/docs/api/invoices/create-invoice-for-items-and-one-time-charges) - [Create invoice for charge](/docs/api/invoices/create-invoice-for-items-and-one-time-charges) - [Create invoice for addon](/docs/api/invoices/create-invoice-for-items-and-one-time-charges) - [Collect payment for an invoice](/docs/api/invoices/collect-payment-for-an-invoice) **Notes:** - The first payment source created for a customer will be automatically marked as the Primary payment source for the customer. - The Payment Source provided in the hosted pages by a customer always **replaces** the Primary payment source for the customer. If a payment source does not exist, it creates a new payment source and marks it as Primary. ## Admin console details page Some of the resources have a corresponding details page in the Chargebee's **admin console**. In some cases you might want to construct the admin console url for easy access from your app (or from exported xls sheets). As the admin console urls are based on **internal ids** you need to construct the url in the below given format. Here is an example of a constructed url for a subscription with id **123xyz**: **Note:** - Accessing the constructed url in a **browser** will redirect it to the **details** page. - The login page will be shown if the user has not yet logged-in into Chargebee's admin console. - Not all resources will have the corresponding details page. To know if it is supported, please look at the cURL documentation under the **retrieve** operation for that resource. - Do not store the redirected internal id based url as it may change.