FAQs Regarding Org API & Webhook Changes for Billing

What’s the new experience of Organisation Developer App?

How to use the new org level API key to access new Billing APIs?

How does this impact my previous Billing integrations?

How to migrate to the new org API key to access new Billing features?

What happens to the existing API keys with account-level Billing permissions?

What happens to the existing Webhooks subscribed to account-level Billing events?

What’s the new experience of Organisation Developer App? 

The entry to the Developer app will now be located in the Organisation menu.

You can create new scoped API keys by specifying Billing permissions at the organisation level. 
 

You can subscribe to the Billing webhook events by selecting the Billing event types in the organisation-level events. 

How to use the new API key to access new Billing APIs?

Create a new API key with Billing permissions selected on the organisation-level, then authenticate to get the API access token using obtain access token API like usual.

How does this impact my previous Billing integrations?

API Keys

For newly created API keys:

• Billing permissions will now be managed at the organisation level.
• Billing APIs with versions earlier than 2025-06-16 will no longer be supported with new organisation-level billing permissions.

For existing account-level API keys with Billing permissions:

• Your current Billing integrations will continue to function without interruption.
• Billing permissions will remain at the account level, but you will no longer be able to edit Billing permissions or duplicate the key.
• Payment Acceptance permissions will still retain access to Billing resources.

Webhooks

For newly created webhooks:

• Billing events will be managed at the organisation level.
• Billing events are only available for API versions 2025-06-16 and later.

For existing account-level webhooks subscribed to Billing events:

• You will continue to receive Billing events, but only related to the subscribed account, identified by the linked payment account.
• Existing account-level Billing events cannot be edited, and the webhook cannot be duplicated.
• If you need to receive Billing events for multiple accounts, you can temporarily create additional webhooks for each account.

How to migrate to the new org API key to access new Billing features?

The existing keys with account-level Billing permissions will not have access to upcoming new Billing features, such as Usage, Credit Notes, and Discounts, so it’s highly recommended to migrate to the org API key and webhook as early as possible to continue to use Billing APIs.

API key migration

1. Create a new organisation-level API key
   • Go to the Developer Tool and generate a new key at the organisation level.
   • Select the Billing permissions required for your integration.
   • (Optional) You can also include account-level permissions (e.g. Payment Acceptance) if your integration needs access to those APIs.
2. Update your integration to use the correct API key for each service.
   • For Billing APIs, use the newly created organisation-level API key for authentication. 
   • For other APIs (such as Payment Acceptance), you can either:
     1. Continue using your existing account-level API key, or
     2. Use the new created API key in step 1 with the header x-login-as: <account_id> to authenticate as a specific account.

Webhook migration

1. Before the migration, for the receiving URL endpoint, make sure you de-duplicate the events by the event.id.
2. Create new webhook subscriptions, with organisation-level Billing events selected.
3. Deprecate the previous webhook subscriptions by deleting the webhook.

What happens to the existing API keys with account-level Billing permissions?

They will remain functional with the access they previously had, however

• You will no longer be able to edit the account-level Billing permissions on the API keys. 
• You can no longer duplicate the API keys with account-level Billing permissions.
• You can still edit other permissions on the API key.

What happens to the existing Webhooks subscribed to account-level Billing events?

You will continue to receive Billing events, however 

• Events will only be related to the subscribed account, identified by the linked payment account.
• You can no longer edit the existing account-level Billing events on the webhook subscription.
• You can no longer duplicate the webhook with account-level Billing events.